---
title: "SDK Overview"
description: "How the Node.js SDK is split between local shards and the HTTP API."
canonical: "https://developers.fnlb.net/docs/sdk/overview"
markdown: "/docs/sdk/overview.md"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fnlb.net/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

---
title: "SDK overview"
sidebarTitle: "Overview"
description: "How the fnlb package splits local shard control from the HTTP API, and where each guide goes."
icon: "sdk"
---

The `fnlb` package is the self-hosted client. `start()` downloads the FNLB client, forks one process per shard, and logs those bots into Fortnite. Events, party meta, chat, and `bot.runCommand` talk to those processes over local IPC. `fnlb.api` is a separate HTTP client for the same account, including bots that are not running in this process.

Install, tokens, shards, and shutdown stay on the [Node.js SDK](/docs/self-hosting/sdk-node.md) page. Every class and method is also in the [SDK Reference](/sdk.md). The machine-readable spec is [/sdk.json](/sdk.json). Generated Markdown for one symbol is under [/sdk-reference](/sdk-reference/index.md), for example [Party](/sdk-reference/classes/Party.md).

## What you import

```ts
import FNLB, {
  Events,
  PartyPrivacy,
  Playlist,
  PresenceOnlineType,
  ApiError,
  SDK_BRIDGE_UNAVAILABLE
} from 'fnlb';
```

| Export | Use it for |
| :--- | :--- |
| `FNLB` | The client. `start()`, `stop()`, `on`, `bots`, `api`. Reference: [`FNLB`](/sdk?symbol=FNLB). |
| `Events` | Listener names. Reference: [`Events`](/sdk?symbol=Events). |
| `PartyPrivacy` | `party.setPrivacy`. Reference: [`PartyPrivacy`](/sdk?symbol=PartyPrivacy). |
| `Playlist` | Built-in playlist link ids for `party.setPlaylist`. Reference: [`Playlist`](/sdk?symbol=Playlist). |
| `PresenceOnlineType` | `bot.setStatus`. Reference: [`PresenceOnlineType`](/sdk?symbol=PresenceOnlineType). |
| `ApiError` | Non-2xx responses from `fnlb.api`. Reference: [`ApiError`](/sdk?symbol=ApiError). |
| `SDK_BRIDGE_UNAVAILABLE` | Thrown when a shard never opens the local bridge. |

`Bot`, `Party`, `PartyMember`, `PartyMeta`, `Message`, and `Collection` are also exported if you want the types. You normally receive them from `fnlb.on` and `fnlb.bots`.

## Two ways to talk to a bot

| | Local shard | HTTP API |
| :--- | :--- | :--- |
| When | The bot is running in this process | Any bot on the account, online or not |
| Entry | `fnlb.bots`, `bot.party`, `fnlb.on` | `fnlb.api` after `start()` |
| Party meta | `bot.party.meta` and `bot.party.me.meta` | Not available. The API member route is a cosmetic snapshot. |
| Commands | `bot.runCommand` | `fnlb.api.bots.commands.run` |
| Chat | `bot.send`, `bot.whisper`, `message.reply` | `fnlb.api.bots.chat.send` |
| Friends | `bot.friends()`, `addFriend`, `block` | `api.bots.friends.list` reads a connected bot. It does not add or block. |
| Cosmetics | `party.setOutfit` and the other member methods | A command through `commands.run`, or a [category config](/docs/sdk/category-config.md) outfit list |

