@nubemclaw/channel-telegram 1.2.2

package/src/channel.test.ts

@@ -0,0 +1,287 @@
+import type {
+  ChannelDeps,
+  ChannelInboundEvent,
+  ChannelLogger,
+  ChannelStateStore,
+} from "@nubemclaw/channel-sdk";
+import { Bot } from "grammy";
+import { describe, expect, it, vi } from "vitest";
+
+import { createTelegramChannel } from "./channel.js";
+
+/**
+ * The channel-level tests focus on the **inbound normalization** —
+ * allowlist drops, non-private chats, missing text, etc. The grammy
+ * Bot itself is exercised by grammy's own tests; we only need to feed
+ * a constructed update into our handler and verify what reaches
+ * `onInbound`. The `botFactory` seam lets us swap in a fake Bot that
+ * exposes `.on("message", handler)` so we can drive updates directly.
+ *
+ * The polling/webhook lifecycle (`start`, `stop`, `webhookRegistration`)
+ * is covered by the live test (#150). Unit-testing grammy's polling
+ * loop here would just reimplement grammy's own tests.
+ */
+
+const silentLogger: ChannelLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+};
+
+const stubState: ChannelStateStore = {
+  async get() {
+    return undefined;
+  },
+  async set() {},
+  async delete() {},
+};
+
+interface BotStub {
+  readonly api: {
+    config: { use: ReturnType<typeof vi.fn> };
+    sendMessage: ReturnType<typeof vi.fn>;
+    setWebhook: ReturnType<typeof vi.fn>;
+    deleteWebhook: ReturnType<typeof vi.fn>;
+  };
+  messageHandler: ((ctx: unknown) => Promise<void>) | null;
+  on(event: string, handler: (ctx: unknown) => Promise<void>): void;
+  start: ReturnType<typeof vi.fn>;
+  stop: ReturnType<typeof vi.fn>;
+}
+
+const makeBotStub = (): BotStub => {
+  const stub: BotStub = {
+    api: {
+      config: { use: vi.fn() },
+      sendMessage: vi.fn(async () => ({})),
+      setWebhook: vi.fn(async () => true),
+      deleteWebhook: vi.fn(async () => true),
+    },
+    messageHandler: null,
+    on(event, handler) {
+      if (event === "message") stub.messageHandler = handler;
+    },
+    start: vi.fn(async () => {}),
+    stop: vi.fn(async () => {}),
+  };
+  return stub;
+};
+
+const fakeBotFactory = (stub: BotStub) =>
+  ((_token: string, _fetcher: typeof globalThis.fetch | undefined) => stub) as unknown as (
+    token: string,
+    fetcher: typeof globalThis.fetch | undefined,
+  ) => Bot;
+
+const baseConfig = {
+  allowedUsers: ["100"],
+  mode: "polling" as const,
+  polling: { timeoutSec: 50 },
+};
+
+describe("TelegramChannel inbound normalization", () => {
+  const setup = async (): Promise<{
+    stub: BotStub;
+    received: ChannelInboundEvent[];
+    feedMessage: (update: unknown) => Promise<void>;
+  }> => {
+    const stub = makeBotStub();
+    const received: ChannelInboundEvent[] = [];
+    const deps: ChannelDeps = {
+      logger: silentLogger,
+      state: stubState,
+      allowlist: { allows: () => true, size: 0 }, // unused — channel uses its own allowlist
+      onInbound: async (event) => {
+        received.push(event);
+      },
+    };
+    const channel = createTelegramChannel({
+      token: "x:y",
+      config: baseConfig,
+      botFactory: fakeBotFactory(stub),
+    });
+    await channel.init(deps);
+    if (stub.messageHandler === null) {
+      throw new Error("channel never registered a message handler");
+    }
+    const handler = stub.messageHandler;
+    return {
+      stub,
+      received,
+      feedMessage: async (update: unknown) => {
+        await handler({ update });
+      },
+    };
+  };
+
+  const buildUpdate = (overrides: Record<string, unknown> = {}): unknown => ({
+    update_id: 1,
+    message: {
+      message_id: 1,
+      date: 1,
+      chat: { id: 999, type: "private" },
+      from: { id: 100, is_bot: false, username: "alice" },
+      text: "hello",
+      ...overrides,
+    },
+  });
+
+  it("delivers a private-chat text message from an allowlisted sender", async () => {
+    const { received, feedMessage } = await setup();
+    await feedMessage(buildUpdate());
+    expect(received).toHaveLength(1);
+    expect(received[0]).toMatchObject({
+      channel: "telegram",
+      target: { kind: "chat", id: "999" },
+      sender: { externalId: "100", displayName: "alice" },
+      content: { type: "text", text: "hello" },
+    });
+  });
+
+  it("drops messages from non-allowlisted senders silently", async () => {
+    const { received, feedMessage } = await setup();
+    await feedMessage(buildUpdate({ from: { id: 200, is_bot: false, username: "mallory" } }));
+    expect(received).toEqual([]);
+  });
+
+  it("drops messages from group chats (chat.type !== 'private') silently", async () => {
+    const { received, feedMessage } = await setup();
+    await feedMessage(
+      buildUpdate({
+        chat: { id: -1001, type: "supergroup", title: "Team" },
+      }),
+    );
+    expect(received).toEqual([]);
+  });
+
+  it("drops messages without `text` silently", async () => {
+    const { received, feedMessage } = await setup();
+    const update = buildUpdate();
+    const msg = (update as { message: Record<string, unknown> }).message;
+    delete msg["text"];
+    await feedMessage(update);
+    expect(received).toEqual([]);
+  });
+
+  it("drops schema-invalid updates silently (does not crash the handler)", async () => {
+    const { received, feedMessage } = await setup();
+    // Garbage shape — should be parsed by zod and rejected.
+    await feedMessage({ not_an_update: true });
+    expect(received).toEqual([]);
+  });
+});
+
+describe("TelegramChannel apiThrottler integration", () => {
+  it("composes apiThrottler on bot.api.config during init (rate-limit applied transparently)", async () => {
+    const stub = makeBotStub();
+    const deps: ChannelDeps = {
+      logger: silentLogger,
+      state: stubState,
+      allowlist: { allows: () => true, size: 0 },
+      onInbound: async () => {},
+    };
+    const channel = createTelegramChannel({
+      token: "x:y",
+      config: baseConfig,
+      botFactory: fakeBotFactory(stub),
+    });
+    await channel.init(deps);
+    expect(stub.api.config.use).toHaveBeenCalledOnce();
+  });
+});
+
+describe("TelegramChannel send", () => {
+  it("forwards to bot.api.sendMessage with the parsed chat id", async () => {
+    const stub = makeBotStub();
+    const deps: ChannelDeps = {
+      logger: silentLogger,
+      state: stubState,
+      allowlist: { allows: () => true, size: 0 },
+      onInbound: async () => {},
+    };
+    const channel = createTelegramChannel({
+      token: "x:y",
+      config: baseConfig,
+      botFactory: fakeBotFactory(stub),
+    });
+    await channel.init(deps);
+    await channel.send({ kind: "chat", id: "42" }, { type: "text", text: "hello" });
+    expect(stub.api.sendMessage).toHaveBeenCalledWith(42, "hello");
+  });
+
+  it("rejects non-numeric chat id with a clear error", async () => {
+    const stub = makeBotStub();
+    const deps: ChannelDeps = {
+      logger: silentLogger,
+      state: stubState,
+      allowlist: { allows: () => true, size: 0 },
+      onInbound: async () => {},
+    };
+    const channel = createTelegramChannel({
+      token: "x:y",
+      config: baseConfig,
+      botFactory: fakeBotFactory(stub),
+    });
+    await channel.init(deps);
+    await expect(
+      channel.send({ kind: "chat", id: "not-a-number" }, { type: "text", text: "x" }),
+    ).rejects.toThrow(/invalid chat id/);
+  });
+});
+
+describe("TelegramChannel webhook mode", () => {
+  it("returns a WebhookRegistration that verifies the secret token header", async () => {
+    const stub = makeBotStub();
+    const deps: ChannelDeps = {
+      logger: silentLogger,
+      state: stubState,
+      allowlist: { allows: () => true, size: 0 },
+      onInbound: async () => {},
+    };
+    const channel = createTelegramChannel({
+      token: "x:y",
+      config: {
+        ...baseConfig,
+        mode: "webhook",
+        webhook: { publicUrl: "https://example.test/wh", secretToken: "s3cr3t" },
+      },
+      botFactory: fakeBotFactory(stub),
+    });
+    await channel.init(deps);
+    const reg = channel.webhookRegistration?.();
+    expect(reg).toBeDefined();
+    expect(reg?.path).toBe("/v1/channels/telegram/webhook");
+
+    // Wrong secret → 401.
+    const bad = await reg?.process({
+      headers: { "x-telegram-bot-api-secret-token": "wrong" },
+      rawBody: Buffer.from("{}", "utf8"),
+    });
+    expect(bad?.status).toBe(401);
+
+    // Right secret → 200.
+    const good = await reg?.process({
+      headers: { "x-telegram-bot-api-secret-token": "s3cr3t" },
+      rawBody: Buffer.from("{}", "utf8"),
+    });
+    expect(good?.status).toBe(200);
+  });
+
+  it("polling mode returns no webhook registration", async () => {
+    const stub = makeBotStub();
+    const deps: ChannelDeps = {
+      logger: silentLogger,
+      state: stubState,
+      allowlist: { allows: () => true, size: 0 },
+      onInbound: async () => {},
+    };
+    const channel = createTelegramChannel({
+      token: "x:y",
+      config: baseConfig, // polling
+      botFactory: fakeBotFactory(stub),
+    });
+    await channel.init(deps);
+    expect(channel.webhookRegistration?.()).toBeUndefined();
+  });
+});

