@kodelyth/zalo 2026.5.39 → 2026.5.42

package/src/send.ts

@@ -0,0 +1,207 @@
+import {
+  createMessageReceiptFromOutboundResults,
+  type MessageReceipt,
+  type MessageReceiptPartKind,
+} from "klaw/plugin-sdk/channel-message";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import { resolveZaloAccount } from "./accounts.js";
+import type { ZaloFetch } from "./api.js";
+import { sendMessage, sendPhoto } from "./api.js";
+import { resolveZaloProxyFetch } from "./proxy.js";
+import { resolveZaloToken } from "./token.js";
+
+type ZaloSendOptions = {
+  token?: string;
+  accountId?: string;
+  cfg?: KlawConfig;
+  mediaUrl?: string;
+  caption?: string;
+  verbose?: boolean;
+  proxy?: string;
+};
+
+type ZaloSendResult = {
+  ok: boolean;
+  messageId?: string;
+  receipt: MessageReceipt;
+  error?: string;
+};
+
+function createZaloSendReceipt(params: {
+  messageId?: string;
+  chatId: string;
+  kind: MessageReceiptPartKind;
+}): MessageReceipt {
+  const messageId = params.messageId?.trim();
+  return createMessageReceiptFromOutboundResults({
+    results: messageId
+      ? [
+          {
+            channel: "zalo",
+            messageId,
+            chatId: params.chatId,
+          },
+        ]
+      : [],
+    kind: params.kind,
+  });
+}
+
+function toZaloSendResult(
+  response: {
+    ok?: boolean;
+    result?: { message_id?: string };
+  },
+  params: { chatId: string; kind: MessageReceiptPartKind },
+): ZaloSendResult {
+  if (response.ok && response.result) {
+    return {
+      ok: true,
+      messageId: response.result.message_id,
+      receipt: createZaloSendReceipt({
+        messageId: response.result.message_id,
+        chatId: params.chatId,
+        kind: params.kind,
+      }),
+    };
+  }
+  return {
+    ok: false,
+    error: "Failed to send message",
+    receipt: createZaloSendReceipt({ chatId: params.chatId, kind: params.kind }),
+  };
+}
+
+async function runZaloSend(
+  failureMessage: string,
+  params: { chatId: string; kind: MessageReceiptPartKind },
+  send: () => Promise<{ ok?: boolean; result?: { message_id?: string } }>,
+): Promise<ZaloSendResult> {
+  try {
+    const result = toZaloSendResult(await send(), params);
+    return result.ok ? result : { ok: false, error: failureMessage, receipt: result.receipt };
+  } catch (err) {
+    return {
+      ok: false,
+      error: formatErrorMessage(err),
+      receipt: createZaloSendReceipt({ chatId: params.chatId, kind: params.kind }),
+    };
+  }
+}
+
+function resolveSendContext(options: ZaloSendOptions): {
+  token: string;
+  fetcher?: ZaloFetch;
+} {
+  if (options.cfg) {
+    const account = resolveZaloAccount({
+      cfg: options.cfg,
+      accountId: options.accountId,
+    });
+    const token = options.token || account.token;
+    const proxy = options.proxy ?? account.config.proxy;
+    return { token, fetcher: resolveZaloProxyFetch(proxy) };
+  }
+
+  const token = options.token ?? resolveZaloToken(undefined, options.accountId).token;
+  const proxy = options.proxy;
+  return { token, fetcher: resolveZaloProxyFetch(proxy) };
+}
+
+function resolveValidatedSendContext(
+  chatId: string,
+  options: ZaloSendOptions,
+): { ok: true; chatId: string; token: string; fetcher?: ZaloFetch } | { ok: false; error: string } {
+  const { token, fetcher } = resolveSendContext(options);
+  if (!token) {
+    return { ok: false, error: "No Zalo bot token configured" };
+  }
+  const trimmedChatId = chatId?.trim();
+  if (!trimmedChatId) {
+    return { ok: false, error: "No chat_id provided" };
+  }
+  return { ok: true, chatId: trimmedChatId, token, fetcher };
+}
+
+function resolveSendContextOrFailure(
+  chatId: string,
+  options: ZaloSendOptions,
+):
+  | { context: { chatId: string; token: string; fetcher?: ZaloFetch } }
+  | { failure: ZaloSendResult } {
+  const context = resolveValidatedSendContext(chatId, options);
+  return context.ok
+    ? { context }
+    : {
+        failure: {
+          ok: false,
+          error: context.error,
+          receipt: createZaloSendReceipt({ chatId, kind: "unknown" }),
+        },
+      };
+}
+
+export async function sendMessageZalo(
+  chatId: string,
+  text: string,
+  options: ZaloSendOptions = {},
+): Promise<ZaloSendResult> {
+  const resolved = resolveSendContextOrFailure(chatId, options);
+  if ("failure" in resolved) {
+    return resolved.failure;
+  }
+  const { context } = resolved;
+
+  if (options.mediaUrl) {
+    return sendPhotoZalo(context.chatId, options.mediaUrl, {
+      ...options,
+      token: context.token,
+      caption: text || options.caption,
+    });
+  }
+
+  return await runZaloSend("Failed to send message", { chatId: context.chatId, kind: "text" }, () =>
+    sendMessage(
+      context.token,
+      {
+        chat_id: context.chatId,
+        text: text.slice(0, 2000),
+      },
+      context.fetcher,
+    ),
+  );
+}
+
+export async function sendPhotoZalo(
+  chatId: string,
+  photoUrl: string,
+  options: ZaloSendOptions = {},
+): Promise<ZaloSendResult> {
+  const resolved = resolveSendContextOrFailure(chatId, options);
+  if ("failure" in resolved) {
+    return resolved.failure;
+  }
+  const { context } = resolved;
+
+  if (!photoUrl?.trim()) {
+    return {
+      ok: false,
+      error: "No photo URL provided",
+      receipt: createZaloSendReceipt({ chatId: context.chatId, kind: "media" }),
+    };
+  }
+
+  return await runZaloSend("Failed to send photo", { chatId: context.chatId, kind: "media" }, () =>
+    (async () =>
+      sendPhoto(
+        context.token,
+        {
+          chat_id: context.chatId,
+          photo: photoUrl.trim(),
+          caption: options.caption?.slice(0, 2000),
+        },
+        context.fetcher,
+      ))(),
+  );
+}

