stitchkit 0.100.2 → 0.101.0

package/dist/telegram/screens/state.d.ts

@@ -0,0 +1,115 @@
+/**
+ * What a chat's screen is, kept where a restart cannot lose it.
+ *
+ * One record per chat: the view it shows — screen, params, the messages with
+ * their fingerprints, the tokens of buttons too long to carry their address —
+ * and the remarks waiting to expire. Nothing else: no history, no copy of
+ * application data. The record is read through its schema every time, because
+ * storage outlives releases and a record written by another version is not
+ * evidence of anything.
+ *
+ * The storage is grammY's own `StorageAdapter`, so any adapter a grammY bot
+ * already uses for sessions (`@grammyjs/storage-*`, `MemorySessionStorage` in
+ * tests, or ten lines over the application's database) keeps screens too.
+ */
+import type { StorageAdapter } from 'grammy';
+import { z } from 'zod';
+/**
+ * How much one chat's record may hold. A view is checked against these when it
+ * is rendered, before anything reaches Telegram: a record refused after the
+ * calls would leave the chat showing messages nothing tracks.
+ */
+export declare const RECORD_LIMITS: {
+    /** Messages in one view. */
+    messages: number;
+    /** Characters of a message key. */
+    key: number;
+    /** Buttons whose address is kept in the record, per view. */
+    tokens: number;
+    /** Characters of one kept address. */
+    tokenBody: number;
+    /** Remarks waiting to expire. */
+    remarks: number;
+};
+declare const ScreenViewStateSchema: z.ZodObject<{
+    screen: z.ZodString;
+    params: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    messages: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        id: z.ZodNumber;
+        kind: z.ZodEnum<{
+            animation: "animation";
+            audio: "audio";
+            document: "document";
+            photo: "photo";
+            rich: "rich";
+            text: "text";
+            video: "video";
+        }>;
+        fingerprint: z.ZodNullable<z.ZodObject<{
+            content: z.ZodString;
+            media: z.ZodString;
+            markup: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    tokens: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+export declare const ScreenChatStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    view: z.ZodNullable<z.ZodObject<{
+        screen: z.ZodString;
+        params: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        messages: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            id: z.ZodNumber;
+            kind: z.ZodEnum<{
+                animation: "animation";
+                audio: "audio";
+                document: "document";
+                photo: "photo";
+                rich: "rich";
+                text: "text";
+                video: "video";
+            }>;
+            fingerprint: z.ZodNullable<z.ZodObject<{
+                content: z.ZodString;
+                media: z.ZodString;
+                markup: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        tokens: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>>;
+    expiring: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        at: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ScreenChatState = z.infer<typeof ScreenChatStateSchema>;
+export type ScreenViewState = z.infer<typeof ScreenViewStateSchema>;
+/** Where chats' screen state survives a restart: grammY's storage contract. */
+export type TelegramScreenStorage = StorageAdapter<ScreenChatState>;
+export declare const emptyChatState: () => ScreenChatState;
+export interface ReadChatState {
+    readonly state: ScreenChatState;
+    /** The stored record did not match the schema and was set aside. */
+    readonly discarded: boolean;
+}
+/**
+ * The chat's record. A storage that fails to answer fails the update — reading
+ * "nothing" would send a message meant as input to whatever handles text next.
+ * A record that does not match this release's schema is set aside and
+ * reported: refusing it forever would leave the chat without screens.
+ */
+export declare function readChatState(storage: TelegramScreenStorage, key: string): Promise<ReadChatState>;
+export declare function writeChatState(storage: TelegramScreenStorage, key: string, state: ScreenChatState): Promise<void>;
+/**
+ * One chat at a time, in arrival order. Two presses in one chat are two
+ * read-render-write passes over one record; interleaved, the second would draw
+ * over messages the first is deleting. A chat's queue is dropped once it
+ * drains, and bounded while it has work: a chat that sends faster than
+ * Telegram answers is refused rather than queued without end.
+ */
+export type ChatQueue = <T>(key: string, task: () => Promise<T>) => Promise<T>;
+export declare function createChatQueue(maxPending: number): ChatQueue;
+export {};
+//# sourceMappingURL=state.d.ts.map

package/dist/telegram/screens/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AACH,eAAO,MAAM,aAAa;IACxB,4BAA4B;IAC5B,QAAQ;IACR,mCAAmC;IACnC,GAAG;IACH,6DAA6D;IAC7D,MAAM;IACN,sCAAsC;IACtC,SAAS;IACT,iCAAiC;IACjC,OAAO;CACR,CAAC;AAeF,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;kBAUhB,CAAC;AAMZ,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAOvB,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,+EAA+E;AAC/E,MAAM,MAAM,qBAAqB,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;AAEpE,eAAO,MAAM,cAAc,QAAO,eAIhC,CAAC;AAEH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,qBAAqB,EAC9B,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,aAAa,CAAC,CAOxB;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,EAC9B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAE/E,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAiB7D"}

package/dist/telegram/screens/telegram-screens.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `telegramScreens<Ctx>()` — where a bot's screens are declared and composed.
+ *
+ * The bot's grammY context type is named once; every screen, group and handler
+ * declared from here sees it. `create` checks the declaration as a whole — ids,
+ * paths, that every screen with params has a load above it — and returns the
+ * middleware.
+ */
+import type { Context } from 'grammy';
+import { type TelegramScreens, type TelegramScreensConfig } from './runtime.js';
+import { ScreenScope } from './screen.js';
+export declare class TelegramScreensRoot<C extends Context> extends ScreenScope<C, Record<never, never>, undefined> {
+    /** Compose the declared screens into grammY middleware. */
+    create(config: TelegramScreensConfig<C>): TelegramScreens<C>;
+}
+/** Declare a bot's screens against its grammY context type. */
+export declare function telegramScreens<C extends Context>(): TelegramScreensRoot<C>;
+//# sourceMappingURL=telegram-screens.d.ts.map

package/dist/telegram/screens/telegram-screens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-screens.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/telegram-screens.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAKtC,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAiB,WAAW,EAAE,MAAM,UAAU,CAAC;AAEtD,qBAAa,mBAAmB,CAAC,CAAC,SAAS,OAAO,CAAE,SAAQ,WAAW,CACrE,CAAC,EACD,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACpB,SAAS,CACV;IACC,2DAA2D;IAC3D,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAE3D;CACF;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,CAAC,SAAS,OAAO,KAAK,mBAAmB,CAAC,CAAC,CAAC,CAE3E"}

package/dist/telegram/screens/test-chat-telegram.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The Telegram side of the test chat: the messages it keeps and how it answers
+ * the Bot API calls screens make.
+ *
+ * It keeps the rules screens depend on: an edit that changes nothing is
+ * refused as "message is not modified", a deleted message cannot be edited or
+ * deleted again, a text message has no caption to edit, a media message no
+ * text.
+ */
+import type { Chat, InlineKeyboardMarkup, Message, User } from 'grammy/types';
+export type TestMessageKind = 'text' | 'rich' | 'photo' | 'video' | 'animation' | 'document' | 'audio';
+export interface StoredMessage {
+    id: number;
+    from: 'bot' | 'user';
+    kind: TestMessageKind;
+    text: string;
+    media: string | undefined;
+    rich: unknown;
+    markup: InlineKeyboardMarkup | undefined;
+    deleted: boolean;
+}
+export type TestChatPeer = Chat.PrivateChat | Chat.GroupChat | Chat.SupergroupChat;
+export interface FakeTelegramIdentity {
+    readonly chat: TestChatPeer;
+    readonly botUser: User;
+    readonly user: User;
+}
+export interface FakeTelegramRefusal {
+    readonly ok: false;
+    readonly error_code: number;
+    readonly description: string;
+}
+export interface FakeTelegram {
+    /** Every message the chat has had, deleted ones marked. */
+    readonly stored: StoredMessage[];
+    /** Press answers — the toasts — in order. */
+    readonly answers: string[];
+    /** A message still in the chat. */
+    find(id: unknown): StoredMessage | undefined;
+    asTelegram(message: StoredMessage): Message;
+    /** A Bot API call answered the way Telegram would. */
+    answer(method: string, payload: Readonly<Record<string, unknown>>): unknown;
+    refuse(description: string, errorCode?: number): FakeTelegramRefusal;
+    nextMessageId(): number;
+}
+export declare function createFakeTelegram({ chat, botUser, user, }: FakeTelegramIdentity): FakeTelegram;
+//# sourceMappingURL=test-chat-telegram.d.ts.map

package/dist/telegram/screens/test-chat-telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-chat-telegram.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/test-chat-telegram.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAK9E,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,MAAM,GACN,OAAO,GACP,OAAO,GACP,WAAW,GACX,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IACrB,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC;AAEnF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,mCAAmC;IACnC,IAAI,CAAC,EAAE,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAAC;IAC7C,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;IAC5C,sDAAsD;IACtD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC;IAC5E,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAAC;IACrE,aAAa,IAAI,MAAM,CAAC;CACzB;AAkID,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EACJ,OAAO,EACP,IAAI,GACL,EAAE,oBAAoB,GAAG,YAAY,CAgHrC"}

package/dist/telegram/screens/test-chat.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A chat with the application's own bot, and no Telegram.
+ *
+ * `createScreenTestChat(bot)` takes the `Bot` the application composes — its
+ * middleware, commands and error boundary, in their real order — and answers
+ * its Bot API calls from memory through `bot.api.config.use`. Updates enter
+ * through `bot.handleUpdate`, so what a test proves is what the bot does:
+ * that `/support` is not swallowed by a screen waiting for text, that a press
+ * edits the message it came from.
+ *
+ * The Telegram it talks to is `test-chat-telegram.ts`, which keeps the rules
+ * screens depend on. Nothing here imports grammY at run time; the bot brings it.
+ */
+import type { Bot, Context } from 'grammy';
+import type { InlineKeyboardMarkup } from 'grammy/types';
+import { type TestMessageKind } from './test-chat-telegram.js';
+/** A message as the user sees it. */
+export interface TestChatMessage {
+    readonly id: number;
+    readonly from: 'bot' | 'user';
+    readonly kind: TestMessageKind;
+    /** The text, or the caption, as sent — Telegram HTML for the bot's messages. */
+    readonly text: string;
+    readonly media: string | undefined;
+    readonly rich: unknown;
+    /** Button labels, row by row. */
+    readonly buttons: readonly (readonly string[])[];
+    readonly markup: InlineKeyboardMarkup | undefined;
+}
+export interface TestChatCall {
+    readonly method: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+export interface TestChatOptions {
+    readonly chatId?: number;
+    readonly chatType?: 'private' | 'group' | 'supergroup';
+    readonly userId?: number;
+}
+export interface ScreenTestChat<C extends Context = Context> {
+    /** What the chat shows, top to bottom. */
+    readonly messages: readonly TestChatMessage[];
+    /** Every Bot API call the bot made, in order. */
+    readonly calls: readonly TestChatCall[];
+    /** Press answers — the toasts — in order; `''` for a silent answer. */
+    readonly answers: readonly string[];
+    /** The user sends text; a leading `/word` is a command. */
+    send(text: string): Promise<void>;
+    /** The user sends a photo, with an optional caption. */
+    sendPhoto(fileId: string, caption?: string): Promise<void>;
+    /** The user presses the lowest button with this label. */
+    press(label: string): Promise<void>;
+    /** A press carrying arbitrary `callback_data` on a message — what a forged press looks like. */
+    pressData(messageId: number, data: string): Promise<void>;
+    /** Refuse the next call of `method` the way Telegram would. */
+    failNext(method: string, description: string, errorCode?: number): void;
+    /** The user deletes a message. */
+    deleteByUser(messageId: number): void;
+    /**
+     * The process restarted: the same chat, as Telegram keeps it, now answered by
+     * a new bot — built over the same storage, the way the application builds it.
+     */
+    restart(bot: Bot<C>): void;
+    clearCalls(): void;
+}
+export declare function createScreenTestChat<C extends Context>(first: Bot<C>, options?: TestChatOptions): ScreenTestChat<C>;
+//# sourceMappingURL=test-chat.d.ts.map

package/dist/telegram/screens/test-chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-chat.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/test-chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,GAAG,EAAY,OAAO,EAAE,MAAM,QAAQ,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAkC,MAAM,cAAc,CAAC;AAEzF,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAE9B,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,CAAC;CACnD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,YAAY,CAAC;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;IACzD,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,wDAAwD;IACxD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,0DAA0D;IAC1D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,gGAAgG;IAChG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxE,kCAAkC;IAClC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC3B,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,OAAO,EACpD,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EACb,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAAC,CAAC,CAAC,CAgLnB"}

package/dist/telegram/screens/view.d.ts

@@ -0,0 +1,89 @@
+/**
+ * What a screen shows: messages as plain objects.
+ *
+ * A view is data, so it can be compared. `{ text }` is a text message,
+ * `{ rich }` a Bot API rich message (Markdown, HTML or blocks, without file
+ * uploads) and `{ photo }` (or `video`, `animation`, `document`, `audio`) a
+ * media message with an optional caption; exactly one of those keys is
+ * present, and the type says so. A keyboard is rows of buttons where a row or a button may be `false`,
+ * `null` or `undefined` — a conditional row is written in the literal, not
+ * around it. Buttons are either screen buttons (`link`, `back`, an action) or
+ * any Telegram inline button that carries no `callback_data`, as Telegram
+ * spells it.
+ */
+import type { InlineKeyboardButton, InputRichMessageWithoutUpload } from 'grammy/types';
+import type { ActionValue } from './callback-codec.js';
+import type { TelegramText } from './html.js';
+import type { AnyTelegramScreen, ScreenLinkArgs } from './screen-types.js';
+export type ScreenMediaKind = 'photo' | 'video' | 'animation' | 'document' | 'audio';
+export declare const SCREEN_MEDIA_KINDS: readonly ScreenMediaKind[];
+/** A button label: its text, or its text with Telegram's style and custom-emoji icon. */
+export type ButtonLabel = string | Omit<InlineKeyboardButton.CallbackButton, 'callback_data'>;
+type ButtonTarget = {
+    readonly kind: 'link';
+    readonly screen: AnyTelegramScreen;
+    readonly params: Readonly<Record<string, ActionValue>>;
+} | {
+    readonly kind: 'back';
+} | {
+    readonly kind: 'action';
+    readonly screen: AnyTelegramScreen;
+    readonly params: Readonly<Record<string, ActionValue>>;
+    readonly action: string;
+    readonly input: Readonly<Record<string, ActionValue | undefined>> | undefined;
+};
+/** A button the screens runtime answers: it becomes `callback_data` when rendered. */
+export declare class ScreenButton {
+    readonly label: ButtonLabel;
+    readonly target: ButtonTarget;
+    constructor(label: ButtonLabel, target: ButtonTarget);
+}
+/** Any inline button Telegram answers itself — a URL, a Mini App, copy text, … */
+export type PlainKeyboardButton = Exclude<InlineKeyboardButton, InlineKeyboardButton.CallbackButton>;
+export type KeyboardButton = ScreenButton | PlainKeyboardButton;
+type Absent = false | null | undefined;
+export type KeyboardRow = readonly (KeyboardButton | Absent)[];
+export type Keyboard = readonly (KeyboardRow | Absent)[];
+interface ViewMessageCommon {
+    /**
+     * The message's identity across renders: two renders put the same key in the
+     * same Telegram message when they can. The default is `'main'` for the last
+     * message and `'s0'`, `'s1'`, … for those above it, so the message that
+     * carries a screen's buttons is the one the next screen edits.
+     */
+    readonly key?: string;
+    readonly keyboard?: Keyboard;
+}
+type ContentKey = 'text' | 'rich' | ScreenMediaKind;
+type Without<TKeys extends string> = {
+    readonly [K in TKeys]?: never;
+};
+export interface TextViewMessage extends ViewMessageCommon, Without<Exclude<ContentKey, 'text'> | 'caption'> {
+    readonly text: TelegramText;
+    /** `false` hides the preview of the first link. Default: Telegram's. */
+    readonly linkPreview?: boolean;
+}
+export interface RichViewMessage extends ViewMessageCommon, Without<Exclude<ContentKey, 'rich'> | 'caption' | 'linkPreview'> {
+    /** A rich message as the Bot API takes it; files by `file_id` or URL only. */
+    readonly rich: InputRichMessageWithoutUpload;
+}
+type MediaViewMessageOf<TKind extends ScreenMediaKind> = ViewMessageCommon & Without<Exclude<ContentKey, TKind> | 'linkPreview'> & {
+    /** A Telegram `file_id` or an HTTP URL Telegram can fetch. */
+    readonly [K in TKind]: string;
+} & {
+    readonly caption?: TelegramText;
+};
+export type PhotoViewMessage = MediaViewMessageOf<'photo'>;
+export type VideoViewMessage = MediaViewMessageOf<'video'>;
+export type AnimationViewMessage = MediaViewMessageOf<'animation'>;
+export type DocumentViewMessage = MediaViewMessageOf<'document'>;
+export type AudioViewMessage = MediaViewMessageOf<'audio'>;
+export type ViewMessage = TextViewMessage | RichViewMessage | PhotoViewMessage | VideoViewMessage | AnimationViewMessage | DocumentViewMessage | AudioViewMessage;
+/** What `view` returns: one message, or several shown top to bottom. */
+export type ScreenViewResult = ViewMessage | readonly ViewMessage[];
+/** A link to another screen; its params are required exactly when its path has any. */
+export declare function link<TScreen extends AnyTelegramScreen>(label: ButtonLabel, screen: TScreen, ...params: ScreenLinkArgs<TScreen>): ScreenButton;
+/** A link to the parent screen — the nearest declared screen above this path. */
+export declare function back(label: ButtonLabel): ScreenButton;
+export {};
+//# sourceMappingURL=view.d.ts.map

package/dist/telegram/screens/view.d.ts.map

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

package/dist/telegram/send-failure.d.ts

@@ -63,6 +63,12 @@ export interface TelegramSendFailure {
      */
     evidence: 'parameters' | 'status' | 'description' | 'none';
 }
+/**
+ * Every reason, for a consumer that maps each one to its own code or text. A
+ * `Record<TelegramSendFailureReason, …>` beside it fails to compile when a
+ * release adds a reason, instead of falling through to a default at run time.
+ */
+export declare const TELEGRAM_SEND_FAILURE_REASONS: readonly TelegramSendFailureReason[];
 /**
  * Classify one refused send.
  *
@@ -70,4 +76,23 @@ export interface TelegramSendFailure {
  * which asserts nothing about the recipient and permits no retry.
  */
 export declare function classifyTelegramSendFailure(error: unknown): TelegramSendFailure;
+/**
+ * What a refused edit, deletion or press answer means for the chat — the
+ * questions a screen asks after the message exists, which a send never does.
+ *
+ * - `not-modified`: the edit asked for what is already there. Success.
+ * - `message-gone`: the message is not there — the user deleted it, or the id
+ *   is not a message at all. A deletion of it has nothing left to do.
+ * - `message-locked`: the message is there and cannot be changed that way — too
+ *   old to delete, not the bot's to edit, no text or caption to edit. An edit
+ *   has to send it anew; a deletion leaves it in the chat.
+ * - `query-expired`: the press waited too long to be answered; nothing to do.
+ * - `other`: everything else, including a malformed payload — the caller's to
+ *   raise.
+ *
+ * Internal to the screens: it reads Telegram's prose the same way
+ * {@link classifyTelegramSendFailure} does and is not a public vocabulary.
+ */
+export type TelegramEditRefusal = 'not-modified' | 'message-gone' | 'message-locked' | 'query-expired' | 'other';
+export declare function classifyTelegramEditRefusal(error: unknown): TelegramEditRefusal;
 //# sourceMappingURL=send-failure.d.ts.map

package/dist/telegram/send-failure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;CAC5D;AAuED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA0D/E"}
+{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;CAC5D;AA6CD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,yBAAyB,EAC7B,CAAC;AAyClD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAyD/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAC;AAeZ,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAM/E"}

package/dist/telegram/update-intake.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Webhook updates received durably: recorded before Telegram is answered,
+ * handled after, and never lost to a restart or a slow handler.
+ *
+ * Answering Telegram only after an update is handled breaks twice. A long
+ * handler — a file of gigabytes arriving from a local Bot API server — holds
+ * the connection past Telegram's patience, it gives up and sends the update
+ * again while the first attempt still runs; and a process that dies after
+ * handling but before answering loses nothing Telegram knows about, while one
+ * that dies before handling loses the update for good once it has answered.
+ * So the body is written first and Telegram answered at once; handling runs
+ * here, outside the request.
+ *
+ * Updates of one chat run one after another, in `update_id` order; different
+ * chats run side by side up to `maxConcurrent`. An attempt holds a lease that
+ * is renewed while its handler lives; a sweep takes over what was left —
+ * `pending` whose process never got to it, `failed` whose retry is due,
+ * `processing` whose lease nobody renewed. Delivery is at least once: a
+ * handler that finished but could not be recorded as finished runs again.
+ */
+import type { TelegramUpdateStore } from './update-store.js';
+import type { TelegramUpdateAcceptance } from './webhook.js';
+/** An update as Telegram sends it; name grammY's `Update` to get its full type. */
+export interface TelegramUpdateEnvelope {
+    readonly update_id: number;
+}
+export interface TelegramUpdateFailure {
+    readonly updateId: number;
+    readonly attempt: number;
+    readonly error: unknown;
+    /** `false` when the update was abandoned — no attempt follows. */
+    readonly retrying: boolean;
+}
+export type TelegramUpdateStoreStep = 'claim' | 'renew' | 'settle' | 'sweep';
+export interface TelegramUpdateIntakeConfig<TUpdate extends TelegramUpdateEnvelope> {
+    readonly store: TelegramUpdateStore;
+    /**
+     * Handle one update — with grammY, `(update) => bot.handleUpdate(update)`.
+     * A grammY `BotError` is unwrapped: `retry`, `onFailure` and the stored
+     * error see what the middleware threw.
+     */
+    readonly handle: (update: TUpdate) => unknown;
+    /**
+     * After a failed attempt: milliseconds until the next, or `false` to
+     * abandon the update. Default: abandon what Telegram said repeating cannot
+     * fix (a refused message, a blocked user), wait Telegram's `retry_after`
+     * when it gave one, otherwise back off 5 s, 20 s, 80 s … up to 15 minutes.
+     */
+    readonly retry?: (error: unknown, attempt: number) => number | false;
+    /** Default 5. */
+    readonly maxAttempts?: number;
+    /** How long an attempt holds its update without renewing. Default 120 000; renewed every quarter. */
+    readonly leaseMs?: number;
+    /** How long a `pending` update waits for this process before a sweep takes it. Default 60 000. */
+    readonly pendingGraceMs?: number;
+    /** Default 30 000. */
+    readonly sweepEveryMs?: number;
+    /** How long finished updates are remembered to refuse Telegram's repeats. Default 24 h. */
+    readonly retainMs?: number;
+    /** Chats handled at once. Default 32. */
+    readonly maxConcurrent?: number;
+    /** Every failed attempt. */
+    readonly onFailure?: (failure: TelegramUpdateFailure) => void;
+    /** The store refused a step; the update is retried when its lease lapses. */
+    readonly onStoreError?: (error: unknown, step: TelegramUpdateStoreStep) => void;
+    /** Default `Date.now`. */
+    readonly now?: () => number;
+}
+export interface TelegramUpdateIntake {
+    /** Record one webhook body; handling starts after, once the intake is started. */
+    accept(body: string): Promise<TelegramUpdateAcceptance>;
+    /** Start handling, beginning with everything recorded before. */
+    start(): Promise<void>;
+    /** Take over what is due now; how many updates were scheduled. */
+    sweep(): Promise<number>;
+    /** Resolves once nothing is scheduled. */
+    idle(): Promise<void>;
+    /** Stop scheduling and wait for the handlers in flight. */
+    close(): Promise<void>;
+}
+export declare function createTelegramUpdateIntake<TUpdate extends TelegramUpdateEnvelope>(config: TelegramUpdateIntakeConfig<TUpdate>): TelegramUpdateIntake;
+//# sourceMappingURL=update-intake.d.ts.map

package/dist/telegram/update-intake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-intake.d.ts","sourceRoot":"","sources":["../../src/telegram/update-intake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAE1D,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7E,MAAM,WAAW,0BAA0B,CAAC,OAAO,SAAS,sBAAsB;IAChF,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,KAAK,CAAC;IACrE,iBAAiB;IACjB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,sBAAsB;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC9D,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAChF,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACxD,iEAAiE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,0CAA0C;IAC1C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,2DAA2D;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAsED,wBAAgB,0BAA0B,CAAC,OAAO,SAAS,sBAAsB,EAC/E,MAAM,EAAE,0BAA0B,CAAC,OAAO,CAAC,GAC1C,oBAAoB,CAiJtB"}

package/dist/telegram/update-store-check.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The rules of `TelegramUpdateStore`, as a check any store can be put
+ * through — the ones shipped here and an application's own over its ORM.
+ *
+ * A store is five conditional statements, and each is easy to write almost
+ * right: a claim that does not check the lease, a settle that does not check
+ * the attempt, a claim read and then written in two statements so that two
+ * processes both take one update. Nothing fails in a test with one process;
+ * the update simply runs twice in production. So the check runs every rule on
+ * a fresh store, and races claims against each other.
+ *
+ * It does not depend on a test framework: it returns what was violated, and
+ * an empty list is a store that keeps the rules.
+ */
+import type { TelegramUpdateStore } from './update-store.js';
+/**
+ * Put a store through every rule, each on a fresh store from `make`. Resolves
+ * with the violations — `"<rule>: <what happened>"` — empty when the store
+ * keeps them all. A store that throws violates the rule it threw in.
+ */
+export declare function checkTelegramUpdateStore(make: () => TelegramUpdateStore | Promise<TelegramUpdateStore>): Promise<string[]>;
+//# sourceMappingURL=update-store-check.d.ts.map

package/dist/telegram/update-store-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-store-check.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAqG1D;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,GAC7D,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnB"}

package/dist/telegram/update-store-postgres.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The update store in Postgres, through whatever client the application
+ * already holds — one function that runs a statement with `$n` parameters and
+ * returns its rows:
+ *
+ * - Bun: `(text, parameters) => sql.unsafe(text, [...parameters])`
+ * - Prisma: `(text, parameters) => prisma.$queryRawUnsafe(text, ...parameters)`
+ * - `pg`: `(text, parameters) => pool.query(text, [...parameters]).then((result) => result.rows)`
+ *
+ * Each rule of `TelegramUpdateStore` is one conditional statement, so a claim
+ * is atomic across every process sharing the table; every statement returns
+ * rows, so a client that has only a "query" call needs nothing else.
+ * Parameters carry explicit casts: a driver that sends a JS number as a
+ * double still lands in a `bigint` column.
+ */
+import type { TelegramUpdateStore } from './update-store.js';
+/** Run one statement with `$1…$n` parameters; resolve with the rows it returned. */
+export type TelegramPostgresQuery = (text: string, parameters: readonly (string | number | null)[]) => Promise<readonly unknown[]>;
+export interface PostgresTelegramUpdateStoreConfig {
+    readonly query: TelegramPostgresQuery;
+    /** Default `telegram_updates`. */
+    readonly table?: string;
+    /**
+     * Create the table on first use when it is missing. Default `true`; set
+     * `false` when migrations own the schema — `postgresTelegramUpdateStoreSchema`
+     * is the statement to put in one.
+     */
+    readonly createTable?: boolean;
+}
+/** The table and its index, for a migration. Safe to run twice. */
+export declare function postgresTelegramUpdateStoreSchema(table?: string): string;
+export declare function postgresTelegramUpdateStore(config: PostgresTelegramUpdateStoreConfig): TelegramUpdateStore;
+//# sourceMappingURL=update-store-postgres.d.ts.map

package/dist/telegram/update-store-postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-store-postgres.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAA4B,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEpF,oFAAoF;AACpF,MAAM,MAAM,qBAAqB,GAAG,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,KAC5C,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AAEjC,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAaD,mEAAmE;AACnE,wBAAgB,iCAAiC,CAAC,KAAK,SAAqB,GAAG,MAAM,CAapF;AAqBD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,iCAAiC,GACxC,mBAAmB,CAyGrB"}

package/dist/telegram/update-store-sqlite.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The update store in SQLite, through the database handle the application
+ * already opened — `bun:sqlite`'s `Database` or `node:sqlite`'s `DatabaseSync`
+ * as it is. The module imports neither, so it runs wherever its caller does.
+ *
+ * Each rule of `TelegramUpdateStore` is one conditional statement, so a claim
+ * is atomic across processes sharing the file.
+ */
+import type { TelegramUpdateStore } from './update-store.js';
+/** What this store needs of a SQLite handle; both runtimes' handles have it. */
+export interface TelegramSqliteDatabase {
+    exec(sql: string): unknown;
+    prepare(sql: string): {
+        run(...parameters: (string | number | null)[]): {
+            readonly changes: number | bigint;
+        };
+        all(...parameters: (string | number | null)[]): unknown[];
+    };
+}
+export interface SqliteTelegramUpdateStoreConfig {
+    readonly database: TelegramSqliteDatabase;
+    /** Default `telegram_updates`. Created when missing. */
+    readonly table?: string;
+}
+export declare function sqliteTelegramUpdateStore(config: SqliteTelegramUpdateStoreConfig): TelegramUpdateStore;
+//# sourceMappingURL=update-store-sqlite.d.ts.map

package/dist/telegram/update-store-sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-store-sqlite.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAGV,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAExB,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,GAAG,CAAC,GAAG,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG;YAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC;QACtF,GAAG,CAAC,GAAG,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC;KAC3D,CAAC;CACH;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAiBD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,+BAA+B,GACtC,mBAAmB,CAkFrB"}