bucli 0.6.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bucli-0.6.0/.gitignore +9 -0
- bucli-0.6.0/CHANGELOG.md +97 -0
- bucli-0.6.0/LICENSE +21 -0
- bucli-0.6.0/PKG-INFO +541 -0
- bucli-0.6.0/README.md +505 -0
- bucli-0.6.0/pyproject.toml +72 -0
- bucli-0.6.0/src/bucli/__init__.py +52 -0
- bucli-0.6.0/src/bucli/_version.py +1 -0
- bucli-0.6.0/src/bucli/client.py +274 -0
- bucli-0.6.0/src/bucli/constants.py +92 -0
- bucli-0.6.0/src/bucli/contrib/__init__.py +1 -0
- bucli-0.6.0/src/bucli/contrib/django/__init__.py +6 -0
- bucli-0.6.0/src/bucli/contrib/django/access.py +99 -0
- bucli-0.6.0/src/bucli/contrib/django/admin.py +19 -0
- bucli-0.6.0/src/bucli/contrib/django/apps.py +8 -0
- bucli-0.6.0/src/bucli/contrib/django/conf.py +140 -0
- bucli-0.6.0/src/bucli/contrib/django/exceptions.py +17 -0
- bucli-0.6.0/src/bucli/contrib/django/management/__init__.py +0 -0
- bucli-0.6.0/src/bucli/contrib/django/management/commands/__init__.py +0 -0
- bucli-0.6.0/src/bucli/contrib/django/management/commands/bucli_flush_usage.py +18 -0
- bucli-0.6.0/src/bucli/contrib/django/management/commands/bucli_sync.py +66 -0
- bucli-0.6.0/src/bucli/contrib/django/metering.py +137 -0
- bucli-0.6.0/src/bucli/contrib/django/migrations/0001_initial.py +102 -0
- bucli-0.6.0/src/bucli/contrib/django/migrations/0002_billingaccount_bucli_updated_at.py +15 -0
- bucli-0.6.0/src/bucli/contrib/django/migrations/0003_pendingusage.py +40 -0
- bucli-0.6.0/src/bucli/contrib/django/migrations/__init__.py +0 -0
- bucli-0.6.0/src/bucli/contrib/django/models.py +122 -0
- bucli-0.6.0/src/bucli/contrib/django/services.py +617 -0
- bucli-0.6.0/src/bucli/contrib/django/signals.py +22 -0
- bucli-0.6.0/src/bucli/contrib/django/urls.py +11 -0
- bucli-0.6.0/src/bucli/contrib/django/views.py +50 -0
- bucli-0.6.0/src/bucli/contrib/django/webhooks.py +236 -0
- bucli-0.6.0/src/bucli/errors.py +193 -0
- bucli-0.6.0/src/bucli/keys.py +18 -0
- bucli-0.6.0/src/bucli/metering.py +331 -0
- bucli-0.6.0/src/bucli/objects.py +168 -0
- bucli-0.6.0/src/bucli/py.typed +0 -0
- bucli-0.6.0/src/bucli/resources.py +1002 -0
- bucli-0.6.0/src/bucli/webhook.py +136 -0
- bucli-0.6.0/tests/conftest.py +38 -0
- bucli-0.6.0/tests/django_project/__init__.py +0 -0
- bucli-0.6.0/tests/django_project/settings.py +45 -0
- bucli-0.6.0/tests/django_project/tenants/__init__.py +0 -0
- bucli-0.6.0/tests/django_project/tenants/apps.py +5 -0
- bucli-0.6.0/tests/django_project/tenants/migrations/0001_initial.py +15 -0
- bucli-0.6.0/tests/django_project/tenants/migrations/__init__.py +0 -0
- bucli-0.6.0/tests/django_project/tenants/models.py +8 -0
- bucli-0.6.0/tests/django_project/urls.py +5 -0
- bucli-0.6.0/tests/django_tests/conftest.py +29 -0
- bucli-0.6.0/tests/django_tests/helpers.py +39 -0
- bucli-0.6.0/tests/django_tests/test_django_metering.py +79 -0
- bucli-0.6.0/tests/django_tests/test_django_services.py +453 -0
- bucli-0.6.0/tests/django_tests/test_django_webhook.py +365 -0
- bucli-0.6.0/tests/factories.py +145 -0
- bucli-0.6.0/tests/test_client.py +287 -0
- bucli-0.6.0/tests/test_contract.py +199 -0
- bucli-0.6.0/tests/test_metering.py +173 -0
- bucli-0.6.0/tests/test_objects_and_pagination.py +103 -0
- bucli-0.6.0/tests/test_resources.py +845 -0
- bucli-0.6.0/tests/test_webhook.py +127 -0
bucli-0.6.0/.gitignore
ADDED
bucli-0.6.0/CHANGELOG.md
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Todos los cambios de esta librería. Formato [Keep a Changelog](https://keepachangelog.com/); versiones [SemVer](https://semver.org/).
|
|
4
|
+
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
## [0.6.0] - 2026-11-17
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
- La librería se publica en PyPI: `pip install "bucli[django]"`. Cada etiqueta `vX.Y.Z` la publica con *trusted publishing* (`.github/workflows/publish.yml`, sin token guardado) y crea la release en GitHub; `ci.yml` corre ruff, las pruebas en Python 3.11–3.13 con Django 4.2, 5.2 y la última, y revisa el paquete con `twine check`.
|
|
11
|
+
- Workflow `saas-bump.yml`: cuando una versión queda publicada en PyPI, abre un PR en cada SaaS que usa la librería que mueve su pin de `requirements/base.txt` a `bucli[django]==X.Y.Z` (un pin desde git pasa a PyPI) y trae las notas de la versión. Necesita el secreto `SAAS_REPOS_TOKEN`.
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
- Licencia MIT (era propietaria). La versión sale de `src/bucli/_version.py`.
|
|
15
|
+
- El README es público: instalación desde PyPI, sin enlaces a documentos internos.
|
|
16
|
+
|
|
17
|
+
## [0.5.0] - 2026-11-12
|
|
18
|
+
|
|
19
|
+
### Added
|
|
20
|
+
- Eventos `product.created` y `product.updated` en `EVENT_TYPES` (`product.updated` trae `previous_attributes`): un SaaS que copia su catálogo se entera de los cambios hechos en el panel de Bucli.
|
|
21
|
+
- Constantes de la vitrina: `PLACEMENT_MAIN` / `PLACEMENT_SECONDARY` (`storefront.placement` de un producto: tarjeta entre los planes principales o línea bajo ellos) y `PRODUCT_KIND_PLAN` / `_ADDON` / `_ONE_TIME` / `_TRIAL` (`kind`, que Bucli lee de las reglas y los precios del producto). `products.create/update` ya aceptan `placement`; `products.list` filtra por `placement` y `kind`.
|
|
22
|
+
|
|
23
|
+
## [0.4.0] - 2026-11-11
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
- `customers.create/update` documentan `fiscal`: los datos del cliente para la factura electrónica.
|
|
27
|
+
- Evento `invoice.updated` en `EVENT_TYPES` (cambió el valor de un cobro abierto: un cupón aplicado mientras estaba pendiente).
|
|
28
|
+
- Django: `services.sync_customer(account, email=…, name=…, phone=…, fiscal=…)` envía los datos actuales de la cuenta a su cliente de Bucli (solo lo que no sea `None`; sin cliente vinculado no hace nada).
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
- Django: `ensure_customer` y `start_checkout` aceptan `external_id`, `phone` y `fiscal`. Con `external_id` el cliente se busca por él y nunca por el correo (dos empresas del mismo dueño ya no se mezclan).
|
|
32
|
+
|
|
33
|
+
## [0.3.0] - 2026-11-09
|
|
34
|
+
|
|
35
|
+
### Added
|
|
36
|
+
- Recursos de F3–F8 de la API: `subscriptions.preview` (prorrateo), `pause`, `resume`, `extend_period`, `extend_trial`, `end_trial`, `apply_discount`, `delete_discount`, `list_actions`; `payment_methods.set_backup`; `invoices.mark_paid`; `payments.refund` y `void`; `refunds`, `coupons` y `fixed_term_offers`.
|
|
37
|
+
- `error.quote`: la cotización nueva de un `409 quote_changed`.
|
|
38
|
+
- Eventos `subscription.update_failed`, `notice.sent`, `charge.refunded`, `payment_method.suspended` y `payment_method.expiring` en `EVENT_TYPES`.
|
|
39
|
+
- Django: `services.preview_plan_change` y `change_plan(..., proration_behavior="create_prorations", expected_amount=…)`; el webhook procesa `subscription.update_failed`, `charge.refunded` (resuelve la cuenta por la factura y la suscripción del refund) y `notice.sent` (por su cliente o suscripción), y `event_processed` los entrega con su cuenta.
|
|
40
|
+
|
|
41
|
+
### Changed
|
|
42
|
+
- `subscription_items.delete` acepta `expected_amount`; los docstrings de `subscriptions.create/update` y de los ítems describen `trial_key`, `coupon`, `overage_caps` y el prorrateo.
|
|
43
|
+
- El docstring de `subscriptions.update` describe `items` (cambio de ciclo de un plan con adicionales, solo prorrateado) y el `202` con el `subscription_change` mientras el cambio espera su cobro.
|
|
44
|
+
|
|
45
|
+
## [0.2.1] - 2026-11-07
|
|
46
|
+
|
|
47
|
+
### Fixed
|
|
48
|
+
- La prueba de las cabeceras lee la versión del paquete (fallaba en v0.2.0 con la versión fija `0.1.0`).
|
|
49
|
+
|
|
50
|
+
### Changed
|
|
51
|
+
- `customers.create`/`list` documentan `external_id` (un cliente por empresa).
|
|
52
|
+
|
|
53
|
+
## [0.2.0] - 2026-11-07
|
|
54
|
+
|
|
55
|
+
### Added
|
|
56
|
+
- Recursos de derechos y medidores: `features`, `meters` (`summary`, `reserve`), `usage` (`report`, `release`), `grant_offers` (`purchase`), `grants` (`withdraw`), `customers.entitlements`, `subscriptions.entitlements` y `subscriptions.set_entitlement_overrides`.
|
|
57
|
+
- `bucli.metering.UsageGuard`: el modo `on_unavailable: allow` — si Bucli no responde en 2 s deja pasar la unidad, la encola con su `idempotency_key` y `flush()` la reporta después; guarda el saldo de cada respuesta y niega sin llamar cuando está en cero.
|
|
58
|
+
- Django: `bucli.contrib.django.metering.guard()` con la cola en la base (`PendingUsage`, migración 0003) y los saldos en la caché; `manage.py bucli_flush_usage`.
|
|
59
|
+
- `request()` acepta `timeout` y `max_retries` por llamada.
|
|
60
|
+
|
|
61
|
+
## [0.1.0] - 2026-11-02
|
|
62
|
+
|
|
63
|
+
### Added
|
|
64
|
+
- `bucli.Bucli`: cliente de la API `/v1` (versión `2026-11-01`). El modo lo decide la llave (`sk_test_`/`sk_live_`) y una llave `pk_` se rechaza.
|
|
65
|
+
- `Idempotency-Key` automático en cada POST, reutilizado en los reintentos.
|
|
66
|
+
- Reintentos con backoff y jitter solo ante errores de red, `409 idempotency_key_in_use`, `429` (con `Retry-After`) y `5xx`.
|
|
67
|
+
- Recursos, cada uno con solo los endpoints que documenta la API:
|
|
68
|
+
- `account`, `customers`, `products`, `prices` (`recurring` y `one_time`);
|
|
69
|
+
- `subscriptions` (`items`, `billing_cycle_anchor`, `trial_end`, `cancel`) y `subscription_items`;
|
|
70
|
+
- `payment_methods`, con la importación de `wompi_payment_source_id`;
|
|
71
|
+
- `invoices` (factura única, `pay`, `void`, `lines`) y `payments`;
|
|
72
|
+
- `events` (`resend`) y `webhook_endpoints` (`roll_secret`);
|
|
73
|
+
- `checkout_sessions`, `payment_links` y `portal_sessions`.
|
|
74
|
+
- Recuperación automática de `409 url_unavailable_on_replay` en el checkout y en el portal.
|
|
75
|
+
- Objetos que son `dict` y además se leen por atributo (`BucliObject`, `ListObject`), con `last_response`.
|
|
76
|
+
- Paginación: `list()` devuelve una página y `auto_paging_iter()` recorre todas, hacia adelante o hacia atrás, también en listas incrustadas. `expand[]` en todas las lecturas.
|
|
77
|
+
- Errores tipados: `AuthenticationError`, `PermissionError`, `InvalidRequestError`, `IdempotencyError`, `RateLimitError`, `BillingError`/`CardError`, `APIError` y `APIConnectionError`, con `type`, `code`, `message`, `param`, `request_id` y `http_status`.
|
|
78
|
+
- `bucli.Webhook.construct_event`:
|
|
79
|
+
- verifica la firma HMAC-SHA256 en tiempo constante;
|
|
80
|
+
- acepta cualquiera de las firmas `v1` durante una rotación;
|
|
81
|
+
- rechaza un timestamp viejo o del futuro y un cuerpo que no sea JSON;
|
|
82
|
+
- `generate_test_header` arma una cabecera válida para pruebas.
|
|
83
|
+
- `bucli.contrib.django` (app `bucli_billing`, extra `[django]`, Django ≥ 4.2):
|
|
84
|
+
- modelos `BillingAccount` y `ProcessedEvent`, con migración;
|
|
85
|
+
- la vista del webhook: verifica, deduplica, vuelve a pedir el objeto, se protege de los eventos fuera de orden con `sequence` y escribe en una transacción;
|
|
86
|
+
- las señales `subscription_changed` y `event_processed`;
|
|
87
|
+
- los servicios `start_checkout`, `portal_url`, `change_plan`, `cancel`, `reactivate`, `sync`, `link` y `discover`;
|
|
88
|
+
- la regla de acceso: `has_access`, `access_level` y `current_plan`;
|
|
89
|
+
- el comando `bucli_sync [pks] [--all] [--discover]`.
|
|
90
|
+
- Pruebas sin red (`responses`), entre ellas una prueba de contrato contra el registro de documentación de la API de Bucli.
|
|
91
|
+
- `checkout_sessions.create` y `payment_links.create` documentan y envían `line_items=[{price, quantity}]` (plan base + puestos + adicionales), `quantity` y, en el checkout, `subscription_data={metadata, trial_days}`.
|
|
92
|
+
- `services.start_checkout(account, items=[...])` en la integración de Django: `"price_…"`, `("price_…", 3)` o `{"price", "quantity"}`, con al menos un precio de `BUCLI_PRICE_PLANS`; `quantity` y `subscription_metadata`. La suscripción creada lleva `metadata.bucli_account`.
|
|
93
|
+
- `portal_sessions.retrieve(id)` (`GET /v1/portal_sessions/{id}`): la sesión sin su `url`.
|
|
94
|
+
- `BucliError.object_id` y `object_type`: el objeto que nombra un `409 url_unavailable_on_replay` o `webhook_secret_unavailable_on_replay`.
|
|
95
|
+
- `BillingAccount.bucli_updated_at` (migración `0002`): el `updated` de Bucli de la copia local.
|
|
96
|
+
- La recuperación de `409 url_unavailable_on_replay` del checkout usa `error.object_id` en vez de buscar el id en el mensaje (sin `object_id`, el error se propaga).
|
|
97
|
+
- `store_subscription` ordena las copias de una suscripción por su `updated`: una más vieja que la guardada es `stale` (también en `sync`) y una más nueva se aplica aunque su evento tenga un `sequence` menor; `sequence` decide cuando `updated` no puede. `last_event_sequence` ya no retrocede.
|
bucli-0.6.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Bithaus SAS
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|