@wrongstack/telegram 0.309.0 → 0.310.0

package/dist/approval-flow.d.ts

@@ -0,0 +1,53 @@
+import type { Logger } from '@wrongstack/core/types';
+import type { TelegramApiCallbackQuery, TelegramApiClient } from './api-client.js';
+export interface TelegramApprovalResult {
+    approved: boolean;
+    fromUser: string;
+    fromUserId?: number | undefined;
+}
+export interface TelegramApprovalRequestInput {
+    requestId: string;
+    sessionId: string;
+    expectedChatId: string | number;
+    expectedUserIds: readonly (string | number)[];
+    allowGroup: boolean;
+    expiresAt: number;
+    signal?: AbortSignal | undefined;
+}
+type TelegramApprovalRequestState = 'pending' | 'resolved' | 'expired' | 'cancelled';
+interface TelegramApprovalRequest {
+    requestId: string;
+    sessionId: string;
+    expectedChatId: string;
+    expectedUserIds: ReadonlySet<string>;
+    allowGroup: boolean;
+    promptMessageId?: number | undefined;
+    pendingCallbacks: TelegramApiCallbackQuery[];
+    expiresAt: number;
+    state: TelegramApprovalRequestState;
+    resolve: (value: TelegramApprovalResult) => void;
+    timer: ReturnType<typeof setTimeout>;
+    signal?: AbortSignal | undefined;
+    abortHandler?: (() => void) | undefined;
+}
+export interface ApprovalFlowDeps {
+    log: Logger;
+    api: () => TelegramApiClient;
+    inboundDenialReason(userId: string | undefined, chatId: string | undefined): 'user' | 'chat' | undefined;
+}
+export declare class ApprovalFlow {
+    readonly callbackWaiters: Map<string, TelegramApprovalRequest>;
+    private readonly log;
+    private readonly api;
+    private readonly inboundDenialReason;
+    constructor(deps: ApprovalFlowDeps);
+    settleApproval(requestId: string, state: Exclude<TelegramApprovalRequestState, 'pending'>, result: TelegramApprovalResult): boolean;
+    dispatchCallback(cq: TelegramApiCallbackQuery): Promise<void>;
+    private answerCallback;
+    awaitApproval(input: TelegramApprovalRequestInput): Promise<TelegramApprovalResult>;
+    bindApprovalPrompt(requestId: string, promptMessageId: number): boolean;
+    cancelApproval(requestId: string, fromUser?: string): boolean;
+    cancelAll(fromUser: string): void;
+}
+export {};
+//# sourceMappingURL=approval-flow.d.ts.map

package/dist/bot-types.d.ts

@@ -0,0 +1,56 @@
+import type { Logger } from '@wrongstack/core/types';
+import type { OffsetStore } from './offset-store.js';
+import type { PollLock } from './poll-lock.js';
+/**
+ * Bot-surface type contracts (card 7A-4).
+ *
+ * Type-only leaf extracted from bot.ts so the composer imports its public
+ * shapes without dragging implementation modules into the type graph.
+ */
+export interface TelegramBotResponse<T> {
+    ok: true;
+    result: T;
+}
+/** Incoming message shape emitted as a custom event. */
+export interface TelegramIncomingMessage {
+    messageId: number;
+    chatId: number;
+    chatType: string;
+    userId?: number | undefined;
+    userName?: string | undefined;
+    text: string;
+    timestamp: number;
+}
+export interface TelegramBotOptions {
+    token: string;
+    pollIntervalSec: number;
+    allowedUsers: Set<string>;
+    allowedChats: Set<string>;
+    /** Max messages to buffer for the agent to read. Default: 50. */
+    bufferSize: number;
+    log: Logger;
+    /**
+     * Resolved on every outbound send so live `parseMode` config changes
+     * (via `api.onConfigChange`) take effect without restarting the plugin.
+     * Empty string or `undefined` → plain text. See `TelegramPluginConfig.parseMode`.
+     */
+    getParseMode?: () => '' | 'HTML' | 'MarkdownV2' | undefined;
+    /** Called for each incoming message that passes allowlist checks. */
+    onMessage(msg: TelegramIncomingMessage): void;
+    /**
+     * Optional typed offset store. When provided, the polling offset is persisted
+     * atomically on every successful poll and restored on startup, preventing
+     * message replay after crashes or restarts.
+     */
+    offsetStore?: OffsetStore | undefined;
+    /**
+     * Optional cross-process single-poller lock. Telegram allows one
+     * `getUpdates` consumer per token; when another wstack instance holds the
+     * lock, this bot stands by (no polling) and takes over once the holder
+     * stops or its heartbeat goes stale.
+     */
+    lock?: PollLock | undefined;
+    /** How often a standby instance retries acquiring the lock. Default: 15s. */
+    standbyRetryMs?: number | undefined;
+}
+//# sourceMappingURL=bot-types.d.ts.map

