Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions .github/workflows/bot-api-watch.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
name: Bot API watch

# Weekly check of the latest Telegram Bot API spec against src/assets/js/data.js.
# Opens (or updates) an issue labelled "bot-api-update" when something is missing.
on:
schedule:
- cron: '17 6 * * 1'
workflow_dispatch:

permissions:
contents: read
issues: write

jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 22
- id: check
name: Compare with Bot API spec
run: |
set +e
node scripts/check-bot-api.mjs > report.md
code=$?
cat report.md
echo "status=$code" >> "$GITHUB_OUTPUT"
[ "$code" -le 1 ]
- name: Open or update issue
if: steps.check.outputs.status == '1'
env:
GH_TOKEN: ${{ github.token }}
run: |
gh label create bot-api-update --color 2481cc --description "Telegram Bot API changed" 2>/dev/null || true
version=$(sed -n 's/^Spec: \*\*Bot API \([0-9.]*\)\*\*.*/\1/p' report.md)
{
echo "The Telegram Bot API spec differs from \`src/assets/js/data.js\`."
echo
cat report.md
echo
echo "To update: edit \`src/assets/js/data.js\` (lists and \`BOT_API_VERSION\`), add labels to all \`src/i18n/*.json\`, then run \`npm test\` and \`node scripts/check-bot-api.mjs\`."
} > body.md
existing=$(gh issue list --label bot-api-update --state open --json number --jq '.[0].number')
if [ -n "$existing" ]; then
gh issue edit "$existing" --title "Update to Telegram Bot API $version" --body-file body.md
else
gh issue create --title "Update to Telegram Bot API $version" --label bot-api-update --body-file body.md
fi
55 changes: 53 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
name: CI

# Runs once per pull request update (no duplicate push runs); main is checked by the deploy workflow.
on:
pull_request:
push:
branches-ignore: [main]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true

jobs:
test:
runs-on: ubuntu-latest
Expand All @@ -18,3 +22,50 @@ jobs:
node-version: 22
- run: npm test
- run: npm run build
- uses: actions/upload-artifact@v4
with:
name: dist
path: dist
include-hidden-files: true
retention-days: 3

e2e:
needs: test
# Pinned: Playwright 1.56 has no browser builds for ubuntu-latest (26.04) yet.
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 22
- uses: actions/download-artifact@v4
with:
name: dist
path: dist
- name: Install Playwright
run: |
npm install --no-save playwright@1.56.1
npx playwright install --with-deps chromium
# Mocked Bot API flows; fails on any console error or CSP violation.
- run: node scripts/screenshots.mjs --no-shots

lighthouse:
needs: test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 22
- uses: actions/download-artifact@v4
with:
name: dist
path: dist
- run: npx --yes @lhci/cli@0.15.1 autorun
- if: always()
uses: actions/upload-artifact@v4
with:
name: lighthouse-reports
path: .lighthouseci
include-hidden-files: true
retention-days: 14
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@ dist/
Thumbs.db
.idea/
.vscode/
.lighthouseci/
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,16 @@
# Changelog

## 3.1.0 — 2026-11-04

### Added
- `scripts/check-bot-api.mjs`: compares the latest Bot API spec with the project's reference data.
- Weekly “Bot API watch” workflow that opens an issue when the API changes.
- CI runs the end-to-end test and a Lighthouse audit on every pull request; duplicate push runs removed.
- `CLAUDE.md` with the Bot API update procedure.

### Changed
- The Bot API version is defined once in `data.js`; translations and the OG image use it automatically.

## 3.0.1 — 2026-10-08

### Fixed
Expand Down
18 changes: 18 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Telegram Bot Manager — notes for agents

Static site (GitHub Pages) that calls the Telegram Bot API from the browser. No backend, no npm dependencies.

- Build: `npm run build` → `dist/`. Unit tests: `npm test`. E2E with mocked API: `node scripts/screenshots.mjs --no-shots` (needs Playwright).
- Deploy: every push to `main` runs `.github/workflows/pages.yml`. Work on a branch and merge via PR; CI (`ci.yml`) runs unit tests, e2e and Lighthouse on PRs.
- UI strings live in `src/i18n/{en,ru,es,pt,zh}.json`; all locales must have the same keys (tests enforce it). Write natural translations, not machine-literal ones.
- The Bot API version is defined only in `BOT_API_VERSION` in `src/assets/js/data.js`; locale strings use the `{botApiVersion}` token.
- Never commit bot tokens. Never add analytics or third-party scripts: the page handles bot tokens and has a strict CSP.

