The client

@fxbot/sdk/client is a typed client for an fxbot server's HTTP API, for a page or a script.

import { applyLine, createClient, type Turn } from "@fxbot/sdk/client";

const client = createClient({ baseUrl: "http://127.0.0.1:8787" });
let turns: Turn[] = [];
for await (const line of client.stream(botId, { signal })) turns = applyLine(turns, line);

It imports nothing from @fxbot/sdk's main entry, so a browser bundle can take it. See Build a page on the client.

createClient

createClient(options?) returns a Client.

• Each call asks <baseUrl>/api/... with fetch, sends JSON, and resolves to the JSON answer.
• A call that fails throws an Error with the server's message. When the server can't be reached, or answers with something that isn't JSON, such as a proxy's page, the message is unreachable: "Cannot reach the server." The Error carries no status.
• The client holds no keys or tokens. A key goes to the server once, in providers.add or providers.update, and comes back only as hasKey. Header values and OAuth clients go up once, in addons.setSecrets.
• The server refuses a write with 403 when the request's Origin header names another host than its Host. A browser sends Origin, so a page on another origin gets 403 for every write. Node's fetch sends no Origin, so a script's writes pass. The server sends no CORS headers.

Calls

Each call is one route of the HTTP API. They mirror the fxbot object, which has the rules for each.

Health and updates

Bots

profiles.memories.list takes the search as a string. An empty one lists the newest.

Chat

send resolves once the server has stored the message. The reply arrives on the stream.

Settings

settings.update also takes local: cpu, gpu, or off. It asks the machine to run its local embedder that way, in an install made by setup.sh.

Providers and sign-ins

A device code sign-in: show userCode and verificationUrl, then call signIns.get until the status is done or failed.

Library

A file itself is read through its item's url, /api/library/<id>/file.

Add-ons and OAuth

After addons.signIn, open the attempt's url, then call oauth.get until the status is done or failed. The browser's Origin decides where the sign-in comes back to.

stream

stream(id: string, options?: { cursor?: number; signal?: AbortSignal; onConnection?: (connected: boolean) => void }): AsyncGenerator<StreamLine>

• It yields every line of the bot's chat from cursor on, then each new line, until signal aborts.
• It keeps the cursor of the last line it read. When the connection drops, the server answers with an error, or the stream ends, it waits 2 seconds and asks again from that cursor. The server ends the stream at once for a bot with no chat yet, so the client asks again every 2 seconds until the chat starts.
• It hides a line whose epoch is lower than one it has already seen, as libfx's rule says.
• Each connection's x-fxbot-version header goes to onVersion.

applyLine

applyLine(turns, line) folds one stream line into a list of turns, one per message, and returns a new list. It doesn't change the list it was given.

A line for a message not in the list adds a turn for it.

Types

type Turn = {
  messageId: string;
  text: string; // the message
  files?: Upload[];
  reply: string; // the reply's text alone
  parts?: Part[]; // the reply step by step, in order
  done: boolean;
  note?: string; // an error, or why it stopped
  unsent?: boolean; // for a page: a message the server never took
};

type Part =
  | { type: "reasoning"; text: string }
  | { type: "text"; text: string }
  | { type: "tool"; id: string; name: string; input?: unknown; inputPreview?: string; output?: string; error?: boolean; done: boolean };

A turn from profiles.earlier has reply and no parts.

Stream lines

StreamLine is one line of a bot's NDJSON stream, as far as fxbot reads it. libfx writes more types and fields.

The types applyLine reads:

libfx writes other types too, such as turn_yield and idle. applyLine passes over them.

Exports

The types are Client, ClientOptions, StreamOptions, Turn, and Part, and the shared types that @fxbot/sdk exports too, such as Profile, Provider, Settings, and StreamLine.