@volter/twin-telegram 1.0.0 → 1.0.1

package/dist/src/engine/media.js

@@ -1,75 +1,37 @@
-// What Telegram reads from an uploaded file's own bytes: an image's width and height (a PhotoSize), and a video's width,
-// height and duration (a Video), each from the format's header as that format defines it. Pure computation over bytes.
-const u16be = (b, i) => (b[i] << 8) | b[i + 1];
-const u32be = (b, i) => ((b[i] << 24) >>> 0) + (b[i + 1] << 16) + (b[i + 2] << 8) + b[i + 3];
-const u16le = (b, i) => b[i] | (b[i + 1] << 8);
-const ascii = (b, i, n) => String.fromCharCode(...b.subarray(i, i + n));
-/** An image's size from its header: PNG (IHDR), GIF (logical screen), JPEG (the first start-of-frame); undefined for
- *  anything else (a photo Telegram takes is a .jpg, .jpeg, .gif, .png, .tif or .bmp, MessagesManager.cpp's
- *  PHOTO_EXT_INVALID; the twin reads the first three). */
-export function imageSize(b) {
-    if (b.length >= 24 && b[0] === 0x89 && ascii(b, 1, 3) === 'PNG' && ascii(b, 12, 4) === 'IHDR')
-        return { width: u32be(b, 16), height: u32be(b, 20), mime: 'image/png' };
-    if (b.length >= 10 && ascii(b, 0, 3) === 'GIF')
-        return { width: u16le(b, 6), height: u16le(b, 8), mime: 'image/gif' };
-    // a JPEG's markers are walked to its first frame header; a JPEG with none, like any other file, has no size
-    const jpeg = b.length >= 4 && b[0] === 0xff && b[1] === 0xd8;
-    for (let i = 2; jpeg && i + 9 < b.length; i += b[i] !== 0xff ? 1 : jpegStep(b, i)) {
-        const marker = b[i + 1];
-        // SOF0-SOF15 but DHT (C4), JPG (C8) and DAC (CC) carry the frame's height and width
-        if (b[i] === 0xff && marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc)
-            return { height: u16be(b, i + 5), width: u16be(b, i + 7), mime: 'image/jpeg' };
-    }
-    return undefined;
+// Telegram's format acceptance and presentation policy over the shared file-header facts.
+import { readImageHeader, readMp4Header } from '@volter/world-core';
+/** Telegram reads PNG's IHDR, GIF's logical screen and JPEG's first frame; other formats have no photo size. */
+export function imageSize(bytes) {
+    const image = readImageHeader(bytes);
+    if (!image || image.type === 'image/webp')
+        return undefined;
+    if (image.type === 'image/png' && String.fromCharCode(...bytes.subarray(12, 16)) !== 'IHDR')
+        return undefined;
+    if (image.type === 'image/jpeg' && (!image.jpeg || image.jpeg.frameEnd >= bytes.length))
+        return undefined;
+    return { width: image.width, height: image.height };
 }
-/** How far a JPEG's marker at `i` reaches: a marker with no length (SOI, TEM, RSTn) is its two bytes, any other its
- *  length after them. */
-const jpegStep = (b, i) => {
-    const marker = b[i + 1];
-    return marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7) ? 2 : 2 + u16be(b, i + 2);
-};
-/** An MP4's (ISO base media) duration in whole seconds from its movie header (mvhd), and the first track with a size
- *  from its track header (tkhd: 16.16 fixed-point width and height); undefined for a file that is not one. */
-export function mp4Info(b) {
-    if (b.length < 12 || ascii(b, 4, 4) !== 'ftyp')
+/** Whole-second duration from the last usable movie header, and the first track whose floored width is nonzero. */
+export function mp4Info(bytes) {
+    if (bytes.length < 12)
+        return undefined;
+    const file = readMp4Header(bytes);
+    if (!file.fileType)
         return undefined;
     let duration;
     let width = 0;
     let height = 0;
-    const walk = (start, end) => {
-        let i = start;
-        while (i + 8 <= end) {
-            let size = u32be(b, i);
-            const type = ascii(b, i + 4, 4);
-            let header = 8;
-            if (size === 1 && i + 16 <= end) {
-                size = u32be(b, i + 8) * 2 ** 32 + u32be(b, i + 12);
-                header = 16;
-            }
-            if (size === 0)
-                size = end - i;
-            if (size < header || i + size > end)
-                return;
-            if (type === 'moov' || type === 'trak')
-                walk(i + header, i + size);
-            else if (type === 'mvhd') {
-                const v = b[i + header];
-                const timescale = v === 1 ? u32be(b, i + header + 20) : u32be(b, i + header + 12);
-                const units = v === 1 ? u32be(b, i + header + 24) * 2 ** 32 + u32be(b, i + header + 28) : u32be(b, i + header + 16);
-                if (timescale)
-                    duration = Math.round(units / timescale);
-            }
-            else if (type === 'tkhd' && !width) {
-                const v = b[i + header];
-                const at = i + header + (v === 1 ? 88 : 76);
-                if (at + 8 <= i + size) {
-                    width = u32be(b, at) >>> 16;
-                    height = u32be(b, at + 4) >>> 16;
-                }
+    for (const movie of file.movies) {
+        for (const header of movie.headers) {
+            if (header.timescale)
+                duration = Math.round(header.duration / header.timescale);
+        }
+        for (const track of movie.tracks) {
+            if (!width) {
+                width = Math.floor(track.width);
+                height = Math.floor(track.height);
             }
-            i += size;
         }
-    };
-    walk(0, b.length);
+    }
     return duration === undefined ? undefined : { width, height, duration };
 }

package/dist/src/engine/text.d.ts

@@ -29,13 +29,6 @@ export declare function parseMarkdownV2(input: string): Formatted | {
 export declare function parseMarkdown(input: string): Formatted | {
     error: string;
 };
-/** Entities in TDLib's order: by offset, the longer first. */
-export declare function sortEntities(entities: Entity[]): Entity[];
-/** The entities the server finds in a text by itself: mentions (@name, 2-32 letters, digits and underscores, not
- *  inside a word), bot commands (/command, 1-64, optionally @bot), hashtags (#tag with a letter), cashtags ($ABC),
- *  links (http, https, or www.) and e-mail addresses. Where the twin stops: TDLib's own link matcher also takes bare
- *  domains by their top-level domain, and finds bank card numbers; the twin does not. */
-export declare function findEntities(text: string, skipBotCommands: boolean): Entity[];
 /** What the server keeps of a formatted text (TDLib's fix_formatted_text): whitespace trimmed from both ends (the
  *  entities moved and cut with it), the entities it finds itself added where they cross none given, sorted. Empty
  *  is the caller's to refuse. */

package/dist/src/engine/text.js

@@ -446,7 +446,7 @@ export function parseMarkdown(input) {
     return { text: out, entities: sortEntities(entities) };
 }
 /** Entities in TDLib's order: by offset, the longer first. */
-export function sortEntities(entities) {
+function sortEntities(entities) {
     return [...entities].sort((a, b) => a.offset - b.offset || b.length - a.length);
 }
 const WORD = /[\p{L}\p{N}_]/u;
@@ -455,7 +455,7 @@ const isWord = (ch) => ch !== undefined && WORD.test(ch);
  *  inside a word), bot commands (/command, 1-64, optionally @bot), hashtags (#tag with a letter), cashtags ($ABC),
  *  links (http, https, or www.) and e-mail addresses. Where the twin stops: TDLib's own link matcher also takes bare
  *  domains by their top-level domain, and finds bank card numbers; the twin does not. */
-export function findEntities(text, skipBotCommands) {
+function findEntities(text, skipBotCommands) {
     const found = [];
     const scan = (re, type, ok = () => true) => {
         for (const m of text.matchAll(re)) {

package/dist/src/index.js

@@ -1,5 +1,6 @@
 // @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").
+// kernel derives the vendor-backed half from the generated surface, unless the manifest declares none (vendorBacked.none;
+// architecture, "The real-system adapters").
 import { packOf, registerPack } from '@volter/world-core';
 import { manifest } from "./manifest.js";
 import surface from './generated/surface.gen.json' with { type: 'json' };

package/dist/src/manifest.js

@@ -36,11 +36,12 @@ export const manifest = {
         // 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' } },
+        user: { idPrefix: '58104400', ids: '{prefix}{n}', unique: [{ fields: ['_username'], refusal: { status: 409, message: 'This username is taken.' } }], 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}' } } },
+        // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Bad Request: chat not found"
+        chat: { idPrefix: '', ...states.chat, refresh: { get: 'getChat', known: true, query: { chat_id: '{id}' }, gone: { status: 400, says: 'chat not found' } } },
         // 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
@@ -53,7 +54,7 @@ export const manifest = {
         // 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: '' },
+        _bot: { idPrefix: '', unique: [{ fields: ['id'], refusal: { status: 409, message: 'This bot already has credentials.' } }] },
         // 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}' },
@@ -88,15 +89,15 @@ export const manifest = {
         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.",
+        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 calls 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)',
+        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)',
         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' } },
+        credentialDoor: { account: { field: 'account', tenancy: 'Telegram person', source: 'https://core.telegram.org/bots/features#botfather' }, deployment: { field: 'deployment', object: 'Bot', source: 'https://core.telegram.org/bots/features#botfather' }, 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/dist/src/semantics/available-methods.js

@@ -1,5 +1,5 @@
 import { imageSize, mp4Info } from "../engine/media.js";
-import { answer, botOf, chatFor, chatFullView, fileBytes, fileById, formatted, jsonParam, memberKey, memberView, messageView, param, refuse, replyTarget, storeBotMessage, storeFile, textFields, uploadOf, } from "./shared.js";
+import { answer, botOf, chatFor, chatFullView, fileBytes, fileById, formatted, jsonParam, memberKey, memberView, messageView, param, refuse, replyTarget, storeBotMessage, storeFile, photoThumbnails, textFields, uploadOf, } from "./shared.js";
 // 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"
@@ -48,11 +48,8 @@ function captionOf(ctx, caption, parseMode, entities) {
         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, botId, kind, upload, given) {
-    const operation = ctx.call.operation.id;
-    let file;
+/** Read and validate a medium without creating files, thumbnails or messages. */
+async function prepareMedia(ctx, kind, upload, given) {
     let bytes;
     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
@@ -63,50 +60,58 @@ async function mediaFields(ctx, botId, kind, upload, given) {
         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);
+        bytes = await fileBytes(ctx, upload.file);
     }
-    else {
+    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)) {
+    // 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 (!('file' in upload) && bytes.byteLength > (kind === 'photo' ? 10 : 50) * 1024 * 1024)
+        return { refusal: refuse(ctx, 400, 'Bad Request: file is too big') };
+    const size = kind === 'photo' ? imageSize(bytes) : undefined;
+    if (!('file' in upload)) {
+        if (kind === 'photo' && !size) {
             // 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 === 'photo')
+        return { kind, upload, bytes, size: size ?? { width: 0, height: 0 } };
+    const name = 'file' in upload ? upload.file._name : upload.name;
+    const mime = 'file' in upload ? upload.file._mime : upload.mime;
+    const fields = { ...(typeof name === 'string' && name ? { file_name: name } : {}), ...(typeof mime === 'string' && mime ? { mime_type: mime } : {}), file_size: bytes.byteLength };
     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, fallback) => (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 { kind, upload, bytes, fields: { width: num(given.width, info?.width ?? 0), height: num(given.height, info?.height ?? 0), duration: num(given.duration, info?.duration ?? 0), ...fields } };
     }
-    return { document: { ...ids, ...(name ? { file_name: name } : {}), ...(mime ? { mime_type: mime } : {}), file_size: bytes.byteLength } };
+    return { kind, upload, bytes, fields };
+}
+/** Persist a validated medium and assemble its message fields. */
+async function mediaFields(ctx, botId, media) {
+    const operation = ctx.call.operation.id;
+    const upload = media.upload;
+    const file = 'file' in upload ? upload.file : await storeFile(ctx, media.bytes, { kind: media.kind === 'photo' ? 'photos' : media.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 (media.kind === 'photo') {
+        // its smaller sizes first, then the photo as it was given
+        // source: https://core.telegram.org/bots/api#message "Optional. Message is a photo, available sizes of the photo"
+        const thumbnails = await photoThumbnails(ctx, file, media.size.width, media.size.height, operation);
+        return { photo: [...thumbnails, { ...ids, file_size: media.bytes.byteLength, ...media.size }] };
+    }
+    return { [media.kind]: { ...ids, ...media.fields } };
 }
 /** One medium sent to a chat with its caption. */
 async function sendMedium(ctx, kind) {
@@ -123,10 +128,11 @@ async function sendMedium(ctx, kind) {
     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') });
+    const media = await prepareMedia(ctx, kind, upload, { width: param(ctx, 'width'), height: param(ctx, 'height'), duration: param(ctx, 'duration') });
     if ('refusal' in media)
         return media.refusal;
-    const row = await storeBotMessage(ctx, botId, access.chat, { ...media, ...caption }, reply.key, ctx.call.operation.id);
+    const fields = await mediaFields(ctx, botId, media);
+    const row = await storeBotMessage(ctx, botId, access.chat, { ...fields, ...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."
@@ -180,16 +186,17 @@ export async function sendMediaGroup(ctx) {
         const caption = captionOf(ctx, item.caption, item.parse_mode, item.caption_entities);
         if ('refusal' in caption)
             return caption.refusal;
-        prepared.push({ kind: item.type, upload, caption, item });
+        const medium = await prepareMedia(ctx, item.type, upload, { width: item.width, height: item.height, duration: item.duration });
+        if ('refusal' in medium)
+            return medium.refusal;
+        prepared.push({ media: medium, caption });
     }
     // 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 = [];
     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;
+        const fields = await mediaFields(ctx, botId, p.media);
         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));
     }
@@ -216,7 +223,7 @@ export async function getChat(ctx) {
     const access = chatFor(ctx, botId, param(ctx, 'chat_id'), 'read');
     if ('refusal' in access)
         return access.refusal;
-    return answer(chatFullView(ctx, access.chat));
+    return answer(chatFullView(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) {
@@ -239,6 +246,9 @@ export async function getFile(ctx) {
     // 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');
+    // a thumbnail's pixels are not rendered by the twin
+    if (file._thumbnail_of !== undefined)
+        return ctx.gap();
     // 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');
@@ -255,9 +265,9 @@ export async function getFile(ctx) {
 }
 // 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) {
-    botOf(ctx);
+    const { id: botId } = botOf(ctx);
     const path = String(ctx.call.params.file_path ?? '');
-    const file = ctx.rowsRaw('file').find((r) => r.deleted !== true && r.file_path === path);
+    const file = ctx.rowsRaw('file').filter((r) => r.file_path === path).map((r) => fileById(ctx, r.file_id, botId)).find((r) => 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');

package/dist/src/semantics/doors.d.ts

@@ -1,5 +1,4 @@
 import type { HandlerContext } from '@volter/world-core';
-export type { HandlerContext };
 /** A Telegram account, as a person signs up in the app. */
 export declare function people(ctx: HandlerContext): Promise<Response>;
 /** BotFather's /newbot: a bot (its name, its username ending in "bot") and its token; the same username answers the

package/dist/src/semantics/doors.js

@@ -16,14 +16,91 @@ export async function people(ctx) {
     const row = await ctx.create('user', (id) => ({
         id: Number(id), is_bot: false, first_name: first,
         ...(str(ctx.params.last_name) ? { last_name: str(ctx.params.last_name) } : {}),
-        ...(username ? { username } : {}),
+        ...(username ? { username, _username: username.toLowerCase() } : {}),
         ...(str(ctx.params.language_code) ? { language_code: str(ctx.params.language_code) } : {}),
     }), 'people');
     return Response.json(userView(ctx, row.id ?? ctx.own(row).id));
 }
+/** A metadata-issued bot belongs to the first member's Telegram person. */
+async function applicationBot(ctx) {
+    const owner = await ctx.tenant('user', async (world) => {
+        const email = world.members[0].toLowerCase();
+        const existing = ctx.rowsRaw('user').find((row) => row.is_bot !== true && row._email === email);
+        return existing ? String(existing.id) : String((await ctx.create('user', (id) => ({
+            id: Number(id), is_bot: false, first_name: world.label, _email: email,
+        }), 'people')).id);
+    });
+    const organization = await ctx.account();
+    const bot = await ctx.deploymentObject(`bot:${owner.id}`, 'user', async (deployment) => {
+        const explicit = str(ctx.params.username)?.replace(/^@/, '');
+        const label = (explicit ?? deployment) || 'world_twin';
+        const base = label.replace(/_?bot$/i, '') || 'world';
+        const identity = deployment ? `${organization}/${deployment}` : organization;
+        for (const suffixed of [false, true]) {
+            const username = explicit && !suffixed && /^[A-Za-z0-9_]{5,32}$/.test(explicit) && /bot$/i.test(explicit) ? explicit
+                : `${ctx.vendorName(base, { max: 28, lower: true, allowed: /[a-z0-9_]/, separator: '_' }, { suffixed, identity })}_bot`;
+            if (userByName(ctx, username))
+                continue;
+            const made = await ctx.createUnique('user', (id) => ({ id: Number(id), is_bot: true,
+                first_name: str(ctx.params.name) ?? (deployment || 'World Twin Bot'), username, _username: username.toLowerCase(),
+                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 }), 'bots');
+            if (made.created) {
+                const id = String(made.row.id);
+                await ctx.record('_bot', { owner: owner.id, generation: 1, update_seq: 836_000_000 }, id);
+                return id;
+            }
+        }
+        throw bad(`A bot username already exists for ${identity}.`, 409);
+    });
+    const key = await ctx.accountKey(`bot-token:${bot.id}`, '_bot', {
+        make: async () => {
+            const id = String(bot.id);
+            const before = ctx.row('_bot', id);
+            if (!before) {
+                const retired = ctx.row('_bot', id, { withDeleted: true });
+                const generation = Number(retired?.generation ?? 0) + 1;
+                const token = await issueToken(ctx, id, generation);
+                await ctx.createUnique('_bot', {
+                    id, owner: owner.id, generation, token_sha256: ctx.crypto.sha256(token),
+                    update_seq: retired?.update_seq ?? 836_000_000, deleted: false, _pending: false,
+                }, 'bot.token', { id, input: 'omit' });
+                return id;
+            }
+            const current = await issueToken(ctx, String(bot.id), Number(before.generation ?? 1));
+            if (before.token_sha256 === ctx.crypto.sha256(current))
+                return String(bot.id);
+            await ctx.change('_bot', String(bot.id), (row) => row._pending === true || row.token_sha256 !== before.token_sha256 ? undefined
+                : { generation: row.token_sha256 === undefined ? Number(row.generation ?? 1) : Number(row.generation ?? 1) + 1, _pending: true }, 'bot.token.reserve');
+            const native = ctx.row('_bot', String(bot.id));
+            const token = await issueToken(ctx, String(bot.id), Number(native.generation));
+            await ctx.change('_bot', String(bot.id), (row) => row.generation === native.generation
+                ? { token_sha256: ctx.crypto.sha256(token), _pending: false } : undefined, 'bot.token');
+            return String(bot.id);
+        },
+        read: async (row) => {
+            if (row.owner !== owner.id || row._pending === true)
+                return undefined;
+            const token = await issueToken(ctx, String(bot.id), Number(row.generation));
+            return row.token_sha256 === ctx.crypto.sha256(token) ? token : undefined;
+        },
+    });
+    return Response.json({ id: Number(bot.id), name: bot.first_name, username: bot.username, token: key.secret });
+}
 /** BotFather's /newbot: a bot (its name, its username ending in "bot") and its token; the same username answers the
  *  bot made before and its token as it stands, so a World's credential door answers the same token at every boot. */
 export async function bots(ctx) {
+    const body = ctx.body && typeof ctx.body === 'object' ? ctx.body : {};
+    if (body.account !== undefined || body.deployment !== undefined) {
+        try {
+            return await applicationBot(ctx);
+        }
+        catch (error) {
+            if (error instanceof Response)
+                return error;
+            throw error;
+        }
+    }
     // source: https://core.telegram.org/bots/features#botfather "Usernames are 5-32 characters long and not case sensitive – but may only include Latin characters, numbers, and underscores. Your bot's username must end in 'bot’, like 'tetris_bot' or 'TetrisBot'."
     const username = (str(ctx.params.username) ?? 'world_twin_bot').replace(/^@/, '');
     if (!/^[A-Za-z0-9_]{5,32}$/.test(username) || !/bot$/i.test(username))
@@ -39,7 +116,7 @@ export async function bots(ctx) {
     // was not set up for
     // source: https://core.telegram.org/bots/features#privacy-mode "Privacy mode is enabled by default for all bots"
     const row = await ctx.create('user', (id) => ({
-        id: Number(id), is_bot: true, first_name: name, username,
+        id: Number(id), is_bot: true, first_name: name, username, _username: username.toLowerCase(),
         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,
     }), 'bots');
@@ -108,11 +185,11 @@ async function moveMember(ctx, chat, by, user, to, rights, operation) {
     const after = ctx.row('chat_member', key);
     if (ctx.row('user', String(user))?.is_bot === true && user !== by) {
         // source: https://core.telegram.org/bots/api#update "Optional. The bot's chat member status was updated in a chat."
-        await queueUpdate(ctx, user, 'my_chat_member', { chat: chatViewOf(ctx, chat), from: userView(ctx, by), date: unixOf(ctx.occurredAt), old_chat_member: before, new_chat_member: memberView(ctx, after, user) }, operation);
+        await queueUpdate(ctx, user, 'my_chat_member', { chat: chatViewOf(chat), from: userView(ctx, by), date: unixOf(ctx.occurredAt), old_chat_member: before, new_chat_member: memberView(ctx, after, user) }, operation);
     }
     return after;
 }
-const chatViewOf = (ctx, chat) => Object.fromEntries(Object.entries(chatFullView(ctx, chat)).filter(([k]) => ['id', 'type', 'title', 'username', 'first_name', 'last_name'].includes(k)));
+const chatViewOf = (chat) => Object.fromEntries(Object.entries(chatFullView(chat)).filter(([k]) => ['id', 'type', 'title', 'username', 'first_name', 'last_name'].includes(k)));
 /** A message a person (or the app, for a service message) writes in a chat, kept and delivered to the bots it reaches. */
 async function post(ctx, chat, fields, from, operation, extra = {}) {
     const chatKey = String(chat.id);
@@ -191,7 +268,7 @@ export async function chats(ctx) {
     // source: https://core.telegram.org/bots/api#message "Optional. Service message: the group has been created"
     const created = type === 'group' ? { group_chat_created: true } : type === 'supergroup' ? { supergroup_chat_created: true } : { channel_chat_created: true };
     await post(ctx, chat(), created, creator, operation);
-    return Response.json(chatFullView(ctx, chat()));
+    return Response.json(chatFullView(chat()));
 }
 /** A person adds a member to a chat, promotes one, or removes one (kicked); a group is told by a service message who
  *  joined or was removed. */

package/dist/src/semantics/shared.d.ts

@@ -1,7 +1,6 @@
 import type { HandlerContext } from '@volter/world-core';
 import { type Formatted } from '../engine/text.js';
 export type Row = Record<string, unknown>;
-export type { HandlerContext };
 export declare function answer(result: unknown, description?: string): Response;
 /** A refusal in the Bot API's envelope ({ ok: false, error_code, description }), the HTTP status its code. */
 export declare function refuse(ctx: HandlerContext, status: number, description: string): Response;
@@ -14,8 +13,6 @@ export declare function jsonParam(ctx: HandlerContext, name: string): {
     value?: unknown;
     error?: true;
 };
-/** The vendor's own fields of a stored row: the kernel's bookkeeping (`_` fields, a tombstone) left out. */
-export declare function vendorFields(ctx: HandlerContext, row: Row): Row;
 /** The methods this pack serves, as the page names them: a request naming one in another case is routed to it. */
 export declare const SERVED_METHODS: string[];
 /** The token in a request's path: `/bot<token>/<method>`, or `/file/bot<token>/<path>` for a file. */
@@ -36,8 +33,6 @@ export declare function botOf(ctx: HandlerContext): {
 export declare function issueToken(ctx: HandlerContext, botId: string, generation: number): Promise<string>;
 /** A User as it appears in a message or an update: the bot-only fields are getMe's alone. */
 export declare function userView(ctx: HandlerContext, id: unknown): Row;
-/** A Chat as a message names it: its id, type and names. */
-export declare function chatView(ctx: HandlerContext, id: unknown): Row;
 /** A ChatMember: its status, its user and what the status carries. */
 export declare function memberView(ctx: HandlerContext, row: Row | undefined, user: unknown): Row;
 /** A chat member's row (`<chat>:<user>`). */
@@ -46,7 +41,7 @@ export declare const memberKey: (chat: unknown, user: unknown) => string;
  *  carries no reply of its own. */
 export declare function messageView(ctx: HandlerContext, row: Row, nested?: boolean): Row;
 /** A ChatFullInfo as getChat answers it, from a chat as chatOf reads it (its own id and type already restored). */
-export declare function chatFullView(_ctx: HandlerContext, chat: Row): Row;
+export declare function chatFullView(chat: Row): Row;
 /** The chat a chat_id names: an integer id or a public chat's @username. */
 export declare function findChat(ctx: HandlerContext, chatId: unknown): Row | undefined;
 /** A chat as stored, its own `id` and `type` (the vendor's, which the kernel keeps apart from its own) restored. */
@@ -86,6 +81,15 @@ export declare function storeFile(ctx: HandlerContext, bytes: Uint8Array, meta:
     name?: string;
     bot?: number;
 }, operation: string): Promise<Row>;
+/** The smaller sizes Telegram makes of an uploaded photo, smallest first: each size type whose box is smaller than the
+ *  photo's longer side, the photo scaled to fit it (the rounding is the twin's). A thumbnail is kept by its ids and
+ *  dimensions only: the twin renders no thumbnail's pixels, so its file is a gap. */
+export declare function photoThumbnails(ctx: HandlerContext, original: Row, width: number, height: number, operation: string): Promise<Array<{
+    file_id: unknown;
+    file_unique_id: unknown;
+    width: number;
+    height: number;
+}>>;
 /** A file by its file_id, as one bot holds it: a file a bot uploaded is that bot's alone (a chat's photo is every
  *  bot's that reads the chat). */
 export declare function fileById(ctx: HandlerContext, fileId: unknown, botId: number): Row | undefined;