@gakr-gakr/zalo 0.1.0

package/src/approval-auth.ts

@@ -0,0 +1,25 @@
+import {
+  createResolvedApproverActionAuthAdapter,
+  resolveApprovalApprovers,
+} from "autobot/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.runtime.ts

@@ -0,0 +1,93 @@
+import { createAccountStatusSink } from "autobot/plugin-sdk/channel-lifecycle";
+import { probeZalo } from "./probe.js";
+import { resolveZaloProxyFetch } from "./proxy.js";
+import {
+  PAIRING_APPROVED_MESSAGE,
+  type ChannelPlugin,
+  type AutoBotConfig,
+} 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: AutoBotConfig; 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.ts

@@ -0,0 +1,309 @@
+import { describeWebhookAccountSnapshot } from "autobot/plugin-sdk/account-helpers";
+import { DEFAULT_ACCOUNT_ID } from "autobot/plugin-sdk/account-id";
+import { formatAllowFromLowercase } from "autobot/plugin-sdk/allow-from";
+import {
+  adaptScopedAccountAccessor,
+  createScopedChannelConfigAdapter,
+  createScopedDmSecurityResolver,
+  mapAllowFromEntries,
+} from "autobot/plugin-sdk/channel-config-helpers";
+import type { ChannelAccountSnapshot } from "autobot/plugin-sdk/channel-contract";
+import {
+  buildChannelConfigSchema,
+  createChatChannelPlugin,
+  type ChannelPlugin,
+} from "autobot/plugin-sdk/channel-core";
+import { defineChannelMessageAdapter } from "autobot/plugin-sdk/channel-message";
+import {
+  buildOpenGroupPolicyRestrictSendersWarning,
+  buildOpenGroupPolicyWarning,
+  createOpenProviderGroupPolicyWarningCollector,
+} from "autobot/plugin-sdk/channel-policy";
+import {
+  createEmptyChannelResult,
+  createRawChannelSendResultAdapter,
+} from "autobot/plugin-sdk/channel-send-result";
+import { buildTokenChannelStatusSummary } from "autobot/plugin-sdk/channel-status";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { createStaticReplyToModeResolver } from "autobot/plugin-sdk/conversation-runtime";
+import { createChannelDirectoryAdapter } from "autobot/plugin-sdk/directory-runtime";
+import { listResolvedDirectoryUserEntriesFromAllowFrom } from "autobot/plugin-sdk/directory-runtime";
+import { createLazyRuntimeModule } from "autobot/plugin-sdk/lazy-runtime";
+import {
+  isNumericTargetId,
+  sendPayloadWithChunkedTextAndMedia,
+} from "autobot/plugin-sdk/reply-payload";
+import {
+  createComputedAccountStatusAdapter,
+  createDefaultChannelRuntimeState,
+} from "autobot/plugin-sdk/status-helpers";
+import { chunkTextForOutbound } from "autobot/plugin-sdk/text-chunking";
+import {
+  listZaloAccountIds,
+  resolveDefaultZaloAccountId,
+  resolveZaloAccount,
+  type ResolvedZaloAccount,
+} from "./accounts.js";
+import { zaloMessageActions } from "./actions.js";
+import { zaloApprovalAuth } from "./approval-auth.js";
+import { ZaloConfigSchema } from "./config-schema.js";
+import type { ZaloProbeResult } from "./probe.js";
+import { collectRuntimeConfigAssignments, secretTargetRegistryEntries } from "./secret-contract.js";
+import { resolveZaloOutboundSessionRoute } from "./session-route.js";
+import { createZaloSetupWizardProxy, zaloSetupAdapter } from "./setup-core.js";
+import { collectZaloStatusIssues } from "./status-issues.js";
+
+const meta = {
+  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,
+};
+
+function normalizeZaloMessagingTarget(raw: string): string | undefined {
+  const trimmed = raw?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  return trimmed.replace(/^(zalo|zl):/i, "").trim();
+}
+
+const loadZaloChannelRuntime = createLazyRuntimeModule(() => import("./channel.runtime.js"));
+const zaloSetupWizard = createZaloSetupWizardProxy(
+  async () => (await import("./setup-surface.js")).zaloSetupWizard,
+);
+const zaloTextChunkLimit = 2000;
+
+const zaloRawSendResultAdapter = createRawChannelSendResultAdapter({
+  channel: "zalo",
+  sendText: async ({ to, text, accountId, cfg }) =>
+    await (
+      await loadZaloChannelRuntime()
+    ).sendZaloText({
+      to,
+      text,
+      accountId: accountId ?? undefined,
+      cfg,
+    }),
+  sendMedia: async ({ to, text, mediaUrl, accountId, cfg }) =>
+    await (
+      await loadZaloChannelRuntime()
+    ).sendZaloText({
+      to,
+      text,
+      accountId: accountId ?? undefined,
+      mediaUrl,
+      cfg,
+    }),
+});
+
+export const zaloMessageAdapter = defineChannelMessageAdapter({
+  id: "zalo",
+  durableFinal: {
+    capabilities: {
+      text: true,
+      media: true,
+      messageSendingHooks: true,
+    },
+  },
+  send: {
+    text: async ({ to, text, accountId, cfg }) =>
+      await (
+        await loadZaloChannelRuntime()
+      ).sendZaloText({
+        to,
+        text,
+        accountId: accountId ?? undefined,
+        cfg,
+      }),
+    media: async ({ to, text, mediaUrl, accountId, cfg }) =>
+      await (
+        await loadZaloChannelRuntime()
+      ).sendZaloText({
+        to,
+        text,
+        accountId: accountId ?? undefined,
+        mediaUrl,
+        cfg,
+      }),
+  },
+});
+
+const zaloConfigAdapter = createScopedChannelConfigAdapter<ResolvedZaloAccount>({
+  sectionKey: "zalo",
+  listAccountIds: listZaloAccountIds,
+  resolveAccount: adaptScopedAccountAccessor(resolveZaloAccount),
+  defaultAccountId: resolveDefaultZaloAccountId,
+  clearBaseFields: ["botToken", "tokenFile", "name"],
+  resolveAllowFrom: (account: ResolvedZaloAccount) => account.config.allowFrom,
+  formatAllowFrom: (allowFrom) =>
+    formatAllowFromLowercase({ allowFrom, stripPrefixRe: /^(zalo|zl):/i }),
+});
+
+const resolveZaloDmPolicy = createScopedDmSecurityResolver<ResolvedZaloAccount>({
+  channelKey: "zalo",
+  resolvePolicy: (account) => account.config.dmPolicy,
+  resolveAllowFrom: (account) => account.config.allowFrom,
+  policyPathSuffix: "dmPolicy",
+  normalizeEntry: (raw) => raw.trim().replace(/^(zalo|zl):/i, ""),
+});
+
+const collectZaloSecurityWarnings = createOpenProviderGroupPolicyWarningCollector<{
+  cfg: AutoBotConfig;
+  account: ResolvedZaloAccount;
+}>({
+  providerConfigPresent: (cfg) => cfg.channels?.zalo !== undefined,
+  resolveGroupPolicy: ({ account }) => account.config.groupPolicy,
+  collect: ({ account, groupPolicy }) => {
+    if (groupPolicy !== "open") {
+      return [];
+    }
+    const explicitGroupAllowFrom = mapAllowFromEntries(account.config.groupAllowFrom);
+    const dmAllowFrom = mapAllowFromEntries(account.config.allowFrom);
+    const effectiveAllowFrom =
+      explicitGroupAllowFrom.length > 0 ? explicitGroupAllowFrom : dmAllowFrom;
+    if (effectiveAllowFrom.length > 0) {
+      return [
+        buildOpenGroupPolicyRestrictSendersWarning({
+          surface: "Zalo groups",
+          openScope: "any member",
+          groupPolicyPath: "channels.zalo.groupPolicy",
+          groupAllowFromPath: "channels.zalo.groupAllowFrom",
+        }),
+      ];
+    }
+    return [
+      buildOpenGroupPolicyWarning({
+        surface: "Zalo groups",
+        openBehavior:
+          "with no groupAllowFrom/allowFrom allowlist; any member can trigger (mention-gated)",
+        remediation: 'Set channels.zalo.groupPolicy="allowlist" + channels.zalo.groupAllowFrom',
+      }),
+    ];
+  },
+});
+
+export const zaloPlugin: ChannelPlugin<ResolvedZaloAccount, ZaloProbeResult> =
+  createChatChannelPlugin({
+    base: {
+      id: "zalo",
+      meta,
+      setup: zaloSetupAdapter,
+      setupWizard: zaloSetupWizard,
+      capabilities: {
+        chatTypes: ["direct", "group"],
+        media: true,
+        reactions: false,
+        threads: false,
+        polls: false,
+        nativeCommands: false,
+        blockStreaming: true,
+      },
+      reload: { configPrefixes: ["channels.zalo"] },
+      configSchema: buildChannelConfigSchema(ZaloConfigSchema),
+      config: {
+        ...zaloConfigAdapter,
+        isConfigured: (account) => Boolean(account.token?.trim()),
+        describeAccount: (account): ChannelAccountSnapshot =>
+          describeWebhookAccountSnapshot({
+            account,
+            configured: Boolean(account.token?.trim()),
+            mode: account.config.webhookUrl ? "webhook" : "polling",
+            extra: {
+              tokenSource: account.tokenSource,
+            },
+          }),
+      },
+      approvalCapability: zaloApprovalAuth,
+      secrets: {
+        secretTargetRegistryEntries,
+        collectRuntimeConfigAssignments,
+      },
+      groups: {
+        resolveRequireMention: () => true,
+      },
+      actions: zaloMessageActions,
+      messaging: {
+        targetPrefixes: ["zalo", "zl"],
+        normalizeTarget: normalizeZaloMessagingTarget,
+        resolveOutboundSessionRoute: (params) => resolveZaloOutboundSessionRoute(params),
+        targetResolver: {
+          looksLikeId: isNumericTargetId,
+          hint: "<chatId>",
+        },
+      },
+      directory: createChannelDirectoryAdapter({
+        listPeers: async (params) =>
+          listResolvedDirectoryUserEntriesFromAllowFrom<ResolvedZaloAccount>({
+            ...params,
+            resolveAccount: adaptScopedAccountAccessor(resolveZaloAccount),
+            resolveAllowFrom: (account) => account.config.allowFrom,
+            normalizeId: (entry) => entry.trim().replace(/^(zalo|zl):/i, ""),
+          }),
+        listGroups: async () => [],
+      }),
+      status: createComputedAccountStatusAdapter<ResolvedZaloAccount, ZaloProbeResult>({
+        defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+        collectStatusIssues: collectZaloStatusIssues,
+        buildChannelSummary: ({ snapshot }) => buildTokenChannelStatusSummary(snapshot),
+        probeAccount: async ({ account, timeoutMs }) =>
+          await (await loadZaloChannelRuntime()).probeZaloAccount({ account, timeoutMs }),
+        resolveAccountSnapshot: ({ account }) => {
+          const configured = Boolean(account.token?.trim());
+          return {
+            accountId: account.accountId,
+            name: account.name,
+            enabled: account.enabled,
+            configured,
+            extra: {
+              tokenSource: account.tokenSource,
+              mode: account.config.webhookUrl ? "webhook" : "polling",
+              dmPolicy: account.config.dmPolicy ?? "pairing",
+            },
+          };
+        },
+      }),
+      gateway: {
+        startAccount: async (ctx) =>
+          await (await loadZaloChannelRuntime()).startZaloGatewayAccount(ctx),
+      },
+      message: zaloMessageAdapter,
+    },
+    security: {
+      resolveDmPolicy: resolveZaloDmPolicy,
+      collectWarnings: collectZaloSecurityWarnings,
+    },
+    pairing: {
+      text: {
+        idLabel: "zaloUserId",
+        message: "Your pairing request has been approved.",
+        normalizeAllowEntry: (entry) => entry.trim().replace(/^(zalo|zl):/i, ""),
+        notify: async (params) =>
+          await (await loadZaloChannelRuntime()).notifyZaloPairingApproval(params),
+      },
+    },
+    threading: {
+      resolveReplyToMode: createStaticReplyToModeResolver("off"),
+    },
+    outbound: {
+      deliveryMode: "direct",
+      chunker: chunkTextForOutbound,
+      chunkerMode: "text",
+      textChunkLimit: zaloTextChunkLimit,
+      sendPayload: async (ctx) =>
+        await sendPayloadWithChunkedTextAndMedia({
+          ctx,
+          textChunkLimit: zaloTextChunkLimit,
+          chunker: chunkTextForOutbound,
+          sendText: (nextCtx) => zaloRawSendResultAdapter.sendText!(nextCtx),
+          sendMedia: (nextCtx) => zaloRawSendResultAdapter.sendMedia!(nextCtx),
+          emptyResult: createEmptyChannelResult("zalo"),
+        }),
+      ...zaloRawSendResultAdapter,
+    },
+  });

