@emulon/telegram 0.2.0

package/esm/model/updates.js

@@ -0,0 +1,354 @@
+// Bot API objects are snake_case on the wire.
+// deno-lint-ignore-file camelcase
+import { z } from 'zod';
+import { DomainError } from 'emulon';
+import { botSchema } from './bots.js';
+/**
+ * Every update type typed by `@grammyjs/types@3.28.0`; a test keeps this list
+ * equal to those types. Only `message_reaction_count` is ever generated.
+ */
+export const updateTypes = [
+    'message',
+    'edited_message',
+    'channel_post',
+    'edited_channel_post',
+    'business_connection',
+    'business_message',
+    'edited_business_message',
+    'deleted_business_messages',
+    'guest_message',
+    'message_reaction',
+    'message_reaction_count',
+    'inline_query',
+    'chosen_inline_result',
+    'callback_query',
+    'shipping_query',
+    'pre_checkout_query',
+    'poll',
+    'poll_answer',
+    'my_chat_member',
+    'chat_member',
+    'managed_bot',
+    'chat_join_request',
+    'chat_boost',
+    'removed_chat_boost',
+    'purchased_paid_media',
+];
+/** The reaction emoji typed by `@grammyjs/types@3.28.0`. */
+export const reactionEmoji = [
+    '👍',
+    '👎',
+    '❤',
+    '🔥',
+    '🥰',
+    '👏',
+    '😁',
+    '🤔',
+    '🤯',
+    '😱',
+    '🤬',
+    '😢',
+    '🎉',
+    '🤩',
+    '🤮',
+    '💩',
+    '🙏',
+    '👌',
+    '🕊',
+    '🤡',
+    '🥱',
+    '🥴',
+    '😍',
+    '🐳',
+    '❤‍🔥',
+    '🌚',
+    '🌭',
+    '💯',
+    '🤣',
+    '⚡',
+    '🍌',
+    '🏆',
+    '💔',
+    '🤨',
+    '😐',
+    '🍓',
+    '🍾',
+    '💋',
+    '🖕',
+    '😈',
+    '😴',
+    '😭',
+    '🤓',
+    '👻',
+    '👨‍💻',
+    '👀',
+    '🎃',
+    '🙈',
+    '😇',
+    '😨',
+    '🤝',
+    '✍',
+    '🤗',
+    '🫡',
+    '🎅',
+    '🎄',
+    '☃',
+    '💅',
+    '🤪',
+    '🗿',
+    '🆒',
+    '💘',
+    '🙉',
+    '🦄',
+    '😘',
+    '💊',
+    '🙊',
+    '😎',
+    '👾',
+    '🤷‍♂',
+    '🤷',
+    '🤷‍♀',
+    '😡',
+];
+export const reactionTypeSchema = z
+    .discriminatedUnion('type', [
+    z.strictObject({ type: z.literal('emoji'), emoji: z.enum(reactionEmoji) }),
+    z.strictObject({
+        type: z.literal('custom_emoji'),
+        custom_emoji_id: z.string().regex(/^[0-9]{1,20}$/),
+    }),
+    z.strictObject({ type: z.literal('paid') }),
+]);
+export const reactionCountSchema = z
+    .strictObject({
+    type: reactionTypeSchema,
+    total_count: z.number().int().nonnegative().safe(),
+});
+export const updateSchema = z.strictObject({
+    update_id: z.number().int().positive().safe(),
+    message_reaction_count: z.strictObject({
+        chat: z.strictObject({
+            id: z.number().int(),
+            title: z.string(),
+            username: z.string(),
+            type: z.literal('channel'),
+        }),
+        message_id: z.number().int().positive(),
+        date: z.number().int().nonnegative(),
+        reactions: z.array(reactionCountSchema),
+    }),
+});
+/** A rejected `getUpdates`; descriptions are fixed and never echo input. */
+export class UpdatesError extends Error {
+    status;
+    description;
+    constructor(status, description) {
+        super(description);
+        this.status = status;
+        this.description = description;
+    }
+}
+export const updatesErrors = {
+    invalid: () => new UpdatesError(400, 'Bad Request: invalid parameter value'),
+    limit: () => new UpdatesError(400, 'Bad Request: limit must be between 1 and 100'),
+    allowedUpdates: () => new UpdatesError(400, 'Bad Request: invalid allowed_updates'),
+    unsupported: () => new UpdatesError(501, 'Not Implemented: parameter is not emulated'),
+    conflict: () => new UpdatesError(409, 'Conflict: terminated by other getUpdates request; make sure that only one bot instance is running'),
+    cancelled: () => new UpdatesError(503, 'Service Unavailable: the request was cancelled'),
+};
+const accepted = new Set(['offset', 'limit', 'timeout', 'allowed_updates']);
+const known = new Set(updateTypes);
+const isInteger = (value) => typeof value === 'number' && Number.isSafeInteger(value);
+/** Only the documented polling fields; anything else is refused, not ignored. */
+export function updatesRequest(params) {
+    if (Object.keys(params).some((key) => !accepted.has(key))) {
+        throw updatesErrors.unsupported();
+    }
+    const { offset, limit, timeout, allowed_updates } = params;
+    const request = { limit: 100, timeout: 0 };
+    if (offset !== undefined) {
+        if (!isInteger(offset)) {
+            throw updatesErrors.invalid();
+        }
+        request.offset = offset;
+    }
+    if (limit !== undefined) {
+        if (!isInteger(limit) || limit < 1 || limit > 100) {
+            throw updatesErrors.limit();
+        }
+        request.limit = limit;
+    }
+    if (timeout !== undefined) {
+        if (!isInteger(timeout) || timeout < 0) {
+            throw updatesErrors.invalid();
+        }
+        request.timeout = timeout;
+    }
+    if (allowed_updates !== undefined) {
+        if (!Array.isArray(allowed_updates) ||
+            allowed_updates.some((type) => typeof type !== 'string' || !known.has(type))) {
+            throw updatesErrors.allowedUpdates();
+        }
+        request.allowedUpdates = [...new Set(allowed_updates)];
+    }
+    return request;
+}
+const queueSchema = z.strictObject({
+    nextUpdateId: z.number().int().positive().safe(),
+    allowedUpdates: z.array(z.enum(updateTypes)),
+});
+const storedUpdateSchema = z.strictObject({
+    botId: z.number().int().positive().safe(),
+    update: updateSchema,
+});
+/** Update IDs sort as text in store order and as numbers in the key. */
+const updateKey = (botId, updateId) => `${botId}:${String(updateId).padStart(16, '0')}`;
+export async function queueOf(tx, botId) {
+    const row = await tx.get('updateQueues', String(botId));
+    return row === undefined
+        ? { nextUpdateId: 1, allowedUpdates: [] }
+        : queueSchema.parse(row);
+}
+export function receives(queue, type) {
+    return queue.allowedUpdates.includes(type);
+}
+/** The bot's queued updates in ID order. */
+export async function queued(tx, botId) {
+    return (await tx.list('updates'))
+        .map((row) => storedUpdateSchema.parse(row.value))
+        .filter((row) => row.botId === botId)
+        .map((row) => row.update)
+        .sort((a, b) => a.update_id - b.update_id);
+}
+/** Allocates the next update ID of one bot and queues the update it builds. */
+export async function enqueue(tx, botId, queue, build) {
+    const update = build(queue.nextUpdateId);
+    await tx.put({
+        collection: 'updateQueues',
+        id: String(botId),
+        value: { ...queue, nextUpdateId: queue.nextUpdateId + 1 },
+    });
+    await tx.put({
+        collection: 'updates',
+        id: updateKey(botId, update.update_id),
+        value: { botId, update },
+    });
+}
+/**
+ * The first read of a `getUpdates` call: it confirms by offset, replaces the
+ * subscription when one is given, then returns the head of the queue without
+ * confirming it.
+ */
+export async function takeUpdates(tx, botId, request) {
+    let updates = await queued(tx, botId);
+    if (request.offset !== undefined) {
+        const forgotten = request.offset < 0
+            ? updates.slice(0, Math.max(0, updates.length + request.offset))
+            : updates.filter((update) => update.update_id < request.offset);
+        for (const update of forgotten) {
+            await tx.delete('updates', updateKey(botId, update.update_id));
+        }
+        updates = updates.slice(forgotten.length);
+    }
+    if (request.allowedUpdates !== undefined) {
+        await tx.put({
+            collection: 'updateQueues',
+            id: String(botId),
+            value: {
+                ...await queueOf(tx, botId),
+                allowedUpdates: request.allowedUpdates,
+            },
+        });
+    }
+    return updates.slice(0, request.limit);
+}
+/** `setTimeout` accepts at most a signed 32-bit millisecond delay. */
+const maxDelay = 2 ** 31 - 1;
+/**
+ * Waits on real time for committed updates. The store listener is attached
+ * before every read, so a commit between the read and the wait is not lost.
+ * Cancellation is an error, never an empty batch: after a reset the caller
+ * must not mistake a cancelled poll for a drained queue.
+ */
+export async function pollUpdates(store, botId, request, signal) {
+    const deadline = performance.now() + request.timeout * 1000;
+    let changed = false;
+    let wake = () => { };
+    const unsubscribe = store.subscribe(() => {
+        changed = true;
+        wake();
+    });
+    const cancel = () => wake();
+    signal.addEventListener('abort', cancel);
+    try {
+        let first = true;
+        while (true) {
+            if (signal.aborted) {
+                throw updatesErrors.cancelled();
+            }
+            changed = false;
+            let batch;
+            try {
+                batch = await store.transaction((tx) => first
+                    ? takeUpdates(tx, botId, request)
+                    : takeUpdates(tx, botId, { limit: request.limit }));
+            }
+            catch (error) {
+                throw signal.aborted ? updatesErrors.cancelled() : error;
+            }
+            first = false;
+            if (signal.aborted) {
+                throw updatesErrors.cancelled();
+            }
+            const remaining = deadline - performance.now();
+            if (batch.length > 0 || remaining <= 0) {
+                return batch;
+            }
+            if (!changed) {
+                let timer;
+                await new Promise((resolve) => {
+                    wake = resolve;
+                    timer = setTimeout(resolve, Math.min(remaining, maxDelay));
+                });
+                clearTimeout(timer);
+                wake = () => { };
+            }
+        }
+    }
+    finally {
+        signal.removeEventListener('abort', cancel);
+        unsubscribe();
+    }
+}
+export const inspectInput = z
+    .strictObject({
+    botId: z.number().int().positive().safe(),
+    limit: z.number().int().min(1).max(100).optional(),
+});
+export const queueViewSchema = z.strictObject({
+    botId: z.number().int().positive().safe(),
+    allowedUpdates: z.array(z.enum(updateTypes)),
+    pending: z.number().int().nonnegative(),
+    updates: z.array(updateSchema),
+});
+/**
+ * The oldest `limit` pending updates (default 100) and the subscription of one
+ * bot. Reading confirms nothing and shows no credential.
+ */
+export async function inspectUpdates(store, raw) {
+    const input = inspectInput.parse(raw);
+    return await store.transaction(async (tx) => {
+        const row = await tx.get('bots', String(input.botId));
+        if (row === undefined) {
+            throw new DomainError('BOT_NOT_FOUND', 'No such bot.');
+        }
+        const bot = botSchema.parse(row);
+        const updates = await queued(tx, bot.id);
+        return {
+            botId: bot.id,
+            allowedUpdates: (await queueOf(tx, bot.id)).allowedUpdates,
+            pending: updates.length,
+            updates: updates.slice(0, input.limit ?? 100),
+        };
+    });
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/routes/api.d.ts

@@ -0,0 +1,31 @@
+import type { Hono } from 'hono';
+import type { PluginContext } from 'emulon';
+/**
+ * A Bot API failure. Descriptions are fixed strings: the request path carries
+ * the bot token, so no failure may echo the path, the token or caller input.
+ */
+export declare class BotApiError extends Error {
+    readonly status: number;
+    readonly description: string;
+    constructor(status: number, description: string);
+}
+export declare const notFound: () => BotApiError;
+export declare const unauthorized: () => BotApiError;
+export declare const unsupportedMethod: () => BotApiError;
+export declare const unsupportedTransport: () => BotApiError;
+export declare const unsupportedParameter: () => BotApiError;
+export declare const invalidBody: () => BotApiError;
+export declare function success(result: unknown): Response;
+export declare function failure(error: unknown): Response;
+/** Exactly one `bot<token>/<method>` pair; anything else is not a Bot API path. */
+export declare function parseRoute(pathname: string): {
+    token: string;
+    method: string;
+} | null;
+/** grammY sends `application/json`, optionally with a charset parameter. */
+export declare function isJson(contentType: string | null): boolean;
+/**
+ * The token is checked before the method is resolved, so an unknown or
+ * unsupported method reveals nothing to a caller without a valid token.
+ */
+export declare function routes(ctx: PluginContext, api: Hono): void;

package/esm/routes/api.js

@@ -0,0 +1,128 @@
+import { parseToken } from '../auth/tokens.js';
+import { authenticate, botUser } from '../model/bots.js';
+import { SendError, sendMessage, sendRequest } from '../model/messages.js';
+import { pollUpdates, UpdatesError, updatesErrors, updatesRequest, } from '../model/updates.js';
+import { knownMethod } from './methods.js';
+/**
+ * A Bot API failure. Descriptions are fixed strings: the request path carries
+ * the bot token, so no failure may echo the path, the token or caller input.
+ */
+export class BotApiError extends Error {
+    status;
+    description;
+    constructor(status, description) {
+        super(description);
+        this.status = status;
+        this.description = description;
+    }
+}
+export const notFound = () => new BotApiError(404, 'Not Found');
+export const unauthorized = () => new BotApiError(401, 'Unauthorized');
+export const unsupportedMethod = () => new BotApiError(501, 'Not Implemented: method is not emulated');
+export const unsupportedTransport = () => new BotApiError(501, 'Not Implemented: only POST requests with a JSON body are emulated');
+export const unsupportedParameter = () => new BotApiError(501, 'Not Implemented: parameter is not emulated');
+export const invalidBody = () => new BotApiError(400, 'Bad Request: request body must be a JSON object');
+export function success(result) {
+    return Response.json({ ok: true, result });
+}
+export function failure(error) {
+    const known = error instanceof BotApiError || error instanceof SendError ||
+        error instanceof UpdatesError
+        ? error
+        : new BotApiError(500, 'Internal Server Error');
+    return Response.json({
+        ok: false,
+        error_code: known.status,
+        description: known.description,
+    }, { status: known.status });
+}
+/** Exactly one `bot<token>/<method>` pair; anything else is not a Bot API path. */
+export function parseRoute(pathname) {
+    const match = /^\/bot([^/]+)\/([^/]+)$/.exec(pathname);
+    return match ? { token: match[1], method: match[2] } : null;
+}
+/** grammY sends `application/json`, optionally with a charset parameter. */
+export function isJson(contentType) {
+    return contentType?.split(';')[0]?.trim().toLowerCase() ===
+        'application/json';
+}
+const handlers = {
+    getMe(params, bot) {
+        if (Object.keys(params).length > 0) {
+            throw unsupportedParameter();
+        }
+        return botUser(bot);
+    },
+    sendMessage(params, bot, { store, now }) {
+        return sendMessage(store, bot, sendRequest(params), now);
+    },
+    async getUpdates(params, bot, { store, signal, polling }) {
+        const request = updatesRequest(params);
+        // A second reader would race the first for confirmations.
+        if (polling.has(bot.id)) {
+            throw updatesErrors.conflict();
+        }
+        polling.add(bot.id);
+        try {
+            return await pollUpdates(store, bot.id, request, signal());
+        }
+        finally {
+            polling.delete(bot.id);
+        }
+    },
+};
+async function params(request) {
+    if (request.method !== 'POST' || !isJson(request.headers.get('content-type'))) {
+        throw unsupportedTransport();
+    }
+    let body;
+    try {
+        body = JSON.parse(await request.text());
+    }
+    catch {
+        throw invalidBody();
+    }
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        throw invalidBody();
+    }
+    return body;
+}
+/**
+ * The token is checked before the method is resolved, so an unknown or
+ * unsupported method reveals nothing to a caller without a valid token.
+ */
+export function routes(ctx, api) {
+    const polling = new Set();
+    api.all('*', async (c) => {
+        const store = ctx.store.scope();
+        try {
+            const route = parseRoute(new URL(c.req.url).pathname);
+            const token = route && parseToken(route.token);
+            if (!route || !token) {
+                throw notFound();
+            }
+            const bot = await authenticate(store, token);
+            if (!bot) {
+                throw unauthorized();
+            }
+            const method = knownMethod(route.method);
+            if (!method) {
+                throw notFound();
+            }
+            const handler = handlers[method];
+            if (!handler) {
+                throw unsupportedMethod();
+            }
+            return success(await handler(await params(c.req.raw), bot, {
+                store,
+                now: ctx.clock.now(),
+                signal: () => c.req.raw.signal,
+                polling,
+            }));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    api.onError(() => failure(undefined));
+}

package/esm/routes/methods.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Every Bot API method typed by `@grammyjs/types@3.28.0`, the types package of
+ * the pinned `grammy@1.44.0`. A test keeps this list equal to those types.
+ * Known methods the slice does not implement fail with an explicit 501 instead
+ * of the 404 that an unknown method receives.
+ */
+export declare const knownMethods: readonly ["getUpdates", "setWebhook", "deleteWebhook", "getWebhookInfo", "getMe", "logOut", "close", "sendMessage", "sendRichMessage", "forwardMessage", "forwardMessages", "copyMessage", "copyMessages", "sendPhoto", "sendLivePhoto", "sendAudio", "sendDocument", "sendVideo", "sendAnimation", "sendVoice", "sendVideoNote", "sendPaidMedia", "sendMediaGroup", "sendLocation", "editMessageLiveLocation", "stopMessageLiveLocation", "sendVenue", "sendContact", "sendPoll", "sendChecklist", "editMessageChecklist", "sendDice", "sendMessageDraft", "sendRichMessageDraft", "sendChatAction", "setMessageReaction", "getUserProfilePhotos", "getUserProfileAudios", "setUserEmojiStatus", "getFile", "banChatMember", "kickChatMember", "unbanChatMember", "restrictChatMember", "promoteChatMember", "setChatAdministratorCustomTitle", "setChatMemberTag", "banChatSenderChat", "unbanChatSenderChat", "setChatPermissions", "exportChatInviteLink", "createChatInviteLink", "editChatInviteLink", "createChatSubscriptionInviteLink", "editChatSubscriptionInviteLink", "revokeChatInviteLink", "approveChatJoinRequest", "declineChatJoinRequest", "answerChatJoinRequestQuery", "sendChatJoinRequestWebApp", "approveSuggestedPost", "declineSuggestedPost", "setChatPhoto", "deleteChatPhoto", "setChatTitle", "setChatDescription", "pinChatMessage", "unpinChatMessage", "unpinAllChatMessages", "leaveChat", "getChat", "getChatAdministrators", "getChatMemberCount", "getChatMembersCount", "getChatMember", "getUserPersonalChatMessages", "setChatStickerSet", "deleteChatStickerSet", "getForumTopicIconStickers", "createForumTopic", "editForumTopic", "closeForumTopic", "reopenForumTopic", "deleteForumTopic", "unpinAllForumTopicMessages", "editGeneralForumTopic", "closeGeneralForumTopic", "reopenGeneralForumTopic", "hideGeneralForumTopic", "unhideGeneralForumTopic", "unpinAllGeneralForumTopicMessages", "answerCallbackQuery", "answerGuestQuery", "getUserChatBoosts", "getUserGifts", "getChatGifts", "getBusinessConnection", "getManagedBotToken", "replaceManagedBotToken", "getManagedBotAccessSettings", "setManagedBotAccessSettings", "setMyCommands", "deleteMyCommands", "getMyCommands", "setMyName", "getMyName", "setMyDescription", "getMyDescription", "setMyShortDescription", "getMyShortDescription", "setMyProfilePhoto", "removeMyProfilePhoto", "setChatMenuButton", "getChatMenuButton", "setMyDefaultAdministratorRights", "getMyDefaultAdministratorRights", "getMyStarBalance", "editMessageText", "editMessageCaption", "editMessageMedia", "editMessageReplyMarkup", "stopPoll", "deleteMessage", "deleteMessages", "deleteMessageReaction", "deleteAllMessageReactions", "deleteBusinessMessages", "setBusinessAccountName", "setBusinessAccountUsername", "setBusinessAccountBio", "setBusinessAccountProfilePhoto", "removeBusinessAccountProfilePhoto", "setBusinessAccountGiftSettings", "getBusinessAccountStarBalance", "transferBusinessAccountStars", "getBusinessAccountGifts", "convertGiftToStars", "upgradeGift", "transferGift", "postStory", "repostStory", "editStory", "deleteStory", "sendSticker", "getStickerSet", "getCustomEmojiStickers", "uploadStickerFile", "createNewStickerSet", "addStickerToSet", "setStickerPositionInSet", "deleteStickerFromSet", "replaceStickerInSet", "setStickerEmojiList", "setStickerKeywords", "setStickerMaskPosition", "setStickerSetTitle", "deleteStickerSet", "setStickerSetThumbnail", "setCustomEmojiStickerSetThumbnail", "getAvailableGifts", "sendGift", "giftPremiumSubscription", "answerInlineQuery", "answerWebAppQuery", "savePreparedInlineMessage", "savePreparedKeyboardButton", "sendInvoice", "createInvoiceLink", "answerShippingQuery", "answerPreCheckoutQuery", "getStarTransactions", "refundStarPayment", "editUserStarSubscription", "verifyUser", "verifyChat", "removeUserVerification", "removeChatVerification", "readBusinessMessage", "setPassportDataErrors", "sendGame", "setGameScore", "getGameHighScores"];
+export type KnownMethod = typeof knownMethods[number];
+/** Bot API method names are case-insensitive. */
+export declare function knownMethod(name: string): KnownMethod | undefined;