@krischoichoi/channel-telegram 0.6.0

package/lib/inbound.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Inbound processing: dedup window + structured mapping + media hydration +
+ * emit. Handles both `message` and `callback_query` updates.
+ *
+ * The getUpdates offset ack already prevents protocol-level redelivery; this
+ * dedup window is the adapter-level second layer for redelivery inside one
+ * cycle (e.g. a webhook-style retry with the same update_id).
+ *
+ * Media hydration runs after the duplicate check and before emit. The dedup
+ * entry is committed only after emit succeeds, so a failed dispatch remains
+ * retryable. Each binary part (`image`, `file`, `audio` — voice notes and
+ * audio messages — and `video`) with an opaque Telegram `resourceRef`
+ * (file_id) is resolved and downloaded through the platform upstream and its
+ * bytes are placed on `localData`. A download failure never blocks text
+ * delivery — the part keeps its `resourceRef` and records a stable
+ * `ingressFailure` code.
+ *
+ * ## Interactions (plan §5 / §12.2)
+ *
+ * A `callback_query` update maps to `interaction.received` with
+ * `action = callback_data` (untrusted, zod-validated, never interpreted by the
+ * adapter). The adapter immediately issues a best-effort `answerCallbackQuery`
+ * ACK so Telegram clears the button progress spinner — this must NOT block on
+ * agent resolution, so the ACK is fired and never gates the emit.
+ */
+import type { ChannelAdapterContext } from '@krischoichoi/channel-core';
+import { type TelegramFileResolver } from './media-hydrator.js';
+import { type TelegramInboundMeta } from './mapper.js';
+export interface InboundProcessorOptions {
+    ctx: ChannelAdapterContext;
+    meta: TelegramInboundMeta;
+    dedupEnabled: boolean;
+    dedupWindowMs: number;
+    /** Platform file resolver used to hydrate image/file `resourceRef` parts. */
+    files?: TelegramFileResolver;
+    /** Hard byte cap for one inbound media download. */
+    maxDownloadBytes?: number;
+    /** Injectable clock (tests). */
+    now?: () => number;
+    /**
+     * Best-effort `answerCallbackQuery` ACK for callback_query updates. The
+     * adapter wires this to the upstream; the call is fired immediately and never
+     * gates the emit (plan §12.2).
+     */
+    ackCallback?: (callbackQueryId: string) => Promise<void>;
+}
+export declare class InboundProcessor {
+    private readonly options;
+    private readonly now;
+    /** dedup key -> last-seen timestamp, pruned on every handle. */
+    private readonly seen;
+    constructor(options: InboundProcessorOptions);
+    /** Process one raw update from the upstream; dedup, hydrate, then emit. */
+    handle(raw: unknown): Promise<void>;
+    /** Map + ACK + emit a callback_query interaction. */
+    private handleCallbackQuery;
+    /** Map + hydrate + emit a message update. */
+    private handleMessage;
+    private prune;
+}
+//# sourceMappingURL=inbound.d.ts.map

package/lib/inbound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../src/inbound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EACV,qBAAqB,EAGtB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAwB,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAML,KAAK,mBAAmB,EACzB,MAAM,aAAa,CAAC;AAgDrB,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,qBAAqB,CAAC;IAC3B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,qBAAa,gBAAgB;IAKf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;gBAErB,OAAO,EAAE,uBAAuB;IAI7D,2EAA2E;IACrE,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BzC,qDAAqD;YACvC,mBAAmB;IAoBjC,6CAA6C;YAC/B,aAAa;IAkB3B,OAAO,CAAC,KAAK;CAKd"}

package/lib/inbound.js

