@cored-im/openclaw-plugin 0.1.0

package/src/messaging/outbound.ts

@@ -0,0 +1,176 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Outbound message delivery — send text/typing/read to Cored chats.
+ *
+ * Pipeline: normalize target -> validate account/client -> send -> map errors
+ *
+ * Text-only for now; media/card/file delivery is follow-up (task 08).
+ */
+
+import {
+  getClient,
+  isAuthError,
+  MessageType_TEXT,
+  type ManagedClient,
+  type SendMessageReq,
+} from "../core/cored-client.js";
+
+// ---------------------------------------------------------------------------
+// Send text
+// ---------------------------------------------------------------------------
+
+export interface SendTextResult {
+  ok: boolean;
+  messageId?: string;
+  error?: Error;
+  provider?: string;
+}
+
+/**
+ * Send a text message to a Cored chat.
+ *
+ * On auth error (code 40000006), forces a token refresh via preheat() and
+ * retries once. This handles the SDK's token-refresh edge case without
+ * requiring a gateway restart.
+ */
+export async function sendText(
+  chatId: string,
+  text: string,
+  accountId?: string,
+  replyMessageId?: string,
+  logWarn?: (msg: string) => void,
+): Promise<SendTextResult> {
+  const managed = getClient(accountId);
+  if (!managed) {
+    return {
+      ok: false,
+      error: new Error(
+        `[cored] no connected client for account=${accountId ?? "default"}`,
+      ),
+    };
+  }
+
+  const req: SendMessageReq = {
+    chat_id: chatId,
+    message_type: MessageType_TEXT,
+    message_content: {
+      text: { content: text },
+    },
+    reply_message_id: replyMessageId,
+  };
+
+  try {
+    const resp = await managed.client.Im.v1.Message.sendMessage(req);
+    return { ok: true, messageId: resp.message_id, provider: "cored" };
+  } catch (err) {
+    if (!isAuthError(err)) {
+      return {
+        ok: false,
+        error: new Error(
+          `[cored] send failed for chat=${chatId}: ${err instanceof Error ? err.message : String(err)}`,
+        ),
+      };
+    }
+
+    // Auth token expired despite SDK auto-refresh — force refresh and retry once.
+    // This avoids requiring a gateway restart when the SDK's background token
+    // refresh hits an edge case (time sync drift, swallowed fetch failure, etc.).
+    logWarn?.(
+      `[cored] auth error on send (chat=${chatId}, account=${accountId ?? "default"}) — refreshing token and retrying`,
+    );
+
+    try {
+      await managed.client.preheat();
+      const resp = await managed.client.Im.v1.Message.sendMessage(req);
+      logWarn?.(
+        `[cored] auth retry succeeded (chat=${chatId}, account=${accountId ?? "default"})`,
+      );
+      return { ok: true, messageId: resp.message_id, provider: "cored" };
+    } catch (retryErr) {
+      return {
+        ok: false,
+        error: new Error(
+          `[cored] send failed after auth retry for chat=${chatId}: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`,
+        ),
+      };
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Typing indicator
+// ---------------------------------------------------------------------------
+
+/**
+ * Set typing indicator in a chat. Cored typing lasts ~5s.
+ */
+export async function setTyping(
+  chatId: string,
+  accountId?: string,
+): Promise<void> {
+  const managed = getClient(accountId);
+  if (!managed) return;
+  try {
+    await managed.client.Im.v1.Chat.createTyping({ chat_id: chatId });
+  } catch {
+    // Typing is best-effort — don't fail the message flow
+  }
+}
+
+/**
+ * Clear typing indicator.
+ */
+export async function clearTyping(
+  chatId: string,
+  accountId?: string,
+): Promise<void> {
+  const managed = getClient(accountId);
+  if (!managed) return;
+  try {
+    await managed.client.Im.v1.Chat.deleteTyping({ chat_id: chatId });
+  } catch {
+    // Best-effort
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Read receipt
+// ---------------------------------------------------------------------------
+
+/**
+ * Mark a message as read.
+ */
+export async function readMessage(
+  messageId: string,
+  accountId?: string,
+): Promise<void> {
+  const managed = getClient(accountId);
+  if (!managed) return;
+  try {
+    await managed.client.Im.v1.Message.readMessage({ message_id: messageId });
+  } catch {
+    // Best-effort
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Delivery callback for inbound dispatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a deliver function scoped to an account, suitable for passing
+ * to processInboundMessage's InboundDispatchOptions.
+ */
+export function makeDeliver(
+  accountId?: string,
+  logWarn?: (msg: string) => void,
+): (chatId: string, text: string) => Promise<void> {
+  return async (chatId: string, text: string) => {
+    const result = await sendText(chatId, text, accountId, undefined, logWarn);
+    if (!result.ok) {
+      throw result.error ?? new Error("[cored] send failed");
+    }
+  };
+}

package/src/targets.test.ts

@@ -0,0 +1,91 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it, expect } from "vitest";
+import { parseTarget } from "./targets.js";
+
+describe("parseTarget", () => {
+  // --- Happy paths ---
+
+  it('parses "user:<id>"', () => {
+    expect(parseTarget("user:abc123")).toEqual({ kind: "user", id: "abc123" });
+  });
+
+  it('parses "chat:<id>"', () => {
+    expect(parseTarget("chat:oc_xyz")).toEqual({ kind: "chat", id: "oc_xyz" });
+  });
+
+  it('strips "cored:" prefix and parses "chat:<id>"', () => {
+    expect(parseTarget("cored:chat:oc_xyz")).toEqual({
+      kind: "chat",
+      id: "oc_xyz",
+    });
+  });
+
+  it('strips "cored:" prefix and parses "user:<id>"', () => {
+    expect(parseTarget("cored:user:abc")).toEqual({
+      kind: "user",
+      id: "abc",
+    });
+  });
+
+  it("strips cored: prefix case-insensitively", () => {
+    expect(parseTarget("CORED:chat:oc_1")).toEqual({
+      kind: "chat",
+      id: "oc_1",
+    });
+    expect(parseTarget("Cored:user:u1")).toEqual({ kind: "user", id: "u1" });
+  });
+
+  it("defaults bare ID to chat", () => {
+    expect(parseTarget("oc_abc123")).toEqual({
+      kind: "chat",
+      id: "oc_abc123",
+    });
+  });
+
+  it("defaults bare numeric ID to chat", () => {
+    expect(parseTarget("83870344313569283")).toEqual({
+      kind: "chat",
+      id: "83870344313569283",
+    });
+  });
+
+  it("trims whitespace", () => {
+    expect(parseTarget("  chat:oc_1  ")).toEqual({
+      kind: "chat",
+      id: "oc_1",
+    });
+    expect(parseTarget("  user:abc  ")).toEqual({ kind: "user", id: "abc" });
+  });
+
+  // --- Null/invalid cases ---
+
+  it("returns null for undefined", () => {
+    expect(parseTarget(undefined)).toBeNull();
+  });
+
+  it("returns null for empty string", () => {
+    expect(parseTarget("")).toBeNull();
+  });
+
+  it("returns null for whitespace-only", () => {
+    expect(parseTarget("   ")).toBeNull();
+  });
+
+  it('returns null for "user:" with no ID', () => {
+    expect(parseTarget("user:")).toBeNull();
+  });
+
+  it('returns null for "chat:" with no ID', () => {
+    expect(parseTarget("chat:")).toBeNull();
+  });
+
+  it('returns null for "user: " (whitespace-only ID)', () => {
+    expect(parseTarget("user:  ")).toBeNull();
+  });
+
+  it('returns null for "cored:" with nothing after', () => {
+    expect(parseTarget("cored:")).toBeNull();
+  });
+});

package/src/targets.ts

@@ -0,0 +1,41 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Target parsing & validation for the --to argument.
+ *
+ * Accepted formats:
+ *   "chat:oc_abc123"         -> { kind: "chat", id: "oc_abc123" }
+ *   "user:83870344313569283" -> { kind: "user", id: "83870344313569283" }
+ *   "cored:chat:oc_abc123"  -> { kind: "chat", id: "oc_abc123" }  (prefix stripped)
+ *   "oc_abc123"              -> { kind: "chat", id: "oc_abc123" }   (bare ID defaults to chat)
+ *
+ * Returns null for empty, whitespace-only, or malformed targets (e.g. "user:" with no ID).
+ */
+
+import type { ParsedTarget } from "./types.js";
+
+/**
+ * Parse a raw --to string into a structured target.
+ * Returns null if the input is missing, empty, or has no usable ID.
+ */
+export function parseTarget(to?: string): ParsedTarget | null {
+  const raw = String(to ?? "").trim();
+  if (!raw) return null;
+
+  // Strip optional "cored:" channel prefix (case-insensitive)
+  const stripped = raw.replace(/^cored:/i, "");
+
+  if (stripped.startsWith("user:")) {
+    const id = stripped.slice("user:".length).trim();
+    return id ? { kind: "user", id } : null;
+  }
+
+  if (stripped.startsWith("chat:")) {
+    const id = stripped.slice("chat:".length).trim();
+    return id ? { kind: "chat", id } : null;
+  }
+
+  // Bare ID — default to chat (Cored SDK uses ChatId for sending)
+  return stripped ? { kind: "chat", id: stripped } : null;
+}

package/src/types.test.ts

@@ -0,0 +1,10 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it, expect } from "vitest";
+
+describe("project setup", () => {
+  it("builds and runs tests", () => {
+    expect(true).toBe(true);
+  });
+});

package/src/types.ts

@@ -0,0 +1,115 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+// --- Plugin Config Types ---
+
+export interface CoredAccountConfig {
+  accountId: string;
+  enabled: boolean;
+  appId: string;
+  appSecret: string;
+  backendUrl: string;
+  enableEncryption: boolean;
+  requestTimeout: number;
+  requireMention: boolean;
+  botUserId?: string;
+  inboundWhitelist: string[];
+}
+
+export interface CoredRawAccountConfig {
+  appId?: string;
+  appSecret?: string;
+  backendUrl?: string;
+  enableEncryption?: boolean;
+  requestTimeout?: number;
+  requireMention?: boolean;
+  enabled?: boolean;
+  botUserId?: string;
+  inboundWhitelist?: string[];
+}
+
+export interface CoredChannelConfig {
+  appId?: string;
+  appSecret?: string;
+  backendUrl?: string;
+  enableEncryption?: boolean;
+  requestTimeout?: number;
+  requireMention?: boolean;
+  enabled?: boolean;
+  botUserId?: string;
+  inboundWhitelist?: string[];
+  accounts?: Record<string, CoredRawAccountConfig>;
+}
+
+// --- Cored Event Types ---
+
+export interface CoredUserId {
+  userId: string;
+  unionUserId?: string;
+  openUserId?: string;
+}
+
+export interface CoredMessage {
+  messageId: string;
+  messageType: string;
+  messageContent: unknown;
+  chatId: string;
+  chatType: string;
+  sender: CoredUserId;
+  createdAt: number;
+  mentionUserList?: CoredUserId[];
+}
+
+export interface CoredMessageEvent {
+  message: CoredMessage;
+}
+
+// --- Target Types ---
+
+export interface ParsedTarget {
+  kind: "user" | "chat";
+  id: string;
+}
+
+// --- Connection Types ---
+
+export type ConnectionState =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "disconnecting";
+
+// --- OpenClaw Plugin API (minimal type surface) ---
+
+export interface PluginApi {
+  registerChannel(opts: { plugin: unknown }): void;
+  registerService(opts: {
+    id: string;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+  }): void;
+  config: { channels?: { cored?: CoredChannelConfig } } & Record<
+    string,
+    unknown
+  >;
+  runtime: {
+    channel: {
+      reply: {
+        dispatchReplyWithBufferedBlockDispatcher: (opts: unknown) => Promise<void>;
+      };
+      session: {
+        recordInboundSession: (opts: unknown) => Promise<void>;
+        resolveStorePath?: (store: unknown, opts: unknown) => string;
+      };
+      routing: {
+        resolveAgentRoute: (opts: unknown) => unknown;
+      };
+    };
+  };
+  logger?: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    debug: (msg: string) => void;
+  };
+}

package/src/typings/cored-sdk.d.ts

@@ -0,0 +1,23 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Re-export types from @cored-im/sdk used across the plugin.
+ *
+ * The published SDK ships its own type declarations. This file exists
+ * only to keep the rest of the plugin importing from a single local
+ * barrel, making future SDK swaps cheaper.
+ */
+export type {
+  CoredClient,
+  CoredClientOptions,
+} from "@cored-im/sdk";
+
+export {
+  LoggerLevel,
+} from "@cored-im/sdk";
+
+export type {
+  Logger,
+  EventHeader,
+} from "@cored-im/sdk";