package/dist/bot.d.ts

@@ -1,182 +1,41 @@
-import type { Logger } from '@wrongstack/core/types';
-import { type TelegramApiMessage } from './api-client.js';
-import type { OffsetStore } from './offset-store.js';
-import type { PollLock } from './poll-lock.js';
-export interface TelegramBotResponse<T> {
-    ok: true;
-    result: T;
-}
-export interface TelegramIncomingMessage {
-    messageId: number;
-    chatId: number;
-    chatType: string;
-    userId?: number | undefined;
-    userName?: string | undefined;
-    text: string;
-    timestamp: number;
-}
-export interface TelegramApprovalResult {
-    approved: boolean;
-    fromUser: string;
-    fromUserId?: number | undefined;
-}
-export interface TelegramApprovalRequestInput {
-    requestId: string;
-    sessionId: string;
-    expectedChatId: string | number;
-    expectedUserIds: readonly (string | number)[];
-    /** Group/supergroup callbacks are rejected unless this was explicitly enabled. */
-    allowGroup: boolean;
-    expiresAt: number;
-    /** Cancels the request when its owning tool execution is aborted. */
-    signal?: AbortSignal | undefined;
-}
-export interface TelegramBotOptions {
-    token: string;
-    pollIntervalSec: number;
-    allowedUsers: Set<string>;
-    allowedChats: Set<string>;
-    /** Max messages to buffer for the agent to read. Default: 50. */
-    bufferSize: number;
-    log: Logger;
-    /**
-     * Resolved on every outbound send so live `parseMode` config changes
-     * (via `api.onConfigChange`) take effect without restarting the plugin.
-     * Empty string or `undefined` → plain text. See `TelegramPluginConfig.parseMode`.
-     */
-    getParseMode?: () => '' | 'HTML' | 'MarkdownV2' | undefined;
-    /** Called for each incoming message that passes allowlist checks. */
-    onMessage(msg: TelegramIncomingMessage): void;
-    /**
-     * Optional typed offset store. When provided, the polling offset is persisted
-     * atomically on every successful poll and restored on startup, preventing
-     * message replay after crashes or restarts.
-     */
-    offsetStore?: OffsetStore | undefined;
-    /**
-     * Optional cross-process single-poller lock. Telegram allows one
-     * `getUpdates` consumer per token; when another wstack instance holds the
-     * lock, this bot stands by (no polling) and takes over once the holder
-     * stops or its heartbeat goes stale.
-     */
-    lock?: PollLock | undefined;
-    /** How often a standby instance retries acquiring the lock. Default: 15s. */
-    standbyRetryMs?: number | undefined;
-}
+import { ApprovalFlow, type TelegramApprovalRequestInput, type TelegramApprovalResult } from './approval-flow.js';
+import type { TelegramBotOptions } from './bot-types.js';
+import { TelegramInbox } from './inbox.js';
+import { Poller } from './poller.js';
+import { TelegramOutbox } from './outbox.js';
+export type { TelegramBotOptions, TelegramBotResponse, TelegramIncomingMessage } from './bot-types.js';
+export type { TelegramApprovalRequestInput, TelegramApprovalResult } from './approval-flow.js';
+export { escapeHtml, truncateForTelegram } from './text-format.js';
 export declare class TelegramBot {
     private readonly api;
-    private readonly pollIntervalMs;
-    private readonly allowedUsers;
-    private readonly allowedChats;
     private readonly log;
-    private readonly onMessage;
-    private readonly controller;
-    private pollTimer;
-    private pollActive;
-    private offset;
-    /**
-     * Consecutive HTTP 409 ("another getUpdates in flight") responses. Two
-     * wstack instances polling the same bot token used to fight at full poll
-     * speed forever, erroring on every cycle. After CONFLICT_BACKOFF_AFTER
-     * consecutive conflicts this instance backs off to a slow poll and warns
-     * once; any successful poll resets to the normal cadence.
-     */
-    private conflictStreak;
-    private static readonly CONFLICT_BACKOFF_AFTER;
-    private static readonly CONFLICT_POLL_MS;
-    private _startedAt;
-    /** Typed offset store for atomic polling-cursor persistence. */
-    private readonly offsetStore?;
-    /** Single-poller election across wstack instances sharing this token. */
     private readonly lock?;
-    private readonly standbyRetryMs;
-    private readonly getParseMode?;
-    private standbyTimer;
-    private standbyAnnounced;
-    private readonly bufferMax;
-    private readonly buffer;
-    private readonly callbackWaiters;
+    readonly approvals: ApprovalFlow;
+    readonly poller: Poller;
+    readonly inbox: TelegramInbox;
+    private readonly outbox;
     constructor(opts: TelegramBotOptions);
-    /** Start polling for updates. Idempotent. */
     start(): void;
-    /** Stop polling and cancel all in-flight requests. */
     stop(): void;
-    /** True when the bot is started but waiting for the poll lock. */
     get standby(): boolean;
-    /**
-     * Acquire the poll lock (when configured) and start the poll loop, or
-     * stand by and retry until the current holder releases it.
-     */
-    private acquireAndPoll;
-    /** The lock was stolen while we held it — pause polling and stand by. */
-    private handleLockLost;
     get startedAt(): number | null;
     get running(): boolean;
-    /** Return buffered messages, newest first. Optionally filter by chat. */
     getMessages(opts?: {
         chatId?: string | number | undefined;
         limit?: number | undefined;
-    }): TelegramIncomingMessage[];
-    /** Drop messages older than or equal to the given message ID from the buffer (optionally scoped to a specific chat). */
+    }): ReturnType<TelegramInbox['getMessages']>;
     acknowledge(lastMessageId: number, chatId?: string | number | undefined): number;
     get bufferCount(): number;