## Updating to a new Bot API version

1. `node scripts/check-bot-api.mjs` — lists new update types, admin rights, getMe flags, command scopes, setWebhook params and bot-settings methods (spec: PaulSonOfLars/telegram-bot-api-spec; core.telegram.org may be unreachable).
2. Update `src/assets/js/data.js`: `UPDATE_GROUPS` (mark `optIn` if the spec says it must be requested explicitly), `ADMIN_RIGHTS` (with `target`), `ME_FLAGS`, `COMMAND_SCOPES`, `BOT_API_VERSION`.
3. Add labels for every new key to all five locale files (`app.updates.*`, `app.rights.*`, `app.me.*`, `app.scopes.*`). `npm test` lists anything missing.
4. A new bot-settings method that needs its own UI (a new tab or form) is a design change: describe it in the PR instead of building it silently.
5. Update `CHANGELOG.md` and the version badge in `README.md`; bump `package.json` patch/minor version.
6. Re-run the check (must print “Up to date”), `npm test`, `npm run build`, the e2e test, then `node scripts/images.mjs` to refresh the OG image.
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,12 @@ npm run build && node scripts/screenshots.mjs # e2e smoke test (Playwright + C

**New Bot API version:** update `src/assets/js/data.js` (update types, admin rights, `getMe` flags) and the translations; `npm test` lists every missing label.

## Automation

- **CI** (`.github/workflows/ci.yml`, on pull requests): unit tests, build, end-to-end test in Chromium against a mocked Bot API, and a Lighthouse audit (accessibility and best practices must stay ≥ 95/90; reports are attached to the run).
- **Bot API watch** (`.github/workflows/bot-api-watch.yml`, weekly): compares the latest Bot API spec with `src/assets/js/data.js` via `scripts/check-bot-api.mjs` and opens an issue labelled `bot-api-update` when something is missing.
- **Agent instructions** for updating the project are in [`CLAUDE.md`](CLAUDE.md).

## FAQ

**How do I check my bot's webhook?** Connect the bot and open the Webhook tab: it calls `getWebhookInfo` and explains the last error.
Expand Down
23 changes: 23 additions & 0 deletions lighthouserc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"ci": {
"collect": {
"staticDistDir": "./dist",
"url": [
"http://localhost/index.html",
"http://localhost/ru/index.html",
"http://localhost/set-webhook/index.html"
],
"numberOfRuns": 1,
"settings": { "chromeFlags": "--no-sandbox --headless=new" }
},
"assert": {
"assertions": {
"categories:accessibility": ["error", { "minScore": 0.95 }],
"categories:best-practices": ["error", { "minScore": 0.9 }],
"categories:seo": ["warn", { "minScore": 0.9 }],
"categories:performance": ["warn", { "minScore": 0.85 }]
}
},
"upload": { "target": "filesystem", "outputDir": ".lighthouseci" }
}
}
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
{
"name": "telegram-bot-manager",
"version": "3.0.1",
"version": "3.1.0",
"private": true,
"description": "Free online Telegram Bot Manager: set, check and delete webhooks, edit commands, profile, menu button and admin rights right in your browser.",
"type": "module",
"scripts": {
"build": "node scripts/build.mjs",
"test": "node --test \"tests/*.test.mjs\"",
"serve": "node scripts/serve.mjs",
"check:bot-api": "node scripts/check-bot-api.mjs",
"start": "node scripts/build.mjs && node scripts/serve.mjs"
},
"engines": {
Expand Down
10 changes: 10 additions & 0 deletions scripts/build.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -131,13 +131,23 @@ export function compareLocales(base, other, path = '') {
return problems;
}

// The Bot API version lives only in data.js; locale strings reference it as {botApiVersion}.
function fillVersion(node, version) {
if (typeof node === 'string') return node.replaceAll('{botApiVersion}', version);
if (Array.isArray(node)) return node.map((x) => fillVersion(x, version));
if (node && typeof node === 'object') return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, fillVersion(v, version)]));
return node;
}

