@neurosquad/card-sdk 1.0.0

package/dist/types/client/channel.d.ts

@@ -0,0 +1,49 @@
+import { CardSdkError } from './errors.js';
+/**
+ * Requests main parses with LIMITS.largeMessageBytes instead of messageBytes —
+ * their params schemas admit bodies over 1 MB (docs/card-sdk/requests/A-contract-log.md, 2026-09-24).
+ */
+export declare const LARGE_REQUEST_METHODS: ReadonlySet<string>;
+/**
+ * The minimal MessagePort surface the SDK uses. A real `MessagePort` fits;
+ * tests may pass any object with these members.
+ */
+export interface CardPort {
+    postMessage(message: unknown): void;
+    onmessage: ((event: MessageEvent) => void) | null;
+    close(): void;
+    start?(): void;
+}
+/** Per-call options accepted by `card.call()` and most helpers. */
+export interface CallOptions {
+    /** Rejects locally with TIMEOUT after this long (the host may still finish the work). */
+    timeoutMs?: number;
+    /** Rejects with the signal's reason when aborted. */
+    signal?: AbortSignal;
+    /** Skip the local params check against METHOD_SPECS (the host always checks). Default false. */
+    skipValidation?: boolean;
+}
+export type EventSink = (event: string, data: unknown) => void;
+/** @internal RPC over one port. The Card wraps it; authors use `card.call()`. */
+export declare class Channel {
+    private readonly port;
+    private nextId;
+    private readonly pending;
+    private readonly queue;
+    private sink;
+    private early;
+    private closedError;
+    private readonly closeListeners;
+    constructor(port: CardPort);
+    /** True after close() or a fatal error. */
+    get closed(): boolean;
+    /** Where events go. Events that arrive before a sink is set are kept and replayed. */
+    setEventSink(sink: EventSink): void;
+    onClose(listener: (error: CardSdkError) => void): () => void;
+    request(method: string, params: unknown, options?: CallOptions): Promise<unknown>;
+    /** Fire-and-forget request: failures are reported to `onError` (default: ignored). */
+    notify(method: string, params: unknown, onError?: (error: unknown) => void): void;
+    close(reason?: string): void;
+    private pump;
+    private receive;
+}

package/dist/types/client/coalesce.d.ts

@@ -0,0 +1,14 @@
+/** One latest-wins lane per method. */
+export declare class Coalescer<A> {
+    private readonly send;
+    private busy;
+    private next;
+    private timer;
+    private closed;
+    constructor(send: (args: A) => Promise<unknown>);
+    push(args: A): Promise<void>;
+    /** Drops what is waiting (the card is closing); its callers resolve. */
+    cancel(): void;
+    private fire;
+    private drain;
+}

package/dist/types/client/connect.d.ts

@@ -0,0 +1,39 @@
+import { Card, type CardOptions } from './card.js';
+import { type CardPort } from './channel.js';
+/** The bits of `window` the handshake uses — a real window, or a stand-in in tests. */
+export interface HandshakeWindow {
+    readonly parent: unknown;
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+}
+/** Options of {@link connect}. */
+export interface ConnectOptions extends CardOptions {
+    /**
+     * Use this port instead of waiting for the host's handshake — for
+     * `createMockHost()` and custom setups.
+     */
+    port?: CardPort;
+    /** The window to listen on (tests). Default: the global `window`. */
+    window?: HandshakeWindow;
+    /** How long to wait for the host's port, then for `host.ready`. Default 10 000 ms. */
+    timeoutMs?: number;
+}
+/**
+ * Connects the card to NeuroSquad and resolves with the typed {@link Card}.
+ *
+ * Waits for the host to hand over the card's private channel (only the
+ * embedding app can), sends `host.ready`, and applies the app theme to
+ * `<html>` as `--ns-*` variables. Calling it again returns the same card.
+ *
+ * Fails with a {@link CardSdkError}:
+ * - `UNAVAILABLE` when the page is not inside a NeuroSquad card frame (for a
+ *   standalone preview or tests use `createMockHost()` from
+ *   `@neurosquad/card-sdk/testing`);
+ * - `PROTOCOL_MISMATCH` when the app is older than this SDK's protocol.
+ *
+ * @example
+ * import { connect } from '@neurosquad/card-sdk'
+ * const card = await connect()
+ * document.querySelector('h1')!.textContent = card.instance.displayName
+ */
+export declare function connect(options?: ConnectOptions): Promise<Card>;