-    sendMessage(chatId: string | number, text: string, signal?: AbortSignal | undefined): Promise<TelegramBotResponse<TelegramApiMessage>>;
-    /**
-     * Send a message that has up to one row of inline buttons (Telegram's
-     * `inline_keyboard`). Used by `telegram_approve` to present a
-     * yes/no prompt. The keyboard payload is opaque to the bot — callers
-     * pass already-encoded `callback_data` strings (≤ 64 bytes each).
-     */
+    private processMessage;
+    sendMessage(chatId: string | number, text: string, signal?: AbortSignal | undefined): ReturnType<TelegramOutbox['sendMessage']>;
     sendMessageWithKeyboard(chatId: string | number, text: string, buttons: Array<{
         text: string;
         callback_data: string;
-    }>, signal?: AbortSignal | undefined): Promise<TelegramBotResponse<TelegramApiMessage>>;
-    health(signal?: AbortSignal | undefined): Promise<{
-        ok: boolean;
-        username?: string | undefined;
-        error?: string | undefined;
-    }>;
-    private schedulePoll;
-    private poll;
-    /**
-     * Apply the inbound identity policy to every update type. A non-empty set is
-     * a mandatory constraint: missing identity fails closed instead of bypassing
-     * the allowlist. An empty set leaves that identity dimension unrestricted.
-     */
-    private inboundDenialReason;
-    private processMessage;
-    /**
-     * Resolve a pending approval request exactly once and record its terminal
-     * state before removing it from the live registry.
-     */
-    private settleApproval;
-    private dispatchCallback;
-    /**
-     * POST /answerCallbackQuery for a callback. Best-effort: failures are
-     * logged at debug and swallowed — the caller's resolve() must not depend
-     * on the ack reaching Telegram (the user may get a "loading" spinner if
-     * it fails, but the agent's approval flow continues normally).
-     */
-    private answerCallback;
-    /**
-     * Register one approval request before its prompt is sent. The returned
-     * promise owns the request's only timer and resolves on one terminal event.
-     */
+    }>, signal?: AbortSignal | undefined): ReturnType<TelegramOutbox['sendMessageWithKeyboard']>;
+    health(signal?: AbortSignal | undefined): Promise<Awaited<ReturnType<TelegramOutbox['health']>>>;
+    get callbackWaiters(): ApprovalFlow['callbackWaiters'];
     awaitApproval(input: TelegramApprovalRequestInput): Promise<TelegramApprovalResult>;
