@relaymessenger/sdk 0.3.6-staging.4 → 0.3.6-staging.41

package/dist/a2ui.js

@@ -0,0 +1,99 @@
+/** 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`. */
+export const RELAY_A2UI_CATALOG_ID = "https://relayapp.im/a2ui/catalog/v1";
+/** 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/buttons.d.ts

@@ -0,0 +1,69 @@
+import type { ButtonsPart } from "./types.js";
+/**
+ * The fence tag a text-only agent uses to put buttons under its answer. The
+ * block body is the `items` array of a `buttons` part, exactly as the API
+ * takes it, so an agent that has read the contract needs nothing else:
+ *
+ * ```buttons
+ * [{"label": "Approve"}, {"label": "Open report", "url": "https://..."}]
+ * ```
+ */
+export declare const BUTTONS_FENCE = "buttons";
+/**
+ * When an agent should send buttons. One text, carried verbatim by every
+ * runtime's tool description or prompt, so a person gets buttons under the
+ * same conditions whichever agent they talk to. The rules are the ones the
+ * messaging platforms give their own business agents: Apple's quick replies
+ * ("avoid expecting customers to type responses that could be handled with a
+ * tap", 2 to 5 options), Google's RCS suggestions ("design for the most
+ * common responses"; never "mimic phone trees"), WhatsApp's reply and
+ * call-to-action buttons (distinct options; one call to action). The line
+ * between a url button and a link is Messenger's ("use URL buttons for tasks
+ * that you want completed on your website (for example, purchases, or
+ * account linking)") and Apple's ("all URLs should be sent as Rich Links";
+ * product pages, support articles, self-serve resources): a task goes on a
+ * button, a thing to look at goes out as a link card.
+ */
+export declare const BUTTONS_GUIDANCE: string;
+/**
+ * How a text-only agent puts buttons under its answer: the same words for
+ * every bridge that sends the agent's final text for it.
+ */
+export declare const BUTTONS_BLOCK_INSTRUCTION: string;
+/** The server's limits (Discord's button limits): items 1..5, label 1..80, url <= 2048. */
+export declare const BUTTONS_MAX_ITEMS = 5;
+export declare const BUTTON_LABEL_MAX_LENGTH = 80;
+export declare const BUTTON_URL_MAX_LENGTH = 2048;
+export interface SplitButtons {
+    /** The answer with the fenced block removed and the edges trimmed. */
+    text: string;
+    /** The buttons part the block described, when there was a valid one. */
+    buttons?: ButtonsPart;
+    /** Why a block that was there could not be used. The text then keeps it. */
+    error?: string;
+}
+/**
+ * Turns a decoded value, an array of items or a whole part, into a `buttons`
+ * part, or explains why it cannot. The checks are the server's own, so a bad
+ * value fails here with a readable reason instead of a 400 from the API.
+ */
+export declare const buttonsPart: (parsed: unknown) => ButtonsPart | string;
+/** Parses the body of a buttons block, JSON, into a `buttons` part. */
+export declare const parseButtonsBlock: (body: string) => ButtonsPart | string;
+/**
+ * Lifts the first ```buttons block out of an agent's answer. The text around
+ * it becomes the text part; the block becomes the buttons part. When the
+ * block is malformed, the answer is returned untouched with `error` set, so
+ * the person still gets the words and the operator sees why.
+ */
+export declare const splitButtons: (answer: string) => SplitButtons;
+/**
+ * The parts a text answer with optional buttons becomes: the text first, when
+ * there is any, then the buttons. A buttons-only message is one the server
+ * accepts, so an answer that is nothing but the block sends just the buttons.
+ */
+export declare const partsWithButtons: (text: string, buttons: ButtonsPart | undefined, limit?: number) => Array<{
+    type: "text";
+    value: string;
+} | ButtonsPart>;
+//# sourceMappingURL=buttons.d.ts.map

