castle-web-sdk 0.4.34 → 0.4.36

package/README.md

@@ -24,7 +24,10 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
 - [Pass](#pass)
 - [Snapshot](#snapshot)
 - [Portal](#portal)
+- [Decks](#decks)
+- [Clipboard](#clipboard)
 - [Haptics](#haptics)
+- [Agent](#agent)
 - [Lifecycle](#lifecycle)
 - [Multiplayer](#multiplayer)
 - [Setup](#setup)
@@ -249,11 +252,30 @@ guide.
 
 ### Limits
 
-The platform caps key length, value size, how many keys one call may
-touch, page size, and how much a deck may store in total, and it limits
-how fast a player may read and write. Going over any of them rejects
-with a `CastleError` whose `code` says which, so a deck can tell a
-player it is saving too fast apart from a deck that is out of space.
+The platform caps key length, value size, how many keys one read may
+name, and how much a deck may store in total, and it limits how fast a
+player may read and write. Going over one of these rejects with a
+`CastleError` whose `code` says which, so a deck can tell a player it is
+saving too fast apart from a deck that is out of space:
+
+| limit | value |
+|---|---|
+| key | 128 bytes |
+| value | 256 KB |
+| keys in one `get` | 32 |
+| whole deck | 50 MB, 500,000 keys |
+| one player's calls | 20 a second, 512 KB a second |
+| every player of a deck together | 500 calls a second, 8 MB a second |
+
+These do not reject. `set` and `remove` with more than 32 keys are split
+into several calls by the SDK (each still counts against the rate above).
+A `list` page holds at most 1,000 entries (a larger `limit` is lowered to
+it) and ends early once it reaches 1 MB; take the next page with its
+`cursor`.
+
+A value is JSON, so binary data such as a picture or a video clip costs
+about a third more once encoded, and a clip of more than a few seconds
+does not fit in one. Ship media with the deck instead.
 
 ## Storage
 
@@ -265,6 +287,10 @@ player it is saving too fast apart from a deck that is out of space.
 
 `Storage` saves data for the current player. Nobody else can read it.
 
+A player's whole `Storage` document is at most 2 MB. A write that takes
+it past that never saves, and nothing tells the deck: `set` has already
+returned.
+
 - **`Storage.get<T>(key): Promise<T | null>`** — the value at `key`, or
   `null` if it is not set.
 - **`Storage.set(key, value)`** — sets `key`. `value` must be something
@@ -293,7 +319,9 @@ await Store.private.set({ level: 7 });
 > and adds counters, listing, and leaderboards.
 
 `SharedStorage` saves data that other players can read. Values must be
-something that converts to JSON, same as `Storage`.
+something that converts to JSON, same as `Storage`. Each bucket holds at
+most 2 MB, and a write past that is dropped without an error, as with
+`Storage`.
 
 Scopes: `'deck'` is one bucket for the whole deck, readable and writable
 by any player. `'user'` is a per-player bucket that anyone can read and
@@ -520,6 +548,9 @@ when the player collects or closes it. `options`:
 
 Collecting works only in the Castle mobile app; the website shows "collect in
 the app" and the dev server a short notice, and both resolve `unavailable`.
+`offer` was added to the app on 2026-09-22; an app build from before then
+rejects it with `UNKNOWN_COMMAND` (see [CastleError](#castleerror)), so catch
+it where a deck has to keep going without the card.
 `SnapshotOfferResult` has a `status`:
 
 - `'collected'` — the player collected it.
@@ -534,6 +565,11 @@ const { status } = await Snapshot.offer({
 });
 ```
 
+A snapshot is not the deck's cover, and no SDK call sets the cover. A cover
+the creator chose by hand is kept; otherwise `save-deck` photographs the deck
+as it opens, falling back to a `preview.png` the deck folder holds when that
+capture does not produce one.
+
 ### `Snapshot.onTaken(handler): () => void`
 
 Registers a function called just before an offer's capture, the twin of the
@@ -604,7 +640,9 @@ label as the fallback. `PortalInfoResult` has a `status`:
   `null`), and `coverUrl`, a `data:` url of the deck's cover or `null`.
 - `'broken'` — the portal wouldn't work for this player: the deck doesn't
   exist, has portals turned off, or isn't visible to them.
-- `'unavailable'` — the host couldn't look it up.
+- `'unavailable'` — the host couldn't look it up. This includes a Castle
+  app built before `portal.info` was added (2026-09-22): `info` never
+  throws `UNKNOWN_COMMAND`.
 
 ```js
 const info = await Portal.info(doorway.deckId);
@@ -616,6 +654,45 @@ if (info.status === "ok") {
 
 Answers are kept per deck for the session, so asking again is cheap.
 
+## Decks
+
+`Decks` lists decks the player can point a portal at: their own published
+decks, and the decks they saved. A deck can offer these as a picker rather
+than asking for a pasted link.
+Decks is limited to Castle admins for now; for every other player both calls
+reject with a `PERMISSION_DENIED` error.
+
+### `Decks.mine(options?): Promise<DecksListResult>`
+
+The player's own decks, newest first, leaving out private ones.
+
+### `Decks.saved(options?): Promise<DecksListResult>`
+
+The decks the player bookmarked, then the decks in their playlists, each
+once.
+
+Both take `{ limit }`, from 1 through 50 (default 20), and both leave out
+decks whose creator turned portals off. The result is
+`{ status: 'ok', decks }`, where each deck is
+`{ deckId, title, creator: { userId, username } | null, coverUrl }` — the
+same shape as `Portal.info`. `coverUrl` is a `data:` url, since a deck may
+not load remote images; it is null when the deck has no cover. A player
+who is not signed in gets an empty list.
+
+```js
+const { decks } = await Decks.mine({ limit: 12 });
+for (const deck of decks) {
+  addPickerTile(deck.title, deck.coverUrl, () => placePortal(deck.deckId));
+}
+```
+
+## Clipboard
+
+The SDK has no clipboard command, and neither Castle host adds one: the
+Castle app has no clipboard bridge, and castle.xyz's player does not grant
+its frame `clipboard-write`. `navigator.clipboard` is best-effort — catch
+its failure and show the text so the player can copy it by hand.
+
 ## Haptics
 
 `Haptics` plays a short device vibration ("buzz") for tactile feedback —
@@ -651,6 +728,103 @@ Haptics respect the player's settings — if a player has muted haptics,
 `play` does nothing and resolves `'unavailable'`. Rapid repeated calls may
 be coalesced, so it's safe to call on frequent events.
 
+## Agent
+
+`Agent` asks a language model for one chat completion. The host sends it
+through Castle's oracle on the player's own Castle account, so the deck
+holds no key. Agent.chat is limited to Castle admins for now; every other
+player gets `'refused'`.
+
+### `Agent.chat(params): Promise<AgentChatResult>`
+
+`params`:
+
+- `messages` — the conversation, in the OpenAI chat format
+  (`{ role, content }`, plus `tool_calls` on an assistant message and
+  `tool_call_id` on a `'tool'` message).
+- `tools` — optional function tools, in the OpenAI function-tool schema.
+- `toolChoice` — optional: `'auto'` (the default), `'none'`, `'required'`,
+  or `{ type: 'function', function: { name } }` to force one tool.
+- `model` — optional OpenRouter model id. Defaults to
+  `'meta/muse-spark-1.3'`.
+- `maxTokens` — optional cap on the reply's length.
+- `reasoning` — optional `{ effort: 'minimal' | 'low' | 'medium' | 'high' }`,
+  how hard the model thinks before it answers. Lower effort answers sooner.
+  Left out, the model uses its own default. Muse can't turn reasoning off;
+  `'minimal'` is its least.
+- `onDelta` — optional callback for the reply as it streams in. It gets
+  `{ type: 'text', text }` and `{ type: 'reasoning', text }` pieces, and
+  `{ type: 'toolCall', toolCall }` once for each tool call, when its
+  arguments are complete. Pieces come in the order the model wrote them.
+- `signal` — optional `AbortSignal`. Aborting it stops the model and
+  resolves the call with `'cancelled'` at once.
+
+The promise resolves with the whole message when the model finishes. A deck
+runs any tool calls itself, appends the message and one `'tool'` message per
+call, and calls Agent.chat again, until a reply has no tool calls:
+
+```js
+import { Agent } from "castle-web-sdk";
+
+const tools = [
+  {
+    type: "function",
+    function: {
+      name: "roll_dice",
+      description: "Roll six-sided dice.",
+      parameters: {
+        type: "object",
+        properties: { count: { type: "integer" } },
+        required: ["count"],
+      },
+    },
+  },
+];
+const messages = [{ role: "user", content: "Roll two dice and add them." }];
+const stop = new AbortController();
+
+for (let round = 0; round < 8; round++) {
+  const result = await Agent.chat({
+    messages,
+    tools,
+    signal: stop.signal,
+    onDelta: (delta) => {
+      if (delta.type === "text") {
+        showText(delta.text);
+      }
+    },
+  });
+  if (result.status !== "ok") {
+    break;
+  }
+  messages.push(result.message);
+  const calls = result.message.tool_calls ?? [];
+  if (calls.length === 0) {
+    break;
+  }
+  for (const call of calls) {
+    const { count } = JSON.parse(call.function.arguments);
+    const faces = Array.from({ length: count }, () => 1 + Math.floor(Math.random() * 6));
+    messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(faces) });
+  }
+}
+```
+
+`AgentChatResult` has a `status`:
+
+- `'ok'` — `message` is the assistant's reply: `{ role, content,
+  tool_calls? }`, with `content` null when the reply is only tool calls.
+  `reasoning` is the model's reasoning summary when it gave one, for
+  display; it is not part of `message`. `finishReason` is `'stop'`,
+  `'tool_calls'` or `'length'`. `usage` carries `prompt_tokens`,
+  `completion_tokens` and `total_tokens`.
+- `'refused'` — the player is not a Castle admin. The model was not called.
+- `'unavailable'` — this host has no route to the oracle.
+- `'cancelled'` — the call's `signal` was aborted.
+- `'error'` — the oracle or the model failed; `reason` says how.
+
+Every status but `'ok'` carries a `reason`.
+
 ## Lifecycle
 
 `Lifecycle` tells the host when the deck has painted its first frame, so
@@ -899,5 +1073,25 @@ Common codes:
 - `CASTLE_HOST_UNAVAILABLE` — the Castle host (the app or website running
   the deck) didn't handle the request — e.g. it timed out or wasn't
   reachable. Usually transient; retry or surface a gentle error.
+- `UNKNOWN_COMMAND` ("Unknown Castle command.") — the Castle app running
+  the deck is a build older than the command. Each app build knows only the
+  commands it shipped with, and only an app update adds one, so keep the
+  deck working without it. The app's last version bump, iOS v1.149, came
+  before every command below, so v1.149 and earlier builds lack all of
+  them. Each date is the commit that added the command to the app's code,
+  not when a build carrying it reached the stores; an app built from code
+  before that commit answers `UNKNOWN_COMMAND`:
+  - `Multiplayer.join` — 2026-08-29
+  - `Store` (every method) — 2026-09-03
+  - `Lifecycle.restoreState` — 2026-09-08 (resolves `null` instead of
+    throwing)
+  - `User.get` — 2026-09-10
+  - `Characters` — 2026-09-20
+  - `Snapshot.offer` — 2026-09-22
+  - `Portal.info` — 2026-09-22 (resolves `unavailable` instead of throwing)
+  - `Agent.chat`, `Decks.mine`, `Decks.saved` — 2026-09-23
+
+  `Leaderboard.show` resolves `unavailable` rather than throwing on an app
+  that lacks it.
 - `CAULDRON_STORAGE_STALE_GENERATION` — the handle belongs to an older reset
   generation; reopen explicitly rather than replaying work into the new one.

package/dist/agent.d.ts

@@ -0,0 +1,6 @@
+import type { AgentChatParams, AgentChatResult } from "./commands";
+export type { AgentChatDelta, AgentChatParams, AgentChatResult, AgentMessage, AgentReasoning, AgentTool, AgentToolCall, AgentToolChoice, AgentUsage, } from "./commands";
+export interface CastleAgentApi {
+    chat(params: AgentChatParams): Promise<AgentChatResult>;
+}
+export declare const Agent: CastleAgentApi;

package/dist/agent.js

@@ -0,0 +1,70 @@
+// Agent — one chat completion from a language model, run by the host through
+// Castle's oracle with the player's own Castle account. Messages and tools
+// follow the OpenAI chat completions format. The reply streams: `onDelta` gets
+// text and reasoning as they arrive and each tool call once its arguments are
+// complete, and the promise resolves with the whole message. A deck runs any
+// tool calls itself and calls Agent.chat again with the results.
+//
+// Agent.chat is limited to Castle admins for now: every other player gets
+// `refused`. A host with no route to the oracle answers `unavailable`.
+import { CastleError } from "./errors";
+import { hostRequest } from "./transport";
+async function chat(params) {
+    validate(params);
+    const onDelta = params.onDelta;
+    try {
+        return await hostRequest("agent.chat", {
+            messages: params.messages,
+            tools: params.tools,
+            toolChoice: params.toolChoice,
+            model: params.model,
+            maxTokens: params.maxTokens,
+            reasoning: params.reasoning,
+        }, {
+            onStream: onDelta ? (event) => deliverDelta(onDelta, event) : undefined,
+            signal: params.signal,
+        });
+    }
+    catch (error) {
+        if (error instanceof CastleError && error.code === "CANCELLED") {
+            return { status: "cancelled", reason: "Agent.chat was cancelled." };
+        }
+        throw error;
+    }
+}
+const REASONING_EFFORTS = ["minimal", "low", "medium", "high"];
+function validate(params) {
+    if (!params || typeof params !== "object") {
+        invalid("Agent.chat requires { messages }.");
+    }
+    if (!Array.isArray(params.messages) || params.messages.length === 0) {
+        invalid("Agent.chat messages must be a non-empty array.");
+    }
+    if (params.tools !== undefined && !Array.isArray(params.tools)) {
+        invalid("Agent.chat tools must be an array.");
+    }
+    if (params.model !== undefined && (typeof params.model !== "string" || params.model === "")) {
+        invalid("Agent.chat model must be a model id.");
+    }
+    if (params.maxTokens !== undefined &&
+        (!Number.isSafeInteger(params.maxTokens) || params.maxTokens < 1)) {
+        invalid("Agent.chat maxTokens must be a positive integer.");
+    }
+    if (params.reasoning !== undefined && !REASONING_EFFORTS.includes(params.reasoning?.effort)) {
+        invalid("Agent.chat reasoning must be { effort: 'minimal' | 'low' | 'medium' | 'high' }.");
+    }
+    if (params.onDelta !== undefined && typeof params.onDelta !== "function") {
+        invalid("Agent.chat onDelta must be a function.");
+    }
+}
+// Keepalives only restart the wait in transport.ts; the deck never sees them.
+function deliverDelta(onDelta, event) {
+    const type = event?.type;
+    if (type === "text" || type === "reasoning" || type === "toolCall") {
+        onDelta(event);
+    }
+}
+function invalid(message) {
+    throw new CastleError({ code: "INVALID_ARGUMENT", message, operation: "Agent.chat" });
+}
+export const Agent = Object.freeze({ chat });

package/dist/castle.d.ts

@@ -1,6 +1,10 @@
 export { isEdit } from "./context";
+export { Agent } from "./agent";
+export type { AgentChatDelta, AgentChatParams, AgentChatResult, AgentMessage, AgentReasoning, AgentTool, AgentToolCall, AgentToolChoice, AgentUsage, CastleAgentApi, } from "./agent";
 export { Characters } from "./characters";
 export type { CastleCharactersApi, CharacterHandle, CharacterHistoryOptions, CharacterSendInput, } from "./characters";
+export { Decks } from "./decks";
+export type { CastleDecksApi, DeckSummary, DecksListParams, DecksListResult } from "./decks";
 export { CastleError } from "./errors";
 export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
 export { Haptics } from "./haptics";
@@ -11,6 +15,7 @@ export { Lifecycle } from "./lifecycle";
 export type { CastleLifecycleApi } from "./lifecycle";
 export { Multiplayer } from "./multiplayer";
 export type { CastleMultiplayerApi, MultiplayerConnection, MultiplayerConnectionState, MultiplayerJoinOptions, MultiplayerRoster, MultiplayerStateMetadata, } from "./multiplayer";
+export type { MultiplayerVoice, VoiceJoinStatus, VoiceMixEntry, VoiceState, } from "./multiplayerVoice";
 export type { MultiplayerSoloReason } from "./commands";
 export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";
 export type { ClientByeFrame, ClientHelloFrame, ClientMessageFrame, ClientPingFrame, ClientPongFrame, ClientReplacedFrame, ClientRosterFrame, ClientToPlatformFrame, ClientToPlatformMessageFrame, MultiplayerPlayer, PlayerIdentity, PlatformToClientFrame, SessionPlayer, SessionType, } from "./multiplayerProtocol";

package/dist/castle.js

@@ -1,6 +1,8 @@
 // Castle Web SDK
 export { isEdit } from "./context";
+export { Agent } from "./agent";
 export { Characters } from "./characters";
+export { Decks } from "./decks";
 export { CastleError } from "./errors";
 export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
 export { Haptics } from "./haptics";

package/dist/commands.d.ts

@@ -103,6 +103,14 @@ export interface MultiplayerGetSessionResult {
     /** Internal local-serve scope for restoring this Play panel after a reload. */
     devReconnectScope?: string;
 }
+export type VoiceState = "unavailable" | "off" | "joining" | "live";
+export type VoiceJoinStatus = "joined" | "declined" | "unavailable";
+export interface VoiceMixEntry {
+    /** 0 (silent) to 1 (full). */
+    gain?: number;
+    /** -1 (left) to 1 (right). */
+    pan?: number;
+}
 export interface CharacterSummary {
     id: string;
     version: string;
@@ -142,7 +150,97 @@ export interface CharacterHistory {
     operations: CharacterOperation[];
     cursor: string | null;
 }
+export interface AgentToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface AgentMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | Json[] | null;
+    tool_calls?: AgentToolCall[];
+    tool_call_id?: string;
+    name?: string;
+}
+export interface AgentTool {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Json;
+    };
+}
+export type AgentToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
+export type AgentChatDelta = {
+    type: "text";
+    text: string;
+} | {
+    type: "reasoning";
+    text: string;
+} | {
+    type: "toolCall";
+    toolCall: AgentToolCall;
+};
+export type AgentChatStreamEvent = AgentChatDelta | {
+    type: "keepalive";
+};
+export interface AgentReasoning {
+    effort: "minimal" | "low" | "medium" | "high";
+}
+export interface AgentChatParams {
+    messages: AgentMessage[];
+    tools?: AgentTool[];
+    toolChoice?: AgentToolChoice;
+    model?: string;
+    maxTokens?: number;
+    reasoning?: AgentReasoning;
+    onDelta?: (delta: AgentChatDelta) => void;
+    signal?: AbortSignal;
+}
+export type AgentChatRequest = Omit<AgentChatParams, "onDelta" | "signal">;
+export interface AgentUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export type AgentChatResult = {
+    status: "ok";
+    message: AgentMessage;
+    reasoning?: string;
+    finishReason: string | null;
+    usage?: AgentUsage;
+} | {
+    status: "unavailable" | "refused" | "error" | "cancelled";
+    reason: string;
+};
+export interface DeckSummary {
+    deckId: string;
+    title: string;
+    creator: {
+        userId: string;
+        username: string;
+    } | null;
+    coverUrl: string | null;
+}
+export interface DecksListParams {
+    limit?: number | null;
+}
+export interface DecksListResult {
+    status: "ok";
+    decks: DeckSummary[];
+}
 export interface CommandParams {
+    "agent.chat": AgentChatRequest;
+    "decks.mine": DecksListParams;
+    "decks.saved": DecksListParams;
     "deckStorage.load": Record<string, never>;
     "deckStorage.update": {
         updates: StorageUpdate[];
@@ -205,6 +303,19 @@ export interface CommandParams {
         style: HapticStyle;
     };
     "multiplayer.getSession": MultiplayerGetSessionParams;
+    "voice.getState": {
+        sessionId: string;
+    };
+    "voice.requestJoin": {
+        sessionId: string;
+    };
+    "voice.leave": {
+        sessionId: string;
+    };
+    "voice.setMix": {
+        sessionId: string;
+        mix: Record<string, VoiceMixEntry>;
+    };
     "characters.open": {
         characterId: string;
     };
@@ -279,6 +390,9 @@ export interface CommandParams {
     "lifecycle.restoreState": Record<string, never>;
 }
 export interface CommandResult {
+    "agent.chat": AgentChatResult;
+    "decks.mine": DecksListResult;
+    "decks.saved": DecksListResult;
     "deckStorage.load": {
         blob: StorageBlob;
     };
@@ -324,6 +438,18 @@ export interface CommandResult {
     "portal.info": PortalInfoResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
+    "voice.getState": {
+        state: VoiceState;
+    };
+    "voice.requestJoin": {
+        status: VoiceJoinStatus;
+    };
+    "voice.leave": {
+        ok: true;
+    };
+    "voice.setMix": {
+        ok: true;
+    };
     "characters.open": CharacterAdmission;
     "characters.send": CharacterOperation;
     "characters.status": CharacterOperation;
@@ -365,6 +491,8 @@ export interface UserPayload {
     color: string | null;
 }
 export type CommandName = keyof CommandParams;
+export declare const COMMAND_TIMEOUTS_MS: Partial<Record<CommandName, number>>;
+export declare const STREAM_IDLE_TIMEOUT_MS = 60000;
 export interface SerializedCommandError {
     code: string;
     message: string;
@@ -385,6 +513,17 @@ export interface CommandResponseEnvelope {
     error?: SerializedCommandError;
 }
 export declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;
+export interface CommandStreamEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    requestId: string;
+    stream: unknown;
+}
+export declare function isStreamEnvelope(value: unknown): value is CommandStreamEnvelope;
+export interface CommandCancelEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    requestId: string;
+    cancel: true;
+}
 export type LifecycleEvent = "ready" | "unloadInterest";
 export interface LifecycleEnvelope {
     castleSdk: typeof CASTLE_SDK_PROTOCOL;
@@ -404,3 +543,18 @@ export interface UnloadDoneEnvelope {
         state?: string;
     };
 }
+export type VoiceEvent = {
+    type: "state";
+    sessionId: string;
+    state: VoiceState;
+} | {
+    type: "speaking";
+    sessionId: string;
+    userIds: string[];
+};
+export interface VoiceEventEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    voice: VoiceEvent;
+}
+export declare function isVoiceState(value: unknown): value is VoiceState;
+export declare function voiceEventFrom(value: unknown): VoiceEvent | null;

package/dist/commands.js

@@ -6,6 +6,18 @@
 // Marker + protocol version. Doubles as a discriminator so host messages can't
 // be confused with embed.js `castlexyz:` strings or RN console messages.
 export const CASTLE_SDK_PROTOCOL = 1;
+// How long the deck waits for a reply to these commands, in place of the
+// data-command timeout. A deck list fetches every cover on the list. A host
+// from before streaming reads a whole model reply before answering agent.chat.
+export const COMMAND_TIMEOUTS_MS = {
+    "agent.chat": 180_000,
+    "decks.mine": 30_000,
+    "decks.saved": 30_000,
+};
+// Once a host streams a command, each stream envelope restarts the wait at this
+// length instead. The oracle sends a heartbeat every 15 seconds, and the host
+// passes each one on.
+export const STREAM_IDLE_TIMEOUT_MS = 60_000;
 export function isResponseEnvelope(value) {
     if (typeof value !== "object" || value === null)
         return false;
@@ -14,6 +26,15 @@ export function isResponseEnvelope(value) {
         typeof record.requestId === "string" &&
         typeof record.ok === "boolean");
 }
+export function isStreamEnvelope(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return (record.castleSdk === CASTLE_SDK_PROTOCOL &&
+        typeof record.requestId === "string" &&
+        "stream" in record);
+}
 export function unloadRequestId(value) {
     if (typeof value !== "object" || value === null)
         return null;
@@ -23,3 +44,28 @@ export function unloadRequestId(value) {
     const unload = record.unload;
     return typeof unload?.unloadId === "string" ? unload.unloadId : null;
 }
+const VOICE_STATES = ["unavailable", "off", "joining", "live"];
+export function isVoiceState(value) {
+    return typeof value === "string" && VOICE_STATES.includes(value);
+}
+export function voiceEventFrom(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const record = value;
+    if (record.castleSdk !== CASTLE_SDK_PROTOCOL)
+        return null;
+    const event = record.voice;
+    if (typeof event !== "object" || event === null)
+        return null;
+    if (typeof event.sessionId !== "string")
+        return null;
+    if (event.type === "state" && isVoiceState(event.state)) {
+        return { type: "state", sessionId: event.sessionId, state: event.state };
+    }
+    if (event.type === "speaking" &&
+        Array.isArray(event.userIds) &&
+        event.userIds.every((userId) => typeof userId === "string")) {
+        return { type: "speaking", sessionId: event.sessionId, userIds: event.userIds.slice() };
+    }
+    return null;
+}

package/dist/decks.d.ts

@@ -0,0 +1,7 @@
+import type { DecksListParams, DecksListResult } from "./commands";
+export type { DeckSummary, DecksListParams, DecksListResult } from "./commands";
+export interface CastleDecksApi {
+    mine(options?: DecksListParams): Promise<DecksListResult>;
+    saved(options?: DecksListParams): Promise<DecksListResult>;
+}
+export declare const Decks: CastleDecksApi;