@emulon/telegram 0.2.0

package/esm/format/markdown_v2.js

@@ -0,0 +1,266 @@
+/**
+ * Telegram MarkdownV2 parsing, modelled on the TDLib parser the Bot API uses:
+ * one left-to-right pass over the source with a stack of open entities, so
+ * nesting, escaping and delimiter ambiguity resolve the way Telegram resolves
+ * them. Offsets and lengths are UTF-16 code units of the rendered text, which
+ * is exactly how a JavaScript string counts.
+ */
+/**
+ * Malformed or unsupported markup. It carries no detail: Telegram's own
+ * message names the offending character, which would echo caller input.
+ */
+export class MarkdownError extends Error {
+    constructor() {
+        super("can't parse entities");
+    }
+}
+/** Characters that are markup outside code and must otherwise be escaped. */
+const reserved = new Set('_*[]()~`>#+-=|{}.!');
+/** Any character from 1 to 126 may follow a backslash to stand for itself. */
+function escapable(source, index) {
+    const code = source.charCodeAt(index);
+    return code >= 1 && code <= 126;
+}
+/**
+ * Link targets are unescaped verbatim. Telegram adds `http://` to a target
+ * without a scheme and silently drops a link it cannot read as a URL; mention,
+ * custom emoji, mail and other schemes are outside this emulator's scope and
+ * are refused rather than rendered differently.
+ */
+export function linkTarget(raw) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+        if (!/^https?:\/\//i.test(raw)) {
+            throw new MarkdownError();
+        }
+    }
+    else if (/^(tg|ton|tonsite|mailto|tel):/i.test(raw)) {
+        throw new MarkdownError();
+    }
+    else {
+        raw = `http://${raw}`;
+    }
+    if (/\s/.test(raw)) {
+        return null;
+    }
+    try {
+        const url = new URL(raw);
+        return url.hostname === '' ? null : url.href;
+    }
+    catch {
+        return null;
+    }
+}
+export function parseMarkdownV2(source) {
+    let text = '';
+    const entities = [];
+    const open = [];
+    let quote = null;
+    let order = 0;
+    let lineStart = true;
+    const push = (entity, at) => {
+        // An empty entity is dropped, as Telegram drops `**` or `[](url)`.
+        if (entity.length > 0) {
+            entities.push({ ...entity, order: at });
+        }
+    };
+    // Entities opened inside a quotation must close inside it.
+    const closeQuote = () => {
+        if (open.length > 0) {
+            throw new MarkdownError();
+        }
+        push({
+            type: quote.expandable ? 'expandable_blockquote' : 'blockquote',
+            offset: quote.offset,
+            length: text.length - quote.offset,
+        }, quote.order);
+        quote = null;
+    };
+    for (let i = 0; i < source.length; i++) {
+        const c = source[i];
+        const top = open.at(-1);
+        const inCode = top?.type === 'code' || top?.type === 'pre';
+        const atLineStart = lineStart;
+        lineStart = false;
+        if (c === '\\' && escapable(source, i + 1)) {
+            text += source[++i];
+            continue;
+        }
+        if (atLineStart && !inCode) {
+            const marker = source.startsWith('**>', i)
+                ? 3
+                : source[i] === '>'
+                    ? 1
+                    : 0;
+            if (marker > 0) {
+                // Quotations cannot nest in other entities or in each other.
+                if (!quote && open.length > 0) {
+                    throw new MarkdownError();
+                }
+                quote ??= { offset: text.length, order: order++, expandable: false };
+                i += marker - 1;
+                continue;
+            }
+        }
+        if (c === '\n') {
+            if (quote && inCode) {
+                // Code spanning quoted lines would need prefix rules Telegram
+                // does not document; refuse instead of guessing them.
+                throw new MarkdownError();
+            }
+            text += c;
+            lineStart = true;
+            // A quotation ends with the newline that ends its last line, so the
+            // newline belongs to it; `||` ends the line after it marked.
+            if (quote && (quote.expandable || source[i + 1] !== '>')) {
+                closeQuote();
+            }
+            continue;
+        }
+        if (inCode ? c !== '`' : !reserved.has(c)) {
+            text += c;
+            continue;
+        }
+        // The expandability mark: `||` ending a quoted line outside a spoiler.
+        if (quote && c === '|' && source[i + 1] === '|' && top?.type !== 'spoiler' &&
+            (i + 2 === source.length || source[i + 2] === '\n')) {
+            quote.expandable = true;
+            i++;
+            continue;
+        }
+        const ends = top !== undefined && (() => {
+            switch (top.type) {
+                case 'bold':
+                    return c === '*';
+                case 'italic':
+                    return c === '_' && source[i + 1] !== '_';
+                case 'underline':
+                    return c === '_' && source[i + 1] === '_';
+                case 'strikethrough':
+                    return c === '~';
+                case 'spoiler':
+                    return c === '|' && source[i + 1] === '|';
+                case 'code':
+                    return c === '`';
+                case 'pre':
+                    return source.startsWith('```', i);
+                case 'text_link':
+                    return c === ']';
+            }
+        })();
+        if (ends) {
+            const entity = open.pop();
+            const base = {
+                type: entity.type,
+                offset: entity.offset,
+                length: text.length - entity.offset,
+            };
+            // Skip the rest of a multi-character closing delimiter.
+            i += entity.type === 'underline' || entity.type === 'spoiler'
+                ? 1
+                : entity.type === 'pre'
+                    ? 2
+                    : 0;
+            if (entity.type === 'text_link') {
+                let raw = '';
+                if (source[i + 1] === '(') {
+                    i += 2;
+                    while (i < source.length && source[i] !== ')') {
+                        if (source[i] === '\\' && escapable(source, i + 1)) {
+                            i++;
+                        }
+                        raw += source[i++];
+                    }
+                    if (i >= source.length) {
+                        throw new MarkdownError();
+                    }
+                }
+                else {
+                    raw = text.slice(entity.offset);
+                }
+                const url = linkTarget(raw);
+                if (url !== null) {
+                    push({ ...base, url }, entity.order);
+                }
+            }
+            else if (entity.type === 'pre' && entity.language !== undefined) {
+                push({ ...base, language: entity.language }, entity.order);
+            }
+            else {
+                push(base, entity.order);
+            }
+            continue;
+        }
+        // A backtick inside code that does not close it cannot open anything.
+        if (inCode) {
+            throw new MarkdownError();
+        }
+        const start = (() => {
+            switch (c) {
+                case '_':
+                    if (source[i + 1] === '_') {
+                        i++;
+                        return { type: 'underline' };
+                    }
+                    return { type: 'italic' };
+                case '*':
+                    return { type: 'bold' };
+                case '~':
+                    return { type: 'strikethrough' };
+                case '|':
+                    if (source[i + 1] === '|') {
+                        i++;
+                        return { type: 'spoiler' };
+                    }
+                    throw new MarkdownError();
+                case '[':
+                    // Links cannot contain links.
+                    if (open.some((entity) => entity.type === 'text_link')) {
+                        throw new MarkdownError();
+                    }
+                    return { type: 'text_link' };
+                case '`': {
+                    if (!source.startsWith('```', i)) {
+                        return { type: 'code' };
+                    }
+                    i += 3;
+                    let end = i;
+                    while (end < source.length && !/\s/.test(source[end]) &&
+                        source[end] !== '`') {
+                        end++;
+                    }
+                    let language;
+                    if (end !== i && end < source.length && source[end] !== '`') {
+                        language = source.slice(i, end);
+                        i = end;
+                    }
+                    // One line break after the opening fence is not content.
+                    if (source[i] === '\n' || source[i] === '\r') {
+                        const pair = (source[i + 1] === '\n' || source[i + 1] === '\r') &&
+                            source[i] !== source[i + 1];
+                        i += pair ? 2 : 1;
+                    }
+                    i--;
+                    return language === undefined
+                        ? { type: 'pre' }
+                        : { type: 'pre', language };
+                }
+                default:
+                    // Includes `!` before `[`: custom emoji are not emulated.
+                    throw new MarkdownError();
+            }
+        })();
+        open.push({ ...start, offset: text.length, order: order++ });
+    }
+    if (open.length > 0) {
+        throw new MarkdownError();
+    }
+    if (quote) {
+        closeQuote();
+    }
+    // Outer entities first: by offset, then longer first, then opening order.
+    entities.sort((a, b) => a.offset - b.offset || b.length - a.length || a.order - b.order);
+    return {
+        text,
+        entities: entities.map(({ order: _, ...entity }) => entity),
+    };
+}

