django-checkouts 1.0.1__tar.gz

django_checkouts-1.0.1/.github/workflows/release.yml

@@ -0,0 +1,73 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+jobs:
+  release:
+    name: Release Please
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - id: release
+        uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071  # v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  build:
+    name: Build distributions
+    needs: release
+    if: ${{ needs.release.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+        with:
+          ref: ${{ needs.release.outputs.tag_name }}
+          # setuptools_scm calcula a versão a partir da tag do git: sem
+          # histórico/tags a build cai no fallback_version "0.0.0".
+          fetch-depth: 0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.13"
+      - name: Install build tools
+        run: python -m pip install "build>=1.2,<2" "twine>=6,<7"
+      - name: Build distributions
+        run: python -m build
+      - name: Validate distributions
+        run: python -m twine check dist/*
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/django-checkouts
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # release/v1
+        with:
+          packages-dir: dist/

django_checkouts-1.0.1/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+django_checkouts/version.py
+docs/_build/

django_checkouts-1.0.1/.python-version

@@ -0,0 +1 @@
+3.12

django_checkouts-1.0.1/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"1.0.1"}

django_checkouts-1.0.1/.superpowers/sdd/task-1-report.md

@@ -0,0 +1,148 @@
+# Task 1 — vocabulário normalizado, DTOs e erros
+
+## Implementação
+
+- Substituído o vocabulário público de `Provider` por `Gateway`, preservando
+  `Provider = Gateway` durante a migração dos módulos legados.
+- Adicionados os enums normalizados de assinatura, fatura, evento, recurso,
+  alterações e retry, todos com rótulos traduzíveis via `pgettext_lazy`.
+- Criada a taxonomia pública de erros com `RetryAdvice`, a árvore de erros de
+  gateway e aliases compatíveis para `ProviderTemporaryError`,
+  `ProviderPermanentError` e `CheckoutNotFound`.
+- Criado `GatewayOptions`, os DTOs públicos de checkout, assinatura, fatura e
+  evento, e a reexportação explícita em `django_checkouts.types`.
+- As dataclasses são congeladas, slotted e keyword-only (exceto
+  `RetryAdvice`, cuja forma posicional é a indicada pela especificação).
+- Centralizados os validadores de quantidades, moeda, UTC, criação de checkout
+  e alterações de assinatura. Resultados e eventos fazem uma cópia defensiva
+  de `raw` com `MappingProxyType(deepcopy(dict(...)))` e omitem esse campo do
+  `repr` e da comparação.
+
+## TDD
+
+1. RED: criado `tests/test_types.py` com os três testes prescritos (dinheiro,
+   imutabilidade/`raw`, quantidade) e executado
+   `uv run pytest tests/test_types.py -q`. A coleta falhou como esperado com
+   `ImportError: cannot import name 'Gateway'`.
+2. RED ampliado: antes da implementação, os testes passaram a abranger itens
+   vazios/moedas mistas/recorrência incompatível, quantidades booleanas,
+   conflitos de alteração, UTC, cópia defensiva de `raw` e `RetryAdvice`.
+   A execução continuou falhando pela mesma API inexistente.
+3. GREEN: após a implementação, `uv run pytest tests/test_types.py
+   tests/test_base.py -q --no-cov` passou com **32 testes**.
+
+## Comandos e resultados
+
+| Comando | Resultado |
+| --- | --- |
+| `uv run pytest tests/test_types.py -q` (RED) | coleta falhou: `Gateway` ausente |
+| `uv run pytest tests/test_types.py tests/test_base.py -q --no-cov` | 32 passed |
+| `uv run pytest -q` | 102 passed; cobertura total 94,39% |
+| `uv run mypy django_checkouts` | sucesso, sem problemas |
+| `uvx ruff check django_checkouts/enums.py django_checkouts/exceptions.py django_checkouts/gateways django_checkouts/types tests/test_types.py` | sucesso |
+| `git diff --check` | sucesso |
+
+O comando literal do brief, sem `--no-cov`, executa os 32 testes com sucesso,
+mas termina com código 1 porque o gate global de 90% de cobertura é aplicado a
+um subconjunto da suíte (64,03%); a suíte completa passa o gate com 94,39%.
+
+## Arquivos alterados
+
+- `django_checkouts/enums.py`
+- `django_checkouts/exceptions.py`
+- `django_checkouts/gateways/__init__.py`
+- `django_checkouts/gateways/options.py`
+- `django_checkouts/types/__init__.py`
+- `django_checkouts/types/common.py`
+- `django_checkouts/types/checkouts.py`
+- `django_checkouts/types/subscriptions.py`
+- `django_checkouts/types/invoices.py`
+- `django_checkouts/types/events.py`
+- `tests/test_types.py`
+
+## Auto-revisão
+
+- Conferidos os valores de todos os novos enums e os campos de `Checkout`,
+  `Subscription`, `Invoice`, `WebhookEvent` e `EventPage` por introspecção de
+  dataclasses.
+- Confirmados `Price` e todos os DTOs no `__all__` explícito.
+- Confirmadas as normalizações de moeda e UTC, a imutabilidade de dataclasses,
+  a ocultação de `raw` no `repr` e a proteção contra mutação da raiz de `raw`.
+- Mantida compatibilidade de imports legados necessária à suíte atual; não
+  foram implementadas tarefas posteriores de gateways/resources.
+
+## Pontos de atenção
+
+- `uvx ruff check .` ainda acusa duas violações preexistentes em
+  `django_checkouts/registry.py` (`S112` e `BLE001`); elas não pertencem a
+  este escopo. O lint de todos os arquivos alterados está limpo.
+- A especificação pede `MappingProxyType` na raiz de `raw`; portanto, valores
+  aninhados continuam objetos mutáveis da cópia defensiva, exatamente conforme
+  a construção prescrita.
+
+## Correção da revisão — 2026-08-15
+
+### RED/GREEN
+
+1. RED: ampliados `tests/test_types.py` e `tests/test_base.py`; a execução de
+   `uv run pytest tests/test_types.py tests/test_base.py -q --no-cov` falhou
+   com 5 falhas esperadas: resultados aceitavam `bool`/`float`, `RetryAdvice`
+   aceitava argumentos posicionais, `GatewayError` retinha token externo e o
+   status financeiro desconhecido ainda levantava `ProviderPermanentError`.
+2. GREEN: adicionada validação estrita de inteiro a todos os montantes públicos
+   de resultado; valores negativos continuam permitidos para créditos e
+   reembolsos. `RetryAdvice` passou a ser `frozen`, `slots` e `kw_only`.
+   Mensagens externas de gateway são substituídas por diagnóstico seguro antes
+   de serem armazenadas. `BaseCheckoutProvider.map_status` agora levanta
+   `GatewayProtocolError`; a herança preserva a compatibilidade com o alias
+   `ProviderPermanentError`.
+
+### Evidência de testes
+
+| Comando | Resultado |
+| --- | --- |
+| `uv run pytest tests/test_types.py tests/test_base.py -q --no-cov` (RED) | 5 failed, 31 passed — falhas esperadas descritas acima |
+| `uv run pytest tests/test_types.py tests/test_base.py -q --no-cov` (GREEN) | 36 passed |
+| `uv run pytest tests/providers/stripe/test_checkout.py -q --no-cov` | 32 passed |
+| `uv run pytest -q` | 106 passed; cobertura total 94,67% |
+| `uv run mypy django_checkouts` | sucesso, sem problemas |
+| `uvx ruff check django_checkouts/exceptions.py django_checkouts/base.py django_checkouts/types tests/test_types.py tests/test_base.py` | sucesso |
+| `git diff --check` | sucesso |
+
+### Auto-revisão da correção
+
+- Conferidos os sete campos monetários solicitados: todos recusam `bool` e
+  `float`; nenhum impõe positividade nos resultados de gateway.
+- Confirmado que segredos e tokens fornecidos via `gateway_message` não são
+  armazenados nem aparecem em `repr`/`str`.
+- Confirmado que o mapeamento desconhecido é `GatewayProtocolError`, mantendo
+  captura legada como `ProviderPermanentError` para provedores existentes.
+- Não há preocupações pendentes no escopo desta correção.
+
+## Correção da re-revisão — 2026-08-15
+
+### RED/GREEN
+
+1. RED: adicionados testes públicos para um `gateway_status` contendo uma
+   credencial, para `typing.get_type_hints` de todos os DTOs reexportados e de
+   `GatewayOptions`, e para os três campos datetime obrigatórios de eventos.
+   `uv run pytest tests/test_types.py tests/test_base.py -q --no-cov` falhou
+   com 5 falhas esperadas: o status externo aparecia na exceção, `Mapping` não
+   era resolvível durante a introspecção e os três valores `None` eram aceitos.
+2. GREEN: `map_status` mantém a orientação para atualizar `STATUS_MAP`, mas
+   não inclui o valor remoto na mensagem. As dependências das anotações dos
+   DTOs e de `GatewayOptions` agora são importadas em runtime, preservando
+   `from __future__ import annotations`. Foi criado `normalize_required_utc`,
+   reutilizando a normalização UTC existente e recusando `None` nos três
+   campos obrigatórios.
+
+### Evidência de testes
+
+| Comando | Resultado |
+| --- | --- |
+| `uv run pytest tests/test_types.py tests/test_base.py -q --no-cov` (RED) | 5 failed, 36 passed — falhas esperadas descritas acima |
+| `uv run pytest tests/test_types.py tests/test_base.py -q --no-cov` (GREEN) | 41 passed |
+| `uv run pytest -q` | 111 passed; cobertura total 95,91% |
+| `uv run mypy django_checkouts` | sucesso, sem problemas |
+| `uvx ruff check django_checkouts/base.py django_checkouts/types django_checkouts/gateways/options.py tests/test_types.py tests/test_base.py` | sucesso |
+| `git diff --check` | sucesso |

django_checkouts-1.0.1/.superpowers/sdd/task-2-report.md

@@ -0,0 +1,68 @@
+# Task 2 — capabilities e despacho tipado
+
+## Escopo entregue
+
+- Capabilities aninhadas, `frozen` e com `slots`; os conjuntos são normalizados
+  para `frozenset` e o mapa de meios de pagamento é protegido por
+  `MappingProxyType`.
+- Os dez comandos internos tipados e os contratos `ExecutionContext` e
+  `CommandHandler`.
+- `BaseCheckoutGateway` com índice de handlers por tipo **exato**, validação antes
+  do contexto de I/O, tradução sanitizada de exceções externas e `check()` vazio.
+- Testes de capabilities, despacho exato, ausência de handler, validação pré-I/O,
+  propagação da variante e sanitização do erro externo.
+
+## Evidência TDD
+
+1. **RED** — após criar `tests/test_capabilities.py` e
+   `tests/test_gateway_dispatch.py`, executei:
+
+   ```console
+   uv run pytest tests/test_capabilities.py tests/test_gateway_dispatch.py -q
+   ```
+
+   A coleta falhou como esperado com `ModuleNotFoundError` para
+   `django_checkouts.capabilities`, pois os módulos de Task 2 ainda não existiam.
+2. **GREEN** — implementei somente os módulos previstos no briefing. A rodada
+   focada sem cobertura passou: `7 passed in 0.08s`.
+3. **REFACTOR** — a anotação da coleção de handlers passou a usar
+   `CommandHandler[Any]`, permitindo handlers concretos de diferentes resultados
+   sem relaxar o despacho exato em runtime. A rodada focada, Ruff e mypy foram
+   repetidos após a alteração.
+
+## Arquivos alterados
+
+- `django_checkouts/capabilities.py`
+- `django_checkouts/gateways/commands.py`
+- `django_checkouts/gateways/contracts.py`
+- `django_checkouts/gateways/base.py`
+- `tests/test_capabilities.py`
+- `tests/test_gateway_dispatch.py`
+
+## Verificação
+
+```console
+uv run pytest tests/test_capabilities.py tests/test_gateway_dispatch.py -q --no-cov
+# 7 passed
+
+uvx ruff check django_checkouts/capabilities.py django_checkouts/gateways tests/test_capabilities.py tests/test_gateway_dispatch.py
+# All checks passed!
+
+uv run mypy django_checkouts
+# Success: no issues found in 27 source files
+
+uv run pytest
+# 118 passed; cobertura total 96.31%
+```
+
+## Auto-revisão e ressalvas
+
+- O despacho usa `type(command)`, portanto subclasses não reutilizam handlers de
+  comandos-base por engano.
+- `validate()` é chamado antes de criar o contexto e antes de qualquer handler
+  poder chamar `context.call`; comandos inválidos e sem handler não fazem I/O.
+- `call()` preserva apenas `CheckoutError`; demais `Exception` viram
+  `GatewayPermanentError` sem expor a mensagem externa.
+- Não foram implementados handlers ou gateways concretos, que pertencem às tarefas
+  posteriores. Handlers concretos devem fazer I/O exclusivamente via
+  `ExecutionContext.call` para conservar a tradução de erros públicos.

django_checkouts-1.0.1/.superpowers/sdd/task-8-report.md

@@ -0,0 +1,99 @@
+# Task 8 report — release surface, documentation, and delivery
+
+## Scope delivered
+
+- Replaced the package root with the exact public exports `CheckoutClient`,
+  `Gateway`, and `get_checkout_gateway`.
+- Added `tests/test_public_interface.py` to lock exact root exports, all ten
+  resource method signatures, statically checked result types via `assert_type`,
+  absence of Stripe SDK names in normalized public annotations, and absence of
+  the pre-1.0 modules and compatibility exports.
+- Removed the pre-1.0 base, DTO, authentication, Stripe implementation, registry
+  compatibility, enums, errors, checks alias, fixtures, and tests. The retained
+  low-level webhook helpers now use gateway terminology consistently.
+- Updated `test_settings.py` to configure
+  `django_checkouts.gateways.stripe.StripeGateway`.
+- Replaced the README with the resource-oriented quickstart, explicit gateway
+  implementation status, persistence boundary, delivery commands, and
+  BSD-3-Clause notice. Added the 1.0 changelog.
+- Added a warning-clean Sphinx site with configuration plus quickstart,
+  subscriptions, webhooks, reconciliation, errors/retries, typed gateway
+  options, gateway authoring, and complete pre-1.0 migration pages. Every
+  public page states that the library owns no persistence.
+- Documented absolute seat quantities, all proration and cancellation choices,
+  resume semantics, raw-body verification, `(variant, event_id)` uniqueness,
+  half-open reconciliation windows with overlap/deduplication, all four retry
+  dispositions, Stripe portability limits, and the gateway contract suite.
+
+## TDD evidence
+
+The structural test was written before production removal. The prescribed RED
+run:
+
+```text
+uv run pytest tests/test_public_interface.py -q
+# 2 failed, 2 passed
+```
+
+The failures were the intended ones: the root still exported only the old
+factory and the old modules were still importable. Exact resource signatures
+and the Stripe-annotation boundary already passed. After replacing the surface:
+
+```text
+uv run pytest tests/test_public_interface.py -q --no-cov
+# 4 passed
+uv run mypy tests/test_public_interface.py
+# Success: no issues found in 1 source file
+```
+
+The direct mypy run proves that every `assert_type` result contract is checked
+statically, in addition to the runtime structural assertions.
+
+## Fresh delivery verification
+
+| Command | Result |
+| --- | --- |
+| `uv sync --all-extras --all-groups` | resolved 60 packages; checked 57 |
+| `uv run pytest` | 196 passed; 95.36% coverage |
+| `uv run mypy django_checkouts` | success across 45 source files |
+| `uv run mypy tests/test_public_interface.py` | success |
+| `uvx ruff check .` | all checks passed |
+| `uv run sphinx-build -W -b html docs docs/_build/html` | build succeeded with warnings as errors |
+| `uv build` | wheel and sdist built successfully |
+| legacy-term scan | matches only `docs/migration-pre-1.0.rst` |
+| public Stripe-annotation scan | no output |
+| `git diff --check` | success |
+
+Both a universal wheel and source distribution exist in `dist/`. A second
+post-commit build derives their version from the clean immutable release commit,
+without a dirty-tree suffix.
+
+## Clean wheel installation
+
+Installed the built wheel plus Stripe into a new `uv` virtual environment
+outside the repository. With Django 5.2.17 and Stripe 15.5.0, the smoke test:
+
+- imported the three exact package exports and `StripeGateway`;
+- confirmed every removed module is undiscoverable;
+- confirmed `py.typed` and the packaged BSD license;
+- confirmed no removed Stripe package path exists in the wheel.
+
+The temporary environment was deleted after the successful check.
+
+The clean-tree wheel smoke test also asserted that its embedded setuptools-scm
+version contains the release commit revision.
+
+## Design notes
+
+- The tests tied exclusively to deleted modules were removed with those modules;
+  the complete gateway lifecycle and contract suites remain and pass.
+- The low-level `django_checkouts.webhooks` utilities were retained because the
+  Task 8 deletion list did not remove that module. Their constructor vocabulary
+  was changed from `provider` to `gateway`, eliminating the compatibility
+  surface and satisfying the release scan.
+- `default_app_config` was removed from the root because modern supported Django
+  versions discover `DjangoCheckoutsConfig` directly.
+
+## Concerns
+
+None.

django_checkouts-1.0.1/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+Todas as mudanças relevantes deste projeto são registradas aqui.
+
+## [1.0.1](https://github.com/davisilvarafacho/django-checkouts/compare/v1.0.0...v1.0.1) (2026-09-05)
+
+
+### Bug Fixes
+
+* alinhar sublinhado do titulo no README.rst ([e885ac9](https://github.com/davisilvarafacho/django-checkouts/commit/e885ac970f754b1b1d808b5ac6445b7306a4cce6))
+* alinhar sublinhado do título no README.rst ([542511e](https://github.com/davisilvarafacho/django-checkouts/commit/542511e1c1eab4153dac23ee60565919b3465b73))
+
+## 1.0.0 (2026-09-05)
+
+
+### Features
+
+* add resource-oriented checkout client ([f047bdd](https://github.com/davisilvarafacho/django-checkouts/commit/f047bdded3f73f595ca02b62a3250b7309b22cbc))
+* add Stripe recurring lifecycle ([c1b5449](https://github.com/davisilvarafacho/django-checkouts/commit/c1b54498c20cb4edf20a852cb2db4b0bfaf39a0c))
+* add Stripe webhooks and reconciliation ([2fd4706](https://github.com/davisilvarafacho/django-checkouts/commit/2fd4706d777e926dbfca575d901f852fed66df92))
+* add typed gateway dispatch ([c4c981e](https://github.com/davisilvarafacho/django-checkouts/commit/c4c981e0f8f2cc304e2f741fee9d1c607fc4ee91))
+* adicionar setup de forma de pagamento ([83c1fb5](https://github.com/davisilvarafacho/django-checkouts/commit/83c1fb546b9269ed40af0dbb16d2492386d8208c))
+* define normalized checkout contracts ([cb5a15e](https://github.com/davisilvarafacho/django-checkouts/commit/cb5a15ec6ba68b4e7e95cc815def27c05629195c))
+* expor fatos financeiros de faturas Stripe ([4695875](https://github.com/davisilvarafacho/django-checkouts/commit/4695875a903e1ce4b628b41837efb86eefed7e8a))
+* port Stripe checkout gateway ([ea47443](https://github.com/davisilvarafacho/django-checkouts/commit/ea47443512288400175d063cec9c351780f7395b))
+* publish gateway integration contracts ([dddca1c](https://github.com/davisilvarafacho/django-checkouts/commit/dddca1c9aee029318375c1e8c26040a75102e819))
+* publish recurring gateway interface ([733964a](https://github.com/davisilvarafacho/django-checkouts/commit/733964ae0cd9b253ac8c3a75dd83e205fd3bcbc2))
+
+
+### Bug Fixes
+
+* completar ciclo de setup de pagamento ([3c0b988](https://github.com/davisilvarafacho/django-checkouts/commit/3c0b988c9d8a78b3fd2723c939c131787f3d0d73))
+* deeply normalize Stripe checkout responses ([d76b0b5](https://github.com/davisilvarafacho/django-checkouts/commit/d76b0b5c5be2cc758df54970de2cf1d7654e8d4a))
+* harden normalized gateway contracts ([9a4fdd9](https://github.com/davisilvarafacho/django-checkouts/commit/9a4fdd90072ad7686277960eff78c03223af7eb8))
+* normalizar eventos de setup ([ce17107](https://github.com/davisilvarafacho/django-checkouts/commit/ce17107186e2153b72efb4e9e5a432e67d7f48a1))
+* normalize Stripe SDK checkout responses ([30d0af7](https://github.com/davisilvarafacho/django-checkouts/commit/30d0af77eada641a7d75eeda7a05303beb345f33))
+* reject Stripe inline subscription prices ([3236c2c](https://github.com/davisilvarafacho/django-checkouts/commit/3236c2c4687538219dc8e461dd6788b688ff7da9))
+
+## 1.0.0
+
+- Publica `CheckoutClient`, `Gateway` e `get_checkout_gateway` como entradas
+  oficiais do pacote.
+- Adiciona recursos tipados para checkouts, assinaturas, faturas, webhooks e
+  reconciliação de eventos.
+- Completa o ciclo Stripe de checkout e cobrança recorrente, com opções
+  específicas tipadas e tradução pública de erros.
+- Publica integração opcional com DRF, fake determinístico e suíte de contrato
+  para gateways externos.
+- Remove a superfície experimental anterior a 1.0; consulte o guia de migração.
+- Mantém o projeto sob a licença BSD-3-Clause.

django_checkouts-1.0.1/CLAUDE.md

@@ -0,0 +1,133 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## O que é
+
+`django-checkouts` — biblioteca (não projeto Django) que dá uma interface única e tipada
+para checkout hospedado de Stripe, PagBank e Asaas, com foco no mercado brasileiro.
+**MVP em construção:** só o Stripe está implementado; PagBank e Asaas ainda não existem
+como código (só como docs de pesquisa em `docs/`).
+
+A lib **não tem models, views, urls nem migrations** — ela nunca toca o banco. Recebe
+argumentos simples, devolve dataclasses normalizados; a persistência é do projeto que a usa.
+
+## Comandos
+
+```console
+uv sync --all-extras          # ambiente (uv >= 0.11.28, Python 3.12 via .python-version)
+uv run pytest                 # suíte completa; gate de 90% de cobertura
+uv run pytest tests/providers/stripe/test_checkout.py::TestCreateCheckout::test_builds_inline_price_data
+uv run pytest -q --no-cov     # rodada rápida sem o relatório de cobertura
+uv run mypy django_checkouts
+uvx ruff check .
+```
+
+`pytest` usa `test_settings.py` como `DJANGO_SETTINGS_MODULE` (sqlite em memória, uma
+variante `stripe` já configurada com credenciais falsas).
+
+## Arquitetura
+
+### O contrato dos providers (`base.py`)
+
+`BaseCheckoutProvider` divide público de protegido, e a divisão é o coração da lib:
+
+- **Público e concreto** (`create_checkout`, `retrieve_checkout`, `cancel_checkout`,
+  `verify_webhook`) — vive na base, valida tudo o que dá para validar sem rede e levanta
+  `ValidationError`/`CapabilityNotSupported` **antes de qualquer I/O**.
+- **Protegido e abstrato** (`_create_checkout`, `_retrieve_checkout`, `_cancel_checkout`,
+  `_parse_webhook`) — é o que um provider novo escreve. Recebe um `CheckoutRequest` já
+  validado e pode confiar nele.
+
+`build_request()` é o funil de validação; `CheckoutRequest` existe justamente para que
+acrescentar um campo em `create_checkout` não mude a assinatura de todos os providers.
+
+### Registry e configuração (`registry.py`)
+
+Providers são "variantes nomeadas" em `settings.CHECKOUT_VARIANTS`:
+`{"stripe": ("caminho.pontilhado.Classe", {**kwargs_do_construtor})}`.
+`get_checkout_provider("stripe")` cacheia a instância em `PROVIDER_CACHE`;
+`get_checkout_provider("asaas", api_key=...)` (com overrides) **não** cacheia — é o caso
+multi-tenant. `conftest.py` limpa o cache entre testes por autouse fixture.
+
+### As duas direções de autenticação
+
+Fácil de confundir; são módulos separados de propósito:
+
+- `credentials.py` — **saída** (app → gateway). `BaseAuth`/`TokenAuth` aplicam o header de
+  API numa sessão de requests. Token com `repr=False` para não vazar em traceback.
+- `webhooks.py` — **entrada** (gateway → app). `BaseWebhookAuth` prova a origem e devolve
+  o payload já decodificado. Comparação de segredo sempre com `hmac.compare_digest`.
+  `HeaderTokenWebhookAuth` (modelo Asaas) e `Sha256BodyWebhookAuth` (modelo PagBank) já
+  existem, sem provider que as use ainda.
+
+Ambos expõem `validate() -> list[CheckMessage]`, e `checks.py` transforma isso em saída do
+`manage.py check` — credencial ausente vira erro de deploy, não 401 no primeiro cliente.
+
+`authentication.py` é a camada DRF opcional: `webhook_auth_for(Provider.STRIPE)` fabrica a
+authentication class, e o `WebhookPayload` verificado chega em `request.auth`. O
+`request.user` vira um `FakeGatewayUser` — usuário falso, sem banco, que só existe porque o
+DRF exige o par `(user, auth)`.
+
+### Invariantes que atravessam tudo
+
+- **Dinheiro é sempre `int` em centavos.** R$ 49,90 é `4990`. `amount_decimal` /
+  `amount_total_decimal` existem só para exibição.
+- **Todo objeto de resposta carrega `raw`** — o payload cru intacto. Para visão tipada do
+  cru, cada provider declara uma subclasse de `ProviderState` (`from_raw` descarta chaves
+  desconhecidas, então campo novo do provedor não quebra nada).
+- **Corpo cru de webhook, sempre.** Reserializar o JSON invalida a assinatura do Stripe e o
+  hash do PagBank.
+- **`map_status` levanta no desconhecido; `map_event` devolve `None`.** Não há
+  `CheckoutStatus.UNKNOWN`: um status não mapeado circularia como estado legítimo e só
+  apareceria na conciliação de dinheiro. Evento desconhecido é o oposto — os provedores
+  emitem dezenas de eventos sem relação com checkout, e derrubar o webhook por causa deles
+  travaria a fila de notificações da conta.
+- **Nada que não seja `CheckoutError` sai de um provider.** Se `requests.Timeout` ou
+  `KeyError` vazar, é bug. A divisão `ProviderTemporaryError` vs `ProviderPermanentError`
+  carrega a semântica de retry no próprio tipo.
+- **Capacidades opcionais são declaradas, não improvisadas.** `CAPABILITIES`,
+  `SUPPORTED_PAYMENT_METHODS` e `SUPPORTED_CYCLES` fazem a base recusar de forma uniforme,
+  antes da rede, em vez de cada provider levantar `NotImplementedError` do seu jeito.
+- **`BillingCycle` tem opções fechadas** (nomes seguem os do Asaas, o vocabulário mais
+  restrito dos três). Expor o par `interval`+`interval_count` do Stripe não sobreviveria à
+  tradução. Cada provider converte: `QUARTERLY` → `("month", 3)` no Stripe.
+
+### Escrever um provider novo
+
+Subclassear `BaseCheckoutProvider`; definir `name`, `STATUS_MAP`, `EVENT_MAP`,
+`CAPABILITIES`, `SUPPORTED_PAYMENT_METHODS`, `SUPPORTED_CYCLES`, `state_class`; no
+`__init__` montar `self.auth` e `self.webhook_auth`; implementar os quatro métodos
+protegidos. O Stripe (`providers/stripe/checkout.py`) é o modelo de referência — inclusive
+do `_call()`, que traduz os erros do SDK para a taxonomia da lib. Note que o `STATUS_MAP`
+dele é chaveado por `f"{status}/{payment_status}"`, porque no Stripe "a sessão terminou" e
+"o dinheiro entrou" são campos diferentes.
+
+## Convenções
+
+- **Português (pt-BR) em docstrings, mensagens de erro e comentários.** As mensagens são
+  longas de propósito: dizem o que fazer, não só o que falhou. Mantenha esse tom.
+- Enums são `models.TextChoices` com `pgettext_lazy` — serializam como string direto num
+  campo de model e o rótulo é traduzível.
+- **Identidade de provedor é `Provider`, nunca string solta.** `name = Provider.STRIPE`,
+  `get_checkout_provider(Provider.STRIPE)`, `webhook_auth_for(Provider.PAGSEGURO)`. Como é
+  `TextChoices`, o membro casa com a chave string do `CHECKOUT_VARIANTS` em `settings` —
+  e o settings do usuário continua com string crua, porque um módulo de settings não deve
+  importar a lib. String crua no código só para variante com nome próprio (`"stripe-br"`,
+  multi-tenant); por isso as anotações são `Provider | str`.
+- Ruff: um import por linha (`force-single-line`) e `from __future__ import annotations`
+  obrigatório no topo de todo módulo, inclusive testes.
+- Nenhum teste toca a rede: SDK e respostas HTTP são substituídos, com fixtures de payload
+  real em `tests/providers/<provider>/fixtures/`. A fixture `load_fixture` do `conftest.py`
+  resolve o caminho ao lado do módulo de teste.
+- Versão vem do `setuptools_scm` (tag git) e é escrita em `django_checkouts/version.py`,
+  que é gitignored.
+
+## `docs/`
+
+Notas de pesquisa, não documentação de usuário: `integracao-sandbox-{stripe,pagseguro,asaas}.md`
+levantam as particularidades de cada API (credenciais, sandbox, formato de webhook) e
+marcam com ⚠️ o que **não** foi confirmado na fonte oficial. `plano-testes-sandbox.md`
+descreve uma suíte contra sandbox real, ainda não implementada. Ao implementar PagBank ou
+Asaas, esses arquivos são o ponto de partida — e os itens ⚠️ precisam de validação antes de
+virarem código.

django_checkouts-1.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Davi Rafacho
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.