Skip to content

README.md

Latest commit

 

History

History
141 lines (125 loc) · 6.26 KB

README.md

File metadata and controls

141 lines (125 loc) · 6.26 KB

Web2Comic Telegram Bot

Bot Docs Runtime Deploy Storage Tests License

Telegram bot backend for Web2Comics. The bot accepts text, web links, PDF links/files, image links/files, and voice/audio, then generates comic panels and sends ordered panel images back to chat.

Bot overview doc: ../docs/telegram-bot.md Extension overview doc: ../docs/extension.md Extension README: ../README.md Shared engine overview: ../docs/engine.md Engine manual source: ../engine/manual.md Bot release notes: docs/release-notes.md GitHub Pages bot docs: https://apartsinprojects.github.io/Web2Comics/HTML/telegram-bot.html

Documentation Scope

  • Bot documentation lists public user-facing commands and flows only.
  • Internal/admin-only commands are intentionally excluded from published docs.
  • Extension popup, sidepanel, options-page, and browser workflows are documented separately.

Public Command Catalog (No Admin Commands)

  • Onboarding/info:
    • /start, /welcome, /help, /about, /version, /user, /config, /explain, /debug <on|off>
  • Story generation:
    • Send plain text, web link, PDF, image, or voice/audio message
    • /invent <story>
    • /random
  • Replay/history:
    • /peek, /peek <n>, /peek<n>
  • Providers and models:
    • /vendors [role], /vendor <role> <name>, /vendor <name>
    • /models [text|image|url|image_extract|pdf|voice] [model]
    • /test
  • Generation controls:
    • /panels <count>, /objective [name], /objectives
    • /language <code>, /mode <default|media_group|single>
    • /consistency <on|off>, /detail <low|medium|high>
    • /crazyness <0..2>, /concurrency <1..5>, /retries <0..3>
  • Objective shortcuts:
    • /summary, /fun, /learn, /news, /timeline, /facts, /compare, /5yold, /eli5, /study, /meeting, /howto, /debate
  • Style controls:
    • /style <preset-or-your-style>
    • /new_style <name> <text>
    • Style shortcuts: /classic, /noir, /manga, /superhero, /watercolor, /newspaper, /cinematic, /anime, /cyberpunk, /pixel-art, /retro-pop, /minimalist, /storybook, /ink-wash, /line-art, /clay-3d
  • Prompts/options:
    • /prompts
    • /set_prompt story <text>
    • /set_prompt panel <text>
    • /set_prompt objective <name> <text>
    • /list_options, /options <path>
  • Keys/reset:
    • /keys, /setkey <KEY> <VALUE>, /unsetkey <KEY>, /reset_config, /restart
  • Behavior:
    • Unknown /... command is rejected as unrecognized (not treated as story text).

What It Does

  • Receives Telegram webhook updates
  • Detects text, web link, PDF, image, and voice/audio inputs
  • Builds storyboard and panel images with configured providers
  • Streams panels to users as they are generated
  • Uses per-user runtime settings and credentials
  • Persists runtime state in Cloudflare R2
  • Persists artifacts/logs/images in Cloudflare R2

Shared Engine Relationship

  • The bot reuses shared prompt-building and composition logic from ../engine/
  • Engine overview: ../docs/engine.md
  • This keeps storyboard behavior closer to the extension while allowing the bot to keep its own transport, storage, and deployment model

Runtime Highlights

  • Fast webhook ACK + per-chat processing queue
  • Caption prefix format X(Y) for each panel
  • Watermark is configurable (default: on)
  • Panel image prompts include Background + Image description fields (no Story title line)
  • Image no-text rule is enforced in English, Hebrew, and Russian
  • Optional style consistency flow (/consistency on): generate summary reference image first, then use it as style reference for panel generation on supported image models
  • Outbound Telegram messages/photos are sent with forwarding allowed (protect_content=false)
  • /objective without args lists all objectives
  • For URL inputs, bot prints the exact parsed URL before extraction

Documentation

Local Development

npm install
npm run telegram:start

Testing

npm run test:telegram:local
npm run test:telegram

Optional:

npm run test:telegram:gemini-real
npm run test:telegram:r2-real
npm run test:telegram:full-stack
npx vitest run -c telegram/vitest.config.js telegram/tests/webhook-url-real.e2e.test.js

Optional real URL e2e is opt-in and requires:

  • RUN_WEBHOOK_URL_REAL=true
  • RUN_RENDER_REAL_GEMINI=1
  • GEMINI_API_KEY set

Deployment

Recommended automatic path:

npm run bot:deploy:auto -- --target render --env staging --branch stage1 --env-only

Release package:

  • Current bot release: v1.0.4
  • Deploy artifact: Web2Comics-TelegramBot-v1.0.4-deploy.zip
  • Companion extension package docs: ../docs/extension.md

Includes:

  • secret validation
  • predeploy checks + local tests
  • Render deploy automation
  • post-deploy sanity E2E check (health + webhook + Telegram + R2 evidence)