package/esm/mod.d.ts

@@ -0,0 +1,9 @@
+import type { z } from 'zod';
+import type { CompatibilityManifest, defineCommand } from 'emulon';
+import { definePlugin } from 'emulon';
+import { type Commands } from './commands/mod.js';
+import { type Options } from './model/channels.js';
+declare const telegram: ReturnType<typeof definePlugin<Options | undefined, Commands & {
+    'compatibility.get': ReturnType<typeof defineCommand<z.ZodObject<Record<string, never>>, z.ZodType<CompatibilityManifest>>>;
+}>>;
+export default telegram;

package/esm/mod.js

@@ -0,0 +1,28 @@
+import { definePlugin } from 'emulon';
+import { commands } from './commands/mod.js';
+import { compatibility } from './compatibility.js';
+import { channelFixtures } from './model/channels.js';
+import { routes } from './routes/api.js';
+const telegram = definePlugin({
+    name: '@emulon/telegram',
+    apiVersion: 1,
+    compatibility,
+    capabilities: ['http', 'authorization', 'reset'],
+    commands,
+    state: {
+        pluginVersion: '0.1.0',
+        schemaVersion: 1,
+        // Bots are never fixtures: reset removes them and every issued token.
+        fixtures: channelFixtures,
+    },
+    async setup(ctx) {
+        routes(ctx, ctx.http.surface('api'));
+        const api = await ctx.http.listen('api');
+        return {
+            endpoints: { api },
+            ready: () => Promise.resolve(),
+            stop: () => Promise.resolve(),
+        };
+    },
+});
+export default telegram;

