@volter/twin-telegram 1.0.0

package/dist/src/semantics/doors.js

@@ -0,0 +1,292 @@
+import { finish } from "../engine/text.js";
+import { chatFullView, chatOf, findChat, issueToken, memberKey, memberView, messageView, nextMessageId, queueUpdate, recipientsOf, storeFile, unixOf, userView, } from "./shared.js";
+const bad = (error, status = 400) => Response.json({ error }, { status });
+const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+const num = (v) => (typeof v === 'number' ? v : typeof v === 'string' && /^-?\d+$/.test(v) ? Number(v) : undefined);
+const userByName = (ctx, name) => ctx.rowsRaw('user').find((u) => u.deleted !== true && typeof u.username === 'string' && u.username.toLowerCase() === name.replace(/^@/, '').toLowerCase());
+/** A Telegram account, as a person signs up in the app. */
+export async function people(ctx) {
+    const first = str(ctx.params.first_name);
+    if (!first)
+        return bad('first_name is required');
+    const username = str(ctx.params.username)?.replace(/^@/, '');
+    // source: https://core.telegram.org/bots/api#user "Optional. User's or bot's username"
+    if (username && userByName(ctx, username))
+        return bad(`the username ${username} is taken`, 409);
+    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 } : {}),
+        ...(str(ctx.params.language_code) ? { language_code: str(ctx.params.language_code) } : {}),
+    }), 'people');
+    return Response.json(userView(ctx, row.id ?? ctx.own(row).id));
+}
+/** 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) {
+    // 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.');
+    const name = str(ctx.params.name) ?? 'World Twin Bot';
+    const owner = num(ctx.params.owner);
+    if (owner !== undefined && !ctx.row('user', String(owner)))
+        return bad(`no person ${owner}`, 404);
+    const held = userByName(ctx, username);
+    if (held)
+        return heldBot(ctx, held);
+    // a bot's own fields, which getMe alone returns: it joins groups, privacy mode is on, and it offers nothing it
+    // 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,
+        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');
+    const id = String(row.id ?? ctx.own(row).id);
+    const token = await issueToken(ctx, id, 1);
+    await ctx.record('_bot', { owner: owner ?? null, generation: 1, token_sha256: ctx.crypto.sha256(token), update_seq: 836_000_000 }, id);
+    return Response.json({ id: Number(id), name, username, token });
+}
+/** The bot a username already names, and its token as it stands (a World's credential door asked again at a boot). */
+async function heldBot(ctx, held) {
+    if (held.is_bot !== true)
+        return bad('Sorry, this username is already taken.', 409);
+    const bot = ctx.row('_bot', String(held.id));
+    return Response.json({ id: Number(ctx.own(held).id), name: held.first_name, username: held.username, token: await issueToken(ctx, String(held.id), Number(bot.generation ?? 1)) });
+}
+/** BotFather's /token: a new token for the bot; the one before stops working. */
+// source: https://core.telegram.org/bots/features#botfather "If your existing token is compromised or you lost it for some reason, use the /token command to generate a new one."
+export async function botToken(ctx) {
+    const held = userByName(ctx, String(ctx.call.params.username ?? ''));
+    if (!held || held.is_bot !== true)
+        return bad('no such bot', 404);
+    const id = String(held.id);
+    const bot = ctx.row('_bot', id);
+    const owner = num(ctx.params.owner);
+    if (bot.owner !== null && bot.owner !== undefined && owner !== Number(bot.owner))
+        return bad('only the bot\'s owner makes its token', 403);
+    const generation = Number(bot.generation ?? 1) + 1;
+    const token = await issueToken(ctx, id, generation);
+    await ctx.record('_bot', { generation, token_sha256: ctx.crypto.sha256(token) }, id);
+    return Response.json({ id: Number(ctx.own(held).id), username: held.username, token });
+}
+/** Default administrator rights for a member made an administrator in the app, as the app proposes them, with what
+ *  the door's `rights` says. */
+function adminRights(type, rights) {
+    const base = {
+        can_be_edited: false, is_anonymous: false, can_manage_chat: true, can_delete_messages: false, can_manage_video_chats: false,
+        can_restrict_members: false, can_promote_members: false, can_change_info: false, can_invite_users: true,
+        can_post_stories: false, can_edit_stories: false, can_delete_stories: false, can_send_welcome_messages: false,
+        ...(type === 'channel' ? { can_post_messages: false, can_edit_messages: false } : { can_pin_messages: false }),
+    };
+    for (const [k, v] of Object.entries(rights))
+        if (k in base && typeof v === 'boolean')
+            base[k] = v;
+    return base;
+}
+/** A member's status moved by a person in the app (the machine allows it), its rights kept, and a bot told of its own
+ *  move (my_chat_member). */
+async function moveMember(ctx, chat, by, user, to, rights, operation) {
+    const key = memberKey(chat.id, user);
+    const prior = ctx.row('chat_member', key);
+    const current = prior && prior.deleted !== true ? String(prior.status) : 'left';
+    const refused = ctx.legal('chat_member', 'status', operation, current, to, key, 'external');
+    if (refused)
+        return bad(refused.message, refused.status);
+    const before = memberView(ctx, prior, user);
+    const fields = { _chat: chat.id, _user: user, status: to };
+    if (to === 'administrator')
+        Object.assign(fields, adminRights(String(chat.type), rights));
+    // source: https://core.telegram.org/bots/api#chatmemberowner "Represents a chat member that owns the chat and has all administrator privileges."
+    if (to === 'creator')
+        Object.assign(fields, { is_anonymous: false });
+    // source: https://core.telegram.org/bots/api#chatmemberbanned "If 0, then the user is banned forever"
+    if (to === 'kicked')
+        Object.assign(fields, { until_date: 0 });
+    await ctx.write('chat_member', key, fields, 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);
+    }
+    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)));
+/** 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);
+    const messageId = await nextMessageId(ctx, chatKey, operation);
+    const key = `${chatKey}:${messageId}`;
+    const channel = chat.type === 'channel';
+    await ctx.write('message', key, {
+        message_id: messageId, date: unixOf(ctx.occurredAt), ...fields,
+        _chat: chat.id,
+        // source: https://core.telegram.org/bots/api#message "Optional. Sender of the message when sent on behalf of a chat. For example, the supergroup itself for messages sent by its anonymous administrators or a linked channel for messages automatically forwarded to the channel's discussion group."
+        ...(channel ? { _sender_chat: chat.id } : from !== undefined ? { _from: from } : {}),
+        ...extra,
+    }, operation);
+    const row = ctx.row('message', key);
+    // source: https://core.telegram.org/bots/api#update "Optional. New incoming channel post of any kind - text, photo, sticker, etc."
+    const type = channel ? 'channel_post' : 'message';
+    for (const bot of recipientsOf(ctx, chatOf(ctx, chatKey), row))
+        await queueUpdate(ctx, bot, type, messageView(ctx, row), operation);
+    return row;
+}
+/** A chat a person makes in the app: a group, a supergroup or a channel, its creator its owner, its members added, and
+ *  the service message that it was made. */
+export async function chats(ctx) {
+    const creator = num(ctx.params.creator);
+    if (creator === undefined || ctx.row('user', String(creator))?.is_bot !== false)
+        return bad('creator must be a person (a user id)');
+    const type = str(ctx.params.type);
+    if (!type || !['group', 'supergroup', 'channel'].includes(type))
+        return bad('type is group, supergroup or channel');
+    const title = str(ctx.params.title);
+    if (!title)
+        return bad('title is required');
+    const username = str(ctx.params.username)?.replace(/^@/, '');
+    if (username && (ctx.rowsRaw('chat').some((c) => c.deleted !== true && String(c.username ?? '').toLowerCase() === username.toLowerCase()) || userByName(ctx, username)))
+        return bad(`the username ${username} is taken`, 409);
+    if (username && type === 'group')
+        return bad('a basic group has no username; make it a supergroup');
+    const id = await ctx.issue(type === 'group' ? '_group' : '_channel');
+    const operation = 'chats';
+    let photo;
+    const photoData = str(ctx.params.photo);
+    if (photoData) {
+        const bytes = Uint8Array.from(atob(photoData), (c) => c.charCodeAt(0));
+        // a chat photo in its two sizes, each its own file
+        // source: https://core.telegram.org/bots/api#chatphoto "File identifier of small (160x160) chat photo."
+        const small = await storeFile(ctx, bytes, { kind: 'profile_photos', mime: 'image/jpeg' }, operation);
+        const big = await storeFile(ctx, bytes, { kind: 'profile_photos', mime: 'image/jpeg' }, operation);
+        photo = { small_file_id: small.file_id, small_file_unique_id: small.file_unique_id, big_file_id: big.file_id, big_file_unique_id: big.file_unique_id };
+    }
+    const n = Math.abs(Number(id));
+    await ctx.write('chat', id, {
+        id: Number(id), type, title,
+        ...(username ? { username, active_usernames: [username] } : {}),
+        ...(photo ? { photo } : {}),
+        ...(str(ctx.params.description) ? { description: str(ctx.params.description) } : {}),
+        // Where the documentation stops: a chat's own accent color, reaction count and accepted gifts until someone sets
+        // them; the page names the colors 0-6 a theme customizes, and the twin takes the id's remainder by 7
+        // source: https://core.telegram.org/bots/api#accent-colors "Colors with identifiers 0 (red), 1 (orange), 2 (purple/violet), 3 (green), 4 (cyan), 5 (blue), 6 (pink) can be customized by app themes."
+        accent_color_id: n % 7,
+        max_reaction_count: 11,
+        accepted_gift_types: { unlimited_gifts: false, limited_gifts: false, unique_gifts: false, premium_subscription: false, gifts_from_channels: false },
+    }, operation);
+    const chat = () => chatOf(ctx, id);
+    const own = await moveMember(ctx, chat(), creator, creator, 'creator', {}, operation);
+    if (own instanceof Response)
+        return own;
+    for (const m of (Array.isArray(ctx.params.members) ? ctx.params.members : [])) {
+        const user = num(m.user);
+        if (user === undefined || !ctx.row('user', String(user)))
+            return bad(`no user ${String(m.user)}`, 404);
+        const to = m.status === 'administrator' ? 'administrator' : 'member';
+        const moved = await moveMember(ctx, chat(), creator, user, to, (m.rights ?? {}), operation);
+        if (moved instanceof Response)
+            return moved;
+    }
+    // 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()));
+}
+/** 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. */
+export async function members(ctx) {
+    const chat = chatOf(ctx, String(ctx.call.params.chat_id ?? ''));
+    if (!chat || chat.deleted === true || chat.type === 'private')
+        return bad('no such group or channel', 404);
+    const by = num(ctx.params.by);
+    const user = num(ctx.params.user);
+    if (by === undefined || user === undefined || !ctx.row('user', String(by)) || !ctx.row('user', String(user)))
+        return bad('by and user are user ids');
+    const to = str(ctx.params.status);
+    if (!to || !['member', 'administrator', 'kicked'].includes(to))
+        return bad('status is member, administrator or kicked');
+    // a person adds, promotes or removes a member only as an administrator of the chat
+    const actor = ctx.row('chat_member', memberKey(chat.id, by));
+    if (!actor || !['creator', 'administrator'].includes(String(actor.status)))
+        return bad('only an administrator of the chat does that', 403);
+    const prior = ctx.row('chat_member', memberKey(chat.id, user));
+    const was = String(prior?.status ?? 'left');
+    // what the app does not offer: making a member what it already is, or demoting an administrator (not served)
+    if (was === to || (was === 'creator') || (to === 'member' && was === 'administrator'))
+        return bad(`the member is ${was}`, 409);
+    const operation = 'members';
+    const moved = await moveMember(ctx, chat, by, user, to, (ctx.params.rights ?? {}), operation);
+    if (moved instanceof Response)
+        return moved;
+    if (chat.type !== 'channel') {
+        // source: https://core.telegram.org/bots/api#message "Optional. New members that were added to the group or supergroup and information about them (the bot itself may be one of these members)"
+        if ((to === 'member' || to === 'administrator') && !['member', 'administrator', 'creator'].includes(was))
+            await post(ctx, chatOf(ctx, chat.id), {}, by, operation, { _new_members: [user] });
+        // source: https://core.telegram.org/bots/api#message "Optional. A member was removed from the group, information about them (this member may be the bot itself)"
+        if (to === 'kicked' && ['member', 'administrator'].includes(was))
+            await post(ctx, chatOf(ctx, chat.id), { left_chat_member: userView(ctx, user) }, by, operation);
+    }
+    return Response.json(memberView(ctx, moved, user));
+}
+/** A person writes a message in the app: in a group or a channel they are in, or to a bot (its @username) in private,
+ *  which starts the bot for them. The app marks what the text holds (mentions, commands, links) as the server does. */
+export async function messages(ctx) {
+    const from = num(ctx.params.from);
+    const person = from === undefined ? undefined : ctx.row('user', String(from));
+    if (!person || person.is_bot !== false)
+        return bad('from must be a person (a user id)');
+    const text = typeof ctx.params.text === 'string' ? ctx.params.text : '';
+    if (!text.trim())
+        return bad('text is required');
+    const target = ctx.params.chat;
+    const operation = 'messages';
+    let chat;
+    let extra = {};
+    const bot = typeof target === 'string' && target.startsWith('@') ? userByName(ctx, target) : undefined;
+    if (bot && bot.is_bot === true) {
+        // a private chat is the person's own id, as a bot sees it
+        // source: https://core.telegram.org/bots/api#chat "Unique identifier for this chat."
+        const key = String(from);
+        if (!ctx.row('chat', key)) {
+            await ctx.write('chat', key, {
+                id: from, type: 'private', first_name: person.first_name,
+                ...(person.last_name ? { last_name: person.last_name } : {}), ...(person.username ? { username: person.username } : {}),
+                accent_color_id: Math.abs(Number(from)) % 7, max_reaction_count: 11,
+                accepted_gift_types: { unlimited_gifts: false, limited_gifts: false, unique_gifts: false, premium_subscription: false, gifts_from_channels: false },
+            }, operation);
+        }
+        // writing to a bot starts it: from now on it may write to the person
+        // source: https://core.telegram.org/bots/features#botfather "Users will see a Start button the first time they open a chat with your bot."
+        // (a private chat's start sends the bot no my_chat_member: that is only for a block or an unblock)
+        // source: https://core.telegram.org/bots/api#update "For private chats, this update is received only when the bot is blocked or unblocked by the user."
+        const member = ctx.row('chat_member', memberKey(key, bot.id));
+        if (!member || member.status !== 'member') {
+            const refused = ctx.legal('chat_member', 'status', operation, String(member?.status ?? 'left'), 'member', memberKey(key, bot.id), 'external');
+            if (refused)
+                return bad(refused.message, refused.status);
+            await ctx.write('chat_member', memberKey(key, bot.id), { _chat: from, _user: Number(bot.id), status: 'member' }, operation);
+        }
+        chat = chatOf(ctx, key);
+        extra = { _with: Number(bot.id) };
+    }
+    else {
+        chat = num(target) !== undefined ? chatOf(ctx, num(target)) : typeof target === 'string' ? findChat(ctx, target) : undefined;
+        if (!chat || chat.type === 'private')
+            return bad('no such chat', 404);
+        const member = ctx.row('chat_member', memberKey(chat.id, from));
+        const status = String(member?.status ?? 'left');
+        if (!['creator', 'administrator', 'member'].includes(status))
+            return bad('the person is not a member of the chat', 403);
+        if (chat.type === 'channel' && !['creator', 'administrator'].includes(status))
+            return bad('only administrators post in a channel', 403);
+    }
+    const reply = num(ctx.params.reply_to_message_id);
+    if (reply !== undefined && !ctx.row('message', `${chat.id}:${reply}`))
+        return bad('no such message to reply to', 404);
+    const formattedText = finish({ text, entities: [] }, { find: true, skipBotCommands: false });
+    const row = await post(ctx, chat, { text: formattedText.text, ...(formattedText.entities.length ? { entities: formattedText.entities } : {}) }, from, operation, {
+        ...extra, ...(reply !== undefined ? { _reply_to: `${chat.id}:${reply}` } : {}),
+    });
+    return Response.json(messageView(ctx, row));
+}

