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

package/README.md

@@ -182,25 +182,45 @@ Calls join one user and one agent in an existing individual Chat. Use
 `relay.calls.create(chatId, { to: [handle], mode: "audio" }, { idempotencyKey })`;
 keep the same key and body when retrying an uncertain create response.
 
-`relay.calls` also exposes `retrieve`, `list`, `accept`, `decline`, `end`, and
-`connected`. Receive typed `call.created`, `call.updated`, and `call.ended`
-events through the existing signed Webhook or Agent WebSocket.
-
-After accepting a Call, an agent creates its audio connection with
-`relay.calls.connections.create(callId, { transport: "websocket" })`.
-The returned `connection.url` and short-lived `connection.token` belong to
-that Call's media socket. Connect using `Authorization: Bearer <token>`.
-They do not replace the Agent Token used for REST requests.
-
-Media uses raw PCM16 little-endian, 48 kHz stereo binary frames. The server
-sends JSON `start` with the format, then `ready`. Send `{"type":"clear"}` to
-discard unsent speech. An `ended` frame terminates the media socket. This
-socket is separate from `relay.websocket.run`, which carries durable events.
-
-WebRTC clients use the same `connections.create` resource with an SDP offer
-and microphone MID, then `connections.subscribe` and
-`connections.renegotiate`. The SDK exposes no media-provider credentials,
-session IDs, model configuration, or audio generation.
+`relay.calls` also exposes `retrieve`, `list`, `accept`, `decline`, and `end`.
+Receive typed `call.created`, `call.updated`, and `call.ended` events through
+the existing signed Webhook or Agent WebSocket.
+
+Every participant holds one socket to the Call room. `relay.calls.room(callId)`
+opens `GET /v1/calls/{callId}/room` with the same bearer as every REST route,
+sends `join`, and keeps `room.state` at the latest `roomState` the room pushed
+after every change. Nothing is polled.
+
+```ts
+const room = relay.calls.room(event.data.call.id);
+room.on("roomState", ({ call, participants, media }) => {
+  // `media` (the audio-socket url and short-lived token) is present only on
+  // the agent's own socket. Open it, then accept.
+  if (call.status === "ringing" && media) room.accept();
+});
+room.on("offer", ({ session_description, track }) => {
+  // The room started pulling the other side's track; answer it.
+  room.send({ type: "answer", session_description: { type: "answer", sdp } });
+});
+room.on("ended", ({ reason }) => { /* the socket closes right after */ });
+room.connected();
+room.userUpdate({ muted: true });
+room.end();
+```
+
+`room.send(frame)` takes any client frame from the contract (`join`, `offer`,
+`answer`, `userUpdate`, `accept`, `decline`, `end`, `connected`, `heartbeat`);
+`accept()`, `decline()`, `end()`, `connected()` and `userUpdate()` send the
+matching frame. The client sends `heartbeat` every 15 s until `close()`. An
+invalid room frame closes the socket 4400 and fires `error`.
+
+The agent's audio flows on the media socket named in `roomState.media`, with
+`Authorization: Bearer <media.token>`: raw PCM16 little-endian, 48 kHz stereo
+binary frames. The server sends JSON `start` with the format, then `ready`.
+Send `{"type":"clear"}` to discard unsent speech. An `ended` frame terminates
+the media socket. Both sockets are separate from `relay.websocket.run`, which
+carries durable events. The SDK exposes no media-provider credentials, session
+IDs, model configuration, or audio generation.
 
 ## Webhooks
 

package/dist/buttons.d.ts

@@ -0,0 +1,64 @@
+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).
+ */
+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, oneTime?: boolean) => 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;;;;;;;;;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"}

package/dist/buttons.js

