@gakr-gakr/zalo 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @gakr-gakr/zalo
+
+Zalo channel plugin for AutoBot (Bot API).
+
+## Install (local checkout)
+
+```bash
+autobot plugins install ./path/to/local/zalo-plugin
+```
+
+## Install (npm)
+
+```bash
+autobot plugins install @gakr-gakr/zalo
+```
+
+Onboarding: select Zalo and confirm the install prompt to fetch the plugin automatically.
+
+## Config
+
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      botToken: "12345689:abc-xyz",
+      dmPolicy: "pairing",
+      proxy: "http://proxy.local:8080",
+    },
+  },
+}
+```
+
+## Webhook mode
+
+```json5
+{
+  channels: {
+    zalo: {
+      webhookUrl: "https://example.com/zalo-webhook",
+      webhookSecret: "your-secret-8-plus-chars",
+      webhookPath: "/zalo-webhook",
+    },
+  },
+}
+```
+
+If `webhookPath` is omitted, the plugin uses the webhook URL path.
+
+Restart the gateway after config changes.

package/api.ts

@@ -0,0 +1,8 @@
+export { zaloPlugin } from "./src/channel.js";
+export {
+  createZaloSetupWizardProxy,
+  resolveZaloRuntimeGroupPolicy,
+  zaloDmPolicy,
+  zaloSetupAdapter,
+  zaloSetupWizard,
+} from "./setup-api.js";

package/autobot.plugin.json

@@ -0,0 +1,15 @@
+{
+  "id": "zalo",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["zalo"],
+  "channelEnvVars": {
+    "zalo": ["ZALO_BOT_TOKEN", "ZALO_WEBHOOK_SECRET"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/channel-plugin-api.ts

@@ -0,0 +1 @@
+export { zaloPlugin } from "./src/channel.js";

package/contract-api.ts

@@ -0,0 +1,5 @@
+export { resolveZaloRuntimeGroupPolicy } from "./src/group-access.js";
+export {
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/index.ts

@@ -0,0 +1,20 @@
+import { defineBundledChannelEntry } from "autobot/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelEntry({
+  id: "zalo",
+  name: "Zalo",
+  description: "Zalo channel plugin",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "zaloPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+  runtime: {
+    specifier: "./runtime-api.js",
+    exportName: "setZaloRuntime",
+  },
+});

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@gakr-gakr/zalo",
+  "version": "0.1.0",
+  "description": "AutoBot Zalo channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/autobot/autobot"
+  },
+  "type": "module",
+  "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": "zalo",
+      "label": "Zalo",
+      "selectionLabel": "Zalo (Bot API)",
+      "docsPath": "/channels/zalo",
+      "docsLabel": "zalo",
+      "blurb": "Vietnam-focused messaging platform with Bot API.",
+      "aliases": [
+        "zl"
+      ],
+      "order": 80,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@gakr-gakr/zalo",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=0.1.0"
+    },
+    "compat": {
+      "pluginApi": ">=0.1.0"
+    },
+    "build": {
+      "autobotVersion": "0.1.0"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,71 @@
+export {
+  addWildcardAllowFrom,
+  applyAccountNameToChannelSection,
+  applyBasicWebhookRequestGuards,
+  applySetupAccountConfigPatch,
+  type BaseProbeResult,
+  type BaseTokenResolution,
+  buildBaseAccountStatusSnapshot,
+  buildChannelConfigSchema,
+  buildSecretInputSchema,
+  buildSingleChannelSecretPromptState,
+  buildTokenChannelStatusSummary,
+  type ChannelAccountSnapshot,
+  type ChannelMessageActionAdapter,
+  type ChannelMessageActionName,
+  type ChannelPlugin,
+  type ChannelStatusIssue,
+  chunkTextForOutbound,
+  createChannelPairingController,
+  createChannelMessageReplyPipeline,
+  createDedupeCache,
+  createFixedWindowRateLimiter,
+  createWebhookAnomalyTracker,
+  DEFAULT_ACCOUNT_ID,
+  deliverTextOrMediaReply,
+  formatAllowFromLowercase,
+  formatPairingApproveHint,
+  type GroupPolicy,
+  hasConfiguredSecretInput,
+  isNormalizedSenderAllowed,
+  isNumericTargetId,
+  jsonResult,
+  logTypingFailure,
+  type MarkdownTableMode,
+  mergeAllowFromEntries,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+  type AutoBotConfig,
+  type OutboundReplyPayload,
+  PAIRING_APPROVED_MESSAGE,
+  type PluginRuntime,
+  promptSingleChannelSecretInput,
+  readJsonWebhookBodyOrReject,
+  readStringParam,
+  registerPluginHttpRoute,
+  type RegisterWebhookPluginRouteOptions,
+  registerWebhookTarget,
+  type RegisterWebhookTargetOptions,
+  registerWebhookTargetWithPluginRoute,
+  type ReplyPayload,
+  resolveClientIp,
+  resolveDefaultGroupPolicy,
+  resolveInboundRouteEnvelopeBuilderWithRuntime,
+  resolveOpenProviderRuntimeGroupPolicy,
+  resolveWebhookPath,
+  resolveWebhookTargetWithAuthOrRejectSync,
+  runSingleChannelSecretStep,
+  type RuntimeEnv,
+  type SecretInput,
+  sendPayloadWithChunkedTextAndMedia,
+  setTopLevelChannelDmPolicyWithAllowFrom,
+  setZaloRuntime,
+  waitForAbortSignal,
+  warnMissingProviderGroupPolicyFallbackOnce,
+  WEBHOOK_ANOMALY_COUNTER_DEFAULTS,
+  WEBHOOK_RATE_LIMIT_DEFAULTS,
+  withResolvedWebhookRequestPipeline,
+  type WizardPrompter,
+} from "./src/runtime-api.js";

package/secret-contract-api.ts

@@ -0,0 +1,5 @@
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/setup-api.ts

@@ -0,0 +1,34 @@
+import { loadBundledEntryExportSync } from "autobot/plugin-sdk/channel-entry-contract";
+
+type SetupSurfaceModule = typeof import("./src/setup-surface.js");
+
+function createLazyObjectValue<T extends object>(load: () => T): T {
+  return new Proxy({} as T, {
+    get(_target, property, receiver) {
+      return Reflect.get(load(), property, receiver);
+    },
+    has(_target, property) {
+      return property in load();
+    },
+    ownKeys() {
+      return Reflect.ownKeys(load());
+    },
+    getOwnPropertyDescriptor(_target, property) {
+      const descriptor = Object.getOwnPropertyDescriptor(load(), property);
+      return descriptor ? { ...descriptor, configurable: true } : undefined;
+    },
+  });
+}
+
+function loadSetupSurfaceModule(): SetupSurfaceModule {
+  return loadBundledEntryExportSync<SetupSurfaceModule>(import.meta.url, {
+    specifier: "./src/setup-surface.js",
+  });
+}
+
+export { zaloDmPolicy, zaloSetupAdapter, createZaloSetupWizardProxy } from "./src/setup-core.js";
+export { resolveZaloRuntimeGroupPolicy } from "./src/group-access.js";
+
+export const zaloSetupWizard: SetupSurfaceModule["zaloSetupWizard"] = createLazyObjectValue(
+  () => loadSetupSurfaceModule().zaloSetupWizard as object,
+) as SetupSurfaceModule["zaloSetupWizard"];

package/setup-entry.ts

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

package/src/accounts.ts

@@ -0,0 +1,65 @@
+import {
+  createAccountListHelpers,
+  resolveMergedAccountConfig,
+} from "autobot/plugin-sdk/account-helpers";
+import { normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { resolveZaloToken } from "./token.js";
+import type { ResolvedZaloAccount, ZaloAccountConfig, ZaloConfig } from "./types.js";
+
+export type { ResolvedZaloAccount };
+
+const { listAccountIds: listZaloAccountIds, resolveDefaultAccountId: resolveDefaultZaloAccountId } =
+  createAccountListHelpers("zalo", {
+    implicitDefaultAccount: {
+      channelKeys: ["botToken", "tokenFile"],
+      envVars: ["ZALO_BOT_TOKEN"],
+    },
+  });
+export { listZaloAccountIds, resolveDefaultZaloAccountId };
+
+function mergeZaloAccountConfig(cfg: AutoBotConfig, accountId: string): ZaloAccountConfig {
+  return resolveMergedAccountConfig<ZaloAccountConfig>({
+    channelConfig: cfg.channels?.zalo as ZaloAccountConfig | undefined,
+    accounts: (cfg.channels?.zalo as ZaloConfig | undefined)?.accounts as
+      | Record<string, Partial<ZaloAccountConfig>>
+      | undefined,
+    accountId,
+    omitKeys: ["defaultAccount"],
+  });
+}
+
+export function resolveZaloAccount(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  allowUnresolvedSecretRef?: boolean;
+}): ResolvedZaloAccount {
+  const accountId = normalizeAccountId(
+    params.accountId ?? (params.cfg.channels?.zalo as ZaloConfig | undefined)?.defaultAccount,
+  );
+  const baseEnabled = (params.cfg.channels?.zalo as ZaloConfig | undefined)?.enabled !== false;
+  const merged = mergeZaloAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+  const tokenResolution = resolveZaloToken(
+    params.cfg.channels?.zalo as ZaloConfig | undefined,
+    accountId,
+    { allowUnresolvedSecretRef: params.allowUnresolvedSecretRef },
+  );
+
+  return {
+    accountId,
+    name: normalizeOptionalString(merged.name),
+    enabled,
+    token: tokenResolution.token,
+    tokenSource: tokenResolution.source,
+    config: merged,
+  };
+}
+
+export function listEnabledZaloAccounts(cfg: AutoBotConfig): ResolvedZaloAccount[] {
+  return listZaloAccountIds(cfg)
+    .map((accountId) => resolveZaloAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

package/src/actions.runtime.ts

@@ -0,0 +1,5 @@
+import { sendMessageZalo as sendMessageZaloImpl } from "./send.js";
+
+export const zaloActionsRuntime = {
+  sendMessageZalo: sendMessageZaloImpl,
+};

package/src/actions.ts

@@ -0,0 +1,62 @@
+import { jsonResult, readStringParam } from "autobot/plugin-sdk/channel-actions";
+import type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionName,
+} from "autobot/plugin-sdk/channel-contract";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { createLazyRuntimeNamedExport } from "autobot/plugin-sdk/lazy-runtime";
+import { extractToolSend } from "autobot/plugin-sdk/tool-send";
+import { listEnabledZaloAccounts, resolveZaloAccount } from "./accounts.js";
+
+const loadZaloActionsRuntime = createLazyRuntimeNamedExport(
+  () => import("./actions.runtime.js"),
+  "zaloActionsRuntime",
+);
+
+const providerId = "zalo";
+
+function listEnabledAccounts(cfg: AutoBotConfig, accountId?: string | null) {
+  return (
+    accountId ? [resolveZaloAccount({ cfg, accountId })] : listEnabledZaloAccounts(cfg)
+  ).filter((account) => account.enabled && account.tokenSource !== "none");
+}
+
+export const zaloMessageActions: ChannelMessageActionAdapter = {
+  describeMessageTool: ({ cfg, accountId }) => {
+    const accounts = listEnabledAccounts(cfg, accountId);
+    if (accounts.length === 0) {
+      return null;
+    }
+    const actions = new Set<ChannelMessageActionName>(["send"]);
+    return { actions: Array.from(actions), capabilities: [] };
+  },
+  extractToolSend: ({ args }) => extractToolSend(args, "sendMessage"),
+  handleAction: async ({ action, params, cfg, accountId }) => {
+    if (action === "send") {
+      const to = readStringParam(params, "to", { required: true });
+      const content = readStringParam(params, "message", {
+        required: true,
+        allowEmpty: true,
+      });
+      const mediaUrl = readStringParam(params, "media", { trim: false });
+
+      const { sendMessageZalo } = await loadZaloActionsRuntime();
+      const result = await sendMessageZalo(to ?? "", content ?? "", {
+        accountId: accountId ?? undefined,
+        mediaUrl: mediaUrl ?? undefined,
+        cfg: cfg,
+      });
+
+      if (!result.ok) {
+        return jsonResult({
+          ok: false,
+          error: result.error ?? "Failed to send Zalo message",
+        });
+      }
+
+      return jsonResult({ ok: true, to, messageId: result.messageId });
+    }
+
+    throw new Error(`Action ${action} is not supported for provider ${providerId}.`);
+  },
+};

package/src/api.ts

@@ -0,0 +1,265 @@
+/**
+ * Zalo Bot API client
+ * @see https://bot.zaloplatforms.com/docs
+ */
+
+import { resolvePinnedHostnameWithPolicy, type SsrFPolicy } from "autobot/plugin-sdk/ssrf-runtime";
+
+const ZALO_API_BASE = "https://bot-api.zaloplatforms.com";
+const ZALO_MEDIA_SSRF_POLICY: SsrFPolicy = {};
+
+export type ZaloFetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+export type ZaloApiResponse<T = unknown> = {
+  ok: boolean;
+  result?: T;
+  error_code?: number;
+  description?: string;
+};
+
+export type ZaloBotInfo = {
+  id: string;
+  name: string;
+  avatar?: string;
+};
+
+export type ZaloMessage = {
+  message_id: string;
+  from: {
+    id: string;
+    name?: string;
+    display_name?: string;
+    avatar?: string;
+    is_bot?: boolean;
+  };
+  chat: {
+    id: string;
+    chat_type: "PRIVATE" | "GROUP";
+  };
+  date: number;
+  text?: string;
+  photo_url?: string;
+  caption?: string;
+  sticker?: string;
+  message_type?: string;
+};
+
+export type ZaloUpdate = {
+  event_name:
+    | "message.text.received"
+    | "message.image.received"
+    | "message.sticker.received"
+    | "message.unsupported.received";
+  message?: ZaloMessage;
+};
+
+export type ZaloSendMessageParams = {
+  chat_id: string;
+  text: string;
+};
+
+export type ZaloSendPhotoParams = {
+  chat_id: string;
+  photo: string;
+  caption?: string;
+};
+
+export type ZaloSendChatActionParams = {
+  chat_id: string;
+  action: "typing" | "upload_photo";
+};
+
+export type ZaloSetWebhookParams = {
+  url: string;
+  secret_token: string;
+};
+
+export type ZaloWebhookInfo = {
+  url?: string;
+  updated_at?: number;
+  has_custom_certificate?: boolean;
+};
+
+export type ZaloGetUpdatesParams = {
+  /** Timeout in seconds (passed as string to API) */
+  timeout?: number;
+};
+
+export class ZaloApiError extends Error {
+  constructor(
+    message: string,
+    public readonly errorCode?: number,
+    public readonly description?: string,
+  ) {
+    super(message);
+    this.name = "ZaloApiError";
+  }
+
+  /** True if this is a long-polling timeout (no updates available) */
+  get isPollingTimeout(): boolean {
+    return this.errorCode === 408;
+  }
+}
+
+/**
+ * Call the Zalo Bot API
+ */
+export async function callZaloApi<T = unknown>(
+  method: string,
+  token: string,
+  body?: Record<string, unknown>,
+  options?: { timeoutMs?: number; fetch?: ZaloFetch },
+): Promise<ZaloApiResponse<T>> {
+  const url = `${ZALO_API_BASE}/bot${token}/${method}`;
+  const controller = new AbortController();
+  const timeoutId = options?.timeoutMs
+    ? setTimeout(() => controller.abort(), options.timeoutMs)
+    : undefined;
+  const fetcher = options?.fetch ?? fetch;
+
+  try {
+    const response = await fetcher(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: controller.signal,
+    });
+
+    const data = (await response.json()) as ZaloApiResponse<T>;
+
+    if (!data.ok) {
+      throw new ZaloApiError(
+        data.description ?? `Zalo API error: ${method}`,
+        data.error_code,
+        data.description,
+      );
+    }
+
+    return data;
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+/**
+ * Validate bot token and get bot info
+ */
+export async function getMe(
+  token: string,
+  timeoutMs?: number,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<ZaloBotInfo>> {
+  return callZaloApi<ZaloBotInfo>("getMe", token, undefined, { timeoutMs, fetch: fetcher });
+}
+
+/**
+ * Send a text message
+ */
+export async function sendMessage(
+  token: string,
+  params: ZaloSendMessageParams,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<ZaloMessage>> {
+  return callZaloApi<ZaloMessage>("sendMessage", token, params, { fetch: fetcher });
+}
+
+/**
+ * Send a photo message
+ */
+export async function sendPhoto(
+  token: string,
+  params: ZaloSendPhotoParams,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<ZaloMessage>> {
+  const photoUrl = params.photo.trim();
+  let parsedPhotoUrl: URL;
+  try {
+    parsedPhotoUrl = new URL(photoUrl);
+  } catch {
+    throw new Error("Zalo photo URL must be an absolute HTTP or HTTPS URL");
+  }
+
+  if (parsedPhotoUrl.protocol !== "http:" && parsedPhotoUrl.protocol !== "https:") {
+    throw new Error("Zalo photo URL must use HTTP or HTTPS");
+  }
+
+  await resolvePinnedHostnameWithPolicy(parsedPhotoUrl.hostname, {
+    policy: ZALO_MEDIA_SSRF_POLICY,
+  });
+
+  return callZaloApi<ZaloMessage>(
+    "sendPhoto",
+    token,
+    { ...params, photo: parsedPhotoUrl.href },
+    { fetch: fetcher },
+  );
+}
+
+/**
+ * Send a temporary chat action such as typing.
+ */
+export async function sendChatAction(
+  token: string,
+  params: ZaloSendChatActionParams,
+  fetcher?: ZaloFetch,
+  timeoutMs?: number,
+): Promise<ZaloApiResponse<boolean>> {
+  return callZaloApi<boolean>("sendChatAction", token, params, {
+    timeoutMs,
+    fetch: fetcher,
+  });
+}
+
+/**
+ * Get updates using long polling (dev/testing only)
+ * Note: Zalo returns a single update per call, not an array like Telegram
+ */
+export async function getUpdates(
+  token: string,
+  params?: ZaloGetUpdatesParams,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<ZaloUpdate>> {
+  const pollTimeoutSec = params?.timeout ?? 30;
+  const timeoutMs = (pollTimeoutSec + 5) * 1000;
+  const body = { timeout: String(pollTimeoutSec) };
+  return callZaloApi<ZaloUpdate>("getUpdates", token, body, { timeoutMs, fetch: fetcher });
+}
+
+/**
+ * Set webhook URL for receiving updates
+ */
+export async function setWebhook(
+  token: string,
+  params: ZaloSetWebhookParams,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<ZaloWebhookInfo>> {
+  return callZaloApi<ZaloWebhookInfo>("setWebhook", token, params, { fetch: fetcher });
+}
+
+/**
+ * Delete webhook configuration
+ */
+export async function deleteWebhook(
+  token: string,
+  fetcher?: ZaloFetch,
+  timeoutMs?: number,
+): Promise<ZaloApiResponse<ZaloWebhookInfo>> {
+  return callZaloApi<ZaloWebhookInfo>("deleteWebhook", token, undefined, {
+    timeoutMs,
+    fetch: fetcher,
+  });
+}
+
+/**
+ * Get current webhook info
+ */
+export async function getWebhookInfo(
+  token: string,
+  fetcher?: ZaloFetch,
+): Promise<ZaloApiResponse<ZaloWebhookInfo>> {
+  return callZaloApi<ZaloWebhookInfo>("getWebhookInfo", token, undefined, { fetch: fetcher });
+}