@volter/twin-telegram 1.0.0

package/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"user":{"actions":[],"states":{},"embeds":{}},"chat":{"actions":[],"states":{},"embeds":{}},"chat_member":{"actions":[],"states":{"status":["administrator","creator","kicked","left","member"]},"embeds":{}},"message":{"actions":[],"states":{},"embeds":{}},"update":{"actions":[],"states":{},"embeds":{}},"file":{"actions":[],"states":{},"embeds":{}},"_bot":{"actions":[],"states":{},"embeds":{}},"_group":{"actions":[],"states":{},"embeds":{}},"_channel":{"actions":[],"states":{},"embeds":{}},"_file_path":{"actions":[],"states":{},"embeds":{}},"_media_group":{"actions":[],"states":{},"embeds":{}}}}

package/src/index.ts

@@ -0,0 +1,11 @@
+// @volter/twin-telegram — the telegram twin (Protocol 3). A fixed file (create-pack): the descriptor is the manifest's, and the
+// kernel derives the vendor-backed half from the generated surface (architecture, "The real-system adapters").
+import { packOf, registerPack, type DerivedSurface } from '@volter/world-core';
+import { manifest } from './manifest.ts';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+
+export { createTelegramFetch } from './fetch.ts';
+export { createTelegramTwinServer } from './server.ts';
+export { manifest };
+
+export const pack = registerPack(packOf(manifest, surface as unknown as DerivedSurface));

package/src/manifest.ts

