Add Telegram invoice scanning

[andrewzolotukhin]

Original request

• "we have a possibility to scan invoices, let's add this possibility to telegram bot client"
• Follow-up: support specifying an existing vendor on Telegram-created transactions, without adding a new vendor.
• Follow-up: move the work out of main and apply it through the PR workflow.

What changed

• Added Telegram bot support for scanning private-chat receipt/invoice images:
  • accepts Telegram photos plus PNG/JPEG/WebP image documents;
  • rejects unsupported documents and images larger than the shared scan limit;
  • downloads Telegram file bytes and starts the existing transactionScans job flow;
  • shows scan progress and opens an inline review flow for returned drafts.
• Added full Telegram chat review/edit for scanned drafts:
  • confirm/discard each draft;
  • edit amount, currency, category, vendor, date/time, and note;
  • records confirmed scan decisions with corrected values and stores the original image attachment once per scan.
• Added existing-vendor selection to manual /add and scan review:
  • lists/searches existing vendors only;
  • supports No vendor;
  • uses vendor suggested category as a category prompt preference without auto-saving a category choice.
• Extended Telegram flow helpers and tracing classification for vendor and scan callbacks without recording raw IDs/search text.
• Added @xpenser/timezone to the Telegram bot workspace dependency for user-timezone date edits.
• Added mocked Telegram/client tests for manual vendor selection, scan confirmation, and unsupported document rejection, plus helper/tracing coverage.

Reasoning

The API and web app already expose invoice/receipt scanning through the shared transactionScans contract, so the Telegram bot reuses that existing typed client path instead of adding new API endpoints or persistence. The scanner still creates drafts only; Telegram now mirrors the web review requirement by letting users inspect and correct each draft before a transaction is created. Vendor support is limited to selecting existing vendors because the requested scope explicitly excluded creating new vendors from Telegram.

Screenshots / preview evidence

Screenshots are not applicable for this change because it is a Telegram bot chat workflow, not a browser-rendered UI. The deterministic preview URL is https://xpenser-pr-027.cleverbrush.com, and the PR environment deployed successfully. Browser Playwright e2e passed in CI; direct Telegram preview QA was skipped because this environment cannot safely drive an external Telegram chat against the PR bot service.

Validation

Local validation from /root/projects/xpenser/feat/telegram-invoice-scanning:

• npm run lint ✅
• npm run typecheck ✅
• npm test ✅
• npm run typecheck -w @xpenser/telegram-bot ✅
• ./node_modules/.bin/vitest --run apps/telegram-bot/src ✅
• ./node_modules/.bin/biome check apps/telegram-bot/src apps/telegram-bot/package.json package-lock.json ✅
• npm run build -w @xpenser/telegram-bot ✅

GitHub checks:

• Lint and test ✅
• Deploy PR environment ✅
• Playwright e2e ✅

SigNoz:

• Queried PR 27 web/api logs for severity_text IN ('ERROR', 'FATAL') over the deployment window: no rows returned. ✅
• Queried logs for service.name = 'xpenser-telegram-bot-pr-27': no rows/service telemetry returned in the checked window. This means there were no visible bot errors, but the PR telegram-bot service did not emit log telemetry for direct verification. SigNoz MCP cannot generate a reliable frontend link.