simple-module-billing 0.0.8__py3-none-any.whl

sm_billing/providers/factory.py

@@ -0,0 +1,47 @@
+"""Build the configured provider from the hydrated settings.
+
+A misconfigured ``stripe`` (missing or undecryptable secrets) falls back to
+``manual`` with the reason kept on ``BillingServices.provider_error``: the app
+still boots, paid checkout stays off, and the admin screens say why.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from sm_billing import constants as c
+from sm_billing import crypto
+from sm_billing.contracts.provider import BillingProvider
+from sm_billing.providers.manual import ManualProvider
+from sm_billing.services import BillingServices
+from sm_billing.settings import BillingSettings
+
+logger = logging.getLogger(__name__)
+
+
+def build_provider(settings: BillingSettings) -> tuple[BillingProvider, str]:
+    if settings.provider != c.PROVIDER_STRIPE:
+        return ManualProvider(), ""
+    try:
+        secret = crypto.decrypt_value(settings.stripe_secret_key, "stripe_secret_key")
+        webhook = crypto.decrypt_value(settings.stripe_webhook_secret, "stripe_webhook_secret")
+    except crypto.BillingKeyUnreadableError as exc:
+        error = str(exc)
+    else:
+        missing = [
+            name
+            for name, value in (("stripe_secret_key", secret), ("stripe_webhook_secret", webhook))
+            if not value
+        ]
+        if not missing:
+            from sm_billing.providers.stripe import StripeProvider
+
+            return StripeProvider(secret_key=secret, webhook_secret=webhook), ""
+        error = f"provider is 'stripe' but {', '.join(missing)} is not set"
+    logger.error("billing: %s — falling back to the manual provider", error)
+    return ManualProvider(), error
+
+
+def install_provider(services: BillingServices) -> None:
+    """Set ``services.provider`` (and ``provider_error`` when it falls back)."""
+    services.provider, services.provider_error = build_provider(services.settings)

sm_billing/providers/manual.py

@@ -0,0 +1,60 @@
+"""``manual`` — no payment provider at all.
+
+Admins assign a plan and status on ``/admin/billing/subscriptions``, which
+writes the subscription row directly. Everything that would reach a payment
+provider refuses with ``ProviderError``; the API layer checks
+``supports_checkout`` first so tenants see "not available", not an error.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from sm_billing.constants import PROVIDER_MANUAL
+from sm_billing.contracts.provider import (
+    CheckoutSession,
+    PriceInfo,
+    ProviderError,
+    SubscriptionSnapshot,
+    WebhookEvent,
+)
+
+_NO = "The manual billing provider has no payment integration."
+
+
+class ManualProvider:
+    name = PROVIDER_MANUAL
+    supports_checkout = False
+
+    async def ensure_customer(self, tenant_id: str, name: str, email: str | None) -> str | None:
+        return None
+
+    async def create_checkout(self, **_: object) -> CheckoutSession:
+        raise ProviderError(_NO)
+
+    async def expire_checkout(self, session_id: str) -> None:
+        raise ProviderError(_NO)
+
+    async def live_subscription_ids(self, customer_id: str) -> list[str]:
+        return []
+
+    async def portal_url(self, customer_id: str, return_url: str) -> str:
+        raise ProviderError(_NO)
+
+    async def change_plan(self, subscription_id: str, price_id: str, quantity: int) -> None:
+        raise ProviderError(_NO)
+
+    async def set_quantity(self, subscription_id: str, quantity: int) -> None:
+        raise ProviderError(_NO)
+
+    async def cancel_at_period_end(self, subscription_id: str) -> None:
+        raise ProviderError(_NO)
+
+    def parse_webhook(self, body: bytes, headers: Mapping[str, str]) -> WebhookEvent:
+        raise ProviderError(_NO)
+
+    async def fetch_subscription(self, subscription_id: str) -> SubscriptionSnapshot:
+        raise ProviderError(_NO)
+
+    async def verify_price(self, price_id: str) -> PriceInfo:
+        raise ProviderError(_NO)

