aiogram-stars 0.1.0__tar.gz

aiogram_stars-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+*.db
+*.sqlite3
+.env

aiogram_stars-0.1.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-17
+
+### Added
+
+- `StarsPayments`: one object that registers the pre-checkout and successful-payment
+  handlers for `XTR` on an aiogram `Router` or `Dispatcher`, ahead of the routers included
+  there, and starts and stops the refund outbox with the dispatcher, for polling and webhooks.
+- Invoice helpers `send_invoice` and `create_invoice_link` (with `subscription_period`), and
+  `make_payload` for other invoice kinds. Payloads carry the order id and an HMAC-SHA256 tag
+  bound to the amount; `PayloadSigner` signs and verifies them, with `previous_secrets` for key
+  rotation.
+- Pre-checkout: payloads not signed with the secret, or paid with another amount, are declined
+  before the `check` callback runs; `check` approves by returning nothing and declines with
+  `RejectPayment(reason)`, and any other return value or exception declines with
+  `checkout_error`; a check slower than `checkout_timeout` (8 s by default) is cancelled and the
+  query is declined before Telegram's 10-second deadline, also when the check is slow to stop.
+- Successful payments are recorded once per `telegram_payment_charge_id`; `on_paid` runs once
+  per charge, also for redelivered updates and for several bot processes on one database.
+  `RejectPayment` from `on_paid` marks the payment rejected and queues a refund in the same
+  storage transaction; a payment whose payload does not verify is rejected and refunded without
+  calling `on_paid`. Shutdown waits up to `payment_lease` for the `on_paid` calls that are
+  running, since Telegram does not send their updates again. A payment left behind by a process
+  that died is handled again by a redelivered update once its lease (`payment_lease`) runs out.
+- Refund outbox: refunds (compensating, and manual through `StarsPayments.refund`) are stored
+  first and sent by a background task with exponential backoff (`RefundPolicy`), at most one
+  refund per charge, claimed with a lease so two workers never send it at the same time.
+  `CHARGE_ALREADY_REFUNDED` counts as done; flood control (`retry_after`) pauses every refund,
+  not only the one that hit it; `on_refunded` and `on_refund_failed` callbacks;
+  `send_due_refunds` makes one attempt at every due refund from the calling task.
+- Callbacks get the handler data they name, as aiogram handlers do; `on_paid` also gets the
+  `message`, and the outbox callbacks get `bot` and the dispatcher's data.
+- `get_payment` and `get_refund` read the stored records; `Payment`, `Refund`, `PaymentStatus`
+  and `RefundStatus` describe them, and the statuses read as their string value.
+- Subscriptions: `Payment.is_recurring`, `is_first_recurring` and `subscription_expires_at`,
+  and `cancel_subscription` (`editUserStarSubscription`).
+- Storage: the `Storage` protocol, `MemoryStorage`, and `aiogram_stars.sqlalchemy.SqlAlchemyStorage`
+  for SQLite and PostgreSQL (SQLAlchemy 2 async). The extras `sqlite` and `postgres` install
+  SQLAlchemy with the driver; `sqlalchemy` installs SQLAlchemy alone.
+- Settings that cannot work (`checkout_timeout` outside (0, 10), a blank `checkout_error`, a
+  `RefundPolicy` lease no longer than its request timeout, and others) raise `ValueError` when
+  the object is created.
+- Python 3.10 to 3.13 and aiogram 3.15 or later; the package ships `py.typed` and passes
+  `mypy --strict`.
+- `examples/shop_bot.py`, a runnable bot with `/buy`, `/refund <charge_id>` and `/paysupport`.
+- README in English and Russian; its quick start runs in the test suite.
+
+[0.1.0]: https://github.com/sinnercode228/aiogram-stars/releases/tag/v0.1.0

aiogram_stars-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sinnercode228
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.