@emulon/telegram 0.2.0

package/esm/model/messages.js

@@ -0,0 +1,269 @@
+// Bot API objects are snake_case on the wire.
+// deno-lint-ignore-file camelcase
+import { z } from 'zod';
+import { DomainError } from 'emulon';
+import { MarkdownError, parseMarkdownV2, } from '../format/markdown_v2.js';
+import { botUser } from './bots.js';
+import { channelSchema, usernameKey } from './channels.js';
+/** Telegram's limit on message text, in UTF-16 code units after parsing. */
+export const maxTextLength = 4096;
+/**
+ * A rejected send. The route turns it into a Bot API envelope; the reason is
+ * one of the fixed descriptions below and never contains caller input.
+ */
+export class SendError extends Error {
+    status;
+    description;
+    constructor(status, description) {
+        super(description);
+        this.status = status;
+        this.description = description;
+    }
+}
+const badRequest = (reason) => new SendError(400, `Bad Request: ${reason}`);
+export const sendErrors = {
+    parse: () => badRequest("can't parse entities"),
+    tooLong: () => badRequest('message is too long'),
+    empty: () => badRequest('message text is empty'),
+    chatEmpty: () => badRequest('chat_id is empty'),
+    chatNotFound: () => badRequest('chat not found'),
+    parseMode: () => badRequest('unsupported parse_mode'),
+    invalid: () => badRequest('invalid parameter value'),
+    unsupported: () => new SendError(501, 'Not Implemented: parameter is not emulated'),
+    unsupportedMode: () => new SendError(501, 'Not Implemented: parse mode is not emulated'),
+};
+/**
+ * Parsing comes before the length rule, so malformed markup is reported even
+ * when it is also too long; the limit counts rendered text only.
+ */
+export function render(source, parseMode) {
+    let rendered;
+    if (parseMode === 'MarkdownV2') {
+        try {
+            rendered = parseMarkdownV2(source);
+        }
+        catch (error) {
+            if (error instanceof MarkdownError) {
+                throw sendErrors.parse();
+            }
+            throw error;
+        }
+    }
+    else {
+        rendered = { text: source, entities: [] };
+    }
+    if (rendered.text.length === 0) {
+        throw sendErrors.empty();
+    }
+    if (rendered.text.length > maxTextLength) {
+        throw sendErrors.tooLong();
+    }
+    return rendered;
+}
+export function chatReference(value) {
+    if (typeof value === 'number') {
+        return Number.isSafeInteger(value) ? { id: value } : null;
+    }
+    if (typeof value !== 'string') {
+        return null;
+    }
+    if (/^-?[1-9][0-9]*$/.test(value)) {
+        const id = Number(value);
+        return Number.isSafeInteger(id) ? { id } : null;
+    }
+    return value.startsWith('@') && value.length > 1
+        ? { username: usernameKey(value.slice(1)) }
+        : null;
+}
+const accepted = new Set([
+    'chat_id',
+    'text',
+    'parse_mode',
+    'disable_notification',
+    'link_preview_options',
+]);
+/**
+ * Only the fields the declared consumer sends are emulated. Any other field,
+ * or a value that would change behavior the emulator does not model, is
+ * refused instead of being silently ignored.
+ */
+export function sendRequest(params) {
+    if (Object.keys(params).some((key) => !accepted.has(key))) {
+        throw sendErrors.unsupported();
+    }
+    const { chat_id, text, parse_mode, disable_notification, link_preview_options, } = params;
+    if (disable_notification !== undefined) {
+        if (typeof disable_notification !== 'boolean') {
+            throw sendErrors.invalid();
+        }
+    }
+    if (link_preview_options !== undefined) {
+        if (typeof link_preview_options !== 'object' ||
+            link_preview_options === null || Array.isArray(link_preview_options)) {
+            throw sendErrors.invalid();
+        }
+        const options = link_preview_options;
+        if (Object.keys(options).some((key) => key !== 'is_disabled') ||
+            (options.is_disabled !== undefined && options.is_disabled !== false)) {
+            throw sendErrors.unsupported();
+        }
+    }
+    let parseMode = null;
+    if (parse_mode !== undefined && parse_mode !== '') {
+        if (typeof parse_mode !== 'string') {
+            throw sendErrors.invalid();
+        }
+        // The Bot API compares parse modes without regard to case.
+        const mode = parse_mode.toLowerCase();
+        if (mode === 'html' || mode === 'markdown') {
+            throw sendErrors.unsupportedMode();
+        }
+        if (mode !== 'markdownv2') {
+            throw sendErrors.parseMode();
+        }
+        parseMode = 'MarkdownV2';
+    }
+    if (chat_id === undefined || chat_id === '') {
+        throw sendErrors.chatEmpty();
+    }
+    const chat = chatReference(chat_id);
+    if (!chat) {
+        throw sendErrors.chatNotFound();
+    }
+    if (text === undefined || text === '') {
+        throw sendErrors.empty();
+    }
+    if (typeof text !== 'string') {
+        throw sendErrors.invalid();
+    }
+    return { chat, source: text, parseMode };
+}
+export const entitySchema = z
+    .strictObject({
+    type: z.enum([
+        'bold',
+        'italic',
+        'underline',
+        'strikethrough',
+        'spoiler',
+        'code',
+        'pre',
+        'text_link',
+        'blockquote',
+        'expandable_blockquote',
+    ]),
+    offset: z.number().int().nonnegative(),
+    length: z.number().int().positive(),
+    url: z.string().optional(),
+    language: z.string().optional(),
+});
+export const storedSchema = z
+    .strictObject({
+    chatId: z.number().int(),
+    messageId: z.number().int().positive(),
+    botId: z.number().int().positive(),
+    date: z.number().int().nonnegative(),
+    parseMode: z.literal('MarkdownV2').nullable(),
+    source: z.string(),
+    text: z.string(),
+    entities: z.array(entitySchema),
+});
+export function chatView(channel) {
+    return {
+        id: channel.id,
+        title: channel.title,
+        username: channel.username,
+        type: 'channel',
+    };
+}
+export function messageView(message, channel, bot) {
+    const user = botUser(bot);
+    return {
+        message_id: message.messageId,
+        from: {
+            id: user.id,
+            is_bot: true,
+            first_name: user.first_name,
+            username: user.username,
+        },
+        sender_chat: chatView(channel),
+        chat: chatView(channel),
+        date: message.date,
+        text: message.text,
+        ...(message.entities.length > 0 ? { entities: message.entities } : {}),
+    };
+}
+export async function findChannel(tx, chat) {
+    if ('id' in chat) {
+        const row = await tx.get('channels', String(chat.id));
+        return row === undefined ? null : channelSchema.parse(row);
+    }
+    const channels = (await tx.list('channels')).map((row) => channelSchema.parse(row.value));
+    return channels.find((channel) => usernameKey(channel.username) === chat.username) ?? null;
+}
+/** Message IDs sort as text in store order and as numbers in the key. */
+export const messageKey = (chatId, messageId) => `${chatId}:${String(messageId).padStart(16, '0')}`;
+const sequenceSchema = z.strictObject({
+    next: z.number().int().positive(),
+});
+/**
+ * The chat lookup, rendering, ID allocation and message write share one
+ * transaction: a rejected send leaves no trace and allocates no ID, and
+ * concurrent sends to one chat never share or skip an ID.
+ */
+export async function sendMessage(store, bot, request, now) {
+    return await store.transaction(async (tx) => {
+        const channel = await findChannel(tx, request.chat);
+        if (!channel) {
+            throw sendErrors.chatNotFound();
+        }
+        const rendered = render(request.source, request.parseMode);
+        const sequence = await tx.get('messageSequences', String(channel.id));
+        const messageId = sequence === undefined
+            ? 1
+            : sequenceSchema.parse(sequence).next;
+        const message = {
+            chatId: channel.id,
+            messageId,
+            botId: bot.id,
+            date: Math.floor(now / 1000),
+            parseMode: request.parseMode,
+            source: request.source,
+            text: rendered.text,
+            entities: rendered.entities,
+        };
+        await tx.put({
+            collection: 'messageSequences',
+            id: String(channel.id),
+            value: { next: messageId + 1 },
+        });
+        await tx.put({
+            collection: 'messages',
+            id: messageKey(channel.id, messageId),
+            value: message,
+        });
+        return messageView(message, channel, bot);
+    });
+}
+export const listInput = z.strictObject({
+    chatId: z.number().int(),
+    limit: z.number().int().min(1).max(100).optional(),
+});
+/**
+ * The most recent `limit` messages (default 100) of one channel, oldest
+ * first, so a multipart post reads in the order it was sent.
+ */
+export async function listMessages(store, raw) {
+    const input = listInput.parse(raw);
+    return await store.transaction(async (tx) => {
+        const channel = await findChannel(tx, { id: input.chatId });
+        if (!channel) {
+            throw new DomainError('CHAT_NOT_FOUND', 'No such channel.');
+        }
+        const messages = (await tx.list('messages'))
+            .map((row) => storedSchema.parse(row.value))
+            .filter((message) => message.chatId === channel.id)
+            .sort((a, b) => a.messageId - b.messageId);
+        return messages.slice(-(input.limit ?? 100));
+    });
+}

