@relaymessenger/sdk 0.2.0

package/README.md

@@ -0,0 +1,28 @@
+# `@relaymessenger/sdk`
+
+Shared Relay transport for native plugins and runnable examples.
+
+Raw HTTPS against `https://api.relayapp.im` remains the public contract. This
+package is a thin TypeScript binding used by host plugins: Agent Token auth,
+Standard Webhooks verification, durable long-poll cursors, event dedupe, and
+idempotent `POST /v1/messages`.
+
+```ts
+import { createRelayClient, runPollLoop, MemoryDedupe } from "@relaymessenger/sdk";
+
+const client = createRelayClient({ token: process.env.RELAY_AGENT_TOKEN! });
+const me = await client.getMe();
+const dedupe = new MemoryDedupe();
+
+await runPollLoop({
+  client,
+  getCursor: () => 0,
+  setCursor: async () => {},
+  dedupe,
+  onMessage: async ({ event, message, reply }) => {
+    await reply.text(`hi from ${me.handle}`);
+  },
+});
+```
+
+Docs: https://docs.relayapp.im

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+import type { RelayAgentProfile, RelayEventsPage, RelayOutgoingPart, RelayReplyRef, RelaySendResult } from "./types.js";
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export type RelayClientOptions = {
+    token: string;
+    baseUrl?: string;
+    fetchImpl?: FetchLike;
+    requestTimeoutMs?: number;
+};
+export type RelayClient = {
+    readonly baseUrl: string;
+    getMe: (params?: {
+        signal?: AbortSignal;
+    }) => Promise<RelayAgentProfile>;
+    pollEvents: (params: {
+        cursor: number;
+        timeoutSeconds?: number;
+        limit?: number;
+        signal?: AbortSignal;
+    }) => Promise<RelayEventsPage>;
+    sendMessage: (params: {
+        conversationId: string;
+        parts: RelayOutgoingPart[];
+        replyTo?: RelayReplyRef;
+        invocationId?: string;
+        idempotencyKey: string;
+        signal?: AbortSignal;
+    }) => Promise<RelaySendResult>;
+    sendText: (params: {
+        conversationId: string;
+        text: string;
+        replyTo?: RelayReplyRef;
+        invocationId?: string;
+        idempotencyKey: string;
+        signal?: AbortSignal;
+    }) => Promise<RelaySendResult>;
+    setTyping: (params: {
+        conversationId: string;
+        started: boolean;
+        label?: string;
+        invocationId?: string;
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    setResponding: (params: {
+        conversationId: string;
+        messageId: string;
+        label?: string;
+        invocationId?: string;
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    markRead: (params: {
+        conversationId: string;
+        messageId: string;
+        signal?: AbortSignal;
+    }) => Promise<void>;
+};
+export declare function createRelayClient(options: RelayClientOptions): RelayClient;
+export {};

package/dist/client.js

@@ -0,0 +1,156 @@
+import { RelayApiError, classifyRelayHttpStatus, isAbortError, } from "./errors.js";
+import { normalizeRelayBaseUrl } from "./url.js";
+async function readErrorDetail(response) {
+    try {
+        const body = (await response.json());
+        return {
+            ...(body?.error?.code ? { code: body.error.code } : {}),
+            ...(body?.error?.details ? { details: body.error.details } : {}),
+            message: body?.error?.message ?? body?.message ?? "",
+        };
+    }
+    catch {
+        return { message: "" };
+    }
+}
+export function createRelayClient(options) {
+    if (!options.token.trim()) {
+        throw new Error("relay: Agent Token is required");
+    }
+    const baseUrl = normalizeRelayBaseUrl(options.baseUrl);
+    const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
+    const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
+    const request = async (params) => {
+        const url = new URL(`${baseUrl}${params.path}`);
+        for (const [key, value] of Object.entries(params.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        const timeoutSignal = AbortSignal.timeout(params.timeoutMs ?? requestTimeoutMs);
+        const signal = params.signal
+            ? AbortSignal.any([params.signal, timeoutSignal])
+            : timeoutSignal;
+        let response;
+        try {
+            response = await fetchImpl(url.toString(), {
+                method: params.method,
+                headers: {
+                    authorization: `Bearer ${options.token}`,
+                    ...(params.body === undefined ? {} : { "content-type": "application/json" }),
+                    ...params.headers,
+                },
+                ...(params.body === undefined ? {} : { body: JSON.stringify(params.body) }),
+                signal,
+            });
+        }
+        catch (error) {
+            if (timeoutSignal.aborted && !params.signal?.aborted) {
+                throw new RelayApiError(`relay: ${params.method} ${params.path} timed out after ${params.timeoutMs ?? requestTimeoutMs}ms`, { kind: "retryable" });
+            }
+            if (isAbortError(error))
+                throw error;
+            throw new RelayApiError(`relay: network error: ${String(error)}`, {
+                kind: "retryable",
+            });
+        }
+        if (!response.ok) {
+            const detail = await readErrorDetail(response);
+            throw new RelayApiError(`relay: ${params.method} ${params.path} failed with ${response.status}${detail.message ? `: ${detail.message}` : ""}`, {
+                status: response.status,
+                kind: classifyRelayHttpStatus(response.status),
+                ...(detail.code ? { code: detail.code } : {}),
+                ...(detail.details ? { details: detail.details } : {}),
+            });
+        }
+        return response;
+    };
+    const client = {
+        baseUrl,
+        getMe: async (params) => {
+            const response = await request({
+                method: "GET",
+                path: "/v1/agents/me",
+                ...(params?.signal ? { signal: params.signal } : {}),
+            });
+            const body = (await response.json());
+            return body.agent;
+        },
+        pollEvents: async (params) => {
+            const timeoutSeconds = Math.min(Math.max(params.timeoutSeconds ?? 30, 1), 30);
+            const response = await request({
+                method: "GET",
+                path: "/v1/events",
+                query: {
+                    cursor: params.cursor,
+                    timeout: timeoutSeconds,
+                    ...(params.limit === undefined ? {} : { limit: params.limit }),
+                },
+                ...(params.signal ? { signal: params.signal } : {}),
+                timeoutMs: (timeoutSeconds + 15) * 1_000,
+            });
+            const body = (await response.json());
+            const events = Array.isArray(body.events) ? body.events : [];
+            const nextCursor = typeof body.next_cursor === "number" && Number.isSafeInteger(body.next_cursor)
+                ? body.next_cursor
+                : params.cursor;
+            return { events, nextCursor };
+        },
+        sendMessage: async (params) => {
+            const response = await request({
+                method: "POST",
+                path: "/v1/messages",
+                headers: { "idempotency-key": params.idempotencyKey },
+                body: {
+                    conversation_id: params.conversationId,
+                    parts: params.parts,
+                    ...(params.invocationId ? { invocation_id: params.invocationId } : {}),
+                    ...(params.replyTo ? { reply_to: params.replyTo } : {}),
+                },
+                ...(params.signal ? { signal: params.signal } : {}),
+            });
+            const body = (await response.json());
+            return { messages: body.messages };
+        },
+        sendText: async (params) => {
+            const { text, ...rest } = params;
+            return client.sendMessage({
+                ...rest,
+                parts: [{ type: "text", text }],
+            });
+        },
+        setTyping: async (params) => {
+            await request({
+                method: "POST",
+                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/typing`,
+                body: {
+                    started: params.started,
+                    ...(params.label ? { label: params.label } : {}),
+                    ...(params.invocationId ? { invocation_id: params.invocationId } : {}),
+                },
+                ...(params.signal ? { signal: params.signal } : {}),
+            });
+        },
+        setResponding: async (params) => {
+            await request({
+                method: "POST",
+                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/responding`,
+                body: {
+                    message_id: params.messageId,
+                    ...(params.label ? { label: params.label } : {}),
+                    ...(params.invocationId ? { invocation_id: params.invocationId } : {}),
+                },
+                ...(params.signal ? { signal: params.signal } : {}),
+            });
+        },
+        markRead: async (params) => {
+            await request({
+                method: "POST",
+                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/read`,
+                body: { message_id: params.messageId },
+                ...(params.signal ? { signal: params.signal } : {}),
+            });
+        },
+    };
+    return client;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+export type RelayApiErrorKind = "auth" | "conflict" | "retryable" | "rejected";
+/** Classified Relay API failure. `terminal` means retrying the same request cannot succeed. */
+export declare class RelayApiError extends Error {
+    readonly status: number | undefined;
+    readonly kind: RelayApiErrorKind;
+    readonly code: string | undefined;
+    /** Structured `error.details` from the response body, e.g. `highest_delivered_cursor` on 422. */
+    readonly details: Record<string, unknown> | undefined;
+    constructor(message: string, params: {
+        status?: number;
+        kind: RelayApiErrorKind;
+        code?: string;
+        details?: Record<string, unknown>;
+    });
+    get terminal(): boolean;
+    get retryable(): boolean;
+}
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+export declare function classifyRelayHttpStatus(status: number): RelayApiErrorKind;
+export declare function isAbortError(error: unknown): boolean;
+export declare function isRelayWebhookConflict(error: unknown): error is RelayApiError;

package/dist/errors.js

@@ -0,0 +1,46 @@
+/** Classified Relay API failure. `terminal` means retrying the same request cannot succeed. */
+export class RelayApiError extends Error {
+    status;
+    kind;
+    code;
+    /** Structured `error.details` from the response body, e.g. `highest_delivered_cursor` on 422. */
+    details;
+    constructor(message, params) {
+        super(message);
+        this.name = "RelayApiError";
+        this.status = params.status;
+        this.kind = params.kind;
+        this.code = params.code;
+        this.details = params.details;
+    }
+    get terminal() {
+        return this.kind !== "retryable";
+    }
+    get retryable() {
+        return this.kind === "retryable";
+    }
+}
+export class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+    }
+}
+export function classifyRelayHttpStatus(status) {
+    if (status === 401)
+        return "auth";
+    if (status === 409)
+        return "conflict";
+    if (status === 408 || status === 429 || status >= 500)
+        return "retryable";
+    return "rejected";
+}
+export function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+export function isRelayWebhookConflict(error) {
+    return (error instanceof RelayApiError &&
+        error.status === 409 &&
+        error.code !== "terminated_by_other_consumer");
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,MAAM,CAAqB;IAC3B,IAAI,CAAoB;IACxB,IAAI,CAAqB;IAClC,iGAAiG;IACxF,OAAO,CAAsC;IAEtD,YACE,OAAe,EACf,MAKC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAChC,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC;IACnC,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,UAAU,CAAC;IACtC,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,GAAG;QAAE,OAAO,WAAW,CAAC;IAC1E,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,OAAO,CACL,KAAK,YAAY,aAAa;QAC9B,KAAK,CAAC,MAAM,KAAK,GAAG;QACpB,KAAK,CAAC,IAAI,KAAK,8BAA8B,CAC9C,CAAC;AACJ,CAAC"}

package/dist/file-cursor.d.ts

@@ -0,0 +1,10 @@
+export type FileCursorStore = {
+    load(): number;
+    current(): number;
+    advance(next: number): void;
+};
+/**
+ * Simple durable cursor file for long-poll consumers.
+ * Advances are monotonic; a corrupt file refuses to reset to zero silently.
+ */
+export declare function createFileCursorStore(path: string): FileCursorStore;

package/dist/file-cursor.js

@@ -0,0 +1,53 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Simple durable cursor file for long-poll consumers.
+ * Advances are monotonic; a corrupt file refuses to reset to zero silently.
+ */
+export function createFileCursorStore(path) {
+    let cursor = 0;
+    let loaded = false;
+    const read = () => {
+        try {
+            const raw = readFileSync(path, "utf8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.cursor !== "number" ||
+                !Number.isSafeInteger(parsed.cursor) ||
+                parsed.cursor < 0) {
+                throw new Error(`corrupt cursor file: ${path}`);
+            }
+            return parsed.cursor;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT")
+                return 0;
+            throw error;
+        }
+    };
+    const write = (value) => {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify({ cursor: value })}\n`, { mode: 0o600 });
+    };
+    return {
+        load: () => {
+            cursor = read();
+            loaded = true;
+            return cursor;
+        },
+        current: () => {
+            if (!loaded)
+                throw new Error("relay cursor: current() before load()");
+            return cursor;
+        },
+        advance: (next) => {
+            if (!loaded)
+                throw new Error("relay cursor: advance() before load()");
+            if (!Number.isSafeInteger(next) || next < 0 || next <= cursor)
+                return;
+            write(next);
+            cursor = next;
+        },
+    };
+}
+//# sourceMappingURL=file-cursor.js.map

package/dist/file-cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cursor.js","sourceRoot":"","sources":["../src/file-cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,IAAI,GAAG,GAAW,EAAE;QACxB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;YACvD,IACE,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;gBACjC,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC;gBACpC,MAAM,CAAC,MAAM,GAAG,CAAC,EACjB,CAAC;gBACD,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;YACnD,IAAI,IAAI,KAAK,QAAQ;gBAAE,OAAO,CAAC,CAAC;YAChC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,EAAE;QAC9B,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjF,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,GAAG,EAAE;YACT,MAAM,GAAG,IAAI,EAAE,CAAC;YAChB,MAAM,GAAG,IAAI,CAAC;YACd,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,EAAE,GAAG,EAAE;YACZ,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;YACtE,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YAChB,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;YACtE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,IAAI,MAAM;gBAAE,OAAO;YACtE,KAAK,CAAC,IAAI,CAAC,CAAC;YACZ,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/idempotency.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Deterministic Idempotency-Key for one reply attempt.
+ * Includes a content digest so a redelivery that produces different text does
+ * not collide with a prior body under the same event id.
+ */
+export declare function deriveIdempotencyKey(eventId: string, ordinal: number, content: unknown): Promise<string>;
+/** Simple key when the reply body is fixed for the event. */
+export declare function replyIdempotencyKey(eventId: string, suffix?: string): string;

package/dist/idempotency.js

@@ -0,0 +1,35 @@
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value) ?? "null";
+    }
+    const withToJson = value;
+    if (typeof withToJson.toJSON === "function") {
+        return canonicalJson(withToJson.toJSON());
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    return `{${entries
+        .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)
+        .join(",")}}`;
+}
+/**
+ * Deterministic Idempotency-Key for one reply attempt.
+ * Includes a content digest so a redelivery that produces different text does
+ * not collide with a prior body under the same event id.
+ */
+export async function deriveIdempotencyKey(eventId, ordinal, content) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalJson(content)));
+    const hex = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0"))
+        .join("")
+        .slice(0, 32);
+    return `${eventId.slice(0, 180)}:${ordinal}:${hex}`;
+}
+/** Simple key when the reply body is fixed for the event. */
+export function replyIdempotencyKey(eventId, suffix = "0") {
+    return `reply-${eventId}-${suffix}`;
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;IACzC,CAAC;IACD,MAAM,UAAU,GAAG,KAAmC,CAAC;IACvD,IAAI,OAAO,UAAU,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QAC5C,OAAO,aAAa,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACnD,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;SAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;SAC1C,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,IAAI,OAAO;SACf,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;SACvE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAe,EACf,OAAe,EACf,OAAgB;IAEhB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CACvC,SAAS,EACT,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CACjD,CAAC;IACF,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CACtD,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CACnC;SACE,IAAI,CAAC,EAAE,CAAC;SACR,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChB,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;AACtD,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,MAAM,GAAG,GAAG;IAC/D,OAAO,SAAS,OAAO,IAAI,MAAM,EAAE,CAAC;AACtC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createRelayClient, type RelayClient, type RelayClientOptions, } from "./client.js";
+export { RelayApiError, WebhookVerificationError, classifyRelayHttpStatus, isAbortError, isRelayWebhookConflict, type RelayApiErrorKind, } from "./errors.js";
+export { createFileCursorStore, type FileCursorStore } from "./file-cursor.js";
+export { deriveIdempotencyKey, replyIdempotencyKey, } from "./idempotency.js";
+export { MemoryDedupe, type EventDedupe } from "./memory-dedupe.js";
+export { runPollLoop, type MessageHandlerContext, type PollLoopParams, type ReplyOptions, } from "./poll-loop.js";
+export { verifyWebhookSignature, type VerifyWebhookOptions, } from "./signature.js";
+export type { MessageReceivedData, MessageReceivedEvent, RelayAgentProfile, RelayEventEnvelope, RelayEventsPage, RelayMessage, RelayOutgoingPart, RelayPart, RelayReplyRef, RelaySender, RelaySendResult, } from "./types.js";
+export { DEFAULT_RELAY_BASE_URL, normalizeRelayBaseUrl } from "./url.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { createRelayClient, } from "./client.js";
+export { RelayApiError, WebhookVerificationError, classifyRelayHttpStatus, isAbortError, isRelayWebhookConflict, } from "./errors.js";
+export { createFileCursorStore } from "./file-cursor.js";
+export { deriveIdempotencyKey, replyIdempotencyKey, } from "./idempotency.js";
+export { MemoryDedupe } from "./memory-dedupe.js";
+export { runPollLoop, } from "./poll-loop.js";
+export { verifyWebhookSignature, } from "./signature.js";
+export { DEFAULT_RELAY_BASE_URL, normalizeRelayBaseUrl } from "./url.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,GAGlB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,uBAAuB,EACvB,YAAY,EACZ,sBAAsB,GAEvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,qBAAqB,EAAwB,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EACL,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,WAAW,GAIZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,sBAAsB,GAEvB,MAAM,gBAAgB,CAAC;AAcxB,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC"}

package/dist/memory-dedupe.d.ts

@@ -0,0 +1,13 @@
+/** In-memory event_id window for at-least-once delivery. */
+export type EventDedupe = {
+    has(eventId: string): boolean;
+    /** Record only after the event was durably handled. */
+    record(eventId: string): void;
+};
+export declare class MemoryDedupe implements EventDedupe {
+    private readonly capacity;
+    private readonly seen;
+    constructor(capacity?: number);
+    has(eventId: string): boolean;
+    record(eventId: string): void;
+}

package/dist/memory-dedupe.js

@@ -0,0 +1,25 @@
+/** In-memory event_id window for at-least-once delivery. */
+export class MemoryDedupe {
+    capacity;
+    seen = new Set();
+    constructor(capacity = 4096) {
+        this.capacity = capacity;
+        if (!Number.isSafeInteger(capacity) || capacity < 1) {
+            throw new Error("relay dedupe capacity must be a positive safe integer");
+        }
+    }
+    has(eventId) {
+        return this.seen.has(eventId);
+    }
+    record(eventId) {
+        if (!eventId)
+            return;
+        this.seen.add(eventId);
+        if (this.seen.size > this.capacity) {
+            const oldest = this.seen.values().next().value;
+            if (oldest !== undefined)
+                this.seen.delete(oldest);
+        }
+    }
+}
+//# sourceMappingURL=memory-dedupe.js.map

package/dist/memory-dedupe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-dedupe.js","sourceRoot":"","sources":["../src/memory-dedupe.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAQ5D,MAAM,OAAO,YAAY;IAGM,QAAQ;IAFpB,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE1C,YAA6B,QAAQ,GAAG,IAAI;wBAAf,QAAQ;QACnC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;IAED,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,MAAM,CAAC,OAAe;QACpB,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvB,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC/C,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;CACF"}

package/dist/poll-loop.d.ts

@@ -0,0 +1,43 @@
+import type { RelayClient } from "./client.js";
+import type { EventDedupe } from "./memory-dedupe.js";
+import type { MessageReceivedData, MessageReceivedEvent, RelayEventEnvelope, RelayOutgoingPart, RelaySendResult } from "./types.js";
+export type ReplyOptions = {
+    /**
+     * Render the reply as a quoted reply bubble referencing the inbound message.
+     * Off by default: plain sends match the shipped OpenClaw integration.
+     */
+    quote?: boolean;
+};
+export type MessageHandlerContext = {
+    event: MessageReceivedEvent;
+    message: MessageReceivedData["message"];
+    invocationId?: string;
+    client: RelayClient;
+    reply: {
+        text: (text: string, options?: ReplyOptions) => Promise<RelaySendResult>;
+        parts: (parts: RelayOutgoingPart[], options?: ReplyOptions) => Promise<RelaySendResult>;
+    };
+    responding: (label?: string) => Promise<void>;
+    typing: (started?: boolean, label?: string) => Promise<void>;
+};
+export type PollLoopParams = {
+    client: RelayClient;
+    getCursor: () => number;
+    setCursor: (cursor: number) => void | Promise<void>;
+    dedupe: EventDedupe;
+    onMessage: (ctx: MessageHandlerContext) => Promise<void> | void;
+    /** Drop events whose sender is not allowed. Default: allow all users. */
+    allowSender?: (senderId: string) => boolean;
+    shouldProcess?: (event: RelayEventEnvelope) => boolean;
+    timeoutSeconds?: number;
+    limit?: number;
+    abortSignal?: AbortSignal;
+    log?: (line: string) => void;
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    random?: () => number;
+};
+/**
+ * Long-poll receive loop for hosts that cannot expose a public webhook URL.
+ * Webhooks and long polling are mutually exclusive per Agent Token.
+ */
+export declare function runPollLoop(params: PollLoopParams): Promise<void>;

package/dist/poll-loop.js

@@ -0,0 +1,164 @@
+import { RelayApiError, isAbortError } from "./errors.js";
+import { replyIdempotencyKey } from "./idempotency.js";
+const TRANSIENT_BASE_DELAY_MS = 500;
+const TRANSIENT_MAX_DELAY_MS = 30_000;
+function defaultSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function isMessageReceived(event) {
+    return (event.event_type === "message.received" &&
+        typeof event.data === "object" &&
+        event.data !== null &&
+        "message" in event.data &&
+        typeof event.data.message === "object");
+}
+function buildContext(client, event) {
+    const message = event.data.message;
+    const invocationId = event.data.invocation_id;
+    let ordinal = 0;
+    const ctx = {
+        event,
+        message,
+        client,
+        reply: {
+            text: async (text, options) => {
+                const key = replyIdempotencyKey(event.event_id, String(ordinal++));
+                return client.sendText({
+                    conversationId: message.conversation_id,
+                    text,
+                    idempotencyKey: key,
+                    ...(invocationId ? { invocationId } : {}),
+                    ...(options?.quote
+                        ? { replyTo: { message_id: message.id } }
+                        : {}),
+                });
+            },
+            parts: async (parts, options) => {
+                const key = replyIdempotencyKey(event.event_id, String(ordinal++));
+                return client.sendMessage({
+                    conversationId: message.conversation_id,
+                    parts,
+                    idempotencyKey: key,
+                    ...(invocationId ? { invocationId } : {}),
+                    ...(options?.quote
+                        ? { replyTo: { message_id: message.id } }
+                        : {}),
+                });
+            },
+        },
+        responding: async (label) => {
+            await client.setResponding({
+                conversationId: message.conversation_id,
+                messageId: message.id,
+                ...(label ? { label } : {}),
+                ...(invocationId ? { invocationId } : {}),
+            });
+        },
+        typing: async (started = true, label) => {
+            await client.setTyping({
+                conversationId: message.conversation_id,
+                started,
+                ...(label ? { label } : {}),
+                ...(invocationId ? { invocationId } : {}),
+            });
+        },
+    };
+    if (invocationId)
+        ctx.invocationId = invocationId;
+    return ctx;
+}
+/**
+ * Long-poll receive loop for hosts that cannot expose a public webhook URL.
+ * Webhooks and long polling are mutually exclusive per Agent Token.
+ */
+export async function runPollLoop(params) {
+    const signal = params.abortSignal ?? new AbortController().signal;
+    const sleep = params.sleep ?? defaultSleep;
+    const random = params.random ?? Math.random;
+    const log = params.log ?? (() => { });
+    let transientAttempts = 0;
+    const transientDelayMs = () => {
+        const backoff = Math.min(TRANSIENT_MAX_DELAY_MS, TRANSIENT_BASE_DELAY_MS * 2 ** Math.min(transientAttempts, 6));
+        return backoff + Math.floor(random() * 250);
+    };
+    while (!signal.aborted) {
+        let page;
+        try {
+            page = await params.client.pollEvents({
+                cursor: params.getCursor(),
+                timeoutSeconds: params.timeoutSeconds ?? 30,
+                ...(params.limit === undefined ? {} : { limit: params.limit }),
+                signal,
+            });
+        }
+        catch (error) {
+            if (signal.aborted || isAbortError(error))
+                return;
+            if (error instanceof RelayApiError && error.terminal) {
+                // Retrying cannot fix these; surface them to the operator.
+                if (error.status === 410) {
+                    log("[relay] cursor expired (410): the cursor is behind the seven-day " +
+                        "retention ceiling. Reconcile from conversation history; do not " +
+                        "reset the cursor to zero.");
+                }
+                else if (error.status === 422) {
+                    const highest = error.details?.["highest_delivered_cursor"];
+                    log("[relay] cursor ahead of the delivered ledger (422): reconcile " +
+                        "history over REST, then resume from " +
+                        (highest === undefined
+                            ? "error.details.highest_delivered_cursor."
+                            : `cursor ${String(highest)}.`));
+                }
+                else if (error.kind === "conflict") {
+                    log(`[relay] long poll conflict: ${error.message}`);
+                }
+                throw error;
+            }
+            transientAttempts += 1;
+            log(`[relay] transient poll error (attempt ${transientAttempts}): ${String(error)}`);
+            await sleep(transientDelayMs(), signal);
+            continue;
+        }
+        transientAttempts = 0;
+        for (const event of page.events) {
+            if (params.shouldProcess && !params.shouldProcess(event))
+                continue;
+            if (!isMessageReceived(event))
+                continue;
+            if (params.dedupe.has(event.event_id))
+                continue;
+            const sender = event.data.message.sender;
+            if (sender.kind === "agent")
+                continue;
+            if (params.allowSender && sender.kind === "user" && !params.allowSender(sender.id)) {
+                params.dedupe.record(event.event_id);
+                continue;
+            }
+            const ctx = buildContext(params.client, event);
+            try {
+                await params.onMessage(ctx);
+                params.dedupe.record(event.event_id);
+            }
+            catch (error) {
+                log(`[relay] handler failed for ${event.event_id}: ${String(error)}`);
+                throw error;
+            }
+        }
+        await params.setCursor(page.nextCursor);
+    }
+}
+//# sourceMappingURL=poll-loop.js.map

package/dist/poll-loop.js.map

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

package/dist/signature.d.ts

@@ -0,0 +1,18 @@
+export type VerifyWebhookOptions = {
+    toleranceSeconds?: number;
+    nowSeconds?: number;
+};
+/**
+ * Verify a Standard Webhooks signature as Relay signs deliveries:
+ * HMAC-SHA256 over `${webhook-id}.${webhook-timestamp}.${raw body}`.
+ */
+export declare function verifyWebhookSignature(input: {
+    secret: string;
+    payload: string;
+    headers: {
+        "webhook-id": string | null | undefined;
+        "webhook-timestamp": string | null | undefined;
+        "webhook-signature": string | null | undefined;
+    };
+    options?: VerifyWebhookOptions;
+}): Promise<void>;

package/dist/signature.js

@@ -0,0 +1,61 @@
+import { WebhookVerificationError } from "./errors.js";
+const DEFAULT_TOLERANCE_SECONDS = 5 * 60;
+function base64ToBytes(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function decodeSecret(secret) {
+    const raw = secret.startsWith("whsec_") ? secret.slice("whsec_".length) : secret;
+    return base64ToBytes(raw);
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+/**
+ * Verify a Standard Webhooks signature as Relay signs deliveries:
+ * HMAC-SHA256 over `${webhook-id}.${webhook-timestamp}.${raw body}`.
+ */
+export async function verifyWebhookSignature(input) {
+    const id = input.headers["webhook-id"];
+    const timestamp = input.headers["webhook-timestamp"];
+    const signatureHeader = input.headers["webhook-signature"];
+    if (!id || !timestamp || !signatureHeader) {
+        throw new WebhookVerificationError("missing webhook signature headers");
+    }
+    const tolerance = input.options?.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    const now = input.options?.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const ts = Number(timestamp);
+    if (!Number.isFinite(ts)) {
+        throw new WebhookVerificationError("invalid webhook-timestamp");
+    }
+    if (Math.abs(now - ts) > tolerance) {
+        throw new WebhookVerificationError("webhook-timestamp outside tolerance");
+    }
+    const key = await crypto.subtle.importKey("raw", decodeSecret(input.secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const signedContent = `${id}.${timestamp}.${input.payload}`;
+    const expected = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(signedContent)));
+    for (const candidate of signatureHeader.split(" ")) {
+        const [version, value] = candidate.split(",", 2);
+        if (version !== "v1" || !value)
+            continue;
+        let provided;
+        try {
+            provided = base64ToBytes(value);
+        }
+        catch {
+            continue;
+        }
+        if (constantTimeEqual(expected, provided))
+            return;
+    }
+    throw new WebhookVerificationError("no matching v1 signature");
+}
+//# sourceMappingURL=signature.js.map

package/dist/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../src/signature.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAOvD,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,CAAC;AAEzC,SAAS,aAAa,CAAC,KAAa;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;QAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC3E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACjF,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,iBAAiB,CAAC,CAAa,EAAE,CAAa;IACrD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;QAAE,IAAI,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IAC5D,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAS5C;IACC,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrD,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC3D,IAAI,CAAC,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC,eAAe,EAAE,CAAC;QAC1C,MAAM,IAAI,wBAAwB,CAAC,mCAAmC,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,EAAE,gBAAgB,IAAI,yBAAyB,CAAC;IAC/E,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACvE,MAAM,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAC7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,wBAAwB,CAAC,2BAA2B,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC;QACnC,MAAM,IAAI,wBAAwB,CAAC,qCAAqC,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CACvC,KAAK,EACL,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,EAC1B,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAC;IACF,MAAM,aAAa,GAAG,GAAG,EAAE,IAAI,SAAS,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;IAC5D,MAAM,QAAQ,GAAG,IAAI,UAAU,CAC7B,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAC/E,CAAC;IAEF,KAAK,MAAM,SAAS,IAAI,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnD,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACjD,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,KAAK;YAAE,SAAS;QACzC,IAAI,QAAoB,CAAC;QACzB,IAAI,CAAC;YACH,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC;YAAE,OAAO;IACpD,CAAC;IACD,MAAM,IAAI,wBAAwB,CAAC,0BAA0B,CAAC,CAAC;AACjE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+/** Wire types for the Relay v1 developer API used by plugins and examples. */
+export type RelaySender = {
+    kind: "user" | "agent" | "system";
+    id: string;
+    display_name?: string;
+};
+export type RelayOutgoingPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "media";
+    attachment_id?: string;
+    url?: string;
+} | {
+    type: "voice_memo";
+    attachment_id?: string;
+    url?: string;
+    duration_ms?: number;
+} | {
+    type: "link_preview";
+    url: string;
+} | {
+    type: "data";
+    data: Record<string, unknown>;
+};
+export type RelayPart = {
+    type: string;
+    part_index?: number;
+    text?: string;
+    url?: string;
+    attachment_id?: string;
+    duration_ms?: number;
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+export type RelayReplyRef = {
+    message_id: string;
+};
+export type RelayMessage = {
+    id: string;
+    conversation_id: string;
+    sequence: number;
+    sender: RelaySender;
+    parts: RelayPart[];
+    reply_to?: RelayReplyRef | null;
+    fallback_text?: string;
+    status?: string;
+    created_at: string;
+};
+export type RelayEventEnvelope<TData = Record<string, unknown>> = {
+    event_id: string;
+    event_type: string;
+    agent_id: string;
+    created_at: string;
+    data: TData;
+};
+export type MessageReceivedData = {
+    message: RelayMessage;
+    invocation_id?: string;
+};
+export type MessageReceivedEvent = RelayEventEnvelope<MessageReceivedData>;
+export type RelayAgentProfile = {
+    id: string;
+    owner_user_id?: string;
+    handle: string;
+    display_name: string;
+    tagline?: string;
+    avatar_url?: string | null;
+    visibility?: "private" | "unlisted" | "public";
+    created_at?: string;
+};
+export type RelayEventsPage = {
+    events: RelayEventEnvelope[];
+    nextCursor: number;
+};
+/**
+ * The 202 from `POST /v1/messages`. The server splits the accepted parts at
+ * ingest: each visible non-media part becomes its own message, contiguous
+ * media parts stay one media message, and a voice memo always commits alone,
+ * so one send commits one or more messages, in display order.
+ */
+export type RelaySendResult = {
+    messages: RelayMessage[];
+};

package/dist/types.js

@@ -0,0 +1,3 @@
+/** Wire types for the Relay v1 developer API used by plugins and examples. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E"}

package/dist/url.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_RELAY_BASE_URL = "https://api.relayapp.im";
+/**
+ * Validate and canonicalize the API origin before a bearer token can be sent.
+ * Remote origins must use HTTPS. Plain HTTP is allowed only on loopback.
+ */
+export declare function normalizeRelayBaseUrl(raw?: string): string;

package/dist/url.js

@@ -0,0 +1,40 @@
+import { isIP } from "node:net";
+export const DEFAULT_RELAY_BASE_URL = "https://api.relayapp.im";
+function isLoopbackHostname(hostname) {
+    const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    const ipVersion = isIP(normalized);
+    if (ipVersion === 4)
+        return normalized.split(".")[0] === "127";
+    if (ipVersion === 6)
+        return normalized === "::1";
+    return normalized === "localhost" || normalized.endsWith(".localhost");
+}
+/**
+ * Validate and canonicalize the API origin before a bearer token can be sent.
+ * Remote origins must use HTTPS. Plain HTTP is allowed only on loopback.
+ */
+export function normalizeRelayBaseUrl(raw) {
+    const candidate = raw?.trim() || DEFAULT_RELAY_BASE_URL;
+    let url;
+    try {
+        url = new URL(candidate);
+    }
+    catch {
+        throw new Error(`relay: invalid baseUrl ${JSON.stringify(candidate)}`);
+    }
+    if (url.username || url.password) {
+        throw new Error("relay: baseUrl must not contain credentials");
+    }
+    if (url.search || url.hash) {
+        throw new Error("relay: baseUrl must not contain a query or fragment");
+    }
+    if (!/^\/+$/u.test(url.pathname)) {
+        throw new Error("relay: baseUrl must be an origin without a path");
+    }
+    if (url.protocol !== "https:" &&
+        !(url.protocol === "http:" && isLoopbackHostname(url.hostname))) {
+        throw new Error("relay: baseUrl must use HTTPS (HTTP is allowed only for loopback development)");
+    }
+    return url.origin;
+}
+//# sourceMappingURL=url.js.map

package/dist/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../src/url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,MAAM,CAAC,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAEhE,SAAS,kBAAkB,CAAC,QAAgB;IAC1C,MAAM,UAAU,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAClE,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IACnC,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC;IAC/D,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,UAAU,KAAK,KAAK,CAAC;IACjD,OAAO,UAAU,KAAK,WAAW,IAAI,UAAU,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAChD,MAAM,SAAS,GAAG,GAAG,EAAE,IAAI,EAAE,IAAI,sBAAsB,CAAC;IACxD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,IACE,GAAG,CAAC,QAAQ,KAAK,QAAQ;QACzB,CAAC,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAC/D,CAAC;QACD,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@relaymessenger/sdk",
+  "version": "0.2.0",
+  "description": "Relay transport library: HTTPS client, Standard Webhooks verify, durable long-poll, idempotent sends.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/relaymessenger/Relay-SDK.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://docs.relayapp.im",
+  "bugs": {
+    "url": "https://github.com/relaymessenger/Relay-SDK/issues"
+  },
+  "keywords": [
+    "relay",
+    "relaymessenger",
+    "agents",
+    "webhooks",
+    "long-poll"
+  ]
+}