@openclaw/zalouser 2026.3.13 → 2026.5.2-beta.1

package/src/zca-client.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from "vitest";
+
+describe("zca-client runtime loading", () => {
+  it("does not import zca-js until a session is created", async () => {
+    vi.clearAllMocks();
+    const runtimeFactory = vi.fn(() => ({
+      Zalo: class MockZalo {
+        constructor(public readonly options?: { logging?: boolean; selfListen?: boolean }) {}
+      },
+    }));
+
+    vi.doMock("zca-js", runtimeFactory);
+
+    const zcaClient = await import("./zca-client.js");
+    expect(runtimeFactory).not.toHaveBeenCalled();
+
+    const client = await zcaClient.createZalo({ logging: false, selfListen: true });
+
+    expect(runtimeFactory).toHaveBeenCalledTimes(1);
+    expect(client).toMatchObject({
+      options: { logging: false, selfListen: true },
+    });
+  });
+});

package/src/zca-client.ts

@@ -1,65 +1,25 @@
 import {
-  LoginQRCallbackEventType as LoginQRCallbackEventTypeRuntime,
-  Reactions as ReactionsRuntime,
-  ThreadType as ThreadTypeRuntime,
-  Zalo as ZaloRuntime,
-} from "zca-js";
+  LoginQRCallbackEventType,
+  Reactions,
+  TextStyle,
+  ThreadType,
+  type Style,
+} from "./zca-constants.js";
 
-export const ThreadType = ThreadTypeRuntime as {
-  User: 0;
-  Group: 1;
+type ZcaJsRuntime = {
+  Zalo: unknown;
 };
+let zcaJsRuntimePromise: Promise<ZcaJsRuntime> | null = null;
 
-export const LoginQRCallbackEventType = LoginQRCallbackEventTypeRuntime as {
-  QRCodeGenerated: 0;
-  QRCodeExpired: 1;
-  QRCodeScanned: 2;
-  QRCodeDeclined: 3;
-  GotLoginInfo: 4;
-};
-
-export const Reactions = ReactionsRuntime as Record<string, string> & {
-  HEART: string;
-  LIKE: string;
-  HAHA: string;
-  WOW: string;
-  CRY: string;
-  ANGRY: string;
-  NONE: string;
-};
-
-// Mirror zca-js sendMessage style constants locally because the package root
-// typing surface does not consistently expose TextStyle/Style to tsgo.
-export const TextStyle = {
-  Bold: "b",
-  Italic: "i",
-  Underline: "u",
-  StrikeThrough: "s",
-  Red: "c_db342e",
-  Orange: "c_f27806",
-  Yellow: "c_f7b503",
-  Green: "c_15a85f",
-  Small: "f_13",
-  Big: "f_18",
-  UnorderedList: "lst_1",
-  OrderedList: "lst_2",
-  Indent: "ind_$",
-} as const;
-
-type TextStyleValue = (typeof TextStyle)[keyof typeof TextStyle];
+async function loadZcaJsRuntime(): Promise<ZcaJsRuntime> {
+  // Keep zca-js behind a runtime boundary so bundled metadata/contracts can load
+  // without resolving its optional WebSocket dependency tree.
+  zcaJsRuntimePromise ??= import("zca-js").then((mod) => mod as unknown as ZcaJsRuntime);
+  return await zcaJsRuntimePromise;
+}
 
-export type Style =
-  | {
-      start: number;
-      len: number;
-      st: Exclude<TextStyleValue, typeof TextStyle.Indent>;
-    }
-  | {
-      start: number;
-      len: number;
-      st: typeof TextStyle.Indent;
-      indentSize?: number;
-    };
+export { LoginQRCallbackEventType, Reactions, TextStyle, ThreadType };
+export type { Style };
 
 export type Credentials = {
   imei: string;
@@ -290,4 +250,10 @@ type ZaloCtor = new (options?: { logging?: boolean; selfListen?: boolean }) => {
   ): Promise<API>;
 };
 
-export const Zalo = ZaloRuntime as unknown as ZaloCtor;
+export async function createZalo(
+  options?: ConstructorParameters<ZaloCtor>[0],
+): Promise<InstanceType<ZaloCtor>> {
+  const zcaJs = await loadZcaJsRuntime();
+  const Zalo = zcaJs.Zalo as ZaloCtor;
+  return new Zalo(options);
+}

package/src/zca-constants.ts

@@ -0,0 +1,55 @@
+export const ThreadType = {
+  User: 0,
+  Group: 1,
+} as const;
+
+export const LoginQRCallbackEventType = {
+  QRCodeGenerated: 0,
+  QRCodeExpired: 1,
+  QRCodeScanned: 2,
+  QRCodeDeclined: 3,
+  GotLoginInfo: 4,
+} as const;
+
+export const Reactions = {
+  HEART: "/-heart",
+  LIKE: "/-strong",
+  HAHA: ":>",
+  WOW: ":o",
+  CRY: ":-((",
+  ANGRY: ":-h",
+  NONE: "",
+} as const;
+
+// Mirror zca-js sendMessage style constants locally because the package root
+// typing surface does not consistently expose TextStyle/Style to tsgo.
+export const TextStyle = {
+  Bold: "b",
+  Italic: "i",
+  Underline: "u",
+  StrikeThrough: "s",
+  Red: "c_db342e",
+  Orange: "c_f27806",
+  Yellow: "c_f7b503",
+  Green: "c_15a85f",
+  Small: "f_13",
+  Big: "f_18",
+  UnorderedList: "lst_1",
+  OrderedList: "lst_2",
+  Indent: "ind_$",
+} as const;
+
+type TextStyleValue = (typeof TextStyle)[keyof typeof TextStyle];
+
+export type Style =
+  | {
+      start: number;
+      len: number;
+      st: Exclude<TextStyleValue, typeof TextStyle.Indent>;
+    }
+  | {
+      start: number;
+      len: number;
+      st: typeof TextStyle.Indent;
+      indentSize?: number;
+    };

package/test-api.ts

@@ -0,0 +1,21 @@
+export { sendMessageZalouser } from "./src/send.js";
+export { parseZalouserOutboundTarget } from "./src/session-route.js";
+export {
+  checkZcaAuthenticated,
+  getZcaUserInfo,
+  listZalouserAccountIds,
+  resolveDefaultZalouserAccountId,
+  resolveZalouserAccountSync,
+} from "./src/accounts.js";
+export {
+  checkZaloAuthenticated,
+  getZaloUserInfo,
+  listZaloFriendsMatching,
+  listZaloGroupMembers,
+  listZaloGroupsMatching,
+  logoutZaloProfile,
+  resolveZaloAllowFromEntries,
+  resolveZaloGroupsByEntries,
+  startZaloQrLogin,
+  waitForZaloQrLogin,
+} from "./src/zalo-js.js";

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}