package/esm/model/bots.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { type PluginContext } from 'emulon';
+import { type ParsedToken } from '../auth/tokens.js';
+type Store = PluginContext['store'];
+/** Telegram bot usernames: 5–32 characters that end in `bot`. */
+export declare const botUsername: z.ZodType<string, string>;
+export declare const createInput: z.ZodType<CreateInput, CreateInput>;
+export interface CreateInput {
+    username: string;
+    firstName: string;
+}
+/** The only output that carries the token; it is never readable again. */
+export interface IssuedBot {
+    id: number;
+    username: string;
+    token: string;
+}
+export declare const issuedSchema: z.ZodType<IssuedBot, IssuedBot>;
+export declare const botSchema: z.ZodType<Bot, Bot>;
+export interface Bot {
+    id: number;
+    username: string;
+    firstName: string;
+    verifier: string;
+}
+/** The `getMe` projection: a bot without optional capabilities. */
+export interface BotUser {
+    id: number;
+    is_bot: true;
+    first_name: string;
+    username: string;
+    can_join_groups: boolean;
+    can_read_all_group_messages: boolean;
+    supports_inline_queries: boolean;
+    can_connect_to_business: boolean;
+    has_main_web_app: boolean;
+    has_topics_enabled: boolean;
+    allows_users_to_create_topics: boolean;
+    can_manage_bots: boolean;
+    supports_join_request_queries: boolean;
+}
+/** IDs look like issued Telegram bot IDs and stay far from channel IDs. */
+export declare const firstBotId = 7000000001;
+export declare function nextBotId(existing: readonly Bot[]): number;
+export declare function botUser(bot: Bot): BotUser;
+/**
+ * The username check, ID allocation and verifier write commit together, so
+ * two concurrent creations can never share a username or an ID.
+ */
+export declare function createBot(store: Store, raw: CreateInput): Promise<IssuedBot>;
+/** The bot a well-formed token names, or null when it names no issued bot. */
+export declare function authenticate(store: Store, token: ParsedToken): Promise<Bot | null>;
+export {};

package/esm/model/bots.js