@@ -0,0 +1,125 @@
+import { hydrateTelegramParts } from './media-hydrator.js';
+import { dedupKey, isCallbackQueryUpdate, mapCallbackQuery, mapInbound, TelegramInboundValidationError, } from './mapper.js';
+/** Compact per-part summary for inbound message logs (debug diagnostics). */
+function summarizeParts(parts) {
+    return parts.map((part) => {
+        switch (part.type) {
+            case 'text':
+                return { type: 'text', text: part.text.slice(0, 80) };
+            case 'image':
+                return {
+                    type: 'image',
+                    url: part.url,
+                    resourceRef: part.resourceRef,
+                    mimeType: part.mimeType,
+                    localDataBytes: part.localData?.byteLength,
+                    ingressFailure: part.ingressFailure,
+                };
+            case 'file':
+                return {
+                    type: 'file',
+                    name: part.name,
+                    size: part.size,
+                    mimeType: part.mimeType,
+                    localDataBytes: part.localData?.byteLength,
+                    ingressFailure: part.ingressFailure,
+                };
+            case 'audio':
+                return {
+                    type: 'audio',
+                    durationMs: part.durationMs,
+                    mimeType: part.mimeType,
+                    localDataBytes: part.localData?.byteLength,
+                    ingressFailure: part.ingressFailure,
+                };
+            case 'video':
+                return {
+                    type: 'video',
+                    durationMs: part.durationMs,
+                    mimeType: part.mimeType,
+                    localDataBytes: part.localData?.byteLength,
+                    ingressFailure: part.ingressFailure,
+                };
+            default:
+                return { type: part.type };
+        }
+    });
+}
+export class InboundProcessor {
+    options;
+    now;
+    /** dedup key -> last-seen timestamp, pruned on every handle. */
+    seen = new Map();
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    /** Process one raw update from the upstream; dedup, hydrate, then emit. */
+    async handle(raw) {
+        const key = dedupKey(raw);
+        if (this.options.dedupEnabled) {
+            const now = this.now();
+            const last = this.seen.get(key);
+            if (last !== undefined && now - last < this.options.dedupWindowMs) {
+                this.options.ctx.logger.debug(`[channel-telegram] dropped duplicate update '${key}'`);
+                return;
+            }
+            this.prune(now);
+        }
+        if (isCallbackQueryUpdate(raw)) {
+            await this.handleCallbackQuery(raw);
+            if (this.options.dedupEnabled)
+                this.seen.set(key, this.now());
+            return;
+        }
+        try {
+            await this.handleMessage(raw);
+        }
+        catch (error) {
+            if (!(error instanceof TelegramInboundValidationError))
+                throw error;
+            // Invalid identities must not enter the contract or block the polling
+            // cursor forever. This is intentionally a silent protocol-level drop.
+            this.options.ctx.logger.warn('[channel-telegram] dropped invalid inbound update');
+            return;
+        }
+        if (this.options.dedupEnabled)
+            this.seen.set(key, this.now());
+    }
+    /** Map + ACK + emit a callback_query interaction. */
+    async handleCallbackQuery(raw) {
+        const event = mapCallbackQuery(raw, this.options.meta);
+        // Immediate best-effort ACK (clears the button spinner). It must never
+        // block on agent resolution, so any failure is logged, not propagated to
+        // the emit.
+        if (this.options.ackCallback) {
+            void this.options.ackCallback(event.interactionId).catch((error) => {
+                this.options.ctx.logger.warn('[channel-telegram] answerCallbackQuery failed', error instanceof Error ? error.message : error);
+            });
+        }
+        this.options.ctx.logger.info(`[channel-telegram] inbound interaction ${event.interactionId} from ${event.sender.id} in ${event.conversation.id}`, { action: event.action.slice(0, 80) });
+        await this.options.ctx.emit(event);
+    }
+    /** Map + hydrate + emit a message update. */
+    async handleMessage(raw) {
+        const event = mapInbound(raw, this.options.meta);
+        if (this.options.files) {
+            await hydrateTelegramParts(event.message.content, this.options.files, {
+                maxBytes: this.options.maxDownloadBytes ?? 20 * 1024 * 1024,
+                signal: this.options.ctx.signal,
+                logger: this.options.ctx.logger,
+            });
+        }
+        // Inbound message log (debug diagnostics): visible in web:debug with
+        // DSH_CHANNELS_DEBUG=1, shows mapped parts incl. hydration result.
+        this.options.ctx.logger.info(`[channel-telegram] inbound message ${event.message.id} from ${event.sender.id} in ${event.conversation.id}`, { parts: summarizeParts(event.message.content) });
+        await this.options.ctx.emit(event);
+    }
+    prune(now) {
+        for (const [key, ts] of this.seen) {
+            if (now - ts >= this.options.dedupWindowMs)
+                this.seen.delete(key);
+        }
+    }
+}
+//# sourceMappingURL=inbound.js.map

