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
2 changes: 1 addition & 1 deletion .github/workflows/bot-api-watch.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ jobs:
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\`."
echo "To update: edit \`src/assets/js/data.js\` (lists and \`BOT_API_VERSION\`), add labels to all \`src/i18n/*.json\`, add new method parameters to \`METHOD_PARAMS\` in \`scripts/check-bot-api.mjs\`, 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
Expand Down
10 changes: 7 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,7 @@ jobs:

e2e:
needs: test
# Pinned: Playwright 1.56 has no browser builds for ubuntu-latest (26.04) yet.
runs-on: ubuntu-24.04
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
Expand All @@ -42,9 +41,14 @@ jobs:
with:
name: dist
path: dist
- name: Cache Playwright browsers
uses: actions/cache@v4
with:
path: ~/.cache/ms-playwright
key: playwright-${{ runner.os }}-${{ runner.arch }}-1.65.1
- name: Install Playwright
run: |
npm install --no-save playwright@1.56.1
npm install --no-save playwright@1.65.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
Expand Down
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,16 @@
# Changelog

## 3.3.0 — 2026-11-21

### Added
- Bot API drift check now compares the parameters of every method the tool calls, plus `WebhookInfo`, `BotCommand` and `MenuButton` fields; it also warns when the spec source is stale.
- The English root page suggests a localized version based on the browser language (a dismissible banner, not a redirect).
- Plural forms for pending-update and saved-command messages via `Intl.PluralRules`.

### Changed
- Accessibility: focus moves to the active tab after connecting; validation errors are linked to their field with `aria-describedby`; the theme toggle exposes `aria-pressed`; radio groups have accessible names; the toast live region is no longer nested.
- CI: Playwright 1.65.1 with a browser cache; the Lighthouse SEO threshold is now an error (≥ 95), while performance stays a warning (≥ 85) because GitHub runners vary.

## 3.2.0 — 2026-11-11

### Changed
Expand Down
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ Static site (GitHub Pages) that calls the Telegram Bot API from the browser. No

## 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`.
1. `node scripts/check-bot-api.mjs` — lists new update types, admin rights, getMe flags, command scopes, BotCommand/MenuButton/WebhookInfo fields, parameters of every method the tool calls, and bot-settings methods (spec: PaulSonOfLars/telegram-bot-api-spec; core.telegram.org may be unreachable). It also warns when the spec release date is stale, so an outdated spec source is not mistaken for “no changes”.
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`. If a new parameter appears on a method the tool already calls, add it to `METHOD_PARAMS` in `scripts/check-bot-api.mjs` and expose it in the UI when it matters.
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.
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,12 +88,12 @@ npm run build && node scripts/screenshots.mjs # e2e smoke test (Playwright + C

**Adding a language:** copy `src/i18n/en.json` to `<code>.json`, translate it, and add the language to `LANGS` in `scripts/build.mjs`. The tests fail if any key is missing.

**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.
**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. If a new parameter appears on a method the tool calls, add it to `METHOD_PARAMS` in `scripts/check-bot-api.mjs` and expose it in the UI when it matters.

## 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.
- **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 ≥ 95, best practices ≥ 90 and SEO ≥ 95 are errors; performance ≥ 85 is a warning; 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` — update types, admin rights, `getMe` flags, scopes, `BotCommand`/`MenuButton`/`WebhookInfo` fields and the parameters of every method the tool calls — and opens an issue labelled `bot-api-update` when something is missing. A stale spec source is reported as a warning.
- **Agent instructions** for updating the project are in [`CLAUDE.md`](CLAUDE.md).