package/dist/types/client/errors.d.ts

@@ -0,0 +1,46 @@
+import type { CardErrorCode, CardErrorPayload, PermissionId, SchemaIssue } from '../contract/index.js';
+/**
+ * The error every SDK call rejects with when the host refuses a request, or
+ * when the SDK catches a problem before sending it (bad params, a message
+ * over the size limit, a closed connection).
+ *
+ * @example
+ * try {
+ *   await card.agents.prompt(agentId, 'Run the tests')
+ * } catch (error) {
+ *   if (isCardSdkError(error, 'NOT_CONNECTED')) card.ui.toast('Connect me to an agent first')
+ *   else throw error
+ * }
+ */
+export declare class CardSdkError extends Error {
+    /** Machine-readable reason — one of `CARD_ERROR_CODES`. */
+    readonly code: CardErrorCode;
+    /** Extra details from the host (issues for INVALID_PARAMS, `{ permission }`, `{ retryAfterMs }`…). */
+    readonly data: unknown;
+    /** The API method that failed, when the error came from a call. */
+    readonly method: string | undefined;
+    /** The host's own message, without the method prefix and hint. */
+    readonly hostMessage: string;
+    /** A one-line suggestion for the developer, when there is one for this code. */
+    readonly hint: string | undefined;
+    constructor(code: CardErrorCode, message: string, data?: unknown, method?: string);
+    /** Builds the error from a wire error payload. */
+    static fromPayload(payload: CardErrorPayload, method?: string): CardSdkError;
+    /** For RATE_LIMITED: how long to wait before retrying, in ms. */
+    get retryAfterMs(): number | undefined;
+    /** For PERMISSION_DENIED: the permission that was missing. */
+    get permission(): PermissionId | undefined;
+    /** For INVALID_PARAMS / BAD_REQUEST: where the params did not match the method's schema. */
+    get issues(): SchemaIssue[] | undefined;
+    /** The wire form (`{ code, message, data? }`). */
+    toJSON(): CardErrorPayload;
+}
+/**
+ * Type guard for {@link CardSdkError}, optionally for one code.
+ *
+ * @example
+ * if (isCardSdkError(error, 'RATE_LIMITED')) await sleep(error.retryAfterMs ?? 1000)
+ */
+export declare function isCardSdkError(error: unknown, code?: CardErrorCode): error is CardSdkError;
+/** Short text of anything thrown, for logs and error replies. */
+export declare function describeError(error: unknown): string;

package/dist/types/client/helpers.d.ts

@@ -0,0 +1,25 @@
+import { type PeerInfo, type PermissionId, type PortTypeId } from '../contract/index.js';
+import type { Card } from './card.js';
+/** True when at least one arrow goes from this card to another (something can receive an emit). */
+export declare function hasDownstreamPeer(peers: readonly PeerInfo[]): boolean;
+/**
+ * The permission this card needs to send to `peer`: the permission of the
+ * input `input` (by id), or of the input an output of type `outputType`
+ * would land on, or of the peer's default input. `null` when none is needed
+ * (custom cards) or the peer has no such input.
+ */
+export declare function permissionForPeer(peer: PeerInfo, target?: {
+    input?: string;
+    outputType?: PortTypeId;
+}): PermissionId | null;
+/**
+ * Asks for the optional permissions not granted yet and resolves with the
+ * ids from `ids` that are usable now. Never throws: a refusal, a card that is
+ * not on screen (NOT_VISIBLE) or a closed connection all resolve with what
+ * is granted already.
+ *
+ * @example
+ * if ((await requestPermissions(card, 'cards.connected')).includes('cards.connected'))
+ *   await card.ports.emit('summary', text)
+ */
+export declare function requestPermissions(card: Card, ...ids: PermissionId[]): Promise<PermissionId[]>;