package/src/session-route.ts

@@ -0,0 +1,32 @@
+import {
+  buildChannelOutboundSessionRoute,
+  stripChannelTargetPrefix,
+  stripTargetKindPrefix,
+  type ChannelOutboundSessionRouteParams,
+} from "klaw/plugin-sdk/core";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+
+export function resolveZaloOutboundSessionRoute(params: ChannelOutboundSessionRouteParams) {
+  const trimmed = stripChannelTargetPrefix(params.target, "zalo", "zl");
+  if (!trimmed) {
+    return null;
+  }
+  const isGroup = normalizeLowercaseStringOrEmpty(trimmed).startsWith("group:");
+  const peerId = stripTargetKindPrefix(trimmed);
+  if (!peerId) {
+    return null;
+  }
+  return buildChannelOutboundSessionRoute({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "zalo",
+    accountId: params.accountId,
+    peer: {
+      kind: isGroup ? "group" : "direct",
+      id: peerId,
+    },
+    chatType: isGroup ? "group" : "direct",
+    from: isGroup ? `zalo:group:${peerId}` : `zalo:${peerId}`,
+    to: `zalo:${peerId}`,
+  });
+}

package/src/setup-allow-from.ts

@@ -0,0 +1,97 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  createSetupTranslator,
+  formatDocsLink,
+  mergeAllowFromEntries,
+  type ChannelSetupDmPolicy,
+  type ChannelSetupWizard,
+  type KlawConfig,
+} from "klaw/plugin-sdk/setup";
+import { resolveDefaultZaloAccountId, resolveZaloAccount } from "./accounts.js";
+
+const t = createSetupTranslator();
+
+type ZaloAccountSetupConfig = {
+  enabled?: boolean;
+};
+
+export async function noteZaloTokenHelp(
+  prompter: Parameters<NonNullable<ChannelSetupWizard["finalize"]>>[0]["prompter"],
+): Promise<void> {
+  await prompter.note(
+    [
+      t("wizard.zalo.helpOpenPlatform"),
+      t("wizard.zalo.helpCreateBot"),
+      t("wizard.zalo.helpTokenFormat"),
+      t("wizard.zalo.helpEnvTip"),
+      `Docs: ${formatDocsLink("/channels/zalo", "zalo")}`,
+    ].join("\n"),
+    t("wizard.zalo.botTokenTitle"),
+  );
+}
+
+export async function promptZaloAllowFrom(params: {
+  cfg: KlawConfig;
+  prompter: Parameters<NonNullable<ChannelSetupDmPolicy["promptAllowFrom"]>>[0]["prompter"];
+  accountId?: string;
+}): Promise<KlawConfig> {
+  const { cfg, prompter } = params;
+  const accountId = params.accountId ?? resolveDefaultZaloAccountId(cfg);
+  const resolved = resolveZaloAccount({ cfg, accountId });
+  const existingAllowFrom = resolved.config.allowFrom ?? [];
+  const entry = await prompter.text({
+    message: t("wizard.zalo.allowFromPrompt"),
+    placeholder: "123456789",
+    initialValue: existingAllowFrom[0] ? String(existingAllowFrom[0]) : undefined,
+    validate: (value) => {
+      const raw = (value ?? "").trim();
+      if (!raw) {
+        return t("common.required");
+      }
+      if (!/^\d+$/.test(raw)) {
+        return t("wizard.zalo.allowFromNumeric");
+      }
+      return undefined;
+    },
+  });
+  const normalized = entry.trim();
+  const unique = mergeAllowFromEntries(existingAllowFrom, [normalized]);
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalo: {
+          ...cfg.channels?.zalo,
+          enabled: true,
+          dmPolicy: "allowlist",
+          allowFrom: unique,
+        },
+      },
+    } as KlawConfig;
+  }
+
+  const currentAccount = cfg.channels?.zalo?.accounts?.[accountId] as
+    | ZaloAccountSetupConfig
+    | undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      zalo: {
+        ...cfg.channels?.zalo,
+        enabled: true,
+        accounts: {
+          ...cfg.channels?.zalo?.accounts,
+          [accountId]: {
+            ...currentAccount,
+            enabled: currentAccount?.enabled ?? true,
+            dmPolicy: "allowlist",
+            allowFrom: unique,
+          },
+        },
+      },
+    },
+  } as KlawConfig;
+}