sm_billing/providers/stripe.py

@@ -0,0 +1,209 @@
+"""``StripeProvider`` — the ``BillingProvider`` over the official ``stripe`` SDK.
+
+Every response is turned into a plain dict (``to_dict``) at the boundary and
+mapped into the protocol's dataclasses, so nothing Stripe-shaped leaks past
+this file. SDK errors become ``ProviderError``; a bad webhook signature or
+body becomes ``InvalidWebhookSignature``.
+
+Period end is read from the subscription item when the subscription itself
+lacks it — Stripe API versions from 2025 onward moved it there.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Any
+
+import stripe
+
+from sm_billing.constants import PROVIDER_STRIPE
+from sm_billing.contracts.provider import (
+    CheckoutSession,
+    InvalidWebhookSignature,
+    PriceInfo,
+    ProviderError,
+    SubscriptionSnapshot,
+    WebhookEvent,
+)
+
+_SUBSCRIPTION_EVENTS = ("customer.subscription.",)
+_CHECKOUT_COMPLETED = "checkout.session.completed"
+# Still billing or granting access — a second checkout would double-charge.
+_LIVE_STATUSES = frozenset({"active", "trialing", "past_due", "unpaid"})
+
+
+def _ts(value: Any) -> datetime | None:
+    return datetime.fromtimestamp(int(value), UTC) if value else None
+
+
+def _id(value: Any) -> str | None:
+    """A Stripe reference: an id string, or an expanded object carrying ``id``."""
+    if isinstance(value, dict):
+        return value.get("id")
+    return value or None
+
+
+def _first_item(sub: dict) -> dict:
+    items = (sub.get("items") or {}).get("data") or []
+    if not items:
+        raise ProviderError(f"subscription {sub.get('id')} has no items")
+    return items[0]
+
+
+def snapshot_from(sub: dict) -> SubscriptionSnapshot:
+    item = _first_item(sub)
+    return SubscriptionSnapshot(
+        id=sub["id"],
+        customer_id=_id(sub.get("customer")),
+        tenant_id=(sub.get("metadata") or {}).get("tenant_id"),
+        status=sub.get("status", ""),
+        price_id=_id(item.get("price")),
+        quantity=int(item.get("quantity") or 1),
+        trial_end=_ts(sub.get("trial_end")),
+        current_period_end=_ts(sub.get("current_period_end") or item.get("current_period_end")),
+        cancel_at_period_end=bool(sub.get("cancel_at_period_end")),
+    )
+
+
+class StripeProvider:
+    name = PROVIDER_STRIPE
+    supports_checkout = True
+
+    def __init__(self, *, secret_key: str, webhook_secret: str) -> None:
+        self._client = stripe.StripeClient(secret_key, max_network_retries=2)
+        self._v1 = self._client.v1
+        self._webhook_secret = webhook_secret
+
+    async def _call(
+        self, fn, *args: Any, params: dict | None = None, options: dict | None = None
+    ) -> dict:
+        kwargs = {k: v for k, v in (("params", params), ("options", options)) if v is not None}
+        try:
+            result = await fn(*args, **kwargs)
+        except stripe.StripeError as exc:
+            raise ProviderError(exc.user_message or str(exc)) from exc
+        return result.to_dict()
+
+    async def ensure_customer(self, tenant_id: str, name: str, email: str | None) -> str | None:
+        params: dict[str, Any] = {"name": name, "metadata": {"tenant_id": tenant_id}}
+        if email:
+            params["email"] = email
+        # Keyed on the tenant and the params: the customer row is rolled back
+        # with a failed checkout, and the retry must get the same Stripe
+        # customer back (Stripe keeps idempotency keys for 24h). The params are
+        # part of the key because Stripe rejects a reused key with different
+        # params, which would block checkout for a day after a rename or when
+        # another owner retries.
+        digest = sha256(f"{name}\0{email or ''}".encode()).hexdigest()[:16]
+        options = {"idempotency_key": f"sm-billing-customer-{tenant_id}-{digest}"}
+        customer = await self._call(self._v1.customers.create_async, params=params, options=options)
+        return customer["id"]
+
+    async def create_checkout(
+        self,
+        *,
+        customer_id: str | None,
+        price_id: str,
+        quantity: int,
+        trial_days: int,
+        tenant_id: str,
+        success_url: str,
+        cancel_url: str,
+    ) -> CheckoutSession:
+        subscription_data: dict[str, Any] = {"metadata": {"tenant_id": tenant_id}}
+        if trial_days > 0:
+            subscription_data["trial_period_days"] = trial_days
+        params: dict[str, Any] = {
+            "mode": "subscription",
+            "line_items": [{"price": price_id, "quantity": quantity}],
+            "client_reference_id": tenant_id,
+            "subscription_data": subscription_data,
+            "success_url": success_url,
+            "cancel_url": cancel_url,
+        }
+        if customer_id:
+            params["customer"] = customer_id
+        session = await self._call(self._v1.checkout.sessions.create_async, params=params)
+        return CheckoutSession(id=session["id"], url=session["url"])
+
+    async def expire_checkout(self, session_id: str) -> None:
+        await self._call(self._v1.checkout.sessions.expire_async, session_id)
+
+    async def live_subscription_ids(self, customer_id: str) -> list[str]:
+        params = {"customer": customer_id, "status": "all", "limit": 100}
+        listing = await self._call(self._v1.subscriptions.list_async, params=params)
+        return [s["id"] for s in listing.get("data", []) if s.get("status") in _LIVE_STATUSES]
+
+    async def portal_url(self, customer_id: str, return_url: str) -> str:
+        params = {"customer": customer_id, "return_url": return_url}
+        session = await self._call(self._v1.billing_portal.sessions.create_async, params=params)
+        return session["url"]
+
+    async def _item_id(self, subscription_id: str) -> str:
+        sub = await self._call(self._v1.subscriptions.retrieve_async, subscription_id)
+        return _first_item(sub)["id"]
+
+    async def change_plan(self, subscription_id: str, price_id: str, quantity: int) -> None:
+        item = await self._item_id(subscription_id)
+        params = {
+            "items": [{"id": item, "price": price_id, "quantity": quantity}],
+            "proration_behavior": "create_prorations",
+            "cancel_at_period_end": False,
+        }
+        await self._call(self._v1.subscriptions.update_async, subscription_id, params=params)
+
+    async def set_quantity(self, subscription_id: str, quantity: int) -> None:
+        item = await self._item_id(subscription_id)
+        params = {
+            "items": [{"id": item, "quantity": quantity}],
+            "proration_behavior": "create_prorations",
+        }
+        await self._call(self._v1.subscriptions.update_async, subscription_id, params=params)
+
+    async def cancel_at_period_end(self, subscription_id: str) -> None:
+        params = {"cancel_at_period_end": True}
+        await self._call(self._v1.subscriptions.update_async, subscription_id, params=params)
+
+    def parse_webhook(self, body: bytes, headers: Mapping[str, str]) -> WebhookEvent:
+        signature = headers.get("stripe-signature")
+        if not signature:
+            raise InvalidWebhookSignature("missing Stripe-Signature header")
+        try:
+            event = self._client.construct_event(body, signature, self._webhook_secret).to_dict()
+        except (stripe.SignatureVerificationError, ValueError) as exc:
+            raise InvalidWebhookSignature(str(exc)) from exc
+        obj = (event.get("data") or {}).get("object") or {}
+        etype = event.get("type", "")
+        if etype == _CHECKOUT_COMPLETED:
+            return WebhookEvent(
+                id=event["id"],
+                type=etype,
+                subscription_id=_id(obj.get("subscription")),
+                tenant_id=obj.get("client_reference_id"),
+                customer_id=_id(obj.get("customer")),
+            )
+        if etype.startswith(_SUBSCRIPTION_EVENTS):
+            return WebhookEvent(
+                id=event["id"],
+                type=etype,
+                subscription_id=obj.get("id"),
+                tenant_id=(obj.get("metadata") or {}).get("tenant_id"),
+                customer_id=_id(obj.get("customer")),
+            )
+        return WebhookEvent(id=event["id"], type=etype)
+
+    async def fetch_subscription(self, subscription_id: str) -> SubscriptionSnapshot:
+        sub = await self._call(self._v1.subscriptions.retrieve_async, subscription_id)
+        return snapshot_from(sub)
+
+    async def verify_price(self, price_id: str) -> PriceInfo:
+        price = await self._call(self._v1.prices.retrieve_async, price_id)
+        recurring = price.get("recurring") or {}
+        return PriceInfo(
+            id=price["id"],
+            currency=str(price.get("currency", "")).lower(),
+            interval=recurring.get("interval"),
+            active=bool(price.get("active")),
+        )

sm_billing/reconcile.py

@@ -0,0 +1,71 @@
+"""Re-pull every provider subscription; the safety net for missed webhooks.
+
+Safe to run live and to run twice: each tenant is one fetch → ``apply_snapshot``
+→ quantity push, the same path a webhook takes. A failure for one tenant is
+recorded and the run moves on.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from simple_module_db import finalize_session
+from sqlalchemy import select
+
+from sm_billing import constants as c
+from sm_billing.models import Subscription
+from sm_billing.seats import push_quantity
+from sm_billing.services import current_provider
+from sm_billing.sync import resync
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ReconcileReport:
+    synced: int = 0
+    pushed: int = 0
+    errors: list[tuple[str, str]] = field(default_factory=list)
+    skipped: str = ""
+
+
+async def _targets(app: FastAPI, tenant_id: str | None) -> list[tuple[str, str]]:
+    async with app.state.sm.db.session_factory() as session:
+        stmt = select(Subscription.tenant_id, Subscription.provider_subscription_id).where(
+            Subscription.provider_subscription_id.is_not(None)
+        )
+        if tenant_id is not None:
+            stmt = stmt.where(Subscription.tenant_id == tenant_id)
+        return [(t, s) for t, s in (await session.execute(stmt)).all()]
+
+
+async def reconcile_one(app: FastAPI, tenant_id: str, subscription_id: str) -> bool:
+    """Sync one tenant from the provider; returns whether a quantity was pushed."""
+    provider = current_provider(app)
+    async with app.state.sm.db.session_factory() as session:
+        await resync(session, app, provider, subscription_id)
+        await finalize_session(session)
+    return await push_quantity(app, tenant_id)
+
+
+async def reconcile(app: FastAPI, *, tenant_id: str | None = None) -> ReconcileReport:
+    report = ReconcileReport()
+    provider = getattr(app.state, c.PACKAGE).provider
+    if provider is None or not provider.supports_checkout:
+        report.skipped = f"{getattr(provider, 'name', 'no')} provider"
+        return report
+    for target_tenant, subscription_id in await _targets(app, tenant_id):
+        try:
+            pushed = await reconcile_one(app, target_tenant, subscription_id)
+        except Exception as exc:
+            logger.warning("billing: reconcile failed for tenant %s", target_tenant, exc_info=True)
+            report.errors.append((target_tenant, f"{type(exc).__name__}: {exc}"))
+            continue
+        report.synced += 1
+        report.pushed += int(pushed)
+    return report