package/dist/types/client/net.d.ts

@@ -0,0 +1,111 @@
+import type { CardEvents, JsonValue, NetResponse } from '../contract/index.js';
+/** How the host returns the body. `stream` resolves at headers and delivers chunks as they arrive. */
+export type NetResponseType = 'text' | 'json' | 'base64' | 'stream';
+/** Options of {@link CardNet.fetch}, modelled on `RequestInit`. */
+export interface CardFetchInit {
+    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /**
+     * Request headers. Values may contain `{{secret:<key>}}` — main substitutes
+     * the card's secret setting of that key (the card never sees the value).
+     */
+    headers?: Record<string, string> | Iterable<readonly [string, string]>;
+    /**
+     * A string is sent as is; bytes (`Uint8Array`, `ArrayBuffer`) are sent as
+     * binary; any other JSON value is serialized and gets
+     * `content-type: application/json` unless you set one.
+     */
+    body?: string | ArrayBuffer | ArrayBufferView | JsonValue;
+    /**
+     * `text` (default), `json` (parsed by the host; > 10 MB fails with TOO_LARGE),
+     * `base64` (binary), or `stream` (chunks as they arrive — SSE, NDJSON, long downloads).
+     */
+    responseType?: NetResponseType;
+    /** Default 30 000, max 120 000. */
+    timeoutMs?: number;
+    /** Aborting cancels the request in the host (`net.abort`). */
+    signal?: AbortSignal;
+}
+/** Read-only response headers (names lowercased; `set-cookie` is never returned). */
+export declare class CardHeaders implements Iterable<[string, string]> {
+    private readonly map;
+    constructor(headers: Record<string, string>);
+    /** The value of a header, case-insensitive, or null. */
+    get(name: string): string | null;
+    has(name: string): boolean;
+    forEach(callback: (value: string, name: string) => void): void;
+    entries(): IterableIterator<[string, string]>;
+    [Symbol.iterator](): IterableIterator<[string, string]>;
+    /** A plain object copy. */
+    toJSON(): Record<string, string>;
+}
+type Chunk = CardEvents['net.chunk'];
+/** @internal Collects `net.chunk` events of one streamed request. */
+export declare class ChunkQueue {
+    private readonly items;
+    private waiter;
+    private finished;
+    private failure;
+    push(chunk: Chunk): void;
+    fail(error: Error): void;
+    drain(): AsyncGenerator<Chunk>;
+    private wake;
+}
+/**
+ * The result of `card.net.fetch()`: the familiar parts of `Response`.
+ *
+ * @example
+ * const res = await card.net.fetch('https://api.github.com/repos/acme/app/issues')
+ * if (!res.ok) throw new Error(`GitHub said ${res.status}`)
+ * const issues = await res.json<{ title: string }[]>()
+ *
+ * @example Streaming (server-sent events)
+ * const res = await card.net.fetch(url, { responseType: 'stream' })
+ * for await (const line of res.lines()) if (line.startsWith('data: ')) render(line.slice(6))
+ */
+export declare class CardResponse {
+    private readonly raw;
+    private readonly stream;
+    /** HTTP status code. */
+    readonly status: number;
+    readonly statusText: string;
+    /** `status` in 200–299. */
+    readonly ok: boolean;
+    /** Final URL after redirects. */
+    readonly url: string;
+    readonly headers: CardHeaders;
+    /** The body was longer than the limit and was cut (text/base64 only). */
+    readonly truncated: boolean;
+    /** The id `net.abort` and stream chunks use. */
+    readonly requestId: string;
+    /** How the body was requested. */
+    readonly type: NetResponseType;
+    private used;
+    /** @internal */
+    constructor(raw: NetResponse, type: NetResponseType, stream: ChunkQueue | null);
+    /** True once a body method was called (a body can be read once, like `Response`). */
+    get bodyUsed(): boolean;
+    /** The body as text (base64 bodies are decoded as UTF-8). */
+    text(): Promise<string>;
+    /** The body parsed as JSON. Throws a SyntaxError for a body that is not JSON. */
+    json<T = JsonValue>(): Promise<T>;
+    /** The body as bytes. */
+    bytes(): Promise<Uint8Array>;
+    /** The body as an ArrayBuffer. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * Chunks of a `responseType: 'stream'` response as they arrive: strings for
+     * text chunks, `Uint8Array` for binary ones. Ends when the host sends the
+     * last chunk; throws a CardSdkError (NETWORK_ERROR) if the stream fails.
+     */
+    chunks(): AsyncGenerator<string | Uint8Array>;
+    /** Lines of the body (`\n` or `\r\n`), streamed when the response is a stream. */
+    lines(): AsyncGenerator<string>;
+    /** Same as {@link chunks}: `for await (const chunk of response)`. */
+    [Symbol.asyncIterator](): AsyncGenerator<string | Uint8Array>;
+    private consume;
+}
+/** @internal Converts init into net.fetch params. */
+export declare function fetchParams(url: string, init: CardFetchInit, requestId: string): Record<string, JsonValue>;
+/** @internal Unique enough request ids for net.fetch. */
+export declare function newRequestId(): string;
+export {};