@@ -0,0 +1,114 @@
+// Telegram's manifest: the vendor facts its spec (../spec, written from the Bot API page) does not carry. Served is what
+// the demand's applications call as they ship and what the life reaches (../journeys/demand.json,
+// ../journeys/decisions.json): a bot reading itself, removing its webhook and polling for updates (a long poll), showing
+// it is typing, sending text, a photo, a video, a document and an album, deleting a message, reading a chat, a chat
+// member and a file, and the file's download. Every other method of the page answers the vendor's unknown method. Every
+// request names its bot by the token in its path (`/bot<token>/<method>`), checked by ./semantics/around.ts before the
+// method is routed, as the Bot API server checks it. People, chats and bots are made in the Telegram app and BotFather,
+// which no Bot API method does: the World's doors stand in for them (./semantics/doors.ts).
+import type { DerivedManifest } from '@volter/world-core';
+import { states } from './semantics/states.ts';
+
+export const manifest: DerivedManifest = {
+  vendor: 'telegram',
+  service: 'telegram',
+  // the four ways the Bot API takes parameters: query, form, JSON and multipart, each read as its content type says
+  // source: https://core.telegram.org/bots/api#making-requests "We support four ways of passing parameters in Bot API requests"
+  body: {},
+  // ids are integers the vendor assigns (a user's, a chat's, a message's per chat); each resource below says its form
+  ids: { template: '{prefix}{n}' },
+  // source: https://core.telegram.org/bots/api#message "Date the message was sent in Unix time"
+  time: 'unix',
+  // source: https://core.telegram.org/bots/api#making-requests "In case of an unsuccessful request, 'ok' equals False and the error is explained in the 'description'."
+  error: { ok: false, error_code: '{status}', description: '{message}' },
+  // the Bot API has no read-only mode; a World started read-only refuses a write with the class of refusal the server
+  // gives an act it does not allow (Where the documentation stops: the words are the twin's)
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "error_code = 403;"
+  readOnly: { status: 403, message: 'Forbidden: this World was started read-only' },
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/HttpConnection.cpp "return send_http_error(404,"
+  notFound: { status: 404, message: 'Not Found' },
+  // a method the twin does not serve answers as an unknown method does
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Not Found: method not found"
+  gap: { status: 404, message: 'Not Found: method not found' },
+  // the Bot API pages nothing; getUpdates' limit is the one bounded read
+  // source: https://core.telegram.org/bots/api#getupdates "Values between 1-100 are accepted. Defaults to 100."
+  list: { style: 'envelope', envelope: { ok: true, result: '{data}' }, limit: { param: 'limit', default: 100, max: 100 } },
+  deleted: { ok: true, result: true },
+  // every method this pack serves is a handler (an RPC wire: no create, read, update or delete of a path), and no
+  // declared resource has an operation the core would serve, so nothing is listed unmodeled
+  unmodeled: [],
+  // getUpdates, getMe, getChat, getChatMember and getFile only read, though asked by POST
+  reads: ['getMe', 'getChat', 'getChatMember', 'getFile'],
+  // a file's path holds its folder: profile_photos/file_1.jpg
+  // source: https://core.telegram.org/bots/api#file "Optional. File path. Use https://api.telegram.org/file/bot<token>/<file_path> to get the file."
+  spanning: ['file_path'],
+  resources: {
+    // a Telegram account, a person's or a bot's, stored as the Bot API answers a User; its id is an integer the vendor
+    // assigns, kept as the subject's id and as its own `id`
+    // source: https://core.telegram.org/bots/api#user "Unique identifier for this user or bot."
+    user: { idPrefix: '58104400', ids: '{prefix}{n}', refresh: { none: 'the Bot API reads no user by id and lists none: getMe answers the bot itself, and a person is seen only in the messages and updates that name them' } },
+    // a chat as getChat answers it (ChatFullInfo); a private chat's id is its person's, a group's and a channel's are
+    // the vendor's negative ids (minted by the doors that make them)
+    // source: https://core.telegram.org/bots/api#chat "Unique identifier for this chat."
+    chat: { idPrefix: '', ...states.chat, refresh: { get: 'getChat', known: true, query: { chat_id: '{id}' } } },
+    // one subject per member of a chat, `<chat>:<user>`, stored as getChatMember answers it
+    chat_member: { idPrefix: '', ...states.chat_member, refresh: { none: 'the Bot API lists only administrators (getChatAdministrators), and getChatMember reads one member by a user id the World learns only from updates' } },
+    // a message, `<chat>:<message_id>`; its message_id counts per chat
+    // source: https://core.telegram.org/bots/api#message "Unique message identifier inside this chat;"
+    message: { idPrefix: '', refresh: { none: 'the Bot API reads no message back: a bot sees one only as an update or as the answer to its own send' } },
+    // an update waiting for its bot, `<bot>:<update_id>`, stored as getUpdates answers it; confirmed, it is gone
+    // source: https://core.telegram.org/bots/api#getupdates "An update is considered confirmed as soon as getUpdates is called with an offset higher than its update_id."
+    update: { idPrefix: '', refresh: { none: 'reading the queue (getUpdates) confirms what it reads: a refresh would take updates from the application the World serves' } },
+    // a stored file (a photo, a video, a document, a chat photo), its bytes the pack's blobs, by its file_unique_id
+    // source: https://core.telegram.org/bots/api#file "Unique identifier for this file, which is supposed to be the same over time and for different bots."
+    file: { idPrefix: 'AgAD', ids: '{prefix}{letters:12}', refresh: { none: 'getFile reads a file by a file_id the World learns only from messages, and its answer is the download path, not the file' } },
+    // a bot's own keeping: its token's SHA-256 and its owner, its updates' counter and the allowed_updates it last asked for
+    _bot: { idPrefix: '' },
+    // the ids the vendor assigns to a basic group and to a channel or supergroup, and a file's download path
+    _group: { idPrefix: '-49870000', ids: '{prefix}{n}' },
+    _channel: { idPrefix: '-10019876540', ids: '{prefix}{n}' },
+    _file_path: { idPrefix: 'file_', ids: '{prefix}{n}' },
+    _media_group: { idPrefix: '137292810', ids: '{prefix}{n}' },
+  },
+  doors: [
+    { id: 'people', method: 'POST', path: '/_twin/people', note: '{ first_name, last_name?, username?, language_code? }: a Telegram account, as a person signs up in the app' },
+    { id: 'bots', method: 'POST', path: '/_twin/bots', note: "{ owner?, name?, username? }: BotFather's /newbot, for the person `owner` (a user id): the bot and its token; the same username answers the same bot" },
+    { id: 'botToken', method: 'POST', path: '/_twin/bots/{username}/token', note: "{ owner }: BotFather's /token: a new token, the old one revoked" },
+    { id: 'chats', method: 'POST', path: '/_twin/chats', note: '{ creator, type: group | supergroup | channel, title, username?, description?, photo? (base64 bytes), members?: [{ user, status?: member | administrator, rights? }] }: a person makes a chat in the app' },
+    { id: 'members', method: 'POST', path: '/_twin/chats/{chat_id}/members', note: '{ by, user, status: member | administrator | kicked, rights? }: a person adds, promotes or removes a member in the app' },
+    { id: 'messages', method: 'POST', path: '/_twin/messages', note: "{ from, chat (a chat id, a chat's @username, or a bot's @username for a private chat with it), text, reply_to_message_id? }: a person writes in the app" },
+  ],
+  // the API's limits (https://core.telegram.org/bots/faq): a bot broadcasts about 30 messages a second; the kernel's
+  // bound is 20 a second, so the World spends at most that
+  // source: https://core.telegram.org/bots/faq "bots are not able to broadcast more than about 30 messages per second"
+  rateBudget: {
+    allowance: { perMinute: 1800, source: 'https://core.telegram.org/bots/faq' },
+    reason: "Telegram's FAQ: about 30 messages a second for bulk notifications, one a second in a single chat, 20 a minute in a group (https://core.telegram.org/bots/faq). The World stays at the kernel's bound of 20 a second over a one-minute window (1000).",
+    windowMs: 60_000, ceiling: 1000, defaultWeight: 1, maxRetryAfterSeconds: 300,
+  },
+  discovery: {
+    twinOf: "Telegram's Bot API as bots use it: a bot reading itself, polling for its updates (a long poll), typing, sending text (plain, HTML, MarkdownV2 or Markdown), photos, videos, documents and albums, deleting messages, reading chats, members and files, and downloading a file",
+    stores: 'people and bots (tokens by their SHA-256), chats with their members, messages, the updates waiting for each bot, and files (their bytes as blobs)',
+    identity: 'the bot token in the path: https://api.telegram.org/bot<token>/<method> (the bots door, standing in for BotFather, issues it)',
+  },
+  descriptor: {
+    protocol: '3',
+    transport: 'web-api',
+    archetype: 'crud',
+    bin: 'world-telegram',
+    resources: ['user', 'chat', 'chat_member', 'message', 'update', 'file'],
+    specSource: 'the Telegram Bot API page (https://core.telegram.org/bots/api, Bot API 10.3), written as OpenAPI in spec/ (provenance in spec/SOURCE.md)',
+    description: "Telegram Bot API twin — a bot's updates by long polling, its messages (text, HTML, MarkdownV2, photos, videos, documents, albums), chats, members and files, as Volter Harness's Chat SDK channel and Postiz call them.",
+    adoption: { sdks: ['@chat-adapter/telegram', 'node-telegram-bot-api', 'telegraf'], envStems: ['TELEGRAM'] },
+    // the libraries above name Telegram in an application; none is Telegram's own
+    // source: https://core.telegram.org/bots/samples "these projects are not maintained by Telegram"
+    clientCasesNone: 'Telegram publishes no client library of its own (its samples page lists libraries others maintain): the demand applications call the Bot API through the Chat SDK adapter (Volter Harness) and node-telegram-bot-api (Postiz)',
+    hosts: [{ host: 'api.telegram.org' }],
+    // the Chat SDK's adapter reads TELEGRAM_API_BASE_URL as its API's base URL (@chat-adapter/telegram 4.39.0, dist/index.js:1039)
+    endpointEnv: { name: 'TELEGRAM_API_BASE_URL', note: "the Chat SDK's Telegram adapter reads it as its API base (@chat-adapter/telegram 4.39.0, dist/index.js:1039); node-telegram-bot-api takes a baseApiUrl option only, and reaches the twin by its host" },
+    credentialDoor: { path: '/_twin/bots', body: {}, fill: { TELEGRAM_BOT_TOKEN: 'token', TELEGRAM_TOKEN: 'token', TELEGRAM_BOT_USERNAME: 'username', TELEGRAM_BOT_NAME: 'username' } },
+    // the bot token rides in the path, after /bot (the API's) or /file/bot (a file's download)
+    // source: https://core.telegram.org/bots/api#making-requests "https://api.telegram.org/bot<token>/METHOD_NAME"
+    auth: { in: 'path', pattern: '/(?:file/)?bot([^/]+)/' },
+  },
+};

