@openclaw/zalo 2026.3.13 → 2026.5.2-beta.1

package/src/secret-contract.ts

@@ -0,0 +1,109 @@
+import {
+  collectConditionalChannelFieldAssignments,
+  getChannelSurface,
+  hasOwnProperty,
+  type ResolverContext,
+  type SecretDefaults,
+  type SecretTargetRegistryEntry,
+} from "openclaw/plugin-sdk/channel-secret-basic-runtime";
+
+export const secretTargetRegistryEntries: SecretTargetRegistryEntry[] = [
+  {
+    id: "channels.zalo.accounts.*.botToken",
+    targetType: "channels.zalo.accounts.*.botToken",
+    configFile: "openclaw.json",
+    pathPattern: "channels.zalo.accounts.*.botToken",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.zalo.accounts.*.webhookSecret",
+    targetType: "channels.zalo.accounts.*.webhookSecret",
+    configFile: "openclaw.json",
+    pathPattern: "channels.zalo.accounts.*.webhookSecret",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.zalo.botToken",
+    targetType: "channels.zalo.botToken",
+    configFile: "openclaw.json",
+    pathPattern: "channels.zalo.botToken",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.zalo.webhookSecret",
+    targetType: "channels.zalo.webhookSecret",
+    configFile: "openclaw.json",
+    pathPattern: "channels.zalo.webhookSecret",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+];
+
+export function collectRuntimeConfigAssignments(params: {
+  config: { channels?: Record<string, unknown> };
+  defaults?: SecretDefaults;
+  context: ResolverContext;
+}): void {
+  const resolved = getChannelSurface(params.config, "zalo");
+  if (!resolved) {
+    return;
+  }
+  const { channel: zalo, surface } = resolved;
+  collectConditionalChannelFieldAssignments({
+    channelKey: "zalo",
+    field: "botToken",
+    channel: zalo,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topLevelActiveWithoutAccounts: true,
+    topLevelInheritedAccountActive: ({ account, enabled }) =>
+      enabled && !hasOwnProperty(account, "botToken"),
+    accountActive: ({ enabled }) => enabled,
+    topInactiveReason: "no enabled Zalo surface inherits this top-level botToken.",
+    accountInactiveReason: "Zalo account is disabled.",
+  });
+  const baseWebhookUrl = typeof zalo.webhookUrl === "string" ? zalo.webhookUrl.trim() : "";
+  const accountWebhookUrl = (account: Record<string, unknown>) =>
+    hasOwnProperty(account, "webhookUrl")
+      ? typeof account.webhookUrl === "string"
+        ? account.webhookUrl.trim()
+        : ""
+      : baseWebhookUrl;
+  collectConditionalChannelFieldAssignments({
+    channelKey: "zalo",
+    field: "webhookSecret",
+    channel: zalo,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topLevelActiveWithoutAccounts: baseWebhookUrl.length > 0,
+    topLevelInheritedAccountActive: ({ account, enabled }) =>
+      enabled && !hasOwnProperty(account, "webhookSecret") && accountWebhookUrl(account).length > 0,
+    accountActive: ({ account, enabled }) => enabled && accountWebhookUrl(account).length > 0,
+    topInactiveReason:
+      "no enabled Zalo webhook surface inherits this top-level webhookSecret (webhook mode is not active).",
+    accountInactiveReason:
+      "Zalo account is disabled or webhook mode is not active for this account.",
+  });
+}
+
+export const channelSecrets = {
+  secretTargetRegistryEntries,
+  collectRuntimeConfigAssignments,
+};

package/src/secret-input.ts

@@ -1,13 +1,5 @@
-import {
-  buildSecretInputSchema,
-  hasConfiguredSecretInput,
-  normalizeResolvedSecretInputString,
-  normalizeSecretInputString,
-} from "openclaw/plugin-sdk/zalo";
-
 export {
   buildSecretInputSchema,
-  hasConfiguredSecretInput,
   normalizeResolvedSecretInputString,
   normalizeSecretInputString,
-};
+} from "openclaw/plugin-sdk/secret-input";

package/src/send.test.ts

