@openclaw/zalouser 2026.3.1 → 2026.3.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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

package/README.md

@@ -1,112 +1,78 @@
 # @openclaw/zalouser
 
-OpenClaw extension for Zalo Personal Account messaging via [zca-cli](https://zca-cli.dev).
+OpenClaw extension for Zalo Personal Account messaging via native `zca-js` integration.
 
 > **Warning:** Using Zalo automation may result in account suspension or ban. Use at your own risk. This is an unofficial integration.
 
 ## Features
 
-- **Channel Plugin Integration**: Appears in onboarding wizard with QR login
-- **Gateway Integration**: Real-time message listening via the gateway
-- **Multi-Account Support**: Manage multiple Zalo personal accounts
-- **CLI Commands**: Full command-line interface for messaging
-- **Agent Tool**: AI agent integration for automated messaging
+- Channel plugin integration with onboarding + QR login
+- In-process listener/sender via `zca-js` (no external CLI)
+- Multi-account support
+- Agent tool integration (`zalouser`)
+- DM/group policy support
 
 ## Prerequisites
 
-Install `zca` CLI and ensure it's in your PATH:
+- OpenClaw Gateway
+- Zalo mobile app (for QR login)
 
-**macOS / Linux:**
+No external `zca`, `openzca`, or `zca-cli` binary is required.
 
-```bash
-curl -fsSL https://get.zca-cli.dev/install.sh | bash
-
-# Or with custom install directory
-ZCA_INSTALL_DIR=~/.local/bin curl -fsSL https://get.zca-cli.dev/install.sh | bash
-
-# Install specific version
-curl -fsSL https://get.zca-cli.dev/install.sh | bash -s v1.0.0
-
-# Uninstall
-curl -fsSL https://get.zca-cli.dev/install.sh | bash -s uninstall
-```
-
-**Windows (PowerShell):**
-
-```powershell
-irm https://get.zca-cli.dev/install.ps1 | iex
+## Install
 
-# Or with custom install directory
-$env:ZCA_INSTALL_DIR = "C:\Tools\zca"; irm https://get.zca-cli.dev/install.ps1 | iex
-
-# Install specific version
-iex "& { $(irm https://get.zca-cli.dev/install.ps1) } -Version v1.0.0"
-
-# Uninstall
-iex "& { $(irm https://get.zca-cli.dev/install.ps1) } -Uninstall"
-```
-
-### Manual Download
-
-Download binary directly:
-
-**macOS / Linux:**
+### Option A: npm
 
 ```bash
-curl -fsSL https://get.zca-cli.dev/latest/zca-darwin-arm64 -o zca && chmod +x zca
+openclaw plugins install @openclaw/zalouser
 ```
 
-**Windows (PowerShell):**
+### Option B: local source checkout
 
-```powershell
-Invoke-WebRequest -Uri https://get.zca-cli.dev/latest/zca-windows-x64.exe -OutFile zca.exe
+```bash
+openclaw plugins install ./extensions/zalouser
+cd ./extensions/zalouser && pnpm install
 ```
 
-Available binaries:
+Restart the Gateway after install.
 
-- `zca-darwin-arm64` - macOS Apple Silicon
-- `zca-darwin-x64` - macOS Intel
-- `zca-linux-arm64` - Linux ARM64
-- `zca-linux-x64` - Linux x86_64
-- `zca-windows-x64.exe` - Windows
+## Quick start
 
-See [zca-cli](https://zca-cli.dev) for manual download (binaries for macOS/Linux/Windows) or building from source.
-
-## Quick Start
-
-### Option 1: Onboarding Wizard (Recommended)
+### Login (QR)
 
 ```bash
-openclaw onboard
-# Select "Zalo Personal" from channel list
-# Follow QR code login flow
+openclaw channels login --channel zalouser
 ```
 
-### Option 2: Login (QR, on the Gateway machine)
+Scan the QR code with the Zalo app on your phone.
 
-```bash
-openclaw channels login --channel zalouser
-# Scan QR code with Zalo app
+### Enable channel
+
+```yaml
+channels:
+  zalouser:
+    enabled: true
+    dmPolicy: pairing # pairing | allowlist | open | disabled
 ```
 
-### Send a Message
+### Send a message
 
 ```bash
-openclaw message send --channel zalouser --target <threadId> --message "Hello from OpenClaw!"
+openclaw message send --channel zalouser --target <threadId> --message "Hello from OpenClaw"
 ```
 
 ## Configuration
 
-After onboarding, your config will include:
+Basic:
 
 ```yaml
 channels:
   zalouser:
     enabled: true
-    dmPolicy: pairing # pairing | allowlist | open | disabled
+    dmPolicy: pairing
 ```
 
-For multi-account:
+Multi-account:
 
 ```yaml
 channels:
@@ -122,104 +88,32 @@ channels:
         profile: work
 ```
 
-## Commands
-
-### Authentication
+## Useful commands
 
 ```bash
-openclaw channels login --channel zalouser              # Login via QR
+openclaw channels login --channel zalouser
 openclaw channels login --channel zalouser --account work
 openclaw channels status --probe
 openclaw channels logout --channel zalouser
-```
-
-### Directory (IDs, contacts, groups)
 
-```bash
 openclaw directory self --channel zalouser
 openclaw directory peers list --channel zalouser --query "name"
 openclaw directory groups list --channel zalouser --query "work"
 openclaw directory groups members --channel zalouser --group-id <id>
 ```
 
-### Account Management
-
-```bash
-zca account list      # List all profiles
-zca account current   # Show active profile
-zca account switch <profile>
-zca account remove <profile>
-zca account label <profile> "Work Account"
-```
-
-### Messaging
-
-```bash
-# Text
-openclaw message send --channel zalouser --target <threadId> --message "message"
-
-# Media (URL)
-openclaw message send --channel zalouser --target <threadId> --message "caption" --media-url "https://example.com/img.jpg"
-```
-
-### Listener
-
-The listener runs inside the Gateway when the channel is enabled. For debugging,
-use `openclaw channels logs --channel zalouser` or run `zca listen` directly.
-
-### Data Access
+## Agent tool
 
-```bash
-# Friends
-zca friend list
-zca friend list -j    # JSON output
-zca friend find "name"
-zca friend online
-
-# Groups
-zca group list
-zca group info <groupId>
-zca group members <groupId>
-
-# Profile
-zca me info
-zca me id
-```
-
-## Multi-Account Support
-
-Use `--profile` or `-p` to work with multiple accounts:
-
-```bash
-openclaw channels login --channel zalouser --account work
-openclaw message send --channel zalouser --account work --target <id> --message "Hello"
-ZCA_PROFILE=work zca listen
-```
-
-Profile resolution order: `--profile` flag > `ZCA_PROFILE` env > default
-
-## Agent Tool
-
-The extension registers a `zalouser` tool for AI agents:
-
-```json
-{
-  "action": "send",
-  "threadId": "123456",
-  "message": "Hello from AI!",
-  "isGroup": false,
-  "profile": "default"
-}
-```
+The extension registers a `zalouser` tool for AI agents.
 
 Available actions: `send`, `image`, `link`, `friends`, `groups`, `me`, `status`
 
 ## Troubleshooting
 
-- **Login Issues:** Run `zca auth logout` then `zca auth login`
-- **API Errors:** Try `zca auth cache-refresh` or re-login
-- **File Uploads:** Check size (max 100MB) and path accessibility
+- Login not persisted: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
+- Probe status: `openclaw channels status --probe`
+- Name resolution issues (allowlist/groups): use numeric IDs or exact Zalo names
 
 ## Credits
 
-Built on [zca-cli](https://zca-cli.dev) which uses [zca-js](https://github.com/RFS-ADRENO/zca-js).
+Built on [zca-js](https://github.com/RFS-ADRENO/zca-js).

package/index.ts

@@ -7,14 +7,12 @@ import { ZalouserToolSchema, executeZalouserTool } from "./src/tool.js";
 const plugin = {
   id: "zalouser",
   name: "Zalo Personal",
-  description: "Zalo personal account messaging via zca-cli",
+  description: "Zalo personal account messaging via native zca-js integration",
   configSchema: emptyPluginConfigSchema(),
   register(api: OpenClawPluginApi) {
     setZalouserRuntime(api.runtime);
-    // Register channel plugin (for onboarding & gateway)
     api.registerChannel({ plugin: zalouserPlugin, dock: zalouserDock });
 
-    // Register agent tool
     api.registerTool({
       name: "zalouser",
       label: "Zalo Personal",

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@openclaw/zalouser",
-  "version": "2026.3.1",
-  "description": "OpenClaw Zalo Personal Account plugin via zca-cli",
+  "version": "2026.3.2",
+  "description": "OpenClaw Zalo Personal Account plugin via native zca-js integration",
   "type": "module",
   "dependencies": {
-    "@sinclair/typebox": "0.34.48"
+    "@sinclair/typebox": "0.34.48",
+    "zca-js": "2.1.1"
   },
   "openclaw": {
     "extensions": [

package/src/accounts.test.ts

@@ -0,0 +1,214 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-id";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  getZcaUserInfo,
+  listEnabledZalouserAccounts,
+  listZalouserAccountIds,
+  resolveDefaultZalouserAccountId,
+  resolveZalouserAccount,
+  resolveZalouserAccountSync,
+} from "./accounts.js";
+import { checkZaloAuthenticated, getZaloUserInfo } from "./zalo-js.js";
+
+vi.mock("./zalo-js.js", () => ({
+  checkZaloAuthenticated: vi.fn(),
+  getZaloUserInfo: vi.fn(),
+}));
+
+const mockCheckAuthenticated = vi.mocked(checkZaloAuthenticated);
+const mockGetUserInfo = vi.mocked(getZaloUserInfo);
+
+function asConfig(value: unknown): OpenClawConfig {
+  return value as OpenClawConfig;
+}
+
+describe("zalouser account resolution", () => {
+  beforeEach(() => {
+    mockCheckAuthenticated.mockReset();
+    mockGetUserInfo.mockReset();
+    delete process.env.ZALOUSER_PROFILE;
+    delete process.env.ZCA_PROFILE;
+  });
+
+  it("returns default account id when no accounts are configured", () => {
+    expect(listZalouserAccountIds(asConfig({}))).toEqual([DEFAULT_ACCOUNT_ID]);
+  });
+
+  it("returns sorted configured account ids", () => {
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          accounts: {
+            work: {},
+            personal: {},
+            default: {},
+          },
+        },
+      },
+    });
+
+    expect(listZalouserAccountIds(cfg)).toEqual(["default", "personal", "work"]);
+  });
+
+  it("uses configured defaultAccount when present", () => {
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          defaultAccount: "work",
+          accounts: {
+            default: {},
+            work: {},
+          },
+        },
+      },
+    });
+
+    expect(resolveDefaultZalouserAccountId(cfg)).toBe("work");
+  });
+
+  it("falls back to default account when configured defaultAccount is missing", () => {
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          defaultAccount: "missing",
+          accounts: {
+            default: {},
+            work: {},
+          },
+        },
+      },
+    });
+
+    expect(resolveDefaultZalouserAccountId(cfg)).toBe("default");
+  });
+
+  it("falls back to first sorted configured account when default is absent", () => {
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          accounts: {
+            zzz: {},
+            aaa: {},
+          },
+        },
+      },
+    });
+
+    expect(resolveDefaultZalouserAccountId(cfg)).toBe("aaa");
+  });
+
+  it("resolves sync account by merging base + account config", () => {
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          enabled: true,
+          dmPolicy: "pairing",
+          accounts: {
+            work: {
+              enabled: false,
+              name: "Work",
+              dmPolicy: "allowlist",
+              allowFrom: ["123"],
+            },
+          },
+        },
+      },
+    });
+
+    const resolved = resolveZalouserAccountSync({ cfg, accountId: "work" });
+    expect(resolved.accountId).toBe("work");
+    expect(resolved.enabled).toBe(false);
+    expect(resolved.name).toBe("Work");
+    expect(resolved.config.dmPolicy).toBe("allowlist");
+    expect(resolved.config.allowFrom).toEqual(["123"]);
+  });
+
+  it("resolves profile precedence correctly", () => {
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          accounts: {
+            work: {},
+          },
+        },
+      },
+    });
+
+    process.env.ZALOUSER_PROFILE = "zalo-env";
+    expect(resolveZalouserAccountSync({ cfg, accountId: "work" }).profile).toBe("zalo-env");
+
+    delete process.env.ZALOUSER_PROFILE;
+    process.env.ZCA_PROFILE = "zca-env";
+    expect(resolveZalouserAccountSync({ cfg, accountId: "work" }).profile).toBe("zca-env");
+
+    delete process.env.ZCA_PROFILE;
+    expect(resolveZalouserAccountSync({ cfg, accountId: "work" }).profile).toBe("work");
+  });
+
+  it("uses explicit profile from config over env fallback", () => {
+    process.env.ZALOUSER_PROFILE = "env-profile";
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          accounts: {
+            work: {
+              profile: "explicit-profile",
+            },
+          },
+        },
+      },
+    });
+
+    expect(resolveZalouserAccountSync({ cfg, accountId: "work" }).profile).toBe("explicit-profile");
+  });
+
+  it("checks authentication during async account resolution", async () => {
+    mockCheckAuthenticated.mockResolvedValueOnce(true);
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          accounts: {
+            default: {},
+          },
+        },
+      },
+    });
+
+    const resolved = await resolveZalouserAccount({ cfg, accountId: "default" });
+    expect(mockCheckAuthenticated).toHaveBeenCalledWith("default");
+    expect(resolved.authenticated).toBe(true);
+  });
+
+  it("filters disabled accounts when listing enabled accounts", async () => {
+    mockCheckAuthenticated.mockResolvedValue(true);
+    const cfg = asConfig({
+      channels: {
+        zalouser: {
+          accounts: {
+            default: { enabled: true },
+            work: { enabled: false },
+          },
+        },
+      },
+    });
+
+    const accounts = await listEnabledZalouserAccounts(cfg);
+    expect(accounts.map((account) => account.accountId)).toEqual(["default"]);
+  });
+
+  it("maps account info helper from zalo-js", async () => {
+    mockGetUserInfo.mockResolvedValueOnce({
+      userId: "123",
+      displayName: "Alice",
+      avatar: "https://example.com/avatar.png",
+    });
+    expect(await getZcaUserInfo("default")).toEqual({
+      userId: "123",
+      displayName: "Alice",
+    });
+
+    mockGetUserInfo.mockResolvedValueOnce(null);
+    expect(await getZcaUserInfo("default")).toBeNull();
+  });
+});