package/src/semantics/around.ts

@@ -0,0 +1,33 @@
+// What the Bot API does around every request (architecture, around.ts): the token in the path names the bot before the
+// method is routed, as the server's client manager reads it. A token of a form BotFather never issues is refused as
+// invalid; one it did not issue, or one made again since (BotFather's /token revokes the token before), as
+// unauthorized. A path that names no bot at all is not the API's.
+import type { HandlerContext } from '@volter/world-core';
+import { botOfToken, refuse, SERVED_METHODS, tokenOf } from './shared.ts';
+
+export async function around(ctx: HandlerContext, next: (request?: Request) => Promise<Response>): Promise<Response> {
+  const path = new URL(ctx.call.request.url).pathname;
+  if (path.startsWith('/_twin/') || path === '/twin' || path.startsWith('/twin/')) return next();
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/HttpConnection.cpp "if (!url_path_parser.try_skip("
+  const token = tokenOf(ctx.call.request);
+  if (token === undefined) return refuse(ctx, 404, 'Not Found');
+  const found = botOfToken(ctx, token);
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/ClientManager.cpp "Unauthorized: invalid token specified"
+  if (found === 'invalid') return refuse(ctx, 401, 'Unauthorized: invalid token specified');
+  // a token the bot does not hold fails its login
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "result.code = 401;"
+  if (found === 'unknown') return refuse(ctx, 401, 'Unauthorized');
+  // a method asked by GET, or named in another case, is the same method: the server takes both methods and lowers the
+  // name before it routes
+  // source: https://core.telegram.org/bots/api#making-requests "We support GET and POST HTTP methods."
+  // source: https://core.telegram.org/bots/api#making-requests "All methods in the Bot API are case-insensitive."
+  const method = /^\/bot[^/]+\/([^/]+)$/.exec(path)?.[1];
+  const canonical = method ? SERVED_METHODS.find((m) => m.toLowerCase() === method.toLowerCase()) : undefined;
+  if (method && (ctx.call.request.method === 'GET' || (canonical && canonical !== method))) {
+    const url = new URL(ctx.call.request.url);
+    if (canonical) url.pathname = path.slice(0, path.length - method.length) + canonical;
+    const body = ctx.call.request.method === 'GET' ? undefined : await ctx.call.request.clone().arrayBuffer();
+    return next(new Request(url, { method: 'POST', headers: ctx.call.request.headers, ...(body ? { body } : {}) }));
+  }
+  return next();
+}