@@ -0,0 +1,84 @@
+// Bot API objects are snake_case on the wire.
+// deno-lint-ignore-file camelcase
+import { z } from 'zod';
+import { DomainError } from 'emulon';
+import { issueToken, sameVerifier, verifier, } from '../auth/tokens.js';
+import { channelSchema, usernameKey } from './channels.js';
+/** Telegram bot usernames: 5–32 characters that end in `bot`. */
+export const botUsername = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{1,28}[Bb][Oo][Tt]$/);
+export const createInput = z.strictObject({
+    username: botUsername,
+    firstName: z.string().min(1).max(64),
+});
+export const issuedSchema = z.strictObject({
+    id: z.number().int().positive().safe(),
+    username: z.string(),
+    token: z.string(),
+});
+export const botSchema = z.strictObject({
+    id: z.number().int().positive().safe(),
+    username: z.string(),
+    firstName: z.string(),
+    verifier: z.string().regex(/^[0-9a-f]{64}$/),
+});
+/** IDs look like issued Telegram bot IDs and stay far from channel IDs. */
+export const firstBotId = 7_000_000_001;
+export function nextBotId(existing) {
+    return existing.reduce((next, bot) => Math.max(next, bot.id + 1), firstBotId);
+}
+export function botUser(bot) {
+    return {
+        id: bot.id,
+        is_bot: true,
+        first_name: bot.firstName,
+        username: bot.username,
+        can_join_groups: true,
+        can_read_all_group_messages: false,
+        supports_inline_queries: false,
+        can_connect_to_business: false,
+        has_main_web_app: false,
+        has_topics_enabled: false,
+        allows_users_to_create_topics: false,
+        can_manage_bots: false,
+        supports_join_request_queries: false,
+    };
+}
+/**
+ * The username check, ID allocation and verifier write commit together, so
+ * two concurrent creations can never share a username or an ID.
+ */
+export async function createBot(store, raw) {
+    const input = createInput.parse(raw);
+    return await store.transaction(async (tx) => {
+        const bots = (await tx.list('bots')).map((row) => botSchema.parse(row.value));
+        const taken = new Set([
+            ...bots.map((bot) => usernameKey(bot.username)),
+            ...(await tx.list('channels')).map((row) => usernameKey(channelSchema.parse(row.value).username)),
+        ]);
+        if (taken.has(usernameKey(input.username))) {
+            throw new DomainError('USERNAME_TAKEN', 'A bot or channel already uses this username.');
+        }
+        const id = nextBotId(bots);
+        const token = issueToken(id);
+        const bot = {
+            id,
+            username: input.username,
+            firstName: input.firstName,
+            verifier: await verifier(token),
+        };
+        await tx.put({ collection: 'bots', id: String(id), value: bot });
+        return { id, username: bot.username, token };
+    });
+}
+/** The bot a well-formed token names, or null when it names no issued bot. */
+export async function authenticate(store, token) {
+    const presented = await verifier(token.token);
+    return await store.transaction(async (tx) => {
+        const row = await tx.get('bots', String(token.botId));
+        if (row === undefined) {
+            return null;
+        }
+        const bot = botSchema.parse(row);
+        return sameVerifier(presented, bot.verifier) ? bot : null;
+    });
+}

package/esm/model/channels.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+/** Telegram public usernames: 5–32 characters, starting with a letter. */
+export declare const channelUsername: z.ZodType<string, string>;
+/** Channel and supergroup IDs are negative with a `-100` decimal prefix. */
+export declare function isChannelId(id: number): boolean;
+export declare const channelSchema: z.ZodType<Channel, Channel>;
+export interface Channel {
+    id: number;
+    title: string;
+    username: string;
+}
+export interface Options {
+    fixtures?: {
+        channels?: Channel[] | undefined;
+    } | undefined;
+}
+export declare const optionsSchema: z.ZodType<Options, Options>;
+/** Usernames of bots and channels share one case-insensitive namespace. */
+export declare function usernameKey(username: string): string;
+/** Fixture errors name the rule, never the configured value. */
+export declare function channelFixtures(options?: Options): {
+    collection: string;
+    id: string;
+    value: Channel;
+}[];

package/esm/model/channels.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+/** Telegram public usernames: 5–32 characters, starting with a letter. */
+export const channelUsername = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{4,31}$/);
+/** Channel and supergroup IDs are negative with a `-100` decimal prefix. */
+export function isChannelId(id) {
+    return Number.isSafeInteger(id) && id < 0 && /^-100\d+$/.test(String(id));
+}
+export const channelSchema = z.strictObject({
+    id: z.number().refine(isChannelId),
+    title: z.string().min(1).max(128),
+    username: channelUsername,
+});
+export const optionsSchema = z.strictObject({
+    fixtures: z.strictObject({ channels: z.array(channelSchema).optional() })
+        .optional(),
+});
+/** Usernames of bots and channels share one case-insensitive namespace. */
+export function usernameKey(username) {
+    return username.toLowerCase();
+}
+/** Fixture errors name the rule, never the configured value. */
+export function channelFixtures(options) {
+    const parsed = optionsSchema.safeParse(options ?? {});
+    if (!parsed.success) {
+        throw new Error('Invalid Telegram options.');
+    }
+    const channels = parsed.data.fixtures?.channels ?? [];
+    const ids = new Set();
+    const usernames = new Set();
+    for (const channel of channels) {
+        if (ids.has(channel.id)) {
+            throw new Error('Duplicate fixture channel ID.');
+        }
+        if (usernames.has(usernameKey(channel.username))) {
+            throw new Error('Duplicate fixture channel username.');
+        }
+        ids.add(channel.id);
+        usernames.add(usernameKey(channel.username));
+    }
+    return channels.map((channel) => ({
+        collection: 'channels',
+        id: String(channel.id),
+        value: { ...channel },
+    }));
+}