@@ -0,0 +1,139 @@
+/**
+ * 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).
+ */
+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.",
+    "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.",
+    "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.",
+].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. "
+    + "To keep the buttons on screen after a tap, write the block as {\"one_time\": false, \"items\": [...]} instead of a bare array.";
+/** 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, oneTime) => {
+    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) {
+        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, ...(one_time === undefined ? {} : { one_time }) };
+};
+/** 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":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AAEvC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,wVAAwV;IACxV,8QAA8Q;IAC9Q,kRAAkR;IAClR,2LAA2L;IAC3L,2GAA2G;IAC3G,2JAA2J;CAC5J,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GACpC,4EAA4E,GAAG,aAAa,GAAG,IAAI;MACjG,qHAAqH;MACrH,2DAA2D;MAC3D,gIAAgI,CAAC;AAErI,2FAA2F;AAC3F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAC1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAW3C,MAAM,KAAK,GAAG,IAAI,MAAM,CACtB,0BAA0B,GAAG,aAAa,GAAG,iEAAiE,EAC9G,GAAG,CACJ,CAAC;AAEF,MAAM,MAAM,GAAG,CAAC,KAAc,EAAE,KAAa,EAAuB,EAAE;IACpE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,QAAQ,KAAK,GAAG,CAAC,mBAAmB,CAAC;IAC9C,CAAC;IACD,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,KAAK,CAAC,CAAC;IACnF,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,KAAK,GAAG,CAAC,sBAAsB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,KAAK,GAAG,CAAC,gBAAgB,CAAC;IAC9F,IAAI,KAAK,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;QAC3C,OAAO,QAAQ,KAAK,GAAG,CAAC,kBAAkB,uBAAuB,aAAa,CAAC;IACjF,CAAC;IACD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;QAClE,OAAO,QAAQ,KAAK,GAAG,CAAC,mCAAmC,qBAAqB,aAAa,CAAC;IAChG,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO;YAAE,MAAM,IAAI,KAAK,EAAE,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,KAAK,GAAG,CAAC,4BAA4B,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AACxB,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAe,EAAE,OAAiB,EAAwB,EAAE;IACtF,MAAM,OAAO,GAAG,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACrF,CAAC,CAAC,MAAiD;QACnD,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACzG,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,iDAAiD,CAAC;IAClF,MAAM,QAAQ,GAAG,OAAO,IAAI,OAAO,EAAE,QAAQ,CAAC;IAC9C,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,QAAQ,KAAK,SAAS;QAAE,OAAO,gCAAgC,CAAC;IACrG,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,gCAAgC,CAAC;IAChE,IAAI,KAAK,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACrC,OAAO,yBAAyB,KAAK,CAAC,MAAM,uBAAuB,iBAAiB,EAAE,CAAC;IACzF,CAAC;IACD,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAClC,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAC7F,CAAC,CAAC;AAEF,uEAAuE;AACvE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAY,EAAwB,EAAE;IACtE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,qCAAqC,CAAC;IAC/C,CAAC;IACD,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAc,EAAgB,EAAE;IAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACjD,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACvE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC/E,MAAM,IAAI,GAAG,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC;IACzE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACnC,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,IAAY,EACZ,OAAgC,EAChC,KAAK,GAAG,MAAM,CAAC,iBAAiB,EACsB,EAAE,CAAC;IACzD,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;CAC9B,CAAC"}

package/dist/calls-room.d.ts

@@ -0,0 +1,50 @@
+import type { CallRoomAnswerFrame, CallRoomClientFrame, CallRoomEndedFrame, CallRoomErrorFrame, CallRoomOfferFrame, CallRoomStateFrame } from "./types.js";
+import type { WebSocketConstructor } from "./websocket.js";
+export interface CallRoomOptions {
+    WebSocket?: WebSocketConstructor;
+    /** Clients send `heartbeat` every 15 s (the room's hibernation auto-response). */
+    heartbeatIntervalMs?: number;
+}
+export interface CallRoomEvents {
+    roomState: (frame: CallRoomStateFrame) => void;
+    offer: (frame: CallRoomOfferFrame) => void;
+    answer: (frame: CallRoomAnswerFrame) => void;
+    ended: (frame: CallRoomEndedFrame) => void;
+    /** A server `error` frame, an upgrade failure, or an invalid frame (closed 4400). */
+    error: (error: CallRoomErrorFrame | Error) => void;
+    close: (event: {
+        code: number;
+        reason: string;
+    }) => void;
+}
+/**
+ * One participant's socket to a Call room. Opens `GET /v1/calls/{callId}/room`
+ * with the same bearer as every REST route, sends `join`, and keeps `state`
+ * at the latest `roomState` the room pushed. Nothing is polled.
+ */
+export declare class CallRoom {
+    #private;
+    readonly url: string;
+    /** The latest `roomState` frame, or null before the room has answered `join`. */
+    state: CallRoomStateFrame | null;
+    constructor(baseURL: string, callID: string, token: string, options?: CallRoomOptions);
+    get closed(): boolean;
+    on<K extends keyof CallRoomEvents>(event: K, listener: CallRoomEvents[K]): this;
+    off<K extends keyof CallRoomEvents>(event: K, listener: CallRoomEvents[K]): this;
+    /** Send one client frame from the room contract. */
+    send(frame: CallRoomClientFrame): void;
+    /** Callee only: ringing → connecting. */
+    accept(): void;
+    /** Callee only: ringing → ended(declined). */
+    decline(): void;
+    /** Either side: ringing → ended(canceled) by the caller, else ended(completed). */
+    end(): void;
+    /** "My remote track is playing"; the second side's `connected` makes the Call active. */
+    connected(): void;
+    /** Mute state for the other side's screen; the room answers with `roomState`. */
+    userUpdate(update: {
+        muted: boolean;
+    }): void;
+    close(code?: number, reason?: string): void;
+}
+//# sourceMappingURL=calls-room.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calls-room.d.ts","sourceRoot":"","sources":["../src/calls-room.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAElB,kBAAkB,EAGlB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,oBAAoB,EAAiB,MAAM,gBAAgB,CAAC;AAE1E,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,kFAAkF;IAClF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC/C,KAAK,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC3C,MAAM,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAC7C,KAAK,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC3C,qFAAqF;IACrF,KAAK,EAAE,CAAC,KAAK,EAAE,kBAAkB,GAAG,KAAK,KAAK,IAAI,CAAC;IACnD,KAAK,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC1D;AAsID;;;;GAIG;AACH,qBAAa,QAAQ;;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAQ;gBAStC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB;IAkB/B,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,EAAE,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAO/E,GAAG,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAKhF,oDAAoD;IACpD,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAKtC,yCAAyC;IACzC,MAAM,IAAI,IAAI;IAId,8CAA8C;IAC9C,OAAO,IAAI,IAAI;IAIf,mFAAmF;IACnF,GAAG,IAAI,IAAI;IAIX,yFAAyF;IACzF,SAAS,IAAI,IAAI;IAIjB,iFAAiF;IACjF,UAAU,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAI5C,KAAK,CAAC,IAAI,SAAO,EAAE,MAAM,SAAkB,GAAG,IAAI;CA4InD"}

