@clawdbot/zalouser 2026.1.16

package/src/send.ts

@@ -0,0 +1,150 @@
+import { runZca } from "./zca.js";
+
+export type ZalouserSendOptions = {
+  profile?: string;
+  mediaUrl?: string;
+  caption?: string;
+  isGroup?: boolean;
+};
+
+export type ZalouserSendResult = {
+  ok: boolean;
+  messageId?: string;
+  error?: string;
+};
+
+export async function sendMessageZalouser(
+  threadId: string,
+  text: string,
+  options: ZalouserSendOptions = {},
+): Promise<ZalouserSendResult> {
+  const profile = options.profile || process.env.ZCA_PROFILE || "default";
+
+  if (!threadId?.trim()) {
+    return { ok: false, error: "No threadId provided" };
+  }
+
+  // Handle media sending
+  if (options.mediaUrl) {
+    return sendMediaZalouser(threadId, options.mediaUrl, {
+      ...options,
+      caption: text || options.caption,
+    });
+  }
+
+  // Send text message
+  const args = ["msg", "send", threadId.trim(), text.slice(0, 2000)];
+  if (options.isGroup) args.push("-g");
+
+  try {
+    const result = await runZca(args, { profile });
+
+    if (result.ok) {
+      return { ok: true, messageId: extractMessageId(result.stdout) };
+    }
+
+    return { ok: false, error: result.stderr || "Failed to send message" };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+async function sendMediaZalouser(
+  threadId: string,
+  mediaUrl: string,
+  options: ZalouserSendOptions = {},
+): Promise<ZalouserSendResult> {
+  const profile = options.profile || process.env.ZCA_PROFILE || "default";
+
+  if (!threadId?.trim()) {
+    return { ok: false, error: "No threadId provided" };
+  }
+
+  if (!mediaUrl?.trim()) {
+    return { ok: false, error: "No media URL provided" };
+  }
+
+  // Determine media type from URL
+  const lowerUrl = mediaUrl.toLowerCase();
+  let command: string;
+  if (lowerUrl.match(/\.(mp4|mov|avi|webm)$/)) {
+    command = "video";
+  } else if (lowerUrl.match(/\.(mp3|wav|ogg|m4a)$/)) {
+    command = "voice";
+  } else {
+    command = "image";
+  }
+
+  const args = ["msg", command, threadId.trim(), "-u", mediaUrl.trim()];
+  if (options.caption) {
+    args.push("-m", options.caption.slice(0, 2000));
+  }
+  if (options.isGroup) args.push("-g");
+
+  try {
+    const result = await runZca(args, { profile });
+
+    if (result.ok) {
+      return { ok: true, messageId: extractMessageId(result.stdout) };
+    }
+
+    return { ok: false, error: result.stderr || `Failed to send ${command}` };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export async function sendImageZalouser(
+  threadId: string,
+  imageUrl: string,
+  options: ZalouserSendOptions = {},
+): Promise<ZalouserSendResult> {
+  const profile = options.profile || process.env.ZCA_PROFILE || "default";
+  const args = ["msg", "image", threadId.trim(), "-u", imageUrl.trim()];
+  if (options.caption) {
+    args.push("-m", options.caption.slice(0, 2000));
+  }
+  if (options.isGroup) args.push("-g");
+
+  try {
+    const result = await runZca(args, { profile });
+    if (result.ok) {
+      return { ok: true, messageId: extractMessageId(result.stdout) };
+    }
+    return { ok: false, error: result.stderr || "Failed to send image" };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export async function sendLinkZalouser(
+  threadId: string,
+  url: string,
+  options: ZalouserSendOptions = {},
+): Promise<ZalouserSendResult> {
+  const profile = options.profile || process.env.ZCA_PROFILE || "default";
+  const args = ["msg", "link", threadId.trim(), url.trim()];
+  if (options.isGroup) args.push("-g");
+
+  try {
+    const result = await runZca(args, { profile });
+    if (result.ok) {
+      return { ok: true, messageId: extractMessageId(result.stdout) };
+    }
+    return { ok: false, error: result.stderr || "Failed to send link" };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+function extractMessageId(stdout: string): string | undefined {
+  // Try to extract message ID from output
+  const match = stdout.match(/message[_\s]?id[:\s]+(\S+)/i);
+  if (match) return match[1];
+  // Return first word if it looks like an ID
+  const firstWord = stdout.trim().split(/\s+/)[0];
+  if (firstWord && /^[a-zA-Z0-9_-]+$/.test(firstWord)) {
+    return firstWord;
+  }
+  return undefined;
+}

package/src/tool.ts

@@ -0,0 +1,156 @@
+import { Type } from "@sinclair/typebox";
+
+import { runZca, parseJsonOutput } from "./zca.js";
+
+const ACTIONS = ["send", "image", "link", "friends", "groups", "me", "status"] as const;
+
+function stringEnum<T extends readonly string[]>(
+  values: T,
+  options: { description?: string } = {},
+) {
+  return Type.Unsafe<T[number]>({
+    type: "string",
+    enum: [...values],
+    ...options,
+  });
+}
+
+// Tool schema - avoiding Type.Union per tool schema guardrails
+export const ZalouserToolSchema = Type.Object({
+  action: stringEnum(ACTIONS, { description: `Action to perform: ${ACTIONS.join(", ")}` }),
+  threadId: Type.Optional(
+    Type.String({ description: "Thread ID for messaging" }),
+  ),
+  message: Type.Optional(Type.String({ description: "Message text" })),
+  isGroup: Type.Optional(Type.Boolean({ description: "Is group chat" })),
+  profile: Type.Optional(Type.String({ description: "Profile name" })),
+  query: Type.Optional(Type.String({ description: "Search query" })),
+  url: Type.Optional(Type.String({ description: "URL for media/link" })),
+}, { additionalProperties: false });
+
+type ToolParams = {
+  action: (typeof ACTIONS)[number];
+  threadId?: string;
+  message?: string;
+  isGroup?: boolean;
+  profile?: string;
+  query?: string;
+  url?: string;
+};
+
+type ToolResult = {
+  content: Array<{ type: string; text: string }>;
+  details: unknown;
+};
+
+function json(payload: unknown): ToolResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    details: payload,
+  };
+}
+
+export async function executeZalouserTool(
+  _toolCallId: string,
+  params: ToolParams,
+): Promise<ToolResult> {
+  try {
+    switch (params.action) {
+      case "send": {
+        if (!params.threadId || !params.message) {
+          throw new Error("threadId and message required for send action");
+        }
+        const args = ["msg", "send", params.threadId, params.message];
+        if (params.isGroup) args.push("-g");
+        const result = await runZca(args, { profile: params.profile });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to send message");
+        }
+        return json({ success: true, output: result.stdout });
+      }
+
+      case "image": {
+        if (!params.threadId) {
+          throw new Error("threadId required for image action");
+        }
+        if (!params.url) {
+          throw new Error("url required for image action");
+        }
+        const args = ["msg", "image", params.threadId, "-u", params.url];
+        if (params.message) args.push("-m", params.message);
+        if (params.isGroup) args.push("-g");
+        const result = await runZca(args, { profile: params.profile });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to send image");
+        }
+        return json({ success: true, output: result.stdout });
+      }
+
+      case "link": {
+        if (!params.threadId || !params.url) {
+          throw new Error("threadId and url required for link action");
+        }
+        const args = ["msg", "link", params.threadId, params.url];
+        if (params.isGroup) args.push("-g");
+        const result = await runZca(args, { profile: params.profile });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to send link");
+        }
+        return json({ success: true, output: result.stdout });
+      }
+
+      case "friends": {
+        const args = params.query
+          ? ["friend", "find", params.query]
+          : ["friend", "list", "-j"];
+        const result = await runZca(args, { profile: params.profile });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to get friends");
+        }
+        const parsed = parseJsonOutput(result.stdout);
+        return json(parsed ?? { raw: result.stdout });
+      }
+
+      case "groups": {
+        const result = await runZca(["group", "list", "-j"], {
+          profile: params.profile,
+        });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to get groups");
+        }
+        const parsed = parseJsonOutput(result.stdout);
+        return json(parsed ?? { raw: result.stdout });
+      }
+
+      case "me": {
+        const result = await runZca(["me", "info", "-j"], {
+          profile: params.profile,
+        });
+        if (!result.ok) {
+          throw new Error(result.stderr || "Failed to get profile");
+        }
+        const parsed = parseJsonOutput(result.stdout);
+        return json(parsed ?? { raw: result.stdout });
+      }
+
+      case "status": {
+        const result = await runZca(["auth", "status"], {
+          profile: params.profile,
+        });
+        return json({
+          authenticated: result.ok,
+          output: result.stdout || result.stderr,
+        });
+      }
+
+      default:
+        throw new Error(
+          `Unknown action: ${params.action}. Valid actions: send, image, link, friends, groups, me, status`,
+        );
+    }
+  } catch (err) {
+    return json({
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}

package/src/types.ts

@@ -0,0 +1,109 @@
+// zca-cli wrapper types
+export type ZcaRunOptions = {
+  profile?: string;
+  cwd?: string;
+  timeout?: number;
+};
+
+export type ZcaResult = {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+export type ZcaProfile = {
+  name: string;
+  label?: string;
+  isDefault?: boolean;
+};
+
+export type ZcaFriend = {
+  userId: string;
+  displayName: string;
+  avatar?: string;
+};
+
+export type ZcaGroup = {
+  groupId: string;
+  name: string;
+  memberCount?: number;
+};
+
+export type ZcaMessage = {
+  threadId: string;
+  msgId?: string;
+  cliMsgId?: string;
+  type: number;
+  content: string;
+  timestamp: number;
+  metadata?: {
+    isGroup: boolean;
+    threadName?: string;
+    senderName?: string;
+    fromId?: string;
+  };
+};
+
+export type ZcaUserInfo = {
+  userId: string;
+  displayName: string;
+  avatar?: string;
+};
+
+export type CommonOptions = {
+  profile?: string;
+  json?: boolean;
+};
+
+export type SendOptions = CommonOptions & {
+  group?: boolean;
+};
+
+export type ListenOptions = CommonOptions & {
+  raw?: boolean;
+  keepAlive?: boolean;
+  webhook?: string;
+  echo?: boolean;
+  prefix?: string;
+};
+
+// Channel plugin config types
+export const DEFAULT_ACCOUNT_ID = "default";
+
+export type ZalouserAccountConfig = {
+  enabled?: boolean;
+  name?: string;
+  profile?: string;
+  dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
+  allowFrom?: Array<string | number>;
+  messagePrefix?: string;
+};
+
+export type ZalouserConfig = {
+  enabled?: boolean;
+  name?: string;
+  profile?: string;
+  defaultAccount?: string;
+  dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
+  allowFrom?: Array<string | number>;
+  messagePrefix?: string;
+  accounts?: Record<string, ZalouserAccountConfig>;
+};
+
+export type CoreConfig = {
+  channels?: {
+    zalouser?: ZalouserConfig;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+};
+
+export type ResolvedZalouserAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  profile: string;
+  authenticated: boolean;
+  config: ZalouserAccountConfig;
+};

package/src/zca.ts

@@ -0,0 +1,183 @@
+import { spawn, type SpawnOptions } from "node:child_process";
+
+import type { ZcaResult, ZcaRunOptions } from "./types.js";
+
+const ZCA_BINARY = "zca";
+const DEFAULT_TIMEOUT = 30000;
+
+function buildArgs(args: string[], options?: ZcaRunOptions): string[] {
+  const result: string[] = [];
+  // Profile flag comes first (before subcommand)
+  const profile = options?.profile || process.env.ZCA_PROFILE;
+  if (profile) {
+    result.push("--profile", profile);
+  }
+  result.push(...args);
+  return result;
+}
+
+export async function runZca(
+  args: string[],
+  options?: ZcaRunOptions,
+): Promise<ZcaResult> {
+  const fullArgs = buildArgs(args, options);
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+
+  return new Promise((resolve) => {
+    const spawnOpts: SpawnOptions = {
+      cwd: options?.cwd,
+      env: { ...process.env },
+      stdio: ["pipe", "pipe", "pipe"],
+    };
+
+    const proc = spawn(ZCA_BINARY, fullArgs, spawnOpts);
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      proc.kill("SIGTERM");
+    }, timeout);
+
+    proc.stdout?.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr?.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        resolve({
+          ok: false,
+          stdout,
+          stderr: stderr || "Command timed out",
+          exitCode: code ?? 124,
+        });
+        return;
+      }
+      resolve({
+        ok: code === 0,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        exitCode: code ?? 1,
+      });
+    });
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({
+        ok: false,
+        stdout: "",
+        stderr: err.message,
+        exitCode: 1,
+      });
+    });
+  });
+}
+
+export function runZcaInteractive(
+  args: string[],
+  options?: ZcaRunOptions,
+): Promise<ZcaResult> {
+  const fullArgs = buildArgs(args, options);
+
+  return new Promise((resolve) => {
+    const spawnOpts: SpawnOptions = {
+      cwd: options?.cwd,
+      env: { ...process.env },
+      stdio: "inherit",
+    };
+
+    const proc = spawn(ZCA_BINARY, fullArgs, spawnOpts);
+
+    proc.on("close", (code) => {
+      resolve({
+        ok: code === 0,
+        stdout: "",
+        stderr: "",
+        exitCode: code ?? 1,
+      });
+    });
+
+    proc.on("error", (err) => {
+      resolve({
+        ok: false,
+        stdout: "",
+        stderr: err.message,
+        exitCode: 1,
+      });
+    });
+  });
+}
+
+export function parseJsonOutput<T>(stdout: string): T | null {
+  try {
+    return JSON.parse(stdout) as T;
+  } catch {
+    return null;
+  }
+}
+
+export async function checkZcaInstalled(): Promise<boolean> {
+  const result = await runZca(["--version"], { timeout: 5000 });
+  return result.ok;
+}
+
+export type ZcaStreamingOptions = ZcaRunOptions & {
+  onData?: (data: string) => void;
+  onError?: (err: Error) => void;
+};
+
+export function runZcaStreaming(
+  args: string[],
+  options?: ZcaStreamingOptions,
+): { proc: ReturnType<typeof spawn>; promise: Promise<ZcaResult> } {
+  const fullArgs = buildArgs(args, options);
+
+  const spawnOpts: SpawnOptions = {
+    cwd: options?.cwd,
+    env: { ...process.env },
+    stdio: ["pipe", "pipe", "pipe"],
+  };
+
+  const proc = spawn(ZCA_BINARY, fullArgs, spawnOpts);
+  let stdout = "";
+  let stderr = "";
+
+  proc.stdout?.on("data", (data: Buffer) => {
+    const text = data.toString();
+    stdout += text;
+    options?.onData?.(text);
+  });
+
+  proc.stderr?.on("data", (data: Buffer) => {
+    stderr += data.toString();
+  });
+
+  const promise = new Promise<ZcaResult>((resolve) => {
+    proc.on("close", (code) => {
+      resolve({
+        ok: code === 0,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        exitCode: code ?? 1,
+      });
+    });
+
+    proc.on("error", (err) => {
+      options?.onError?.(err);
+      resolve({
+        ok: false,
+        stdout: "",
+        stderr: err.message,
+        exitCode: 1,
+      });
+    });
+  });
+
+  return { proc, promise };
+}