@tavora/sdk 0.0.0-stage → 0.2.2

package/dist/protocol.js

@@ -0,0 +1,123 @@
+// Wire protocol v1 between a module and the Tavora host, carried over a
+// MessagePort. Specified in apps/docs/reference/protocol.md.
+//
+// Identity (which module, which game, which panel) is never part of a
+// message. The host binds it to the port when it creates the channel.
+/** Major protocol version. Every message carries it as `v`. */
+export const PROTOCOL_VERSION = 1;
+/** Posted by the SDK on its own window to ask the host for a bridge port. */
+export const HELLO_MESSAGE = "tavora:hello";
+/** Posted by the host preload on the module window, carrying the port. */
+export const PORT_MESSAGE = "tavora:port";
+/** Names of the semantic colour tokens in TavoraTheme.tokens. */
+export const THEME_TOKENS = [
+    "background",
+    "foreground",
+    "card",
+    "card-foreground",
+    "popover",
+    "popover-foreground",
+    "primary",
+    "primary-hover",
+    "primary-foreground",
+    "secondary",
+    "secondary-foreground",
+    "muted",
+    "muted-foreground",
+    "accent",
+    "accent-foreground",
+    "destructive",
+    "border",
+    "input",
+    "ring",
+    "rail",
+    "success",
+    "warning",
+    "info",
+];
+export const DISCORD_COMMANDS = [
+    "GET_SELECTED_VOICE_CHANNEL",
+    "GET_GUILDS",
+    "GET_GUILD",
+    "GET_CHANNELS",
+    "GET_CHANNEL",
+    "SELECT_VOICE_CHANNEL",
+    "SET_VOICE_SETTINGS",
+    "SET_USER_VOICE_SETTINGS",
+];
+/**
+ * Discord RPC events a module may subscribe to. VOICE_CHANNEL_SELECT (the player joined, moved or left)
+ * takes no channel; the others are for one voice channel and need its id.
+ */
+export const DISCORD_EVENTS = ["VOICE_CHANNEL_SELECT", "VOICE_STATE_CREATE", "VOICE_STATE_UPDATE", "VOICE_STATE_DELETE", "SPEAKING_START", "SPEAKING_STOP"];
+/** Methods reserved for later milestones, and the capability each needs. */
+export const RESERVED_METHODS = {
+    "files.open": "files",
+    "files.save": "files",
+    "clipboard.writeText": "clipboard",
+    "clipboard.readText": "clipboard",
+    "sharedData.publish": "sharedData",
+    "sharedData.read": "sharedData",
+    "sharedData.subscribe": "sharedData",
+};
+export const LIMITS = {
+    /** Largest serialized request the host accepts. */
+    maxMessageBytes: 8 * 1024 * 1024,
+    /** Requests a module may have waiting at once. */
+    maxInFlight: 64,
+    maxKeyLength: 256,
+    /** Settings storage per module and game. */
+    maxStoreBytes: 5 * 1024 * 1024,
+    /** One document's data. */
+    maxDocumentBytes: 4 * 1024 * 1024,
+    /** All documents of one module in one game. */
+    maxDocumentsBytes: 50 * 1024 * 1024,
+    maxDocuments: 1000,
+    maxTitleLength: 200,
+    /** UI state for one panel. */
+    maxPanelStateBytes: 256 * 1024,
+    /** One stored file (see Blobs). */
+    maxBlobBytes: 50 * 1024 * 1024,
+    /** All stored files of one module in one game. */
+    maxBlobsBytes: 500 * 1024 * 1024,
+    /** A PNG a module puts on the clipboard. */
+    maxClipboardImageBytes: 20 * 1024 * 1024,
+    /** The body of one network.fetch answer, before any base64. A longer answer fails with QUOTA_EXCEEDED. */
+    maxNetworkResponseBytes: 5 * 1024 * 1024,
+    /** How long one network.fetch may take, redirects included. */
+    networkTimeoutMs: 15_000,
+    /** Redirects one network.fetch follows; each must go to a granted host. */
+    maxNetworkRedirects: 5,
+    /** network.fetch calls one panel may have running at once; more fail with BAD_REQUEST. */
+    maxNetworkInFlight: 6,
+    /** How often Tavora reads one AI account at most, for every module together; asking sooner gives the last reading. */
+    aiUsageMinReadMs: 60_000,
+    /** How long one aiUsage.read may take; the Codex command line can be slow to start. */
+    aiUsageTimeoutMs: 40_000,
+    /** How long one discord.command may take; a slower answer is `no-answer`. */
+    discordTimeoutMs: 15_000,
+    /** Largest Discord answer or event passed on, as JSON; a larger one is `no-answer` (or dropped, for an event). */
+    maxDiscordAnswerBytes: 512 * 1024,
+    /** Discord events one panel may subscribe to at once. */
+    maxDiscordSubscriptions: 32,
+    /** Entries in one menu, submenus included. */
+    maxMenuEntries: 100,
+    /** Characters of a menu label or heading. */
+    maxMenuLabel: 80,
+    /** Characters of the hint on the right of a menu item, such as a shortcut. */
+    maxMenuHint: 30,
+};
+/** The kinds of file a module can keep with blobs.put, found by looking at the file itself. */
+export const BLOB_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
+/**
+ * Files are sent to and shown from the module's own address, not over the
+ * bridge: POST /_blobs/ stores the request body and answers with a BlobInfo,
+ * GET /_blobs/<id> serves a file. Both only work from the module's own page.
+ */
+export const BLOB_PATH = "/_blobs/";
+export const BLOB_ID = /^[a-f0-9]{32}$/;
+/** POST a PNG here, from the module's own page, to put it on the clipboard (see clipboard.writeImage). */
+export const CLIPBOARD_PATH = "/_clipboard/";
+/** Document ids: host-generated UUIDs or module-chosen slugs. */
+export const DOCUMENT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@tavora/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.2",
+  "description": "Typed client for Tavora modules: talks to the Tavora Desktop host over its bridge.",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "tavora",
+    "module",
+    "sdk",
+    "gaming"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wellbrained/tavora.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://docs.mytavora.app/",
+  "bugs": "https://github.com/wellbrained/tavora/issues",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p ."
+  }
 }

