@relaymessenger/chat-sdk-adapter 0.2.1 → 0.3.0-staging.1

package/dist/webhook.js

@@ -0,0 +1,115 @@
+import { ValidationError } from "@chat-adapter/shared";
+import { RELAY_API_VERSION, RELAY_WEBHOOK_EVENT_TYPES, RELAY_WEBHOOK_VERSION, } from "./types.js";
+import { isRelayUuid } from "./thread-id.js";
+const EVENT_TYPES = new Set(RELAY_WEBHOOK_EVENT_TYPES);
+// One Message may carry 100 text parts of 10,000 UTF-16 units. JSON escaping
+// can expand a valid text unit to six ASCII bytes, before envelope metadata.
+// Eight MiB accepts that locked maximum while still bounding untrusted input.
+export const MAX_WEBHOOK_BODY_BYTES = 8 * 1_048_576;
+function isRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value));
+}
+function isDateTime(value) {
+    return (typeof value === "string" &&
+        Number.isFinite(Date.parse(value)));
+}
+export function parseWebhookEnvelope(value) {
+    if (!isRecord(value)) {
+        throw new ValidationError("relay", "Relay webhook body must be an object");
+    }
+    if (value.api_version !== RELAY_API_VERSION ||
+        value.webhook_version !== RELAY_WEBHOOK_VERSION ||
+        typeof value.event_type !== "string" ||
+        !EVENT_TYPES.has(value.event_type) ||
+        typeof value.event_id !== "string" ||
+        !isRelayUuid(value.event_id) ||
+        typeof value.agent_id !== "string" ||
+        !isRelayUuid(value.agent_id) ||
+        typeof value.trace_id !== "string" ||
+        !value.trace_id ||
+        !isDateTime(value.created_at) ||
+        !isRecord(value.data)) {
+        throw new ValidationError("relay", `Webhook envelope must match Relay v1/${RELAY_WEBHOOK_VERSION}`);
+    }
+    return value;
+}
+function isHandle(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.id === "string" &&
+        isRelayUuid(value.id) &&
+        typeof value.handle === "string" &&
+        (value.kind === "user" || value.kind === "agent"));
+}
+export function parseWebhookMessageEvent(data) {
+    if (!isRecord(data.chat) ||
+        typeof data.chat.id !== "string" ||
+        !isRelayUuid(data.chat.id) ||
+        typeof data.id !== "string" ||
+        !isRelayUuid(data.id) ||
+        (data.direction !== "inbound" &&
+            data.direction !== "outbound") ||
+        !isHandle(data.sender_handle) ||
+        !Array.isArray(data.parts)) {
+        throw new ValidationError("relay", "message webhook data does not match the locked MessageEvent contract");
+    }
+    return data;
+}
+export function parseReactionEvent(data) {
+    if (typeof data.chat_id !== "string" ||
+        !isRelayUuid(data.chat_id) ||
+        typeof data.message_id !== "string" ||
+        !isRelayUuid(data.message_id) ||
+        !isHandle(data.from_handle) ||
+        !Number.isInteger(data.part_index) ||
+        data.part_index < 0 ||
+        typeof data.is_from_me !== "boolean" ||
+        typeof data.reaction_type !== "string" ||
+        ![
+            "love",
+            "like",
+            "dislike",
+            "laugh",
+            "emphasize",
+            "question",
+            "custom",
+        ].includes(data.reaction_type) ||
+        !isDateTime(data.reacted_at)) {
+        throw new ValidationError("relay", "reaction webhook data does not match the locked ReactionEventBase contract");
+    }
+    return data;
+}
+export function assertExhaustiveEvent(eventType) {
+    throw new Error(`Unhandled Relay webhook event: ${eventType}`);
+}
+export async function readWebhookBody(request) {
+    if (!request.body)
+        return "";
+    const reader = request.body.getReader();
+    const chunks = [];
+    let length = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        length += value.byteLength;
+        if (length > MAX_WEBHOOK_BODY_BYTES) {
+            await reader.cancel();
+            throw new RangeError("Relay webhook body exceeds 8 MiB");
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+export function isMessageEventType(value) {
+    return value.startsWith("message.");
+}
+//# sourceMappingURL=webhook.js.map

package/dist/webhook.js.map

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

package/package.json

@@ -1,59 +1,79 @@
 {
   "name": "@relaymessenger/chat-sdk-adapter",
-  "version": "0.2.1",
-  "description": "Relay adapter for the Vercel Chat SDK. Receive signed Relay webhooks and post replies as one canonical message.",
-  "homepage": "https://docs.relayapp.im/integrations/chat-sdk",
-  "bugs": {
-    "url": "https://github.com/relaymessenger/Relay-SDK/issues"
-  },
-  "license": "MIT",
+  "version": "0.3.0-staging.1",
+  "description": "Vendor-official Relay adapter for Vercel Chat SDK.",
   "keywords": [
     "relay",
     "chat-sdk",
     "adapter",
     "messaging",
-    "agent",
     "webhook"
   ],
-  "engines": {
-    "node": ">=22.18"
+  "homepage": "https://docs.relayapp.im/ecosystem/chat-sdk",
+  "bugs": {
+    "url": "https://github.com/RelayMessenger/Relay-SDK/issues"
   },
-  "publishConfig": {
-    "access": "public"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RelayMessenger/Relay-SDK.git",
+    "directory": "packages/chat-sdk-adapter"
   },
+  "license": "MIT",
   "type": "module",
-  "main": "./dist/src/index.js",
-  "types": "./dist/src/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/src/index.d.ts",
-      "default": "./dist/src/index.js"
-    }
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
+    "dist/",
     "README.md",
-    "LICENSE",
-    "dist/**/*.js",
-    "dist/**/*.d.ts"
+    "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "staging",
+    "provenance": true
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "check": "tsc --noEmit",
-    "test": "vitest run",
-    "prepack": "npm run build"
+    "test": "npm run test:unit && npm run test:workerd",
+    "test:unit": "vitest run --config vitest.config.ts",
+    "test:workerd": "vitest run --config vitest.workerd.config.ts",
+    "test:installed": "node scripts/test-installed-package.mjs",
+    "test:all": "npm run check && npm run build && npm run test && npm run test:installed",
+    "example:check": "RELAY_EXAMPLE_CHECK=1 node examples/server.mjs",
+    "prepack": "npm run check && npm run test && npm run build",
+    "wrangler:types": "wrangler types",
+    "wrangler:types:check": "wrangler types --check"
   },
   "peerDependencies": {
-    "chat": "^4.38.0"
+    "chat": "^4.39.0"
   },
-  "devDependencies": {
-    "@types/node": "^26.2.0",
-    "chat": "^4.38.1",
-    "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+  "dependencies": {
+    "@chat-adapter/shared": "4.39.0"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/relaymessenger/Relay-SDK.git",
-    "directory": "integrations/chat-sdk"
+  "devDependencies": {
+    "@chat-adapter/state-memory": "4.39.0",
+    "@chat-adapter/tests": "4.39.0",
+    "@cloudflare/vitest-plugin": "1.1.2",
+    "@types/node": "26.4.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "chat": "4.39.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11",
+    "wrangler": "4.127.1",
+    "yaml": "2.9.0"
   }
 }

package/dist/src/adapter.d.ts

@@ -1,125 +0,0 @@
-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 };