@kodelyth/zalo 2026.5.42 → 2026.6.2

package/src/api.ts

@@ -1,265 +0,0 @@
-/**
- * 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 });
-}

package/src/approval-auth.test.ts

@@ -1,17 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { zaloApprovalAuth } from "./approval-auth.js";
-
-describe("zaloApprovalAuth", () => {
-  it("authorizes numeric Zalo user ids", () => {
-    const cfg = { channels: { zalo: { allowFrom: ["zl:123"] } } };
-
-    expect(
-      zaloApprovalAuth.authorizeActorAction({
-        cfg,
-        senderId: "123",
-        action: "approve",
-        approvalKind: "exec",
-      }),
-    ).toEqual({ authorized: true });
-  });
-});

package/src/approval-auth.ts

@@ -1,25 +0,0 @@
-import {
-  createResolvedApproverActionAuthAdapter,
-  resolveApprovalApprovers,
-} from "klaw/plugin-sdk/approval-auth-runtime";
-import { resolveZaloAccount } from "./accounts.js";
-
-function normalizeZaloApproverId(value: string | number): string | undefined {
-  const normalized = String(value)
-    .trim()
-    .replace(/^(zalo|zl):/i, "")
-    .trim();
-  return /^\d+$/.test(normalized) ? normalized : undefined;
-}
-
-export const zaloApprovalAuth = createResolvedApproverActionAuthAdapter({
-  channelLabel: "Zalo",
-  resolveApprovers: ({ cfg, accountId }) => {
-    const account = resolveZaloAccount({ cfg, accountId }).config;
-    return resolveApprovalApprovers({
-      allowFrom: account.allowFrom,
-      normalizeApprover: normalizeZaloApproverId,
-    });
-  },
-  normalizeSenderId: (value) => normalizeZaloApproverId(value),
-});

package/src/channel.directory.test.ts

@@ -1,56 +0,0 @@
-import {
-  createDirectoryTestRuntime,
-  expectDirectorySurface,
-} from "klaw/plugin-sdk/channel-test-helpers";
-import { describe, expect, it } from "vitest";
-import type { KlawConfig, RuntimeEnv } from "../runtime-api.js";
-import { zaloPlugin } from "./channel.js";
-
-describe("zalo directory", () => {
-  const runtimeEnv = createDirectoryTestRuntime() as RuntimeEnv;
-  const directory = expectDirectorySurface(zaloPlugin.directory);
-
-  async function expectPeersFromAllowFrom(allowFrom: string[]) {
-    const cfg = {
-      channels: {
-        zalo: {
-          allowFrom,
-        },
-      },
-    } as unknown as KlawConfig;
-
-    const peers = await directory.listPeers({
-      cfg,
-      accountId: undefined,
-      query: undefined,
-      limit: undefined,
-      runtime: runtimeEnv,
-    });
-    expect(peers).toStrictEqual([
-      { kind: "user", id: "123" },
-      { kind: "user", id: "234" },
-      { kind: "user", id: "345" },
-    ]);
-
-    await expect(
-      directory.listGroups({
-        cfg,
-        accountId: undefined,
-        query: undefined,
-        limit: undefined,
-        runtime: runtimeEnv,
-      }),
-    ).resolves.toStrictEqual([]);
-  }
-
-  it("lists peers from allowFrom", async () => {
-    await expectPeersFromAllowFrom(["zalo:123", "zl:234", "345"]);
-  });
-
-  it("normalizes spaced zalo prefixes in allowFrom and pairing entries", async () => {
-    await expectPeersFromAllowFrom(["  zalo:123  ", "  zl:234  ", " 345 "]);
-
-    expect(zaloPlugin.pairing?.normalizeAllowEntry?.("  zalo:123  ")).toBe("123");
-    expect(zaloPlugin.messaging?.normalizeTarget?.("  zl:234  ")).toBe("234");
-  });
-});

package/src/channel.runtime.ts

@@ -1,89 +0,0 @@
-import { createAccountStatusSink } from "klaw/plugin-sdk/channel-lifecycle";
-import { probeZalo } from "./probe.js";
-import { resolveZaloProxyFetch } from "./proxy.js";
-import { PAIRING_APPROVED_MESSAGE, type ChannelPlugin, type KlawConfig } from "./runtime-api.js";
-import { normalizeSecretInputString } from "./secret-input.js";
-import { sendMessageZalo } from "./send.js";
-import type { ResolvedZaloAccount } from "./types.js";
-
-export async function notifyZaloPairingApproval(params: { cfg: KlawConfig; id: string }) {
-  const { resolveZaloAccount } = await import("./accounts.js");
-  const account = resolveZaloAccount({ cfg: params.cfg });
-  if (!account.token) {
-    throw new Error("Zalo token not configured");
-  }
-  await sendMessageZalo(params.id, PAIRING_APPROVED_MESSAGE, {
-    token: account.token,
-  });
-}
-
-export async function sendZaloText(
-  params: Parameters<typeof sendMessageZalo>[2] & {
-    to: string;
-    text: string;
-  },
-) {
-  return await sendMessageZalo(params.to, params.text, params);
-}
-
-export async function probeZaloAccount(params: {
-  account: import("./accounts.js").ResolvedZaloAccount;
-  timeoutMs?: number;
-}) {
-  return await probeZalo(
-    params.account.token,
-    params.timeoutMs,
-    resolveZaloProxyFetch(params.account.config.proxy),
-  );
-}
-
-export async function startZaloGatewayAccount(
-  ctx: Parameters<
-    NonNullable<NonNullable<ChannelPlugin<ResolvedZaloAccount>["gateway"]>["startAccount"]>
-  >[0],
-) {
-  const account = ctx.account;
-  const token = account.token.trim();
-  const mode = account.config.webhookUrl ? "webhook" : "polling";
-  let zaloBotLabel = "";
-  const fetcher = resolveZaloProxyFetch(account.config.proxy);
-  try {
-    const probe = await probeZalo(token, 2500, fetcher);
-    const name = probe.ok ? probe.bot?.name?.trim() : null;
-    if (name) {
-      zaloBotLabel = ` (${name})`;
-    }
-    if (!probe.ok) {
-      ctx.log?.warn?.(
-        `[${account.accountId}] Zalo probe failed before provider start (${String(probe.elapsedMs)}ms): ${probe.error}`,
-      );
-    }
-    ctx.setStatus({
-      accountId: account.accountId,
-      bot: probe.bot,
-    });
-  } catch (err) {
-    ctx.log?.warn?.(
-      `[${account.accountId}] Zalo probe threw before provider start: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`,
-    );
-  }
-  const statusSink = createAccountStatusSink({
-    accountId: ctx.accountId,
-    setStatus: ctx.setStatus,
-  });
-  ctx.log?.info(`[${account.accountId}] starting provider${zaloBotLabel} mode=${mode}`);
-  const { monitorZaloProvider } = await import("./monitor.js");
-  return monitorZaloProvider({
-    token,
-    account,
-    config: ctx.cfg,
-    runtime: ctx.runtime,
-    abortSignal: ctx.abortSignal,
-    useWebhook: Boolean(account.config.webhookUrl),
-    webhookUrl: account.config.webhookUrl,
-    webhookSecret: normalizeSecretInputString(account.config.webhookSecret),
-    webhookPath: account.config.webhookPath,
-    fetcher,
-    statusSink,
-  });
-}

package/src/channel.startup.test.ts

@@ -1,121 +0,0 @@
-import {
-  expectLifecyclePatch,
-  expectPendingUntilAbort,
-  startAccountAndTrackLifecycle,
-  waitForStartedMocks,
-} from "klaw/plugin-sdk/channel-test-helpers";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import type { ResolvedZaloAccount } from "./accounts.js";
-
-const hoisted = vi.hoisted(() => ({
-  monitorZaloProvider: vi.fn(),
-  probeZalo: vi.fn(async () => ({
-    ok: false as const,
-    error: "probe failed",
-    elapsedMs: 1,
-  })),
-}));
-
-vi.mock("./monitor.js", () => {
-  return {
-    monitorZaloProvider: hoisted.monitorZaloProvider,
-  };
-});
-
-vi.mock("./probe.js", () => {
-  return {
-    probeZalo: hoisted.probeZalo,
-  };
-});
-
-vi.mock("./channel.runtime.js", () => ({
-  probeZaloAccount: hoisted.probeZalo,
-  startZaloGatewayAccount: async (ctx: {
-    account: ResolvedZaloAccount;
-    abortSignal: AbortSignal;
-    setStatus: (patch: Partial<ResolvedZaloAccount>) => void;
-  }) => {
-    await hoisted.probeZalo();
-    ctx.setStatus({ accountId: ctx.account.accountId });
-    return await hoisted.monitorZaloProvider({
-      token: ctx.account.token,
-      account: ctx.account,
-      abortSignal: ctx.abortSignal,
-      useWebhook: false,
-    });
-  },
-}));
-
-import { zaloPlugin } from "./channel.js";
-
-type ZaloGateway = NonNullable<typeof zaloPlugin.gateway>;
-type ZaloStartAccount = NonNullable<ZaloGateway["startAccount"]>;
-
-function requireStartAccount(): ZaloStartAccount {
-  const startAccount = zaloPlugin.gateway?.startAccount;
-  if (!startAccount) {
-    throw new Error("Expected Zalo gateway startAccount");
-  }
-  return startAccount;
-}
-
-function buildAccount(): ResolvedZaloAccount {
-  return {
-    accountId: "default",
-    enabled: true,
-    token: "test-token",
-    tokenSource: "config",
-    config: {},
-  };
-}
-
-function requireMonitorArgs() {
-  const [call] = hoisted.monitorZaloProvider.mock.calls;
-  if (!call) {
-    throw new Error("expected Zalo monitor call");
-  }
-  const [monitorArgs] = call;
-  return monitorArgs;
-}
-
-describe("zaloPlugin gateway.startAccount", () => {
-  afterEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("keeps startAccount pending until abort", async () => {
-    hoisted.monitorZaloProvider.mockImplementationOnce(
-      async ({ abortSignal }: { abortSignal: AbortSignal }) =>
-        await new Promise<void>((resolve) => {
-          if (abortSignal.aborted) {
-            resolve();
-            return;
-          }
-          abortSignal.addEventListener("abort", () => resolve(), { once: true });
-        }),
-    );
-
-    const { abort, patches, task, isSettled } = startAccountAndTrackLifecycle({
-      startAccount: requireStartAccount(),
-      account: buildAccount(),
-    });
-
-    await expectPendingUntilAbort({
-      waitForStarted: waitForStartedMocks(hoisted.probeZalo, hoisted.monitorZaloProvider),
-      isSettled,
-      abort,
-      task,
-    });
-
-    expectLifecyclePatch(patches, { accountId: "default" });
-    expect(isSettled()).toBe(true);
-    expect(hoisted.monitorZaloProvider).toHaveBeenCalledTimes(1);
-    const monitorArgs = requireMonitorArgs();
-    expect(monitorArgs).toStrictEqual({
-      token: "test-token",
-      account: buildAccount(),
-      abortSignal: abort.signal,
-      useWebhook: false,
-    });
-  });
-});