package/src/semantics/available-methods.ts

@@ -0,0 +1,253 @@
+// Available methods (https://core.telegram.org/bots/api#available-methods) the demand reaches: the bot itself, text and
+// media sent to a chat, the typing indicator, a chat, a member and a file read, and a file's download.
+import type { HandlerContext } from '@volter/world-core';
+import { imageSize, mp4Info } from '../engine/media.ts';
+import {
+  answer, botOf, chatFor, chatFullView, fileBytes, fileById, formatted, jsonParam, memberKey, memberView, messageView, param,
+  refuse, replyTarget, storeBotMessage, storeFile, textFields, uploadOf, type Row, type Upload,
+} from './shared.ts';
+
+// source: https://core.telegram.org/bots/api#sendmessage "Text of the message to be sent, 1-4096 characters after entities parsing"
+const TEXT_MAX = 4096;
+// source: https://core.telegram.org/bots/api#sendphoto "Photo caption (may also be used when resending photos by file_id), 0-1024 characters after entities parsing"
+const CAPTION_MAX = 1024;
+const characters = (s: string): number => [...s].length;
+
+export async function getMe(ctx: HandlerContext): Promise<Response> {
+  const { user } = botOf(ctx);
+  // the bot's User with the fields getMe alone returns
+  // source: https://core.telegram.org/bots/api#getme "Returns basic information about the bot in form of a User object."
+  return answer(Object.fromEntries(Object.entries(ctx.own(user)).filter(([k]) => !k.startsWith('_') && k !== 'deleted')));
+}
+
+export async function sendMessage(ctx: HandlerContext): Promise<Response> {
+  const { id: botId } = botOf(ctx);
+  const access = chatFor(ctx, botId, param(ctx, 'chat_id'), 'write');
+  if ('refusal' in access) return access.refusal;
+  const raw = param(ctx, 'text');
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Message text is empty"
+  if (raw === undefined || String(raw) === '') return refuse(ctx, 400, 'Bad Request: message text is empty');
+  const entities = jsonParam(ctx, 'entities');
+  const text = formatted(ctx, String(raw), param(ctx, 'parse_mode'), entities.value);
+  if ('refusal' in text) return text.refusal;
+  // source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/MessageEntity.cpp "Text must be non-empty"
+  if (text.text === '') return refuse(ctx, 400, 'Bad Request: text must be non-empty');
+  // source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/MessagesManager.cpp "Message is too long"
+  if (characters(text.text) > TEXT_MAX) return refuse(ctx, 400, 'Bad Request: message is too long');
+  const reply = replyTarget(ctx, access.chat, botId);
+  if ('refusal' in reply) return reply.refusal;
+  const row = await storeBotMessage(ctx, botId, access.chat, textFields(text, 'text'), reply.key, ctx.call.operation.id);
+  return answer(messageView(ctx, row));
+}
+
+/** A caption checked as the server checks it: parsed, then at most 1024 characters. */
+function captionOf(ctx: HandlerContext, caption: unknown, parseMode: unknown, entities: unknown): Row | { refusal: Response } {
+  if (caption === undefined || caption === null || String(caption) === '') return {};
+  const text = formatted(ctx, String(caption), parseMode, entities);
+  if ('refusal' in text) return text;
+  // source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/MessagesManager.cpp "Message caption is too long"
+  if (characters(text.text) > CAPTION_MAX) return { refusal: refuse(ctx, 400, 'Bad Request: message caption is too long') };
+  return textFields(text, 'caption');
+}
+
+/** A medium's fields on its message, from an upload or a file sent again: a photo's one size, a video's size and
+ *  length, a document's name and type. */
+async function mediaFields(ctx: HandlerContext, botId: number, kind: 'photo' | 'video' | 'document', upload: Upload, given: { width?: unknown; height?: unknown; duration?: unknown }): Promise<Row | { refusal: Response }> {
+  const operation = ctx.call.operation.id;
+  let file: Row;
+  let bytes: Uint8Array;
+  if ('file' in upload) {
+    // a file sent again keeps its type: a photo is not sent as a document, nor a video as a photo
+    // source: https://core.telegram.org/bots/api#sending-files "It is not possible to change the file type when resending by file_id ."
+    // source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/files/FileManager.cpp "Can't use file of type"
+    const types: Record<string, string> = { photos: 'Photo', videos: 'Video', documents: 'Document', profile_photos: 'ProfilePhoto' };
+    const real = types[String(upload.file._kind)] ?? 'Document';
+    const wanted = kind === 'photo' ? 'Photo' : kind === 'video' ? 'Video' : 'Document';
+    if (real !== wanted) return { refusal: refuse(ctx, 400, `Bad Request: can't use file of type ${real} as ${wanted}`) };
+    file = upload.file;
+    bytes = await fileBytes(ctx, file);
+  }
+  else {
+    bytes = upload.bytes;
+    // source: https://core.telegram.org/bots/api#sendphoto "The photo must be at most 10 MB in size."
+    // source: https://core.telegram.org/bots/api#sendvideo "Bots can currently send video files of up to 50 MB in size, this limit may be changed in the future."
+    // source: https://core.telegram.org/bots/api#senddocument "Bots can currently send files of any type of up to 50 MB in size, this limit may be changed in the future."
+    // Where the documentation stops: the words for a file over its limit are the server's for a file too big
+    // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Bad Request: file is too big"
+    if (bytes.byteLength > (kind === 'photo' ? 10 : 50) * 1024 * 1024) return { refusal: refuse(ctx, 400, 'Bad Request: file is too big') };
+    if (kind === 'photo' && !imageSize(bytes)) {
+      // an upload that is no image Telegram can read: Telegram's own error for it, which the server relays as it is (its
+      // second character an underscore or a capital)
+      // source: https://core.telegram.org/method/messages.sendMedia "Failure while processing image."
+      // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "(error_message[1] == '_' || ('A' <= error_message[1] && error_message[1] <= 'Z'))) {"
+      return { refusal: refuse(ctx, 400, 'Bad Request: IMAGE_PROCESS_FAILED') };
+    }
+    const size = kind === 'photo' ? imageSize(bytes)! : undefined;
+    // source: https://core.telegram.org/bots/api#sendphoto "The photo's width and height must not exceed 10000 in total. Width and height ratio must be at most 20."
+    // (Telegram's own error for it, relayed as it is: an MTProto error's second character is a capital)
+    if (size && (size.width + size.height > 10000 || Math.max(size.width, size.height) > 20 * Math.max(1, Math.min(size.width, size.height)))) return { refusal: refuse(ctx, 400, 'Bad Request: PHOTO_INVALID_DIMENSIONS') };
+    file = await storeFile(ctx, bytes, { kind: kind === 'photo' ? 'photos' : kind === 'video' ? 'videos' : 'documents', bot: botId, ...(upload.mime ? { mime: upload.mime } : {}), ...(upload.name ? { name: upload.name } : {}) }, operation);
+  }
+  const ids = { file_id: file.file_id, file_unique_id: file.file_unique_id };
+  if (kind === 'photo') {
+    const size = imageSize(bytes) ?? { width: 0, height: 0 };
+    // Where the documentation stops: the page gives a photo's sizes as "Available sizes of the photo" and names none;
+    // the twin keeps the one it was given
+    // source: https://core.telegram.org/bots/api#message "Optional. Message is a photo, available sizes of the photo"
+    return { photo: [{ ...ids, file_size: bytes.byteLength, width: size.width, height: size.height }] };
+  }
+  const name = typeof file._name === 'string' ? file._name : undefined;
+  const mime = typeof file._mime === 'string' ? file._mime : undefined;
+  if (kind === 'video') {
+    const info = mp4Info(bytes);
+    // the request's own width, height and duration, else the file's
+    // source: https://core.telegram.org/bots/api#sendvideo "Duration of sent video in seconds"
+    const num = (v: unknown, fallback: number): number => (typeof v === 'number' ? v : typeof v === 'string' && /^\d+$/.test(v) ? Number(v) : fallback);
+    return { video: { ...ids, width: num(given.width, info?.width ?? 0), height: num(given.height, info?.height ?? 0), duration: num(given.duration, info?.duration ?? 0), ...(name ? { file_name: name } : {}), ...(mime ? { mime_type: mime } : {}), file_size: bytes.byteLength } };
+  }
+  return { document: { ...ids, ...(name ? { file_name: name } : {}), ...(mime ? { mime_type: mime } : {}), file_size: bytes.byteLength } };
+}
+
+/** One medium sent to a chat with its caption. */
+async function sendMedium(ctx: HandlerContext, kind: 'photo' | 'video' | 'document'): Promise<Response> {
+  const { id: botId } = botOf(ctx);
+  const access = chatFor(ctx, botId, param(ctx, 'chat_id'), 'write');
+  if ('refusal' in access) return access.refusal;
+  const upload = uploadOf(ctx, ctx.params[kind], botId);
+  if ('refusal' in upload) return upload.refusal;
+  const caption = captionOf(ctx, param(ctx, 'caption'), param(ctx, 'parse_mode'), jsonParam(ctx, 'caption_entities').value);
+  if ('refusal' in caption) return caption.refusal as Response;
+  const reply = replyTarget(ctx, access.chat, botId);
+  if ('refusal' in reply) return reply.refusal;
+  const media = await mediaFields(ctx, botId, kind, upload, { width: param(ctx, 'width'), height: param(ctx, 'height'), duration: param(ctx, 'duration') });
+  if ('refusal' in media) return media.refusal as Response;
+  const row = await storeBotMessage(ctx, botId, access.chat, { ...media, ...caption }, reply.key, ctx.call.operation.id);
+  return answer(messageView(ctx, row));
+}
+
+// source: https://core.telegram.org/bots/api#sendphoto "Use this method to send photos. On success, the sent Message is returned."
+export async function sendPhoto(ctx: HandlerContext): Promise<Response> {
+  return sendMedium(ctx, 'photo');
+}
+
+// source: https://core.telegram.org/bots/api#sendvideo "Use this method to send video files, Telegram clients support MPEG4 videos (other formats may be sent as Document)."
+export async function sendVideo(ctx: HandlerContext): Promise<Response> {
+  return sendMedium(ctx, 'video');
+}
+
+// source: https://core.telegram.org/bots/api#senddocument "Use this method to send general files. On success, the sent Message is returned."
+export async function sendDocument(ctx: HandlerContext): Promise<Response> {
+  return sendMedium(ctx, 'document');
+}
+
+// source: https://core.telegram.org/bots/api#sendmediagroup "On success, an Array of Message objects that were sent is returned."
+export async function sendMediaGroup(ctx: HandlerContext): Promise<Response> {
+  const { id: botId } = botOf(ctx);
+  const access = chatFor(ctx, botId, param(ctx, 'chat_id'), 'write');
+  if ('refusal' in access) return access.refusal;
+  const media = jsonParam(ctx, 'media');
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Can't parse media JSON object"
+  if (media.error || (media.value !== undefined && !Array.isArray(media.value))) return refuse(ctx, 400, "Bad Request: can't parse media JSON object");
+  const items = (media.value ?? []) as Row[];
+  // source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/MessageContent.cpp "There are no messages to send"
+  if (!items.length) return refuse(ctx, 400, 'Bad Request: there are no messages to send');
+  // source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/MessageContent.cpp "Too many messages to send as an album"
+  if (items.length > 10) return refuse(ctx, 400, 'Bad Request: too many messages to send as an album');
+  const kinds = items.map((i) => String(i?.type ?? ''));
+  for (const k of kinds) {
+    // source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/MessageContent.cpp "Invalid message content type"
+    if (!['photo', 'video', 'document'].includes(k)) return refuse(ctx, 400, `Bad Request: can't parse InputMedia: ${k ? 'unsupported media type' : 'media type is not specified'}`);
+  }
+  // source: https://core.telegram.org/bots/api#sendmediagroup "Documents and audio files can be only grouped in an album with messages of the same type."
+  // source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/MessageContent.cpp "can't be mixed with other media types"
+  if (kinds.includes('document') && kinds.some((k) => k !== 'document')) return refuse(ctx, 400, "Bad Request: document can't be mixed with other media types");
+  const reply = replyTarget(ctx, access.chat, botId);
+  if ('refusal' in reply) return reply.refusal;
+  // every part checked before any is sent
+  const prepared: Array<{ kind: 'photo' | 'video' | 'document'; upload: Upload; caption: Row; item: Row }> = [];
+  for (const item of items) {
+    const upload = uploadOf(ctx, item.media, botId);
+    if ('refusal' in upload) return upload.refusal;
+    const caption = captionOf(ctx, item.caption, item.parse_mode, item.caption_entities);
+    if ('refusal' in caption) return caption.refusal as Response;
+    prepared.push({ kind: item.type as 'photo' | 'video' | 'document', upload, caption, item });
+  }
+  // the album's one media_group_id, the World's for it
+  // source: https://core.telegram.org/bots/api#message "Optional. The unique identifier inside this chat of a media message group this message belongs to"
+  const group = await ctx.issue('_media_group');
+  const sent: Row[] = [];
+  for (const p of prepared) {
+    const fields = await mediaFields(ctx, botId, p.kind, p.upload, { width: p.item.width, height: p.item.height, duration: p.item.duration });
+    if ('refusal' in fields) return fields.refusal as Response;
+    const row = await storeBotMessage(ctx, botId, access.chat, { media_group_id: group, ...fields, ...p.caption }, reply.key, ctx.call.operation.id);
+    sent.push(messageView(ctx, row));
+  }
+  return answer(sent);
+}
+
+// source: https://core.telegram.org/bots/api#sendchataction "Use this method when you need to tell the user that something is happening on the bot's side."
+export async function sendChatAction(ctx: HandlerContext): Promise<Response> {
+  const { id: botId } = botOf(ctx);
+  const access = chatFor(ctx, botId, param(ctx, 'chat_id'), 'write');
+  if ('refusal' in access) return access.refusal;
+  const action = String(param(ctx, 'action') ?? '').toLowerCase();
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Wrong parameter action in request"
+  if (!['cancel', 'typing', 'record_video', 'upload_video', 'record_audio', 'record_voice', 'upload_audio', 'upload_voice', 'upload_photo', 'upload_document', 'choose_sticker', 'pick_up_location', 'find_location', 'record_video_note', 'upload_video_note'].includes(action)) {
+    return refuse(ctx, 400, 'Bad Request: wrong parameter action in request');
+  }
+  // the status shows for five seconds in the person's app; nothing is stored
+  // source: https://core.telegram.org/bots/api#sendchataction "The status is set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear its typing status). Returns True on success."
+  return answer(true);
+}
+
+// source: https://core.telegram.org/bots/api#getchat "Use this method to get up-to-date information about the chat. Returns a ChatFullInfo object on success."
+export async function getChat(ctx: HandlerContext): Promise<Response> {
+  const { id: botId } = botOf(ctx);
+  const access = chatFor(ctx, botId, param(ctx, 'chat_id'), 'read');
+  if ('refusal' in access) return access.refusal;
+  return answer(chatFullView(ctx, access.chat));
+}
+
+// source: https://core.telegram.org/bots/api#getchatmember "Use this method to get information about a member of a chat."
+export async function getChatMember(ctx: HandlerContext): Promise<Response> {
+  const { id: botId } = botOf(ctx);
+  const access = chatFor(ctx, botId, param(ctx, 'chat_id'), 'read');
+  if ('refusal' in access) return access.refusal;
+  const userId = param(ctx, 'user_id');
+  const user = typeof userId === 'number' ? userId : typeof userId === 'string' && /^\d+$/.test(userId) ? Number(userId) : undefined;
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "user not found"
+  if (user === undefined || !ctx.row('user', String(user))) return refuse(ctx, 400, 'Bad Request: user not found');
+  const member = ctx.row('chat_member', memberKey(access.chat.id, user));
+  return answer(memberView(ctx, member, user));
+}
+
+// source: https://core.telegram.org/bots/api#getfile "Use this method to get basic information about a file and prepare it for downloading. For the moment, bots can download files of up to 20MB in size."
+export async function getFile(ctx: HandlerContext): Promise<Response> {
+  const { id: botId } = botOf(ctx);
+  const file = fileById(ctx, param(ctx, 'file_id'), botId);
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "invalid file_id"
+  if (!file) return refuse(ctx, 400, 'Bad Request: invalid file_id');
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Bad Request: file is too big"
+  if (Number(file.file_size ?? 0) > 20 * 1024 * 1024) return refuse(ctx, 400, 'Bad Request: file is too big');
+  let path = typeof file.file_path === 'string' ? file.file_path : undefined;
+  if (!path) {
+    // the path a file is downloaded by: its kind's folder and a name the server gives it
+    // source: https://core.telegram.org/bots/api#file "Optional. File path. Use https://api.telegram.org/file/bot<token>/<file_path> to get the file."
+    const name = await ctx.issue('_file_path');
+    const ext = typeof file._name === 'string' && file._name.includes('.') ? file._name.slice(file._name.lastIndexOf('.')) : file._kind === 'videos' ? '.mp4' : file._kind === 'documents' ? '' : '.jpg';
+    path = `${String(file._kind ?? 'documents')}/${name}${ext}`;
+    await ctx.write('file', String(file.id), { file_path: path }, ctx.call.operation.id);
+  }
+  return answer({ file_id: file.file_id, file_unique_id: file.file_unique_id, file_size: file.file_size, file_path: path });
+}
+
+// source: https://core.telegram.org/bots/api#getfile "The file can then be downloaded via the link https://api.telegram.org/file/bot<token>/<file_path> , where <file_path> is taken from the response."
+export async function downloadFile(ctx: HandlerContext): Promise<Response> {
+  botOf(ctx);
+  const path = String(ctx.call.params.file_path ?? '');
+  const file = ctx.rowsRaw('file').find((r) => r.deleted !== true && r.file_path === path);
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/HttpConnection.cpp "return send_http_error(404,"
+  if (!file) return refuse(ctx, 404, 'Not Found');
+  const bytes = await fileBytes(ctx, file);
+  return ctx.raw(bytes.slice(), { status: 200, headers: { 'content-type': String(file._mime ?? 'application/octet-stream'), 'content-length': String(bytes.byteLength) } });
+}