@openclaw/zalouser 2026.2.21 → 2026.2.23

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.2.22
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.1.17-1
 
 - Initial version with full channel plugin support

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/zalouser",
-  "version": "2026.2.21",
+  "version": "2026.2.23",
   "description": "OpenClaw Zalo Personal Account plugin via zca-cli",
   "type": "module",
   "dependencies": {

package/src/monitor.ts

@@ -1,10 +1,20 @@
 import type { ChildProcess } from "node:child_process";
-import type { OpenClawConfig, MarkdownTableMode, RuntimeEnv } from "openclaw/plugin-sdk";
+import type {
+  MarkdownTableMode,
+  OpenClawConfig,
+  OutboundReplyPayload,
+  RuntimeEnv,
+} from "openclaw/plugin-sdk";
 import {
   createReplyPrefixOptions,
+  resolveOutboundMediaUrls,
   mergeAllowlist,
+  resolveOpenProviderRuntimeGroupPolicy,
+  resolveDefaultGroupPolicy,
   resolveSenderCommandAuthorization,
+  sendMediaWithLeadingCaption,
   summarizeMapping,
+  warnMissingProviderGroupPolicyFallbackOnce,
 } from "openclaw/plugin-sdk";
 import { getZalouserRuntime } from "./runtime.js";
 import { sendMessageZalouser } from "./send.js";
@@ -177,8 +187,18 @@ async function processMessage(
   const groupName = metadata?.threadName ?? "";
   const chatId = threadId;
 
-  const defaultGroupPolicy = config.channels?.defaults?.groupPolicy;
-  const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "open";
+  const defaultGroupPolicy = resolveDefaultGroupPolicy(config);
+  const { groupPolicy, providerMissingFallbackApplied } = resolveOpenProviderRuntimeGroupPolicy({
+    providerConfigPresent: config.channels?.zalouser !== undefined,
+    groupPolicy: account.config.groupPolicy,
+    defaultGroupPolicy,
+  });
+  warnMissingProviderGroupPolicyFallbackOnce({
+    providerMissingFallbackApplied,
+    providerKey: "zalouser",
+    accountId: account.accountId,
+    log: (message) => logVerbose(core, runtime, message),
+  });
   const groups = account.config.groups ?? {};
   if (isGroup) {
     if (groupPolicy === "disabled") {
@@ -379,7 +399,7 @@ async function processMessage(
 }
 
 async function deliverZalouserReply(params: {
-  payload: { text?: string; mediaUrls?: string[]; mediaUrl?: string };
+  payload: OutboundReplyPayload;
   profile: string;
   chatId: string;
   isGroup: boolean;
@@ -395,29 +415,23 @@ async function deliverZalouserReply(params: {
   const tableMode = params.tableMode ?? "code";
   const text = core.channel.text.convertMarkdownTables(payload.text ?? "", tableMode);
 
-  const mediaList = payload.mediaUrls?.length
-    ? payload.mediaUrls
-    : payload.mediaUrl
-      ? [payload.mediaUrl]
-      : [];
-
-  if (mediaList.length > 0) {
-    let first = true;
-    for (const mediaUrl of mediaList) {
-      const caption = first ? text : undefined;
-      first = false;
-      try {
-        logVerbose(core, runtime, `Sending media to ${chatId}`);
-        await sendMessageZalouser(chatId, caption ?? "", {
-          profile,
-          mediaUrl,
-          isGroup,
-        });
-        statusSink?.({ lastOutboundAt: Date.now() });
-      } catch (err) {
-        runtime.error(`Zalouser media send failed: ${String(err)}`);
-      }
-    }
+  const sentMedia = await sendMediaWithLeadingCaption({
+    mediaUrls: resolveOutboundMediaUrls(payload),
+    caption: text,
+    send: async ({ mediaUrl, caption }) => {
+      logVerbose(core, runtime, `Sending media to ${chatId}`);
+      await sendMessageZalouser(chatId, caption ?? "", {
+        profile,
+        mediaUrl,
+        isGroup,
+      });
+      statusSink?.({ lastOutboundAt: Date.now() });
+    },
+    onError: (error) => {
+      runtime.error(`Zalouser media send failed: ${String(error)}`);
+    },
+  });
+  if (sentMedia) {
     return;
   }
 

package/src/onboarding.ts

@@ -23,6 +23,45 @@ import { runZca, runZcaInteractive, checkZcaInstalled, parseJsonOutput } from ".
 
 const channel = "zalouser" as const;
 
+function setZalouserAccountScopedConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+  defaultPatch: Record<string, unknown>,
+  accountPatch: Record<string, unknown> = defaultPatch,
+): OpenClawConfig {
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalouser: {
+          ...cfg.channels?.zalouser,
+          enabled: true,
+          ...defaultPatch,
+        },
+      },
+    } 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,
+            ...accountPatch,
+          },
+        },
+      },
+    },
+  } as OpenClawConfig;
+}
+
 function setZalouserDmPolicy(
   cfg: OpenClawConfig,
   dmPolicy: "pairing" | "allowlist" | "open" | "disabled",
@@ -123,40 +162,10 @@ async function promptZalouserAllowFrom(params: {
       continue;
     }
     const unique = mergeAllowFromEntries(existingAllowFrom, results.filter(Boolean) as string[]);
-    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;
+    return setZalouserAccountScopedConfig(cfg, accountId, {
+      dmPolicy: "allowlist",
+      allowFrom: unique,
+    });
   }
 }
 
@@ -165,37 +174,9 @@ function setZalouserGroupPolicy(
   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;
+  return setZalouserAccountScopedConfig(cfg, accountId, {
+    groupPolicy,
+  });
 }
 
 function setZalouserGroupAllowlist(
@@ -204,37 +185,9 @@ function setZalouserGroupAllowlist(
   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;
+  return setZalouserAccountScopedConfig(cfg, accountId, {
+    groups,
+  });
 }
 
 async function resolveZalouserGroups(params: {
@@ -403,38 +356,12 @@ export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
     }
 
     // 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;
-    }
+    next = setZalouserAccountScopedConfig(
+      next,
+      accountId,
+      { profile: account.profile !== "default" ? account.profile : undefined },
+      { profile: account.profile, enabled: true },
+    );
 
     if (forceAllowFrom) {
       next = await promptZalouserAllowFrom({
@@ -447,7 +374,7 @@ export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
     const accessConfig = await promptChannelAccessConfig({
       prompter,
       label: "Zalo groups",
-      currentPolicy: account.config.groupPolicy ?? "open",
+      currentPolicy: account.config.groupPolicy ?? "allowlist",
       currentEntries: Object.keys(account.config.groups ?? {}),
       placeholder: "Family, Work, 123456789",
       updatePrompt: Boolean(account.config.groups),

package/src/send.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  sendImageZalouser,
+  sendLinkZalouser,
+  sendMessageZalouser,
+  type ZalouserSendResult,
+} from "./send.js";
+import { runZca } from "./zca.js";
+
+vi.mock("./zca.js", () => ({
+  runZca: vi.fn(),
+}));
+
+const mockRunZca = vi.mocked(runZca);
+const originalZcaProfile = process.env.ZCA_PROFILE;
+
+function okResult(stdout = "message_id: msg-1") {
+  return {
+    ok: true,
+    stdout,
+    stderr: "",
+    exitCode: 0,
+  };
+}
+
+function failResult(stderr = "") {
+  return {
+    ok: false,
+    stdout: "",
+    stderr,
+    exitCode: 1,
+  };
+}
+
+describe("zalouser send helpers", () => {
+  beforeEach(() => {
+    mockRunZca.mockReset();
+    delete process.env.ZCA_PROFILE;
+  });
+
+  afterEach(() => {
+    if (originalZcaProfile) {
+      process.env.ZCA_PROFILE = originalZcaProfile;
+      return;
+    }
+    delete process.env.ZCA_PROFILE;
+  });
+
+  it("returns validation error when thread id is missing", async () => {
+    const result = await sendMessageZalouser("", "hello");
+    expect(result).toEqual({
+      ok: false,
+      error: "No threadId provided",
+    } satisfies ZalouserSendResult);
+    expect(mockRunZca).not.toHaveBeenCalled();
+  });
+
+  it("builds text send command with truncation and group flag", async () => {
+    mockRunZca.mockResolvedValueOnce(okResult("message id: mid-123"));
+
+    const result = await sendMessageZalouser("  thread-1  ", "x".repeat(2200), {
+      profile: "profile-a",
+      isGroup: true,
+    });
+
+    expect(mockRunZca).toHaveBeenCalledWith(["msg", "send", "thread-1", "x".repeat(2000), "-g"], {
+      profile: "profile-a",
+    });
+    expect(result).toEqual({ ok: true, messageId: "mid-123" });
+  });
+
+  it("routes media sends from sendMessage and keeps text as caption", async () => {
+    mockRunZca.mockResolvedValueOnce(okResult());
+
+    await sendMessageZalouser("thread-2", "media caption", {
+      profile: "profile-b",
+      mediaUrl: "https://cdn.example.com/video.mp4",
+      isGroup: true,
+    });
+
+    expect(mockRunZca).toHaveBeenCalledWith(
+      [
+        "msg",
+        "video",
+        "thread-2",
+        "-u",
+        "https://cdn.example.com/video.mp4",
+        "-m",
+        "media caption",
+        "-g",
+      ],
+      { profile: "profile-b" },
+    );
+  });
+
+  it("maps audio media to voice command", async () => {
+    mockRunZca.mockResolvedValueOnce(okResult());
+
+    await sendMessageZalouser("thread-3", "", {
+      profile: "profile-c",
+      mediaUrl: "https://cdn.example.com/clip.mp3",
+    });
+
+    expect(mockRunZca).toHaveBeenCalledWith(
+      ["msg", "voice", "thread-3", "-u", "https://cdn.example.com/clip.mp3"],
+      { profile: "profile-c" },
+    );
+  });
+
+  it("builds image command with caption and returns fallback error", async () => {
+    mockRunZca.mockResolvedValueOnce(failResult(""));
+
+    const result = await sendImageZalouser("thread-4", " https://cdn.example.com/img.png ", {
+      profile: "profile-d",
+      caption: "caption text",
+      isGroup: true,
+    });
+
+    expect(mockRunZca).toHaveBeenCalledWith(
+      [
+        "msg",
+        "image",
+        "thread-4",
+        "-u",
+        "https://cdn.example.com/img.png",
+        "-m",
+        "caption text",
+        "-g",
+      ],
+      { profile: "profile-d" },
+    );
+    expect(result).toEqual({ ok: false, error: "Failed to send image" });
+  });
+
+  it("uses env profile fallback and builds link command", async () => {
+    process.env.ZCA_PROFILE = "env-profile";
+    mockRunZca.mockResolvedValueOnce(okResult("abc123"));
+
+    const result = await sendLinkZalouser("thread-5", " https://openclaw.ai ", { isGroup: true });
+
+    expect(mockRunZca).toHaveBeenCalledWith(
+      ["msg", "link", "thread-5", "https://openclaw.ai", "-g"],
+      { profile: "env-profile" },
+    );
+    expect(result).toEqual({ ok: true, messageId: "abc123" });
+  });
+
+  it("returns caught command errors", async () => {
+    mockRunZca.mockRejectedValueOnce(new Error("zca unavailable"));
+
+    await expect(sendLinkZalouser("thread-6", "https://openclaw.ai")).resolves.toEqual({
+      ok: false,
+      error: "zca unavailable",
+    });
+  });
+});

package/src/send.ts

@@ -13,12 +13,41 @@ export type ZalouserSendResult = {
   error?: string;
 };
 
+function resolveProfile(options: ZalouserSendOptions): string {
+  return options.profile || process.env.ZCA_PROFILE || "default";
+}
+
+function appendCaptionAndGroupFlags(args: string[], options: ZalouserSendOptions): void {
+  if (options.caption) {
+    args.push("-m", options.caption.slice(0, 2000));
+  }
+  if (options.isGroup) {
+    args.push("-g");
+  }
+}
+
+async function runSendCommand(
+  args: string[],
+  profile: string,
+  fallbackError: string,
+): Promise<ZalouserSendResult> {
+  try {
+    const result = await runZca(args, { profile });
+    if (result.ok) {
+      return { ok: true, messageId: extractMessageId(result.stdout) };
+    }
+    return { ok: false, error: result.stderr || fallbackError };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 export async function sendMessageZalouser(
   threadId: string,
   text: string,
   options: ZalouserSendOptions = {},
 ): Promise<ZalouserSendResult> {
-  const profile = options.profile || process.env.ZCA_PROFILE || "default";
+  const profile = resolveProfile(options);
 
   if (!threadId?.trim()) {
     return { ok: false, error: "No threadId provided" };
@@ -38,17 +67,7 @@ export async function sendMessageZalouser(
     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) };
-  }
+  return runSendCommand(args, profile, "Failed to send message");
 }
 
 async function sendMediaZalouser(
@@ -56,7 +75,7 @@ async function sendMediaZalouser(
   mediaUrl: string,
   options: ZalouserSendOptions = {},
 ): Promise<ZalouserSendResult> {
-  const profile = options.profile || process.env.ZCA_PROFILE || "default";
+  const profile = resolveProfile(options);
 
   if (!threadId?.trim()) {
     return { ok: false, error: "No threadId provided" };
@@ -78,24 +97,8 @@ async function sendMediaZalouser(
   }
 
   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) };
-  }
+  appendCaptionAndGroupFlags(args, options);
+  return runSendCommand(args, profile, `Failed to send ${command}`);
 }
 
 export async function sendImageZalouser(
@@ -103,24 +106,10 @@ export async function sendImageZalouser(
   imageUrl: string,
   options: ZalouserSendOptions = {},
 ): Promise<ZalouserSendResult> {
-  const profile = options.profile || process.env.ZCA_PROFILE || "default";
+  const profile = resolveProfile(options);
   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) };
-  }
+  appendCaptionAndGroupFlags(args, options);
+  return runSendCommand(args, profile, "Failed to send image");
 }
 
 export async function sendLinkZalouser(
@@ -128,21 +117,13 @@ export async function sendLinkZalouser(
   url: string,
   options: ZalouserSendOptions = {},
 ): Promise<ZalouserSendResult> {
-  const profile = options.profile || process.env.ZCA_PROFILE || "default";
+  const profile = resolveProfile(options);
   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) };
-  }
+  return runSendCommand(args, profile, "Failed to send link");
 }
 
 function extractMessageId(stdout: string): string | undefined {

package/src/types.ts

@@ -68,35 +68,30 @@ export type ListenOptions = CommonOptions & {
   prefix?: string;
 };
 
-export type ZalouserAccountConfig = {
+type ZalouserToolConfig = { allow?: string[]; deny?: string[] };
+
+type ZalouserGroupConfig = {
+  allow?: boolean;
   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; tools?: { allow?: string[]; deny?: string[] } }
-  >;
-  messagePrefix?: string;
-  responsePrefix?: string;
+  tools?: ZalouserToolConfig;
 };
 
-export type ZalouserConfig = {
+type ZalouserSharedConfig = {
   enabled?: boolean;
   name?: string;
   profile?: string;
-  defaultAccount?: string;
   dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
   allowFrom?: Array<string | number>;
   groupPolicy?: "open" | "allowlist" | "disabled";
-  groups?: Record<
-    string,
-    { allow?: boolean; enabled?: boolean; tools?: { allow?: string[]; deny?: string[] } }
-  >;
+  groups?: Record<string, ZalouserGroupConfig>;
   messagePrefix?: string;
   responsePrefix?: string;
+};
+
+export type ZalouserAccountConfig = ZalouserSharedConfig;
+
+export type ZalouserConfig = ZalouserSharedConfig & {
+  defaultAccount?: string;
   accounts?: Record<string, ZalouserAccountConfig>;
 };