package/dist/calls-room.js

@@ -0,0 +1,319 @@
+import NodeWebSocket from "ws";
+import { RelayAPIError } from "./errors.js";
+const HEARTBEAT_INTERVAL_MS = 15_000;
+/** The exact text frame the room answers from the runtime, never by code. */
+const HEARTBEAT_FRAME = JSON.stringify({ type: "heartbeat" });
+const CLIENT_CLOSE_INVALID_FRAME = 4400;
+const CALL_STATUSES = new Set(["ringing", "connecting", "active", "ended"]);
+const END_REASONS = new Set([
+    "completed", "declined", "canceled", "no_answer", "disconnected", "failed",
+]);
+const ROOM_ERROR_CODES = new Set(["invalid_frame", "not_allowed", "media_unavailable"]);
+const TRACKS = new Set(["microphone", "agent-voice"]);
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const hasKeys = (value, required, optional = []) => {
+    const keys = Object.keys(value);
+    return required.every((key) => keys.includes(key))
+        && keys.every((key) => required.includes(key) || optional.includes(key));
+};
+const isSessionDescription = (value, type) => isRecord(value)
+    && hasKeys(value, ["type", "sdp"])
+    && value.type === type
+    && typeof value.sdp === "string"
+    && value.sdp.length > 0;
+const isCall = (value) => isRecord(value)
+    && typeof value.id === "string"
+    && typeof value.chat_id === "string"
+    && isRecord(value.from)
+    && Array.isArray(value.to)
+    && value.mode === "audio"
+    && CALL_STATUSES.has(String(value.status))
+    && Number.isInteger(value.revision)
+    && typeof value.created_at === "string"
+    && (value.end_reason === null || END_REASONS.has(String(value.end_reason)));
+const isParticipant = (value) => isRecord(value)
+    && hasKeys(value, ["contact_id", "kind", "attached", "track", "muted", "connected"])
+    && typeof value.contact_id === "string"
+    && (value.kind === "user" || value.kind === "agent")
+    && typeof value.attached === "boolean"
+    && (value.track === null || TRACKS.has(String(value.track)))
+    && typeof value.muted === "boolean"
+    && typeof value.connected === "boolean";
+const isMedia = (value) => isRecord(value)
+    && hasKeys(value, ["url", "token", "expires_at", "audio_format"])
+    && typeof value.url === "string"
+    && typeof value.token === "string"
+    && typeof value.expires_at === "string"
+    && isRecord(value.audio_format)
+    && value.audio_format.encoding === "pcm_s16le"
+    && value.audio_format.sample_rate === 48_000
+    && value.audio_format.channels === 2;
+const parseServerFrame = (value) => {
+    if (!isRecord(value) || typeof value.type !== "string")
+        return undefined;
+    switch (value.type) {
+        case "roomState":
+            return hasKeys(value, ["type", "call", "participants"], ["media"])
+                && isCall(value.call)
+                && Array.isArray(value.participants)
+                && value.participants.every(isParticipant)
+                && (!Object.hasOwn(value, "media") || isMedia(value.media))
+                ? value
+                : undefined;
+        case "answer":
+            return hasKeys(value, ["type", "session_description"])
+                && isSessionDescription(value.session_description, "answer")
+                ? value
+                : undefined;
+        case "offer":
+            return hasKeys(value, ["type", "session_description", "track"])
+                && isSessionDescription(value.session_description, "offer")
+                && TRACKS.has(String(value.track))
+                ? value
+                : undefined;
+        case "ended":
+            return hasKeys(value, ["type", "reason"]) && END_REASONS.has(String(value.reason))
+                ? value
+                : undefined;
+        case "error":
+            return hasKeys(value, ["type", "code", "message"])
+                && ROOM_ERROR_CODES.has(String(value.code))
+                && typeof value.message === "string"
+                ? value
+                : undefined;
+        case "heartbeat":
+            return hasKeys(value, ["type"]) ? { type: "heartbeat" } : undefined;
+        default:
+            return undefined;
+    }
+};
+const deriveRoomURL = (baseURL, callID) => {
+    let url;
+    try {
+        url = new URL(baseURL);
+    }
+    catch {
+        throw new TypeError("Relay baseURL must be an absolute HTTP(S) URL.");
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:")
+        || url.username !== ""
+        || url.password !== "") {
+        throw new TypeError("Relay baseURL must be an absolute HTTP(S) URL.");
+    }
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.pathname = `/v1/calls/${encodeURIComponent(callID)}/room`;
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+};
+/**
+ * One participant's socket to a Call room. Opens `GET /v1/calls/{callId}/room`
+ * with the same bearer as every REST route, sends `join`, and keeps `state`
+ * at the latest `roomState` the room pushed. Nothing is polled.
+ */
+export class CallRoom {
+    url;
+    /** The latest `roomState` frame, or null before the room has answered `join`. */
+    state = null;
+    #socket;
+    #listeners = new Map();
+    #heartbeatIntervalMs;
+    #heartbeat;
+    #open = false;
+    #closed = false;
+    constructor(baseURL, callID, token, options = {}) {
+        if (!callID.trim())
+            throw new TypeError("A Call id is required to join its room.");
+        if (!token.trim())
+            throw new TypeError("A Relay token is required to join a Call room.");
+        this.url = deriveRoomURL(baseURL, callID);
+        this.#heartbeatIntervalMs = options.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+        const Constructor = options.WebSocket
+            ?? NodeWebSocket;
+        this.#socket = new Constructor(this.url, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        this.#socket.addEventListener("open", this.#onOpen);
+        this.#socket.addEventListener("message", this.#onMessage);
+        this.#socket.addEventListener("close", this.#onClose);
+        this.#socket.addEventListener("error", this.#onError);
+        this.#socket.on?.("unexpected-response", this.#onUnexpectedResponse);
+    }
+    get closed() {
+        return this.#closed;
+    }
+    on(event, listener) {
+        const listeners = this.#listeners.get(event) ?? new Set();
+        listeners.add(listener);
+        this.#listeners.set(event, listeners);
+        return this;
+    }
+    off(event, listener) {
+        this.#listeners.get(event)?.delete(listener);
+        return this;
+    }
+    /** Send one client frame from the room contract. */
+    send(frame) {
+        if (this.#closed)
+            throw new Error("Relay Call room socket is closed.");
+        this.#socket.send(JSON.stringify(frame));
+    }
+    /** Callee only: ringing → connecting. */
+    accept() {
+        this.send({ type: "accept" });
+    }
+    /** Callee only: ringing → ended(declined). */
+    decline() {
+        this.send({ type: "decline" });
+    }
+    /** Either side: ringing → ended(canceled) by the caller, else ended(completed). */
+    end() {
+        this.send({ type: "end" });
+    }
+    /** "My remote track is playing"; the second side's `connected` makes the Call active. */
+    connected() {
+        this.send({ type: "connected" });
+    }
+    /** Mute state for the other side's screen; the room answers with `roomState`. */
+    userUpdate(update) {
+        this.send({ type: "userUpdate", muted: update.muted });
+    }
+    close(code = 1000, reason = "client closed") {
+        if (this.#closed)
+            return;
+        this.#stopHeartbeat();
+        try {
+            this.#socket.close(code, reason);
+        }
+        catch {
+            this.#finish({ code, reason });
+        }
+    }
+    #emit(event, ...args) {
+        for (const listener of this.#listeners.get(event) ?? [])
+            listener(...args);
+    }
+    #stopHeartbeat() {
+        if (this.#heartbeat !== undefined)
+            clearInterval(this.#heartbeat);
+        this.#heartbeat = undefined;
+    }
+    #finish(event) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#stopHeartbeat();
+        this.#socket.removeEventListener("open", this.#onOpen);
+        this.#socket.removeEventListener("message", this.#onMessage);
+        this.#socket.removeEventListener("close", this.#onClose);
+        this.#socket.removeEventListener("error", this.#onError);
+        this.#socket.off?.("unexpected-response", this.#onUnexpectedResponse);
+        this.#emit("close", event);
+    }
+    #invalid(message) {
+        this.#emit("error", new Error(`Relay Call room received an invalid frame: ${message}`));
+        this.close(CLIENT_CLOSE_INVALID_FRAME, "invalid frame");
+    }
+    #onOpen = () => {
+        if (this.#open || this.#closed)
+            return;
+        this.#open = true;
+        this.send({ type: "join" });
+        this.#heartbeat = setInterval(() => {
+            try {
+                this.#socket.send(HEARTBEAT_FRAME);
+            }
+            catch (cause) {
+                this.#emit("error", cause instanceof Error ? cause : new Error(String(cause)));
+                this.close(1000, "heartbeat failed");
+            }
+        }, this.#heartbeatIntervalMs);
+    };
+    #onMessage = (message) => {
+        if (this.#closed)
+            return;
+        let value;
+        try {
+            const data = message.data;
+            const textData = typeof data === "string"
+                ? data
+                : data instanceof ArrayBuffer || ArrayBuffer.isView(data)
+                    ? new TextDecoder().decode(data)
+                    : undefined;
+            if (textData === undefined) {
+                this.#invalid("non-text frame");
+                return;
+            }
+            value = JSON.parse(textData);
+        }
+        catch {
+            this.#invalid("invalid JSON");
+            return;
+        }
+        const frame = parseServerFrame(value);
+        if (frame === undefined) {
+            this.#invalid(isRecord(value) && typeof value.type === "string"
+                ? `unexpected ${value.type} frame`
+                : "missing type");
+            return;
+        }
+        switch (frame.type) {
+            case "roomState":
+                this.state = frame;
+                this.#emit("roomState", frame);
+                return;
+            case "offer":
+                this.#emit("offer", frame);
+                return;
+            case "answer":
+                this.#emit("answer", frame);
+                return;
+            case "ended":
+                this.#emit("ended", frame);
+                // The room closes 1000 "Call ended" right after; closing here too
+                // is idempotent and frees the timer without waiting for it.
+                this.close(1000, "Call ended");
+                return;
+            case "error":
+                this.#emit("error", frame);
+                return;
+            case "heartbeat":
+                return;
+        }
+    };
+    #onClose = (event) => {
+        this.#finish({ code: event.code ?? 1006, reason: event.reason ?? "" });
+    };
+    #onError = () => {
+        if (this.#closed)
+            return;
+        this.#emit("error", new Error("Relay Call room connection failed."));
+    };
+    #onUnexpectedResponse = (_request, response) => {
+        const chunks = [];
+        response.setEncoding?.("utf8");
+        response.on("data", (chunk) => {
+            if (chunks.join("").length < 65_536)
+                chunks.push(String(chunk));
+        });
+        const settle = () => {
+            const status = response.statusCode ?? 0;
+            let message = `Relay Call room upgrade failed with HTTP ${status}.`;
+            let body = chunks.join("");
+            try {
+                body = JSON.parse(chunks.join(""));
+                if (isRecord(body) && isRecord(body.error) && typeof body.error.message === "string") {
+                    message = body.error.message;
+                }
+            }
+            catch {
+                // Keep the unparsed body for diagnostics.
+            }
+            this.#emit("error", new RelayAPIError(message, { status, body }));
+            this.#finish({ code: 1006, reason: `HTTP ${status}` });
+        };
+        response.on("end", settle);
+        response.on("error", settle);
+    };
+}
+//# sourceMappingURL=calls-room.js.map