package/src/channel.ts

@@ -0,0 +1,345 @@
+import { apiThrottler } from "@grammyjs/transformer-throttler";
+import {
+  createAllowlist,
+  createWebhookTransport,
+  webhookVerifyOk,
+  type Channel,
+  type ChannelCapabilities,
+  type ChannelDeps,
+  type ChannelInboundEvent,
+  type ChannelMessage,
+  type ChannelTarget,
+  type WebhookInbound,
+  type WebhookRegistration,
+} from "@nubemclaw/channel-sdk";
+import { err, nubemClawError } from "@nubemclaw/core";
+import { Bot, type Context } from "grammy";
+
+import { TelegramUpdateSchema, type TelegramUpdate } from "./api/schemas.js";
+import type { TelegramChannelConfig } from "./config.js";
+import { createTelegramTransport, type TelegramTransport } from "./transport.js";
+
+/**
+ * Telegram channel implementation (Phase 13, ADR-0020 §1 — library
+ * route). Wraps **grammy** for the Bot API + long-polling loop, and
+ * `@grammyjs/transformer-throttler` for outbound rate-limit. The
+ * channel does NOT use the SDK's `PollingTransport` because grammy
+ * already owns the polling lifecycle (via `bot.start()`).
+ *
+ * Precedent: OpenClaw `extensions/telegram/` uses the same stack
+ * (`grammy@1.42.0` + `@grammyjs/transformer-throttler@1.2.1`); pinned
+ * to the same versions to share the upstream rodaje. Patterns adapted
+ * from OpenClaw `bot.runtime.ts:1-4` and `account-throttler.ts:1-21`.
+ *
+ * Three behaviours the channel guarantees (unchanged from the original
+ * raw implementation):
+ *
+ *   1. **Inbound is private-chat, text-only, allowlisted.** Updates
+ *      from groups (chat.type !== "private"), media-only messages
+ *      (no `text`), or senders not in `allowedUsers` are silently
+ *      dropped with a debug log. F13's scope (ADR-0020 §8) is
+ *      private-chat text; any other shape just doesn't reach the
+ *      agent loop. Telegram receives `allowed_updates: ["message"]`
+ *      so non-message updates never reach us in the first place.
+ *
+ *   2. **Outbound respects Telegram rate limits via apiThrottler.**
+ *      `@grammyjs/transformer-throttler` is installed on the bot's
+ *      api config — it honors the `retry_after` Telegram returns on
+ *      429 automatically (no manual bucket needed; OpenClaw's
+ *      `account-throttler.ts` confirms this pattern).
+ *
+ *   3. **Mode transition is clean.** Polling mode calls
+ *      `bot.api.deleteWebhook()` on start (Telegram rejects with 409
+ *      if `getUpdates` runs while a webhook is registered). Webhook
+ *      mode calls `bot.api.setWebhook(...)` with the secret token we
+ *      verify against.
+ */
+
+export interface CreateTelegramChannelOptions {
+  readonly token: string;
+  readonly config: TelegramChannelConfig;
+  /**
+   * Test seam: override the Bot constructor (the tests substitute a
+   * thin fake that records calls and serves canned `getMe` /
+   * `getUpdates` responses). Default is grammy's `Bot` configured
+   * with the operational transport (see `createTelegramTransport`).
+   */
+  readonly botFactory?: (token: string, fetcher: typeof globalThis.fetch | undefined) => Bot;
+  /**
+   * Test seam: override the operational transport. Tests pass
+   * `undefined` to let grammy use its default `globalThis.fetch`
+   * (which under Vitest's environment is fine — production paths get
+   * the hardened transport).
+   */
+  readonly transport?: TelegramTransport | null;
+}
+
+const CHANNEL_ID = "telegram" as const;
+const ALLOWED_UPDATES = ["message"] as const;
+
+const CAPABILITIES: ChannelCapabilities = {
+  transports: ["polling", "webhook"],
+  mediaTypes: ["text"],
+  supportsGroups: false,
+  rateLimits: {
+    // apiThrottler honors Telegram's documented limits + retry_after
+    // automatically — these values stay in capabilities for operator
+    // visibility, not for enforcement.
+    globalPerSec: 30,
+    perTargetPerMin: 20,
+  },
+};
+
+export const createTelegramChannel = (opts: CreateTelegramChannelOptions): Channel => {
+  let deps: ChannelDeps | null = null;
+  let bot: Bot | null = null;
+  let pollingPromise: Promise<void> | null = null;
+  let webhookReg: WebhookRegistration | null = null;
+  // The operational transport owns its undici Agents; the channel
+  // owns this reference so `stop()` can release dispatchers cleanly.
+  let ownedTransport: TelegramTransport | null = null;
+  const allowlist = createAllowlist(opts.config.allowedUsers);
+
+  const requireDeps = (): ChannelDeps => {
+    if (deps === null) throw new Error("telegram channel: not initialized — call init() first");
+    return deps;
+  };
+  const requireBot = (): Bot => {
+    if (bot === null) throw new Error("telegram channel: not initialized — call init() first");
+    return bot;
+  };
+
+  /**
+   * Normalize a grammy `Context` (or a raw `TelegramUpdate` from the
+   * webhook path) into the SDK's `ChannelInboundEvent`. Returns
+   * `undefined` for any update F13 intentionally ignores. The caller
+   * logs the drop reason at debug level — no user-facing log at info
+   * because a chatty rejected user would spam the logs.
+   */
+  const normalize = (
+    update: TelegramUpdate,
+    receivedAt: string,
+  ): ChannelInboundEvent | undefined => {
+    const msg = update.message;
+    if (msg === undefined) return undefined;
+    if (msg.chat.type !== "private") {
+      requireDeps().logger.debug(
+        { channel: CHANNEL_ID, chatType: msg.chat.type },
+        "telegram inbound from non-private chat — dropping",
+      );
+      return undefined;
+    }
+    if (msg.text === undefined || msg.text === "") return undefined;
+    const sender = msg.from;
+    if (sender === undefined) return undefined;
+    const externalId = String(sender.id);
+    if (!allowlist.allows(externalId)) {
+      requireDeps().logger.info(
+        { channel: CHANNEL_ID },
+        "telegram inbound from non-allowed user rejected",
+      );
+      return undefined;
+    }
+    return {
+      channel: CHANNEL_ID,
+      target: { kind: "chat", id: String(msg.chat.id) },
+      sender: {
+        externalId,
+        ...(sender.username !== undefined ? { displayName: sender.username } : {}),
+      },
+      content: { type: "text", text: msg.text },
+      receivedAt,
+      raw: update,
+    };
+  };
+
+  const dispatchUpdate = async (update: TelegramUpdate): Promise<void> => {
+    const event = normalize(update, new Date().toISOString());
+    if (event === undefined) return;
+    await requireDeps().onInbound(event);
+  };
+
+  return {
+    id: CHANNEL_ID,
+    capabilities: CAPABILITIES,
+
+    async init(d) {
+      deps = d;
+      // Operational transport: opts.transport === undefined → build
+      // the hardened default (undici Agent + allowH2:false + bounded
+      // pool + IPv4 fallback + proxy support). opts.transport === null
+      // → caller explicitly disables it (tests letting grammy use the
+      // global fetch). Either way, the result is the fetcher passed
+      // to grammy's `Bot` constructor.
+      if (opts.transport !== null) {
+        ownedTransport = opts.transport ?? createTelegramTransport({ logger: d.logger });
+      }
+      const fetcher = ownedTransport?.fetch;
+      const factory =
+        opts.botFactory ??
+        ((token: string, f: typeof globalThis.fetch | undefined) =>
+          f !== undefined ? new Bot(token, { client: { fetch: f as never } }) : new Bot(token));
+      bot = factory(opts.token, fetcher);
+      // Compose the throttler transformer on the api so every outbound
+      // call (sendMessage, deleteWebhook, setWebhook, etc.) is rate-
+      // limited and respects Telegram's retry_after automatically.
+      // Pattern adopted from OpenClaw `account-throttler.ts`.
+      bot.api.config.use(apiThrottler());
+
+      // Inbound handler — grammy invokes this for every text message
+      // matching `allowed_updates`. We bridge to our normalizer +
+      // onInbound callback. The grammy update shape is structurally
+      // compatible with our zod-validated `TelegramUpdate`, so we
+      // safeParse to keep the boundary explicit.
+      bot.on("message", async (ctx: Context) => {
+        const parsed = TelegramUpdateSchema.safeParse(ctx.update);
+        if (!parsed.success) {
+          d.logger.warn(
+            { channel: CHANNEL_ID, issues: parsed.error.issues },
+            "telegram polled update failed schema validation — dropping",
+          );
+          return;
+        }
+        await dispatchUpdate(parsed.data);
+      });
+
+      if (opts.config.mode === "webhook") {
+        const secretToken = opts.config.webhook?.secretToken ?? "";
+        webhookReg = createWebhookTransport({
+          channel: CHANNEL_ID,
+          logger: d.logger,
+          verify: async (req: WebhookInbound) => {
+            const header = req.headers["x-telegram-bot-api-secret-token"];
+            const provided = Array.isArray(header) ? header[0] : header;
+            if (provided !== secretToken) {
+              return err(
+                nubemClawError({
+                  code: "auth.unauthorized",
+                  message: "telegram webhook secret token mismatch",
+                }),
+              );
+            }
+            return webhookVerifyOk();
+          },
+          handle: async (body: unknown) => {
+            const parsed = TelegramUpdateSchema.safeParse(body);
+            if (!parsed.success) {
+              d.logger.warn(
+                { channel: CHANNEL_ID, issues: parsed.error.issues },
+                "telegram webhook body failed schema validation — dropping",
+              );
+              return;
+            }
+            await dispatchUpdate(parsed.data);
+          },
+        });
+      }
+    },
+
+    async start() {
+      const b = requireBot();
+      const d = requireDeps();
+      if (opts.config.mode === "polling") {
+        // Drop any registered webhook so getUpdates does not 409.
+        try {
+          await b.api.deleteWebhook({ drop_pending_updates: false });
+        } catch (err) {
+          d.logger.warn(
+            { channel: CHANNEL_ID, err },
+            "telegram: deleteWebhook on start failed (continuing into polling anyway)",
+          );
+        }
+        // `bot.start()` is the polling loop — the returned promise
+        // resolves when the loop terminates cleanly (someone called
+        // `bot.stop()`) and rejects if it dies mid-flight (network
+        // drop persisting beyond grammy's internal retries, bot
+        // kicked, persistent 5xx). The channel propagates this
+        // promise upward so the `ChannelManager` can tap it via
+        // `.then/.catch/.finally` and trigger restart on mid-flight
+        // failure. See `Channel.start()` contract in
+        // `@nubemclaw/channel-sdk/types.ts`.
+        pollingPromise = b.start({
+          allowed_updates: [...ALLOWED_UPDATES],
+          onStart: (info) => {
+            d.logger.info(
+              { channel: CHANNEL_ID, botUsername: info.username },
+              "telegram polling started",
+            );
+          },
+        });
+        // Return the polling promise so the manager observes the full
+        // lifecycle. `stop()` calls `bot.stop()` which resolves this
+        // promise cleanly; `bot.stop()` is idempotent so the local
+        // `pollingPromise` reference is retained but not re-awaited.
+        return pollingPromise;
+      } else {
+        const webhookCfg = opts.config.webhook;
+        if (webhookCfg === undefined) {
+          throw new Error("telegram channel: webhook mode requires webhook config");
+        }
+        await b.api.setWebhook(webhookCfg.publicUrl, {
+          secret_token: webhookCfg.secretToken,
+          allowed_updates: [...ALLOWED_UPDATES],
+          drop_pending_updates: false,
+        });
+      }
+    },
+
+    async stop() {
+      if (bot === null) return;
+      // grammy.Bot.stop() unblocks an in-flight getUpdates and lets
+      // bot.start() resolve cleanly. Safe to call when no polling
+      // session is active — it's a no-op then.
+      try {
+        await bot.stop();
+      } catch (e) {
+        requireDeps().logger.warn(
+          { channel: CHANNEL_ID, err: e },
+          "telegram bot.stop() raised (continuing teardown)",
+        );
+      }
+      if (pollingPromise !== null) {
+        try {
+          await pollingPromise;
+        } catch {
+          // bot.start() rejects when stop interrupts it; swallow.
+        }
+        pollingPromise = null;
+      }
+      // Release the undici dispatchers owned by the operational
+      // transport. Without this, keep-alive sockets to
+      // api.telegram.org stay open indefinitely (the openclaw#68128
+      // failure mode the transport hardening was originally written
+      // to fix). Idempotent — safe to call when there's no transport.
+      if (ownedTransport !== null) {
+        await ownedTransport.close();
+        ownedTransport = null;
+      }
+      // Webhook mode: we deliberately do NOT call deleteWebhook on
+      // stop because the operator may run a short-lived process
+      // (deploy, restart) and dropping the webhook each cycle would
+      // make Telegram drop in-flight events.
+    },
+
+    async send(target: ChannelTarget, message: ChannelMessage): Promise<void> {
+      if (target.kind !== "chat") {
+        throw new Error(`telegram channel: unsupported target kind '${target.kind}'`);
+      }
+      if (message.type !== "text") {
+        throw new Error(`telegram channel: unsupported message type '${message.type}'`);
+      }
+      const chatId = Number.parseInt(target.id, 10);
+      if (!Number.isFinite(chatId)) {
+        throw new Error(`telegram channel: invalid chat id '${target.id}'`);
+      }
+      // apiThrottler is composed on bot.api.config — sendMessage goes
+      // through it automatically and honors Telegram's retry_after on
+      // 429 without manual bucket management.
+      await requireBot().api.sendMessage(chatId, message.text);
+    },
+
+    webhookRegistration() {
+      return webhookReg ?? undefined;
+    },
+  };
+};

