@gakr-gakr/zalouser 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @gakr-gakr/zalouser
+
+AutoBot 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 with setup wizard + QR login
+- In-process listener/sender via `zca-js` (no external CLI)
+- Multi-account support
+- Agent tool integration (`zalouser`)
+- DM/group policy support
+
+## Prerequisites
+
+- AutoBot Gateway
+- Zalo mobile app (for QR login)
+
+No external `zca`, `openzca`, or `zca-cli` binary is required.
+
+## Install
+
+### Option A: npm
+
+```bash
+autobot plugins install @gakr-gakr/zalouser
+```
+
+### Option B: local source checkout
+
+```bash
+PLUGIN_SRC=./path/to/local/zalouser-plugin
+autobot plugins install "$PLUGIN_SRC"
+cd "$PLUGIN_SRC" && pnpm install
+```
+
+Restart the Gateway after install.
+
+## Quick start
+
+### Login (QR)
+
+```bash
+autobot channels login --channel zalouser
+```
+
+Scan the QR code with the Zalo app on your phone.
+
+### Enable channel
+
+```yaml
+channels:
+  zalouser:
+    enabled: true
+    dmPolicy: pairing # pairing | allowlist | open | disabled
+```
+
+### Send a message
+
+```bash
+autobot message send --channel zalouser --target <threadId> --message "Hello from AutoBot"
+```
+
+## Configuration
+
+Basic:
+
+```yaml
+channels:
+  zalouser:
+    enabled: true
+    dmPolicy: pairing
+```
+
+Multi-account:
+
+```yaml
+channels:
+  zalouser:
+    enabled: true
+    defaultAccount: default
+    accounts:
+      default:
+        enabled: true
+        profile: default
+      work:
+        enabled: true
+        profile: work
+```
+
+## Useful commands
+
+```bash
+autobot channels login --channel zalouser
+autobot channels login --channel zalouser --account work
+autobot channels status --probe
+autobot channels logout --channel zalouser
+
+autobot directory self --channel zalouser
+autobot directory peers list --channel zalouser --query "name"
+autobot directory groups list --channel zalouser --query "work"
+autobot directory groups members --channel zalouser --group-id <id>
+```
+
+## Agent tool
+
+The extension registers a `zalouser` tool for AI agents.
+
+Available actions: `send`, `image`, `link`, `friends`, `groups`, `me`, `status`
+
+## Troubleshooting
+
+- Login not persisted: `autobot channels logout --channel zalouser && autobot channels login --channel zalouser`
+- Probe status: `autobot channels status --probe`
+- Name resolution issues (allowlist/groups): use numeric IDs or exact Zalo names
+
+## Credits
+
+Built on [zca-js](https://github.com/RFS-ADRENO/zca-js).

package/api.ts

@@ -0,0 +1,9 @@
+export { zalouserPlugin } from "./src/channel.js";
+export { zalouserSetupPlugin } from "./src/channel.setup.js";
+export { createZalouserTool } from "./src/tool.js";
+export { createZalouserSetupWizardProxy, zalouserSetupAdapter } from "./src/setup-core.js";
+export { zalouserSetupWizard } from "./src/setup-surface.js";
+export {
+  collectZalouserSecurityAuditFindings,
+  isZalouserMutableGroupEntry,
+} from "./src/security-audit.js";

package/autobot.plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "zalouser",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["zalouser"],
+  "contracts": {
+    "tools": ["zalouser"]
+  },
+  "channelEnvVars": {
+    "zalouser": ["ZALOUSER_PROFILE", "ZCA_PROFILE"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/channel-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled channel entry imports narrow so bootstrap/discovery paths do
+// not drag setup-only or tool runtime surfaces into lightweight plugin loads.
+export { zalouserPlugin } from "./src/channel.js";

package/contract-api.ts

@@ -0,0 +1,2 @@
+export { collectZalouserSecurityAuditFindings } from "./src/security-audit.js";
+export { legacyConfigRules, normalizeCompatibilityConfig } from "./src/doctor-contract.js";

package/doctor-contract-api.ts

@@ -0,0 +1 @@
+export { normalizeCompatibilityConfig, legacyConfigRules } from "./src/doctor-contract.js";

package/index.ts

@@ -0,0 +1,34 @@
+import {
+  type AnyAgentTool,
+  defineBundledChannelEntry,
+  loadBundledEntryExportSync,
+} from "autobot/plugin-sdk/channel-entry-contract";
+
+function createZalouserTool(context?: unknown): AnyAgentTool {
+  const createTool = loadBundledEntryExportSync<(context?: unknown) => AnyAgentTool>(
+    import.meta.url,
+    {
+      specifier: "./api.js",
+      exportName: "createZalouserTool",
+    },
+  );
+  return createTool(context);
+}
+
+export default defineBundledChannelEntry({
+  id: "zalouser",
+  name: "Zalo Personal",
+  description: "Zalo personal account messaging via native zca-js integration",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "zalouserPlugin",
+  },
+  runtime: {
+    specifier: "./runtime-api.js",
+    exportName: "setZalouserRuntime",
+  },
+  registerFull(api) {
+    api.registerTool((ctx) => createZalouserTool(ctx), { name: "zalouser" });
+  },
+});

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@gakr-gakr/zalouser",
+  "version": "0.1.0",
+  "description": "AutoBot Zalo Personal Account plugin via native zca-js integration",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/autobot/autobot"
+  },
+  "type": "module",
+  "dependencies": {
+    "typebox": "1.1.38",
+    "zca-js": "2.1.2",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@gakr-gakr/plugin-sdk": "workspace:*",
+    "@gakr-gakr/autobot": "workspace:*",
+    "autobot": "workspace:@gakr-gakr/autobot@*"
+  },
+  "peerDependencies": {
+    "@gakr-gakr/autobot": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@gakr-gakr/autobot": {
+      "optional": true
+    }
+  },
+  "autobot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "zalouser",
+      "label": "Zalo Personal",
+      "selectionLabel": "Zalo (Personal Account)",
+      "docsPath": "/channels/zalouser",
+      "docsLabel": "zalouser",
+      "blurb": "Zalo personal account via QR code login.",
+      "aliases": [
+        "zlu"
+      ],
+      "order": 85,
+      "quickstartAllowFrom": false,
+      "doctorCapabilities": {
+        "dmAllowFromMode": "topOnly",
+        "groupModel": "hybrid",
+        "groupAllowFromFallbackToAllowFrom": false,
+        "warnOnEmptyGroupSenderAllowlist": false
+      }
+    },
+    "install": {
+      "npmSpec": "@gakr-gakr/zalouser",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.19"
+    },
+    "build": {
+      "autobotVersion": "2026.5.19"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,62 @@
+export {
+  collectZalouserSecurityAuditFindings,
+  createZalouserSetupWizardProxy,
+  createZalouserTool,
+  isZalouserMutableGroupEntry,
+  zalouserPlugin,
+  zalouserSetupAdapter,
+  zalouserSetupPlugin,
+  zalouserSetupWizard,
+} from "./api.js";
+export { setZalouserRuntime } from "./src/runtime.js";
+export type { ReplyPayload } from "autobot/plugin-sdk/reply-runtime";
+export type {
+  BaseProbeResult,
+  ChannelAccountSnapshot,
+  ChannelDirectoryEntry,
+  ChannelGroupContext,
+  ChannelMessageActionAdapter,
+  ChannelStatusIssue,
+} from "autobot/plugin-sdk/channel-contract";
+export type {
+  AutoBotConfig,
+  GroupToolPolicyConfig,
+  MarkdownTableMode,
+} from "autobot/plugin-sdk/config-contracts";
+export type {
+  PluginRuntime,
+  AnyAgentTool,
+  ChannelPlugin,
+  AutoBotPluginToolContext,
+} from "autobot/plugin-sdk/core";
+export type { RuntimeEnv } from "autobot/plugin-sdk/runtime";
+export {
+  DEFAULT_ACCOUNT_ID,
+  buildChannelConfigSchema,
+  normalizeAccountId,
+} from "autobot/plugin-sdk/core";
+export { chunkTextForOutbound } from "autobot/plugin-sdk/text-chunking";
+export { isDangerousNameMatchingEnabled } from "autobot/plugin-sdk/dangerous-name-runtime";
+export {
+  resolveDefaultGroupPolicy,
+  resolveOpenProviderRuntimeGroupPolicy,
+  warnMissingProviderGroupPolicyFallbackOnce,
+} from "autobot/plugin-sdk/runtime-group-policy";
+export {
+  mergeAllowlist,
+  summarizeMapping,
+  formatAllowFromLowercase,
+} from "autobot/plugin-sdk/allow-from";
+export { resolveInboundMentionDecision } from "autobot/plugin-sdk/channel-inbound";
+export { createChannelPairingController } from "autobot/plugin-sdk/channel-pairing";
+export { createChannelMessageReplyPipeline } from "autobot/plugin-sdk/channel-message";
+export { buildBaseAccountStatusSnapshot } from "autobot/plugin-sdk/status-helpers";
+export { loadOutboundMediaFromUrl } from "autobot/plugin-sdk/outbound-media";
+export {
+  deliverTextOrMediaReply,
+  isNumericTargetId,
+  resolveSendableOutboundReplyParts,
+  sendPayloadWithChunkedTextAndMedia,
+  type OutboundReplyPayload,
+} from "autobot/plugin-sdk/reply-payload";
+export { resolvePreferredAutoBotTmpDir } from "autobot/plugin-sdk/temp-path";

package/secret-contract-api.ts

@@ -0,0 +1,4 @@
+// Zalo User does not expose secret-contract surfaces.
+export const secretTargetRegistryEntries: readonly [] = [];
+
+export function collectRuntimeConfigAssignments(): void {}

package/setup-entry.ts

@@ -0,0 +1,9 @@
+import { defineBundledChannelSetupEntry } from "autobot/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./setup-plugin-api.js",
+    exportName: "zalouserSetupPlugin",
+  },
+});

