@nubemclaw/channel-telegram 1.2.2

package/dist/channel.d.ts

@@ -0,0 +1,59 @@
+import { type Channel } from "@nubemclaw/channel-sdk";
+import { Bot } from "grammy";
+import type { TelegramChannelConfig } from "./config.js";
+import { 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;
+}
+export declare const createTelegramChannel: (opts: CreateTelegramChannelOptions) => Channel;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,OAAO,EAQb,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,GAAG,EAAgB,MAAM,QAAQ,CAAC;AAG3C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,UAAU,CAAC,KAAK,GAAG,SAAS,KAAK,GAAG,CAAC;IAC3F;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAC/C;AAkBD,eAAO,MAAM,qBAAqB,GAAI,MAAM,4BAA4B,KAAG,OA4P1E,CAAC"}

package/dist/channel.js

@@ -0,0 +1,246 @@
+import { apiThrottler } from "@grammyjs/transformer-throttler";
+import { createAllowlist, createWebhookTransport, webhookVerifyOk, } from "@nubemclaw/channel-sdk";
+import { err, nubemClawError } from "@nubemclaw/core";
+import { Bot } from "grammy";
+import { TelegramUpdateSchema } from "./api/schemas.js";
+import { createTelegramTransport } from "./transport.js";
+const CHANNEL_ID = "telegram";
+const ALLOWED_UPDATES = ["message"];
+const CAPABILITIES = {
+    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) => {
+    let deps = null;
+    let bot = null;
+    let pollingPromise = null;
+    let webhookReg = null;
+    // The operational transport owns its undici Agents; the channel
+    // owns this reference so `stop()` can release dispatchers cleanly.
+    let ownedTransport = null;
+    const allowlist = createAllowlist(opts.config.allowedUsers);
+    const requireDeps = () => {
+        if (deps === null)
+            throw new Error("telegram channel: not initialized — call init() first");
+        return deps;
+    };
+    const requireBot = () => {
+        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, receivedAt) => {
+        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) => {
+        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, f) => f !== undefined ? new Bot(token, { client: { fetch: f } }) : 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) => {
+                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) => {
+                        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) => {
+                        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, message) {
+            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;
+        },
+    };
+};
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,100 @@
+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 declare const TelegramPollingConfigSchema: z.ZodObject<{
+    timeoutSec: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    timeoutSec: number;
+}, {
+    timeoutSec?: number | undefined;
+}>;
+export type TelegramPollingConfig = z.infer<typeof TelegramPollingConfigSchema>;
+export declare const TelegramWebhookConfigSchema: z.ZodObject<{
+    publicUrl: z.ZodString;
+    secretToken: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    publicUrl: string;
+    secretToken: string;
+}, {
+    publicUrl: string;
+    secretToken: string;
+}>;
+export type TelegramWebhookConfig = z.infer<typeof TelegramWebhookConfigSchema>;
+export declare const TelegramChannelConfigSchema: z.ZodEffects<z.ZodObject<{
+    allowedUsers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    mode: z.ZodDefault<z.ZodEnum<["polling", "webhook"]>>;
+    polling: z.ZodDefault<z.ZodObject<{
+        timeoutSec: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        timeoutSec: number;
+    }, {
+        timeoutSec?: number | undefined;
+    }>>;
+    webhook: z.ZodOptional<z.ZodObject<{
+        publicUrl: z.ZodString;
+        secretToken: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        publicUrl: string;
+        secretToken: string;
+    }, {
+        publicUrl: string;
+        secretToken: string;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    allowedUsers: string[];
+    polling: {
+        timeoutSec: number;
+    };
+    mode: "polling" | "webhook";
+    webhook?: {
+        publicUrl: string;
+        secretToken: string;
+    } | undefined;
+}, {
+    allowedUsers?: string[] | undefined;
+    polling?: {
+        timeoutSec?: number | undefined;
+    } | undefined;
+    webhook?: {
+        publicUrl: string;
+        secretToken: string;
+    } | undefined;
+    mode?: "polling" | "webhook" | undefined;
+}>, {
+    allowedUsers: string[];
+    polling: {
+        timeoutSec: number;
+    };
+    mode: "polling" | "webhook";
+    webhook?: {
+        publicUrl: string;
+        secretToken: string;
+    } | undefined;
+}, {
+    allowedUsers?: string[] | undefined;
+    polling?: {
+        timeoutSec?: number | undefined;
+    } | undefined;
+    webhook?: {
+        publicUrl: string;
+        secretToken: string;
+    } | undefined;
+    mode?: "polling" | "webhook" | undefined;
+}>;
+export type TelegramChannelConfig = z.infer<typeof TelegramChannelConfigSchema>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,2BAA2B;;;;;;EAI7B,CAAC;AACZ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,2BAA2B;;;;;;;;;EAK7B,CAAC;AACZ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBpC,CAAC;AACL,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

package/dist/config.js

@@ -0,0 +1,47 @@
+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 const TelegramWebhookConfigSchema = z
+    .object({
+    publicUrl: z.string().url(),
+    secretToken: z.string().min(1).max(256),
+})
+    .strict();
+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'",
+        });
+    }
+});
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC;KACzC,MAAM,CAAC;IACN,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACxD,CAAC;KACD,MAAM,EAAE,CAAC;AAGZ,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC;KACzC,MAAM,CAAC;IACN,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC3B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;CACxC,CAAC;KACD,MAAM,EAAE,CAAC;AAGZ,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC;KACzC,MAAM,CAAC;IACN,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACpD,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACvD,OAAO,EAAE,2BAA2B,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAChE,OAAO,EAAE,2BAA2B,CAAC,QAAQ,EAAE;CAChD,CAAC;KACD,MAAM,EAAE;KACR,WAAW,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IACxB,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACxD,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;YAC3B,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,OAAO,EAAE,mDAAmD;SAC7D,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export declare const PACKAGE_NAME: "@nubemclaw/channel-telegram";
+export declare const PACKAGE_VERSION: string;
+export * from "./api/schemas.js";
+export * from "./channel.js";
+export * from "./config.js";
+export * from "./setup.js";
+export * from "./transport.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,EAAG,6BAAsC,CAAC;AACnE,eAAO,MAAM,eAAe,EAAE,MAAoB,CAAC;AAEnD,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

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

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAExD,MAAM,CAAC,MAAM,YAAY,GAAG,6BAAsC,CAAC;AACnE,MAAM,CAAC,MAAM,eAAe,GAAW,GAAG,CAAC,OAAO,CAAC;AAEnD,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/setup.d.ts

