@clawdbot/zalouser 2026.1.16 → 2026.1.21

package/src/onboarding.ts

@@ -1,27 +1,35 @@
-import type { ChannelOnboardingAdapter, ChannelOnboardingDmPolicy } from "../../../src/channels/plugins/onboarding-types.js";
-import type { WizardPrompter } from "../../../src/wizard/prompts.js";
+import type {
+  ChannelOnboardingAdapter,
+  ChannelOnboardingDmPolicy,
+  ClawdbotConfig,
+  WizardPrompter,
+} from "clawdbot/plugin-sdk";
+import {
+  addWildcardAllowFrom,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  promptAccountId,
+  promptChannelAccessConfig,
+} from "clawdbot/plugin-sdk";
 
 import {
   listZalouserAccountIds,
   resolveDefaultZalouserAccountId,
   resolveZalouserAccountSync,
-  normalizeAccountId,
   checkZcaAuthenticated,
 } from "./accounts.js";
-import { runZcaInteractive, checkZcaInstalled } from "./zca.js";
-import { DEFAULT_ACCOUNT_ID, type CoreConfig } from "./types.js";
+import { runZca, runZcaInteractive, checkZcaInstalled, parseJsonOutput } from "./zca.js";
+import type { ZcaFriend, ZcaGroup } from "./types.js";
 
 const channel = "zalouser" as const;
 
 function setZalouserDmPolicy(
-  cfg: CoreConfig,
+  cfg: ClawdbotConfig,
   dmPolicy: "pairing" | "allowlist" | "open" | "disabled",
-): CoreConfig {
+): ClawdbotConfig {
   const allowFrom =
     dmPolicy === "open"
-      ? [...(cfg.channels?.zalouser?.allowFrom ?? []), "*"].filter(
-          (v, i, a) => a.indexOf(v) === i,
-        )
+      ? addWildcardAllowFrom(cfg.channels?.zalouser?.allowFrom)
       : undefined;
   return {
     ...cfg,
@@ -33,7 +41,7 @@ function setZalouserDmPolicy(
         ...(allowFrom ? { allowFrom } : {}),
       },
     },
-  } as CoreConfig;
+  } as ClawdbotConfig;
 }
 
 async function noteZalouserHelp(prompter: WizardPrompter): Promise<void> {
@@ -52,32 +60,80 @@ async function noteZalouserHelp(prompter: WizardPrompter): Promise<void> {
 }
 
 async function promptZalouserAllowFrom(params: {
-  cfg: CoreConfig;
+  cfg: ClawdbotConfig;
   prompter: WizardPrompter;
   accountId: string;
-}): Promise<CoreConfig> {
+}): Promise<ClawdbotConfig> {
   const { cfg, prompter, accountId } = params;
   const resolved = resolveZalouserAccountSync({ cfg, accountId });
   const existingAllowFrom = resolved.config.allowFrom ?? [];
-  const entry = await prompter.text({
-    message: "Zalouser allowFrom (user id)",
-    placeholder: "123456789",
-    initialValue: existingAllowFrom[0] ? String(existingAllowFrom[0]) : undefined,
-    validate: (value) => {
-      const raw = String(value ?? "").trim();
-      if (!raw) return "Required";
-      if (!/^\d+$/.test(raw)) return "Use a numeric Zalo user id";
-      return undefined;
-    },
-  });
-  const normalized = String(entry).trim();
-  const merged = [
-    ...existingAllowFrom.map((item) => String(item).trim()).filter(Boolean),
-    normalized,
-  ];
-  const unique = [...new Set(merged)];
+  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 ClawdbotConfig;
+    }
 
-  if (accountId === DEFAULT_ACCOUNT_ID) {
     return {
       ...cfg,
       channels: {
@@ -85,13 +141,39 @@ async function promptZalouserAllowFrom(params: {
         zalouser: {
           ...cfg.channels?.zalouser,
           enabled: true,
-          dmPolicy: "allowlist",
-          allowFrom: unique,
+          accounts: {
+            ...(cfg.channels?.zalouser?.accounts ?? {}),
+            [accountId]: {
+              ...(cfg.channels?.zalouser?.accounts?.[accountId] ?? {}),
+              enabled: cfg.channels?.zalouser?.accounts?.[accountId]?.enabled ?? true,
+              dmPolicy: "allowlist",
+              allowFrom: unique,
+            },
+          },
         },
       },
-    } as CoreConfig;
+    } as ClawdbotConfig;
   }
+}
 
+function setZalouserGroupPolicy(
+  cfg: ClawdbotConfig,
+  accountId: string,
+  groupPolicy: "open" | "allowlist" | "disabled",
+): ClawdbotConfig {
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalouser: {
+          ...cfg.channels?.zalouser,
+          enabled: true,
+          groupPolicy,
+        },
+      },
+    } as ClawdbotConfig;
+  }
   return {
     ...cfg,
     channels: {
@@ -104,55 +186,83 @@ async function promptZalouserAllowFrom(params: {
           [accountId]: {
             ...(cfg.channels?.zalouser?.accounts?.[accountId] ?? {}),
             enabled: cfg.channels?.zalouser?.accounts?.[accountId]?.enabled ?? true,
-            dmPolicy: "allowlist",
-            allowFrom: unique,
+            groupPolicy,
           },
         },
       },
     },
-  } as CoreConfig;
+  } as ClawdbotConfig;
 }
 