package/setup-plugin-api.ts

@@ -0,0 +1,2 @@
+// Keep setup-entry imports narrow so setup loads do not pull tool surfaces.
+export { zalouserSetupPlugin } from "./src/channel.setup.js";

package/src/accounts.runtime.ts

@@ -0,0 +1 @@
+export { checkZaloAuthenticated, getZaloUserInfo } from "./zalo-js.js";

package/src/accounts.test-mocks.ts

@@ -0,0 +1,14 @@
+import { vi } from "vitest";
+import { createDefaultResolvedZalouserAccount } from "./test-helpers.js";
+
+vi.mock("./accounts.js", () => {
+  return {
+    listZalouserAccountIds: () => ["default"],
+    resolveDefaultZalouserAccountId: () => "default",
+    resolveZalouserAccountSync: () => createDefaultResolvedZalouserAccount(),
+    resolveZalouserAccount: async () => createDefaultResolvedZalouserAccount(),
+    listEnabledZalouserAccounts: async () => [createDefaultResolvedZalouserAccount()],
+    getZcaUserInfo: async () => null,
+    checkZcaAuthenticated: async () => false,
+  };
+});

package/src/accounts.ts

@@ -0,0 +1,136 @@
+import {
+  createAccountListHelpers,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  resolveMergedAccountConfig,
+} from "autobot/plugin-sdk/account-resolution";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import type { ResolvedZalouserAccount, ZalouserAccountConfig, ZalouserConfig } from "./types.js";
+
+let zalouserAccountsRuntimePromise: Promise<typeof import("./accounts.runtime.js")> | undefined;
+
+async function loadZalouserAccountsRuntime() {
+  zalouserAccountsRuntimePromise ??= import("./accounts.runtime.js");
+  return await zalouserAccountsRuntimePromise;
+}
+
+const {
+  listAccountIds: listZalouserAccountIds,
+  resolveDefaultAccountId: resolveDefaultZalouserAccountId,
+} = createAccountListHelpers("zalouser", {
+  implicitDefaultAccount: {
+    channelKeys: ["profile"],
+    envVars: ["ZALOUSER_PROFILE", "ZCA_PROFILE"],
+  },
+});
+export { listZalouserAccountIds, resolveDefaultZalouserAccountId };
+
+function mergeZalouserAccountConfig(cfg: AutoBotConfig, accountId: string): ZalouserAccountConfig {
+  const merged = resolveMergedAccountConfig<ZalouserAccountConfig>({
+    channelConfig: cfg.channels?.zalouser as ZalouserAccountConfig | undefined,
+    accounts: (cfg.channels?.zalouser as ZalouserConfig | undefined)?.accounts as
+      | Record<string, Partial<ZalouserAccountConfig>>
+      | undefined,
+    accountId,
+    omitKeys: ["defaultAccount"],
+  });
+  return {
+    ...merged,
+    // Match Telegram's safe default: groups stay allowlisted unless explicitly opened.
+    groupPolicy: merged.groupPolicy ?? "allowlist",
+  };
+}
+
+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();
+  }
+  if (accountId !== DEFAULT_ACCOUNT_ID) {
+    return accountId;
+  }
+  return "default";
+}
+
+function resolveZalouserAccountBase(params: { cfg: AutoBotConfig; accountId?: string | null }) {
+  const accountId = normalizeAccountId(
+    params.accountId ?? resolveDefaultZalouserAccountId(params.cfg),
+  );
+  const baseEnabled =
+    (params.cfg.channels?.zalouser as ZalouserConfig | undefined)?.enabled !== false;
+  const merged = mergeZalouserAccountConfig(params.cfg, accountId);
+  return {
+    accountId,
+    enabled: baseEnabled && merged.enabled !== false,
+    merged,
+    profile: resolveProfile(merged, accountId),
+  };
+}
+
+export async function resolveZalouserAccount(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): Promise<ResolvedZalouserAccount> {
+  const { accountId, enabled, merged, profile } = resolveZalouserAccountBase(params);
+  const authenticated = await (await loadZalouserAccountsRuntime()).checkZaloAuthenticated(profile);
+
+  return {
+    accountId,
+    name: normalizeOptionalString(merged.name),
+    enabled,
+    profile,
+    authenticated,
+    config: merged,
+  };
+}
+
+export function resolveZalouserAccountSync(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): ResolvedZalouserAccount {
+  const { accountId, enabled, merged, profile } = resolveZalouserAccountBase(params);
+
+  return {
+    accountId,
+    name: normalizeOptionalString(merged.name),
+    enabled,
+    profile,
+    authenticated: false,
+    config: merged,
+  };
+}
+
+export async function listEnabledZalouserAccounts(
+  cfg: AutoBotConfig,
+): Promise<ResolvedZalouserAccount[]> {
+  const ids = listZalouserAccountIds(cfg);
+  const accounts = await Promise.all(
+    ids.map((accountId) => resolveZalouserAccount({ cfg, accountId })),
+  );
+  return accounts.filter((account) => account.enabled);
+}
+
+export async function getZcaUserInfo(
+  profile: string,
+): Promise<{ userId?: string; displayName?: string } | null> {
+  const info = await (await loadZalouserAccountsRuntime()).getZaloUserInfo(profile);
+  if (!info) {
+    return null;
+  }
+  return {
+    userId: info.userId,
+    displayName: info.displayName,
+  };
+}
+
+export async function checkZcaAuthenticated(profile: string): Promise<boolean> {
+  return await (await loadZalouserAccountsRuntime()).checkZaloAuthenticated(profile);
+}
+
+export type { ResolvedZalouserAccount } from "./types.js";

package/src/channel-api.ts

@@ -0,0 +1,20 @@
+export { formatAllowFromLowercase } from "autobot/plugin-sdk/allow-from";
+export type {
+  ChannelDirectoryEntry,
+  ChannelGroupContext,
+  ChannelMessageActionAdapter,
+} from "autobot/plugin-sdk/channel-contract";
+export { buildChannelConfigSchema } from "autobot/plugin-sdk/channel-config-schema";
+export type { ChannelPlugin } from "autobot/plugin-sdk/core";
+export {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  type AutoBotConfig,
+} from "autobot/plugin-sdk/core";
+export { isDangerousNameMatchingEnabled } from "autobot/plugin-sdk/dangerous-name-runtime";
+export type { GroupToolPolicyConfig } from "autobot/plugin-sdk/config-contracts";
+export { chunkTextForOutbound } from "autobot/plugin-sdk/text-chunking";
+export {
+  isNumericTargetId,
+  sendPayloadWithChunkedTextAndMedia,
+} from "autobot/plugin-sdk/reply-payload";