telegram-ask 0.1.1

package/dist/telegram/adapter.js

@@ -0,0 +1,99 @@
+import { updateConfigFile } from '../config/index.js';
+import { CALLBACK_DATA_PATTERN } from './constants.js';
+/** Button payload `<id>:<optionIndex>`; `routeTap` parses it. */
+export function formatCallbackData(id, optionIndex) {
+    return `${id}:${optionIndex}`;
+}
+/**
+ * 'ignored' for anyone but the owner, 'expired' for malformed data, else whatever `tap` returns.
+ */
+export function routeTap(fromId, data, ownerId, tap) {
+    if (ownerId === undefined || fromId !== ownerId) {
+        return 'ignored';
+    }
+    const [, id, rawIndex] = (data === undefined ? null : CALLBACK_DATA_PATTERN.exec(data)) ?? [];
+    if (id === undefined || rawIndex === undefined) {
+        return 'expired';
+    }
+    return tap(id, Number(rawIndex));
+}
+/**
+ * Sends requests as inline-keyboard messages to the owner; the final edit removes the buttons.
+ * Sending throws when nobody is paired.
+ */
+export function createTelegramMessenger(bot, owner) {
+    return {
+        async sendRequest(id, text, options) {
+            if (owner.id === undefined) {
+                throw new Error('bot is not paired yet');
+            }
+            const sent = await bot.api.sendMessage(owner.id, text, {
+                reply_markup: {
+                    inline_keyboard: options.map((label, index) => [
+                        { text: label, callback_data: formatCallbackData(id, index) },
+                    ]),
+                },
+            });
+            return { chatId: sent.chat.id, messageId: sent.message_id };
+        },
+        async finalize(reference, text) {
+            await bot.api.editMessageText(reference.chatId, reference.messageId, text, {
+                reply_markup: { inline_keyboard: [] },
+            });
+        },
+    };
+}
+/** Routes button taps to `tap`; always answers the callback so the button stops spinning. */
+export function registerTapHandler(bot, owner, tap) {
+    bot.on('callback_query:data', async (context) => {
+        const route = routeTap(context.from.id, context.callbackQuery.data, owner.id, tap);
+        if (route === 'expired') {
+            await context.answerCallbackQuery({ text: 'Expired' });
+        }
+        else {
+            await context.answerCallbackQuery();
+        }
+    });
+}
+/**
+ * Reply text for a pairing attempt, or undefined to stay silent (not a private chat, blocked, or
+ * already paired). Calls `onPaired` on success.
+ */
+export function handlePairingMessage(message, pairing, onPaired) {
+    if (message.chatType !== 'private') {
+        return undefined;
+    }
+    const result = pairing.attempt(message.fromId, message.text);
+    if (result === 'paired') {
+        onPaired(message.fromId);
+        return 'Paired. Approval requests will appear here.';
+    }
+    if (result === 'wrong') {
+        return "This bot isn't paired. Check the service logs for the pairing code.";
+    }
+    return undefined;
+}
+/** Feeds text messages to `handlePairingMessage` and sends any reply. */
+export function registerPairingHandler(bot, pairing, onPaired) {
+    bot.on('message:text', async (context) => {
+        const reply = handlePairingMessage({ fromId: context.from.id, chatType: context.chat.type, text: context.message.text }, pairing, onPaired);
+        if (reply !== undefined) {
+            await context.reply(reply);
+        }
+    });
+}
+/**
+ * Callback that sets the owner in memory first, then saves it to the config file. A failed save is
+ * logged, not thrown.
+ */
+export function createOnPaired(owner, path, log = console.error) {
+    return (id) => {
+        owner.id = id;
+        try {
+            updateConfigFile(path, { ownerId: id });
+        }
+        catch {
+            log(`paired with ${id} but couldn't save the owner to ${path}; it'll be lost on restart`);
+        }
+    };
+}

package/dist/telegram/constants.js