package/esm/model/reactions.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { type PluginContext } from 'emulon';
+import { type ReactionCount } from './updates.js';
+type Store = PluginContext['store'];
+export declare const reactionsInput: z.ZodType<ReactionsInput, ReactionsInput>;
+export interface ReactionsInput {
+    chatId: number;
+    messageId: number;
+    reactions: ReactionCount[];
+}
+export interface ReactionsResult {
+    chatId: number;
+    messageId: number;
+    reactions: ReactionCount[];
+    changed: boolean;
+    queued: number;
+}
+export declare const reactionsResultSchema: z.ZodType<ReactionsResult, ReactionsResult>;
+/**
+ * The stored form of an absolute snapshot: zero counts are dropped, and the
+ * rest are ordered by count, then paid before emoji before custom emoji, then
+ * by emoji or ID, so equal snapshots compare equal. A type listed twice is
+ * ambiguous and refused.
+ */
+export declare function normalizeReactions(reactions: readonly ReactionCount[]): ReactionCount[];
+/**
+ * Replaces a message's aggregate counts. The check of the target, the counts
+ * and the update of every subscribed bot commit together, so a poll either
+ * sees the new counts in its queue or not at all. An unchanged snapshot queues
+ * nothing.
+ */
+export declare function setReactions(store: Store, raw: ReactionsInput, now: number): Promise<ReactionsResult>;
+export {};