## FAQ
Expand Down
2 changes: 1 addition & 1 deletion lighthouserc.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
"assertions": {
"categories:accessibility": ["error", { "minScore": 0.95 }],
"categories:best-practices": ["error", { "minScore": 0.9 }],
"categories:seo": ["warn", { "minScore": 0.9 }],
"categories:seo": ["error", { "minScore": 0.95 }],
"categories:performance": ["warn", { "minScore": 0.85 }]
}
},
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "telegram-bot-manager",
"version": "3.2.0",
"version": "3.3.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",
Expand Down
100 changes: 90 additions & 10 deletions scripts/check-bot-api.mjs
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// 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.
// Compares the project's Bot API reference data 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';
Expand All @@ -14,12 +14,52 @@ const JS_DIR = fileURLToPath(new URL('../src/assets/js/', import.meta.url));
const IGNORED_METHODS = new Set(['getMyStarBalance', 'logOut', 'close']);
const BOT_SETTINGS_METHOD = /^(set|get|delete|remove)(My[A-Z]|Webhook|WebhookInfo|ChatMenuButton)/;

// Bot API parameters the project knows about for every method it calls.
// A parameter added by Telegram is reported even when the UI does not need it yet;
// when the UI starts using it, add it here. Keep this map in sync with src/assets/js.
export const METHOD_PARAMS = {
getMe: [],
getWebhookInfo: [],
setWebhook: ['url', 'certificate', 'ip_address', 'max_connections', 'allowed_updates', 'drop_pending_updates', 'secret_token'],
deleteWebhook: ['drop_pending_updates'],
getFile: ['file_id'],
getUserProfilePhotos: ['user_id', 'offset', 'limit'],
getMyStarBalance: [],
removeMyProfilePhoto: [],
setMyProfilePhoto: ['photo'],
getMyName: ['language_code'],
setMyName: ['name', 'language_code'],
getMyShortDescription: ['language_code'],
setMyShortDescription: ['short_description', 'language_code'],
getMyDescription: ['language_code'],
setMyDescription: ['description', 'language_code'],
getMyCommands: ['scope', 'language_code'],
setMyCommands: ['commands', 'scope', 'language_code'],
deleteMyCommands: ['scope', 'language_code'],
getChatMenuButton: ['chat_id'],
setChatMenuButton: ['chat_id', 'menu_button'],
getMyDefaultAdministratorRights: ['for_channels'],
setMyDefaultAdministratorRights: ['rights', 'for_channels'],
};

// Object fields rendered (or deliberately ignored) by the UI.
export const WEBHOOK_INFO_FIELDS = [
'url', 'has_custom_certificate', 'pending_update_count', 'ip_address', 'last_error_date',
'last_error_message', 'last_synchronization_error_date', 'max_connections', 'allowed_updates',
];
export const BOT_COMMAND_FIELDS = ['command', 'description', 'is_ephemeral'];
export const MENU_BUTTON_TYPES = ['MenuButtonCommands', 'MenuButtonWebApp', 'MenuButtonDefault'];

// A stale spec source is a silent-drift risk: it can look "up to date" while Telegram has
// already shipped a newer API. The report warns when the spec release date is older than this.
export const MAX_SPEC_AGE_DAYS = 90;

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

