@relaymessenger/sdk 0.3.6-staging.9 → 0.3.7-staging.0

package/dist/a2ui.d.ts

@@ -0,0 +1,111 @@
+import type { Relay } from "./client.js";
+import type { A2uiAction, A2uiBrowserActionName, A2uiBrowserComponent, A2uiComponent, A2uiCreateSurfaceMessage, A2uiMessage, A2uiServerToClientMessage, DataPart, MessageContent, MessageSendResponse, MessageWebhookData, RelayWebhookEvent, RequestOptions } from "./types.js";
+/** The `media_type` of a data part that carries A2UI messages. */
+export declare const A2UI_MEDIA_TYPE = "application/a2ui+json";
+/** The A2UI version every message these helpers write carries. */
+export declare const A2UI_VERSION = "v0.9.1";
+/** A2UI v0.9.1's basic catalog, by the `catalogId` its catalog file declares. */
+export declare const A2UI_BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json";
+/** Relay's catalog: every basic catalog component and function, plus `PaymentRequest` and `Browser`. */
+export declare const RELAY_A2UI_CATALOG_ID = "https://relayapp.im/a2ui/catalog/v1";
+/**
+ * The taps a Browser card sends to the agent that created it, as an A2UI
+ * `action` whose `sourceComponentId` is the Browser's id and whose `context`
+ * is empty: "Take control of the browser", "Finish up" and "Stop the task".
+ * Pause your browser work from `takeControl` until `returnControl`; end the
+ * task on `stop`.
+ */
+export declare const A2UI_BROWSER_ACTIONS: {
+    readonly takeControl: "browser.takeControl";
+    readonly returnControl: "browser.returnControl";
+    readonly stop: "browser.stop";
+};
+/** Whether a tap's `name` is one of a Browser card's taps. */
+export declare const isA2uiBrowserAction: (name: string) => name is A2uiBrowserActionName;
+/** A Browser card's properties: everything but `id` and `component`. */
+export type A2uiBrowserCard = Omit<A2uiBrowserComponent, "id" | "component">;
+/** The Browser component a card draws, with the id `root` unless another is given. */
+export declare const a2uiBrowserComponent: (card: A2uiBrowserCard, id?: string) => A2uiBrowserComponent;
+/**
+ * The A2UI message that changes a Browser card in place: `updateComponents`
+ * replaces the whole component by id, so `card` is the card as it should now
+ * be drawn, for example `{ ...card, state: "needs_you", status: "Blocked ·
+ * Waiting for confirmation" }`. A bound property changes with
+ * `updateA2uiSurface`'s `dataModel` instead.
+ */
+export declare const a2uiBrowserCardUpdate: (surfaceId: string, card: A2uiBrowserCard) => A2uiServerToClientMessage;
+/**
+ * The A2UI messages of a new Browser card in Relay's catalog: `createSurface`,
+ * then `updateComponents` with the Browser as `root`, then, when `dataModel`
+ * is given (for bound properties), `updateDataModel` for the whole model.
+ */
+export declare const a2uiBrowserCardMessages: (surfaceId: string, card: A2uiBrowserCard, dataModel?: Record<string, unknown>) => A2uiServerToClientMessage[];
+/** A card: the surface to create, its components, and, optionally, its first data model. */
+export interface A2uiSurface {
+    surfaceId: string;
+    /** A catalog Relay draws: `A2UI_BASIC_CATALOG_ID` or `RELAY_A2UI_CATALOG_ID`. */
+    catalogId: string;
+    /** Every component of the card; one has the id `root`. The catalog defines each component and property. */
+    components: A2uiComponent[];
+    /** The whole data model, sent as an `updateDataModel` with no `path`. */
+    dataModel?: Record<string, unknown>;
+    theme?: A2uiCreateSurfaceMessage["createSurface"]["theme"];
+    sendDataModel?: boolean;
+}
+/**
+ * A change to a card that is already in the chat: components to add or
+ * replace by id, and a data model value to set at `path` (a JSON Pointer; no
+ * `path` is the whole data model; no `value` removes the key at `path`).
+ */
+export interface A2uiSurfaceUpdate {
+    components?: A2uiComponent[];
+    dataModel?: {
+        path?: string;
+        value?: unknown;
+    };
+}
+/**
+ * The rest of the Message beside the data part. `text` becomes a text part
+ * before it; the chat list and notification show it. With no text, they show
+ * the card's first `Text` component. A text beside an update is a new Message,
+ * and the update still changes the card in place.
+ */
+export type A2uiSendOptions = Omit<MessageContent, "parts"> & {
+    text?: string;
+};
+/** A tap read out of `message.received`. */
+export interface A2uiTap {
+    action: A2uiAction;
+    /** The tapped surface's data model, present when the surface set `sendDataModel`. */
+    dataModel?: Record<string, unknown>;
+}
+/** Wraps A2UI messages in the data part Relay carries them in. */
+export declare const a2uiPart: (messages: A2uiMessage[]) => DataPart;
+/**
+ * Sends a new card into a chat: `createSurface`, `updateComponents` and, when
+ * `dataModel` is given, `updateDataModel`, in one data part. Messages Relay
+ * could not apply come back in `a2ui_errors` (`A2uiFailure`); a send it could
+ * not apply at all throws a `RelayAPIError` whose `body.a2ui_errors` lists each.
+ */
+export declare const sendA2uiSurface: (client: Pick<Relay, "chats">, chatID: string, surface: A2uiSurface, message?: A2uiSendOptions, options?: RequestOptions) => Promise<MessageSendResponse>;
+/**
+ * Changes a card already in the chat, in place, for every member. With no
+ * `text`, the send adds no Message and returns the card's own Message. Any
+ * agent in the chat may update any surface in it.
+ */
+export declare const updateA2uiSurface: (client: Pick<Relay, "chats">, chatID: string, surfaceId: string, update: A2uiSurfaceUpdate, message?: A2uiSendOptions, options?: RequestOptions) => Promise<MessageSendResponse>;
+/**
+ * Removes a card for everyone. When every surface a Message draws is deleted,
+ * the Message reads back with no parts and a non-null `unsent_at`. The
+ * `surfaceId` may be created again afterwards.
+ */
+export declare const deleteA2uiSurface: (client: Pick<Relay, "chats">, chatID: string, surfaceId: string, message?: A2uiSendOptions, options?: RequestOptions) => Promise<MessageSendResponse>;
+/**
+ * Reads the first A2UI `action` out of a `message.received` event (a signed
+ * webhook or a WebSocket event), or out of its `data`. Returns null for any
+ * other event and for a Message that carries no tap. When the surface set
+ * `sendDataModel`, `dataModel` is that surface's model from
+ * `metadata.a2uiClientDataModel`.
+ */
+export declare const readA2uiAction: (event: RelayWebhookEvent | MessageWebhookData) => A2uiTap | null;
+//# sourceMappingURL=a2ui.d.ts.map