package/dist/types/client/theme.d.ts

@@ -0,0 +1,31 @@
+import { type ThemeSnapshot } from '../contract/index.js';
+/** Anything with an inline style — `document.documentElement` by default. */
+export interface ThemeTarget {
+    style: {
+        setProperty(name: string, value: string): void;
+        colorScheme?: string;
+    };
+    dataset?: Record<string, string | undefined>;
+}
+/**
+ * Writes the app's theme onto an element as CSS variables, so a card can look
+ * native without guessing colours:
+ *
+ * - `--ns-<token>` for every {@link THEME_TOKENS} entry (`--ns-accent`, `--ns-surface`, `--ns-radius`…)
+ * - `--ns-font-sans`, `--ns-font-mono`
+ * - `color-scheme` and `data-ns-scheme="dark|light"`
+ *
+ * `connect()` calls it for you on start and on every `theme.changed` (pass
+ * `{ theme: false }` to opt out). The optional `ui.css` kit reads these
+ * variables.
+ *
+ * @param theme The snapshot from `card.context.theme`, `card.theme.get()` or a `theme.changed` event.
+ * @param target Where to write the variables. Default: `document.documentElement`.
+ */
+export declare function applyTheme(theme: ThemeSnapshot, target?: ThemeTarget): void;
+/**
+ * The app's dark theme as it ships (HeroUI v3 dark tokens, resolved). Used by
+ * the mock host and as the fallback values baked into `ui.css`; a live card
+ * always gets the real computed values from the host.
+ */
+export declare const DEFAULT_DARK_THEME: ThemeSnapshot;

package/dist/types/client/toolResult.d.ts

@@ -0,0 +1,16 @@
+import type { ToolResultPayload } from '../contract/index.js';
+/** A text tool result. Same as returning the string from a tool handler. */
+export declare function toolText(text: string): ToolResultPayload;
+/**
+ * An image tool result (base64 data), optionally with a caption.
+ *
+ * @example
+ * return toolImage(bytesToBase64(png), 'image/png', 'Current chart')
+ */
+export declare function toolImage(data: string, mimeType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif', caption?: string): ToolResultPayload;
+/**
+ * A result the agent sees as a failed tool call (`isError: true`) — for
+ * expected failures you want to explain to the model. Throwing from a
+ * handler does the same with the error's message.
+ */
+export declare function toolError(message: string): ToolResultPayload;