package/src/config-schema.ts

@@ -0,0 +1,29 @@
+import {
+  AllowFromListSchema,
+  buildCatchallMultiAccountChannelSchema,
+  DmPolicySchema,
+  GroupPolicySchema,
+  MarkdownConfigSchema,
+} from "autobot/plugin-sdk/channel-config-schema";
+import { z } from "zod";
+import { buildSecretInputSchema } from "./secret-input.js";
+
+const zaloAccountSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  markdown: MarkdownConfigSchema,
+  botToken: buildSecretInputSchema().optional(),
+  tokenFile: z.string().optional(),
+  webhookUrl: z.string().optional(),
+  webhookSecret: buildSecretInputSchema().optional(),
+  webhookPath: z.string().optional(),
+  dmPolicy: DmPolicySchema.optional(),
+  allowFrom: AllowFromListSchema,
+  groupPolicy: GroupPolicySchema.optional(),
+  groupAllowFrom: AllowFromListSchema,
+  mediaMaxMb: z.number().optional(),
+  proxy: z.string().optional(),
+  responsePrefix: z.string().optional(),
+});
+
+export const ZaloConfigSchema = buildCatchallMultiAccountChannelSchema(zaloAccountSchema);

package/src/group-access.ts

@@ -0,0 +1,23 @@
+import type { GroupPolicy } from "autobot/plugin-sdk/config-contracts";
+import { resolveOpenProviderRuntimeGroupPolicy } from "autobot/plugin-sdk/runtime-group-policy";
+
+const ZALO_ALLOW_FROM_PREFIX_RE = /^(zalo|zl):/i;
+
+export function normalizeZaloAllowEntry(value: string): string {
+  return value.trim().replace(ZALO_ALLOW_FROM_PREFIX_RE, "").trim().toLowerCase();
+}
+
+export function resolveZaloRuntimeGroupPolicy(params: {
+  providerConfigPresent: boolean;
+  groupPolicy?: GroupPolicy;
+  defaultGroupPolicy?: GroupPolicy;
+}): {
+  groupPolicy: GroupPolicy;
+  providerMissingFallbackApplied: boolean;
+} {
+  return resolveOpenProviderRuntimeGroupPolicy({
+    providerConfigPresent: params.providerConfigPresent,
+    groupPolicy: params.groupPolicy,
+    defaultGroupPolicy: params.defaultGroupPolicy,
+  });
+}

