@openclaw/zalo 2026.3.13 → 2026.5.2-beta.1

package/src/setup-surface.test.ts

@@ -0,0 +1,175 @@
+import { adaptScopedAccountAccessor } from "openclaw/plugin-sdk/channel-config-helpers";
+import {
+  createPluginSetupWizardConfigure,
+  createTestWizardPrompter,
+  runSetupWizardConfigure,
+} from "openclaw/plugin-sdk/plugin-test-runtime";
+import type { WizardPrompter } from "openclaw/plugin-sdk/plugin-test-runtime";
+import { describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../runtime-api.js";
+import { listZaloAccountIds, resolveDefaultZaloAccountId, resolveZaloAccount } from "./accounts.js";
+import { zaloDmPolicy } from "./setup-core.js";
+import { zaloSetupAdapter, zaloSetupWizard } from "./setup-surface.js";
+
+const zaloSetupPlugin = {
+  id: "zalo",
+  meta: {
+    id: "zalo",
+    label: "Zalo",
+    selectionLabel: "Zalo (Bot API)",
+    docsPath: "/channels/zalo",
+    blurb: "Vietnam-focused messaging platform with Bot API.",
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"] as Array<"direct" | "group">,
+  },
+  config: {
+    listAccountIds: (cfg: unknown) => listZaloAccountIds(cfg as never),
+    defaultAccountId: (cfg: unknown) => resolveDefaultZaloAccountId(cfg as never),
+    resolveAccount: adaptScopedAccountAccessor(resolveZaloAccount),
+  },
+  setup: zaloSetupAdapter,
+  setupWizard: zaloSetupWizard,
+} as const;
+
+const zaloConfigure = createPluginSetupWizardConfigure(zaloSetupPlugin);
+
+describe("zalo setup wizard", () => {
+  it("configures a polling token flow", async () => {
+    const prompter = createTestWizardPrompter({
+      select: vi.fn(async () => "plaintext") as WizardPrompter["select"],
+      text: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "Enter Zalo bot token") {
+          return "12345689:abc-xyz";
+        }
+        throw new Error(`Unexpected prompt: ${message}`);
+      }) as WizardPrompter["text"],
+      confirm: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "Use webhook mode for Zalo?") {
+          return false;
+        }
+        return false;
+      }),
+    });
+
+    const result = await runSetupWizardConfigure({
+      configure: zaloConfigure,
+      cfg: {} as OpenClawConfig,
+      prompter,
+      options: { secretInputMode: "plaintext" as const },
+    });
+
+    expect(result.accountId).toBe("default");
+    expect(result.cfg.channels?.zalo?.enabled).toBe(true);
+    expect(result.cfg.channels?.zalo?.botToken).toBe("12345689:abc-xyz");
+    expect(result.cfg.channels?.zalo?.webhookUrl).toBeUndefined();
+  });
+
+  it("reads the named-account DM policy instead of the channel root", () => {
+    expect(
+      zaloDmPolicy.getCurrent(
+        {
+          channels: {
+            zalo: {
+              dmPolicy: "disabled",
+              accounts: {
+                work: {
+                  botToken: "12345689:abc-xyz",
+                  dmPolicy: "allowlist",
+                },
+              },
+            },
+          },
+        } as OpenClawConfig,
+        "work",
+      ),
+    ).toBe("allowlist");
+  });
+
+  it("reports account-scoped config keys for named accounts", () => {
+    expect(zaloDmPolicy.resolveConfigKeys?.({} as OpenClawConfig, "work")).toEqual({
+      policyKey: "channels.zalo.accounts.work.dmPolicy",
+      allowFromKey: "channels.zalo.accounts.work.allowFrom",
+    });
+  });
+
+  it("uses configured defaultAccount for omitted DM policy account context", () => {
+    const cfg = {
+      channels: {
+        zalo: {
+          defaultAccount: "work",
+          dmPolicy: "disabled",
+          allowFrom: ["123456789"],
+          accounts: {
+            work: {
+              botToken: "12345689:abc-xyz",
+              dmPolicy: "allowlist",
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(zaloDmPolicy.getCurrent(cfg)).toBe("allowlist");
+    expect(zaloDmPolicy.resolveConfigKeys?.(cfg)).toEqual({
+      policyKey: "channels.zalo.accounts.work.dmPolicy",
+      allowFromKey: "channels.zalo.accounts.work.allowFrom",
+    });
+
+    const next = zaloDmPolicy.setPolicy(cfg, "open");
+    expect(next.channels?.zalo?.dmPolicy).toBe("disabled");
+    const workAccount = next.channels?.zalo?.accounts?.work as
+      | { dmPolicy?: string; allowFrom?: Array<string | number> }
+      | undefined;
+    expect(workAccount?.dmPolicy).toBe("open");
+  });
+
+  it('writes open policy state to the named account and preserves inherited allowFrom with "*"', () => {
+    const next = zaloDmPolicy.setPolicy(
+      {
+        channels: {
+          zalo: {
+            allowFrom: ["123456789"],
+            accounts: {
+              work: {
+                botToken: "12345689:abc-xyz",
+              },
+            },
+          },
+        },
+      } as OpenClawConfig,
+      "open",
+      "work",
+    );
+
+    expect(next.channels?.zalo?.dmPolicy).toBeUndefined();
+    const workAccount = next.channels?.zalo?.accounts?.work as
+      | { dmPolicy?: string; allowFrom?: Array<string | number> }
+      | undefined;
+    expect(workAccount?.dmPolicy).toBe("open");
+    expect(workAccount?.allowFrom).toEqual(["123456789", "*"]);
+  });
+
+  it("uses configured defaultAccount for omitted setup configured state", async () => {
+    const configured = await zaloSetupWizard.status.resolveConfigured({
+      cfg: {
+        channels: {
+          zalo: {
+            defaultAccount: "work",
+            botToken: "root-token",
+            accounts: {
+              alerts: {
+                botToken: "alerts-token",
+              },
+              work: {
+                botToken: "",
+              },
+            },
+          },
+        },
+      } as OpenClawConfig,
+    });
+
+    expect(configured).toBe(false);
+  });
+});

package/src/{onboarding.ts → setup-surface.ts}

@@ -1,38 +1,22 @@
-import type {
-  ChannelOnboardingAdapter,
-  ChannelOnboardingDmPolicy,
-  OpenClawConfig,
-  SecretInput,
-  WizardPrompter,
-} from "openclaw/plugin-sdk/zalo";
 import {
   buildSingleChannelSecretPromptState,
+  createStandardChannelSetupStatus,
   DEFAULT_ACCOUNT_ID,
   hasConfiguredSecretInput,
-  mergeAllowFromEntries,
-  normalizeAccountId,
   promptSingleChannelSecretInput,
   runSingleChannelSecretStep,
-  resolveAccountIdForConfigure,
-  setTopLevelChannelDmPolicyWithAllowFrom,
-} from "openclaw/plugin-sdk/zalo";
-import { listZaloAccountIds, resolveDefaultZaloAccountId, resolveZaloAccount } from "./accounts.js";
+  type ChannelSetupWizard,
+  type OpenClawConfig,
+  type SecretInput,
+} from "openclaw/plugin-sdk/setup";
+import { resolveZaloAccount } from "./accounts.js";
+import { noteZaloTokenHelp, promptZaloAllowFrom } from "./setup-allow-from.js";
+import { zaloDmPolicy } from "./setup-core.js";
 
 const channel = "zalo" as const;
 
 type UpdateMode = "polling" | "webhook";
 
-function setZaloDmPolicy(
-  cfg: OpenClawConfig,
-  dmPolicy: "pairing" | "allowlist" | "open" | "disabled",
-) {
-  return setTopLevelChannelDmPolicyWithAllowFrom({
-    cfg,
-    channel: "zalo",
-    dmPolicy,
-  }) as OpenClawConfig;
-}
-
 function setZaloUpdateMode(
   cfg: OpenClawConfig,
   accountId: string,
@@ -108,108 +92,22 @@ function setZaloUpdateMode(
   } as OpenClawConfig;
 }
 
-async function noteZaloTokenHelp(prompter: WizardPrompter): Promise<void> {
-  await prompter.note(
-    [
-      "1) Open Zalo Bot Platform: https://bot.zaloplatforms.com",
-      "2) Create a bot and get the token",
-      "3) Token looks like 12345689:abc-xyz",
-      "Tip: you can also set ZALO_BOT_TOKEN in your env.",
-      "Docs: https://docs.openclaw.ai/channels/zalo",
-    ].join("\n"),
-    "Zalo bot token",
-  );
-}
+export { zaloSetupAdapter } from "./setup-core.js";
 
-async function promptZaloAllowFrom(params: {
-  cfg: OpenClawConfig;
-  prompter: WizardPrompter;
-  accountId: string;
-}): Promise<OpenClawConfig> {
-  const { cfg, prompter, accountId } = params;
-  const resolved = resolveZaloAccount({ cfg, accountId });
-  const existingAllowFrom = resolved.config.allowFrom ?? [];
-  const entry = await prompter.text({
-    message: "Zalo 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 unique = mergeAllowFromEntries(existingAllowFrom, [normalized]);
-
-  if (accountId === DEFAULT_ACCOUNT_ID) {
-    return {
-      ...cfg,
-      channels: {
-        ...cfg.channels,
-        zalo: {
-          ...cfg.channels?.zalo,
-          enabled: true,
-          dmPolicy: "allowlist",
-          allowFrom: unique,
-        },
-      },
-    } as OpenClawConfig;
-  }
-
-  return {
-    ...cfg,
-    channels: {
-      ...cfg.channels,
-      zalo: {
-        ...cfg.channels?.zalo,
-        enabled: true,
-        accounts: {
-          ...cfg.channels?.zalo?.accounts,
-          [accountId]: {
-            ...cfg.channels?.zalo?.accounts?.[accountId],
-            enabled: cfg.channels?.zalo?.accounts?.[accountId]?.enabled ?? true,
-            dmPolicy: "allowlist",
-            allowFrom: unique,
-          },
-        },
-      },
-    },
-  } as OpenClawConfig;
-}
-
-const dmPolicy: ChannelOnboardingDmPolicy = {
-  label: "Zalo",
-  channel,
-  policyKey: "channels.zalo.dmPolicy",
-  allowFromKey: "channels.zalo.allowFrom",
-  getCurrent: (cfg) => (cfg.channels?.zalo?.dmPolicy ?? "pairing") as "pairing",
-  setPolicy: (cfg, policy) => setZaloDmPolicy(cfg, policy),
-  promptAllowFrom: async ({ cfg, prompter, accountId }) => {
-    const id =
-      accountId && normalizeAccountId(accountId)
-        ? (normalizeAccountId(accountId) ?? DEFAULT_ACCOUNT_ID)
-        : resolveDefaultZaloAccountId(cfg);
-    return promptZaloAllowFrom({
-      cfg: cfg,
-      prompter,
-      accountId: id,
-    });
-  },
-};
-
-export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
+export const zaloSetupWizard: ChannelSetupWizard = {
   channel,
-  dmPolicy,
-  getStatus: async ({ cfg }) => {
-    const configured = listZaloAccountIds(cfg).some((accountId) => {
+  status: createStandardChannelSetupStatus({
+    channelLabel: "Zalo",
+    configuredLabel: "configured",
+    unconfiguredLabel: "needs token",
+    configuredHint: "recommended · configured",
+    unconfiguredHint: "recommended · newcomer-friendly",
+    configuredScore: 1,
+    unconfiguredScore: 10,
+    includeStatusLine: true,
+    resolveConfigured: ({ cfg, accountId }) => {
       const account = resolveZaloAccount({
-        cfg: cfg,
+        cfg,
         accountId,
         allowUnresolvedSecretRef: true,
       });
@@ -218,41 +116,18 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
         hasConfiguredSecretInput(account.config.botToken) ||
         Boolean(account.config.tokenFile?.trim())
       );
-    });
-    return {
-      channel,
-      configured,
-      statusLines: [`Zalo: ${configured ? "configured" : "needs token"}`],
-      selectionHint: configured ? "recommended · configured" : "recommended · newcomer-friendly",
-      quickstartScore: configured ? 1 : 10,
-    };
-  },
-  configure: async ({
-    cfg,
-    prompter,
-    accountOverrides,
-    shouldPromptAccountIds,
-    forceAllowFrom,
-  }) => {
-    const defaultZaloAccountId = resolveDefaultZaloAccountId(cfg);
-    const zaloAccountId = await resolveAccountIdForConfigure({
-      cfg,
-      prompter,
-      label: "Zalo",
-      accountOverride: accountOverrides.zalo,
-      shouldPromptAccountIds,
-      listAccountIds: listZaloAccountIds,
-      defaultAccountId: defaultZaloAccountId,
-    });
-
+    },
+  }),
+  credentials: [],
+  finalize: async ({ cfg, accountId, forceAllowFrom, options, prompter }) => {
     let next = cfg;
     const resolvedAccount = resolveZaloAccount({
       cfg: next,
-      accountId: zaloAccountId,
+      accountId,
       allowUnresolvedSecretRef: true,
     });
     const accountConfigured = Boolean(resolvedAccount.token);
-    const allowEnv = zaloAccountId === DEFAULT_ACCOUNT_ID;
+    const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
     const hasConfigToken = Boolean(
       hasConfiguredSecretInput(resolvedAccount.config.botToken) || resolvedAccount.config.tokenFile,
     );
@@ -261,6 +136,7 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
       prompter,
       providerHint: "zalo",
       credentialLabel: "bot token",
+      secretInputMode: options?.secretInputMode,
       accountConfigured,
       hasConfigToken,
       allowEnv,
@@ -270,43 +146,45 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
       inputPrompt: "Enter Zalo bot token",
       preferredEnvVar: "ZALO_BOT_TOKEN",
       onMissingConfigured: async () => await noteZaloTokenHelp(prompter),
-      applyUseEnv: async (cfg) =>
-        zaloAccountId === DEFAULT_ACCOUNT_ID
+      applyUseEnv: async (currentCfg) =>
+        accountId === DEFAULT_ACCOUNT_ID
           ? ({
-              ...cfg,
+              ...currentCfg,
               channels: {
-                ...cfg.channels,
+                ...currentCfg.channels,
                 zalo: {
-                  ...cfg.channels?.zalo,
+                  ...currentCfg.channels?.zalo,
                   enabled: true,
                 },
               },
             } as OpenClawConfig)
-          : cfg,
-      applySet: async (cfg, value) =>
-        zaloAccountId === DEFAULT_ACCOUNT_ID
+          : currentCfg,
+      applySet: async (currentCfg, value) =>
+        accountId === DEFAULT_ACCOUNT_ID
           ? ({
-              ...cfg,
+              ...currentCfg,
               channels: {
-                ...cfg.channels,
+                ...currentCfg.channels,
                 zalo: {
-                  ...cfg.channels?.zalo,
+                  ...currentCfg.channels?.zalo,
                   enabled: true,
                   botToken: value,
                 },
               },
             } as OpenClawConfig)
           : ({
-              ...cfg,
+              ...currentCfg,
               channels: {
-                ...cfg.channels,
+                ...currentCfg.channels,
                 zalo: {
-                  ...cfg.channels?.zalo,
+                  ...currentCfg.channels?.zalo,
                   enabled: true,
                   accounts: {
-                    ...cfg.channels?.zalo?.accounts,
-                    [zaloAccountId]: {
-                      ...cfg.channels?.zalo?.accounts?.[zaloAccountId],
+                    ...currentCfg.channels?.zalo?.accounts,
+                    [accountId]: {
+                      ...(currentCfg.channels?.zalo?.accounts?.[accountId] as
+                        | Record<string, unknown>
+                        | undefined),
                       enabled: true,
                       botToken: value,
                     },
@@ -322,13 +200,13 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
       initialValue: Boolean(resolvedAccount.config.webhookUrl),
     });
     if (wantsWebhook) {
-      const webhookUrl = String(
+      const webhookUrl = (
         await prompter.text({
           message: "Webhook URL (https://...) ",
           initialValue: resolvedAccount.config.webhookUrl,
           validate: (value) =>
             value?.trim()?.startsWith("https://") ? undefined : "HTTPS URL required",
-        }),
+        })
       ).trim();
       const defaultPath = (() => {
         try {
@@ -337,11 +215,13 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
           return "/zalo-webhook";
         }
       })();
+
       let webhookSecretResult = await promptSingleChannelSecretInput({
         cfg: next,
         prompter,
         providerHint: "zalo-webhook",
         credentialLabel: "webhook secret",
+        secretInputMode: options?.secretInputMode,
         ...buildSingleChannelSecretPromptState({
           accountConfigured: hasConfiguredSecretInput(resolvedAccount.config.webhookSecret),
           hasConfigToken: hasConfiguredSecretInput(resolvedAccount.config.webhookSecret),
@@ -363,6 +243,7 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
           prompter,
           providerHint: "zalo-webhook",
           credentialLabel: "webhook secret",
+          secretInputMode: options?.secretInputMode,
           ...buildSingleChannelSecretPromptState({
             accountConfigured: false,
             hasConfigToken: false,
@@ -378,32 +259,33 @@ export const zaloOnboardingAdapter: ChannelOnboardingAdapter = {
         webhookSecretResult.action === "set"
           ? webhookSecretResult.value
           : resolvedAccount.config.webhookSecret;
-      const webhookPath = String(
+      const webhookPath = (
         await prompter.text({
           message: "Webhook path (optional)",
           initialValue: resolvedAccount.config.webhookPath ?? defaultPath,
-        }),
+        })
       ).trim();
       next = setZaloUpdateMode(
         next,
-        zaloAccountId,
+        accountId,
         "webhook",
         webhookUrl,
         webhookSecret,
         webhookPath || undefined,
       );
     } else {
-      next = setZaloUpdateMode(next, zaloAccountId, "polling");
+      next = setZaloUpdateMode(next, accountId, "polling");
     }
 
     if (forceAllowFrom) {
       next = await promptZaloAllowFrom({
         cfg: next,
         prompter,
-        accountId: zaloAccountId,
+        accountId,
       });
     }
 
-    return { cfg: next, accountId: zaloAccountId };
+    return { cfg: next };
   },
+  dmPolicy: zaloDmPolicy,
 };

package/src/status-issues.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, it } from "vitest";
-import { expectOpenDmPolicyConfigIssue } from "../../test-utils/status-issues.js";
+import { expectOpenDmPolicyConfigIssue } from "openclaw/plugin-sdk/channel-test-helpers";
+import { describe, it } from "vitest";
 import { collectZaloStatusIssues } from "./status-issues.js";
 
 describe("collectZaloStatusIssues", () => {
@@ -14,16 +14,4 @@ describe("collectZaloStatusIssues", () => {
       },
     });
   });
-
-  it("skips unconfigured accounts", () => {
-    const issues = collectZaloStatusIssues([
-      {
-        accountId: "default",
-        enabled: true,
-        configured: false,
-        dmPolicy: "open",
-      },
-    ]);
-    expect(issues).toHaveLength(0);
-  });
 });

package/src/status-issues.ts

@@ -1,5 +1,11 @@
-import type { ChannelAccountSnapshot, ChannelStatusIssue } from "openclaw/plugin-sdk/zalo";
-import { coerceStatusIssueAccountId, readStatusIssueFields } from "../../shared/status-issues.js";
+import type {
+  ChannelAccountSnapshot,
+  ChannelStatusIssue,
+} from "openclaw/plugin-sdk/channel-contract";
+import {
+  coerceStatusIssueAccountId,
+  readStatusIssueFields,
+} from "openclaw/plugin-sdk/extension-shared";
 
 const ZALO_STATUS_FIELDS = ["accountId", "enabled", "configured", "dmPolicy"] as const;