-async function promptAccountId(params: {
-  cfg: CoreConfig;
-  prompter: WizardPrompter;
-  label: string;
-  currentId: string;
-  listAccountIds: (cfg: CoreConfig) => string[];
-  defaultAccountId: string;
-}): Promise<string> {
-  const { cfg, prompter, label, currentId, listAccountIds, defaultAccountId } = params;
-  const existingIds = listAccountIds(cfg);
-  const options = [
-    ...existingIds.map((id) => ({
-      value: id,
-      label: id === defaultAccountId ? `${id} (default)` : id,
-    })),
-    { value: "__new__", label: "Create new account" },
-  ];
-
-  const selected = await prompter.select({
-    message: `${label} account`,
-    options,
-    initialValue: currentId,
-  });
-
-  if (selected === "__new__") {
-    const newId = await prompter.text({
-      message: "New account ID",
-      placeholder: "work",
-      validate: (value) => {
-        const raw = String(value ?? "").trim().toLowerCase();
-        if (!raw) return "Required";
-        if (!/^[a-z0-9_-]+$/.test(raw)) return "Use lowercase alphanumeric, dash, or underscore";
-        if (existingIds.includes(raw)) return "Account already exists";
-        return undefined;
+function setZalouserGroupAllowlist(
+  cfg: ClawdbotConfig,
+  accountId: string,
+  groupKeys: string[],
+): ClawdbotConfig {
+  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,
+        },
       },
-    });
-    return String(newId).trim().toLowerCase();
+    } as ClawdbotConfig;
+  }
+  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 ClawdbotConfig;
+}
+
+async function resolveZalouserGroups(params: {
+  cfg: ClawdbotConfig;
+  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 selected as string;
+  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 = {
@@ -160,18 +270,29 @@ const dmPolicy: ChannelOnboardingDmPolicy = {
   channel,
   policyKey: "channels.zalouser.dmPolicy",
   allowFromKey: "channels.zalouser.allowFrom",
-  getCurrent: (cfg) => ((cfg as CoreConfig).channels?.zalouser?.dmPolicy ?? "pairing") as "pairing",
-  setPolicy: (cfg, policy) => setZalouserDmPolicy(cfg as CoreConfig, policy),
+  getCurrent: (cfg) => ((cfg as ClawdbotConfig).channels?.zalouser?.dmPolicy ?? "pairing") as "pairing",
+  setPolicy: (cfg, policy) => setZalouserDmPolicy(cfg as ClawdbotConfig, policy),
+  promptAllowFrom: async ({ cfg, prompter, accountId }) => {
+    const id =
+      accountId && normalizeAccountId(accountId)
+        ? normalizeAccountId(accountId) ?? DEFAULT_ACCOUNT_ID
+        : resolveDefaultZalouserAccountId(cfg as ClawdbotConfig);
+    return promptZalouserAllowFrom({
+      cfg: cfg as ClawdbotConfig,
+      prompter,
+      accountId: id,
+    });
+  },
 };
 
 export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
   channel,
   dmPolicy,
   getStatus: async ({ cfg }) => {
-    const ids = listZalouserAccountIds(cfg as CoreConfig);
+    const ids = listZalouserAccountIds(cfg as ClawdbotConfig);
     let configured = false;
     for (const accountId of ids) {
-      const account = resolveZalouserAccountSync({ cfg: cfg as CoreConfig, accountId });
+      const account = resolveZalouserAccountSync({ cfg: cfg as ClawdbotConfig, accountId });
       const isAuth = await checkZcaAuthenticated(account.profile);
       if (isAuth) {
         configured = true;
@@ -203,14 +324,14 @@ export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
     }
 
     const zalouserOverride = accountOverrides.zalouser?.trim();
-    const defaultAccountId = resolveDefaultZalouserAccountId(cfg as CoreConfig);
+    const defaultAccountId = resolveDefaultZalouserAccountId(cfg as ClawdbotConfig);
     let accountId = zalouserOverride
       ? normalizeAccountId(zalouserOverride)
       : defaultAccountId;
 
     if (shouldPromptAccountIds && !zalouserOverride) {
       accountId = await promptAccountId({
-        cfg: cfg as CoreConfig,
+        cfg: cfg as ClawdbotConfig,
         prompter,
         label: "Zalo Personal",
         currentId: accountId,
@@ -219,7 +340,7 @@ export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
       });
     }
 
-    let next = cfg as CoreConfig;
+    let next = cfg as ClawdbotConfig;
     const account = resolveZalouserAccountSync({ cfg: next, accountId });
     const alreadyAuthenticated = await checkZcaAuthenticated(account.profile);
 
@@ -277,7 +398,7 @@ export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
             profile: account.profile !== "default" ? account.profile : undefined,
           },
         },
-      } as CoreConfig;
+      } as ClawdbotConfig;
     } else {
       next = {
         ...next,
@@ -296,7 +417,7 @@ export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
             },
           },
         },
