@octostaff/sdk

Install the Bubble client and shared OctoStaff contracts:

pnpm add @octostaff/sdk

Connect to Bubble

import { createBubbleClient } from '@octostaff/sdk/client';

const bubble = createBubbleClient({
  baseUrl: 'https://bubble.example.com',
  token: process.env.BUBBLE_TOKEN,
});

await bubble.connection.connect();
const identity = await bubble.identity.get();

// Call this when the application shuts down.
bubble.connection.close();

The runtime must provide fetch and WebSocket. Node consumers using the ws package can pass adaptNodeWebSocketFactory(WebSocket) as webSocketFactory.

Assemble thread events

import { createAssembler } from '@octostaff/sdk/assembler';

const snapshot = await createAssembler().assemble(events);
console.log(snapshot.messages);

Import paths

• @octostaff/sdk — Bubble protocol contracts, codecs, IDs, roles, and authorization helpers.
• @octostaff/sdk/client — HTTP/WebSocket client and connection lifecycle.
• @octostaff/sdk/assembler — Bubble event-to-message assembly.
• @octostaff/sdk/extensions, /extensions/artifacts, /extensions/schedules — extension client contracts.
• @octostaff/sdk/types — assembled message data-part contracts.
• @octostaff/sdk/logger and /logger/browser — Node and browser logging.
• @octostaff/sdk/config, /bot, and /amphibian — shared bot runtime utilities.

Documentation

• TypeScript SDK — what the package ships and how each subpath export maps to a source module.
• Thread assembler — turning a sequenced event log into BubbleMessage snapshots, and the partHandlers extension surface.
• Artifact protocol — the artifact control plane, authorization scopes, and staged byte transfers.

Full documentation lives at https://www.octostaff.com/docs.