async function usedMethods() {
export async function usedMethods() {
const files = [];
const walk = async (dir) => {
for (const entry of await readdir(dir, { withFileTypes: true })) {
Expand All @@ -37,14 +77,38 @@ async function usedMethods() {
return [...methods];
}

export async function checkBotApi(spec) {
const fields = (type) => spec.types[type].fields.map((f) => f.name);
function parseDate(value) {
if (!value) return null;
const date = new Date(value);
return Number.isNaN(date.getTime()) ? null : date;
}

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

// Parameters of every method the tool calls: a new optional parameter matters because
// the UI may need a control for it (as happened with is_ephemeral and secret_token).
const methodParams = { added: [], removed: [] };
for (const [method, expected] of Object.entries(METHOD_PARAMS)) {
if (!spec.methods[method]) continue; // Method removal is reported by botSettingsMethods.removed.
const actual = (spec.methods[method].fields ?? []).map((f) => f.name);
for (const name of actual) if (!expected.includes(name)) methodParams.added.push(`${method}.${name}`);
for (const name of expected) if (!actual.includes(name)) methodParams.removed.push(`${method}.${name}`);
}

// A new method in the source must also get a METHOD_PARAMS entry, otherwise its
// parameters are silently unchecked.
const uncheckedMethods = used.filter((method) => spec.methods[method] && !(method in METHOD_PARAMS));
const releaseDate = parseDate(spec.release_date);
const specAgeDays = releaseDate ? Math.floor((now.getTime() - releaseDate.getTime()) / 86_400_000) : null;

const report = {
specVersion: version,
specReleaseDate: spec.release_date,
specAgeDays,
staleSpec: specAgeDays !== null && specAgeDays > maxSpecAgeDays,
ourVersion: data.BOT_API_VERSION,
changelog: spec.changelog,
updateTypes: diff(fields('Update').filter((f) => f !== 'update_id'), data.UPDATE_TYPES),
Expand All @@ -57,14 +121,21 @@ export async function checkBotApi(spec) {
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']),
botCommandFields: diff(fields('BotCommand'), BOT_COMMAND_FIELDS),
menuButtonTypes: diff(spec.types.MenuButton?.subtypes ?? [], MENU_BUTTON_TYPES),
webhookInfoFields: diff(fields('WebhookInfo'), WEBHOOK_INFO_FIELDS),
methodParams,
uncheckedMethods: { added: uncheckedMethods, removed: [] },
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');
const sections = [
report.updateTypes, report.adminRights, report.meFlags, report.commandScopes,
report.botCommandFields, report.menuButtonTypes, report.webhookInfoFields,
report.methodParams, report.uncheckedMethods, report.botSettingsMethods,
];
report.upToDate = report.specVersion === report.ourVersion
&& sections.every((s) => s.added.length === 0 && s.removed.length === 0);
return report;
Expand All @@ -81,7 +152,11 @@ export function toMarkdown(r) {
adminRights: 'ChatAdministratorRights',
meFlags: 'getMe flags',
commandScopes: 'BotCommandScope types',
setWebhookParams: 'setWebhook parameters',
botCommandFields: 'BotCommand fields',
menuButtonTypes: 'MenuButton types',
webhookInfoFields: 'WebhookInfo fields',
methodParams: 'Method parameters',
uncheckedMethods: 'Used methods without a parameter check',
botSettingsMethods: 'Bot settings methods not used by the tool',
};
for (const [key, label] of Object.entries(labels)) {
Expand All @@ -92,6 +167,10 @@ export function toMarkdown(r) {
if (removed.length) lines.push(`- Removed from spec: ${removed.map((x) => `\`${x}\``).join(', ')}`);
lines.push('');
}
if (r.staleSpec) {
lines.push(`⚠️ The spec was released ${r.specAgeDays} days ago; the source may be stale.`);
lines.push('');
}
if (r.upToDate) lines.push('✅ Up to date.');
return lines.join('\n');
}
Expand All @@ -102,7 +181,8 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
const spec = specIndex > -1
? JSON.parse(await readFile(process.argv[specIndex + 1], 'utf8'))
: await (await fetch(SPEC_URL)).json();
const report = await checkBotApi(spec);
const maxSpecAgeDays = Number(process.env.SPEC_MAX_AGE_DAYS) || MAX_SPEC_AGE_DAYS;
const report = await checkBotApi(spec, { maxSpecAgeDays });
console.log(process.argv.includes('--json') ? JSON.stringify(report, null, 2) : toMarkdown(report));
process.exitCode = report.upToDate ? 0 : 1;
} catch (error) {
Expand Down
31 changes: 29 additions & 2 deletions scripts/screenshots.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -113,9 +113,11 @@ const { chromium } = await loadPlaywright();
const browser = await chromium.launch();
const errors = [];

async function openApp({ theme = 'dark', lang = '', width = 1280, height = 900 } = {}) {
async function openApp({ theme = 'dark', lang = '', width = 1280, height = 900, locale } = {}) {
const mock = createMock();
const context = await browser.newContext({ viewport: { width, height }, colorScheme: theme, deviceScaleFactor: 1 });
const context = await browser.newContext({
viewport: { width, height }, colorScheme: theme, deviceScaleFactor: 1, ...(locale ? { locale } : {}),
});
const page = await context.newPage();
page.on('pageerror', (e) => errors.push(`pageerror: ${e.message}`));
page.on('console', (m) => {
Expand Down Expand Up @@ -152,6 +154,8 @@ async function connect(page) {
await page.waitForSelector('#app:not([hidden])');
await page.waitForSelector('#webhook-status .stats');
await page.waitForSelector('#bot-avatar img');
await page.waitForFunction(() => document.activeElement?.id === 'tab-webhook');
assert(await page.evaluate(() => document.activeElement?.id) === 'tab-webhook', 'focus moves to the active tab');
}

try {
Expand All @@ -163,7 +167,25 @@ try {
await page.fill('#token', 'bad');
await page.click('#connect-form button[type="submit"]');
assert(await page.locator('.field-error').isVisible(), 'token validation');
const describedBy = await page.getAttribute('#token', 'aria-describedby');
assert(describedBy && await page.locator(`#${describedBy}`).isVisible(), 'token error is linked to the field');
await shot(page, 'landing.png');
const themePressed = await page.getAttribute('#theme-toggle', 'aria-pressed');
await page.click('#theme-toggle');
assert((await page.getAttribute('#theme-toggle', 'aria-pressed')) !== themePressed, 'theme toggle exposes its state');
await context.close();
}

// Browser-language suggestion (a banner, not a redirect)
{
const { page, context } = await openApp({ theme: 'light', locale: 'ru-RU' });
await page.waitForSelector('#lang-suggest:not([hidden])');
assert((await page.textContent('#lang-suggest-link')) === 'Русский', 'language suggestion');
assert((await page.getAttribute('#lang-suggest-link', 'href')) === 'ru/', 'language suggestion link');
await page.click('#lang-suggest-dismiss');
assert(await page.locator('#lang-suggest').isHidden(), 'language suggestion dismissed');
await page.reload();
assert(await page.locator('#lang-suggest').isHidden(), 'language suggestion stays dismissed');
await context.close();
}

Expand All @@ -172,6 +194,11 @@ try {
const { page, mock, context } = await openApp();
await connect(page);
assert((await page.textContent('#bot-name')) === 'Demo Helper Bot', 'bot name');
const unnamedGroups = await page.locator('[role="radiogroup"]').evaluateAll((groups) => groups.filter((group) => {
const labelledBy = group.getAttribute('aria-labelledby');
return !group.getAttribute('aria-label') && !(labelledBy && document.getElementById(labelledBy));
}).length);
assert(unnamedGroups === 0, 'radio groups have accessible names');
assert((await page.textContent('#webhook-status')).includes('502 Bad Gateway'), 'last error shown');
assert(await page.isChecked('input[name="wh-updates-mode"][value="custom"]'), 'custom updates mode');
assert(await page.isChecked('input[value="chat_member"]'), 'chat_member checked');
Expand Down
3 changes: 3 additions & 0 deletions src/assets/css/app.css
Original file line number Diff line number Diff line change
Expand Up @@ -387,6 +387,9 @@ input[type="checkbox"], input[type="radio"] { accent-color: var(--accent); width
@keyframes toast-in { from { transform: translateY(8px); opacity: 0; } }

/* ---------- Landing & guides ---------- */
.lang-suggest { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 12px; margin-top: 16px; }
.lang-suggest p { margin: 0; flex: 1 1 240px; }

.section { padding: 44px 16px; }
.section > h2 { font-size: 1.7rem; margin-bottom: 20px; }
.feature-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 14px; }
Expand Down
Loading
Loading