package/dist/a2ui.d.ts.map

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

package/dist/a2ui.js

@@ -0,0 +1,137 @@
+/** The `media_type` of a data part that carries A2UI messages. */
+export const A2UI_MEDIA_TYPE = "application/a2ui+json";
+/** The A2UI version every message these helpers write carries. */
+export const A2UI_VERSION = "v0.9.1";
+/** A2UI v0.9.1's basic catalog, by the `catalogId` its catalog file declares. */
+export const A2UI_BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json";
+/** Relay's catalog: every basic catalog component and function, plus `PaymentRequest` and `Browser`. */
+export const RELAY_A2UI_CATALOG_ID = "https://relayapp.im/a2ui/catalog/v1";
+/**
+ * The taps a Browser card sends to the agent that created it, as an A2UI
+ * `action` whose `sourceComponentId` is the Browser's id and whose `context`
+ * is empty: "Take control of the browser", "Finish up" and "Stop the task".
+ * Pause your browser work from `takeControl` until `returnControl`; end the
+ * task on `stop`.
+ */
+export const A2UI_BROWSER_ACTIONS = {
+    takeControl: "browser.takeControl",
+    returnControl: "browser.returnControl",
+    stop: "browser.stop",
+};
+/** Whether a tap's `name` is one of a Browser card's taps. */
+export const isA2uiBrowserAction = (name) => Object.values(A2UI_BROWSER_ACTIONS).includes(name);
+/** The Browser component a card draws, with the id `root` unless another is given. */
+export const a2uiBrowserComponent = (card, id = "root") => ({ id, component: "Browser", ...card });
+/**
+ * The A2UI message that changes a Browser card in place: `updateComponents`
+ * replaces the whole component by id, so `card` is the card as it should now
+ * be drawn, for example `{ ...card, state: "needs_you", status: "Blocked ·
+ * Waiting for confirmation" }`. A bound property changes with
+ * `updateA2uiSurface`'s `dataModel` instead.
+ */
+export const a2uiBrowserCardUpdate = (surfaceId, card) => ({ version: A2UI_VERSION, updateComponents: { surfaceId, components: [a2uiBrowserComponent(card)] } });
+/**
+ * The A2UI messages of a new Browser card in Relay's catalog: `createSurface`,
+ * then `updateComponents` with the Browser as `root`, then, when `dataModel`
+ * is given (for bound properties), `updateDataModel` for the whole model.
+ */
+export const a2uiBrowserCardMessages = (surfaceId, card, dataModel) => {
+    const messages = [
+        { version: A2UI_VERSION, createSurface: { surfaceId, catalogId: RELAY_A2UI_CATALOG_ID } },
+        a2uiBrowserCardUpdate(surfaceId, card),
+    ];
+    if (dataModel !== undefined)
+        messages.push({ version: A2UI_VERSION, updateDataModel: { surfaceId, value: dataModel } });
+    return messages;
+};
+/** Wraps A2UI messages in the data part Relay carries them in. */
+export const a2uiPart = (messages) => ({
+    type: "data",
+    media_type: A2UI_MEDIA_TYPE,
+    data: messages,
+});
+const send = (client, chatID, messages, { text, ...message } = {}, options) => {
+    const parts = text === undefined
+        ? [a2uiPart(messages)]
+        : [{ type: "text", value: text }, a2uiPart(messages)];
+    return client.chats.messages.send(chatID, { message: { ...message, parts } }, options);
+};
+/**
+ * Sends a new card into a chat: `createSurface`, `updateComponents` and, when
+ * `dataModel` is given, `updateDataModel`, in one data part. Messages Relay
+ * could not apply come back in `a2ui_errors` (`A2uiFailure`); a send it could
+ * not apply at all throws a `RelayAPIError` whose `body.a2ui_errors` lists each.
+ */
+export const sendA2uiSurface = (client, chatID, surface, message, options) => {
+    const { surfaceId, catalogId, components, dataModel, theme, sendDataModel } = surface;
+    const messages = [
+        {
+            version: A2UI_VERSION,
+            createSurface: {
+                surfaceId,
+                catalogId,
+                ...(theme === undefined ? {} : { theme }),
+                ...(sendDataModel === undefined ? {} : { sendDataModel }),
+            },
+        },
+        { version: A2UI_VERSION, updateComponents: { surfaceId, components } },
+    ];
+    if (dataModel !== undefined) {
+        messages.push({ version: A2UI_VERSION, updateDataModel: { surfaceId, value: dataModel } });
+    }
+    return send(client, chatID, messages, message, options);
+};
+/**
+ * Changes a card already in the chat, in place, for every member. With no
+ * `text`, the send adds no Message and returns the card's own Message. Any
+ * agent in the chat may update any surface in it.
+ */
+export const updateA2uiSurface = (client, chatID, surfaceId, update, message, options) => {
+    const messages = [];
+    if (update.components !== undefined) {
+        messages.push({ version: A2UI_VERSION, updateComponents: { surfaceId, components: update.components } });
+    }
+    if (update.dataModel !== undefined) {
+        messages.push({ version: A2UI_VERSION, updateDataModel: { surfaceId, ...update.dataModel } });
+    }
+    if (!messages.length)
+        throw new Error("an update needs components or a dataModel");
+    return send(client, chatID, messages, message, options);
+};
+/**
+ * Removes a card for everyone. When every surface a Message draws is deleted,
+ * the Message reads back with no parts and a non-null `unsent_at`. The
+ * `surfaceId` may be created again afterwards.
+ */
+export const deleteA2uiSurface = (client, chatID, surfaceId, message, options) => send(client, chatID, [{ version: A2UI_VERSION, deleteSurface: { surfaceId } }], message, options);
+/**
+ * Reads the first A2UI `action` out of a `message.received` event (a signed
+ * webhook or a WebSocket event), or out of its `data`. Returns null for any
+ * other event and for a Message that carries no tap. When the surface set
+ * `sendDataModel`, `dataModel` is that surface's model from
+ * `metadata.a2uiClientDataModel`.
+ */
+export const readA2uiAction = (event) => {
+    let data;
+    if ("event_type" in event) {
+        if (event.event_type !== "message.received")
+            return null;
+        data = event.data;
+    }
+    else {
+        data = event;
+    }
+    for (const part of data.parts ?? []) {
+        if (part.type !== "data" || part.media_type !== A2UI_MEDIA_TYPE)
+            continue;
+        for (const message of part.data) {
+            if (typeof message !== "object" || message === null || !("action" in message))
+                continue;
+            const { action } = message;
+            const dataModel = data.metadata?.a2uiClientDataModel?.surfaces[action.surfaceId];
+            return dataModel === undefined ? { action } : { action, dataModel };
+        }
+    }
+    return null;
+};
+//# sourceMappingURL=a2ui.js.map