@@ -0,0 +1,24 @@
+import { type ChannelLogger, type ChannelSetup } from "@nubemclaw/channel-sdk";
+import { Bot } from "grammy";
+import { z } from "zod";
+export declare const TelegramCredentialsSchema: z.ZodObject<{
+    botToken: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    botToken: string;
+}, {
+    botToken: string;
+}>;
+export type TelegramCredentials = z.infer<typeof TelegramCredentialsSchema>;
+export interface CreateTelegramSetupOptions {
+    readonly logger: ChannelLogger;
+    /**
+     * Test seam: override the Bot constructor. Production callers
+     * always use grammy's `Bot`; tests inject a fake whose `api.getMe()`
+     * is scriptable.
+     */
+    readonly botFactory?: (token: string) => Pick<Bot, "api">;
+    /** Test seam: override env vars for credential path resolution. */
+    readonly envVars?: NodeJS.ProcessEnv;
+}
+export declare const createTelegramSetup: (opts: CreateTelegramSetupOptions) => ChannelSetup<TelegramCredentials>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,GAAG,EAA0B,MAAM,QAAQ,CAAC;AACrD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmCxB,eAAO,MAAM,yBAAyB;;;;;;EAM3B,CAAC;AACZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1D,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACtC;AAED,eAAO,MAAM,mBAAmB,GAC9B,MAAM,0BAA0B,KAC/B,YAAY,CAAC,mBAAmB,CAuEjC,CAAC"}

package/dist/setup.js

