@openclaw/zalouser 2026.1.29

package/src/onboarding.ts

@@ -0,0 +1,488 @@
+import type {
+  ChannelOnboardingAdapter,
+  ChannelOnboardingDmPolicy,
+  OpenClawConfig,
+  WizardPrompter,
+} from "openclaw/plugin-sdk";
+import {
+  addWildcardAllowFrom,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  promptAccountId,
+  promptChannelAccessConfig,
+} from "openclaw/plugin-sdk";
+
+import {
+  listZalouserAccountIds,
+  resolveDefaultZalouserAccountId,
+  resolveZalouserAccountSync,
+  checkZcaAuthenticated,
+} from "./accounts.js";
+import { runZca, runZcaInteractive, checkZcaInstalled, parseJsonOutput } from "./zca.js";
+import type { ZcaFriend, ZcaGroup } from "./types.js";
+
+const channel = "zalouser" as const;
+
+function setZalouserDmPolicy(
+  cfg: OpenClawConfig,
+  dmPolicy: "pairing" | "allowlist" | "open" | "disabled",
+): OpenClawConfig {
+  const allowFrom =
+    dmPolicy === "open"
+      ? addWildcardAllowFrom(cfg.channels?.zalouser?.allowFrom)
+      : undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      zalouser: {
+        ...cfg.channels?.zalouser,
+        dmPolicy,
+        ...(allowFrom ? { allowFrom } : {}),
+      },
+    },
+  } as OpenClawConfig;
+}
+
+async function noteZalouserHelp(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "Zalo Personal Account login via QR code.",
+      "",
+      "Prerequisites:",
+      "1) Install zca-cli",
+      "2) You'll scan a QR code with your Zalo app",
+      "",
+      "Docs: https://docs.openclaw.ai/channels/zalouser",
+    ].join("\n"),
+    "Zalo Personal Setup",
+  );
+}
+
+async function promptZalouserAllowFrom(params: {
+  cfg: OpenClawConfig;
+  prompter: WizardPrompter;
+  accountId: string;
+}): Promise<OpenClawConfig> {
+  const { cfg, prompter, accountId } = params;
+  const resolved = resolveZalouserAccountSync({ cfg, accountId });
+  const existingAllowFrom = resolved.config.allowFrom ?? [];
+  const parseInput = (raw: string) =>
+    raw
+      .split(/[\n,;]+/g)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+
+  const resolveUserId = async (input: string): Promise<string | null> => {
+    const trimmed = input.trim();
+    if (!trimmed) return null;
+    if (/^\d+$/.test(trimmed)) return trimmed;
+    const ok = await checkZcaInstalled();
+    if (!ok) return null;
+    const result = await runZca(["friend", "find", trimmed], {
+      profile: resolved.profile,
+      timeout: 15000,
+    });
+    if (!result.ok) return null;
+    const parsed = parseJsonOutput<ZcaFriend[]>(result.stdout);
+    const rows = Array.isArray(parsed) ? parsed : [];
+    const match = rows[0];
+    if (!match?.userId) return null;
+    if (rows.length > 1) {
+      await prompter.note(
+        `Multiple matches for "${trimmed}", using ${match.displayName ?? match.userId}.`,
+        "Zalo Personal allowlist",
+      );
+    }
+    return String(match.userId);
+  };
+
+  while (true) {
+    const entry = await prompter.text({
+      message: "Zalouser allowFrom (username or user id)",
+      placeholder: "Alice, 123456789",
+      initialValue: existingAllowFrom[0] ? String(existingAllowFrom[0]) : undefined,
+      validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+    });
+    const parts = parseInput(String(entry));
+    const results = await Promise.all(parts.map((part) => resolveUserId(part)));
+    const unresolved = parts.filter((_, idx) => !results[idx]);
+    if (unresolved.length > 0) {
+      await prompter.note(
+        `Could not resolve: ${unresolved.join(", ")}. Use numeric user ids or ensure zca is available.`,
+        "Zalo Personal allowlist",
+      );
+      continue;
+    }
+    const merged = [
+      ...existingAllowFrom.map((item) => String(item).trim()).filter(Boolean),
+      ...(results.filter(Boolean) as string[]),
+    ];
+    const unique = [...new Set(merged)];
+    if (accountId === DEFAULT_ACCOUNT_ID) {
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          zalouser: {
+            ...cfg.channels?.zalouser,
+            enabled: true,
+            dmPolicy: "allowlist",
+            allowFrom: unique,
+          },
+        },
+      } as OpenClawConfig;
+    }
+
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalouser: {
+          ...cfg.channels?.zalouser,
+          enabled: true,
+          accounts: {
+            ...(cfg.channels?.zalouser?.accounts ?? {}),
+            [accountId]: {
+              ...(cfg.channels?.zalouser?.accounts?.[accountId] ?? {}),
+              enabled: cfg.channels?.zalouser?.accounts?.[accountId]?.enabled ?? true,
+              dmPolicy: "allowlist",
+              allowFrom: unique,
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+  }
+}
+
+function setZalouserGroupPolicy(
+  cfg: OpenClawConfig,
+  accountId: string,
+  groupPolicy: "open" | "allowlist" | "disabled",
+): OpenClawConfig {
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalouser: {
+          ...cfg.channels?.zalouser,
+          enabled: true,
+          groupPolicy,
+        },
+      },
+    } as OpenClawConfig;
+  }
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      zalouser: {
+        ...cfg.channels?.zalouser,
+        enabled: true,
+        accounts: {
+          ...(cfg.channels?.zalouser?.accounts ?? {}),
+          [accountId]: {
+            ...(cfg.channels?.zalouser?.accounts?.[accountId] ?? {}),
+            enabled: cfg.channels?.zalouser?.accounts?.[accountId]?.enabled ?? true,
+            groupPolicy,
+          },
+        },
+      },
+    },
+  } as OpenClawConfig;
+}
+
+function setZalouserGroupAllowlist(
+  cfg: OpenClawConfig,
+  accountId: string,
+  groupKeys: string[],
+): OpenClawConfig {
+  const groups = Object.fromEntries(groupKeys.map((key) => [key, { allow: true }]));
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalouser: {
+          ...cfg.channels?.zalouser,
+          enabled: true,
+          groups,
+        },
+      },
+    } as OpenClawConfig;
+  }
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      zalouser: {
+        ...cfg.channels?.zalouser,
+        enabled: true,
+        accounts: {
+          ...(cfg.channels?.zalouser?.accounts ?? {}),
+          [accountId]: {
+            ...(cfg.channels?.zalouser?.accounts?.[accountId] ?? {}),
+            enabled: cfg.channels?.zalouser?.accounts?.[accountId]?.enabled ?? true,
+            groups,
+          },
+        },
+      },
+    },
+  } as OpenClawConfig;
+}
+
+async function resolveZalouserGroups(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  entries: string[];
+}): Promise<Array<{ input: string; resolved: boolean; id?: string }>> {
+  const account = resolveZalouserAccountSync({ cfg: params.cfg, accountId: params.accountId });
+  const result = await runZca(["group", "list", "-j"], { profile: account.profile, timeout: 15000 });
+  if (!result.ok) throw new Error(result.stderr || "Failed to list groups");
+  const groups = (parseJsonOutput<ZcaGroup[]>(result.stdout) ?? []).filter(
+    (group) => Boolean(group.groupId),
+  );
+  const byName = new Map<string, ZcaGroup[]>();
+  for (const group of groups) {
+    const name = group.name?.trim().toLowerCase();
+    if (!name) continue;
+    const list = byName.get(name) ?? [];
+    list.push(group);
+    byName.set(name, list);
+  }
+
+  return params.entries.map((input) => {
+    const trimmed = input.trim();
+    if (!trimmed) return { input, resolved: false };
+    if (/^\d+$/.test(trimmed)) return { input, resolved: true, id: trimmed };
+    const matches = byName.get(trimmed.toLowerCase()) ?? [];
+    const match = matches[0];
+    return match?.groupId
+      ? { input, resolved: true, id: String(match.groupId) }
+      : { input, resolved: false };
+  });
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+  label: "Zalo Personal",
+  channel,
+  policyKey: "channels.zalouser.dmPolicy",
+  allowFromKey: "channels.zalouser.allowFrom",
+  getCurrent: (cfg) => ((cfg as OpenClawConfig).channels?.zalouser?.dmPolicy ?? "pairing") as "pairing",
+  setPolicy: (cfg, policy) => setZalouserDmPolicy(cfg as OpenClawConfig, policy),
+  promptAllowFrom: async ({ cfg, prompter, accountId }) => {
+    const id =
+      accountId && normalizeAccountId(accountId)
+        ? normalizeAccountId(accountId) ?? DEFAULT_ACCOUNT_ID
+        : resolveDefaultZalouserAccountId(cfg as OpenClawConfig);
+    return promptZalouserAllowFrom({
+      cfg: cfg as OpenClawConfig,
+      prompter,
+      accountId: id,
+    });
+  },
+};
+
+export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  dmPolicy,
+  getStatus: async ({ cfg }) => {
+    const ids = listZalouserAccountIds(cfg as OpenClawConfig);
+    let configured = false;
+    for (const accountId of ids) {
+      const account = resolveZalouserAccountSync({ cfg: cfg as OpenClawConfig, accountId });
+      const isAuth = await checkZcaAuthenticated(account.profile);
+      if (isAuth) {
+        configured = true;
+        break;
+      }
+    }
+    return {
+      channel,
+      configured,
+      statusLines: [`Zalo Personal: ${configured ? "logged in" : "needs QR login"}`],
+      selectionHint: configured ? "recommended · logged in" : "recommended · QR login",
+      quickstartScore: configured ? 1 : 15,
+    };
+  },
+  configure: async ({ cfg, prompter, accountOverrides, shouldPromptAccountIds, forceAllowFrom }) => {
+    // Check zca is installed
+    const zcaInstalled = await checkZcaInstalled();
+    if (!zcaInstalled) {
+      await prompter.note(
+        [
+          "The `zca` binary was not found in PATH.",
+          "",
+          "Install zca-cli, then re-run onboarding:",
+          "Docs: https://docs.openclaw.ai/channels/zalouser",
+        ].join("\n"),
+        "Missing Dependency",
+      );
+      return { cfg, accountId: DEFAULT_ACCOUNT_ID };
+    }
+
+    const zalouserOverride = accountOverrides.zalouser?.trim();
+    const defaultAccountId = resolveDefaultZalouserAccountId(cfg as OpenClawConfig);
+    let accountId = zalouserOverride
+      ? normalizeAccountId(zalouserOverride)
+      : defaultAccountId;
+
+    if (shouldPromptAccountIds && !zalouserOverride) {
+      accountId = await promptAccountId({
+        cfg: cfg as OpenClawConfig,
+        prompter,
+        label: "Zalo Personal",
+        currentId: accountId,
+        listAccountIds: listZalouserAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    let next = cfg as OpenClawConfig;
+    const account = resolveZalouserAccountSync({ cfg: next, accountId });
+    const alreadyAuthenticated = await checkZcaAuthenticated(account.profile);
+
+    if (!alreadyAuthenticated) {
+      await noteZalouserHelp(prompter);
+
+      const wantsLogin = await prompter.confirm({
+        message: "Login via QR code now?",
+        initialValue: true,
+      });
+
+      if (wantsLogin) {
+        await prompter.note(
+          "A QR code will appear in your terminal.\nScan it with your Zalo app to login.",
+          "QR Login",
+        );
+
+        // Run interactive login
+        const result = await runZcaInteractive(["auth", "login"], {
+          profile: account.profile,
+        });
+
+        if (!result.ok) {
+          await prompter.note(
+            `Login failed: ${result.stderr || "Unknown error"}`,
+            "Error",
+          );
+        } else {
+          const isNowAuth = await checkZcaAuthenticated(account.profile);
+          if (isNowAuth) {
+            await prompter.note("Login successful!", "Success");
+          }
+        }
+      }
+    } else {
+      const keepSession = await prompter.confirm({
+        message: "Zalo Personal already logged in. Keep session?",
+        initialValue: true,
+      });
+      if (!keepSession) {
+        await runZcaInteractive(["auth", "logout"], { profile: account.profile });
+        await runZcaInteractive(["auth", "login"], { profile: account.profile });
+      }
+    }
+
+    // Enable the channel
+    if (accountId === DEFAULT_ACCOUNT_ID) {
+      next = {
+        ...next,
+        channels: {
+          ...next.channels,
+          zalouser: {
+            ...next.channels?.zalouser,
+            enabled: true,
+            profile: account.profile !== "default" ? account.profile : undefined,
+          },
+        },
+      } as OpenClawConfig;
+    } else {
+      next = {
+        ...next,
+        channels: {
+          ...next.channels,
+          zalouser: {
+            ...next.channels?.zalouser,
+            enabled: true,
+            accounts: {
+              ...(next.channels?.zalouser?.accounts ?? {}),
+              [accountId]: {
+                ...(next.channels?.zalouser?.accounts?.[accountId] ?? {}),
+                enabled: true,
+                profile: account.profile,
+              },
+            },
+          },
+        },
+      } as OpenClawConfig;
+    }
+
+    if (forceAllowFrom) {
+      next = await promptZalouserAllowFrom({
+        cfg: next,
+        prompter,
+        accountId,
+      });
+    }
+
+    const accessConfig = await promptChannelAccessConfig({
+      prompter,
+      label: "Zalo groups",
+      currentPolicy: account.config.groupPolicy ?? "open",
+      currentEntries: Object.keys(account.config.groups ?? {}),
+      placeholder: "Family, Work, 123456789",
+      updatePrompt: Boolean(account.config.groups),
+    });
+    if (accessConfig) {
+      if (accessConfig.policy !== "allowlist") {
+        next = setZalouserGroupPolicy(next, accountId, accessConfig.policy);
+      } else {
+        let keys = accessConfig.entries;
+        if (accessConfig.entries.length > 0) {
+          try {
+            const resolved = await resolveZalouserGroups({
+              cfg: next,
+              accountId,
+              entries: accessConfig.entries,
+            });
+            const resolvedIds = resolved
+              .filter((entry) => entry.resolved && entry.id)
+              .map((entry) => entry.id as string);
+            const unresolved = resolved
+              .filter((entry) => !entry.resolved)
+              .map((entry) => entry.input);
+            keys = [
+              ...resolvedIds,
+              ...unresolved.map((entry) => entry.trim()).filter(Boolean),
+            ];
+            if (resolvedIds.length > 0 || unresolved.length > 0) {
+              await prompter.note(
+                [
+                  resolvedIds.length > 0 ? `Resolved: ${resolvedIds.join(", ")}` : undefined,
+                  unresolved.length > 0
+                    ? `Unresolved (kept as typed): ${unresolved.join(", ")}`
+                    : undefined,
+                ]
+                  .filter(Boolean)
+                  .join("\n"),
+                "Zalo groups",
+              );
+            }
+          } catch (err) {
+            await prompter.note(
+              `Group lookup failed; keeping entries as typed. ${String(err)}`,
+              "Zalo groups",
+            );
+          }
+        }
+        next = setZalouserGroupPolicy(next, accountId, "allowlist");
+        next = setZalouserGroupAllowlist(next, accountId, keys);
+      }
+    }
+
+    return { cfg: next, accountId };
+  },
+};

package/src/probe.ts

@@ -0,0 +1,28 @@
+import { runZca, parseJsonOutput } from "./zca.js";
+import type { ZcaUserInfo } from "./types.js";
+
+export interface ZalouserProbeResult {
+  ok: boolean;
+  user?: ZcaUserInfo;
+  error?: string;
+}
+
+export async function probeZalouser(
+  profile: string,
+  timeoutMs?: number,
+): Promise<ZalouserProbeResult> {
+  const result = await runZca(["me", "info", "-j"], {
+    profile,
+    timeout: timeoutMs,
+  });
+
+  if (!result.ok) {
+    return { ok: false, error: result.stderr || "Failed to probe" };
+  }
+
+  const user = parseJsonOutput<ZcaUserInfo>(result.stdout);
+  if (!user) {
+    return { ok: false, error: "Failed to parse user info" };
+  }
+  return { ok: true, user };
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setZalouserRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getZalouserRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Zalouser runtime not initialized");
+  }
+  return runtime;
+}

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;
+}