@relaymessenger/sdk 0.3.6-staging.5 → 0.3.6-staging.51

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":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,wBAAwB,EACxB,WAAW,EACX,yBAAyB,EACzB,QAAQ,EACR,cAAc,EAEd,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,kEAAkE;AAClE,eAAO,MAAM,eAAe,0BAA0B,CAAC;AAEvD,kEAAkE;AAClE,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,oEAAoE,CAAC;AAEvG,wGAAwG;AACxG,eAAO,MAAM,qBAAqB,wCAAwC,CAAC;AAE3E;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;;;;CAIyB,CAAC;AAE3D,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,IAAI,IAAI,qBACO,CAAC;AAEnE,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,oBAAoB,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC;AAE7E,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,GAAI,MAAM,eAAe,EAAE,WAAW,KAAG,oBACjC,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,MAAM,EAAE,MAAM,eAAe,KAAG,yBACuB,CAAC;AAEzG;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,WAAW,MAAM,EACjB,MAAM,eAAe,EACrB,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAClC,yBAAyB,EAO3B,CAAC;AAEF,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,2GAA2G;IAC3G,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,KAAK,CAAC,EAAE,wBAAwB,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC;IAC3D,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAChD;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,4CAA4C;AAC5C,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,kEAAkE;AAClE,eAAO,MAAM,QAAQ,GAAI,UAAU,WAAW,EAAE,KAAG,QAIjD,CAAC;AAeH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,EAC5B,QAAQ,MAAM,EACd,SAAS,WAAW,EACpB,UAAU,eAAe,EACzB,UAAU,cAAc,KACvB,OAAO,CAAC,mBAAmB,CAkB7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,EAC5B,QAAQ,MAAM,EACd,WAAW,MAAM,EACjB,QAAQ,iBAAiB,EACzB,UAAU,eAAe,EACzB,UAAU,cAAc,KACvB,OAAO,CAAC,mBAAmB,CAU7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,EAC5B,QAAQ,MAAM,EACd,WAAW,MAAM,EACjB,UAAU,eAAe,EACzB,UAAU,cAAc,KACvB,OAAO,CAAC,mBAAmB,CACqE,CAAC;AAEpG;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,iBAAiB,GAAG,kBAAkB,KAC5C,OAAO,GAAG,IAkBZ,CAAC"}

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/buttons.d.ts

@@ -17,7 +17,12 @@ export declare const BUTTONS_FENCE = "buttons";
  * ("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).
+ * 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;
 /**
@@ -42,7 +47,7 @@ export interface SplitButtons {
  * 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, oneTime?: boolean) => ButtonsPart | string;
+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;
 /**

package/dist/buttons.d.ts.map

@@ -1 +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;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,QAOlB,CAAC;AAEZ;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAI8F,CAAC;AAErI,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,EAAE,UAAU,OAAO,KAAG,WAAW,GAAG,MAmB9E,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"}
+{"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

@@ -16,15 +16,21 @@ export const BUTTONS_FENCE = "buttons";
  * ("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).
+ * 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 opens it inside the app: connect an account, sign in, open the page, pay. A plain button confirms one step: Start, Done, Continue. Do not paste a link or ask \"ready?\" when a single button does the job.",
+    "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\", list choices for the person to type, or paste a link for them to open, send buttons instead. If the person asks for buttons, send them.",
+    "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. Set one_time to false only for controls the person is meant to tap again and again, such as Next, Another one, or Refresh.",
+    "Buttons disappear once tapped.",
 ].join(" ");
 /**
  * How a text-only agent puts buttons under its answer: the same words for
@@ -32,8 +38,7 @@ export const BUTTONS_GUIDANCE = [
  */
 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. "
-    + "To keep the buttons on screen after a tap, write the block as {\"one_time\": false, \"items\": [...]} instead of a bare array.";
+    + "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;
@@ -73,16 +78,13 @@ const asItem = (value, index) => {
  * 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, oneTime) => {
+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";
-    const one_time = oneTime ?? wrapped?.one_time;
-    if (one_time !== undefined && typeof one_time !== "boolean")
-        return "one_time must be true or false";
     if (items.length === 0)
         return "the buttons block has no items";
     if (items.length > BUTTONS_MAX_ITEMS) {
@@ -95,7 +97,7 @@ export const buttonsPart = (parsed, oneTime) => {
             return item;
         result.push(item);
     }
-    return { type: "buttons", items: result, ...(one_time === undefined ? {} : { one_time }) };
+    return { type: "buttons", items: result };
 };
 /** Parses the body of a buttons block, JSON, into a `buttons` part. */
 export const parseButtonsBlock = (body) => {

package/dist/buttons.js.map

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