package/dist/buttons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buttons.d.ts","sourceRoot":"","sources":["../src/buttons.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,QAQlB,CAAC;AAEZ;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAGwB,CAAC;AAE/D,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAgCD;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,OAAO,KAAG,WAAW,GAAG,MAiB3D,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,WAAW,GAAG,MAQ9D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,KAAG,YAU7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,MAAM,EACZ,SAAS,WAAW,GAAG,SAAS,EAChC,cAAgC,KAC/B,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAGrD,CAAC"}

package/dist/buttons.js

@@ -0,0 +1,141 @@
+/**
+ * The fence tag a text-only agent uses to put buttons under its answer. The
+ * block body is the `items` array of a `buttons` part, exactly as the API
+ * takes it, so an agent that has read the contract needs nothing else:
+ *
+ * ```buttons
+ * [{"label": "Approve"}, {"label": "Open report", "url": "https://..."}]
+ * ```
+ */
+export const BUTTONS_FENCE = "buttons";
+/**
+ * When an agent should send buttons. One text, carried verbatim by every
+ * runtime's tool description or prompt, so a person gets buttons under the
+ * same conditions whichever agent they talk to. The rules are the ones the
+ * messaging platforms give their own business agents: Apple's quick replies
+ * ("avoid expecting customers to type responses that could be handled with a
+ * tap", 2 to 5 options), Google's RCS suggestions ("design for the most
+ * common responses"; never "mimic phone trees"), WhatsApp's reply and
+ * call-to-action buttons (distinct options; one call to action). The line
+ * between a url button and a link is Messenger's ("use URL buttons for tasks
+ * that you want completed on your website (for example, purchases, or
+ * account linking)") and Apple's ("all URLs should be sent as Rich Links";
+ * product pages, support articles, self-serve resources): a task goes on a
+ * button, a thing to look at goes out as a link card.
+ */
+export const BUTTONS_GUIDANCE = [
+    "Send buttons when your message ends with a question the person can answer by picking one of 2 to 5 short options you already know: yes or no, choosing between things you named, picking a next step, or a multiple-choice question in a quiz. Each label is a complete answer, so a tap replaces typing. Put the question in text beside the buttons.",
+    "Send one button when there is one thing to do next. A url button is for a task the person completes on a web page: pay, sign in, connect an account, open their booking or order, track a package. Its label names the action, not the site. A plain button confirms one step: Start, Done, Continue. Do not ask \"ready?\" when a single button does the job.",
+    "A link is for something the person will look at or read: an article, a listing, a video, a place, a product page, a support article. Send it as a link on its own, so it draws as a card with the page's title and image; never paste a bare URL into your words, and send one link per message. When the page is where the person does something, send a url button; when the page is the thing you are showing them, send a link.",
+    "Do not send buttons when the answer is open-ended, when your options are not the full set of likely answers, or when you are not asking anything and there is nothing to do. One question or one action per message; never a menu of things you can do, and never as decoration.",
+    "If you would otherwise write \"reply 1, 2 or 3\" or list choices for the person to type, send buttons instead. If the person asks for buttons, send them.",
+    "A tap comes back to you as an ordinary message whose text is the label. Labels are at most 80 characters.",
+    "Buttons disappear once tapped.",
+].join(" ");
+/**
+ * How a text-only agent puts buttons under its answer: the same words for
+ * every bridge that sends the agent's final text for it.
+ */
+export const BUTTONS_BLOCK_INSTRUCTION = "To put buttons under your answer, end it with a fenced code block tagged `" + BUTTONS_FENCE + "` "
+    + "holding a JSON array of 1 to 5 items, each {\"label\": \"...\"} or {\"label\": \"...\", \"url\": \"https://...\"}. "
+    + "The block is removed from the text and drawn as buttons.";
+/** The server's limits (Discord's button limits): items 1..5, label 1..80, url <= 2048. */
+export const BUTTONS_MAX_ITEMS = 5;
+export const BUTTON_LABEL_MAX_LENGTH = 80;
+export const BUTTON_URL_MAX_LENGTH = 2_048;
+const FENCE = new RegExp("(^|\\n)[ \\t]*```[ \\t]*" + BUTTONS_FENCE + "[ \\t]*\\r?\\n([\\s\\S]*?)\\r?\\n[ \\t]*```[ \\t]*(?=\\r?\\n|$)", "u");
+const asItem = (value, index) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return `item ${index + 1} is not an object`;
+    }
+    const record = value;
+    const keys = Object.keys(record).filter((key) => key !== "label" && key !== "url");
+    if (keys.length > 0)
+        return `item ${index + 1} has unknown field ${keys[0]}`;
+    const { label, url } = record;
+    if (typeof label !== "string" || label.length === 0)
+        return `item ${index + 1} needs a label`;
+    if (label.length > BUTTON_LABEL_MAX_LENGTH) {
+        return `item ${index + 1} label is over ${BUTTON_LABEL_MAX_LENGTH} characters`;
+    }
+    if (url === undefined)
+        return { label };
+    if (typeof url !== "string" || url.length > BUTTON_URL_MAX_LENGTH) {
+        return `item ${index + 1} url is not a string of at most ${BUTTON_URL_MAX_LENGTH} characters`;
+    }
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+            throw new Error();
+    }
+    catch {
+        return `item ${index + 1} url is not an http(s) URL`;
+    }
+    return { url, label };
+};
+/**
+ * Turns a decoded value, an array of items or a whole part, into a `buttons`
+ * part, or explains why it cannot. The checks are the server's own, so a bad
+ * value fails here with a readable reason instead of a 400 from the API.
+ */
+export const buttonsPart = (parsed) => {
+    const wrapped = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed
+        : undefined;
+    const items = Array.isArray(parsed) ? parsed : Array.isArray(wrapped?.items) ? wrapped.items : undefined;
+    if (items === undefined)
+        return "the buttons block must be a JSON array of items";
+    if (items.length === 0)
+        return "the buttons block has no items";
+    if (items.length > BUTTONS_MAX_ITEMS) {
+        return `the buttons block has ${items.length} items; the most is ${BUTTONS_MAX_ITEMS}`;
+    }
+    const result = [];
+    for (const [index, value] of items.entries()) {
+        const item = asItem(value, index);
+        if (typeof item === "string")
+            return item;
+        result.push(item);
+    }
+    return { type: "buttons", items: result };
+};
+/** Parses the body of a buttons block, JSON, into a `buttons` part. */
+export const parseButtonsBlock = (body) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return "the buttons block is not valid JSON";
+    }
+    return buttonsPart(parsed);
+};
+/**
+ * Lifts the first ```buttons block out of an agent's answer. The text around
+ * it becomes the text part; the block becomes the buttons part. When the
+ * block is malformed, the answer is returned untouched with `error` set, so
+ * the person still gets the words and the operator sees why.
+ */
+export const splitButtons = (answer) => {
+    const match = FENCE.exec(answer);
+    if (!match)
+        return { text: answer };
+    const parsed = parseButtonsBlock(match[2] ?? "");
+    if (typeof parsed === "string")
+        return { text: answer, error: parsed };
+    const start = match.index + (match[1]?.length ?? 0);
+    const before = answer.slice(0, start).replace(/\s+$/u, "");
+    const after = answer.slice(match.index + match[0].length).replace(/^\s+/u, "");
+    const text = before && after ? `${before}\n\n${after}` : before || after;
+    return { text, buttons: parsed };
+};
+/**
+ * The parts a text answer with optional buttons becomes: the text first, when
+ * there is any, then the buttons. A buttons-only message is one the server
+ * accepts, so an answer that is nothing but the block sends just the buttons.
+ */
+export const partsWithButtons = (text, buttons, limit = Number.POSITIVE_INFINITY) => [
+    ...(text.length > 0 ? [{ type: "text", value: text.slice(0, limit) }] : []),
+    ...(buttons ? [buttons] : []),
+];
+//# sourceMappingURL=buttons.js.map

package/dist/buttons.js.map

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