@relaymessenger/chat-sdk-adapter 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Companion Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @relaymessenger/chat-sdk-adapter
+
+Relay adapter for the [Vercel Chat SDK](https://chat-sdk.dev). Relay is a
+consumer messenger where people talk to agents the way they talk to contacts;
+this package makes a Relay conversation a Chat SDK thread, so anything built on
+the Chat SDK can reach Relay users. Raw HTTPS remains the canonical contract;
+this is a thin, dependency-free binding of it.
+
+```ts
+import { createMemoryState } from "@chat-adapter/state-memory";
+import { createRelayAdapter } from "@relaymessenger/chat-sdk-adapter";
+import { Chat } from "chat";
+
+const chat = new Chat({
+  userName: "My Agent",
+  adapters: {
+    relay: createRelayAdapter({
+      token: process.env.RELAY_AGENT_TOKEN!,
+      webhookSecret: process.env.RELAY_WEBHOOK_SECRET!,
+    }),
+  },
+  state: createMemoryState(),
+});
+
+chat.onNewMention(async (thread, message) => {
+  await thread.subscribe();
+  await thread.post({ markdown: `You said: ${message.text}` });
+});
+
+// Mount as a POST route.
+export const POST = (request: Request) => chat.webhooks.relay(request);
+```
+
+`chat` is a peer dependency: install it alongside this package.
+
+## With eve
+
+eve's Chat SDK channel bridges any adapter to an agent. See
+[`examples/eve`](../../examples/eve) in this repository for the channel file and
+the environment it needs.
+
+## What the adapter enforces
+
+- Standard Webhooks signature verification over the exact raw body, then
+  `event_id` deduplication, because Relay delivers at least once. The event id
+  is claimed before the handler runs, so two redeliveries racing each other
+  cannot both dispatch, and released again if the handler throws, so Relay's
+  retry of a failed turn is still handled. **This window is a bounded set in
+  memory, in one process.** A restart, or a second instance behind the same
+  webhook URL, has no claim to lose and will dispatch the event again. The
+  idempotency key below is what makes that second dispatch harmless.
+- A deterministic `Idempotency-Key` on every `POST /v1/messages`, derived from
+  the inbound event id and the send's position in the turn, and from nothing
+  else. Relay hashes the request body server side and stores it beside the key,
+  so a retry carrying the same body replays the first response and a retry
+  carrying a different body is refused with 409 `idempotency_conflict`. Keeping
+  the content out of the key is what leaves both of those reachable: a key that
+  moved with the body would make every retry a new send, and a handler backed
+  by a model rarely writes the same words twice.
+- Group `invocation_id` threading. Relay delivers a group message to an agent
+  only when that agent was invoked, and the reply is scoped to that single-use
+  invocation, so the first send of a turn carries it and a second raises
+  `RelayInvocationSpentError` rather than going out bare and taking a 403.
+- Chunking rather than truncation. Relay caps a text part at 8 KB and a message
+  at 32 parts; a longer reply becomes more parts, and then more messages. Each
+  text part draws as its own balloon in the app, so a long reply arrives as a
+  stack of bubbles rather than one tall one. A split consumes the whitespace it
+  lands on, and nothing else.
+
+## Formatting
+
+Relay does not render Markdown. A text part carries canonical plain text plus
+`styles` runs with UTF-16 offsets, and clients draw the runs. So `{ markdown }`
+and `{ ast }` are flattened to the text a person reads, with emphasis carried
+across as style ranges: `strong` becomes `bold`, `emphasis` becomes `italic`,
+`delete` becomes `strikethrough`, and inline or fenced code becomes `monospace`.
+
+Constructs Relay has no style for keep their information in the text rather than
+losing it. A link whose label differs from its target renders as `label (url)`,
+a blockquote keeps its `> ` line prefix, a list keeps its markers, and a table is
+drawn as a monospace ASCII grid. A plain string is sent verbatim with an empty
+`styles` array, which is Relay's marker for structured plain text rather than a
+legacy Markdown body.
+
+## Capabilities
+
+| Chat SDK operation                | Relay                                                            |
+| --------------------------------- | ---------------------------------------------------------------- |
+| `postMessage`, `editMessage`, `deleteMessage` | `POST /v1/messages`, `PATCH` and `DELETE /v1/messages/{id}` |
+| `addReaction`, `removeReaction`    | `POST /v1/messages/{id}/reactions`                              |
+| `startTyping`                      | `POST /v1/conversations/{id}/typing`, ephemeral, 80-char label  |
+| `markAsRead`                       | `POST /v1/conversations/{id}/read`                              |
+| `fetchMessages`, `fetchThread`     | `GET /v1/conversations/{id}/messages` and `/v1/conversations/{id}` |
+| `getUser`                          | `GET /v1/users/{id}`, scoped to a shared conversation           |
+| `stream`                           | Buffered, then committed as one message                          |
+
+Things Relay does not do, stated rather than faked:
+
+- **No streaming bubbles.** A turn commits exactly one canonical message, so
+  `stream` buffers the whole reply and posts it once. Nothing partial reaches a
+  recipient. With eve's Chat SDK channel, set `streaming: false`.
+- **No forward history cursor.** `GET /v1/conversations/{id}/messages` pages
+  backwards with `before_sequence`, so `fetchMessages({ direction: "forward" })`
+  throws `NotImplementedError` instead of walking the whole conversation.
+- **No agent-initiated DM.** `POST /v1/conversations/direct` accepts a user
+  session, not an Agent Token, so `openDM` is not implemented. A conversation
+  starts when a person adds the agent.
+- **No single-message read.** The API has no `GET /v1/messages/{id}`, so
+  `fetchMessage` is not implemented and the Chat SDK returns `null`.
+- **No cards.** Relay removed interactive components. A card is delivered as its
+  fallback text, so the words arrive but buttons do not render and a
+  human-in-the-loop prompt cannot be answered in the app.
+- **No edits carrying media.** Relay requires an edit to stay text-bearing and
+  rejects attachment parts.
+
+Attachments work in both directions. Inbound media and voice memo parts arrive as
+Chat SDK attachments; outbound attachments with a public HTTPS URL are sent as
+media parts, and outbound bytes are uploaded through `POST /v1/attachments`
+first.
+
+Docs: <https://docs.relayapp.im>.

package/dist/src/adapter.d.ts

@@ -0,0 +1,125 @@
+import { Message } from "chat";
+import type { Adapter, AdapterPostableMessage, ChatInstance, EmojiValue, FetchOptions, FetchResult, FormattedContent, RawMessage, StreamChunk, ThreadInfo, UserInfo, WebhookOptions } from "chat";
+import { RelayClient } from "./client.js";
+import type { RelayClientOptions } from "./client.js";
+import type { RelayMessage, RelayRawMessage, RelayThreadId } from "./types.js";
+export declare const RELAY_ADAPTER_NAME = "relay";
+export interface RelayAdapterOptions extends Omit<RelayClientOptions, "token"> {
+    /** Agent Token. Defaults to `RELAY_AGENT_TOKEN`. */
+    token?: string;
+    /** Webhook signing secret. Defaults to `RELAY_WEBHOOK_SECRET`. */
+    webhookSecret?: string;
+    /** Display name for the agent. Defaults to `Relay Agent`. */
+    userName?: string;
+    /** This agent's `agt_` id, when the caller knows it. */
+    agentId?: string;
+    /** Clock tolerance for signature verification, in seconds. */
+    toleranceSeconds?: number;
+    /** How many handled `event_id` values to remember. */
+    dedupeWindow?: number;
+    /** Override the client, mainly for tests. */
+    client?: RelayClient;
+}
+/**
+ * A group turn tried to commit a second message. Relay's invocation is single
+ * use, so there is nothing valid for the second message to cite and the server
+ * would answer 403.
+ */
+export declare class RelayInvocationSpentError extends Error {
+    constructor(message: string);
+}
+/**
+ * Relay adapter for the Vercel Chat SDK.
+ *
+ * Relay is a consumer messenger where people talk to agents as contacts, so
+ * this adapter maps the Chat SDK's thread model onto Relay conversations one
+ * to one: a Relay conversation has no enclosing channel, and a thread id is
+ * `relay:{conversation_id}`.
+ *
+ * Two Relay rules shape the surface. A streamed turn commits exactly one
+ * canonical message, so `stream` buffers and posts once rather than editing a
+ * draft bubble into place. And a group reply is scoped to the single-use
+ * invocation that produced the inbound event, so the first send of a turn
+ * carries it and a second cannot.
+ */
+export declare class RelayAdapter implements Adapter<RelayThreadId, RelayRawMessage> {
+    readonly name = "relay";
+    readonly userName: string;
+    readonly botUserId?: string;
+    readonly lockScope: "thread";
+    /** Relay serves history from `GET /v1/conversations/{id}/messages`. */
+    readonly persistThreadHistory = false;
+    private readonly client;
+    private readonly webhookSecret?;
+    private readonly toleranceSeconds?;
+    private readonly dedupe;
+    private chat?;
+    constructor(options?: RelayAdapterOptions);
+    initialize(chat: ChatInstance): Promise<void>;
+    encodeThreadId(platformData: RelayThreadId): string;
+    decodeThreadId(threadId: string): RelayThreadId;
+    channelIdFromThreadId(threadId: string): string;
+    renderFormatted(content: FormattedContent): string;
+    parseMessage(raw: RelayRawMessage): Message<RelayRawMessage>;
+    postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<RelayRawMessage>>;
+    editMessage(threadId: string, messageId: string, message: AdapterPostableMessage): Promise<RawMessage<RelayRawMessage>>;
+    deleteMessage(threadId: string, messageId: string): Promise<void>;
+    addReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    removeReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    /**
+     * Relay's typing indicator is ephemeral and carries an optional label of up
+     * to 80 characters. The invocation is peeked rather than consumed: typing is
+     * not the group reply the invocation is spent on.
+     *
+     * Failures are swallowed. Group typing without a live pending invocation is a
+     * 403 (`Relay-Server/server/src/domain/typing.ts:70-73`), which is exactly
+     * what typing after the first send of a group turn looks like. The Chat SDK
+     * treats this call as best effort and has no `stopTyping` to strand, so a
+     * hint that cannot be shown must never take the reply down with it.
+     */
+    startTyping(threadId: string, status?: string): Promise<void>;
+    markAsRead(threadId: string, messageId: string): Promise<void>;
+    getUser(userId: string): Promise<UserInfo | null>;
+    /**
+     * Relay pages history backwards with `before_sequence` and returns newest
+     * first; the Chat SDK wants each page in chronological order. There is no
+     * forward cursor on the route, so `direction: "forward"` has nothing to call.
+     */
+    fetchMessages(threadId: string, options?: FetchOptions): Promise<FetchResult<RelayRawMessage>>;
+    fetchThread(threadId: string): Promise<ThreadInfo>;
+    /**
+     * Relay commits one canonical message per turn and has no draft bubble to
+     * edit, so the stream is buffered and posted once. Nothing partial ever
+     * reaches a recipient, and no cleanup is needed if the stream fails midway.
+     */
+    stream(threadId: string, textStream: AsyncIterable<string | StreamChunk>): Promise<RawMessage<RelayRawMessage> | null>;
+    /**
+     * Verify the Standard Webhooks signature over the exact raw body, refuse a
+     * replay by `event_id`, and hand the event to the Chat SDK. Relay redelivers
+     * on 5xx, so a dispatch failure must not answer 2xx.
+     */
+    handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
+    private dispatch;
+    private buildParts;
+    private textParts;
+    /**
+     * Relay has no card surface: interactive components were removed from the
+     * app, so buttons cannot render and a human cannot answer one in Relay. The
+     * card's words are still delivered, as text, rather than dropped.
+     */
+    private cardToText;
+    private attachmentPart;
+    private filePart;
+    /**
+     * Send the parts in one call when they fit, and as follow-up calls when
+     * they do not. The server splits each call at ingest into one or more
+     * messages, and the one call that carries the invocation owns every message
+     * it commits. A group turn cannot overflow, and cannot POST twice: Relay's
+     * invocation is single use per call, so a second POST has nothing valid to
+     * cite and the server answers 403.
+     */
+    private sendParts;
+}
+/** Build a Relay adapter for the Vercel Chat SDK. */
+export declare function createRelayAdapter(options?: RelayAdapterOptions): RelayAdapter;
+export type { RelayMessage };