package/esm/model/reactions.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { DomainError } from 'emulon';
+import { botSchema } from './bots.js';
+import { chatView, findChannel, messageKey } from './messages.js';
+import { enqueue, queueOf, reactionCountSchema, receives, } from './updates.js';
+export const reactionsInput = z
+    .strictObject({
+    chatId: z.number().int(),
+    messageId: z.number().int().positive().safe(),
+    reactions: z.array(reactionCountSchema).max(100),
+});
+export const reactionsResultSchema = z.strictObject({
+    chatId: z.number().int(),
+    messageId: z.number().int().positive(),
+    reactions: z.array(reactionCountSchema),
+    changed: z.boolean(),
+    queued: z.number().int().nonnegative(),
+});
+const kinds = ['paid', 'emoji', 'custom_emoji'];
+function canonicalType(type) {
+    switch (type.type) {
+        case 'emoji':
+            return { type: 'emoji', emoji: type.emoji };
+        case 'custom_emoji':
+            return { type: 'custom_emoji', custom_emoji_id: type.custom_emoji_id };
+        case 'paid':
+            return { type: 'paid' };
+    }
+}
+const reactionKey = (type) => `${type.type}:${reactionId(type)}`;
+function reactionId(type) {
+    switch (type.type) {
+        case 'emoji':
+            return type.emoji;
+        case 'custom_emoji':
+            return type.custom_emoji_id;
+        case 'paid':
+            return '';
+    }
+}
+/**
+ * The stored form of an absolute snapshot: zero counts are dropped, and the
+ * rest are ordered by count, then paid before emoji before custom emoji, then
+ * by emoji or ID, so equal snapshots compare equal. A type listed twice is
+ * ambiguous and refused.
+ */
+export function normalizeReactions(reactions) {
+    const seen = new Set();
+    for (const { type } of reactions) {
+        const key = reactionKey(type);
+        if (seen.has(key)) {
+            throw new DomainError('DUPLICATE_REACTION', 'Each reaction type may appear only once.');
+        }
+        seen.add(key);
+    }
+    const id = (reaction) => reactionId(reaction.type);
+    return reactions
+        .filter((reaction) => reaction.total_count > 0)
+        .map((reaction) => ({
+        type: canonicalType(reaction.type),
+        total_count: reaction.total_count,
+    }))
+        .sort((a, b) => b.total_count - a.total_count ||
+        kinds.indexOf(a.type.type) - kinds.indexOf(b.type.type) ||
+        (id(a) < id(b) ? -1 : id(a) > id(b) ? 1 : 0));
+}
+function sameReactions(a, b) {
+    return a.length === b.length &&
+        a.every((reaction, index) => reactionKey(reaction.type) === reactionKey(b[index].type) &&
+            reaction.total_count === b[index].total_count);
+}
+const storedSchema = z.strictObject({
+    reactions: z.array(reactionCountSchema),
+});
+/**
+ * Replaces a message's aggregate counts. The check of the target, the counts
+ * and the update of every subscribed bot commit together, so a poll either
+ * sees the new counts in its queue or not at all. An unchanged snapshot queues
+ * nothing.
+ */
+export async function setReactions(store, raw, now) {
+    const input = reactionsInput.parse(raw);
+    const reactions = normalizeReactions(input.reactions);
+    return await store.transaction(async (tx) => {
+        const channel = await findChannel(tx, { id: input.chatId });
+        if (!channel) {
+            throw new DomainError('CHAT_NOT_FOUND', 'No such channel.');
+        }
+        const key = messageKey(channel.id, input.messageId);
+        if (await tx.get('messages', key) === undefined) {
+            throw new DomainError('MESSAGE_NOT_FOUND', 'No such message.');
+        }
+        const stored = await tx.get('reactions', key);
+        const previous = stored === undefined
+            ? []
+            : storedSchema.parse(stored).reactions;
+        const result = {
+            chatId: channel.id,
+            messageId: input.messageId,
+            reactions,
+            changed: !sameReactions(previous, reactions),
+            queued: 0,
+        };
+        if (!result.changed) {
+            return result;
+        }
+        await tx.put({ collection: 'reactions', id: key, value: { reactions } });
+        const bots = (await tx.list('bots'))
+            .map((row) => botSchema.parse(row.value))
+            .sort((a, b) => a.id - b.id);
+        for (const bot of bots) {
+            const queue = await queueOf(tx, bot.id);
+            if (!receives(queue, 'message_reaction_count')) {
+                continue;
+            }
+            await enqueue(tx, bot.id, queue, (updateId) => ({
+                update_id: updateId,
+                message_reaction_count: {
+                    chat: chatView(channel),
+                    message_id: input.messageId,
+                    date: Math.floor(now / 1000),
+                    reactions,
+                },
+            }));
+            result.queued++;
+        }
+        return result;
+    });
+}

