@kodelyth/zalo 2026.5.39 → 2026.5.42

package/src/accounts.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import {
+  listEnabledZaloAccounts,
+  listZaloAccountIds,
+  resolveDefaultZaloAccountId,
+  resolveZaloAccount,
+} from "./accounts.js";
+
+describe("resolveZaloAccount", () => {
+  it("resolves account config when account key casing differs from normalized id", () => {
+    const resolved = resolveZaloAccount({
+      cfg: {
+        channels: {
+          zalo: {
+            webhookUrl: "https://top.example.com",
+            accounts: {
+              Work: {
+                name: "Work",
+                webhookUrl: "https://work.example.com",
+              },
+            },
+          },
+        },
+      },
+      accountId: "work",
+    });
+
+    expect(resolved.accountId).toBe("work");
+    expect(resolved.name).toBe("Work");
+    expect(resolved.config.webhookUrl).toBe("https://work.example.com");
+  });
+
+  it("falls back to top-level config for named accounts without overrides", () => {
+    const resolved = resolveZaloAccount({
+      cfg: {
+        channels: {
+          zalo: {
+            enabled: true,
+            webhookUrl: "https://top.example.com",
+            accounts: {
+              work: {},
+            },
+          },
+        },
+      },
+      accountId: "work",
+    });
+
+    expect(resolved.accountId).toBe("work");
+    expect(resolved.enabled).toBe(true);
+    expect(resolved.config.webhookUrl).toBe("https://top.example.com");
+  });
+
+  it("uses configured defaultAccount when accountId is omitted", () => {
+    const resolved = resolveZaloAccount({
+      cfg: {
+        channels: {
+          zalo: {
+            defaultAccount: "work",
+            accounts: {
+              work: {
+                name: "Work",
+                botToken: "work-token",
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(resolved.accountId).toBe("work");
+    expect(resolved.name).toBe("Work");
+    expect(resolved.token).toBe("work-token");
+  });
+
+  it("keeps the implicit default account when named accounts are added to top-level credentials", () => {
+    const cfg = {
+      channels: {
+        zalo: {
+          botToken: "default-token",
+          accounts: {
+            work: {
+              enabled: false,
+              botToken: "work-token",
+            },
+          },
+        },
+      },
+    };
+
+    expect(listZaloAccountIds(cfg)).toEqual(["default", "work"]);
+    expect(resolveDefaultZaloAccountId(cfg)).toBe("default");
+    expect(listEnabledZaloAccounts(cfg).map((account) => account.accountId)).toEqual(["default"]);
+  });
+});

package/src/accounts.ts

@@ -0,0 +1,65 @@
+import {
+  createAccountListHelpers,
+  resolveMergedAccountConfig,
+} from "klaw/plugin-sdk/account-helpers";
+import { normalizeAccountId } from "klaw/plugin-sdk/account-id";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { normalizeOptionalString } from "klaw/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: KlawConfig, 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: KlawConfig;
+  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: KlawConfig): 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.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { zaloMessageActions } from "./actions.js";
+import type { KlawConfig } from "./runtime-api.js";
+
+describe("zaloMessageActions.describeMessageTool", () => {
+  it("honors the selected Zalo account during discovery", () => {
+    const cfg: KlawConfig = {
+      channels: {
+        zalo: {
+          enabled: true,
+          botToken: "root-token",
+          accounts: {
+            default: {
+              enabled: false,
+              botToken: "default-token",
+            },
+            work: {
+              enabled: true,
+              botToken: "work-token",
+            },
+          },
+        },
+      },
+    };
+
+    expect(zaloMessageActions.describeMessageTool?.({ cfg, accountId: "default" })).toBeNull();
+    expect(zaloMessageActions.describeMessageTool?.({ cfg, accountId: "work" })).toEqual({
+      actions: ["send"],
+      capabilities: [],
+    });
+  });
+});

package/src/actions.ts

@@ -0,0 +1,62 @@
+import { jsonResult, readStringParam } from "klaw/plugin-sdk/channel-actions";
+import type {
+  ChannelMessageActionAdapter,
+  ChannelMessageActionName,
+} from "klaw/plugin-sdk/channel-contract";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { createLazyRuntimeNamedExport } from "klaw/plugin-sdk/lazy-runtime";
+import { extractToolSend } from "klaw/plugin-sdk/tool-send";
+import { listEnabledZaloAccounts, resolveZaloAccount } from "./accounts.js";
+
+const loadZaloActionsRuntime = createLazyRuntimeNamedExport(
+  () => import("./actions.runtime.js"),
+  "zaloActionsRuntime",
+);
+
+const providerId = "zalo";
+
+function listEnabledAccounts(cfg: KlawConfig, 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.test.ts

@@ -0,0 +1,166 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const resolvePinnedHostnameWithPolicyMock = vi.fn();
+
+vi.mock("klaw/plugin-sdk/ssrf-runtime", () => ({
+  resolvePinnedHostnameWithPolicy: (...args: unknown[]) =>
+    resolvePinnedHostnameWithPolicyMock(...args),
+}));
+
+import { deleteWebhook, getWebhookInfo, sendChatAction, sendPhoto, type ZaloFetch } from "./api.js";
+
+function createOkFetcher() {
+  return vi.fn<ZaloFetch>(async () => new Response(JSON.stringify({ ok: true, result: {} })));
+}
+
+function requireFirstFetchCall(fetcher: ReturnType<typeof createOkFetcher>, label: string) {
+  const [call] = fetcher.mock.calls;
+  if (!call) {
+    throw new Error(`expected ${label}`);
+  }
+  return call;
+}
+
+async function expectPostJsonRequest(run: (token: string, fetcher: ZaloFetch) => Promise<unknown>) {
+  const fetcher = createOkFetcher();
+  await run("test-token", fetcher);
+  expect(fetcher).toHaveBeenCalledTimes(1);
+  const [, init] = requireFirstFetchCall(fetcher, "Zalo request");
+  if (!init) {
+    throw new Error("expected Zalo request init");
+  }
+  expect(init.method).toBe("POST");
+  expect(init.headers).toEqual({ "Content-Type": "application/json" });
+}
+
+describe("Zalo API request methods", () => {
+  beforeEach(() => {
+    resolvePinnedHostnameWithPolicyMock.mockReset();
+    resolvePinnedHostnameWithPolicyMock.mockResolvedValue({
+      hostname: "example.com",
+      addresses: ["93.184.216.34"],
+      lookup: vi.fn(),
+    });
+  });
+
+  it("uses POST for getWebhookInfo", async () => {
+    await expectPostJsonRequest(getWebhookInfo);
+  });
+
+  it("keeps POST for deleteWebhook", async () => {
+    await expectPostJsonRequest(deleteWebhook);
+  });
+
+  it("aborts sendChatAction when the typing timeout elapses", async () => {
+    vi.useFakeTimers();
+    try {
+      const fetcher = vi.fn<ZaloFetch>(
+        (_, init) =>
+          new Promise<Response>((_, reject) => {
+            init?.signal?.addEventListener("abort", () => reject(new Error("aborted")), {
+              once: true,
+            });
+          }),
+      );
+
+      const promise = sendChatAction(
+        "test-token",
+        {
+          chat_id: "chat-123",
+          action: "typing",
+        },
+        fetcher,
+        25,
+      );
+      const rejected = expect(promise).rejects.toThrow("aborted");
+
+      await vi.advanceTimersByTimeAsync(25);
+
+      await rejected;
+      const [, init] = requireFirstFetchCall(fetcher, "Zalo chat action request");
+      if (!init) {
+        throw new Error("expected Zalo chat action request init");
+      }
+      if (!init.signal) {
+        throw new Error("expected Zalo chat action abort signal");
+      }
+      expect(init.signal.aborted).toBe(true);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("validates outbound photo URLs against the SSRF guard before posting", async () => {
+    const fetcher = createOkFetcher();
+
+    await sendPhoto(
+      "test-token",
+      {
+        chat_id: "chat-123",
+        photo: "https://example.com/image.png",
+      },
+      fetcher,
+    );
+
+    expect(resolvePinnedHostnameWithPolicyMock).toHaveBeenCalledWith("example.com", {
+      policy: {},
+    });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it("blocks private-network photo URLs before they reach the Zalo API", async () => {
+    const fetcher = createOkFetcher();
+    resolvePinnedHostnameWithPolicyMock.mockRejectedValueOnce(
+      new Error("Blocked hostname or private/internal/special-use IP address"),
+    );
+
+    await expect(
+      sendPhoto(
+        "test-token",
+        {
+          chat_id: "chat-123",
+          photo: "http://169.254.169.254/latest/meta-data/iam/security-credentials/",
+        },
+        fetcher,
+      ),
+    ).rejects.toThrow("Blocked hostname or private/internal/special-use IP address");
+
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+
+  it("rejects non-http photo URLs", async () => {
+    const fetcher = createOkFetcher();
+
+    await expect(
+      sendPhoto(
+        "test-token",
+        {
+          chat_id: "chat-123",
+          photo: "file:///etc/passwd",
+        },
+        fetcher,
+      ),
+    ).rejects.toThrow("Zalo photo URL must use HTTP or HTTPS");
+
+    expect(resolvePinnedHostnameWithPolicyMock).not.toHaveBeenCalled();
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+
+  it("rejects non-URL strings", async () => {
+    const fetcher = createOkFetcher();
+
+    await expect(
+      sendPhoto(
+        "test-token",
+        {
+          chat_id: "chat-123",
+          photo: "not a url",
+        },
+        fetcher,
+      ),
+    ).rejects.toThrow("Zalo photo URL must be an absolute HTTP or HTTPS URL");
+
+    expect(resolvePinnedHostnameWithPolicyMock).not.toHaveBeenCalled();
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+});

package/src/api.ts

@@ -0,0 +1,265 @@
+/**
+ * Zalo Bot API client
+ * @see https://bot.zaloplatforms.com/docs
+ */
+
+import { resolvePinnedHostnameWithPolicy, type SsrFPolicy } from "klaw/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 });
+}