@relaymessenger/openclaw-plugin 0.3.3 → 0.4.0-staging.0

package/src/types.ts

@@ -1,141 +1,12 @@
-// Relay wire types plus the plugin's config and resolved-account shapes. The
-// long-poll receive contract is GET /v1/events?cursor&timeout&limit ->
-// { events, next_cursor }, cursor N acknowledges everything <= N.
-
-export type RelaySender = {
-  kind: "user" | "agent";
-  id: string;
-};
-
-// Inline mention of a conversation participant. Offsets are UTF-16 code
-// units into the part's text, which holds the inserted display name with
-// no "@". Ranges are sorted by start and never overlap.
-export type RelayMentionRange = {
-  start: number;
-  length: number;
-  participant_id: string;
-};
-
-export type RelayTextStyle = "bold" | "italic" | "underline" | "strikethrough" | "monospace" | "spoiler";
-
-// One formatting run over a text part, offsets in UTF-16 code units like
-// mentions. An EMPTY styles array on the part is meaningful: it marks
-// structured plain text as opposed to a legacy Markdown body.
-export type RelayStyleRange = {
-  start: number;
-  length: number;
-  styles: RelayTextStyle[];
-};
-
-export type RelayTextPart = {
-  part_index?: number;
-  type: "text";
-  text: string;
-  mentions?: RelayMentionRange[];
-  styles?: RelayStyleRange[];
-};
-
-export type RelayMediaPart = {
-  part_index?: number;
-  type: "media";
-  url: string;
-  attachment_id?: string;
-  // Pixel dimensions (always paired) and a blurhash placeholder (base83)
-  // to draw before the bytes download.
-  width?: number;
-  height?: number;
-  blur_hash?: string;
-};
-
-export type RelayVoiceMemoPart = {
-  part_index?: number;
-  type: "voice_memo";
-  url: string;
-  attachment_id?: string;
-  duration_ms?: number;
-};
-
-export type RelayLinkPreviewPart = {
-  part_index?: number;
-  type: "link_preview";
-  url: string;
-};
-
-export type RelayDataPart = {
-  part_index?: number;
-  type: "data";
-  data: unknown;
-};
-
-export type RelayPart =
-  | RelayTextPart
-  | RelayMediaPart
-  | RelayVoiceMemoPart
-  | RelayLinkPreviewPart
-  | RelayDataPart;
-
-export type RelayReplyRef = {
-  message_id?: string;
-} | null;
-
-export type RelayMessage = {
-  id: string;
-  conversation_id: string;
-  sequence: number;
-  sender: RelaySender;
-  parts: RelayPart[];
-  reply_to?: RelayReplyRef;
-  fallback_text: string;
-  status: string;
-  created_at: string;
-};
-
-export type RelayEventType =
-  | "message.received"
-  | "reaction.added"
-  | "reaction.removed"
-  | "message.delivered"
-  | "message.read"
-  | (string & {});
-
-export type RelayEvent = {
-  event_id: string;
-  event_type: RelayEventType;
-  agent_id: string;
-  created_at: string;
-  data: {
-    message?: RelayMessage;
-    [key: string]: unknown;
-  };
-};
-
-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: RelayEvent[];
-  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[];
-};
-
-// ---------------------------------------------------------------------------
-// Plugin config (channels.relay) and resolved account.
-// ---------------------------------------------------------------------------
+import type {
+  Chat,
+  ChatHandle,
+  MessageWebhookData,
+  Message,
+  RelayWebhookEnvelope,
+  RelayWebhookEvent,
+} from "@relaymessenger/sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
 
 export type RelayAccountConfig = {
   name?: string;
@@ -143,31 +14,63 @@ export type RelayAccountConfig = {
   token?: string;
   tokenFile?: string;
   baseUrl?: string;
-  allowFrom?: Array<string | number>;
-  pollTimeoutSeconds?: number;
+  allowFrom?: string[];
 };
 
 export type RelayChannelConfig = RelayAccountConfig & {
-  accounts?: Record<string, Partial<RelayAccountConfig>>;
   defaultAccount?: string;
+  accounts?: Record<string, RelayAccountConfig>;
 };
 
-export type RelayCoreConfig = {
-  channels?: {
+export type RelayCoreConfig = OpenClawConfig & {
+  channels?: OpenClawConfig["channels"] & {
     relay?: RelayChannelConfig;
   };
-  session?: {
-    store?: string;
-  };
 };
 
 export type ResolvedRelayAccount = {
   accountId: string;
+  name?: string;
   enabled: boolean;
   configured: boolean;
-  name?: string;
   token: string;
   baseUrl: string;
-  pollTimeoutSeconds: number;
+  allowFrom: string[];
   config: RelayAccountConfig;
 };
+
+export type RelayIngressPayload = {
+  version: 1;
+  rawEvent: string;
+};
+
+export type RelaySnapshot = {
+  version: 1;
+  throughSequence: string;
+  reason: "checkpoint_outside_retention";
+  completedAt: string;
+  chats: Array<{
+    chat: Chat;
+    messages: Message[];
+  }>;
+};
+
+export type RelayMessageReceivedEvent = RelayWebhookEnvelope<
+  MessageWebhookData,
+  "message.received"
+>;
+
+export type RelayInboundFacts = {
+  eventId: string;
+  messageId: string;
+  chatId: string;
+  chatType: "direct" | "group";
+  contactId: string;
+  handle: string;
+  displayName: string;
+  text: string;
+  mentionHandles: string[];
+  ownerHandle?: ChatHandle;
+  replyToId?: string;
+  timestamp?: number;
+};

package/dist/src/account-lock.js

@@ -1,91 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-function processIsLive(pid) {
-    if (!Number.isSafeInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error?.code === "EPERM";
-    }
-}
-function readOwner(path) {
-    try {
-        const value = JSON.parse(readFileSync(path, "utf8"));
-        if (Number.isSafeInteger(value.pid) &&
-            typeof value.nonce === "string" &&
-            typeof value.account_id === "string" &&
-            typeof value.created_at === "string") {
-            return value;
-        }
-    }
-    catch {
-        // Missing/malformed ownership is never deleted in place by a contender.
-    }
-    return undefined;
-}
-/** Atomic filesystem lease preventing two OpenClaw processes polling one agent. */
-export class RelayAccountLock {
-    accountId;
-    lockPath;
-    ownerPath;
-    nonce = randomUUID();
-    held = false;
-    constructor(baseUrl, agentId, accountId, baseDir = join(homedir(), ".openclaw", "relay", "consumer-locks")) {
-        this.accountId = accountId;
-        const key = createHash("sha256").update(`${baseUrl}\0${agentId}`).digest("hex");
-        this.lockPath = join(baseDir, key);
-        this.ownerPath = join(this.lockPath, "owner.json");
-    }
-    acquire() {
-        mkdirSync(join(this.lockPath, ".."), { recursive: true, mode: 0o700 });
-        for (let attempt = 0; attempt < 2; attempt += 1) {
-            try {
-                mkdirSync(this.lockPath, { mode: 0o700 });
-                const owner = {
-                    pid: process.pid,
-                    nonce: this.nonce,
-                    account_id: this.accountId,
-                    created_at: new Date().toISOString(),
-                };
-                writeFileSync(this.ownerPath, `${JSON.stringify(owner)}\n`, { mode: 0o600 });
-                this.held = true;
-                return;
-            }
-            catch (error) {
-                if (error?.code !== "EEXIST")
-                    throw error;
-                const owner = readOwner(this.ownerPath);
-                if (!owner || processIsLive(owner.pid)) {
-                    const claimant = owner
-                        ? `account "${owner.account_id}" (pid ${owner.pid})`
-                        : "an existing process with unreadable ownership";
-                    throw new Error(`relay: this agent already has an active consumer in ${claimant}`);
-                }
-                const stalePath = `${this.lockPath}.stale-${Date.now()}-${randomUUID()}`;
-                try {
-                    renameSync(this.lockPath, stalePath);
-                    rmSync(stalePath, { recursive: true, force: true });
-                }
-                catch (renameError) {
-                    if (renameError?.code !== "ENOENT")
-                        throw renameError;
-                }
-            }
-        }
-        throw new Error("relay: could not acquire the agent consumer lock");
-    }
-    release() {
-        if (!this.held)
-            return;
-        const owner = readOwner(this.ownerPath);
-        if (owner?.nonce === this.nonce && existsSync(this.lockPath)) {
-            rmSync(this.lockPath, { recursive: true, force: true });
-        }
-        this.held = false;
-    }
-}

package/dist/src/client.js

@@ -1,229 +0,0 @@
-// Thin Relay REST client boundary for the standalone OpenClaw channel plugin.
-// Owns the abort-aware long poll, idempotent sends, typing, responding, and
-// read watermarks without loading an OpenClaw runtime in unit tests.
-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
- * to it. Production/custom remote origins must use HTTPS. Plain HTTP remains
- * available only for an explicit loopback development server.
- */
-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;
-}
-/** Classified Relay API failure. `terminal` means operator action (bad token). */
-export class RelayApiError extends Error {
-    status;
-    kind;
-    /** Server error code from the response body (`error.code`), when present. */
-    code;
-    constructor(message, params) {
-        super(message);
-        this.name = "RelayApiError";
-        this.status = params.status;
-        this.kind = params.kind;
-        this.code = params.code;
-    }
-    get terminal() {
-        return this.kind === "auth";
-    }
-    get retryable() {
-        return this.kind === "retryable";
-    }
-}
-/**
- * 409 from the webhook XOR rule: an enabled webhook endpoint makes long
- * polling unavailable until the operator disables it (server code
- * `conflict`, distinct from `terminated_by_other_consumer`).
- */
-export function isRelayWebhookConflict(error) {
-    return (error instanceof RelayApiError &&
-        error.status === 409 &&
-        error.code !== "terminated_by_other_consumer");
-}
-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";
-}
-async function readErrorDetail(response) {
-    try {
-        const body = (await response.json());
-        return {
-            ...(body?.error?.code ? { code: body.error.code } : {}),
-            message: body?.error?.message ?? body?.message ?? "",
-        };
-    }
-    catch {
-        return { message: "" };
-    }
-}
-export function createRelayClient(options) {
-    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));
-            }
-        }
-        let response;
-        const timeoutSignal = AbortSignal.timeout(params.timeoutMs ?? requestTimeoutMs);
-        const signal = params.signal
-            ? AbortSignal.any([params.signal, timeoutSignal])
-            : timeoutSignal;
-        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;
-            }
-            // Network-level failure (DNS, reset, offline): always retryable.
-            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 } : {}),
-            });
-        }
-        return response;
-    };
-    return {
-        getMe: async (params) => {
-            const response = await request({
-                method: "GET",
-                path: "/v1/agents/me",
-                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);
-            // Guard against a wedged connection: the server holds <= timeout seconds,
-            // so anything past timeout + slack is a dead socket, not a slow poll.
-            const response = await request({
-                method: "GET",
-                path: "/v1/events",
-                query: {
-                    cursor: params.cursor,
-                    timeout: timeoutSeconds,
-                    ...(params.limit === undefined ? {} : { limit: params.limit }),
-                },
-                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.replyTo ? { reply_to: params.replyTo } : {}),
-                },
-                signal: params.signal,
-            });
-            const body = (await response.json());
-            return { messages: body.messages };
-        },
-        setTyping: async (params) => {
-            await request({
-                method: "POST",
-                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/typing`,
-                body: {
-                    started: params.started,
-                    ...(params.label ? { label: params.label } : {}),
-                },
-                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 } : {}),
-                },
-                signal: params.signal,
-            });
-        },
-        markRead: async (params) => {
-            await request({
-                method: "POST",
-                path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/read`,
-                body: { message_id: params.messageId },
-                signal: params.signal,
-            });
-        },
-    };
-}