package/src/monitor-durable.ts

@@ -0,0 +1,38 @@
+import type { MarkdownTableMode } from "autobot/plugin-sdk/config-contracts";
+import { resolveSendableOutboundReplyParts } from "autobot/plugin-sdk/reply-payload";
+import type { OutboundReplyPayload } from "autobot/plugin-sdk/reply-payload";
+
+export type ZaloDurableReplyOptions = {
+  to: string;
+};
+
+export function prepareZaloDurableReplyPayload(params: {
+  payload: OutboundReplyPayload;
+  tableMode: MarkdownTableMode;
+  convertMarkdownTables: (text: string, tableMode: MarkdownTableMode) => string;
+}): OutboundReplyPayload {
+  if (!params.payload.text) {
+    return params.payload;
+  }
+  return {
+    ...params.payload,
+    text: params.convertMarkdownTables(params.payload.text, params.tableMode),
+  };
+}
+
+export function resolveZaloDurableReplyOptions(params: {
+  payload: OutboundReplyPayload;
+  infoKind: string;
+  chatId: string;
+}): ZaloDurableReplyOptions | false {
+  if (params.infoKind !== "final") {
+    return false;
+  }
+  const reply = resolveSendableOutboundReplyParts(params.payload);
+  if (reply.hasMedia || !reply.hasText) {
+    return false;
+  }
+  return {
+    to: params.chatId,
+  };
+}