package/lib/inbound.js.map

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

package/lib/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @krischoichoi/channel-telegram — Telegram Bot API channel adapter for DeepSeek
+ * Harness.
+ *
+ * A fifth official channel built on the same Channel Contract as Weixin / QQ /
+ * DingTalk / Lark. The Bot API token is resolved through `ctx.credentials`
+ * (`tokenRef`, default `TELEGRAM_BOT_TOKEN`) — the secret value never lives in
+ * profile config, logs, or fixtures.
+ *
+ * Lifecycle: when the Channel Control Plane (`ctx.channelControl`) is present,
+ * apply() registers a `ChannelDefinition` ('telegram'); the control plane
+ * decides when to instantiate/mount the adapter (headless auto-start). When it
+ * is absent (standalone / older harness), apply() falls back to resolving the
+ * token credential and mounting directly — never throwing when the channel is
+ * merely unconfigured.
+ *
+ * Streaming is `edit`: one message is sent and then edited in place with
+ * `editMessageText` as full-text previews arrive. Set
+ * `config.streaming.enabled: false` to force the buffered send-once strategy.
+ */
+import { type Context } from '@deepseek-ai/cordis';
+import { Config, TELEGRAM_BOT_TOKEN_REF } from './config.js';
+import type { TelegramConfig, TelegramConfigLive } from './config.js';
+import { type TelegramAdapterDeps } from './adapter.js';
+export declare const name = "channel-telegram";
+export declare const inject: string[];
+export { Config, TELEGRAM_BOT_TOKEN_REF };
+export { TelegramAdapter, type TelegramAdapterDeps } from './adapter.js';
+export { createTelegramDefinition, type TelegramCredentialSeam } from './definition.js';
+export { InboundProcessor } from './inbound.js';
+export { hydrateTelegramParts, type TelegramFileResolver, type TelegramMediaHydratorOptions } from './media-hydrator.js';
+export { OutboundSender, actionsToReplyMarkup } from './outbound.js';
+export { TelegramStreamingReply, makePreview } from './streaming-reply.js';
+export { TelegramRichStreamingReply } from './rich-streaming-reply.js';
+export { TelegramApiError, classifyTelegramError, type TelegramErrorKind, type TelegramErrorParameters, } from './api-error.js';
+export { RICH_MESSAGE_MAX_UTF8, RICH_MESSAGE_MAX_BLOCKS, RICH_MESSAGE_MAX_NESTING, RICH_MESSAGE_MAX_MEDIA, RICH_MESSAGE_MAX_TABLE_COLUMNS, REGULAR_MESSAGE_MAX, CAPTION_MAX, type InputRichMessage, type TelegramInlineKeyboardButton, type TelegramInlineKeyboardMarkup, type TelegramInlineKeyboardRow, type TelegramReplyMarkup, type AnswerCallbackQueryParams, } from './rich-message.js';
+export * as render from './render/index.js';
+export { renderMessage, sendWithFallback, resolveMode, isFormattingFailure, type RenderMode, type RenderOptions, type RenderPlan, } from './render/index.js';
+export type { TelegramFormattingConfig, TelegramConfigLive } from './config.js';
+export { mapInbound, mapCallbackQuery, isCallbackQueryUpdate, dedupKey, simpleHash, type TelegramInboundMeta } from './mapper.js';
+export { HttpTelegramUpstream, type TelegramUpstream, type TelegramBotUser, type TelegramMedia, type TelegramSendOptions, type TelegramFormatOptions, type TelegramSentMessage, type TelegramFileInfo, type TelegramDownloadedFile, } from './upstream.js';
+export { FetchTransport, type HttpTransport, type HttpRequestInit, type HttpBinaryResponse, } from './transport.js';
+export { manifest, type TelegramManifest } from './manifest.js';
+/**
+ * Entry plugin apply. Accepts both the activation-time live shape (volatile
+ * fields resolve to `Volatile<T>` handles under Harness 0.2.0) and a plain
+ * snapshot (tests / programmatic mounting); plain fields pass through
+ * `resolveVolatileConfig` untouched. The shape is validated by Schemastery at
+ * the Loader boundary via the attached `Config` schema.
+ */
+export declare function apply(ctx: Context, rawConfig: TelegramConfig | TelegramConfigLive, deps?: TelegramAdapterDeps): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAKnD,OAAO,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGzE,eAAO,MAAM,IAAI,qBAAqB,CAAC;AACvC,eAAO,MAAM,MAAM,EAAE,MAAM,EAAgC,CAAC;AAE5D,OAAO,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,KAAK,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,KAAK,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACzH,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,8BAA8B,EAC9B,mBAAmB,EACnB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,mBAAmB,EACnB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClI,OAAO,EACL,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,GAC5B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAoChE;;;;;;GAMG;AACH,wBAAgB,KAAK,CACnB,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,cAAc,GAAG,kBAAkB,EAC9C,IAAI,GAAE,mBAAwB,GAC7B,IAAI,CAsDN"}

