opensquid 0.5.395

package/dist/channels/adapters/discord.js

@@ -0,0 +1,220 @@
+/**
+ * discord:// adapter — outbound delivery via discord.js v14.
+ *
+ * URI scheme: `discord://<guild_id>/<channel_id>` (both snowflake numerics).
+ *
+ * Dependency: `discord.js` is an OPTIONAL peerDependency. Users who never
+ * configure a Discord channel pay nothing — we lazy-load the module on
+ * first `start()`/`send()`. If the dependency is missing at runtime, the
+ * adapter surfaces a structured error via `SendResult` rather than
+ * crashing the process.
+ *
+ * Intents: deliberately narrow to `GatewayIntentBits.Guilds` only. We do
+ * NOT request `MessageContent` (which requires verified-bot approval
+ * after 100 servers) because the adapter is outbound-only — we never
+ * read message contents.
+ *
+ * Lifecycle: `start()` logs in + waits for the `ready` event before
+ * resolving so the first `send()` cannot race the gateway handshake.
+ * `stop()` destroys the client. `send()` auto-starts if not yet ready.
+ *
+ * Security: the bot token is closed over by this function and never
+ * appears in any log output, error message, or SendResult — the same
+ * discipline as the Telegram adapter.
+ */
+/** Parse `discord://<guild>/<channel>` into `{ guildId, channelId }`. */
+function parseUri(uri) {
+    const match = /^discord:\/\/(\d+)\/(\d+)$/.exec(uri);
+    if (match === null)
+        return null;
+    const guildId = match[1];
+    const channelId = match[2];
+    if (guildId === undefined || channelId === undefined)
+        return null;
+    return { guildId, channelId };
+}
+/** Lazy-load discord.js so it stays an optional peerDep. */
+async function loadDiscordModule() {
+    const mod = (await import('discord.js'));
+    return { Client: mod.Client, GatewayIntentBits: mod.GatewayIntentBits };
+}
+export function discordAdapter(opts) {
+    let client = null;
+    let ready = false;
+    let starting = null;
+    // `inboundEnabled` flips before client construction. Once true, the
+    // client is built with GuildMessages + MessageContent intents in
+    // addition to Guilds. Discord intents are immutable after client
+    // construction; once the client exists we cannot upgrade — flipping
+    // this flag after start() throws on the next subscribeInbound.
+    let inboundEnabled = false;
+    const inboundListeners = new Set();
+    let installedMessageHandler = null;
+    async function ensureStarted() {
+        if (ready)
+            return;
+        if (starting !== null) {
+            await starting;
+            return;
+        }
+        starting = (async () => {
+            const { Client, GatewayIntentBits } = await loadDiscordModule();
+            // Spec lock: declare GuildMessages + MessageContent at client
+            // creation when any subscribeInbound has been registered.
+            // Otherwise stay narrow (`Guilds` only) — verified-bot approval
+            // requirement past 100 servers.
+            const intents = inboundEnabled
+                ? [
+                    GatewayIntentBits.Guilds,
+                    GatewayIntentBits.GuildMessages,
+                    GatewayIntentBits.MessageContent,
+                ]
+                : [GatewayIntentBits.Guilds];
+            const c = new Client({ intents });
+            const readyPromise = new Promise((resolve) => {
+                c.once('ready', () => {
+                    resolve();
+                });
+            });
+            await c.login(opts.token);
+            await readyPromise;
+            client = c;
+            ready = true;
+            // Install ONE shared messageCreate listener for all inbound
+            // subscriptions, if any are registered. We dispatch to each
+            // listener inside the handler — discord.js's `off()` removes by
+            // function identity, which we preserve via `installedMessageHandler`.
+            if (inboundEnabled) {
+                installMessageHandler(c);
+            }
+        })();
+        try {
+            await starting;
+        }
+        finally {
+            starting = null;
+        }
+    }
+    function installMessageHandler(c) {
+        if (installedMessageHandler !== null)
+            return;
+        const handler = (msg) => {
+            // Skip messages from bots (including this bot) — prevents loop-back
+            // when an outbound send triggers a fresh inbound event. Loop-break
+            // belongs to the engine, but the bot-author filter is a cheap
+            // first line of defense at the platform boundary.
+            if (msg.author.bot === true)
+                return;
+            const event = {
+                kind: 'inbound_channel',
+                channelUri: msg.guildId !== null
+                    ? `discord://${msg.guildId}/${msg.channelId}`
+                    : `discord://dm/${msg.channelId}`,
+                sender: msg.author.id,
+                text: msg.content,
+                receivedAt: new Date().toISOString(),
+            };
+            // Fan out to every registered listener; errors stay inside.
+            for (const fn of inboundListeners) {
+                void fn(event).catch(() => {
+                    /* swallow — never bubble to discord.js's event loop */
+                });
+            }
+        };
+        c.on('messageCreate', handler);
+        installedMessageHandler = handler;
+    }
+    return {
+        scheme: 'discord',
+        validate(uri) {
+            return /^discord:\/\/\d+\/\d+$/.test(uri);
+        },
+        async start() {
+            await ensureStarted();
+        },
+        async stop() {
+            if (!ready || client === null)
+                return;
+            // Remove the messageCreate handler before destroy so an in-flight
+            // event can't fire one of our inbound listeners after stop() resolves.
+            if (installedMessageHandler !== null) {
+                try {
+                    client.off('messageCreate', installedMessageHandler);
+                }
+                catch {
+                    // best-effort
+                }
+                installedMessageHandler = null;
+            }
+            inboundListeners.clear();
+            try {
+                await client.destroy();
+            }
+            catch {
+                // best-effort — already torn down.
+            }
+            client = null;
+            ready = false;
+            inboundEnabled = false;
+        },
+        async send(uri, message) {
+            const parsed = parseUri(uri);
+            if (parsed === null)
+                return { ok: false, error: 'bad uri' };
+            try {
+                await ensureStarted();
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                // Strip token if it ever appears in an error path; defense in
+                // depth — discord.js may include it in some auth failures.
+                return { ok: false, error: msg.replaceAll(opts.token, '[redacted]') };
+            }
+            if (client === null)
+                return { ok: false, error: 'client not ready' };
+            try {
+                const channel = await client.channels.fetch(parsed.channelId);
+                if (channel === null)
+                    return { ok: false, error: 'channel not found' };
+                if (!channel.isTextBased()) {
+                    return { ok: false, error: 'channel not text-based' };
+                }
+                await channel.send(message.text);
+                return { ok: true };
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return { ok: false, error: msg.replaceAll(opts.token, '[redacted]') };
+            }
+        },
+        async subscribeInbound(handler) {
+            // Intents are immutable after client construction. If we already
+            // started without inbound intents, subscribeInbound is a misuse —
+            // surface it loud so the operator fixes the bootstrap order.
+            if (ready && !inboundEnabled) {
+                throw new Error('discordAdapter.subscribeInbound: client already started without inbound intents; ' +
+                    'call subscribeInbound BEFORE send()/start()');
+            }
+            inboundEnabled = true;
+            inboundListeners.add(handler);
+            // If the client is already running (because a prior subscribeInbound
+            // started it), the messageCreate handler is already installed. If
+            // not, start it now so events actually flow.
+            if (!ready) {
+                await ensureStarted();
+            }
+            return {
+                // eslint-disable-next-line @typescript-eslint/require-await -- async to satisfy InboundSubscription contract
+                unsubscribe: async () => {
+                    inboundListeners.delete(handler);
+                    // The shared messageCreate handler stays attached as long as
+                    // the client lives; removing it on the last unsubscribe would
+                    // re-install on the next subscribeInbound, which complicates
+                    // the bot-author filter. The set membership check inside the
+                    // handler is the cheap detach.
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=discord.js.map

package/dist/channels/adapters/discord.js.map

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

package/dist/channels/adapters/slack.d.ts

@@ -0,0 +1,63 @@
+/**
+ * slack:// adapter — outbound via @slack/web-api (`chat.postMessage`),
+ * inbound via @slack/socket-mode (`SocketModeClient`).
+ *
+ * URI scheme: `slack://<workspace>/<channel>` where both segments are
+ * `[\w-]+`. The workspace segment is informational — Slack routes by
+ * the bot token's workspace, not by URI — but we keep it in the URI so
+ * users can spot the destination without resolving credentials.
+ *
+ * Dependencies: both Slack SDKs are OPTIONAL peerDependencies, loaded
+ * lazily on `start()` / `send()`. Users who never configure a Slack
+ * channel never install them.
+ *
+ * Critical SLA: Slack requires `ack()` within 3 seconds on every inbound
+ * event. The runtime contract here is "ack first, work async": the
+ * adapter wraps every event listener so `ack()` is called synchronously
+ * before the user-supplied handler runs, and the handler is then
+ * scheduled on the next microtask. This makes it impossible for a slow
+ * handler to miss the SLA.
+ *
+ * Security: bot + app tokens are closed over by this function and
+ * scrubbed from any error path that might surface them.
+ */
+import type { InboundChannelEvent } from '../../runtime/event.js';
+import type { ChannelAdapter, InboundSubscription } from '../types.js';
+export interface SlackAdapterOpts {
+    /** Bot token (xoxb-...) for chat.postMessage and other web-api calls. */
+    botToken: string;
+    /** App-level token (xapp-...) for socket-mode connection. */
+    appToken: string;
+    /** Optional inbound event handler. Adapter acks BEFORE invoking. */
+    onEvent?: (event: SlackInboundEvent) => void | Promise<void>;
+    /** Workspace segment to embed in `InboundChannelEvent.channelUri` — Slack
+     *  routes by token, not URI, but we keep the segment so audit logs +
+     *  channel mapping read identifiably. Defaults to `'workspace'`. */
+    workspace?: string;
+}
+export interface SlackInboundEvent {
+    type: string;
+    body: unknown;
+}
+export interface SlackAdapter extends ChannelAdapter {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Test/inspection hook — process a single inbound envelope as if it
+     * arrived from Slack. ACKs synchronously, runs the user handler async. */
+    handleInbound(envelope: SlackInboundEnvelope): Promise<void>;
+    /**
+     * AUTO.6 — attach an inbound handler that maps Slack `message` events
+     * to a unified `InboundChannelEvent`. Auto-starts Socket Mode if not
+     * already running. ACK still fires synchronously before any handler
+     * runs (3s SLA).
+     */
+    subscribeInbound(handler: (event: InboundChannelEvent) => Promise<void>): Promise<InboundSubscription>;
+}
+export interface SlackInboundEnvelope {
+    type: string;
+    body: unknown;
+    /** Slack SDK supplies this; the adapter MUST call it within 3s. */
+    ack: () => Promise<void> | void;
+}
+export declare function slackAdapter(opts: SlackAdapterOpts): SlackAdapter;
+//# sourceMappingURL=slack.d.ts.map

package/dist/channels/adapters/slack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.d.ts","sourceRoot":"","sources":["../../../src/channels/adapters/slack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAkB,mBAAmB,EAAc,MAAM,aAAa,CAAC;AAEnG,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;wEAEoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;8EAC0E;IAC1E,aAAa,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;;;OAKG;IACH,gBAAgB,CACd,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,GACrD,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,mEAAmE;IACnE,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACjC;AAgED,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAiKjE"}

package/dist/channels/adapters/slack.js

@@ -0,0 +1,216 @@
+/**
+ * slack:// adapter — outbound via @slack/web-api (`chat.postMessage`),
+ * inbound via @slack/socket-mode (`SocketModeClient`).
+ *
+ * URI scheme: `slack://<workspace>/<channel>` where both segments are
+ * `[\w-]+`. The workspace segment is informational — Slack routes by
+ * the bot token's workspace, not by URI — but we keep it in the URI so
+ * users can spot the destination without resolving credentials.
+ *
+ * Dependencies: both Slack SDKs are OPTIONAL peerDependencies, loaded
+ * lazily on `start()` / `send()`. Users who never configure a Slack
+ * channel never install them.
+ *
+ * Critical SLA: Slack requires `ack()` within 3 seconds on every inbound
+ * event. The runtime contract here is "ack first, work async": the
+ * adapter wraps every event listener so `ack()` is called synchronously
+ * before the user-supplied handler runs, and the handler is then
+ * scheduled on the next microtask. This makes it impossible for a slow
+ * handler to miss the SLA.
+ *
+ * Security: bot + app tokens are closed over by this function and
+ * scrubbed from any error path that might surface them.
+ */
+/** Parse `slack://<workspace>/<channel>` into `{ workspace, channel }`. */
+function parseUri(uri) {
+    const match = /^slack:\/\/([\w-]+)\/([\w-]+)$/.exec(uri);
+    if (match === null)
+        return null;
+    const workspace = match[1];
+    const channel = match[2];
+    if (workspace === undefined || channel === undefined)
+        return null;
+    return { workspace, channel };
+}
+async function loadWebApi() {
+    const mod = (await import('@slack/web-api'));
+    return { WebClient: mod.WebClient };
+}
+async function loadSocketMode() {
+    const mod = (await import('@slack/socket-mode'));
+    return { SocketModeClient: mod.SocketModeClient };
+}
+function redact(message, ...secrets) {
+    let out = message;
+    for (const s of secrets) {
+        if (s !== '')
+            out = out.replaceAll(s, '[redacted]');
+    }
+    return out;
+}
+export function slackAdapter(opts) {
+    let web = null;
+    let socket = null;
+    let started = false;
+    const inboundListeners = new Set();
+    const workspaceSegment = opts.workspace ?? 'workspace';
+    /** Map a Slack envelope (event_callback) → unified InboundChannelEvent.
+     *  Returns `null` for envelopes that don't carry a user-authored
+     *  message (subtypes like bot_message, message_changed, etc). */
+    function mapToInboundEvent(envelope) {
+        if (envelope.type !== 'event_callback' && envelope.type !== 'events_api')
+            return null;
+        const body = envelope.body;
+        const ev = body?.event;
+        if (ev?.type !== 'message')
+            return null;
+        // Skip bot-authored + subtyped messages — loop-break first line of
+        // defense + ignore edit/delete envelopes which aren't fresh inputs.
+        if (ev.bot_id !== undefined && ev.bot_id !== '')
+            return null;
+        if (ev.subtype !== undefined && ev.subtype !== '')
+            return null;
+        if (ev.channel === undefined || ev.user === undefined)
+            return null;
+        const channelUri = `slack://${workspaceSegment}/${ev.channel}`;
+        const event = {
+            kind: 'inbound_channel',
+            channelUri,
+            sender: ev.user,
+            text: ev.text ?? '',
+            receivedAt: new Date().toISOString(),
+            ...(ev.thread_ts !== undefined ? { threadKey: ev.thread_ts } : {}),
+        };
+        return event;
+    }
+    /**
+     * ACK-first dispatch. We invoke `envelope.ack()` synchronously (the
+     * Slack SDK accepts both sync and async return), then schedule the
+     * user handler on the next microtask so the ack flushes before any
+     * potentially-slow work. This guarantees the 3-second SLA regardless
+     * of handler latency.
+     */
+    async function ackThenDispatch(envelope) {
+        // 1) ACK first — never await user code before this.
+        const ackResult = envelope.ack();
+        if (ackResult instanceof Promise)
+            await ackResult;
+        // 2a) Dispatch legacy onEvent — back-compat path.
+        if (opts.onEvent !== undefined) {
+            try {
+                await opts.onEvent({ type: envelope.type, body: envelope.body });
+            }
+            catch {
+                // user handler errors are swallowed — never affect ack.
+            }
+        }
+        // 2b) Dispatch AUTO.6 inbound listeners — only when the envelope
+        // carries a user-authored message event.
+        if (inboundListeners.size > 0) {
+            const event = mapToInboundEvent(envelope);
+            if (event !== null) {
+                for (const fn of inboundListeners) {
+                    try {
+                        await fn(event);
+                    }
+                    catch {
+                        // never bubble — same posture as onEvent.
+                    }
+                }
+            }
+        }
+    }
+    /** Ensure Socket Mode is connected. Mirrors `start()` but for the
+     *  subscribeInbound auto-start path — only spins up if needed. */
+    async function ensureSocketStarted() {
+        if (socket !== null)
+            return;
+        const { SocketModeClient } = await loadSocketMode();
+        const s = new SocketModeClient({ appToken: opts.appToken });
+        s.on('slack_event', (envelope) => {
+            void ackThenDispatch(envelope);
+        });
+        await s.start();
+        socket = s;
+    }
+    return {
+        scheme: 'slack',
+        validate(uri) {
+            return /^slack:\/\/[\w-]+\/[\w-]+$/.test(uri);
+        },
+        async start() {
+            if (started)
+                return;
+            started = true;
+            const { WebClient } = await loadWebApi();
+            web = new WebClient(opts.botToken);
+            // Only attach socket mode when the caller registered an inbound
+            // handler — outbound-only deployments stay cheap.
+            if (opts.onEvent !== undefined) {
+                await ensureSocketStarted();
+            }
+        },
+        async stop() {
+            if (!started)
+                return;
+            started = false;
+            // Clear AUTO.6 listeners FIRST so an in-flight envelope can't reach
+            // a stale handler after stop() resolves.
+            inboundListeners.clear();
+            if (socket !== null) {
+                try {
+                    await socket.disconnect();
+                }
+                catch {
+                    // best-effort
+                }
+                socket = null;
+            }
+            web = null;
+        },
+        async send(uri, message) {
+            const parsed = parseUri(uri);
+            if (parsed === null)
+                return { ok: false, error: 'bad uri' };
+            if (web === null) {
+                try {
+                    const { WebClient } = await loadWebApi();
+                    web = new WebClient(opts.botToken);
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    return { ok: false, error: redact(msg, opts.botToken, opts.appToken) };
+                }
+            }
+            try {
+                await web.chat.postMessage({ channel: parsed.channel, text: message.text });
+                return { ok: true };
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return { ok: false, error: redact(msg, opts.botToken, opts.appToken) };
+            }
+        },
+        async handleInbound(envelope) {
+            await ackThenDispatch(envelope);
+        },
+        async subscribeInbound(handler) {
+            inboundListeners.add(handler);
+            // Auto-attach Socket Mode if start() hasn't been called yet, OR if
+            // start() ran without `onEvent` (outbound-only path). Idempotent.
+            started = true;
+            if (web === null) {
+                const { WebClient } = await loadWebApi();
+                web = new WebClient(opts.botToken);
+            }
+            await ensureSocketStarted();
+            return {
+                // eslint-disable-next-line @typescript-eslint/require-await -- async to satisfy InboundSubscription contract
+                unsubscribe: async () => {
+                    inboundListeners.delete(handler);
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=slack.js.map

package/dist/channels/adapters/slack.js.map

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

package/dist/channels/adapters/telegram.d.ts

@@ -0,0 +1,89 @@
+/**
+ * telegram:// adapter — outbound Bot API delivery via grammy.
+ *
+ * URI scheme: `telegram://<chat_id>[/<topic_id>]`
+ *   - `chat_id` may be negative (supergroups + channels are negative).
+ *   - Optional `topic_id` maps to grammy's `message_thread_id` (forum
+ *     topics in supergroups).
+ *
+ * Allowlist: enforced at `send()`. A chat_id not in
+ * `opts.allowlistChatIds` rejects with `{ ok: false, error: 'chat not
+ * in allowlist' }` BEFORE any API call — no leak of policy decision to
+ * the chat itself.
+ *
+ * Inbound (long-polling) is opt-in via `start()`. The 409 Conflict path
+ * is the documented degradation when another consumer holds the token
+ * (e.g. a parallel Claude Code plugin:telegram bot): we back off
+ * exponentially up to 5 attempts and otherwise stay outbound-only.
+ *
+ * Critical async-pattern note: grammy's `bot.start()` returns a promise
+ * that resolves ONLY on shutdown (when `bot.stop()` is called) — it
+ * does NOT resolve on successful start. Awaiting it deadlocks the
+ * caller forever. We deliberately do not await it; we only attach a
+ * `.catch()` to handle the 409 retry path. The legacy adapter at
+ * `src.legacy/chat/adapters/telegram.ts` documents the same gotcha.
+ *
+ * Outbound-only mode: when `opts.outboundOnly === true` OR every 409
+ * retry has been exhausted, `send()` continues to work (it uses
+ * `bot.api.sendMessage` over HTTPS, which is independent of the
+ * long-poll). `start()` becomes a no-op in this state.
+ */
+import type { InboundChannelEvent } from '../../runtime/event.js';
+import type { ChannelAdapter, InboundChatMessage, InboundSubscription, SendResult } from '../types.js';
+export interface TelegramAdapterOpts {
+    /** Bot API token from @BotFather. */
+    token: string;
+    /** Allowlist of chat_ids the adapter will deliver to. */
+    allowlistChatIds: number[];
+    /** Skip `bot.start()` entirely; outbound `send()` continues to work. */
+    outboundOnly?: boolean;
+    /**
+     * Bot's own @username (without `@`), used to compute `mentionsBot` on the
+     * rich transport envelope. The daemon resolves it once via `getMe` at
+     * startup and passes it here. Unset ⇒ `mentionsBot` is always false.
+     */
+    botUsername?: string;
+    /**
+     * CAT.4 — directory inbound media (photos/documents) is downloaded into.
+     * Defaults to `inboundMediaDir()` (`~/.opensquid/media/inbound`). Tests
+     * point it at an `mkdtemp` so downloads never escape the sandbox.
+     */
+    mediaDownloadDir?: string;
+    /**
+     * CAT.4 — injectable download seam. Given the fully-qualified Telegram file
+     * URL (`https://api.telegram.org/file/bot<token>/<file_path>`), resolves to
+     * the raw bytes. Defaults to `fetch`-based download; tests inject a stub so
+     * the suite never hits the network.
+     */
+    download?: (url: string) => Promise<Uint8Array>;
+}
+export interface TelegramAdapter extends ChannelAdapter {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * AUTO.6 — attach an inbound `'message'` handler that emits a unified
+     * `InboundChannelEvent`. Auto-starts long-polling if not already started
+     * (skipped when `outboundOnly: true` — inbound is impossible there).
+     */
+    subscribeInbound(handler: (event: InboundChannelEvent) => Promise<void>): Promise<InboundSubscription>;
+    /**
+     * CAT.1b — attach a RICH transport handler that emits the full
+     * `InboundChatMessage` envelope (message id, sender id, DM flag, …) the
+     * chat-daemon needs. Same lifecycle/auto-start semantics as
+     * `subscribeInbound`; both are fed from one grammy middleware.
+     */
+    subscribeTransport(handler: (msg: InboundChatMessage) => Promise<void>): Promise<InboundSubscription>;
+    /**
+     * CAT.4 — deliver a photo from a local file. `uri` is the same
+     * `telegram://<chat>[/<topic>]` shape as `send`; the optional `caption`
+     * becomes the photo caption; `threadId` overrides any topic in the URI.
+     * Returns the delivered `message_id` like `send`. Allowlist-enforced.
+     */
+    sendPhoto(uri: string, opts: {
+        path: string;
+        caption?: string;
+        threadId?: number;
+    }): Promise<SendResult>;
+}
+export declare function telegramAdapter(opts: TelegramAdapterOpts): TelegramAdapter;
+//# sourceMappingURL=telegram.d.ts.map

package/dist/channels/adapters/telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../../src/channels/adapters/telegram.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,KAAK,EACV,cAAc,EAEd,kBAAkB,EAElB,mBAAmB,EACnB,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,wEAAwE;IACxE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CACd,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,GACrD,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChC;;;;;OAKG;IACH,kBAAkB,CAChB,OAAO,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,GAClD,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChC;;;;;OAKG;IACH,SAAS,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1D,OAAO,CAAC,UAAU,CAAC,CAAC;CACxB;AAwKD,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAiR1E"}