@soyeht/soyeht 0.1.1

package/src/openclaw-plugin-sdk.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Minimal type declarations for openclaw/plugin-sdk.
+ * Only the types used by the soyeht plugin are declared here.
+ * The full types live in the OpenClaw monorepo.
+ */
+declare module "openclaw/plugin-sdk" {
+  // ---- Config ----
+  export type OpenClawConfig = Record<string, unknown>;
+
+  // ---- Channel types ----
+  export type ChannelId = string;
+
+  export type ChannelMeta = {
+    id: ChannelId;
+    label: string;
+    selectionLabel: string;
+    docsPath: string;
+    blurb: string;
+    order?: number;
+    aliases?: string[];
+    systemImage?: string;
+    [key: string]: unknown;
+  };
+
+  export type ChatType = "direct" | "group" | "thread";
+
+  export type ChannelCapabilities = {
+    chatTypes: Array<ChatType | "thread">;
+    media?: boolean;
+    polls?: boolean;
+    reactions?: boolean;
+    edit?: boolean;
+    unsend?: boolean;
+    reply?: boolean;
+    threads?: boolean;
+    [key: string]: unknown;
+  };
+
+  export type ChannelConfigAdapter<ResolvedAccount> = {
+    listAccountIds: (cfg: OpenClawConfig) => string[];
+    resolveAccount: (
+      cfg: OpenClawConfig,
+      accountId?: string | null,
+    ) => ResolvedAccount;
+    defaultAccountId?: (cfg: OpenClawConfig) => string;
+    isEnabled?: (account: ResolvedAccount, cfg: OpenClawConfig) => boolean;
+    isConfigured?: (
+      account: ResolvedAccount,
+      cfg: OpenClawConfig,
+    ) => boolean | Promise<boolean>;
+    describeAccount?: (account: ResolvedAccount, cfg: OpenClawConfig) => Record<string, unknown>;
+    [key: string]: unknown;
+  };
+
+  export type OutboundDeliveryResult = {
+    channel: string;
+    messageId: string;
+    chatId?: string;
+    meta?: Record<string, unknown>;
+  };
+
+  export type ChannelOutboundContext = {
+    cfg: OpenClawConfig;
+    to: string;
+    text: string;
+    mediaUrl?: string;
+    accountId?: string | null;
+    identity?: unknown;
+    deps?: unknown;
+    silent?: boolean;
+    [key: string]: unknown;
+  };
+
+  export type ChannelOutboundAdapter = {
+    deliveryMode: "direct" | "gateway" | "hybrid";
+    sendText?: (ctx: ChannelOutboundContext) => Promise<OutboundDeliveryResult>;
+    sendMedia?: (ctx: ChannelOutboundContext) => Promise<OutboundDeliveryResult>;
+    [key: string]: unknown;
+  };
+
+  export type ChannelPlugin<ResolvedAccount = unknown> = {
+    id: ChannelId;
+    meta: ChannelMeta;
+    capabilities: ChannelCapabilities;
+    configSchema?: { schema: Record<string, unknown> };
+    reload?: { configPrefixes?: string[] };
+    config: ChannelConfigAdapter<ResolvedAccount>;
+    outbound?: ChannelOutboundAdapter;
+    [key: string]: unknown;
+  };
+
+  export type ChannelRegistration<ResolvedAccount = unknown> = {
+    plugin: ChannelPlugin<ResolvedAccount>;
+    dock?: unknown;
+    [key: string]: unknown;
+  };
+
+  // ---- Gateway types ----
+  export type ErrorShape = {
+    code?: string;
+    message?: string;
+    [key: string]: unknown;
+  };
+
+  export type RespondFn = (
+    ok: boolean,
+    payload?: unknown,
+    error?: ErrorShape,
+    meta?: Record<string, unknown>,
+  ) => void;
+
+  export type GatewayRequestHandlerOptions = {
+    req: unknown;
+    params: Record<string, unknown>;
+    client: unknown | null;
+    respond: RespondFn;
+    context: unknown;
+    [key: string]: unknown;
+  };
+
+  export type GatewayRequestHandler = (
+    opts: GatewayRequestHandlerOptions,
+  ) => Promise<void> | void;
+
+  // ---- Plugin types ----
+  export type PluginLogger = {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+  };
+
+  export type TtsTelephonyResult = {
+    success: boolean;
+    audioBuffer?: Buffer;
+    error?: string;
+    latencyMs?: number;
+    provider?: string;
+    outputFormat?: string;
+    sampleRate?: number;
+  };
+
+  export type PluginRuntime = {
+    config: {
+      loadConfig: () => Promise<OpenClawConfig>;
+      [key: string]: unknown;
+    };
+    stt: {
+      transcribeAudioFile: (params: {
+        filePath: string;
+        cfg: OpenClawConfig;
+        agentDir?: string;
+        mime?: string;
+      }) => Promise<{ text: string | undefined }>;
+    };
+    tts: {
+      textToSpeechTelephony: (params: {
+        text: string;
+        cfg: OpenClawConfig;
+        prefsPath?: string;
+      }) => Promise<TtsTelephonyResult>;
+    };
+    [key: string]: unknown;
+  };
+
+  export type OpenClawPluginServiceContext = {
+    config: OpenClawConfig;
+    workspaceDir?: string;
+    stateDir: string;
+    logger: PluginLogger;
+  };
+
+  export type OpenClawPluginService = {
+    id: string;
+    start: (ctx?: OpenClawPluginServiceContext) => void | Promise<void>;
+    stop?: (ctx?: OpenClawPluginServiceContext) => void | Promise<void>;
+  };
+
+  export type OpenClawPluginHttpRouteHandler = (
+    req: import("node:http").IncomingMessage,
+    res: import("node:http").ServerResponse,
+  ) => Promise<boolean | void> | boolean | void;
+
+  export type OpenClawPluginApi = {
+    id: string;
+    name: string;
+    runtime: PluginRuntime;
+    logger: PluginLogger;
+    registerChannel: (registration: ChannelRegistration | unknown) => void;
+    registerGatewayMethod: (
+      method: string,
+      handler: GatewayRequestHandler,
+    ) => void;
+    registerHttpRoute: (params: {
+      path: string;
+      handler: OpenClawPluginHttpRouteHandler;
+      auth: "gateway" | "plugin";
+      match?: "exact" | "prefix";
+    }) => void;
+    registerService: (service: OpenClawPluginService) => void;
+    [key: string]: unknown;
+  };
+
+  // ---- Account helpers ----
+  export function listConfiguredAccountIds(params: {
+    accounts: Record<string, unknown> | undefined;
+    normalizeAccountId: (accountId: string) => string;
+  }): string[];
+}

