Initial release of go-telegram

A fully-generated, strongly-typed Go client for the Telegram Bot API.

* 176 methods + 301 types generated from Bot API v10.0
* 1408 auto-generated tests (8 scenarios per method)
* Typed unions throughout — no 'any' in the public surface
* Pluggable HTTP transport and JSON codec (default goccy/go-json)
* Built-in retry middleware honouring Telegram's retry_after
* Generic dispatcher with filters and conversation handlers
* Self-verifying codegen pipeline (regen → audit → emit → run tests)
* 14 example bots covering common patterns

examples/payments/README.md

@@ -0,0 +1,47 @@
+# payments
+
+Full Telegram Payments flow: invoice → pre-checkout confirmation → successful payment.
+
+## What it shows
+
+- `api.SendInvoice` to send a product invoice with `LabeledPrice` breakdown
+- `router.OnPreCheckoutQuery` + `api.AnswerPreCheckoutQuery` — must respond within 10 s
+- `router.OnMessageFilter` matching `Message.SuccessfulPayment` to confirm payment
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | Yes | Bot token from @BotFather |
+| `PAYMENT_PROVIDER_TOKEN` | No | Provider token from @BotFather. Leave empty for Telegram Stars (XTR). |
+| `CURRENCY` | No | ISO 4217 code (default: `USD`). Use `XTR` for Stars. |
+
+## Test payments
+
+Telegram provides a test payment provider to avoid real charges during development:
+
+1. In @BotFather, use `/mybots` → choose your bot → **Payments** → select "Stripe TEST".
+2. Use the test provider token — test payments are free and won't charge users.
+3. In the Telegram client, use a test card number such as `4242 4242 4242 4242`.
+
+**Never expose a live provider token in source code.** Use environment variables or secrets management.
+
+## Flow
+
+```
+User: /buy
+Bot:  [Invoice message — "Premium Widget $2.19"]
+User: [taps Pay]
+Telegram → Bot: pre_checkout_query (bot has 10 s to respond)
+Bot → Telegram: answerPreCheckoutQuery ok=true
+Telegram → Bot: Message.SuccessfulPayment
+Bot: "Payment received! Your widget is on its way."
+```
+
+## Running
+
+```bash
+export TELEGRAM_BOT_TOKEN=123456:ABC...
+export PAYMENT_PROVIDER_TOKEN=<stripe-test-token>
+go run ./examples/payments
+```