package/dist/src/semantics/getting-updates.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function getUpdates(ctx: HandlerContext): Promise<Response>;
+export declare function deleteWebhook(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/getting-updates.js

@@ -0,0 +1,68 @@
+import { answer, botOf, intParam, jsonParam, param } from "./shared.js";
+// source: https://core.telegram.org/bots/api#getting-updates "Incoming updates are stored on the server until the bot receives them either way, but they will not be kept longer than 24 hours."
+const KEPT_MS = 24 * 60 * 60 * 1000;
+// source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.h "static constexpr int32 LONG_POLL_MAX_TIMEOUT = 50;"
+const LONG_POLL_MAX_TIMEOUT = 50;
+/** The updates of a bot still kept, from `from` on, in order. */
+function waiting(ctx, botId, from) {
+    const now = Date.parse(ctx.occurredAt);
+    return ctx.rowsRaw('update')
+        .filter((u) => u.deleted !== true && Number(u._bot) === botId && Number(u.update_id) >= from && now - Date.parse(String(u._made ?? ctx.occurredAt)) < KEPT_MS)
+        .sort((a, b) => Number(a.update_id) - Number(b.update_id));
+}
+export async function getUpdates(ctx) {
+    const { id: botId } = botOf(ctx);
+    const operation = ctx.call.operation.id;
+    // source: https://core.telegram.org/bots/api#getupdates "Limits the number of updates to be retrieved. Values between 1-100 are accepted. Defaults to 100."
+    const limit = Math.min(100, Math.max(1, intParam(ctx, 'limit') ?? 100));
+    // source: https://core.telegram.org/bots/api#getupdates "Timeout in seconds for long polling. Defaults to 0, i.e. usual short polling."
+    const timeout = Math.min(LONG_POLL_MAX_TIMEOUT, Math.max(0, intParam(ctx, 'timeout') ?? 0));
+    let offset = intParam(ctx, 'offset') ?? 0;
+    // the update types the bot asks for, kept for the updates made from now on
+    // source: https://core.telegram.org/bots/api#getupdates "If not specified, the previous setting will be used."
+    // a form's field is read by its exact name, as the server reads a query's arguments: a client that encodes the list
+    // as allowed_updates[0]=… (a form library's bracket notation) names no allowed_updates at all
+    // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "auto allowed_update_types = get_allowed_update_types(query->arg("
+    const form = (ctx.call.request.headers.get('content-type') ?? '').includes('application/x-www-form-urlencoded');
+    const exact = form ? new URLSearchParams(await ctx.call.request.clone().text()).get('allowed_updates') ?? new URL(ctx.call.request.url).searchParams.get('allowed_updates') ?? undefined : undefined;
+    const allowed = form ? (exact === undefined ? {} : (() => { try {
+        return { value: JSON.parse(exact) };
+    }
+    catch {
+        return { error: true };
+    } })()) : jsonParam(ctx, 'allowed_updates');
+    if ('value' in allowed && Array.isArray(allowed.value))
+        await ctx.record('_bot', { allowed_updates: allowed.value.map(String) }, String(botId));
+    const mine = ctx.rowsRaw('update').filter((u) => u.deleted !== true && Number(u._bot) === botId).sort((a, b) => Number(a.update_id) - Number(b.update_id));
+    // a negative offset keeps only the last -offset updates and forgets the rest
+    // source: https://core.telegram.org/bots/api#getupdates "The negative offset can be specified to retrieve updates starting from -offset update from the end of the updates queue. All previous updates will be forgotten."
+    if (offset < 0) {
+        for (const u of mine.slice(0, Math.max(0, mine.length + offset)))
+            await ctx.remove('update', String(u.id), operation);
+        offset = 0;
+    }
+    // the updates below the offset are confirmed, and so forgotten
+    // 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."
+    if (offset > 0)
+        for (const u of mine)
+            if (Number(u.update_id) < offset)
+                await ctx.remove('update', String(u.id), operation);
+    let found = waiting(ctx, botId, offset);
+    // nothing waiting: the request is held until an update comes or the timeout passes (a long poll)
+    // source: https://core.telegram.org/bots/api#getupdates "Should be positive, short polling should be used for testing purposes only."
+    if (!found.length && timeout > 0 && (await ctx.awaitWrite(['update'], timeout * 1000)))
+        found = waiting(ctx, botId, offset);
+    return answer(found.slice(0, limit).map((u) => Object.fromEntries(Object.entries(ctx.own(u)).filter(([k]) => !k.startsWith('_') && k !== 'deleted'))));
+}
+export async function deleteWebhook(ctx) {
+    const { id: botId } = botOf(ctx);
+    // source: https://core.telegram.org/bots/api#deletewebhook "Pass True to drop all pending updates"
+    if (ctx.flag(param(ctx, 'drop_pending_updates')) === true) {
+        for (const u of ctx.rowsRaw('update'))
+            if (u.deleted !== true && Number(u._bot) === botId)
+                await ctx.remove('update', String(u.id), ctx.call.operation.id);
+    }
+    // no webhook is ever set in this pack's scope, so the server answers that it is already deleted
+    // source: https://raw.githubusercontent.com/tdlib/telegram-bot-api/e3e9dd8e5b3d7ab8537cd5a10dc31d5ffa8f82d1/telegram-bot-api/Client.cpp "Webhook is already deleted"
+    return answer(true, 'Webhook is already deleted');
+}

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

@@ -0,0 +1,2 @@
+import type { Handler } from '@volter/world-core';
+export declare const telegramSemantics: Record<string, Handler>;

package/dist/src/semantics/index.js

@@ -0,0 +1,19 @@
+import * as available_methods from "./available-methods.js";
+import * as getting_updates from "./getting-updates.js";
+import * as updating_messages from "./updating-messages.js";
+export const telegramSemantics = {
+    deleteMessage: updating_messages.deleteMessage,
+    deleteWebhook: getting_updates.deleteWebhook,
+    downloadFile: available_methods.downloadFile,
+    getChat: available_methods.getChat,
+    getChatMember: available_methods.getChatMember,
+    getFile: available_methods.getFile,
+    getMe: available_methods.getMe,
+    getUpdates: getting_updates.getUpdates,
+    sendChatAction: available_methods.sendChatAction,
+    sendDocument: available_methods.sendDocument,
+    sendMediaGroup: available_methods.sendMediaGroup,
+    sendMessage: available_methods.sendMessage,
+    sendPhoto: available_methods.sendPhoto,
+    sendVideo: available_methods.sendVideo,
+};

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

@@ -0,0 +1,112 @@
+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;
+/** A parameter as the request gave it: a query or form value is text, a JSON body's value keeps its type. */
+export declare function param(ctx: HandlerContext, name: string): unknown;
+/** An integer parameter, or undefined when absent or not one. */
+export declare function intParam(ctx: HandlerContext, name: string): number | undefined;
+/** A JSON-serialized parameter (reply_parameters, media, allowed_updates): a form value is its JSON text. */
+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. */
+export declare function tokenOf(request: Request): string | undefined;
+/** The bot a well-formed token names when its secret is the one BotFather last issued (a token made again revokes
+ *  the one before), or why not. */
+export declare function botOfToken(ctx: HandlerContext, token: string | undefined): {
+    bot: Row;
+    user: Row;
+} | 'invalid' | 'unknown';
+/** The bot the request's token names (around.ts has refused any other before the method ran). */
+export declare function botOf(ctx: HandlerContext): {
+    id: number;
+    bot: Row;
+    user: Row;
+};
+/** A bot's token: its user id and a secret drawn from the World's seed for this bot and this issue of it. */
+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>`). */
+export declare const memberKey: (chat: unknown, user: unknown) => string;
+/** A Message as the Bot API answers it, its user, chat and replied message read as they stand. A replied message
+ *  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;
+/** 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. */
+export declare function chatOf(ctx: HandlerContext, key: unknown): Row | undefined;
+/** The chat a bot reaches with chat_id, and its own membership there, or the server's refusal: a read needs the chat
+ *  known to the bot; a write in a group, a supergroup or a channel needs the bot a member, in a channel an
+ *  administrator that may post, and in a private chat the person having started the bot. */
+export declare function chatFor(ctx: HandlerContext, botId: number, chatId: unknown, need: 'read' | 'write'): {
+    chat: Row;
+    member: Row | undefined;
+} | {
+    refusal: Response;
+};
+/** A text or a caption as the server keeps it: parsed by its parse_mode (HTML, MarkdownV2 or Markdown, named in any
+ *  case; plain when none), with the entities the server finds itself, trimmed; or the server's refusal. */
+export declare function formatted(ctx: HandlerContext, text: string, parseMode: unknown, entitiesParam: unknown): Formatted | {
+    refusal: Response;
+};
+/** A message's text, its entities only where it has some. */
+export declare const textFields: (f: Formatted, as: "text" | "caption") => Row;
+/** The next message_id of a chat: one past the last it holds. */
+export declare function nextMessageId(ctx: HandlerContext, chatKey: string, operation: string): Promise<number>;
+/** The message a reply names in this chat, or the server's refusal; `allow` sends without it when it is gone. */
+export declare function replyTarget(ctx: HandlerContext, chat: Row, botId: number): {
+    key?: string;
+} | {
+    refusal: Response;
+};
+/** A bot's message stored in a chat (it writes no update for its sender: a bot is not sent its own messages), and
+ *  the bot kept as the last that wrote in a group (privacy mode reads it). */
+export declare function storeBotMessage(ctx: HandlerContext, botId: number, chat: Row, fields: Row, replyKey: string | undefined, operation: string): Promise<Row>;
+export declare const unixOf: (iso: string) => number;
+/** A file kept: its bytes as a blob, its row naming them; a file_id that leads with the kind of file it is. */
+export declare function storeFile(ctx: HandlerContext, bytes: Uint8Array, meta: {
+    kind: string;
+    mime?: string;
+    name?: string;
+    bot?: number;
+}, operation: string): Promise<Row>;
+/** 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;
+/** An upload's part as the request carries it: multipart bytes, the name `attach://<name>` points at, a file_id sent
+ *  again, or an HTTP URL; or the server's refusal. */
+export type Upload = {
+    bytes: Uint8Array;
+    name?: string;
+    mime?: string;
+} | {
+    file: Row;
+};
+export declare function uploadOf(ctx: HandlerContext, value: unknown, botId: number): Upload | {
+    refusal: Response;
+};
+/** A file's bytes. */
+export declare function fileBytes(ctx: HandlerContext, file: Row): Promise<Uint8Array>;
+/** An update put in a bot's queue, when the allowed_updates the bot last asked for take its type: a setting does not
+ *  reach the updates made before it, so a type is decided when its update is made. */
+export declare function queueUpdate(ctx: HandlerContext, botId: unknown, type: string, payload: Row, operation: string): Promise<void>;
+/** The bots a person's message in a chat reaches, as privacy mode lets each: in a private chat its bot; in a channel
+ *  every bot member; in a group an administrator bot every message, any other the service messages, the commands
+ *  meant for it and the replies to it. */
+export declare function recipientsOf(ctx: HandlerContext, chat: Row, message: Row): number[];