stapel-billing 0.4.1__tar.gz

stapel_billing-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 usestapel
+
+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.

stapel_billing-0.4.1/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: stapel-billing
+Version: 0.4.1
+Summary: Billing and payments Django app for the Stapel framework
+License: MIT
+Keywords: django,stapel,billing,payments,stripe
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.4,>=0.3.0
+Provides-Extra: stripe
+Requires-Dist: stripe<12,>=8.0; extra == "stripe"
+Provides-Extra: all
+Requires-Dist: stapel-billing[stripe]; extra == "all"
+Dynamic: license-file
+
+# stapel-billing
+
+[![CI](https://github.com/usestapel/stapel-billing/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-billing/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-billing/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-billing)
+
+> Billing — Stripe subscriptions, credit wallets, transaction history
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps for building production-grade platforms.
+
+## Installation
+
+```bash
+pip install stapel-billing
+```
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'stapel_billing',
+]
+```
+
+## Bus events
+
+### Emits
+| `payment.completed` | [schema](schemas/emits/payment.completed.json) | A payment transaction completed successfully. |
+| `subscription.changed` | [schema](schemas/emits/subscription.changed.json) | User subscription plan or status changed. |
+
+### Consumes
+| `user.deleted` | [schema](schemas/consumes/user.deleted.json) |
+| `user.deletion_initiated` | [schema](schemas/consumes/user.deletion_initiated.json) |
+
+## License
+
+MIT — see [LICENSE](LICENSE)

stapel_billing-0.4.1/README.md

@@ -0,0 +1,38 @@
+# stapel-billing
+
+[![CI](https://github.com/usestapel/stapel-billing/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-billing/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-billing/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-billing)
+
+> Billing — Stripe subscriptions, credit wallets, transaction history
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps for building production-grade platforms.
+
+## Installation
+
+```bash
+pip install stapel-billing
+```
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'stapel_billing',
+]
+```
+
+## Bus events
+
+### Emits
+| `payment.completed` | [schema](schemas/emits/payment.completed.json) | A payment transaction completed successfully. |
+| `subscription.changed` | [schema](schemas/emits/subscription.changed.json) | User subscription plan or status changed. |
+
+### Consumes
+| `user.deleted` | [schema](schemas/consumes/user.deleted.json) |
+| `user.deletion_initiated` | [schema](schemas/consumes/user.deletion_initiated.json) |
+
+## License
+
+MIT — see [LICENSE](LICENSE)

stapel_billing-0.4.1/__init__.py

@@ -0,0 +1,49 @@
+"""stapel-billing — wallets, credit ledger and pluggable payment providers.
+
+Public API (lazily resolved, PEP 562 — importing this package pulls in
+no Django code until an attribute is actually accessed):
+
+    billing_settings          — the ``STAPEL_BILLING`` settings namespace
+    credit                    — add credits to a user's wallet
+    debit                     — deduct credits (raises InsufficientCreditsError)
+    get_provider              — instantiate the configured PaymentProvider
+    PaymentProvider           — base class for custom payment backends
+    InsufficientCreditsError  — raised by ``debit`` on insufficient balance
+"""
+
+__all__ = [
+    "InsufficientCreditsError",
+    "PaymentProvider",
+    "billing_settings",
+    "credit",
+    "debit",
+    "get_provider",
+]
+
+# name -> (relative module, attribute)
+_EXPORTS = {
+    "billing_settings": (".conf", "billing_settings"),
+    "credit": (".services", "credit"),
+    "debit": (".services", "debit"),
+    "get_provider": (".services", "get_provider"),
+    "InsufficientCreditsError": (".services", "InsufficientCreditsError"),
+    "PaymentProvider": (".providers.base", "PaymentProvider"),
+}
+
+
+def __getattr__(name):
+    try:
+        module_path, attr = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(
+            f"module {__name__!r} has no attribute {name!r}"
+        ) from None
+    from importlib import import_module
+
+    value = getattr(import_module(module_path, __name__), attr)
+    globals()[name] = value  # cache: subsequent lookups skip __getattr__
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_billing-0.4.1/actions.py

@@ -0,0 +1,23 @@
+"""Action subscriptions of the billing module.
+
+Handlers must be idempotent: delivery is at-least-once (outbox retries,
+broker redelivery).
+"""
+import logging
+
+from stapel_core.comm import on_action
+
+logger = logging.getLogger(__name__)
+
+
+@on_action("user.deleted")
+def handle_user_deleted(event):
+    """Erase this module's PII when an account deletion is executed."""
+    from .gdpr import BillingGDPRProvider
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error("user.deleted event without user_id: %s", event.event_id)
+        return
+    BillingGDPRProvider().delete(user_id)
+    logger.info("billing data erased for deleted user %s", user_id)

stapel_billing-0.4.1/admin.py

@@ -0,0 +1,42 @@
+from django.contrib import admin
+
+from .models import StripeWebhookEvent, Subscription, Transaction, Wallet
+
+
+@admin.register(Wallet)
+class WalletAdmin(admin.ModelAdmin):
+    list_display = ["user", "balance", "currency", "auto_recharge_enabled", "updated_at"]
+    search_fields = ["user__email", "user__id"]
+    readonly_fields = ["id", "created_at", "updated_at"]
+
+
+@admin.register(Transaction)
+class TransactionAdmin(admin.ModelAdmin):
+    list_display = ["wallet", "type", "credits_delta", "balance_after", "created_at"]
+    list_filter = ["type"]
+    search_fields = ["wallet__user__email", "description"]
+    readonly_fields = [
+        "id",
+        "wallet",
+        "type",
+        "amount_cents",
+        "credits_delta",
+        "balance_after",
+        "metadata",
+        "created_at",
+    ]
+
+
+@admin.register(Subscription)
+class SubscriptionAdmin(admin.ModelAdmin):
+    list_display = ["user", "plan", "status", "current_period_end", "cancelled_at"]
+    list_filter = ["plan", "status"]
+    search_fields = ["user__email", "stripe_subscription_id", "stripe_customer_id"]
+
+
+@admin.register(StripeWebhookEvent)
+class StripeWebhookEventAdmin(admin.ModelAdmin):
+    list_display = ["stripe_event_id", "event_type", "processed_at", "received_at"]
+    list_filter = ["event_type"]
+    search_fields = ["stripe_event_id"]
+    readonly_fields = ["id", "received_at"]

stapel_billing-0.4.1/apps.py

@@ -0,0 +1,17 @@
+from django.apps import AppConfig
+
+
+class BillingConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "stapel_billing"
+    label = 'billing'
+    verbose_name = "Stapel Billing"
+
+    def ready(self):
+        from stapel_core.gdpr import gdpr_registry
+        from .gdpr import BillingGDPRProvider
+        gdpr_registry.register(BillingGDPRProvider())
+
+        # Action subscriptions (in-process in a monolith, bus consumer in
+        # microservices — same code, transport chosen by STAPEL_COMM).
+        from . import actions  # noqa: F401

stapel_billing-0.4.1/catalog.py

@@ -0,0 +1,161 @@
+"""
+Credit packages and subscription plan catalogue.
+
+The lists below are *defaults*.  Host projects override them through the
+``STAPEL_BILLING`` settings namespace without forking::
+
+    STAPEL_BILLING = {
+        "CREDIT_PACKAGES": [
+            {"slug": "mini", "name": "Mini", "credits": 100, "price_cents": 200},
+        ],
+        "PLANS": [
+            {"slug": "free", "name": "Free", "price_cents": 0,
+             "monthly_credits_included": 0, "storage_limit_bytes": 0,
+             "description": "..."},
+        ],
+    }
+
+Entries may be dicts (converted to the dataclasses below) or dataclass
+instances.  The module-level names ``CREDIT_PACKAGES`` / ``PLANS`` /
+``CREDIT_PACKAGES_BY_SLUG`` / ``PLANS_BY_SLUG`` keep working — they are
+lazy views that re-read the configuration on every access.
+"""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Callable, Iterator
+
+
+@dataclass(frozen=True)
+class CreditPackage:
+    slug: str
+    name: str
+    credits: int
+    price_cents: int
+    currency: str = "USD"
+
+
+@dataclass(frozen=True)
+class PlanCatalogEntry:
+    slug: str
+    name: str
+    price_cents: int
+    monthly_credits_included: int
+    storage_limit_bytes: int
+    description: str
+    currency: str = "USD"
+
+
+DEFAULT_CREDIT_PACKAGES = [
+    CreditPackage("starter", "Starter", credits=500, price_cents=500),
+    CreditPackage("standard", "Standard", credits=2200, price_cents=2000),
+    CreditPackage("bulk", "Bulk", credits=6000, price_cents=5000),
+]
+
+DEFAULT_PLANS = [
+    PlanCatalogEntry(
+        slug="free",
+        name="Free",
+        price_cents=0,
+        monthly_credits_included=0,
+        storage_limit_bytes=5 * 1024 * 1024 * 1024,
+        description="5h upload per month, Fast ASR only, community support.",
+    ),
+    PlanCatalogEntry(
+        slug="pro",
+        name="Pro",
+        price_cents=1500,
+        monthly_credits_included=300,
+        storage_limit_bytes=100 * 1024 * 1024 * 1024,
+        description="Unlimited upload, Accurate ASR, 300 credits/mo.",
+    ),
+    PlanCatalogEntry(
+        slug="team",
+        name="Team",
+        price_cents=2500,
+        monthly_credits_included=600,
+        storage_limit_bytes=500 * 1024 * 1024 * 1024,
+        description="Pro plus team roles, 600 credits/mo, SSO.",
+    ),
+    PlanCatalogEntry(
+        slug="enterprise",
+        name="Enterprise",
+        price_cents=0,
+        monthly_credits_included=0,
+        storage_limit_bytes=10 * 1024 * 1024 * 1024 * 1024,
+        description="Custom pricing.",
+    ),
+]
+
+
+def _coerce(entry, cls):
+    if isinstance(entry, cls):
+        return entry
+    if isinstance(entry, Mapping):
+        return cls(**entry)
+    raise TypeError(
+        f"catalog entries must be {cls.__name__} instances or dicts, got {entry!r}"
+    )
+
+
+def get_credit_packages() -> list[CreditPackage]:
+    """Resolve the credit-package catalogue through STAPEL_BILLING config."""
+    from .conf import billing_settings
+
+    raw = billing_settings.CREDIT_PACKAGES
+    return [_coerce(e, CreditPackage) for e in raw]
+
+
+def get_plans() -> list[PlanCatalogEntry]:
+    """Resolve the plan catalogue through STAPEL_BILLING config."""
+    from .conf import billing_settings
+
+    raw = billing_settings.PLANS
+    return [_coerce(e, PlanCatalogEntry) for e in raw]
+
+
+class _LazyCatalogList(Sequence):
+    """Sequence view over a loader — re-reads configuration on access."""
+
+    def __init__(self, loader: Callable[[], list]) -> None:
+        self._loader = loader
+
+    def __getitem__(self, index):
+        return self._loader()[index]
+
+    def __len__(self) -> int:
+        return len(self._loader())
+
+    def __iter__(self) -> Iterator:
+        return iter(self._loader())
+
+    def __repr__(self) -> str:
+        return repr(self._loader())
+
+
+class _LazyBySlug(Mapping):
+    """Mapping view keyed by slug — re-reads configuration on access."""
+
+    def __init__(self, loader: Callable[[], list]) -> None:
+        self._loader = loader
+
+    def _mapping(self) -> dict:
+        return {entry.slug: entry for entry in self._loader()}
+
+    def __getitem__(self, key):
+        return self._mapping()[key]
+
+    def __iter__(self) -> Iterator:
+        return iter(self._mapping())
+
+    def __len__(self) -> int:
+        return len(self._mapping())
+
+    def __repr__(self) -> str:
+        return repr(self._mapping())
+
+
+CREDIT_PACKAGES = _LazyCatalogList(get_credit_packages)
+PLANS = _LazyCatalogList(get_plans)
+CREDIT_PACKAGES_BY_SLUG = _LazyBySlug(get_credit_packages)
+PLANS_BY_SLUG = _LazyBySlug(get_plans)

stapel_billing-0.4.1/conf.py

@@ -0,0 +1,49 @@
+"""Settings namespace for stapel-billing.
+
+All configuration is read through ``billing_settings`` (lazily, at call
+time) instead of module-level ``os.getenv`` — so tests and host projects
+can override any key via ``settings.STAPEL_BILLING``, a flat Django
+setting of the same name, or an environment variable::
+
+    STAPEL_BILLING = {
+        "PAYMENT_PROVIDER": "myproject.billing.MyProvider",
+        "STRIPE_SECRET_KEY": "sk_live_...",
+        "CREDIT_PACKAGES": [
+            {"slug": "mini", "name": "Mini", "credits": 100, "price_cents": 200},
+        ],
+        "PLANS": [...],
+    }
+
+``PAYMENT_PROVIDER`` is resolved with import_string — the dotted-path
+escape hatch that makes the payment backend swappable without forking.
+"""
+from stapel_core.conf import AppSettings
+
+from . import catalog as _catalog
+
+billing_settings = AppSettings(
+    "STAPEL_BILLING",
+    defaults={
+        # Dotted path to a stapel_billing.providers.base.PaymentProvider subclass.
+        "PAYMENT_PROVIDER": "stapel_billing.providers.stripe.StripeProvider",
+        # Read lazily at call time (never frozen at import).
+        "STRIPE_SECRET_KEY": "",
+        "STRIPE_WEBHOOK_SECRET": "",
+        # Catalog overrides: lists of dicts (converted to the catalog
+        # dataclasses) or dataclass instances. Defaults live in catalog.py.
+        "CREDIT_PACKAGES": _catalog.DEFAULT_CREDIT_PACKAGES,
+        "PLANS": _catalog.DEFAULT_PLANS,
+        # Fallback redirect targets for Stripe Checkout / customer portal,
+        # used when the request does not carry them. Empty by default;
+        # when unset the fallback is derived from the flat FRONTEND_URL
+        # setting, and with neither configured the request is rejected
+        # with error.400.redirect_url_not_configured (no placeholder
+        # domains, ever).
+        "CHECKOUT_SUCCESS_URL": "",
+        "CHECKOUT_CANCEL_URL": "",
+        "PORTAL_RETURN_URL": "",
+    },
+    import_strings=("PAYMENT_PROVIDER",),
+)
+
+__all__ = ["billing_settings"]

stapel_billing-0.4.1/conftest.py

@@ -0,0 +1,108 @@
+def pytest_configure(config):
+    from django.conf import settings
+    if not settings.configured:
+        settings.configure(
+            SECRET_KEY="test-secret-key-not-for-production",
+            INSTALLED_APPS=[
+                "django.contrib.contenttypes",
+                "django.contrib.auth",
+                "django.contrib.sessions",
+                "django.contrib.messages",
+                # contrib.admin so the ModelAdmin registrations in admin.py
+                # are importable (and covered) in tests.
+                "django.contrib.admin",
+                "stapel_core.django.users",
+                "rest_framework",
+                "stapel_billing",
+            ],
+            AUTH_USER_MODEL="users.User",
+            DATABASES={
+                "default": {
+                    "ENGINE": "django.db.backends.sqlite3",
+                    "NAME": ":memory:",
+                }
+            },
+            DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+            USE_TZ=True,
+            ROOT_URLCONF="stapel_billing.tests.urls",
+            CACHES={
+                "default": {
+                    "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+                }
+            },
+            # In-memory bus — no Kafka/Redis broker needed
+            STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+            # Synchronous in-process action delivery (no outbox table needed)
+            # and schema validation ON so emits are checked against
+            # schemas/emits/*.json in tests.
+            STAPEL_COMM={
+                "OUTBOX_ENABLED": False,
+                "ACTION_TRANSPORT": "inprocess",
+                "VALIDATE_SCHEMAS": True,
+            },
+            MIDDLEWARE=[
+                "django.middleware.common.CommonMiddleware",
+                "stapel_core.django.jwt.middleware.ServiceAPIKeyMiddleware",
+            ],
+            SERVICE_API_KEY="",
+            # Checkout/portal redirect fallbacks derive from this when the
+            # request and STAPEL_BILLING don't provide URLs.
+            FRONTEND_URL="https://front.example",
+            # Skip migrations — create tables directly from models
+            MIGRATION_MODULES={
+                "users": None,
+                "billing": None,
+            },
+        )
+        import django
+        django.setup()
+
+        # Register schemas/emits/*.json with the comm registries so emit()
+        # payloads are validated against the committed contracts in tests.
+        from stapel_core.comm.schemas import autoload_schemas
+        autoload_schemas()
+
+
+import pytest  # noqa: E402
+
+
+@pytest.fixture
+def user(db):
+    from django.contrib.auth import get_user_model
+    User = get_user_model()
+    return User.objects.create_user(
+        username="testuser",
+        email="testuser@example.com",
+        password="testpass123",
+    )
+
+
+@pytest.fixture
+def api_client():
+    from rest_framework.test import APIClient
+    return APIClient()
+
+
+@pytest.fixture
+def authed_client(user):
+    from rest_framework.test import APIClient
+    client = APIClient()
+    client.force_authenticate(user=user)
+    return client
+
+
+@pytest.fixture
+def stripe_disabled(settings, monkeypatch):
+    """Disable Stripe regardless of the host environment.
+
+    Keys are read lazily through stapel_billing.conf.billing_settings, so
+    overriding the Django settings here actually takes effect at call
+    time (they are no longer frozen at import via os.getenv).  The env
+    vars are cleared too so the AppSettings env fallback cannot leak a
+    real key into the test.
+    """
+    monkeypatch.delenv("STRIPE_SECRET_KEY", raising=False)
+    monkeypatch.delenv("STRIPE_WEBHOOK_SECRET", raising=False)
+    settings.STRIPE_SECRET_KEY = ""
+    settings.STRIPE_WEBHOOK_SECRET = ""
+    return settings