sm_billing/resolve.py

@@ -0,0 +1,30 @@
+"""Which plan is in force for a tenant.
+
+A subscription whose status is trialing, active or past_due grants its plan;
+anything else — no row, canceled, incomplete, unpaid — falls back to the
+default plan. One indexed lookup plus the default; no cache, because a
+per-process cache would go stale across workers.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sm_billing.constants import ENTITLED_STATUSES
+from sm_billing.models import Plan, Subscription
+from sm_billing.plans import PlanService
+
+
+async def subscription_for(db: AsyncSession, tenant_id: str) -> Subscription | None:
+    stmt = select(Subscription).where(Subscription.tenant_id == tenant_id)
+    return (await db.execute(stmt)).scalar_one_or_none()
+
+
+async def effective_plan(db: AsyncSession, tenant_id: str) -> tuple[Plan, Subscription | None]:
+    sub = await subscription_for(db, tenant_id)
+    if sub is not None and sub.status in ENTITLED_STATUSES:
+        plan = await db.get(Plan, sub.plan_id)
+        if plan is not None:
+            return plan, sub
+    return await PlanService(db).default(), sub

sm_billing/schemas.py

@@ -0,0 +1,222 @@
+"""Pydantic request/response models for the billing API."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel, Field, field_validator
+
+from sm_billing.constants import Interval, PricingModel, SubscriptionStatus
+
+_KEY_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+_LIMIT_KEY_RE = re.compile(r"^[a-z0-9][a-z0-9_.-]{0,99}$")
+# Stored in int4 columns (amounts, limits); keep well inside 2**31 - 1.
+MAX_AMOUNT = 2_000_000_000
+MAX_SORT_ORDER = 1_000_000
+RETURN_URL_MAX = 255
+RETURN_URL_RULE = (
+    "Return URL must be an http(s) origin such as https://app.example.com — "
+    f"no path, query or fragment, at most {RETURN_URL_MAX} characters."
+)
+_HOST_RE = re.compile(r"^[A-Za-z0-9.-]+$|^\[[0-9A-Fa-f:.]+\]$")
+_CONTROL_RE = re.compile(r"[\x00-\x20\x7f]")
+
+
+def _blank_to_none(value: str | None) -> str | None:
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+class PlanIn(BaseModel):
+    key: str
+    name: str = Field(min_length=1, max_length=120)
+    description: str = Field(default="", max_length=500)
+    pricing_model: PricingModel
+    currency: str = Field(default="eur", min_length=3, max_length=3)
+    amount_month: int | None = Field(default=None, ge=0, le=MAX_AMOUNT)
+    amount_year: int | None = Field(default=None, ge=0, le=MAX_AMOUNT)
+    stripe_price_month: str | None = Field(default=None, max_length=255)
+    stripe_price_year: str | None = Field(default=None, max_length=255)
+    trial_days: int = Field(default=0, ge=0, le=730)
+    limits: dict[str, int] = Field(default_factory=dict)
+    features: list[str] = Field(default_factory=list)
+    is_default: bool = False
+    is_public: bool = True
+    sort_order: int = Field(default=0, ge=-MAX_SORT_ORDER, le=MAX_SORT_ORDER)
+
+    @field_validator("key")
+    @classmethod
+    def _key(cls, value: str) -> str:
+        if not _KEY_RE.match(value):
+            raise ValueError("key must be 1-64 chars of a-z, 0-9, '-' or '_'")
+        return value
+
+    @field_validator("currency")
+    @classmethod
+    def _currency(cls, value: str) -> str:
+        return value.lower()
+
+    @field_validator("stripe_price_month", "stripe_price_year", mode="before")
+    @classmethod
+    def _prices(cls, value: str | None) -> str | None:
+        return _blank_to_none(value)
+
+    @field_validator("limits")
+    @classmethod
+    def _limits(cls, value: dict[str, int]) -> dict[str, int]:
+        for key, limit in value.items():
+            if not _LIMIT_KEY_RE.match(key):
+                raise ValueError(f"invalid limit key {key!r}")
+            if limit < 0:
+                raise ValueError(f"limit for {key!r} must be >= 0")
+            if limit > MAX_AMOUNT:
+                raise ValueError(f"limit for {key!r} must be <= {MAX_AMOUNT}")
+        return value
+
+    @field_validator("features")
+    @classmethod
+    def _features(cls, value: list[str]) -> list[str]:
+        cleaned = sorted({f.strip() for f in value if f.strip()})
+        for feature in cleaned:
+            if not _LIMIT_KEY_RE.match(feature):
+                raise ValueError(f"invalid feature key {feature!r}")
+        return cleaned
+
+
+class PlanOut(BaseModel):
+    """A stored plan as the API returns it.
+
+    Deliberately not a ``PlanIn`` subclass: input bounds and validators guard
+    writes, and a row stored before a bound existed must still be readable —
+    otherwise one legacy value 500s every screen that lists plans.
+    """
+
+    id: int
+    key: str
+    name: str
+    description: str
+    pricing_model: PricingModel
+    currency: str
+    amount_month: int | None
+    amount_year: int | None
+    stripe_price_month: str | None
+    stripe_price_year: str | None
+    trial_days: int
+    limits: dict[str, int]
+    features: list[str]
+    is_default: bool
+    is_public: bool
+    sort_order: int
+    archived_at: datetime | None = None
+
+
+class SubscriptionOut(BaseModel):
+    status: SubscriptionStatus | None
+    interval: Interval | None
+    quantity: int
+    trial_end: datetime | None
+    current_period_end: datetime | None
+    cancel_at_period_end: bool
+    has_provider_subscription: bool
+
+
+class StatusOut(BaseModel):
+    plan: PlanOut
+    subscription: SubscriptionOut | None
+    seats: dict[str, int | None]
+    provider: str
+    checkout_available: bool
+    portal_available: bool
+
+
+class PlanChoice(BaseModel):
+    plan_id: int
+    interval: Interval = Interval.MONTH
+
+
+class UrlOut(BaseModel):
+    url: str
+
+
+class AssignIn(BaseModel):
+    plan_id: int
+    status: SubscriptionStatus = SubscriptionStatus.ACTIVE
+    interval: Interval | None = None
+
+
+class ConnectionIn(BaseModel):
+    """Empty string = keep the stored value; ``clear_*`` wins over a value."""
+
+    stripe_secret_key: str = ""
+    stripe_webhook_secret: str = ""
+    clear_secret_key: bool = False
+    clear_webhook_secret: bool = False
+    # Validated by ``normalise_return_url`` so a bad value is a 400 with a
+    # readable message, not a raw 422.
+    return_base_url: str = ""
+
+
+def normalise_return_url(value: str) -> str:
+    """Blank, or an http(s) origin without a trailing "/". ``ValueError`` otherwise."""
+    value = value.strip()
+    if not value:
+        return ""
+    # Whitespace/control characters first: urlsplit drops \t \n \r silently,
+    # so they would pass every check below and be stored verbatim.
+    if len(value) > RETURN_URL_MAX or _CONTROL_RE.search(value):
+        raise ValueError(RETURN_URL_RULE)
+    try:
+        parts = urlsplit(value)
+        port_ok = parts.port is None or parts.port > 0
+    except ValueError as exc:
+        raise ValueError(RETURN_URL_RULE) from exc
+    netloc_host = parts.netloc.rsplit(":", 1)[0] if parts.port else parts.netloc
+    if (
+        parts.scheme.lower() not in ("http", "https")
+        or not parts.hostname
+        or "@" in parts.netloc
+        or not _HOST_RE.match(netloc_host)
+        or not port_ok
+        or parts.path not in ("", "/")
+        or parts.query
+        or parts.fragment
+        or "?" in value
+        or "#" in value
+    ):
+        raise ValueError(RETURN_URL_RULE)
+    return value.rstrip("/")
+
+
+class ConnectionOut(BaseModel):
+    provider: str
+    active_provider: str
+    provider_error: str
+    has_secret_key: bool
+    has_webhook_secret: bool
+    return_base_url: str
+    webhook_path: str
+
+
+class SubscriptionRow(BaseModel):
+    """One tenant on the admin subscriptions screen (tenants without a row too)."""
+
+    tenant_id: str
+    tenant_name: str
+    tenant_slug: str
+    tenant_status: str
+    members: int
+    plan_id: int
+    plan_key: str
+    plan_name: str
+    status: SubscriptionStatus | None
+    interval: Interval | None
+    quantity: int | None
+    current_period_end: datetime | None
+    cancel_at_period_end: bool
+    suspended_by_billing: bool
+    provider_subscription_id: str | None
+    synced_at: datetime | None