-    /**
-     * Attach the Bot API response's prompt message ID to an existing request.
-     * Any callback that arrived during the send is replayed against the fully
-     * bound identity without allocating a second waiter or timer.
-     */
     bindApprovalPrompt(requestId: string, promptMessageId: number): boolean;
-    /** Cancel a request that cannot reach a valid terminal callback. */
     cancelApproval(requestId: string, fromUser?: string): boolean;
-    private loadOffset;
-    private saveOffset;
 }
-export declare function truncateForTelegram(text: string, maxLen?: number): string;
-/**
- * Escape HTML special chars for Telegram's HTML parse mode.
- */
-export declare function escapeHtml(text: string): string;
 //# sourceMappingURL=bot.d.ts.map

package/dist/inbox.d.ts

@@ -0,0 +1,48 @@
+import type { Logger } from '@wrongstack/core/types';
+import type { TelegramApiMessage } from './api-client.js';
+import type { TelegramIncomingMessage } from './bot-types.js';
+/**
+ * Inbound message handling (card 7A-4): the bounded incoming-message buffer,
+ * the allowlist identity policy, and update→incoming mapping. Moved verbatim
+ * from bot.ts; the bot keeps thin delegates so its public surface and the
+ * white-box suites (which reach this owner through `bot.inbox`) keep working.
+ */
+export interface TelegramInboxDeps {
+    log: Logger;
+    /** Max messages to buffer for the agent to read. */
+    bufferMax: number;
+    allowedUsers: Set<string>;
+    allowedChats: Set<string>;
+    /** Called for each incoming message that passes allowlist checks. */
+    onMessage(msg: TelegramIncomingMessage): void;
+    /**
+     * Best-effort denial notice sender — wired to the bot's retry-wrapped
+     * `sendMessage`. Failures are swallowed by `processMessage` so an
+     * unauthorized user cannot spam unhandled rejections into the poll loop.
+     */
+    sendNotice(chatId: string | number, text: string): Promise<unknown>;
+}
+export declare class TelegramInbox {
+    private readonly deps;
+    readonly buffer: TelegramIncomingMessage[];
+    constructor(deps: TelegramInboxDeps);
+    /** Return buffered messages, newest first. Optionally filter by chat. */
+    getMessages(opts?: {
+        chatId?: string | number | undefined;
+        limit?: number | undefined;
+    }): TelegramIncomingMessage[];
+    /** Drop messages older than or equal to the given message ID from the buffer (optionally scoped to a specific chat). */
+    acknowledge(lastMessageId: number, chatId?: string | number | undefined): number;
+    get bufferCount(): number;
+    /**
+     * Apply the inbound identity policy to every update type. A non-empty set is
+     * a mandatory constraint: missing identity fails closed instead of bypassing
+     * the allowlist. An empty set leaves that identity dimension unrestricted.
+     * Public because ApprovalFlow consumes the same gate via the bot's wiring.
+     */
+    denialReason(userId: string | undefined, chatId: string | undefined): 'user' | 'chat' | undefined;
+    processMessage(msg: TelegramApiMessage & {
+        text: string;
+    }): void;
+}
+//# sourceMappingURL=inbox.d.ts.map