@@ -0,0 +1,104 @@
+import { err, nubemClawError, ok } from "@nubemclaw/core";
+import { resolveCredentialPaths, writeChannelCredential, } from "@nubemclaw/channel-sdk";
+import { Bot, GrammyError, HttpError } from "grammy";
+import { z } from "zod";
+/**
+ * `TelegramSetup` — guided credential capture for the Telegram channel
+ * (Phase 13, ADR-0020 §2).
+ *
+ * Wizard transcript:
+ *
+ *   1. `secret` — bot token, format `<digits>:<token>` (BotFather).
+ *
+ * Schema (`credentialSchema`):
+ *
+ *   - `botToken: string` matching `/^\d+:[A-Za-z0-9_-]+$/`.
+ *
+ * Validate (`validate`):
+ *
+ *   - Instantiates a transient grammy `Bot` and calls `bot.api.getMe()`.
+ *     grammy maps the Bot API failure modes to typed errors:
+ *       • `GrammyError` with `error_code: 401` → invalid token.
+ *       • `HttpError` → transport/network failure.
+ *   - We translate both into `channel.setup_validation_failed` so the
+ *     operator sees a clean message; the orchestrator does NOT persist.
+ *
+ * Persist (`persist`):
+ *
+ *   - Atomic 0o600 write to
+ *     `~/.nubemclaw-dev/credentials/telegram-bot-token` via
+ *     `writeChannelCredential` (SDK shared helper).
+ *
+ * Cancellation at any step is converted by `runChannelSetup` to
+ * `channel.setup_cancelled` — see ADR-0020 §2.
+ */
+const TELEGRAM_BOT_TOKEN_REGEX = /^\d+:[A-Za-z0-9_-]+$/;
+export const TelegramCredentialsSchema = z
+    .object({
+    botToken: z.string().regex(TELEGRAM_BOT_TOKEN_REGEX, {
+        message: "expected BotFather format: <digits>:<token>",
+    }),
+})
+    .strict();
+export const createTelegramSetup = (opts) => ({
+    channel: "telegram",
+    credentialSchema: TelegramCredentialsSchema,
+    async promptOperator(wizard) {
+        const token = await wizard.secret({
+            message: "Telegram bot token (BotFather format: 123456:ABC...)",
+            validate: (value) => {
+                if (value === undefined || value.trim() === "")
+                    return "required";
+                if (!TELEGRAM_BOT_TOKEN_REGEX.test(value.trim())) {
+                    return "expected BotFather format: <digits>:<token>";
+                }
+                return undefined;
+            },
+        });
+        if (!token.ok)
+            return token;
+        return ok({ botToken: token.value.trim() });
+    },
+    async validate(creds) {
+        const factory = opts.botFactory ?? ((token) => new Bot(token));
+        const bot = factory(creds.botToken);
+        try {
+            const me = await bot.api.getMe();
+            if (me.is_bot !== true) {
+                return err(nubemClawError({
+                    code: "channel.setup_validation_failed",
+                    message: "telegram getMe returned a non-bot identity — token is not a bot token",
+                }));
+            }
+            opts.logger.info({ username: me.username, id: me.id }, "telegram bot validated");
+            return ok(undefined);
+        }
+        catch (cause) {
+            if (cause instanceof GrammyError) {
+                return err(nubemClawError({
+                    code: "channel.setup_validation_failed",
+                    message: `telegram getMe rejected the token: ${cause.description}`,
+                    meta: { error_code: cause.error_code },
+                    cause,
+                }));
+            }
+            if (cause instanceof HttpError) {
+                return err(nubemClawError({
+                    code: "channel.setup_validation_failed",
+                    message: `telegram getMe could not reach the Bot API: ${cause.message}`,
+                    cause,
+                }));
+            }
+            return err(nubemClawError({
+                code: "channel.setup_validation_failed",
+                message: `telegram getMe failed: ${String(cause)}`,
+                cause,
+            }));
+        }
+    },
+    async persist(creds) {
+        const paths = resolveCredentialPaths({ channel: "telegram", role: "bot-token" }, opts.envVars ?? process.env);
+        await writeChannelCredential(creds.botToken, paths);
+    },
+});
+//# sourceMappingURL=setup.js.map

package/dist/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"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"}