package/dist/src/cursor-store.js

@@ -1,136 +0,0 @@
-// Persisted long-poll cursor, Telegram-offset style:
-// monotonic writes only, bound to the agent identity so a token that now
-// resolves to a different agent discards the stale cursor instead of acking
-// another contact's event stream.
-import { createHash } from "node:crypto";
-import { assertRelayStateDocument, emptyRelayStateDocument, openRelayStateDocument, } from "./state-files.js";
-export const RELAY_CURSOR_MAX_ENTRIES = 1_000;
-export const RELAY_CURSOR_OVERFLOW_POLICY = "reject-new";
-const RECORD_VERSION = 2;
-/**
- * Open Relay's private, lock-protected state file with fail-closed capacity
- * semantics. A cursor is permanent safety state: evicting an old identity to
- * admit a new one could replay retained events when the old identity returns.
- */
-export function openRelayCursorStateStore(warn, options = {}) {
-    const maxEntries = options.maxEntries ?? RELAY_CURSOR_MAX_ENTRIES;
-    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
-        throw new Error("relay cursor maxEntries must be a positive safe integer");
-    }
-    const store = openRelayStateDocument({
-        fileName: "cursors.json",
-        ...(options.env ? { env: options.env } : {}),
-    });
-    const storageKey = (key) => createHash("sha256").update(key).digest("hex");
-    const validateEntry = (key, value) => {
-        if (!/^[a-f0-9]{64}$/u.test(key) || !value || typeof value !== "object")
-            return false;
-        const record = value;
-        return (record.version === RECORD_VERSION &&
-            isValidCursor(record.cursor) &&
-            typeof record.baseUrl === "string" &&
-            (() => {
-                try {
-                    return new URL(record.baseUrl).origin === record.baseUrl;
-                }
-                catch {
-                    return false;
-                }
-            })() &&
-            typeof record.agentId === "string" &&
-            record.agentId.length > 0);
-    };
-    const read = async () => {
-        try {
-            const current = await store.read();
-            if (current === undefined)
-                return emptyRelayStateDocument();
-            assertRelayStateDocument(current, "cursor", validateEntry);
-            return current;
-        }
-        catch (error) {
-            warn(`[relay] cursor state unavailable; refusing unsafe cursor reset: ${String(error)}`);
-            throw error;
-        }
-    };
-    return {
-        lookup: async (key) => (await read()).entries[storageKey(key)],
-        register: async (key, value) => {
-            try {
-                await store.updateOr(emptyRelayStateDocument(), (current) => {
-                    assertRelayStateDocument(current, "cursor", validateEntry);
-                    const hashedKey = storageKey(key);
-                    if (!Object.hasOwn(current.entries, hashedKey) &&
-                        Object.keys(current.entries).length >= maxEntries) {
-                        throw new Error(`relay cursor state reached ${maxEntries} identities (${RELAY_CURSOR_OVERFLOW_POLICY})`);
-                    }
-                    return {
-                        version: current.version,
-                        entries: { ...current.entries, [hashedKey]: value },
-                    };
-                });
-            }
-            catch (error) {
-                warn(`[relay] cursor state unavailable; refusing unsafe cursor reset: ${String(error)}`);
-                throw error;
-            }
-        },
-    };
-}
-function isValidCursor(value) {
-    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-export function createRelayCursorStore(params) {
-    const baseUrl = new URL(params.baseUrl).origin;
-    const key = `relay:${baseUrl}:${params.agentId}`;
-    let cursor = 0;
-    let loaded = false;
-    return {
-        load: async () => {
-            let record;
-            try {
-                record = await params.store.lookup(key);
-            }
-            catch (error) {
-                params.onPersistError?.(error);
-                throw new Error(`relay cursor state could not be loaded: ${String(error)}`);
-            }
-            if (!record) {
-                cursor = 0;
-                loaded = true;
-                return cursor;
-            }
-            if (record.version !== RECORD_VERSION ||
-                !isValidCursor(record.cursor) ||
-                record.agentId !== params.agentId ||
-                record.baseUrl !== baseUrl) {
-                throw new Error(`relay cursor state is corrupt for ${baseUrl} ${params.agentId}; refusing cursor-zero replay`);
-            }
-            cursor = record.cursor;
-            loaded = true;
-            return cursor;
-        },
-        current: () => cursor,
-        advance: async (next) => {
-            if (!loaded) {
-                throw new Error("relay cursor store: advance() before load()");
-            }
-            if (!isValidCursor(next) || next <= cursor) {
-                return;
-            }
-            try {
-                await params.store.register(key, {
-                    version: RECORD_VERSION,
-                    cursor: next,
-                    baseUrl,
-                    agentId: params.agentId,
-                });
-            }
-            catch (error) {
-                params.onPersistError?.(error);
-                throw new Error(`relay cursor advance was not durable: ${String(error)}`);
-            }
-            cursor = next;
-        },
-    };
-}