-      } as CoreConfig;
+      } as ClawdbotConfig;
     }
 
     if (forceAllowFrom) {
@@ -307,6 +428,61 @@ export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
       });
     }
 
+    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 "clawdbot/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/status-issues.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import { collectZalouserStatusIssues } from "./status-issues.js";
+
+describe("collectZalouserStatusIssues", () => {
+  it("flags missing zca when configured is false", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        configured: false,
+        lastError: "zca CLI not found in PATH",
+      },
+    ]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.kind).toBe("runtime");
+    expect(issues[0]?.message).toMatch(/zca CLI not found/i);
+  });
+
+  it("flags missing auth when configured is false", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        configured: false,
+        lastError: "not authenticated",
+      },
+    ]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.kind).toBe("auth");
+    expect(issues[0]?.message).toMatch(/Not authenticated/i);
+  });
+
+  it("warns when dmPolicy is open", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        configured: true,
+        dmPolicy: "open",
+      },
+    ]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.kind).toBe("config");
+  });
+
+  it("skips disabled accounts", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: false,
+        configured: false,
+        lastError: "zca CLI not found in PATH",
+      },
+    ]);
+    expect(issues).toHaveLength(0);
+  });
+});

package/src/status-issues.ts

@@ -0,0 +1,81 @@
+import type { ChannelAccountSnapshot, ChannelStatusIssue } from "clawdbot/plugin-sdk";
+
+type ZalouserAccountStatus = {
+  accountId?: unknown;
+  enabled?: unknown;
+  configured?: unknown;
+  dmPolicy?: unknown;
+  lastError?: unknown;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === "object");
+
+const asString = (value: unknown): string | undefined =>
+  typeof value === "string" ? value : typeof value === "number" ? String(value) : undefined;
+
+function readZalouserAccountStatus(value: ChannelAccountSnapshot): ZalouserAccountStatus | null {
+  if (!isRecord(value)) return null;
+  return {
+    accountId: value.accountId,
+    enabled: value.enabled,
+    configured: value.configured,
+    dmPolicy: value.dmPolicy,
+    lastError: value.lastError,
+  };
+}
+
+function isMissingZca(lastError?: string): boolean {
+  if (!lastError) return false;
+  const lower = lastError.toLowerCase();
+  return lower.includes("zca") && (lower.includes("not found") || lower.includes("enoent"));
+}
+
+export function collectZalouserStatusIssues(
+  accounts: ChannelAccountSnapshot[],
+): ChannelStatusIssue[] {
+  const issues: ChannelStatusIssue[] = [];
+  for (const entry of accounts) {
+    const account = readZalouserAccountStatus(entry);
+    if (!account) continue;
+    const accountId = asString(account.accountId) ?? "default";
+    const enabled = account.enabled !== false;
+    if (!enabled) continue;
+
+    const configured = account.configured === true;
+    const lastError = asString(account.lastError)?.trim();
+
+    if (!configured) {
+      if (isMissingZca(lastError)) {
+        issues.push({
+          channel: "zalouser",
+          accountId,
+          kind: "runtime",
+          message: "zca CLI not found in PATH.",
+          fix: "Install zca-cli and ensure it is on PATH for the Gateway process.",
+        });
+      } else {
+        issues.push({
+          channel: "zalouser",
+          accountId,
+          kind: "auth",
+          message: "Not authenticated (no zca session).",
+          fix: "Run: clawdbot channels login --channel zalouser",
+        });
+      }
+      continue;
+    }
+
+    if (account.dmPolicy === "open") {
+      issues.push({
+        channel: "zalouser",
+        accountId,
+        kind: "config",
+        message:
+          'Zalo Personal dmPolicy is "open", allowing any user to message the bot without pairing.',
+        fix: 'Set channels.zalouser.dmPolicy to "pairing" or "allowlist" to restrict access.',
+      });
+    }
+  }
+  return issues;
+}

package/src/types.ts

@@ -68,15 +68,14 @@ export type ListenOptions = CommonOptions & {
   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>;
+  groupPolicy?: "open" | "allowlist" | "disabled";
+  groups?: Record<string, { allow?: boolean; enabled?: boolean }>;
   messagePrefix?: string;
 };
 
@@ -87,18 +86,12 @@ export type ZalouserConfig = {
   defaultAccount?: string;
   dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
   allowFrom?: Array<string | number>;
+  groupPolicy?: "open" | "allowlist" | "disabled";
+  groups?: Record<string, { allow?: boolean; enabled?: boolean }>;
   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;