export async function loadLocales() {
const locales = {};
for (const lang of LANGS) {
locales[lang.code] = JSON.parse(await readFile(join(SRC, 'i18n', `${lang.code}.json`), 'utf8'));
}
const problems = LANGS.slice(1).flatMap((lang) => compareLocales(locales.en, locales[lang.code], lang.code));
if (problems.length) throw new Error(`Locale mismatch:\n ${problems.join('\n ')}`);
const { BOT_API_VERSION } = await import('../src/assets/js/data.js');
for (const code of Object.keys(locales)) locales[code] = fillVersion(locales[code], BOT_API_VERSION);
return locales;
}

Expand Down
112 changes: 112 additions & 0 deletions scripts/check-bot-api.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
// Compares the project's Bot API reference data (src/assets/js/data.js) with the latest
// machine-readable Bot API spec and reports what is missing or outdated.
// Usage: node scripts/check-bot-api.mjs [--spec path/to/api.json] [--json]
// Exit code: 0 = up to date, 1 = drift found, 2 = error.
import { readFile, readdir } from 'node:fs/promises';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import * as data from '../src/assets/js/data.js';

export const SPEC_URL = 'https://raw.githubusercontent.com/PaulSonOfLars/telegram-bot-api-spec/main/api.json';
const JS_DIR = fileURLToPath(new URL('../src/assets/js/', import.meta.url));

// Methods the tool deliberately does not expose (dangerous or unrelated to bot settings).
const IGNORED_METHODS = new Set(['getMyStarBalance', 'logOut', 'close']);
const BOT_SETTINGS_METHOD = /^(set|get|delete|remove)(My[A-Z]|Webhook|WebhookInfo|ChatMenuButton)/;

const diff = (spec, ours) => ({
added: spec.filter((x) => !ours.includes(x)),
removed: ours.filter((x) => !spec.includes(x)),
});