package/src/outbound.ts

@@ -0,0 +1,198 @@
+import { randomUUID } from "node:crypto";
+import type { OutboundEnvelope, TextMessagePayload, AudioMessagePayload, FileMessagePayload } from "./types.js";
+import { encryptEnvelopeV2 } from "./envelope-v2.js";
+import type { RatchetState, DhRatchetConfig } from "./ratchet.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type OutboundDeliveryResult = {
+  channel: string;
+  messageId: string;
+  chatId?: string;
+  meta?: Record<string, unknown>;
+};
+
+export type DeliverTextParams = {
+  backendBaseUrl: string;
+  pluginAuthToken: string;
+  accountId: string;
+  sessionId: string;
+  to: string;
+  text: string;
+};
+
+export type DeliverAudioParams = {
+  backendBaseUrl: string;
+  pluginAuthToken: string;
+  accountId: string;
+  sessionId: string;
+  to: string;
+  url: string;
+  mimeType: string;
+  filename: string;
+  durationMs?: number;
+  transcript?: string;
+};
+
+export type DeliverFileParams = {
+  backendBaseUrl: string;
+  pluginAuthToken: string;
+  accountId: string;
+  sessionId: string;
+  to: string;
+  url: string;
+  mimeType: string;
+  filename: string;
+  sizeBytes?: number;
+};
+
+// ---------------------------------------------------------------------------
+// Envelope builder
+// ---------------------------------------------------------------------------
+
+export function buildOutboundEnvelope(
+  accountId: string,
+  sessionId: string,
+  message: TextMessagePayload | AudioMessagePayload | FileMessagePayload,
+): OutboundEnvelope {
+  return {
+    accountId,
+    sessionId,
+    deliveryId: randomUUID(),
+    timestamp: Date.now(),
+    message,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// HTTP POST to backend
+// ---------------------------------------------------------------------------
+
+export type PostToBackendOptions = {
+  ratchetSession?: RatchetState;
+  dhRatchetCfg?: DhRatchetConfig;
+  onSessionUpdated?: (updated: RatchetState) => void;
+  securityEnabled?: boolean;
+};
+
+export async function postToBackend(
+  backendBaseUrl: string,
+  pluginAuthToken: string,
+  envelope: OutboundEnvelope,
+  opts: PostToBackendOptions = {},
+): Promise<OutboundDeliveryResult> {
+  const url = `${backendBaseUrl.replace(/\/+$/, "")}/api/v1/messages/deliver`;
+
+  let body: string;
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${pluginAuthToken}`,
+    "X-Soyeht-Delivery-Id": envelope.deliveryId,
+  };
+
+  if (opts.ratchetSession) {
+    // V2 path — fail-closed: reject expired sessions
+    if (opts.ratchetSession.expiresAt < Date.now()) {
+      return {
+        channel: "soyeht",
+        messageId: envelope.deliveryId,
+        meta: { error: true, reason: "session_expired" },
+      };
+    }
+    const dhRatchetCfg = opts.dhRatchetCfg ?? { intervalMessages: 50, intervalMs: 3_600_000 };
+    const { envelope: v2env, updatedSession } = encryptEnvelopeV2({
+      session: opts.ratchetSession,
+      accountId: envelope.accountId,
+      plaintext: JSON.stringify(envelope),
+      dhRatchetCfg,
+    });
+    opts.onSessionUpdated?.(updatedSession);
+    body = JSON.stringify(v2env);
+    headers["X-Soyeht-Version"] = "2";
+    headers["X-Soyeht-Account-Id"] = v2env.accountId;
+    headers["X-Soyeht-Direction"] = v2env.direction;
+    headers["X-Soyeht-Counter"] = String(v2env.counter);
+    headers["X-Soyeht-Timestamp"] = String(v2env.timestamp);
+    if (v2env.dhRatchetKey) headers["X-Soyeht-Dh-Ratchet-Key"] = v2env.dhRatchetKey;
+  } else if (opts.securityEnabled) {
+    // Fail-closed: security required but no session
+    return {
+      channel: "soyeht",
+      messageId: envelope.deliveryId,
+      meta: { error: true, reason: "session_required" },
+    };
+  } else {
+    body = JSON.stringify(envelope);
+  }
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body,
+    signal: AbortSignal.timeout(15_000),
+  });
+
+  if (!res.ok) {
+    return {
+      channel: "soyeht",
+      messageId: envelope.deliveryId,
+      meta: {
+        error: true,
+        statusCode: res.status,
+        statusText: res.statusText,
+      },
+    };
+  }
+
+  return {
+    channel: "soyeht",
+    messageId: envelope.deliveryId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Deliver functions
+// ---------------------------------------------------------------------------
+
+export async function deliverTextMessage(
+  params: DeliverTextParams,
+): Promise<OutboundDeliveryResult> {
+  const message: TextMessagePayload = {
+    contentType: "text",
+    text: params.text,
+  };
+  const envelope = buildOutboundEnvelope(params.accountId, params.sessionId, message);
+  return postToBackend(params.backendBaseUrl, params.pluginAuthToken, envelope, {});
+}
+
+export async function deliverAudioMessage(
+  params: DeliverAudioParams,
+): Promise<OutboundDeliveryResult> {
+  const message: AudioMessagePayload = {
+    contentType: "audio",
+    renderStyle: "voice_note",
+    mimeType: params.mimeType,
+    filename: params.filename,
+    durationMs: params.durationMs,
+    url: params.url,
+    transcript: params.transcript,
+  };
+  const envelope = buildOutboundEnvelope(params.accountId, params.sessionId, message);
+  return postToBackend(params.backendBaseUrl, params.pluginAuthToken, envelope, {});
+}
+
+export async function deliverFileMessage(
+  params: DeliverFileParams,
+): Promise<OutboundDeliveryResult> {
+  const message: FileMessagePayload = {
+    contentType: "file",
+    mimeType: params.mimeType,
+    filename: params.filename,
+    sizeBytes: params.sizeBytes,
+    url: params.url,
+  };
+  const envelope = buildOutboundEnvelope(params.accountId, params.sessionId, message);
+  return postToBackend(params.backendBaseUrl, params.pluginAuthToken, envelope, {});
+}