package/src/config.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+/**
+ * Per-channel config schema for Telegram (Phase 13, ADR-0020 §7
+ * identity + allowlist).
+ *
+ *   • `allowedUsers` — exact-match deny-default allowlist of
+ *     `telegram_user_id` values (as strings — Telegram IDs are numbers
+ *     but config files round-trip JSON cleanly with strings, and the
+ *     SDK `createAllowlist` expects strings anyway).
+ *   • `mode`         — polling or webhook. ADR-0020 §1 keeps polling
+ *     as the default because it works behind NAT without a public URL;
+ *     the operator opts into webhook by setting `mode: "webhook"` and
+ *     supplying `webhook.publicUrl` + `webhook.secretToken`.
+ *   • `polling.timeoutSec` — Telegram `getUpdates(timeout=N)` long-poll
+ *     duration. Default 50 (Telegram's recommended ceiling is 50).
+ *
+ * `.strict()` so a typo (`allowedUSers`) fails loud at boot.
+ */
+
+export const TelegramPollingConfigSchema = z
+  .object({
+    timeoutSec: z.number().int().min(1).max(50).default(50),
+  })
+  .strict();
+export type TelegramPollingConfig = z.infer<typeof TelegramPollingConfigSchema>;
+
+export const TelegramWebhookConfigSchema = z
+  .object({
+    publicUrl: z.string().url(),
+    secretToken: z.string().min(1).max(256),
+  })
+  .strict();
+export type TelegramWebhookConfig = z.infer<typeof TelegramWebhookConfigSchema>;
+
+export const TelegramChannelConfigSchema = z
+  .object({
+    allowedUsers: z.array(z.string().min(1)).default([]),
+    mode: z.enum(["polling", "webhook"]).default("polling"),
+    polling: TelegramPollingConfigSchema.default({ timeoutSec: 50 }),
+    webhook: TelegramWebhookConfigSchema.optional(),
+  })
+  .strict()
+  .superRefine((cfg, ctx) => {
+    if (cfg.mode === "webhook" && cfg.webhook === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["webhook"],
+        message: "webhook config is required when mode is 'webhook'",
+      });
+    }
+  });
+export type TelegramChannelConfig = z.infer<typeof TelegramChannelConfigSchema>;

package/src/index.ts

@@ -0,0 +1,10 @@
+import pkg from "../package.json" with { type: "json" };
+
+export const PACKAGE_NAME = "@nubemclaw/channel-telegram" as const;
+export const PACKAGE_VERSION: string = pkg.version;
+
+export * from "./api/schemas.js";
+export * from "./channel.js";
+export * from "./config.js";
+export * from "./setup.js";
+export * from "./transport.js";