@@ -0,0 +1,12 @@
+/** Uppercase letters and digits without look-alikes (I, L, O, 0, 1). */
+export const PAIRING_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+/** Characters in a pairing code (shown as two groups of four). */
+export const PAIRING_CODE_LENGTH = 8;
+/** Wrong guesses allowed per Telegram user before they are blocked. */
+export const DEFAULT_MAX_FAILURES = 5;
+/** Leading `/start` or `/start@botname` on a pairing message. */
+export const START_COMMAND_PATTERN = /^\/start(@\w+)?/i;
+/** Dashes and whitespace ignored when comparing a typed code. */
+export const CODE_SEPARATOR_PATTERN = /[-\s]/g;
+/** Matches `<id>:<optionIndex>`, the format `formatCallbackData` writes. */
+export const CALLBACK_DATA_PATTERN = /^([^:]+):(\d+)$/;

package/dist/telegram/index.js

@@ -0,0 +1,3 @@
+export { createOnPaired, createTelegramMessenger, formatCallbackData, handlePairingMessage, registerPairingHandler, registerTapHandler, routeTap, } from './adapter.js';
+export { PAIRING_ALPHABET } from './constants.js';
+export { formatCode, generateCode, Pairing } from './pairing.js';

package/dist/telegram/pairing.js

@@ -0,0 +1,60 @@
+import { randomInt } from 'node:crypto';
+import { CODE_SEPARATOR_PATTERN, DEFAULT_MAX_FAILURES, PAIRING_ALPHABET, PAIRING_CODE_LENGTH, START_COMMAND_PATTERN, } from './constants.js';
+/** Random pairing code from `PAIRING_ALPHABET`; `random` is injectable for tests. */
+export function generateCode(random = randomInt) {
+    let code = '';
+    for (let index = 0; index < PAIRING_CODE_LENGTH; index += 1) {
+        code += PAIRING_ALPHABET[random(PAIRING_ALPHABET.length)];
+    }
+    return code;
+}
+/** Splits a code into two groups of four with a dash, for display. */
+export function formatCode(code) {
+    return `${code.slice(0, 4)}-${code.slice(4)}`;
+}
+function normalizeCode(text) {
+    return text
+        .trim()
+        .replace(START_COMMAND_PATTERN, '')
+        .toUpperCase()
+        .replace(CODE_SEPARATOR_PATTERN, '');
+}
+/**
+ * One-shot pairing state: the first correct code claims the bot, and each sender gets a limited
+ * number of wrong guesses.
+ */
+export class Pairing {
+    #code;
+    #maxFailures;
+    #failures = new Map();
+    constructor(code, maxFailures = DEFAULT_MAX_FAILURES) {
+        this.#code = code.toUpperCase();
+        this.#maxFailures = maxFailures;
+    }
+    /** The code to show, or undefined once paired. */
+    get code() {
+        return this.#code;
+    }
+    get paired() {
+        return this.#code === undefined;
+    }
+    /**
+     * Compares `text` (case, dashes and a leading /start ignored) to the code. Wrong guesses are
+     * counted per sender and block at the limit.
+     */
+    attempt(fromId, text) {
+        if (this.#code === undefined) {
+            return 'notPairing';
+        }
+        const failures = this.#failures.get(fromId) ?? 0;
+        if (failures >= this.#maxFailures) {
+            return 'blocked';
+        }
+        if (normalizeCode(text) === this.#code) {
+            this.#code = undefined;
+            return 'paired';
+        }
+        this.#failures.set(fromId, failures + 1);
+        return 'wrong';
+    }
+}

package/dist/telegram/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "telegram-ask",
+  "version": "0.1.1",
+  "description": "Local HTTP API that asks you a question on Telegram with inline buttons and returns your answer",
+  "keywords": [
+    "approval",
+    "bot",
+    "human-in-the-loop",
+    "telegram"
+  ],
+  "license": "Apache-2.0",
+  "author": "Cozmin",
+  "bin": {
+    "telegram-ask": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "start": "node src/cli.ts start",
+    "cli": "node src/cli.ts",
+    "test": "vp test",
+    "check": "vp check",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "commander": "^15.0.0",
+    "fastify": "^5.12.7",
+    "grammy": "^1.46.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2",
+    "vite-plus": "1.3.0"
+  },
+  "engines": {
+    "node": ">=24.2"
+  }
+}