package/esm/model/updates.d.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { type PluginContext } from 'emulon';
+import type { ChatView } from './messages.js';
+type Store = PluginContext['store'];
+type Transaction = Parameters<Parameters<Store['transaction']>[0]>[0];
+/**
+ * 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 declare const updateTypes: readonly ["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"];
+export type UpdateType = typeof updateTypes[number];
+/** The reaction emoji typed by `@grammyjs/types@3.28.0`. */
+export declare const reactionEmoji: readonly ["👍", "👎", "❤", "🔥", "🥰", "👏", "😁", "🤔", "🤯", "😱", "🤬", "😢", "🎉", "🤩", "🤮", "💩", "🙏", "👌", "🕊", "🤡", "🥱", "🥴", "😍", "🐳", "❤‍🔥", "🌚", "🌭", "💯", "🤣", "⚡", "🍌", "🏆", "💔", "🤨", "😐", "🍓", "🍾", "💋", "🖕", "😈", "😴", "😭", "🤓", "👻", "👨‍💻", "👀", "🎃", "🙈", "😇", "😨", "🤝", "✍", "🤗", "🫡", "🎅", "🎄", "☃", "💅", "🤪", "🗿", "🆒", "💘", "🙉", "🦄", "😘", "💊", "🙊", "😎", "👾", "🤷‍♂", "🤷", "🤷‍♀", "😡"];
+export type ReactionType = {
+    type: 'emoji';
+    emoji: typeof reactionEmoji[number];
+} | {
+    type: 'custom_emoji';
+    custom_emoji_id: string;
+} | {
+    type: 'paid';
+};
+export interface ReactionCount {
+    type: ReactionType;
+    total_count: number;
+}
+export declare const reactionTypeSchema: z.ZodType<ReactionType, ReactionType>;
+export declare const reactionCountSchema: z.ZodType<ReactionCount, ReactionCount>;
+export interface ReactionCountUpdate {
+    update_id: number;
+    message_reaction_count: {
+        chat: ChatView;
+        message_id: number;
+        date: number;
+        reactions: ReactionCount[];
+    };
+}
+export declare const updateSchema: z.ZodType<ReactionCountUpdate, ReactionCountUpdate>;
+/** A rejected `getUpdates`; descriptions are fixed and never echo input. */
+export declare class UpdatesError extends Error {
+    readonly status: 400 | 409 | 501 | 503;
+    readonly description: string;
+    constructor(status: 400 | 409 | 501 | 503, description: string);
+}
+export declare const updatesErrors: {
+    readonly invalid: () => UpdatesError;
+    readonly limit: () => UpdatesError;
+    readonly allowedUpdates: () => UpdatesError;
+    readonly unsupported: () => UpdatesError;
+    readonly conflict: () => UpdatesError;
+    readonly cancelled: () => UpdatesError;
+};
+export interface UpdatesRequest {
+    offset?: number;
+    limit: number;
+    timeout: number;
+    allowedUpdates?: UpdateType[];
+}
+/** Only the documented polling fields; anything else is refused, not ignored. */
+export declare function updatesRequest(params: Record<string, unknown>): UpdatesRequest;
+/**
+ * Per-bot queue state. An empty `allowedUpdates` is Telegram's default, which
+ * leaves out `message_reaction_count`.
+ */
+export interface Queue {
+    nextUpdateId: number;
+    allowedUpdates: UpdateType[];
+}
+export declare function queueOf(tx: Transaction, botId: number): Promise<Queue>;
+export declare function receives(queue: Queue, type: UpdateType): boolean;
+/** The bot's queued updates in ID order. */
+export declare function queued(tx: Transaction, botId: number): Promise<ReactionCountUpdate[]>;
+/** Allocates the next update ID of one bot and queues the update it builds. */
+export declare function enqueue(tx: Transaction, botId: number, queue: Queue, build: (updateId: number) => ReactionCountUpdate): Promise<void>;
+/**
+ * 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 declare function takeUpdates(tx: Transaction, botId: number, request: Pick<UpdatesRequest, 'offset' | 'limit' | 'allowedUpdates'>): Promise<ReactionCountUpdate[]>;
+/**
+ * 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 declare function pollUpdates(store: Store, botId: number, request: UpdatesRequest, signal: AbortSignal): Promise<ReactionCountUpdate[]>;
+export declare const inspectInput: z.ZodType<InspectInput, InspectInput>;
+export interface InspectInput {
+    botId: number;
+    limit?: number | undefined;
+}
+export interface QueueView {
+    botId: number;
+    allowedUpdates: UpdateType[];
+    pending: number;
+    updates: ReactionCountUpdate[];
+}
+export declare const queueViewSchema: z.ZodType<QueueView, QueueView>;
+/**
+ * The oldest `limit` pending updates (default 100) and the subscription of one
+ * bot. Reading confirms nothing and shows no credential.
+ */
+export declare function inspectUpdates(store: Store, raw: InspectInput): Promise<QueueView>;
+export {};