package/src/setup-core.ts

@@ -0,0 +1,152 @@
+import {
+  addWildcardAllowFrom,
+  createDelegatedSetupWizardProxy,
+  createPatchedAccountSetupAdapter,
+  createSetupInputPresenceValidator,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  createSetupTranslator,
+  type ChannelSetupDmPolicy,
+  type ChannelSetupWizard,
+} from "klaw/plugin-sdk/setup";
+import { resolveDefaultZaloAccountId, resolveZaloAccount } from "./accounts.js";
+import { promptZaloAllowFrom } from "./setup-allow-from.js";
+
+const t = createSetupTranslator();
+
+const channel = "zalo" as const;
+
+type ZaloAccountSetupConfig = {
+  enabled?: boolean;
+  dmPolicy?: string;
+  allowFrom?: Array<string | number> | ReadonlyArray<string | number>;
+};
+
+export const zaloSetupAdapter = createPatchedAccountSetupAdapter({
+  channelKey: channel,
+  validateInput: createSetupInputPresenceValidator({
+    defaultAccountOnlyEnvError: "ZALO_BOT_TOKEN can only be used for the default account.",
+    whenNotUseEnv: [
+      {
+        someOf: ["token", "tokenFile"],
+        message: "Zalo requires token or --token-file (or --use-env).",
+      },
+    ],
+  }),
+  buildPatch: (input) =>
+    input.useEnv
+      ? {}
+      : input.tokenFile
+        ? { tokenFile: input.tokenFile }
+        : input.token
+          ? { botToken: input.token }
+          : {},
+});
+
+export const zaloDmPolicy: ChannelSetupDmPolicy = {
+  label: "Zalo",
+  channel,
+  policyKey: "channels.zalo.dmPolicy",
+  allowFromKey: "channels.zalo.allowFrom",
+  resolveConfigKeys: (cfg, accountId) =>
+    (accountId ?? resolveDefaultZaloAccountId(cfg)) !== DEFAULT_ACCOUNT_ID
+      ? {
+          policyKey: `channels.zalo.accounts.${accountId ?? resolveDefaultZaloAccountId(cfg)}.dmPolicy`,
+          allowFromKey: `channels.zalo.accounts.${accountId ?? resolveDefaultZaloAccountId(cfg)}.allowFrom`,
+        }
+      : {
+          policyKey: "channels.zalo.dmPolicy",
+          allowFromKey: "channels.zalo.allowFrom",
+        },
+  getCurrent: (cfg, accountId) =>
+    resolveZaloAccount({
+      cfg: cfg,
+      accountId: accountId ?? resolveDefaultZaloAccountId(cfg),
+    }).config.dmPolicy ?? "pairing",
+  setPolicy: (cfg, policy, accountId) => {
+    const resolvedAccountId =
+      accountId && normalizeAccountId(accountId)
+        ? (normalizeAccountId(accountId) ?? DEFAULT_ACCOUNT_ID)
+        : resolveDefaultZaloAccountId(cfg);
+    const resolved = resolveZaloAccount({
+      cfg: cfg,
+      accountId: resolvedAccountId,
+    });
+    if (resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          zalo: {
+            ...cfg.channels?.zalo,
+            enabled: true,
+            dmPolicy: policy,
+            ...(policy === "open"
+              ? { allowFrom: addWildcardAllowFrom(resolved.config.allowFrom) }
+              : {}),
+          },
+        },
+      };
+    }
+    const currentAccount = cfg.channels?.zalo?.accounts?.[resolvedAccountId] as
+      | ZaloAccountSetupConfig
+      | undefined;
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalo: {
+          ...cfg.channels?.zalo,
+          enabled: true,
+          accounts: {
+            ...cfg.channels?.zalo?.accounts,
+            [resolvedAccountId]: {
+              ...currentAccount,
+              enabled: currentAccount?.enabled ?? true,
+              dmPolicy: policy,
+              ...(policy === "open"
+                ? { allowFrom: addWildcardAllowFrom(resolved.config.allowFrom) }
+                : {}),
+            },
+          },
+        },
+      },
+    };
+  },
+  promptAllowFrom: async ({ cfg, prompter, accountId }) =>
+    promptZaloAllowFrom({
+      cfg,
+      prompter,
+      accountId: accountId ?? resolveDefaultZaloAccountId(cfg),
+    }),
+};
+
+export function createZaloSetupWizardProxy(
+  loadWizard: () => Promise<ChannelSetupWizard>,
+): ChannelSetupWizard {
+  return createDelegatedSetupWizardProxy({
+    channel,
+    loadWizard,
+    status: {
+      configuredLabel: t("wizard.channels.statusConfigured"),
+      unconfiguredLabel: t("wizard.channels.statusNeedsToken"),
+      configuredHint: t("wizard.channels.statusRecommendedConfigured"),
+      unconfiguredHint: t("wizard.channels.statusRecommendedNewcomerFriendly"),
+      configuredScore: 1,
+      unconfiguredScore: 10,
+    },
+    credentials: [],
+    delegateFinalize: true,
+    dmPolicy: zaloDmPolicy,
+    disable: (cfg) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        zalo: {
+          ...cfg.channels?.zalo,
+          enabled: false,
+        },
+      },
+    }),
+  });
+}

package/src/setup-status.test.ts

@@ -0,0 +1,33 @@
+import { createPluginSetupWizardStatus } from "klaw/plugin-sdk/plugin-test-runtime";
+import { describe, expect, it } from "vitest";
+import type { KlawConfig } from "../runtime-api.js";
+import { zaloSetupWizard } from "./setup-surface.js";
+
+const zaloGetStatus = createPluginSetupWizardStatus({
+  id: "zalo",
+  meta: {
+    label: "Zalo",
+  },
+  setupWizard: zaloSetupWizard,
+} as never);
+
+describe("zalo setup wizard status", () => {
+  it("treats SecretRef botToken as configured", async () => {
+    const status = await zaloGetStatus({
+      cfg: {
+        channels: {
+          zalo: {
+            botToken: {
+              source: "env",
+              provider: "default",
+              id: "ZALO_BOT_TOKEN",
+            },
+          },
+        },
+      } as KlawConfig,
+      accountOverrides: {},
+    });
+
+    expect(status.configured).toBe(true);
+  });
+});