@@ -0,0 +1,120 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const sendMessageMock = vi.fn();
+const sendPhotoMock = vi.fn();
+const resolveZaloProxyFetchMock = vi.fn();
+
+vi.mock("./api.js", () => ({
+  sendMessage: (...args: unknown[]) => sendMessageMock(...args),
+  sendPhoto: (...args: unknown[]) => sendPhotoMock(...args),
+}));
+
+vi.mock("./proxy.js", () => ({
+  resolveZaloProxyFetch: (...args: unknown[]) => resolveZaloProxyFetchMock(...args),
+}));
+
+import { sendMessageZalo, sendPhotoZalo } from "./send.js";
+
+describe("zalo send", () => {
+  beforeEach(() => {
+    sendMessageMock.mockReset();
+    sendPhotoMock.mockReset();
+    resolveZaloProxyFetchMock.mockReset();
+    resolveZaloProxyFetchMock.mockReturnValue(undefined);
+  });
+
+  it("sends text messages through the message API", async () => {
+    sendMessageMock.mockResolvedValueOnce({
+      ok: true,
+      result: { message_id: "z-msg-1" },
+    });
+
+    const result = await sendMessageZalo("dm-chat-1", "hello there", {
+      token: "zalo-token",
+    });
+
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      "zalo-token",
+      {
+        chat_id: "dm-chat-1",
+        text: "hello there",
+      },
+      undefined,
+    );
+    expect(sendPhotoMock).not.toHaveBeenCalled();
+    expect(result).toEqual({ ok: true, messageId: "z-msg-1" });
+  });
+
+  it("routes media-bearing sends through the photo API and uses text as caption", async () => {
+    sendPhotoMock.mockResolvedValueOnce({
+      ok: true,
+      result: { message_id: "z-photo-1" },
+    });
+
+    const result = await sendMessageZalo("dm-chat-2", "caption text", {
+      token: "zalo-token",
+      mediaUrl: "https://example.com/photo.jpg",
+      caption: "ignored fallback caption",
+    });
+
+    expect(sendPhotoMock).toHaveBeenCalledWith(
+      "zalo-token",
+      {
+        chat_id: "dm-chat-2",
+        photo: "https://example.com/photo.jpg",
+        caption: "caption text",
+      },
+      undefined,
+    );
+    expect(sendMessageMock).not.toHaveBeenCalled();
+    expect(result).toEqual({ ok: true, messageId: "z-photo-1" });
+  });
+
+  it("fails fast for missing token or blank photo URLs", async () => {
+    await expect(sendMessageZalo("dm-chat-3", "hello", {})).resolves.toEqual({
+      ok: false,
+      error: "No Zalo bot token configured",
+    });
+
+    await expect(
+      sendPhotoZalo("dm-chat-4", "   ", {
+        token: "zalo-token",
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      error: "No photo URL provided",
+    });
+
+    expect(sendMessageMock).not.toHaveBeenCalled();
+    expect(sendPhotoMock).not.toHaveBeenCalled();
+  });
+
+  it("sends cfg-backed media directly without hosted-media rewrites", async () => {
+    sendPhotoMock.mockResolvedValueOnce({
+      ok: true,
+      result: { message_id: "z-photo-2" },
+    });
+
+    const result = await sendPhotoZalo("dm-chat-5", "https://example.com/photo.jpg", {
+      cfg: {
+        channels: {
+          zalo: {
+            botToken: "zalo-token",
+            webhookUrl: "https://gateway.example.com/zalo-webhook",
+          },
+        },
+      } as never,
+    });
+
+    expect(sendPhotoMock).toHaveBeenCalledWith(
+      "zalo-token",
+      {
+        chat_id: "dm-chat-5",
+        photo: "https://example.com/photo.jpg",
+        caption: undefined,
+      },
+      undefined,
+    );
+    expect(result).toEqual({ ok: true, messageId: "z-photo-2" });
+  });
+});

package/src/send.ts

@@ -1,11 +1,12 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/zalo";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import { resolveZaloAccount } from "./accounts.js";
 import type { ZaloFetch } from "./api.js";
 import { sendMessage, sendPhoto } from "./api.js";
 import { resolveZaloProxyFetch } from "./proxy.js";
 import { resolveZaloToken } from "./token.js";
 