package/src/index.ts

@@ -0,0 +1,491 @@
+// @tavora/sdk: thin typed client for modules running inside Tavora Desktop.
+// The host enforces every check; this package only marshals typed calls.
+// Protocol reference: apps/docs/reference/protocol.md.
+
+import {
+  BLOB_PATH,
+  CLIPBOARD_PATH,
+  HELLO_MESSAGE,
+  LIMITS,
+  PORT_MESSAGE,
+  PROTOCOL_VERSION,
+  type AiUsageAccountInfo,
+  type AiUsageReading,
+  type BlobInfo,
+  type BlobUsage,
+  type Capability,
+  type DiscordCommand,
+  type DiscordCommands,
+  type DiscordEvent,
+  type DiscordEventName,
+  type DiscordResult,
+  type DiscordState,
+  type DocumentChange,
+  type DocumentSummary,
+  type ErrorCode,
+  type ErrorPayload,
+  type EventName,
+  type Events,
+  type HandshakeResult,
+  type HostMessage,
+  type JsonValue,
+  type MenuRequest,
+  type MethodName,
+  type Methods,
+  type NetworkRequest,
+  type NetworkResponse,
+  type PutDocumentParams,
+  type TavoraDocument,
+  type TavoraGame,
+  type TavoraTheme,
+  type TavoraViewport,
+} from "./protocol.js";
+
+export type {
+  AiUsageAccountInfo,
+  AiUsageReading,
+  BlobInfo,
+  BlobType,
+  BlobUsage,
+  Capability,
+  DiscordCommand,
+  DiscordCommands,
+  DiscordEvent,
+  DiscordEventName,
+  DiscordResult,
+  DiscordState,
+  DocumentChange,
+  DocumentSummary,
+  ErrorCode,
+  HandshakeResult,
+  JsonValue,
+  MenuEntry,
+  MenuRequest,
+  NetworkRequest,
+  NetworkResponse,
+  PutDocumentParams,
+  TavoraDocument,
+  TavoraGame,
+  TavoraTheme,
+  TavoraViewport,
+  ThemeToken,
+} from "./protocol.js";
+export { BLOB_ID, BLOB_TYPES, DISCORD_COMMANDS, DISCORD_EVENTS, LIMITS, PROTOCOL_VERSION, THEME_TOKENS } from "./protocol.js";
+
+/** How long a menu may stay open; the host closes it itself when its panel goes. */
+const MENU_TIMEOUT_MS = 60 * 60_000;
+
+/** Version of this SDK package, sent to the host during the handshake. */
+export const SDK_VERSION = "0.2.2";
+
+/**
+ * The oldest Tavora that has everything this SDK version offers. Put it in your manifest as
+ * `minTavora`, so an older Tavora says it needs an update instead of loading a module it cannot run
+ * (the starter, `npm create @tavora/module`, does). The changelog names it for every version.
+ */
+export const MIN_TAVORA = "0.17.12";
+
+export class TavoraError extends Error {
+  readonly code: ErrorCode;
+  /** Set for PERMISSION_DENIED. */
+  readonly capability: Capability | undefined;
+  /** Set for CONFLICT: the document's current revision. */
+  readonly revision: number | undefined;
+
+  constructor(payload: ErrorPayload) {
+    super(payload.message);
+    this.name = "TavoraError";
+    this.code = payload.code;
+    this.capability = payload.capability;
+    this.revision = payload.revision;
+  }
+}
+
+type Unsubscribe = () => void;
+
+/** Small key/value settings: at most 5 MB of keys and values together, values plain JSON. */
+export interface KeyValueStore {
+  /** T is not checked at runtime; the host only guarantees the value is JSON. */
+  get<T = JsonValue>(key: string): Promise<T | null>;
+  set(key: string, value: JsonValue): Promise<void>;
+  delete(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+}
+
+export interface TavoraSDK {
+  /** What the host reported when this module connected. */
+  readonly host: HandshakeResult;
+  game: {
+    getCurrent(): Promise<TavoraGame>;
+  };
+  /** Small key/value settings, private to this module in the current game. */
+  storage: KeyValueStore & {
+    /** The same, shared by every game: settings that should not change from game to game. */
+    app: KeyValueStore;
+  };
+  /**
+   * Named documents (builds, plans, checklists), private to this module in
+   * the current game and shared by all of its panels.
+   */
+  documents: {
+    list(): Promise<DocumentSummary[]>;
+    get<T = JsonValue>(id: string): Promise<(TavoraDocument & { data: T }) | null>;
+    /** Creates or replaces a document. Pass ifRevision to avoid overwriting another panel's change. */
+    put(document: PutDocumentParams): Promise<DocumentSummary>;
+    delete(id: string, options?: { ifRevision?: number }): Promise<void>;
+    /** Fires when another panel of this module changes a document. */
+    onChange(fn: (change: DocumentChange) => void): Unsubscribe;
+  };
+  /** UI state for this one panel (selection, scroll, open tab). Cleared when the panel is closed. */
+  panel: {
+    /** Which of the manifest's `panels` this panel is, by id; null for a module without panel types (or an older Tavora). */
+    readonly type: string | null;
+    getState<T = JsonValue>(): Promise<T | null>;
+    setState(value: JsonValue | null): Promise<void>;
+  };
+  workspace: {
+    getViewport(): Promise<TavoraViewport>;
+    onResize(fn: (viewport: TavoraViewport) => void): Unsubscribe;
+  };
+  ui: {
+    getTheme(): Promise<TavoraTheme>;
+    onThemeChange(fn: (theme: TavoraTheme) => void): Unsubscribe;
+    /** The language Tavora shows its own texts in, as a code such as "en" or "de". Show yours in it, or in English when you have no translation. */
+    getLanguage(): Promise<string>;
+    /** Fires when the player changes the language. */
+    onLanguageChange(fn: (language: string) => void): Unsubscribe;
+    /**
+     * Shows a menu that Tavora draws above every panel, so it is never cut off at the panel's edge. Call it from
+     * the click, right-click or key press that asked for it: the host refuses it otherwise (PERMISSION_DENIED).
+     * Resolves with the chosen item's id, or null when the player closed the menu without choosing.
+     */
+    showMenu(request: MenuRequest): Promise<string | null>;
+  };
+  /**
+   * Files (pictures) this module keeps in the current game, shared by all of its panels. They live
+   * in a folder Tavora manages, not in a document, so they can be large: up to 50 MB each and
+   * 500 MB together. Only PNG, JPEG, GIF and WebP are accepted, judged by the file itself.
+   */
+  blobs: {
+    /** Stores a file and returns its id. Rejects with QUOTA_EXCEEDED, or INVALID_PARAMS for another kind of file. */
+    put(file: Blob): Promise<BlobInfo>;
+    /** The address to show a stored file from, for example as an image source. */
+    url(id: string): string;
+    list(): Promise<BlobInfo[]>;
+    usage(): Promise<BlobUsage>;
+    /** Deletes a file; nothing happens when it does not exist. */
+    delete(id: string): Promise<void>;
+  };
+  clipboard: {
+    /**
+     * Puts a picture on the system clipboard, so the player can paste it anywhere. Call it from the click or key
+     * press that asked for it: the host refuses it otherwise (PERMISSION_DENIED), and one press copies one
+     * picture. PNG only, a complete one, at most 20 MB and 16384 pixels on a side (INVALID_PARAMS, QUOTA_EXCEEDED).
+     */
+    writeImage(png: Blob): Promise<void>;
+  };
+  links: {
+    /**
+     * Opens a web address (http or https) in a Browser panel of this game, as a new tab or in a new
+     * panel. Call it from the click or key press that asked for it: the host refuses it otherwise
+     * (PERMISSION_DENIED). The module learns nothing about the page.
+     */
+    open(url: string): Promise<void>;
+  };
+  network: {
+    /**
+     * Makes a web request through Tavora, to a host listed in `permissions.network` that the player
+     * granted (PERMISSION_DENIED otherwise). HTTPS only, no cookies, at most 5 MB back and 15 seconds.
+     * Error statuses such as 404 are answers, not errors; NETWORK_ERROR means no answer came.
+     */
+    fetch(url: string, init?: Omit<NetworkRequest, "url">): Promise<NetworkResponse>;
+  };
+  /** Parts of Tavora that hold a sign-in, used without seeing it. Each needs its connector in `permissions.connectors` and the player's grant (PERMISSION_DENIED otherwise). */
+  connectors: {
+    /** `ai-usage`: the usage of the Claude and Codex accounts the player set up in Settings > Integrations > AI usage. */
+    aiUsage: {
+      accounts(): Promise<AiUsageAccountInfo[]>;
+      /** Reads one account. Tavora reads each account at most once a minute; asking sooner gives the last reading. */
+      read(accountId: string): Promise<AiUsageReading>;
+      /** Fires when the player adds, renames or removes an account. */
+      onAccountsChange(fn: () => void): Unsubscribe;
+    };
+    /**
+     * `discord`: the Discord app on this PC, through Tavora's Discord sign-in. The connection runs while a
+     * panel has asked for state(); Tavora keeps the sign-in and sends only the commands in DISCORD_COMMANDS.
+     */
+    discord: {
+      /** The connection now. The first call starts it for this panel. */
+      state(): Promise<DiscordState>;
+      onStateChange(fn: (state: DiscordState) => void): Unsubscribe;
+      /** Signs in, asking for approval in Discord the first time. Call it from a click or key press handler. */
+      connect(): Promise<void>;
+      /** Asks Discord to approve muting and deafening, for a sign-in that can't yet (canControl false). From a click or key press. */
+      allowControl(): Promise<void>;
+      /** Sends one command; resolves with Discord's answer as it came, or why there is none. SELECT_VOICE_CHANNEL and SET_VOICE_SETTINGS only from a click or key press. */
+      command<C extends DiscordCommand>(command: C, args: DiscordCommands[C]): Promise<DiscordResult>;
+      /** Starts sending an event to this panel (VOICE_CHANNEL_SELECT without a channel, the others for one voice channel). Kept across reconnects. */
+      subscribe(event: DiscordEventName, channelId?: string): Promise<void>;
+      unsubscribe(event: DiscordEventName, channelId?: string): Promise<void>;
+      onEvent(fn: (event: DiscordEvent) => void): Unsubscribe;
+      /** A picture from cdn.discordapp.com (an avatar or server icon address) as a small PNG data address, or null. */
+      image(url: string): Promise<string | null>;
+    };
+  };
+  lifecycle: {
+    /** The panel is hidden; pause timers and animations. Called immediately if already suspended. */
+    onSuspend(fn: () => void): Unsubscribe;
+    onResume(fn: () => void): Unsubscribe;
+    /** Best effort only: autosave must not depend on this firing. */
+    onDispose(fn: () => void): Unsubscribe;
+  };
+}
+
+export interface ConnectOptions {
+  /** How long to wait for the host to hand over a port. Default 5000 ms. */
+  connectTimeoutMs?: number;
+  /** How long to wait for each request. Default 10000 ms. */
+  requestTimeoutMs?: number;
+}
+
+let connection: Promise<TavoraSDK> | undefined;
+
+/**
+ * Connects to the Tavora host. Safe to call more than once: every call
+ * returns the same connection for this window. Rejects with a TavoraError
+ * (HOST_UNAVAILABLE, INCOMPATIBLE) if the module cannot run here.
+ */
+export function connect(options: ConnectOptions = {}): Promise<TavoraSDK> {
+  connection ??= openPort(options.connectTimeoutMs ?? 5000)
+    .then((port) => createClient(port, options.requestTimeoutMs ?? 10_000))
+    .catch((error: unknown) => {
+      connection = undefined;
+      throw error;
+    });
+  return connection;
+}
+
+function openPort(timeoutMs: number): Promise<MessagePort> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      window.removeEventListener("message", onMessage);
+      reject(
+        new TavoraError({
+          code: "HOST_UNAVAILABLE",
+          message: "Tavora host did not respond. Is this module running inside Tavora?",
+        }),
+      );
+    }, timeoutMs);
+
+    function onMessage(event: MessageEvent) {
+      if (event.source !== window || event.data?.type !== PORT_MESSAGE || !event.ports[0]) return;
+      clearTimeout(timer);
+      window.removeEventListener("message", onMessage);
+      resolve(event.ports[0]);
+    }
+
+    window.addEventListener("message", onMessage);
+    window.postMessage({ type: HELLO_MESSAGE, v: PROTOCOL_VERSION }, window.location.origin);
+  });
+}
+
+async function createClient(port: MessagePort, requestTimeoutMs: number): Promise<TavoraSDK> {
+  let nextId = 1;
+  const pending = new Map<
+    number,
+    { resolve(value: unknown): void; reject(error: TavoraError): void; timer: ReturnType<typeof setTimeout> }
+  >();
+  const listeners = new Map<EventName, Set<(data: unknown) => void>>();
+  let suspended = false;
+
+  port.onmessage = (event: MessageEvent<HostMessage>) => {
+    const message = event.data;
+    if (typeof message !== "object" || message === null || message.v !== PROTOCOL_VERSION) return;
+
+    if ("event" in message) {
+      if (message.event === "lifecycle.suspend") suspended = true;
+      if (message.event === "lifecycle.resume") suspended = false;
+      for (const fn of listeners.get(message.event) ?? []) {
+        try {
+          fn(message.data);
+        } catch (error) {
+          console.error(`[tavora] ${message.event} listener failed`, error);
+        }
+      }
+      return;
+    }
+
+    const entry = pending.get(message.id);
+    if (!entry) return;
+    pending.delete(message.id);
+    clearTimeout(entry.timer);
+    if (message.ok) entry.resolve(message.result);
+    else entry.reject(new TavoraError(message.error));
+  };
+  port.start();
+
+  function call<M extends MethodName>(method: M, params?: Methods[M]["params"], timeoutMs = requestTimeoutMs): Promise<Methods[M]["result"]> {
+    const id = nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new TavoraError({ code: "TIMEOUT", message: `${method} timed out` }));
+      }, Math.max(timeoutMs, requestTimeoutMs));
+      pending.set(id, { resolve: resolve as (value: unknown) => void, reject, timer });
+      port.postMessage({ v: PROTOCOL_VERSION, id, method, params });
+    });
+  }
+
+  function on<E extends EventName>(event: E, fn: (data: Events[E]) => void): Unsubscribe {
+    let set = listeners.get(event);
+    if (!set) listeners.set(event, (set = new Set()));
+    const listener = fn as (data: unknown) => void;
+    set.add(listener);
+    // Initial suspension can arrive before connect() callers register listeners.
+    if (event === "lifecycle.suspend" && suspended) {
+      try {
+        listener(null);
+      } catch (error) {
+        console.error(`[tavora] ${event} listener failed`, error);
+      }
+    }
+    return () => set.delete(listener);
+  }
+
+  const host = await call("bridge.handshake", { protocol: PROTOCOL_VERSION, sdkVersion: SDK_VERSION });
+
+  return {
+    host,
+    game: {
+      getCurrent: () => call("game.getCurrent"),
+    },
+    storage: {
+      get: <T = JsonValue>(key: string) => call("storage.get", { key }) as Promise<T | null>,
+      set: async (key, value) => {
+        await call("storage.set", { key, value });
+      },
+      delete: async (key) => {
+        await call("storage.delete", { key });
+      },
+      keys: () => call("storage.keys"),
+      app: {
+        get: <T = JsonValue>(key: string) => call("storage.app.get", { key }) as Promise<T | null>,
+        set: async (key, value) => {
+          await call("storage.app.set", { key, value });
+        },
+        delete: async (key) => {
+          await call("storage.app.delete", { key });
+        },
+        keys: () => call("storage.app.keys"),
+      },
+    },
+    documents: {
+      list: () => call("documents.list"),
+      get: <T = JsonValue>(id: string) =>
+        call("documents.get", { id }) as Promise<(TavoraDocument & { data: T }) | null>,
+      put: (document) => call("documents.put", document),
+      delete: async (id, options = {}) => {
+        await call("documents.delete", { id, ...options });
+      },
+      onChange: (fn) => on("documents.changed", fn),
+    },
+    panel: {
+      type: host.panel?.type ?? null,
+      getState: <T = JsonValue>() => call("panel.getState") as Promise<T | null>,
+      setState: async (value) => {
+        await call("panel.setState", { value });
+      },
+    },
+    workspace: {
+      getViewport: () => call("workspace.getViewport"),
+      onResize: (fn) => on("workspace.resize", fn),
+    },
+    ui: {
+      getTheme: () => call("ui.getTheme"),
+      onThemeChange: (fn) => on("ui.theme", fn),
+      getLanguage: () => call("ui.getLanguage"),
+      onLanguageChange: (fn) => on("ui.language", fn),
+      // The player may take their time choosing.
+      showMenu: (request) => call("ui.showMenu", request, MENU_TIMEOUT_MS),
+    },
+    blobs: {
+      put: async (file) => {
+        let response: Response;
+        try {
+          response = await fetch(new URL(BLOB_PATH, window.location.href), {
+            method: "POST",
+            body: file,
+            headers: { "Content-Type": file.type || "application/octet-stream" },
+          });
+        } catch {
+          throw new TavoraError({ code: "INTERNAL", message: "could not store the file" });
+        }
+        const body = (await response.json().catch(() => null)) as (BlobInfo & { error?: ErrorPayload }) | null;
+        if (!response.ok || !body || body.error) {
+          throw new TavoraError(body?.error ?? { code: "INTERNAL", message: `could not store the file (${response.status})` });
+        }
+        return body;
+      },
+      url: (id) => new URL(`${BLOB_PATH}${encodeURIComponent(id)}`, window.location.href).href,
+      list: () => call("blobs.list"),
+      usage: () => call("blobs.usage"),
+      delete: async (id) => {
+        await call("blobs.delete", { id });
+      },
+    },
+    clipboard: {
+      writeImage: async (png) => {
+        if (png.type !== "image/png") throw new TavoraError({ code: "INVALID_PARAMS", message: "only a PNG picture can be copied" });
+        let response: Response;
+        try {
+          response = await fetch(new URL(CLIPBOARD_PATH, window.location.href), { method: "POST", body: png, headers: { "Content-Type": "image/png" } });
+        } catch {
+          throw new TavoraError({ code: "INTERNAL", message: "could not copy the picture" });
+        }
+        if (response.ok) return;
+        const body = (await response.json().catch(() => null)) as { error?: ErrorPayload } | null;
+        throw new TavoraError(body?.error ?? { code: "INTERNAL", message: `could not copy the picture (${response.status})` });
+      },
+    },
+    links: {
+      open: async (url) => {
+        await call("links.open", { url });
+      },
+    },
+    network: {
+      // The host gives up after its own limit; this waits a little longer so its answer arrives first.
+      fetch: (url, init = {}) => call("network.fetch", { ...init, url }, LIMITS.networkTimeoutMs + 5000),
+    },
+    connectors: {
+      aiUsage: {
+        accounts: () => call("aiUsage.accounts"),
+        read: (accountId) => call("aiUsage.read", { accountId }, LIMITS.aiUsageTimeoutMs + 5000),
+        onAccountsChange: (fn) => on("aiUsage.accountsChanged", () => fn()),
+      },
+      discord: {
+        state: () => call("discord.state"),
+        onStateChange: (fn) => on("discord.state", fn),
+        connect: async () => {
+          await call("discord.connect");
+        },
+        allowControl: async () => {
+          await call("discord.allowControl");
+        },
+        command: (command, args) => call("discord.command", { command, args }, LIMITS.discordTimeoutMs + 5000),
+        subscribe: async (event, channelId) => {
+          await call("discord.subscribe", channelId === undefined ? { event } : { event, channelId });
+        },
+        unsubscribe: async (event, channelId) => {
+          await call("discord.unsubscribe", channelId === undefined ? { event } : { event, channelId });
+        },
+        onEvent: (fn) => on("discord.event", fn),
+        image: (url) => call("discord.image", { url }),
+      },
+    },
+    lifecycle: {
+      onSuspend: (fn) => on("lifecycle.suspend", fn),
+      onResume: (fn) => on("lifecycle.resume", fn),
+      onDispose: (fn) => on("lifecycle.dispose", fn),
+    },
+  };
+}