package/dist/a2ui.js.map

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

package/dist/calls/call-room.d.ts

@@ -0,0 +1,110 @@
+import type { CallRoomClientFrame, CallRoomEndedFrame, CallRoomErrorFrame, CallRoomIceServer, CallRoomIceServersFrame, CallRoomServerAnswerFrame, CallRoomServerFrame, CallRoomStateFrame, CallRoomSubscriptionOfferFrame } from "../types.js";
+import type { WebSocketConstructor } from "../websocket.js";
+export interface CallRoomOptions {
+    /** Abort closes the signaling socket without ending the Call. */
+    signal?: AbortSignal;
+    /** Override the Node WebSocket implementation, primarily for tests. */
+    WebSocket?: WebSocketConstructor;
+    /** Client heartbeat cadence. Relay's room heartbeat frame has no payload. */
+    heartbeatIntervalMs?: number;
+    /**
+     * Called once per unknown server frame type, which the room ignores.
+     * Defaults to `console.warn`.
+     */
+    onWarning?: (message: string) => void;
+}
+export interface CallRoomCloseEvent {
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+/**
+ * The room socket dropped, or an attempt to open one failed, and the room
+ * opens a new one after `delayMs`. Media rides the SFU, not this socket, so the
+ * Call and its WebRTC session continue; nothing is re-offered.
+ */
+export interface CallRoomReconnectingEvent {
+    /** 1 for the first retry; the count resets once a socket stays open 5 s. */
+    attempt: number;
+    delayMs: number;
+    /** The close that caused the retry; absent when an attempt failed before opening. */
+    close?: CallRoomCloseEvent;
+    /** Why the failed attempt did not open (connect timeout, handshake error). */
+    error?: Error;
+}
+export type CallRoomConnectionState = "idle" | "connecting" | "open" | "reconnecting" | "closed";
+export type CallRoomEventMap = {
+    open: [];
+    reconnecting: [CallRoomReconnectingEvent];
+    /** The room's STUN/TURN servers, sent after every accepted `join`, before its `roomState`. */
+    iceServers: [CallRoomIceServersFrame];
+    roomState: [CallRoomStateFrame];
+    offer: [CallRoomSubscriptionOfferFrame];
+    answer: [CallRoomServerAnswerFrame];
+    ended: [CallRoomEndedFrame];
+    error: [CallRoomErrorFrame | Error];
+    /** The room socket closed and the room will not reopen it by itself. */
+    close: [CallRoomCloseEvent];
+};
+type CallRoomEvent = keyof CallRoomEventMap;
+type Listener<K extends CallRoomEvent> = (...args: CallRoomEventMap[K]) => void;
+/**
+ * Validate one server frame before exposing it to application code. Returns
+ * `null` for Relay's echoed heartbeat (not part of the public server-frame
+ * union) and for a frame type this client does not know (a newer Relay's
+ * frame, ignored). Throws for a known frame type whose shape is invalid.
+ */
+export declare const parseCallRoomServerFrame: (value: unknown) => CallRoomServerFrame | null;
+/**
+ * Authenticated JSON signaling socket for one Relay Call participant.
+ *
+ * The room reopens its socket after any close that neither this client nor the
+ * server asked for, with PartySocket's numbers (PROTOCOL.md section 5): first
+ * retry after 3000 ms, then x1.3, capped at 10000 ms, a 4000 ms connect
+ * timeout, the retry count reset once a socket stays open 5000 ms, and no
+ * retry limit. On every open it sends `join`, then `userUpdate` with the last
+ * muted/video state, then the frames queued while closed. Media is never
+ * re-offered by a socket-only reconnect.
+ */
+export declare class CallRoom {
+    #private;
+    readonly callID: string;
+    readonly url: string;
+    state: CallRoomStateFrame | null;
+    /**
+     * The STUN/TURN servers from the room's latest `iceServers` frame, or `null`
+     * before the first one. Relay sends fresh ones on every join, reconnects
+     * included, so read this again before building each new peer connection.
+     */
+    iceServers: CallRoomIceServer[] | null;
+    constructor(callID: string, baseURL: string, apiKey: string, options?: CallRoomOptions);
+    /** `reconnecting` while the room waits to reopen a dropped socket. */
+    get connectionState(): CallRoomConnectionState;
+    on<K extends CallRoomEvent>(event: K, listener: Listener<K>): this;
+    off<K extends CallRoomEvent>(event: K, listener: Listener<K>): this;
+    /** Resolves on the first open; a failed attempt is retried, not thrown. */
+    connect(): Promise<void>;
+    /**
+     * Open a new signaling socket now, keeping application/WebRTC state alive.
+     * Relay accepts the new authenticated socket before the previous one closes,
+     * so an active Call is not interpreted as having lost its participant. Same
+     * path as the automatic reconnect (PartySocket `reconnect()`: retry count
+     * reset, no delay); if the new socket fails while the old one is still open,
+     * the old one stays and this rejects.
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Send one frame. While the socket is reopening the frame is queued and sent
+     * after `join` on the next open (PartySocket's queue); heartbeats are dropped.
+     */
+    send(frame: CallRoomClientFrame): void;
+    connected(): void;
+    userUpdate(update: {
+        muted: boolean;
+        video?: boolean;
+    }): void;
+    end(): void;
+    close(code?: number, reason?: string): void;
+}
+export {};
+//# sourceMappingURL=call-room.d.ts.map

package/dist/calls/call-room.d.ts.map

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