@volter/twin-telegram 1.0.0 → 1.0.1

package/src/semantics/doors.ts

@@ -9,8 +9,6 @@ import {
   type Row,
 } from './shared.ts';
 
-export type { HandlerContext };
-
 const bad = (error: string, status = 400): Response => Response.json({ error }, { status });
 const str = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
 const num = (v: unknown): number | undefined => (typeof v === 'number' ? v : typeof v === 'string' && /^-?\d+$/.test(v) ? Number(v) : undefined);
@@ -27,15 +25,83 @@ export async function people(ctx: HandlerContext): Promise<Response> {
   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 as Row).id ?? ctx.own(row as Row).id));
 }
 
+/** A metadata-issued bot belongs to the first member's Telegram person. */
+async function applicationBot(ctx: HandlerContext): Promise<Response> {
+  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: HandlerContext): Promise<Response> {
+  const body = ctx.body && typeof ctx.body === 'object' ? ctx.body as Row : {};
+  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)) return bad('Sorry, this username is invalid.');
@@ -48,7 +114,7 @@ export async function bots(ctx: HandlerContext): Promise<Response> {
   // 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');
@@ -112,13 +178,13 @@ async function moveMember(ctx: HandlerContext, chat: Row, by: number, user: numb
   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: HandlerContext, chat: Row): Row =>
-  Object.fromEntries(Object.entries(chatFullView(ctx, chat)).filter(([k]) => ['id', 'type', 'title', 'username', 'first_name', 'last_name'].includes(k)));
+const chatViewOf = (chat: Row): Row =>
+  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: HandlerContext, chat: Row, fields: Row, from: number | undefined, operation: string, extra: Row = {}): Promise<Row> {
@@ -190,7 +256,7 @@ export async function chats(ctx: HandlerContext): Promise<Response> {
   // 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

package/src/semantics/shared.ts

@@ -8,7 +8,6 @@ import type { HandlerContext } from '@volter/world-core';
 import { finish, parseHtml, parseMarkdown, parseMarkdownV2, type Entity, type Formatted } from '../engine/text.ts';
 
 export type Row = Record<string, unknown>;
-export type { HandlerContext };
 
 // ── answers ─────────────────────────────────────────────────────────────────────────────────────────────────────
 
@@ -45,7 +44,7 @@ export function jsonParam(ctx: HandlerContext, name: string): { value?: unknown;
 }
 
 /** The vendor's own fields of a stored row: the kernel's bookkeeping (`_` fields, a tombstone) left out. */
-export function vendorFields(ctx: HandlerContext, row: Row): Row {
+function vendorFields(ctx: HandlerContext, row: Row): Row {
   return Object.fromEntries(Object.entries(ctx.own(row)).filter(([k]) => !k.startsWith('_') && k !== 'deleted'));
 }
 
@@ -100,7 +99,7 @@ export function userView(ctx: HandlerContext, id: unknown): Row {
 }
 
 /** A Chat as a message names it: its id, type and names. */
-export function chatView(ctx: HandlerContext, id: unknown): Row {
+function chatView(ctx: HandlerContext, id: unknown): Row {
   const row = ctx.row('chat', String(id));
   const v = row ? vendorFields(ctx, row) : { id: Number(id), type: 'private' };
   return Object.fromEntries(Object.entries(v).filter(([k]) => ['id', 'type', 'title', 'username', 'first_name', 'last_name', 'is_forum', 'is_direct_messages'].includes(k)));
@@ -141,7 +140,7 @@ export function messageView(ctx: HandlerContext, row: Row, nested = false): Row
 }
 
 /** A ChatFullInfo as getChat answers it, from a chat as chatOf reads it (its own id and type already restored). */
-export function chatFullView(_ctx: HandlerContext, chat: Row): Row {
+export function chatFullView(chat: Row): Row {
   return Object.fromEntries(Object.entries(chat).filter(([k]) => !k.startsWith('_') && k !== 'deleted'));
 }
 
@@ -220,11 +219,13 @@ export function formatted(ctx: HandlerContext, text: string, parseMode: unknown,
   // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Text is too long"
   if (new TextEncoder().encode(text).length > 1 << 15) return { refusal: refuse(ctx, 400, 'Bad Request: text is too long') };
   const mode = typeof parseMode === 'string' ? parseMode.toLowerCase() : '';
+  // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Unsupported parse_mode"
+  if (!['', 'none', 'html', 'markdownv2', 'markdown'].includes(mode)) return { refusal: refuse(ctx, 400, 'Bad Request: unsupported parse_mode') };
   let parsed: Formatted;
   if (mode === '' || mode === 'none') {
     const given = Array.isArray(entitiesParam) ? (entitiesParam as Entity[]) : [];
     parsed = { text, entities: given };
-  } else if (mode === 'html' || mode === 'markdownv2' || mode === 'markdown') {
+  } else {
     // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "text_parse_mode = make_object<td_api::textParseModeMarkdown>(2);"
     // source: https://core.telegram.org/bots/api#markdownv2-style "To use this mode, pass MarkdownV2 in the parse_mode field."
     // source: https://core.telegram.org/bots/api#markdown-style "This is a legacy mode, retained for backward compatibility."
@@ -234,9 +235,6 @@ export function formatted(ctx: HandlerContext, text: string, parseMode: unknown,
     // source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/MessageEntity.cpp "is reserved and must be escaped with the preceding"
     if ('error' in r) return { refusal: refuse(ctx, 400, `Bad Request: can't parse entities: ${r.error}`) };
     parsed = r;
-  } else {
-    // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Unsupported parse_mode"
-    return { refusal: refuse(ctx, 400, 'Bad Request: unsupported parse_mode') };
   }
   // a bot's text gets the entities the server finds (TDLib's fix_formatted_text: a bot finds new entities)
   // source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/MessageEntity.cpp "add_entities(MessageEntity::Type::Mention, find_mentions);"
@@ -338,6 +336,27 @@ export async function storeFile(ctx: HandlerContext, bytes: Uint8Array, meta: {
   return ctx.row('file', id)!;
 }
 
+/** 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. */
+// source: https://core.telegram.org/api/files "s - Server-side resized image, bounded by 100x100 pixels."
+// source: https://core.telegram.org/api/files "w - Server-side resized image, bounded by 2560x2560 pixels."
+// source: https://raw.githubusercontent.com/tdlib/td/42e6a5259551178d1dab54a22ad96d14bd906e20/td/telegram/PhotoSize.cpp "get_photo_sizes_object"
+export async 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 }>> {
+  const longer = Math.max(width, height), out: Array<{ file_id: unknown; file_unique_id: unknown; width: number; height: number }> = [];
+  // a photo's sizes are made once: the same photo sent again (by its file_id) answers the sizes it already has
+  // 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."
+  const made = ctx.rowsRaw('file').filter((r) => r.deleted !== true && r._thumbnail_of === original.file_unique_id && typeof r._width === 'number');
+  if (made.length) return made.map((r) => ({ file_id: r.file_id, file_unique_id: r.file_unique_id, width: r._width as number, height: r._height as number })).sort((x, y) => x.width - y.width);
+  for (const box of [100, 320, 800, 1280, 2560]) {
+    if (box >= longer) break;
+    const scale = box / longer, w = Math.max(1, Math.round(width * scale)), h = Math.max(1, Math.round(height * scale));
+    const row = await ctx.create('file', (id) => ({ file_id: `AgACAgIAAxkBAA${id.slice(4)}`, file_unique_id: id, _kind: 'photos', _thumbnail_of: original.file_unique_id, _width: w, _height: h, ...(original._bot !== undefined ? { _bot: original._bot } : {}) }), operation);
+    out.push({ file_id: (row as Row).file_id, file_unique_id: (row as Row).file_unique_id, width: w, height: h });
+  }
+  return out;
+}
+
 /** 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). */
 // source: https://core.telegram.org/bots/api#sending-files "file_id is unique for each individual bot and can't be transferred from one bot to another."

package/src/server.ts

@@ -1,17 +1,8 @@
 // FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).
-import { grpc, serveHttp, type PackFetchOptions } from '@volter/world-core';
+import { serveHttp, type PackFetchOptions } from '@volter/world-core';
 import { createTelegramFetch } from './fetch.ts';
-import { manifest } from './manifest.ts';
 
 export async function createTelegramTwinServer(options: PackFetchOptions & { port?: number } = {}): Promise<{ port: number; stop: () => void }> {
-  const fetch = createTelegramFetch(options);
-  // a vendor that speaks gRPC (its manifest's `grpc`): HTTP/2 and HTTP/1 on one port, each rpc through the fetch
-  if ('grpc' in manifest && manifest.grpc) {
-    const schemaPath = './generated/proto.gen.json';
-    const schema = (await import(schemaPath, { with: { type: 'json' } })).default as unknown as Parameters<typeof grpc.serveGrpc>[0]['schema'];
-    return grpc.serveGrpc({ ...(options.port ? { port: options.port } : {}), fetch: async (r) => fetch(r), schema });
-  }
-  // the vendor's sockets, when its manifest declares any (the kernel's sockets.ts)
-  const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch });
+  const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createTelegramFetch(options) });
   return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
 }

package/dist/generated/pack-facts.json

@@ -1,53 +0,0 @@
-{
-  "//": "GENERATED by scripts/pack-facts.ts — current pack descriptors and explicit world-runtime server backings; no prior-artifact entries are retained.",
-  "packs": {
-    "telegram": {
-      "adoption": {
-        "sdks": [
-          "@chat-adapter/telegram",
-          "node-telegram-bot-api",
-          "telegraf"
-        ],
-        "envStems": [
-          "TELEGRAM"
-        ]
-      },
-      "hosts": [
-        {
-          "host": "api.telegram.org"
-        }
-      ],
-      "archetype": "crud",
-      "protocol": {
-        "declared": "3",
-        "major": 3,
-        "standing": "current"
-      },
-      "transport": "web-api",
-      "resources": [
-        "user",
-        "chat",
-        "chat_member",
-        "message",
-        "update",
-        "file"
-      ],
-      "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"
-        }
-      },
-      "serveExport": "createTelegramTwinServer"
-    }
-  },
-  "undeclared": []
-}

package/dist/spec/page-to-openapi.ts

@@ -1,258 +0,0 @@
-// Writes an OpenAPI 3.1 document of the Telegram Bot API from its reference page (https://core.telegram.org/bots/api),
-// read as HTML (SOURCE.md names the bytes it read). Usage: bun spec/page-to-openapi.ts <page.html> <out.json>, then
-// `gzip -n -9` the output to spec/openapi.json.gz.
-//
-// Every method's parameters are declared twice: as its body (JSON, form or multipart) and in its query string, since
-// the Bot API reads them from either (Making requests: "We support four ways of passing parameters in Bot API
-// requests", the first "URL query string").
-import { readFileSync, writeFileSync } from 'node:fs';
-
-const [, , inPath, outPath] = process.argv;
-const html = readFileSync(inPath!, 'utf8');
-
-const decode = (s: string) =>
-  s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&');
-const text = (s: string) => decode(s.replace(/<br\s*\/?>/g, ' ').replace(/<[^>]+>/g, '')).replace(/\s+/g, ' ').trim();
-
-// the page in order: h3 sections and h4 items, each item's HTML up to the next heading
-type Item = { section: string; name: string; anchor: string; body: string };
-const items: Item[] = [];
-const heads = [...html.matchAll(/<h([34])><a class="anchor" name="([^"]+)"[^>]*><i class="anchor-icon"><\/i><\/a>([\s\S]*?)<\/h\1>/g)];
-let section = '';
-for (let i = 0; i < heads.length; i++) {
-  const h = heads[i]!;
-  const end = i + 1 < heads.length ? heads[i + 1]!.index! : html.indexOf('</div>', h.index!) > 0 ? html.length : html.length;
-  const body = html.slice(h.index! + h[0].length, end);
-  if (h[1] === '3') { section = text(h[3]!); continue; }
-  items.push({ section, name: text(h[3]!), anchor: h[2]!, body });
-}
-const METHOD_SECTIONS = new Set(['Getting updates', 'Available methods', 'Updating messages', 'Stickers', 'Rich messages', 'Inline mode', 'Payments', 'Telegram Passport', 'Games']);
-const isType = (it: Item) => /^[A-Z][A-Za-z0-9]+$/.test(it.name) && it.section !== 'Recent changes';
-const isMethod = (it: Item) => /^[a-z][A-Za-z0-9]+$/.test(it.name) && METHOD_SECTIONS.has(it.section) && !/\s/.test(it.name);
-const typeNames = new Set(items.filter(isType).map((t) => t.name));
-
-function tableRows(body: string): string[][] | null {
-  const t = body.match(/<table class="table">([\s\S]*?)<\/table>/);
-  if (!t) return null;
-  const rows = [...t[1]!.matchAll(/<tr>([\s\S]*?)<\/tr>/g)].map((r) => [...r[1]!.matchAll(/<t[dh]>([\s\S]*?)<\/t[dh]>/g)].map((c) => c[1]!));
-  return rows;
-}
-function beforeTable(body: string): string {
-  const i = body.indexOf('<table');
-  return i < 0 ? body : body.slice(0, i);
-}
-
-// a Type cell: Integer, String, Boolean, True, Float, InputFile, a type, "Array of X", "X or Y", "X, Y and Z"
-function schemaOf(cell: string): any {
-  const t = text(cell).replace(/\s+/g, ' ').trim();
-  return parseType(t);
-}
-function parseType(t: string): any {
-  t = t.trim();
-  const arr = t.match(/^Array of (.+)$/);
-  if (arr) return { type: 'array', items: parseType(arr[1]!) };
-  const parts = t.split(/\s*,\s*|\s+or\s+|\s+and\s+/).filter(Boolean);
-  if (parts.length > 1) return { oneOf: parts.map(parseType) };
-  switch (t) {
-    case 'Integer': case 'Int': return { type: 'integer' };
-    case 'String': return { type: 'string' };
-    case 'Boolean': return { type: 'boolean' };
-    case 'True': return { type: 'boolean', enum: [true] };
-    case 'False': return { type: 'boolean', enum: [false] };
-    case 'Float': case 'Float number': return { type: 'number' };
-    case 'InputFile': return { type: 'string', format: 'binary' };
-  }
-  if (typeNames.has(t)) return { $ref: `#/components/schemas/${t}` };
-  throw new Error(`unknown type: ${t}`);
-}
-
-// quoted values the description states a field can take (“private”, “group” …)
-function enumOf(desc: string, schema: any): any {
-  if (schema.type !== 'string') return schema;
-  const d = text(desc);
-  const m = d.match(/(?:\balways\b|\bcan be\b|\bmust be\b|\bone of\b)/);
-  if (!m) return schema;
-  // the rest of the sentence the phrase opens (a sentence ends at ". " before a capital, outside quotes)
-  const rest = d.slice(m.index!);
-  const end = rest.search(/\.\s+[A-Z]/);
-  const sentence = end < 0 ? rest : rest.slice(0, end);
-  const values = [...sentence.matchAll(/“([^”]+)”/g)].map((x) => x[1]!);
-  return values.length ? { ...schema, enum: [...new Set(values)] } : schema;
-}
-
-const schemas: Record<string, any> = {};
-for (const it of items.filter(isType)) {
-  const rows = tableRows(it.body);
-  const desc = text(beforeTable(it.body));
-  if (rows && rows[0]?.[0]?.trim() === 'Field') {
-    const properties: Record<string, any> = {};
-    const required: string[] = [];
-    for (const r of rows.slice(1)) {
-      const [f, ty, d] = r;
-      const name = text(f!);
-      const s = enumOf(d!, schemaOf(ty!));
-      properties[name] = { ...s, description: text(d!) };
-      if (!/^Optional\./.test(text(d!))) required.push(name);
-    }
-    schemas[it.name] = { type: 'object', description: desc, properties, ...(required.length ? { required } : {}) };
-    continue;
-  }
-  const list = it.body.match(/<ul>([\s\S]*?)<\/ul>/);
-  if (list && !rows) {
-    const lis = [...list[1]!.matchAll(/<li>([\s\S]*?)<\/li>/g)].map((m) => m[1]!.trim());
-    const refs = lis.map((li) => li.match(/^<a href="#[a-z0-9]+">([A-Za-z0-9]+)<\/a>$/)?.[1]).filter((n): n is string => Boolean(n && typeNames.has(n)));
-    if (refs.length && refs.length === lis.length) { schemas[it.name] = { description: desc, oneOf: refs.map((n) => ({ $ref: `#/components/schemas/${n}` })) }; continue; }
-  }
-  // a type that holds no information yet ("Currently holds no information"), or one described in prose only
-  schemas[it.name] = { type: 'object', description: desc };
-}
-// InputFile is the multipart upload itself, not a JSON object
-schemas.InputFile = { type: 'string', format: 'binary', description: schemas.InputFile?.description ?? 'This object represents the contents of a file to be uploaded.' };
-
-// the result an operation's description says is returned
-const RETURN_OVERRIDES: Record<string, any> = {};
-function resultOf(it: Item): any {
-  if (RETURN_OVERRIDES[it.name]) return RETURN_OVERRIDES[it.name];
-  const descHtml = beforeTable(it.body);
-  const sentences = descHtml.split(/(?<=\.)\s+(?=[A-Z<])/).filter((s) => /return/i.test(text(s)));
-  const found: any[] = [];
-  const seen = new Set<string>();
-  const add = (key: string, s: any) => { if (!seen.has(key)) { seen.add(key); found.push(s); } };
-  for (const s of sentences) {
-    const tx = s;
-    for (const m of tx.matchAll(/(Array of |array of |an array of )?<a href="#([a-z0-9]+)">([A-Za-z0-9]+)<\/a>(s?)/g)) {
-      const name = m[3]!;
-      if (!typeNames.has(name)) continue;
-      const isArr = Boolean(m[1]) || (m[4] === 's' && /array of/i.test(tx.slice(Math.max(0, m.index! - 40), m.index!)));
-      add(`${isArr ? '[]' : ''}${name}`, isArr ? { type: 'array', items: { $ref: `#/components/schemas/${name}` } } : { $ref: `#/components/schemas/${name}` });
-    }
-    const plain = text(tx);
-    if (/\bTrue\b/.test(plain)) add('true', { type: 'boolean', enum: [true] });
-    if (/\bas String\b|\bString on success\b|\bin form of a String\b|new invite link as String/.test(plain)) add('string', { type: 'string' });
-    if (/\bReturns Int(eger)?\b|\bas Int(eger)?\b|\bInt(eger)? on success\b/.test(plain)) add('integer', { type: 'integer' });
-    if (/\bReturns String\b/.test(plain)) add('string', { type: 'string' });
-  }
-  if (!found.length) { console.error(`NO RESULT ${it.name}: ${text(descHtml)}`); return {}; }
-  return found.length === 1 ? found[0] : { oneOf: found };
-}
-
-// the types a method's result names (by itself, as an array's items, or as one of several): each is what the Bot API
-// answers under `result` ("If 'ok' equals True, the request was successful and the result of the query can be found
-// in the 'result' field", Making requests), so each is declared a resource under its own name (`x-resourceId`, the
-// declaration the spec IR reads), and the IR reads every such answer under its envelope key, `answers.key: result`.
-// The page has no GET read to infer them from: every method is written as a POST.
-const answered = new Set<string>();
-const namedIn = (s: any): void => {
-  if (!s || typeof s !== 'object') return;
-  if (typeof s.$ref === 'string') answered.add(s.$ref.split('/').pop());
-  if (s.items) namedIn(s.items);
-  for (const alt of s.oneOf ?? []) namedIn(alt);
-};
-
-const TAG: Record<string, string> = {};
-const paths: Record<string, any> = {};
-const methods = items.filter(isMethod);
-for (const it of methods) {
-  const rows = tableRows(it.body);
-  const properties: Record<string, any> = {};
-  const required: string[] = [];
-  let hasFile = false;
-  if (rows && rows[0]?.[0]?.trim() === 'Parameter') {
-    for (const r of rows.slice(1)) {
-      const [p, ty, req, d] = r;
-      const name = text(p!);
-      const s = enumOf(d!, schemaOf(ty!));
-      if (/InputFile/.test(text(ty!))) hasFile = true;
-      properties[name] = { ...s, description: text(d!) };
-      if (text(req!) === 'Yes') required.push(name);
-    }
-  }
-  const body = { type: 'object', properties, ...(required.length ? { required } : {}) };
-  // the same parameters in the query string, none required there (a request carries each in one place or the other)
-  const query = Object.entries(properties).map(([name, schema]) => ({ name, in: 'query', required: false, description: schema.description, schema: Object.fromEntries(Object.entries(schema).filter(([k]) => k !== 'description')) }));
-  const result = resultOf(it);
-  namedIn(result);
-  paths[`/bot{token}/${it.name}`] = {
-    post: {
-      operationId: it.name,
-      tags: [it.section],
-      summary: it.name,
-      description: text(beforeTable(it.body)),
-      externalDocs: { url: `https://core.telegram.org/bots/api#${it.anchor}` },
-      parameters: [{ $ref: '#/components/parameters/token' }, ...query],
-      ...(Object.keys(properties).length
-        ? {
-            requestBody: {
-              required: required.length > 0,
-              content: {
-                'application/json': { schema: body },
-                'application/x-www-form-urlencoded': { schema: body },
-                'multipart/form-data': { schema: body },
-              },
-            },
-          }
-        : {}),
-      responses: {
-        '200': {
-          description: 'The request was successful: the result of the query is in the result field.',
-          content: { 'application/json': { schema: { type: 'object', required: ['ok', 'result'], properties: { ok: { type: 'boolean', enum: [true] }, result, description: { type: 'string' } } } } },
-        },
-        default: { $ref: '#/components/responses/Error' },
-      },
-    },
-  };
-  TAG[it.section] = it.section;
-}
-// the file download path getFile names ("https://api.telegram.org/file/bot<token>/<file_path>")
-paths['/file/bot{token}/{file_path}'] = {
-  get: {
-    operationId: 'downloadFile',
-    tags: ['Available methods'],
-    summary: 'Download a file',
-    description: text(beforeTable(items.find((i) => i.name === 'getFile')!.body)),
-    externalDocs: { url: 'https://core.telegram.org/bots/api#getfile' },
-    parameters: [{ $ref: '#/components/parameters/token' }, { name: 'file_path', in: 'path', required: true, schema: { type: 'string' } }],
-    responses: { '200': { description: 'The file', content: { 'application/octet-stream': { schema: { type: 'string', format: 'binary' } } } }, default: { $ref: '#/components/responses/Error' } },
-  },
-};
-
-for (const name of answered) if (schemas[name]) schemas[name]['x-resourceId'] = name;
-
-const ver = text(html.match(/<strong>Bot API ([0-9.]+)<\/strong>/)?.[0] ?? html.match(/Bot API ([0-9.]+)/)?.[0] ?? '');
-const doc = {
-  openapi: '3.1.0',
-  info: {
-    title: 'Telegram Bot API',
-    version: ver.replace(/^Bot API /, ''),
-    description: 'Written from https://core.telegram.org/bots/api (spec/SOURCE.md): every method and type the page documents.',
-  },
-  servers: [{ url: 'https://api.telegram.org' }],
-  tags: [...new Set(methods.map((m) => m.section))].map((name) => ({ name })),
-  paths,
-  components: {
-    parameters: {
-      token: { name: 'token', in: 'path', required: true, description: "The bot's authentication token, as BotFather gives it (123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).", schema: { type: 'string' } },
-    },
-    responses: {
-      Error: {
-        description: "The request was unsuccessful: 'ok' equals False and the error is explained in the 'description'.",
-        content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } },
-      },
-    },
-    schemas: {
-      Error: {
-        type: 'object',
-        required: ['ok', 'error_code', 'description'],
-        properties: {
-          ok: { type: 'boolean', enum: [false] },
-          error_code: { type: 'integer' },
-          description: { type: 'string' },
-          parameters: { $ref: '#/components/schemas/ResponseParameters' },
-        },
-      },
-      ...schemas,
-    },
-  },
-};
-writeFileSync(outPath!, JSON.stringify(doc, null, 1) + '\n');
-console.log(`methods ${methods.length}, types ${Object.keys(schemas).length}, version ${doc.info.version}`);