@relaymessenger/openclaw-plugin 0.3.0 → 0.3.4

package/src/vendor/relay-sdk/client.ts

@@ -0,0 +1,293 @@
+import {
+  RelayApiError,
+  classifyRelayHttpStatus,
+  isAbortError,
+} from "./errors.js";
+import type {
+  RelayAgentProfile,
+  RelayEventsPage,
+  RelayOutgoingPart,
+  RelayReplyRef,
+  RelaySendResult,
+} from "./types.js";
+import { normalizeRelayBaseUrl } from "./url.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>;
+  /**
+   * Advance the delivered watermark to `messageId`, and every earlier message
+   * from other participants with it.
+   *
+   * Most agents never call this. Delivered means the agent's endpoint has the
+   * message, so Relay records it from the transport itself: a webhook gets it
+   * when the endpoint answers `2xx`, and a `GET /v1/events` consumer gets it
+   * when the cursor moves past the event. Neither needs a line of code, and
+   * neither can suppress it.
+   *
+   * The exception is a transcript poller — a client that reads
+   * `GET /v1/conversations/:id/messages` on a timer. Reading history records
+   * no receipt, so nothing on the server ever learns the message arrived.
+   * That client, and only that client, has to say so itself.
+   *
+   * Send it on ingest, before anything that implies a read. The server
+   * advances the delivered watermark whenever it records a read, so a
+   * delivered receipt that arrives after a read for the same message is
+   * silently dropped: the sender goes straight from "Sent" to "Read" and never
+   * sees "Delivered". Skipping this call costs the middle rung of the ladder,
+   * not the top one.
+   */
+  markDelivered: (params: {
+    conversationId: string;
+    messageId: string;
+    signal?: AbortSignal;
+  }) => Promise<void>;
+  markRead: (params: {
+    conversationId: string;
+    messageId: string;
+    signal?: AbortSignal;
+  }) => Promise<void>;
+};
+
+async function readErrorDetail(response: Response): Promise<{
+  code?: string;
+  message: string;
+  details?: Record<string, unknown>;
+}> {
+  try {
+    const body = (await response.json()) as {
+      error?: { code?: string; message?: string; details?: Record<string, unknown> };
+      message?: string;
+    };
+    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: RelayClientOptions): RelayClient {
+  if (!options.token.trim()) {
+    throw new Error("relay: Agent Token is required");
+  }
+  const baseUrl = normalizeRelayBaseUrl(options.baseUrl);
+  const fetchImpl: FetchLike =
+    options.fetchImpl ?? ((input, init) => fetch(input, init));
+  const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
+
+  const request = async (params: {
+    method: string;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+  }): Promise<Response> => {
+    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: 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: RelayClient = {
+    baseUrl,
+
+    getMe: async (params) => {
+      const response = await request({
+        method: "GET",
+        path: "/v1/agents/me",
+        ...(params?.signal ? { signal: params.signal } : {}),
+      });
+      const body = (await response.json()) as { agent: RelayAgentProfile };
+      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()) as {
+        events?: RelayEventsPage["events"];
+        next_cursor?: number;
+      };
+      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()) as {
+        messages: RelaySendResult["messages"];
+      };
+      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 } : {}),
+      });
+    },
+
+    markDelivered: async (params) => {
+      await request({
+        method: "POST",
+        path: `/v1/conversations/${encodeURIComponent(params.conversationId)}/delivered`,
+        body: { message_id: params.messageId },
+        ...(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;
+}

package/src/vendor/relay-sdk/errors.ts

@@ -0,0 +1,61 @@
+export type RelayApiErrorKind = "auth" | "conflict" | "retryable" | "rejected";
+
+/** Classified Relay API failure. `terminal` means retrying the same request cannot succeed. */
+export 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>;
+    },
+  ) {
+    super(message);
+    this.name = "RelayApiError";
+    this.status = params.status;
+    this.kind = params.kind;
+    this.code = params.code;
+    this.details = params.details;
+  }
+
+  get terminal(): boolean {
+    return this.kind !== "retryable";
+  }
+
+  get retryable(): boolean {
+    return this.kind === "retryable";
+  }
+}
+
+export class WebhookVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WebhookVerificationError";
+  }
+}
+
+export function classifyRelayHttpStatus(status: number): RelayApiErrorKind {
+  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: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}
+
+export function isRelayWebhookConflict(error: unknown): error is RelayApiError {
+  return (
+    error instanceof RelayApiError &&
+    error.status === 409 &&
+    error.code !== "terminated_by_other_consumer"
+  );
+}

package/src/vendor/relay-sdk/types.ts

@@ -0,0 +1,82 @@
+/** 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/src/vendor/relay-sdk/url.ts

@@ -0,0 +1,43 @@
+import { isIP } from "node:net";
+
+export const DEFAULT_RELAY_BASE_URL = "https://api.relayapp.im";
+
+function isLoopbackHostname(hostname: string): boolean {
+  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?: string): string {
+  const candidate = raw?.trim() || DEFAULT_RELAY_BASE_URL;
+  let url: 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;
+}