package/CHANGELOG.md

@@ -1,107 +0,0 @@
-# Changelog
-
-## 2026.3.13
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.12
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.11
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.10
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.9
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.8-beta.1
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.8
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.7
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.3
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.2
-
-### Changes
-
-- Rebuilt the plugin to use native `zca-js` integration inside OpenClaw (no external `zca` CLI runtime dependency).
-
-### Breaking
-
-- **BREAKING:** Removed the old external CLI-based backend (`zca`/`openzca`/`zca-cli`) from runtime flow. Existing setups that depended on external CLI binaries should re-login with `openclaw channels login --channel zalouser` after upgrading.
-
-## 2026.3.1
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.2.26
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.2.25
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.2.24
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.2.22
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.1.17-1
-
-- Initial version with full channel plugin support
-- QR code login via zca-cli
-- Multi-account support
-- Agent tool for sending messages
-- Group and DM policy support
-- ChannelDock for lightweight shared metadata
-- Zod-based config schema validation
-- Setup adapter for programmatic configuration
-- Dedicated probe and status issues modules

package/src/onboarding.ts

@@ -1,340 +0,0 @@
-import type {
-  ChannelOnboardingAdapter,
-  ChannelOnboardingDmPolicy,
-  OpenClawConfig,
-  WizardPrompter,
-} from "openclaw/plugin-sdk/zalouser";
-import {
-  DEFAULT_ACCOUNT_ID,
-  formatResolvedUnresolvedNote,
-  mergeAllowFromEntries,
-  normalizeAccountId,
-  patchScopedAccountConfig,
-  promptChannelAccessConfig,
-  resolveAccountIdForConfigure,
-  setTopLevelChannelDmPolicyWithAllowFrom,
-} from "openclaw/plugin-sdk/zalouser";
-import {
-  listZalouserAccountIds,
-  resolveDefaultZalouserAccountId,
-  resolveZalouserAccountSync,
-  checkZcaAuthenticated,
-} from "./accounts.js";
-import { writeQrDataUrlToTempFile } from "./qr-temp-file.js";
-import {
-  logoutZaloProfile,
-  resolveZaloAllowFromEntries,
-  resolveZaloGroupsByEntries,
-  startZaloQrLogin,
-  waitForZaloQrLogin,
-} from "./zalo-js.js";
-
-const channel = "zalouser" as const;
-
-function setZalouserAccountScopedConfig(
-  cfg: OpenClawConfig,
-  accountId: string,
-  defaultPatch: Record<string, unknown>,
-  accountPatch: Record<string, unknown> = defaultPatch,
-): OpenClawConfig {
-  return patchScopedAccountConfig({
-    cfg,
-    channelKey: channel,
-    accountId,
-    patch: defaultPatch,
-    accountPatch,
-  }) as OpenClawConfig;
-}
-
-function setZalouserDmPolicy(
-  cfg: OpenClawConfig,
-  dmPolicy: "pairing" | "allowlist" | "open" | "disabled",
-): OpenClawConfig {
-  return setTopLevelChannelDmPolicyWithAllowFrom({
-    cfg,
-    channel: "zalouser",
-    dmPolicy,
-  }) as OpenClawConfig;
-}
-
-async function noteZalouserHelp(prompter: WizardPrompter): Promise<void> {
-  await prompter.note(
-    [
-      "Zalo Personal Account login via QR code.",
-      "",
-      "This plugin uses zca-js directly (no external CLI dependency).",
-      "",
-      "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);
-
-  while (true) {
-    const entry = await prompter.text({
-      message: "Zalouser allowFrom (name 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 resolvedEntries = await resolveZaloAllowFromEntries({
-      profile: resolved.profile,
-      entries: parts,
-    });
-
-    const unresolved = resolvedEntries.filter((item) => !item.resolved).map((item) => item.input);
-    if (unresolved.length > 0) {
-      await prompter.note(
-        `Could not resolve: ${unresolved.join(", ")}. Use numeric user ids or exact friend names.`,
-        "Zalo Personal allowlist",
-      );
-      continue;
-    }
-
-    const resolvedIds = resolvedEntries
-      .filter((item) => item.resolved && item.id)
-      .map((item) => item.id as string);
-    const unique = mergeAllowFromEntries(existingAllowFrom, resolvedIds);
-
-    const notes = resolvedEntries
-      .filter((item) => item.note)
-      .map((item) => `${item.input} -> ${item.id} (${item.note})`);
-    if (notes.length > 0) {
-      await prompter.note(notes.join("\n"), "Zalo Personal allowlist");
-    }
-
-    return setZalouserAccountScopedConfig(cfg, accountId, {
-      dmPolicy: "allowlist",
-      allowFrom: unique,
-    });
-  }
-}
-
-function setZalouserGroupPolicy(
-  cfg: OpenClawConfig,
-  accountId: string,
-  groupPolicy: "open" | "allowlist" | "disabled",
-): OpenClawConfig {
-  return setZalouserAccountScopedConfig(cfg, accountId, {
-    groupPolicy,
-  });
-}
-
-function setZalouserGroupAllowlist(
-  cfg: OpenClawConfig,
-  accountId: string,
-  groupKeys: string[],
-): OpenClawConfig {
-  const groups = Object.fromEntries(groupKeys.map((key) => [key, { allow: true }]));
-  return setZalouserAccountScopedConfig(cfg, accountId, {
-    groups,
-  });
-}
-
-const dmPolicy: ChannelOnboardingDmPolicy = {
-  label: "Zalo Personal",
-  channel,
-  policyKey: "channels.zalouser.dmPolicy",
-  allowFromKey: "channels.zalouser.allowFrom",
-  getCurrent: (cfg) => (cfg.channels?.zalouser?.dmPolicy ?? "pairing") as "pairing",
-  setPolicy: (cfg, policy) => setZalouserDmPolicy(cfg, policy),
-  promptAllowFrom: async ({ cfg, prompter, accountId }) => {
-    const id =
-      accountId && normalizeAccountId(accountId)
-        ? (normalizeAccountId(accountId) ?? DEFAULT_ACCOUNT_ID)
-        : resolveDefaultZalouserAccountId(cfg);
-    return promptZalouserAllowFrom({
-      cfg,
-      prompter,
-      accountId: id,
-    });
-  },
-};
-
-export const zalouserOnboardingAdapter: ChannelOnboardingAdapter = {
-  channel,
-  dmPolicy,
-  getStatus: async ({ cfg }) => {
-    const ids = listZalouserAccountIds(cfg);
-    let configured = false;
-    for (const accountId of ids) {
-      const account = resolveZalouserAccountSync({ cfg, 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,
-  }) => {
-    const defaultAccountId = resolveDefaultZalouserAccountId(cfg);
-    const accountId = await resolveAccountIdForConfigure({
-      cfg,
-      prompter,
-      label: "Zalo Personal",
-      accountOverride: accountOverrides.zalouser,
-      shouldPromptAccountIds,
-      listAccountIds: listZalouserAccountIds,
-      defaultAccountId,
-    });
-
-    let next = cfg;
-    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) {
-        const start = await startZaloQrLogin({ profile: account.profile, timeoutMs: 35_000 });
-        if (start.qrDataUrl) {
-          const qrPath = await writeQrDataUrlToTempFile(start.qrDataUrl, account.profile);
-          await prompter.note(
-            [
-              start.message,
-              qrPath
-                ? `QR image saved to: ${qrPath}`
-                : "Could not write QR image file; use gateway web login UI instead.",
-              "Scan + approve on phone, then continue.",
-            ].join("\n"),
-            "QR Login",
-          );
-          const scanned = await prompter.confirm({
-            message: "Did you scan and approve the QR on your phone?",
-            initialValue: true,
-          });
-          if (scanned) {
-            const waited = await waitForZaloQrLogin({
-              profile: account.profile,
-              timeoutMs: 120_000,
-            });
-            await prompter.note(waited.message, waited.connected ? "Success" : "Login pending");
-          }
-        } else {
-          await prompter.note(start.message, "Login pending");
-        }
-      }
-    } else {
-      const keepSession = await prompter.confirm({
-        message: "Zalo Personal already logged in. Keep session?",
-        initialValue: true,
-      });
-      if (!keepSession) {
-        await logoutZaloProfile(account.profile);
-        const start = await startZaloQrLogin({
-          profile: account.profile,
-          force: true,
-          timeoutMs: 35_000,
-        });
-        if (start.qrDataUrl) {
-          const qrPath = await writeQrDataUrlToTempFile(start.qrDataUrl, account.profile);
-          await prompter.note(
-            [start.message, qrPath ? `QR image saved to: ${qrPath}` : undefined]
-              .filter(Boolean)
-              .join("\n"),
-            "QR Login",
-          );
-          const waited = await waitForZaloQrLogin({ profile: account.profile, timeoutMs: 120_000 });
-          await prompter.note(waited.message, waited.connected ? "Success" : "Login pending");
-        }
-      }
-    }
-
-    next = setZalouserAccountScopedConfig(
-      next,
-      accountId,
-      { profile: account.profile !== "default" ? account.profile : undefined },
-      { profile: account.profile, enabled: true },
-    );
-
-    if (forceAllowFrom) {
-      next = await promptZalouserAllowFrom({
-        cfg: next,
-        prompter,
-        accountId,
-      });
-    }
-
-    const updatedAccount = resolveZalouserAccountSync({ cfg: next, accountId });
-    const accessConfig = await promptChannelAccessConfig({
-      prompter,
-      label: "Zalo groups",
-      currentPolicy: updatedAccount.config.groupPolicy ?? "allowlist",
-      currentEntries: Object.keys(updatedAccount.config.groups ?? {}),
-      placeholder: "Family, Work, 123456789",
-      updatePrompt: Boolean(updatedAccount.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 resolveZaloGroupsByEntries({
-              profile: updatedAccount.profile,
-              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)];
-            const resolution = formatResolvedUnresolvedNote({
-              resolved: resolvedIds,
-              unresolved,
-            });
-            if (resolution) {
-              await prompter.note(resolution, "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 };
-  },
-};