package/lib/index.js

@@ -0,0 +1,114 @@
+/**
+ * @krischoichoi/channel-telegram — Telegram Bot API channel adapter for DeepSeek
+ * Harness.
+ *
+ * A fifth official channel built on the same Channel Contract as Weixin / QQ /
+ * DingTalk / Lark. The Bot API token is resolved through `ctx.credentials`
+ * (`tokenRef`, default `TELEGRAM_BOT_TOKEN`) — the secret value never lives in
+ * profile config, logs, or fixtures.
+ *
+ * Lifecycle: when the Channel Control Plane (`ctx.channelControl`) is present,
+ * apply() registers a `ChannelDefinition` ('telegram'); the control plane
+ * decides when to instantiate/mount the adapter (headless auto-start). When it
+ * is absent (standalone / older harness), apply() falls back to resolving the
+ * token credential and mounting directly — never throwing when the channel is
+ * merely unconfigured.
+ *
+ * Streaming is `edit`: one message is sent and then edited in place with
+ * `editMessageText` as full-text previews arrive. Set
+ * `config.streaming.enabled: false` to force the buffered send-once strategy.
+ */
+import {} from '@deepseek-ai/cordis';
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { mountChannelAdapter, resolveVolatileConfig, resolveVolatileValue } from '@krischoichoi/channel-core';
+import { Config, TELEGRAM_BOT_TOKEN_REF } from './config.js';
+import { TelegramAdapter } from './adapter.js';
+import { createTelegramDefinition } from './definition.js';
+export const name = 'channel-telegram';
+export const inject = ['channels', 'credentials'];
+export { Config, TELEGRAM_BOT_TOKEN_REF };
+export { TelegramAdapter } from './adapter.js';
+export { createTelegramDefinition } from './definition.js';
+export { InboundProcessor } from './inbound.js';
+export { hydrateTelegramParts } from './media-hydrator.js';
+export { OutboundSender, actionsToReplyMarkup } from './outbound.js';
+export { TelegramStreamingReply, makePreview } from './streaming-reply.js';
+export { TelegramRichStreamingReply } from './rich-streaming-reply.js';
+export { TelegramApiError, classifyTelegramError, } from './api-error.js';
+export { RICH_MESSAGE_MAX_UTF8, RICH_MESSAGE_MAX_BLOCKS, RICH_MESSAGE_MAX_NESTING, RICH_MESSAGE_MAX_MEDIA, RICH_MESSAGE_MAX_TABLE_COLUMNS, REGULAR_MESSAGE_MAX, CAPTION_MAX, } from './rich-message.js';
+export * as render from './render/index.js';
+export { renderMessage, sendWithFallback, resolveMode, isFormattingFailure, } from './render/index.js';
+export { mapInbound, mapCallbackQuery, isCallbackQueryUpdate, dedupKey, simpleHash } from './mapper.js';
+export { HttpTelegramUpstream, } from './upstream.js';
+export { FetchTransport, } from './transport.js';
+export { manifest } from './manifest.js';
+/**
+ * One-time legacy plaintext `config.token` -> credential reference migration.
+ * The value is written to the credentials seam once, then the plaintext is
+ * stripped from the in-memory config. The secret value is never logged.
+ */
+function migrateLegacyToken(ctx, config) {
+    const legacy = config.token;
+    if (typeof legacy !== 'string' || legacy.length === 0)
+        return;
+    const ref = config.tokenRef ?? TELEGRAM_BOT_TOKEN_REF;
+    void ctx.credentials
+        .set(credentialRef(ref), legacy)
+        .then(() => {
+        ctx.logger('channel-telegram').info(`[channel-telegram] legacy plaintext token migrated into credentials ref "${ref}"`);
+    })
+        .catch((error) => {
+        ctx.logger('channel-telegram').warn('[channel-telegram] legacy plaintext token migration failed', error);
+    });
+    delete config.token;
+}
+/**
+ * Entry plugin apply. Accepts both the activation-time live shape (volatile
+ * fields resolve to `Volatile<T>` handles under Harness 0.2.0) and a plain
+ * snapshot (tests / programmatic mounting); plain fields pass through
+ * `resolveVolatileConfig` untouched. The shape is validated by Schemastery at
+ * the Loader boundary via the attached `Config` schema.
+ */
+export function apply(ctx, rawConfig, deps = {}) {
+    const config = resolveVolatileConfig(rawConfig);
+    const credentialsCtx = ctx;
+    migrateLegacyToken(credentialsCtx, config);
+    const ref = config.tokenRef ?? TELEGRAM_BOT_TOKEN_REF;
+    const control = ctx.get('channelControl');
+    if (control) {
+        // Control plane present (doc §25/§27): register the definition EVEN when
+        // disabled — the plane owns adapter instantiation + headless auto-start,
+        // and a disabled definition must stay visible so the Web control plane can
+        // re-enable it later (doc §19/§20).
+        const settings = ctx.get('settings');
+        control.definitions.register(createTelegramDefinition({
+            config,
+            deps,
+            credentials: {
+                resolve: (name) => credentialsCtx.credentials.resolve(credentialRef(name)),
+                describe: (name) => credentialsCtx.credentials.describe(credentialRef(name)),
+                set: (name, value) => credentialsCtx.credentials.set(credentialRef(name), value),
+            },
+            persistEnabled: (enabled) => settings?.update('channels-telegram', { enabled }) ?? Promise.resolve(),
+        }));
+        return;
+    }
+    // Legacy fallback (standalone, no control plane): mount directly. There is no
+    // directory/control surface to re-enable a disabled channel, so the config
+    // `enabled` gate still applies (doc §20). Unconfigured token must NOT throw
+    // (doc §25) — log a warning and stay idle.
+    if (!resolveVolatileValue(config.enabled))
+        return;
+    ctx.effect(async () => {
+        const token = deps.token ?? (await credentialsCtx.credentials.resolve(credentialRef(ref)))?.value;
+        if (!token) {
+            ctx.logger('channel-telegram').warn(`[channel-telegram] telegram credential "${ref}" is not configured; adapter not mounted`);
+            return () => { };
+        }
+        mountChannelAdapter(ctx, new TelegramAdapter(config, { ...deps, token }), (signal) => ctx.channels.createAdapterContext({ channelId: 'telegram', signal }));
+        // The mount owns the adapter lifecycle; this outer effect only scopes the
+        // async credential resolution, so its disposer is a no-op.
+        return () => { };
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/lib/manifest.d.ts

@@ -0,0 +1,16 @@
+export interface TelegramUpstreamManifest {
+    reference: string;
+    testedVersion: string;
+    versionRange: string;
+    strategy: 'source';
+}
+export interface TelegramManifest {
+    id: 'telegram';
+    adapterVersion: string;
+    upstream: TelegramUpstreamManifest;
+    sdk: undefined;
+    status: 'experimental';
+}
+/** M5 manifest: direct HTTP protocol, no SDK. */
+export declare const manifest: TelegramManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/lib/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,UAAU,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,wBAAwB,CAAC;IACnC,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,iDAAiD;AACjD,eAAO,MAAM,QAAQ,EAAE,gBAWtB,CAAC"}

package/lib/manifest.js

@@ -0,0 +1,26 @@
+/**
+ * Telegram upstream compatibility manifest (M4 pattern).
+ *
+ * Records the upstream reference and tested version so `channels doctor` and
+ * the upgrade pipeline can govern compatibility without re-verifying by hand.
+ *
+ * Strategy choice: 'source' — the adapter speaks the Telegram Bot API HTTP
+ * protocol directly (`/bot<token>/...`), so no platform SDK is consumed.
+ * Offline contract and fixture coverage is not a live-platform verification,
+ * so the adapter remains experimental until the Telegram live gate passes.
+ */
+import pkg from '../package.json' with { type: 'json' };
+/** M5 manifest: direct HTTP protocol, no SDK. */
+export const manifest = {
+    id: 'telegram',
+    adapterVersion: pkg.version,
+    upstream: {
+        reference: 'Telegram Bot API (https://core.telegram.org/bots/api)',
+        testedVersion: '10.2',
+        versionRange: '>=10.2',
+        strategy: 'source',
+    },
+    sdk: undefined,
+    status: 'experimental',
+};
+//# sourceMappingURL=manifest.js.map

package/lib/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAiBxD,iDAAiD;AACjD,MAAM,CAAC,MAAM,QAAQ,GAAqB;IACxC,EAAE,EAAE,UAAU;IACd,cAAc,EAAE,GAAG,CAAC,OAAO;IAC3B,QAAQ,EAAE;QACR,SAAS,EAAE,uDAAuD;QAClE,aAAa,EAAE,MAAM;QACrB,YAAY,EAAE,QAAQ;QACtB,QAAQ,EAAE,QAAQ;KACnB;IACD,GAAG,EAAE,SAAS;IACd,MAAM,EAAE,cAAc;CACvB,CAAC"}

package/lib/mapper.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure payload mapping (no I/O): Telegram Bot API updates → Channel Contract.
+ *
+ * Raw updates only ever ride along in `event.raw` for debugging — core and
+ * the harness bridge never depend on their shape (red line 6).
+ *
+ * Telegram update shape (Bot API 10.2):
+ * ```json
+ * { "update_id": 123,
+ *   "message": { "message_id": 456, "date": 1700000000,
+ *     "chat": { "id": 789, "type": "private" },
+ *     "from": { "id": 111, "first_name": "Alice" },
+ *     "text": "hello" } }
+ * ```
+ *
+ * `chat.type` 'private' → dm conversation; 'group'/'supergroup' → group
+ * conversation keyed by the chat id. All ids are numeric on the wire and are
+ * stringified into the branded contract identities. The bot token is never
+ * part of any mapped event.
+ */
+import type { AccountId, ChannelId, MessageReceived } from '@krischoichoi/channel-core';
+import type { InteractionReceived } from '@krischoichoi/channel-core';
+export interface TelegramInboundMeta {
+    channel: ChannelId;
+    accountId: AccountId;
+    /** Trusted bot identity resolved from getMe before polling starts. */
+    bot?: {
+        id: number;
+        username?: string;
+    };
+}
+/** An untrusted Telegram update did not satisfy the canonical identity schema. */
+export declare class TelegramInboundValidationError extends Error {
+    constructor(message: string);
+}
+/** Stable hash for ids when the platform omits them. */
+export declare function simpleHash(input: string): string;
+/** Map one raw Telegram update into the stable channel event shape. */
+export declare function mapInbound(raw: unknown, meta: TelegramInboundMeta): MessageReceived;
+/** Dedup identity for raw updates (update_id, then message_id). */
+export declare function dedupKey(raw: unknown): string;
+/** Whether a raw update carries a `callback_query` (message-bearing). */
+export declare function isCallbackQueryUpdate(raw: unknown): boolean;
+/**
+ * Map a validated `callback_query` update to `InteractionReceived`. Always run
+ * `isCallbackQueryUpdate` first; this function re-parses defensively and throws
+ * a clear error for a malformed tolerance so the adapter fails closed rather
+ * than emitting a fabricated interaction.
+ */
+export declare function mapCallbackQuery(raw: unknown, meta: TelegramInboundMeta): InteractionReceived;
+//# sourceMappingURL=mapper.d.ts.map

package/lib/mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapper.d.ts","sourceRoot":"","sources":["../src/mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EAIT,eAAe,EAEhB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,SAAS,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB,sEAAsE;IACtE,GAAG,CAAC,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,kFAAkF;AAClF,qBAAa,8BAA+B,SAAQ,KAAK;gBAC3C,OAAO,EAAE,MAAM;CAI5B;AAqGD,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMhD;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,eAAe,CA4CnF;AAoGD,mEAAmE;AACnE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAS7C;AAwBD,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,mBAAmB,CA4B7F"}