package/esm/model/messages.d.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { type PluginContext } from 'emulon';
+import { type MessageEntity } from '../format/markdown_v2.js';
+import { type Bot, type BotUser } from './bots.js';
+import { type Channel } from './channels.js';
+type Store = PluginContext['store'];
+type Transaction = Parameters<Parameters<Store['transaction']>[0]>[0];
+/** Telegram's limit on message text, in UTF-16 code units after parsing. */
+export declare 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 declare class SendError extends Error {
+    readonly status: 400 | 501;
+    readonly description: string;
+    constructor(status: 400 | 501, description: string);
+}
+export declare const sendErrors: {
+    readonly parse: () => SendError;
+    readonly tooLong: () => SendError;
+    readonly empty: () => SendError;
+    readonly chatEmpty: () => SendError;
+    readonly chatNotFound: () => SendError;
+    readonly parseMode: () => SendError;
+    readonly invalid: () => SendError;
+    readonly unsupported: () => SendError;
+    readonly unsupportedMode: () => SendError;
+};
+export type ParseMode = 'MarkdownV2' | null;
+export interface Rendered {
+    text: string;
+    entities: MessageEntity[];
+}
+/**
+ * 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 declare function render(source: string, parseMode: ParseMode): Rendered;
+/** A `chat_id` as a channel ID, or a lowercase username without `@`. */
+export type ChatReference = {
+    id: number;
+} | {
+    username: string;
+};
+export declare function chatReference(value: unknown): ChatReference | null;
+export interface SendRequest {
+    chat: ChatReference;
+    source: string;
+    parseMode: ParseMode;
+}
+/**
+ * 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 declare function sendRequest(params: Record<string, unknown>): SendRequest;
+export declare const entitySchema: z.ZodType<MessageEntity, MessageEntity>;
+/** A stored channel post: what was submitted and what Telegram would show. */
+export interface StoredMessage {
+    chatId: number;
+    messageId: number;
+    botId: number;
+    date: number;
+    parseMode: ParseMode;
+    source: string;
+    text: string;
+    entities: MessageEntity[];
+}
+export declare const storedSchema: z.ZodType<StoredMessage, StoredMessage>;
+export interface ChatView {
+    id: number;
+    title: string;
+    username: string;
+    type: 'channel';
+}
+/** The Bot API `Message` returned by `sendMessage`. */
+export interface MessageView {
+    message_id: number;
+    from: Pick<BotUser, 'id' | 'is_bot' | 'first_name' | 'username'>;
+    sender_chat: ChatView;
+    chat: ChatView;
+    date: number;
+    text: string;
+    entities?: MessageEntity[];
+}
+export declare function chatView(channel: Channel): ChatView;
+export declare function messageView(message: StoredMessage, channel: Channel, bot: Bot): MessageView;
+export declare function findChannel(tx: Transaction, chat: ChatReference): Promise<Channel | null>;
+/** Message IDs sort as text in store order and as numbers in the key. */
+export declare const messageKey: (chatId: number, messageId: number) => string;
+/**
+ * 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 declare function sendMessage(store: Store, bot: Bot, request: SendRequest, now: number): Promise<MessageView>;
+export declare const listInput: z.ZodType<ListInput, ListInput>;
+export interface ListInput {
+    chatId: number;
+    limit?: number | undefined;
+}
+/**
+ * The most recent `limit` messages (default 100) of one channel, oldest
+ * first, so a multipart post reads in the order it was sent.
+ */
+export declare function listMessages(store: Store, raw: ListInput): Promise<StoredMessage[]>;
+export {};