async function usedMethods() {
const files = [];
const walk = async (dir) => {
for (const entry of await readdir(dir, { withFileTypes: true })) {
const full = join(dir, entry.name);
if (entry.isDirectory()) await walk(full);
else if (entry.name.endsWith('.js')) files.push(full);
}
};
await walk(JS_DIR);
const methods = new Set();
for (const file of files) {
// Methods are passed either directly (api.call('getMe')) or via request objects ({ method: 'setMyName' }).
for (const m of (await readFile(file, 'utf8')).matchAll(/(?:\.call\(|method: )'([a-z]\w+)'/g)) methods.add(m[1]);
}
return [...methods];
}

export async function checkBotApi(spec) {
const fields = (type) => spec.types[type].fields.map((f) => f.name);
const version = spec.version.replace(/^Bot API\s*/, '');
const used = await usedMethods();

const report = {
specVersion: version,
specReleaseDate: spec.release_date,
ourVersion: data.BOT_API_VERSION,
changelog: spec.changelog,
updateTypes: diff(fields('Update').filter((f) => f !== 'update_id'), data.UPDATE_TYPES),
adminRights: diff(fields('ChatAdministratorRights'), data.ADMIN_RIGHTS.map((r) => r.key)),
meFlags: diff(
spec.types.User.fields.filter((f) => f.description.includes('Returned only in getMe')).map((f) => f.name),
data.ME_FLAGS,
),
commandScopes: diff(
spec.types.BotCommandScope.subtypes.map((t) => spec.types[t].fields.find((f) => f.name === 'type').description.match(/must be (\w+)/)[1]),
data.COMMAND_SCOPES.map((s) => s.type),
),
setWebhookParams: diff(spec.methods.setWebhook.fields.map((f) => f.name),
['url', 'certificate', 'ip_address', 'max_connections', 'allowed_updates', 'drop_pending_updates', 'secret_token']),
botSettingsMethods: {
added: Object.keys(spec.methods).filter((m) => BOT_SETTINGS_METHOD.test(m) && !used.includes(m) && !IGNORED_METHODS.has(m)),
removed: used.filter((m) => !spec.methods[m]),
},
};
const sections = Object.values(report).filter((v) => v && typeof v === 'object');
report.upToDate = report.specVersion === report.ourVersion
&& sections.every((s) => s.added.length === 0 && s.removed.length === 0);
return report;
}

export function toMarkdown(r) {
const lines = [
`Spec: **Bot API ${r.specVersion}** (${r.specReleaseDate}) · project: **${r.ourVersion}**`,
`Changelog: ${r.changelog}`,
'',
];
const labels = {
updateTypes: 'Update types (allowed_updates)',
adminRights: 'ChatAdministratorRights',
meFlags: 'getMe flags',
commandScopes: 'BotCommandScope types',
setWebhookParams: 'setWebhook parameters',
botSettingsMethods: 'Bot settings methods not used by the tool',
};
for (const [key, label] of Object.entries(labels)) {
const { added, removed } = r[key];
if (!added.length && !removed.length) continue;
lines.push(`### ${label}`);
if (added.length) lines.push(`- New: ${added.map((x) => `\`${x}\``).join(', ')}`);
if (removed.length) lines.push(`- Removed from spec: ${removed.map((x) => `\`${x}\``).join(', ')}`);
lines.push('');
}
if (r.upToDate) lines.push('✅ Up to date.');
return lines.join('\n');
}

if (process.argv[1] === fileURLToPath(import.meta.url)) {
const specIndex = process.argv.indexOf('--spec');
try {
const spec = specIndex > -1
? JSON.parse(await readFile(process.argv[specIndex + 1], 'utf8'))
: await (await fetch(SPEC_URL)).json();
const report = await checkBotApi(spec);
console.log(process.argv.includes('--json') ? JSON.stringify(report, null, 2) : toMarkdown(report));
process.exitCode = report.upToDate ? 0 : 1;
} catch (error) {
console.error(`check-bot-api failed: ${error.message}`);
process.exitCode = 2;
}
}
3 changes: 2 additions & 1 deletion scripts/images.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
import { readFile, writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import { loadPlaywright } from './playwright.mjs';
import { BOT_API_VERSION } from '../src/assets/js/data.js';

const root = (p) => fileURLToPath(new URL(`../${p}`, import.meta.url));
const svg = await readFile(root('src/assets/img/favicon.svg'), 'utf8');
Expand All @@ -29,7 +30,7 @@ const card = (width, height) => `<!doctype html><html><head><style>
</style></head><body>
<div class="brand"><img src="${svgUri}" alt=""><h1>Telegram Bot<br>Manager</h1></div>
<p>Set, check &amp; delete webhooks, edit commands, profile, menu button and admin rights — online, in your browser.</p>
<div class="chips"><span class="chip">setWebhook</span><span class="chip">getWebhookInfo</span><span class="chip">deleteWebhook</span><span class="chip">setMyCommands</span><span class="chip">Bot API 10.3</span></div>
<div class="chips"><span class="chip">setWebhook</span><span class="chip">getWebhookInfo</span><span class="chip">deleteWebhook</span><span class="chip">setMyCommands</span><span class="chip">Bot API ${BOT_API_VERSION}</span></div>
<span class="url">github.com/f1devbin/telegram-bot-manager</span>
</body></html>`;

Expand Down
6 changes: 3 additions & 3 deletions src/i18n/en.json
Original file line number Diff line number Diff line change
Expand Up @@ -153,11 +153,11 @@
}
},
"home": {
"eyebrow": "Free · Open source · Bot API 10.3",
"eyebrow": "Free · Open source · Bot API {botApiVersion}",
"h1": "Telegram Bot Manager: webhooks, commands and profile online",
"lead": "Set, check and delete your bot's webhook, edit commands, name, description, avatar, menu button and default admin rights — without writing code or running scripts.",
"point1": "Works right in the browser — no install, no backend",
"point2": "Supports the latest Telegram Bot API 10.3",
"point2": "Supports the latest Telegram Bot API {botApiVersion}",
"point3": "Shows webhook errors with hints on how to fix them",
"featuresTitle": "Everything BotFather can't do in one place",
"features": [
Expand Down Expand Up @@ -189,7 +189,7 @@
{
"icon": "🛡",
"title": "Admin rights",
"text": "Default administrator rights for groups and channels, including the newest rights from Bot API 10.3."
"text": "Default administrator rights for groups and channels, including the newest rights from Bot API {botApiVersion}."
},
{
"icon": "🧰",
Expand Down
Loading
Loading