@kodelyth/zalouser 2026.5.39 → 2026.5.42

package/README.md

@@ -0,0 +1,120 @@
+# @klaw/zalouser
+
+Klaw 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
+
+- Klaw Gateway
+- Zalo mobile app (for QR login)
+
+No external `zca`, `openzca`, or `zca-cli` binary is required.
+
+## Install
+
+### Option A: npm
+
+```bash
+klaw plugins install @klaw/zalouser
+```
+
+### Option B: local source checkout
+
+```bash
+PLUGIN_SRC=./path/to/local/zalouser-plugin
+klaw plugins install "$PLUGIN_SRC"
+cd "$PLUGIN_SRC" && pnpm install
+```
+
+Restart the Gateway after install.
+
+## Quick start
+
+### Login (QR)
+
+```bash
+klaw 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
+klaw message send --channel zalouser --target <threadId> --message "Hello from Klaw"
+```
+
+## 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
+klaw channels login --channel zalouser
+klaw channels login --channel zalouser --account work
+klaw channels status --probe
+klaw channels logout --channel zalouser
+
+klaw directory self --channel zalouser
+klaw directory peers list --channel zalouser --query "name"
+klaw directory groups list --channel zalouser --query "work"
+klaw 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: `klaw channels logout --channel zalouser && klaw channels login --channel zalouser`
+- Probe status: `klaw 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/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/dist/accounts-DOefD_if.js

@@ -0,0 +1,66 @@
+import { DEFAULT_ACCOUNT_ID, createAccountListHelpers, normalizeAccountId, resolveMergedAccountConfig } from "klaw/plugin-sdk/account-resolution";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+//#region extensions/zalouser/src/accounts.ts
+let zalouserAccountsRuntimePromise;
+async function loadZalouserAccountsRuntime() {
+	zalouserAccountsRuntimePromise ??= import("./accounts.runtime-KT101uuu.js");
+	return await zalouserAccountsRuntimePromise;
+}
+const { listAccountIds: listZalouserAccountIds, resolveDefaultAccountId: resolveDefaultZalouserAccountId } = createAccountListHelpers("zalouser", { implicitDefaultAccount: {
+	channelKeys: ["profile"],
+	envVars: ["ZALOUSER_PROFILE", "ZCA_PROFILE"]
+} });
+function mergeZalouserAccountConfig(cfg, accountId) {
+	const merged = resolveMergedAccountConfig({
+		channelConfig: cfg.channels?.zalouser,
+		accounts: (cfg.channels?.zalouser)?.accounts,
+		accountId,
+		omitKeys: ["defaultAccount"]
+	});
+	return {
+		...merged,
+		groupPolicy: merged.groupPolicy ?? "allowlist"
+	};
+}
+function resolveProfile(config, accountId) {
+	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) {
+	const accountId = normalizeAccountId(params.accountId ?? resolveDefaultZalouserAccountId(params.cfg));
+	const baseEnabled = (params.cfg.channels?.zalouser)?.enabled !== false;
+	const merged = mergeZalouserAccountConfig(params.cfg, accountId);
+	return {
+		accountId,
+		enabled: baseEnabled && merged.enabled !== false,
+		merged,
+		profile: resolveProfile(merged, accountId)
+	};
+}
+function resolveZalouserAccountSync(params) {
+	const { accountId, enabled, merged, profile } = resolveZalouserAccountBase(params);
+	return {
+		accountId,
+		name: normalizeOptionalString(merged.name),
+		enabled,
+		profile,
+		authenticated: false,
+		config: merged
+	};
+}
+async function getZcaUserInfo(profile) {
+	const info = await (await loadZalouserAccountsRuntime()).getZaloUserInfo(profile);
+	if (!info) return null;
+	return {
+		userId: info.userId,
+		displayName: info.displayName
+	};
+}
+async function checkZcaAuthenticated(profile) {
+	return await (await loadZalouserAccountsRuntime()).checkZaloAuthenticated(profile);
+}
+//#endregion
+export { resolveZalouserAccountSync as a, resolveDefaultZalouserAccountId as i, getZcaUserInfo as n, listZalouserAccountIds as r, checkZcaAuthenticated as t };

package/dist/accounts.runtime-KT101uuu.js

@@ -0,0 +1,2 @@
+import { n as getZaloUserInfo, t as checkZaloAuthenticated } from "./zalo-js-B80cRyDF.js";
+export { checkZaloAuthenticated, getZaloUserInfo };

package/dist/api-DSWT4Dh_.js

@@ -0,0 +1,133 @@
+import "./setup-surface-Cfj4GQlB.js";
+import "./shared-DjK0e2FC.js";
+import "./channel-pby_3Sur.js";
+import { r as parseZalouserOutboundTarget } from "./session-route-CalHiv1d.js";
+import "./security-audit-D_rftvs-.js";
+import { i as listZaloFriendsMatching, n as getZaloUserInfo, s as listZaloGroupsMatching, t as checkZaloAuthenticated } from "./zalo-js-B80cRyDF.js";
+import "./channel.setup-CqyWwqcQ.js";
+import { i as sendMessageZalouser, n as sendImageZalouser, r as sendLinkZalouser } from "./send-uRjUB8mG.js";
+import { stringEnum } from "klaw/plugin-sdk/channel-actions";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import { Type } from "typebox";
+//#region extensions/zalouser/src/tool.ts
+const ACTIONS = [
+	"send",
+	"image",
+	"link",
+	"friends",
+	"groups",
+	"me",
+	"status"
+];
+const ZalouserToolSchema = Type.Object({
+	action: stringEnum(ACTIONS, { description: `Action to perform: ${ACTIONS.join(", ")}` }),
+	threadId: Type.Optional(Type.String({ description: "Thread ID for messaging" })),
+	message: Type.Optional(Type.String({ description: "Message text" })),
+	isGroup: Type.Optional(Type.Boolean({ description: "Is group chat" })),
+	profile: Type.Optional(Type.String({ description: "Profile name" })),
+	query: Type.Optional(Type.String({ description: "Search query" })),
+	url: Type.Optional(Type.String({ description: "URL for media/link" }))
+}, { additionalProperties: false });
+function json(payload) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(payload, null, 2)
+		}],
+		details: payload
+	};
+}
+function resolveAmbientZalouserTarget(context) {
+	const deliveryContext = context?.deliveryContext;
+	const rawTarget = deliveryContext?.to;
+	if ((deliveryContext?.channel === void 0 || deliveryContext.channel === "zalouser") && typeof rawTarget === "string" && rawTarget.trim()) try {
+		return parseZalouserOutboundTarget(rawTarget);
+	} catch {}
+	if (deliveryContext?.channel && deliveryContext.channel !== "zalouser") return {};
+	const ambientThreadId = deliveryContext?.threadId;
+	if (typeof ambientThreadId === "string" && ambientThreadId.trim()) return { threadId: ambientThreadId.trim() };
+	if (typeof ambientThreadId === "number" && Number.isFinite(ambientThreadId)) return { threadId: String(ambientThreadId) };
+	return {};
+}
+function resolveZalouserSendTarget(params, context) {
+	const explicitThreadId = typeof params.threadId === "string" ? params.threadId.trim() : "";
+	const ambientTarget = resolveAmbientZalouserTarget(context);
+	return {
+		threadId: explicitThreadId || ambientTarget.threadId,
+		isGroup: typeof params.isGroup === "boolean" ? params.isGroup : ambientTarget.isGroup
+	};
+}
+async function executeZalouserTool(_toolCallId, params, _signal, _onUpdate, context) {
+	try {
+		switch (params.action) {
+			case "send": {
+				const target = resolveZalouserSendTarget(params, context);
+				if (!target.threadId || !params.message) throw new Error("threadId and message required for send action");
+				const result = await sendMessageZalouser(target.threadId, params.message, {
+					profile: params.profile,
+					isGroup: target.isGroup
+				});
+				if (!result.ok) throw new Error(result.error || "Failed to send message");
+				return json({
+					success: true,
+					messageId: result.messageId
+				});
+			}
+			case "image": {
+				const target = resolveZalouserSendTarget(params, context);
+				if (!target.threadId) throw new Error("threadId required for image action");
+				if (!params.url) throw new Error("url required for image action");
+				const result = await sendImageZalouser(target.threadId, params.url, {
+					profile: params.profile,
+					caption: params.message,
+					isGroup: target.isGroup
+				});
+				if (!result.ok) throw new Error(result.error || "Failed to send image");
+				return json({
+					success: true,
+					messageId: result.messageId
+				});
+			}
+			case "link": {
+				const target = resolveZalouserSendTarget(params, context);
+				if (!target.threadId || !params.url) throw new Error("threadId and url required for link action");
+				const result = await sendLinkZalouser(target.threadId, params.url, {
+					profile: params.profile,
+					caption: params.message,
+					isGroup: target.isGroup
+				});
+				if (!result.ok) throw new Error(result.error || "Failed to send link");
+				return json({
+					success: true,
+					messageId: result.messageId
+				});
+			}
+			case "friends": return json(await listZaloFriendsMatching(params.profile, params.query));
+			case "groups": return json(await listZaloGroupsMatching(params.profile, params.query));
+			case "me": return json(await getZaloUserInfo(params.profile) ?? { error: "Not authenticated" });
+			case "status": {
+				const authenticated = await checkZaloAuthenticated(params.profile);
+				return json({
+					authenticated,
+					output: authenticated ? "authenticated" : "not authenticated"
+				});
+			}
+			default:
+				params.action;
+				throw new Error(`Unknown action: ${String(params.action)}. Valid actions: send, image, link, friends, groups, me, status`);
+		}
+	} catch (err) {
+		return json({ error: formatErrorMessage(err) });
+	}
+}
+function createZalouserTool(context) {
+	return {
+		name: "zalouser",
+		label: "Zalo Personal",
+		description: "Send messages and access data via Zalo personal account. Actions: send (text message), image (send image URL), link (send link), friends (list/search friends), groups (list groups), me (profile info), status (auth check).",
+		parameters: ZalouserToolSchema,
+		execute: async (toolCallId, params, signal, onUpdate) => await executeZalouserTool(toolCallId, params, signal, onUpdate, context)
+	};
+}
+//#endregion
+export { createZalouserTool as t };

package/dist/api.js

@@ -0,0 +1,7 @@
+import { n as zalouserSetupWizard } from "./setup-surface-Cfj4GQlB.js";
+import { n as createZalouserSetupWizardProxy, r as zalouserSetupAdapter } from "./shared-DjK0e2FC.js";
+import { t as zalouserPlugin } from "./channel-pby_3Sur.js";
+import { n as isZalouserMutableGroupEntry, t as collectZalouserSecurityAuditFindings } from "./security-audit-D_rftvs-.js";
+import { t as zalouserSetupPlugin } from "./channel.setup-CqyWwqcQ.js";
+import { t as createZalouserTool } from "./api-DSWT4Dh_.js";
+export { collectZalouserSecurityAuditFindings, createZalouserSetupWizardProxy, createZalouserTool, isZalouserMutableGroupEntry, zalouserPlugin, zalouserSetupAdapter, zalouserSetupPlugin, zalouserSetupWizard };