-export type ZaloSendOptions = {
+type ZaloSendOptions = {
   token?: string;
   accountId?: string;
   cfg?: OpenClawConfig;
@@ -15,7 +16,7 @@ export type ZaloSendOptions = {
   proxy?: string;
 };
 
-export type ZaloSendResult = {
+type ZaloSendResult = {
   ok: boolean;
   messageId?: string;
   error?: string;
@@ -39,7 +40,7 @@ async function runZaloSend(
     const result = toZaloSendResult(await send());
     return result.ok ? result : { ok: false, error: failureMessage };
   } catch (err) {
-    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    return { ok: false, error: formatErrorMessage(err) };
   }
 }
 
@@ -138,14 +139,15 @@ export async function sendPhotoZalo(
   }
 
   return await runZaloSend("Failed to send photo", () =>
-    sendPhoto(
-      context.token,
-      {
-        chat_id: context.chatId,
-        photo: photoUrl.trim(),
-        caption: options.caption?.slice(0, 2000),
-      },
-      context.fetcher,
-    ),
+    (async () =>
+      sendPhoto(
+        context.token,
+        {
+          chat_id: context.chatId,
+          photo: photoUrl.trim(),
+          caption: options.caption?.slice(0, 2000),
+        },
+        context.fetcher,
+      ))(),
   );
 }

package/src/session-route.ts

@@ -0,0 +1,32 @@
+import {
+  buildChannelOutboundSessionRoute,
+  stripChannelTargetPrefix,
+  stripTargetKindPrefix,
+  type ChannelOutboundSessionRouteParams,
+} from "openclaw/plugin-sdk/core";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+
+export function resolveZaloOutboundSessionRoute(params: ChannelOutboundSessionRouteParams) {
+  const trimmed = stripChannelTargetPrefix(params.target, "zalo", "zl");
+  if (!trimmed) {
+    return null;
+  }
+  const isGroup = normalizeLowercaseStringOrEmpty(trimmed).startsWith("group:");
+  const peerId = stripTargetKindPrefix(trimmed);
+  if (!peerId) {
+    return null;
+  }
+  return buildChannelOutboundSessionRoute({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "zalo",
+    accountId: params.accountId,
+    peer: {
+      kind: isGroup ? "group" : "direct",
+      id: peerId,
+    },
+    chatType: isGroup ? "group" : "direct",
+    from: isGroup ? `zalo:group:${peerId}` : `zalo:${peerId}`,
+    to: `zalo:${peerId}`,
+  });
+}

package/src/setup-allow-from.ts

@@ -0,0 +1,94 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  formatDocsLink,
+  mergeAllowFromEntries,
+  type ChannelSetupDmPolicy,
+  type ChannelSetupWizard,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/setup";
+import { resolveDefaultZaloAccountId, resolveZaloAccount } from "./accounts.js";
+
+type ZaloAccountSetupConfig = {
+  enabled?: boolean;
+};
+
+export async function noteZaloTokenHelp(
+  prompter: Parameters<NonNullable<ChannelSetupWizard["finalize"]>>[0]["prompter"],
+): 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: ${formatDocsLink("/channels/zalo", "zalo")}`,
+    ].join("\n"),
+    "Zalo bot token",
+  );
+}
+
+export async function promptZaloAllowFrom(params: {
+  cfg: OpenClawConfig;
+  prompter: Parameters<NonNullable<ChannelSetupDmPolicy["promptAllowFrom"]>>[0]["prompter"];
+  accountId?: string;
+}): Promise<OpenClawConfig> {
+  const { cfg, prompter } = params;
+  const accountId = params.accountId ?? resolveDefaultZaloAccountId(cfg);
+  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 = (value ?? "").trim();
+      if (!raw) {
+        return "Required";
+      }
+      if (!/^\d+$/.test(raw)) {
+        return "Use a numeric Zalo user id";
+      }
+      return undefined;
+    },
+  });
+  const normalized = 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;
+  }
+
+  const currentAccount = cfg.channels?.zalo?.accounts?.[accountId] as
+    | ZaloAccountSetupConfig
+    | undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      zalo: {
+        ...cfg.channels?.zalo,
+        enabled: true,
+        accounts: {
+          ...cfg.channels?.zalo?.accounts,
+          [accountId]: {
+            ...currentAccount,
+            enabled: currentAccount?.enabled ?? true,
+            dmPolicy: "allowlist",
+            allowFrom: unique,
+          },
+        },
+      },
+    },
+  } as OpenClawConfig;
+}

package/src/setup-core.ts

@@ -0,0 +1,149 @@
+import {
+  addWildcardAllowFrom,
+  createDelegatedSetupWizardProxy,
+  createPatchedAccountSetupAdapter,
+  createSetupInputPresenceValidator,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  type ChannelSetupDmPolicy,
+  type ChannelSetupWizard,
+} from "openclaw/plugin-sdk/setup";
+import { resolveDefaultZaloAccountId, resolveZaloAccount } from "./accounts.js";
+import { promptZaloAllowFrom } from "./setup-allow-from.js";
+
+const channel = "zalo" as const;
+
+type ZaloAccountSetupConfig = {
+  enabled?: boolean;
+  dmPolicy?: string;
+  allowFrom?: Array<string | number> | ReadonlyArray<string | number>;
+};
+
+export const zaloSetupAdapter = createPatchedAccountSetupAdapter({
+  channelKey: channel,
+  validateInput: createSetupInputPresenceValidator({
+    defaultAccountOnlyEnvError: "ZALO_BOT_TOKEN can only be used for the default account.",
+    whenNotUseEnv: [
+      {
+        someOf: ["token", "tokenFile"],
+        message: "Zalo requires token or --token-file (or --use-env).",
+      },
+    ],
+  }),
+  buildPatch: (input) =>
+    input.useEnv
+      ? {}
+      : input.tokenFile
+        ? { tokenFile: input.tokenFile }
+        : input.token
+          ? { botToken: input.token }
+          : {},
+});
+
+export const zaloDmPolicy: ChannelSetupDmPolicy = {
+  label: "Zalo",
+  channel,
+  policyKey: "channels.zalo.dmPolicy",
+  allowFromKey: "channels.zalo.allowFrom",
+  resolveConfigKeys: (cfg, accountId) =>
+    (accountId ?? resolveDefaultZaloAccountId(cfg)) !== DEFAULT_ACCOUNT_ID
+      ? {
+          policyKey: `channels.zalo.accounts.${accountId ?? resolveDefaultZaloAccountId(cfg)}.dmPolicy`,
+          allowFromKey: `channels.zalo.accounts.${accountId ?? resolveDefaultZaloAccountId(cfg)}.allowFrom`,
+        }
+      : {
+          policyKey: "channels.zalo.dmPolicy",
+          allowFromKey: "channels.zalo.allowFrom",
+        },
+  getCurrent: (cfg, accountId) =>
+    resolveZaloAccount({
+      cfg: cfg,
+      accountId: accountId ?? resolveDefaultZaloAccountId(cfg),
+    }).config.dmPolicy ?? "pairing",
+  setPolicy: (cfg, policy, accountId) => {
+    const resolvedAccountId =
+      accountId && normalizeAccountId(accountId)
+        ? (normalizeAccountId(accountId) ?? DEFAULT_ACCOUNT_ID)
+        : resolveDefaultZaloAccountId(cfg);
+    const resolved = resolveZaloAccount({
+      cfg: cfg,
+      accountId: resolvedAccountId,
+    });
+    if (resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          zalo: {
+            ...cfg.channels?.zalo,
+            enabled: true,
+            dmPolicy: policy,
+            ...(policy === "open"
+              ? { allowFrom: addWildcardAllowFrom(resolved.config.allowFrom) }
+              : {}),
+          },
+        },
+      };
+    }
+    const currentAccount = cfg.channels?.zalo?.accounts?.[resolvedAccountId] as
+      | ZaloAccountSetupConfig
+      | undefined;
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalo: {
+          ...cfg.channels?.zalo,
+          enabled: true,
+          accounts: {
+            ...cfg.channels?.zalo?.accounts,
+            [resolvedAccountId]: {
+              ...currentAccount,
+              enabled: currentAccount?.enabled ?? true,
+              dmPolicy: policy,
+              ...(policy === "open"
+                ? { allowFrom: addWildcardAllowFrom(resolved.config.allowFrom) }
+                : {}),
+            },
+          },
+        },
+      },
+    };
+  },
+  promptAllowFrom: async ({ cfg, prompter, accountId }) =>
+    promptZaloAllowFrom({
+      cfg,
+      prompter,
+      accountId: accountId ?? resolveDefaultZaloAccountId(cfg),
+    }),
+};
+
+export function createZaloSetupWizardProxy(
+  loadWizard: () => Promise<ChannelSetupWizard>,
+): ChannelSetupWizard {
+  return createDelegatedSetupWizardProxy({
+    channel,
+    loadWizard,
+    status: {
+      configuredLabel: "configured",
+      unconfiguredLabel: "needs token",
+      configuredHint: "recommended · configured",
+      unconfiguredHint: "recommended · newcomer-friendly",
+      configuredScore: 1,
+      unconfiguredScore: 10,
+    },
+    credentials: [],
+    delegateFinalize: true,
+    dmPolicy: zaloDmPolicy,
+    disable: (cfg) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalo: {
+          ...cfg.channels?.zalo,
+          enabled: false,
+        },
+      },
+    }),
+  });
+}

package/src/{onboarding.status.test.ts → setup-status.test.ts}

@@ -1,10 +1,19 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/zalo";
+import { createPluginSetupWizardStatus } from "openclaw/plugin-sdk/plugin-test-runtime";
 import { describe, expect, it } from "vitest";
-import { zaloOnboardingAdapter } from "./onboarding.js";
+import type { OpenClawConfig } from "../runtime-api.js";
+import { zaloSetupWizard } from "./setup-surface.js";
 
-describe("zalo onboarding status", () => {
+const zaloGetStatus = createPluginSetupWizardStatus({
+  id: "zalo",
+  meta: {
+    label: "Zalo",
+  },
+  setupWizard: zaloSetupWizard,
+} as never);
+
+describe("zalo setup wizard status", () => {
   it("treats SecretRef botToken as configured", async () => {
-    const status = await zaloOnboardingAdapter.getStatus({
+    const status = await zaloGetStatus({
       cfg: {
         channels: {
           zalo: {