package/src/accounts.ts

@@ -5,7 +5,7 @@ import {
   normalizeOptionalAccountId,
 } from "openclaw/plugin-sdk/account-id";
 import type { ResolvedZalouserAccount, ZalouserAccountConfig, ZalouserConfig } from "./types.js";
-import { runZca, parseJsonOutput } from "./zca.js";
+import { checkZaloAuthenticated, getZaloUserInfo } from "./zalo-js.js";
 
 function listConfiguredAccountIds(cfg: OpenClawConfig): string[] {
   const accounts = (cfg.channels?.zalouser as ZalouserConfig | undefined)?.accounts;
@@ -57,10 +57,13 @@ function mergeZalouserAccountConfig(cfg: OpenClawConfig, accountId: string): Zal
   return { ...base, ...account };
 }
 
-function resolveZcaProfile(config: ZalouserAccountConfig, accountId: string): string {
+function resolveProfile(config: ZalouserAccountConfig, accountId: string): string {
   if (config.profile?.trim()) {
     return config.profile.trim();
   }
+  if (process.env.ZALOUSER_PROFILE?.trim()) {
+    return process.env.ZALOUSER_PROFILE.trim();
+  }
   if (process.env.ZCA_PROFILE?.trim()) {
     return process.env.ZCA_PROFILE.trim();
   }
@@ -70,11 +73,6 @@ function resolveZcaProfile(config: ZalouserAccountConfig, accountId: string): st
   return "default";
 }
 
-export async function checkZcaAuthenticated(profile: string): Promise<boolean> {
-  const result = await runZca(["auth", "status"], { profile, timeout: 5000 });
-  return result.ok;
-}
-
 export async function resolveZalouserAccount(params: {
   cfg: OpenClawConfig;
   accountId?: string | null;
@@ -85,8 +83,8 @@ export async function resolveZalouserAccount(params: {
   const merged = mergeZalouserAccountConfig(params.cfg, accountId);
   const accountEnabled = merged.enabled !== false;
   const enabled = baseEnabled && accountEnabled;
-  const profile = resolveZcaProfile(merged, accountId);
-  const authenticated = await checkZcaAuthenticated(profile);
+  const profile = resolveProfile(merged, accountId);
+  const authenticated = await checkZaloAuthenticated(profile);
 
   return {
     accountId,
@@ -108,14 +106,14 @@ export function resolveZalouserAccountSync(params: {
   const merged = mergeZalouserAccountConfig(params.cfg, accountId);
   const accountEnabled = merged.enabled !== false;
   const enabled = baseEnabled && accountEnabled;
-  const profile = resolveZcaProfile(merged, accountId);
+  const profile = resolveProfile(merged, accountId);
 
   return {
     accountId,
     name: merged.name?.trim() || undefined,
     enabled,
     profile,
-    authenticated: false, // unknown without async check
+    authenticated: false,
     config: merged,
   };
 }
@@ -133,11 +131,16 @@ export async function listEnabledZalouserAccounts(
 export async function getZcaUserInfo(
   profile: string,
 ): Promise<{ userId?: string; displayName?: string } | null> {
-  const result = await runZca(["me", "info", "-j"], { profile, timeout: 10000 });
-  if (!result.ok) {
+  const info = await getZaloUserInfo(profile);
+  if (!info) {
     return null;
   }
-  return parseJsonOutput<{ userId?: string; displayName?: string }>(result.stdout);
+  return {
+    userId: info.userId,
+    displayName: info.displayName,
+  };
 }
 
+export { checkZaloAuthenticated as checkZcaAuthenticated };
+
 export type { ResolvedZalouserAccount } from "./types.js";