<Info>
`start()` resolves when the shard processes have been spawned. Wait for [Events.Ready](/docs/sdk/events.md#ready) before you call a bot.
</Info>

## Guides

<CardGroup cols={2}>
  <Card icon="gateway" href="/docs/sdk/events" title="Events">
    Ready, chat, friends, invites, joins, and cosmetic changes.
  </Card>
  <Card icon="smartToy" href="/docs/sdk/parties" title="Bots and parties">
    Members, meta, privacy, playlists, and cosmetics.
  </Card>
  <Card icon="terminal" href="/docs/sdk/chat-and-commands" title="Chat and commands">
    Party chat, whispers, friend requests, and local commands.
  </Card>
  <Card icon="api" href="/docs/sdk/http-client" title="HTTP client">
    List bots, categories, presets, and run cloud commands.
  </Card>
  <Card icon="sliders" href="/docs/sdk/category-config" title="Category config">
    Keys for `overrideCategoryConfig` and selection overrides.
  </Card>
  <Card icon="server" href="/docs/self-hosting/sdk-node" title="Node.js SDK">
    Install, authenticate, shard, and stop the process.
  </Card>
  <Card icon="code" href="/sdk" title="SDK Reference">
    Generated classes, methods, and types.
  </Card>
</CardGroup>

## A complete loop

```ts
import FNLB, { Events, PartyPrivacy, Playlist } from 'fnlb';

const fnlb = new FNLB({ clusterName: 'dev' });

fnlb.on(Events.Ready, (bot) => {
  console.log(bot.displayName, 'is ready');
});

fnlb.on(Events.PartyMemberMessage, async (message) => {
  if (message.content === '!ping') await message.reply('pong');
});

await fnlb.start({
  token: 'FNLB_...',
  categories: ['your-category-id']
});

const bot = await fnlb.bots.fetch('bot-id');
await bot.party.setPrivacy(PartyPrivacy.PRIVATE);
await bot.party.setPlaylist(Playlist.SQUAD);
await bot.party.setOutfit('CID_028_Athena_Commando_F');
await bot.party.meta.set('Default:CustomMatchKey_s', 'my-key');

const accountBots = await fnlb.api.bots.list();
```

`fnlb.bots.cache` only contains bots this process has started. `fnlb.api.bots.list()` is every bot on the token.

## Shards

Each shard is a child process. `fnlb.shards` holds them after `start()`. `fnlb.fetchShardInfo()` returns version, protocol, gateway connection, and bot count for each one. `fnlb.broadcast(method, params)` sends one bridge call to every shard and returns a result per shard. A failed shard is `ok: false` and does not reject the whole call.

Prefer `fnlb.bots` for party, chat, and commands. Use the shard when you want [`Shard.fetchInfo`](/sdk?symbol=Shard#fetchinfo).

## When a call throws

| Error | Cause |
| :--- | :--- |
| `SDK_BRIDGE_UNAVAILABLE` | The shard never announced the bridge. The downloaded FNLB client is too old, or it exited before hello. |
| `Bot <id> is not running on this client.` | `fetch` was asked for a bot this process did not start. Use `fnlb.api.bots.get` for account bots. |
| `Only this bot can change its own member.` | `party.members.get(someoneElse).setOutfit` (or any other self-only member method). |
| Party leader errors from Fortnite | `setPrivacy`, `kick`, `setPlaylist`, and the other leader calls when this bot is not the leader. |
| `ApiError` | `fnlb.api` got a non-2xx response. `status`, `path`, and `body` are on the error. |

Local party calls need a current FNLB client. An older build rejects `fortnite.action` with an unknown-method error. `fnlb.api` still works on that build.

## Where to go next

| You want to | Read |
| :--- | :--- |
| Hear ready, chat, invites, and cosmetic changes | [Events](/docs/sdk/events.md) |
| Change privacy, playlist, meta, or cosmetics | [Bots and parties](/docs/sdk/parties.md) |
| Chat, friends, and `runCommand` | [Chat and commands](/docs/sdk/chat-and-commands.md) |
| Create bots, categories, or run a cloud command | [HTTP client](/docs/sdk/http-client.md) |
| Override dashboard settings for this run | [Category config](/docs/sdk/category-config.md) |
| Install, tokens, and shard counts | [Node.js SDK](/docs/self-hosting/sdk-node.md) |