This repository contains two deployable parts:
| Part | Path | Platform | Purpose |
|---|---|---|---|
| tgbot | packages/bot-worker/ |
Cloudflare Workers | Telegram bot, APK link preview, WebUI upload guidance, report rendering, webhook/admin APIs. |
| Web UI | packages/apk-webui/ |
Cloudflare Pages | Standalone browser APK analyzer powered by the same parser and LibChecker rules. |
| Local MCP | packages/apk-mcp/ |
Node >=24 / stdio | Offline local APK analysis for desktop MCP clients. |
| Shared analyzer | packages/shared/ |
Worker and Pages | APK parser, signature parser, SDK marker runtime, and generated local bundles. |
The Worker bot accepts APK links and guides local APK, APKS, APKM, and XAPK uploads to the Web UI. Link previews return a short Telegram summary and a full LibChecker-style report page.
Key capabilities:
- Telegram webhook handling for private chats, groups, and channels.
- Range-based APK link preview parsing for manifest, resources, permissions, components, and native libraries.
- LibChecker-Rules-Bundle matching for SDK names, icons, and component markers.
/uploadguidance to the browser Web UI for local APK, APKS, APKM, and XAPK files.- Protected admin APIs for webhook and command-menu management.
- Structured Worker logs and Analytics Engine events.
The Pages app is a separate browser-first APK analyzer. It runs the analysis locally in the browser through a Web Worker, so APK files do not need to be sent to the Telegram bot flow.
Key capabilities:
- Local APK analysis in the browser.
- Shared parser and generated local LibChecker rule bundles.
- Static Cloudflare Pages deployment.
- Independent development and deployment commands.
- Send an APK download link for range-based preview parsing.
- Reply to an APK link with
/apkinfo. - Use
/uploadfor local APK, APKS, APKM, and XAPK files. - Open the Web UI when you want browser-only local analysis.
Group behavior depends on Telegram Privacy Mode. For the most reliable group flow, use /apkinfo@your_bot_name or disable Privacy Mode in BotFather.
Install workspace dependencies from the repository root:
npm installRun the Worker bot locally:
npm run devRun the Web UI locally:
npm run pages:devConfigure Worker secrets:
npx wrangler secret put BOT_TOKEN --config packages/bot-worker/wrangler.jsonc --env production
npx wrangler secret put BOT_TOKEN --config packages/bot-worker/wrangler.jsonc --env preview
npx wrangler secret put ADMIN_TOKEN --config packages/bot-worker/wrangler.jsonc --env production
npx wrangler secret put ADMIN_TOKEN --config packages/bot-worker/wrangler.jsonc --env preview
npx wrangler secret put TELEGRAM_WEBHOOK_SECRET --config packages/bot-worker/wrangler.jsonc --env production
npx wrangler secret put TELEGRAM_WEBHOOK_SECRET --config packages/bot-worker/wrangler.jsonc --env previewUse a dedicated test bot token for the preview environment. In GitHub Actions,
set TEST_BOT_TOKEN; the workflow syncs it into the preview Worker as
BOT_TOKEN so production BOT_TOKEN stays isolated.
TELEGRAM_WEBHOOK_SECRET is optional, but recommended for production.
Report sharing uses the REPORT_DATA_BUCKET R2 binding declared in
packages/bot-worker/wrangler.jsonc. Deploys use separate preview and
production buckets, and the deploy script creates the target bucket when it is
missing during a real deploy. The deploy CLOUDFLARE_API_TOKEN must include
R2 Admin Read & Write permission for bucket creation.
SDK custom emoji ids are runtime data. The sync and deploy scripts resolve a
Workers KV namespace named tgbot-sdk-emojis; real sync/deploy runs create it
automatically when it does not exist. Set TELEGRAM_SDK_EMOJI_KV_NAMESPACE_NAME
only if you want a different namespace name. When the KV binding or key is
absent, the Worker still lists SDK markers but omits custom emoji icons.
Run the deploy preflight locally before shipping:
npm run deploy:preflight -- --target=preview
npm run deploy:preflight -- --target=productionDeploy preview or production:
npm run deploy:preview
npm run deploy:productionDeploy production and register the Telegram webhook:
npm run deploy:setupThe Worker has explicit Wrangler environments in packages/bot-worker/wrangler.jsonc:
preview: deploystgbot-previewonworkers.dev, binds the custom domain from repository variablePREVIEW_WORKER_URL, usesLibchecker_TG_Bot_Preview, usesTEST_BOT_TOKENfor preview bot testing, points report buttons atPREVIEW_WEBUI_SITE_URLor the fixed Cloudflare Pages preview alias, registers the preview Web UI Pages custom domain when configured, and injects the preview Worker origin so Web UI report links can resolve?r=....production: deploystgbot, binds the custom domain from repository variableWORKER_URL, usesLibchecker_TG_Bot, injects that URL asPUBLIC_WEBHOOK_URL, points report buttons atWEBUI_SITE_URL, registers the production Web UI Pages custom domain when configured, and injects the production Worker origin so Web UI report links can resolve?r=....
Build and deploy the Pages app directly:
npm run pages:build
npm run pages:deploy:preview
npm run pages:deploy:productionThe root Cloudflare deploy commands are preferred because they always run check, WebUI build, WebUI performance budgets, and Worker dry-run size budgets before deployment. Pages preview deploys use the current branch name, while production deploys use the main branch.
The Web UI build publishes machine-readable discovery resources for its real public URL-analysis API:
/.well-known/api-catalog/openapi.jsonand/api-docs.md/.well-known/agent-skills/index.json/auth.md, which documents that the public API needs no registration or credentials/health
DNS-AID is an external DNS-zone operation and is not changed by the Pages deploy. After resolving WEBUI_SITE_URL to its hostname, publish an organization-index record like the following, using a Private Use numeric SvcParamKey for the unregistered well-known path parameter, and enable DNSSEC for the public zone:
_index._agents.<webui-host>. 3600 IN SVCB 1 <webui-host>. mandatory=alpn,port alpn="h2" port=443 key65400="/.well-known/agent-skills/index.json"
Do not advertise mcp in DNS until the /mcp endpoint is deployed and verified. Do not advertise a2a or OAuth services that do not exist.