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

sm_billing/lifecycle.py

@@ -0,0 +1,74 @@
+"""What a subscription's status does to its tenant.
+
+``decide`` is the whole policy as a pure function; ``apply_lifecycle`` carries
+it out through ``TenantService.set_status`` so the tenants module publishes
+``TenantStatusChanged`` and drops its membership cache exactly as an admin
+suspension would.
+
+- trialing / active / past_due / canceled / incomplete: reactivate the tenant
+  *only if billing suspended it*. An admin's suspension is never lifted here.
+- unpaid: suspend an active tenant and remember that billing did it. A tenant
+  an admin already suspended stays theirs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from tenants.constants import TenantStatus
+from tenants.models import Tenant
+from tenants.resolver import make_invalidator
+from tenants.service import TenantService
+
+from sm_billing.constants import SubscriptionStatus
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+    from sm_billing.models import Subscription
+
+
+@dataclass(frozen=True)
+class Actions:
+    set_status: TenantStatus | None
+    suspended_by_billing: bool
+
+
+def decide(status: str, suspended_by_billing: bool, tenant_status: str) -> Actions:
+    if status == SubscriptionStatus.UNPAID:
+        if tenant_status == TenantStatus.ACTIVE:
+            return Actions(TenantStatus.SUSPENDED, True)
+        return Actions(None, suspended_by_billing)
+    if suspended_by_billing and tenant_status == TenantStatus.SUSPENDED:
+        return Actions(TenantStatus.ACTIVE, False)
+    return Actions(None, False)
+
+
+def tenant_service(db: AsyncSession, app: FastAPI) -> TenantService:
+    """A ``TenantService`` wired like ``tenants.deps.get_tenant_service``."""
+    return TenantService(
+        db,
+        bus=app.state.sm.event_bus,
+        invalidate=make_invalidator(app),
+        entitlements=app.state.tenants.entitlements,
+    )
+
+
+async def apply_lifecycle(db: AsyncSession, app: FastAPI, sub: Subscription) -> None:
+    """Apply ``decide`` to ``sub``'s tenant; flushes, never commits.
+
+    The status event is queued with ``db.on_commit`` (every framework session
+    is a ``RequestSession``), so a caller outside a request must commit with
+    ``simple_module_db.finalize_session`` — a bare ``commit()`` drops it.
+    """
+    service = tenant_service(db, app)
+    tenant = await db.get(Tenant, sub.tenant_id)
+    if tenant is None:
+        return
+    actions = decide(sub.status, sub.suspended_by_billing, tenant.status)
+    sub.suspended_by_billing = actions.suspended_by_billing
+    if actions.set_status is not None:
+        await service.set_status(tenant.id, actions.set_status)
+    await db.flush()

sm_billing/models.py

@@ -0,0 +1,112 @@
+"""SQLModel tables for the Billing module.
+
+None use ``MultiTenantMixin``: webhooks, reconcile and the admin list span
+tenants by nature — the same reasoning as ``tenants``' own tables. Each row
+that belongs to a tenant carries an explicit ``tenant_id`` and every query
+filters on it. Nothing billing-specific is added to ``tenants_tenant``.
+
+``tenant_id`` is a plain string, not a foreign key: each module owns its own
+``MetaData``, so a cross-module FK cannot resolve (``tenants`` stores
+``user_id`` the same way). Deleting a tenant therefore leaves its billing rows
+behind — see the README's tenant-deletion note.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin
+from sqlalchemy import JSON, Column, DateTime, Text
+from sqlmodel import Field
+
+from sm_billing.constants import SubscriptionStatus
+
+Base = create_module_base("billing")
+
+_TENANT_ID_LEN = 32  # tenants: uuid4().hex
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+def _tz_column(*, nullable: bool = True) -> Column:
+    return Column(DateTime(timezone=True), nullable=nullable)
+
+
+class Plan(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """A sellable plan. Archived, never deleted, so subscriptions keep a valid plan."""
+
+    __tablename__ = "billing_plan"
+
+    id: int | None = Field(default=None, primary_key=True)
+    key: str = Field(max_length=64, unique=True, index=True)
+    name: str = Field(max_length=120)
+    description: str = Field(default="", max_length=500)
+    pricing_model: str = Field(max_length=20)
+    currency: str = Field(default="eur", max_length=3)
+    # Minor units, display only — Stripe charges what the price says.
+    amount_month: int | None = Field(default=None)
+    amount_year: int | None = Field(default=None)
+    stripe_price_month: str | None = Field(default=None, max_length=255, unique=True)
+    stripe_price_year: str | None = Field(default=None, max_length=255, unique=True)
+    trial_days: int = Field(default=0)
+    # {entitlement key: int}; an absent key is unlimited, 0 forbids.
+    limits: dict = Field(default_factory=dict, sa_column=Column(JSON, nullable=False))
+    features: list = Field(default_factory=list, sa_column=Column(JSON, nullable=False))
+    is_default: bool = Field(default=False)
+    is_public: bool = Field(default=True)
+    sort_order: int = Field(default=0)
+    archived_at: datetime | None = Field(default=None, sa_column=_tz_column())
+
+
+class Customer(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """The tenant's identity at the payment provider. Created at first checkout."""
+
+    __tablename__ = "billing_customer"
+
+    tenant_id: str = Field(primary_key=True, max_length=_TENANT_ID_LEN)
+    provider: str = Field(max_length=20)
+    provider_customer_id: str | None = Field(default=None, max_length=255, unique=True, index=True)
+    email: str | None = Field(default=None, max_length=320)
+    # The one open Checkout session, expired when a new one is started so two
+    # tabs cannot both be paid into two subscriptions.
+    checkout_session_id: str | None = Field(default=None, max_length=255)
+
+
+class Subscription(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """A tenant's one current subscription — the local mirror of the provider's."""
+
+    __tablename__ = "billing_subscription"
+
+    id: int | None = Field(default=None, primary_key=True)
+    tenant_id: str = Field(max_length=_TENANT_ID_LEN, unique=True, index=True)
+    plan_id: int = Field(foreign_key="billing_plan.id")
+    status: str = Field(default=SubscriptionStatus.ACTIVE, max_length=20, index=True)
+    interval: str | None = Field(default=None, max_length=10)
+    provider_subscription_id: str | None = Field(
+        default=None, max_length=255, unique=True, index=True
+    )
+    quantity: int = Field(default=1)
+    trial_end: datetime | None = Field(default=None, sa_column=_tz_column())
+    current_period_end: datetime | None = Field(default=None, sa_column=_tz_column())
+    cancel_at_period_end: bool = Field(default=False)
+    # Billing only ever reactivates a tenant it suspended itself.
+    suspended_by_billing: bool = Field(default=False)
+    synced_at: datetime | None = Field(default=None, sa_column=_tz_column())
+
+
+class WebhookEvent(Base, table=True):  # ty: ignore[unsupported-base]
+    """One row per provider event id: idempotency and an audit trail."""
+
+    __tablename__ = "billing_webhook_event"
+
+    id: str = Field(primary_key=True, max_length=255)
+    provider: str = Field(max_length=20)
+    type: str = Field(max_length=100)
+    received_at: datetime = Field(
+        default_factory=_utcnow, sa_column=Column(DateTime(timezone=True), nullable=False)
+    )
+    processed_at: datetime | None = Field(default=None, sa_column=_tz_column())
+    error: str | None = Field(default=None, sa_column=Column(Text, nullable=True))

sm_billing/module.py

@@ -0,0 +1,132 @@
+"""Billing — plans, subscriptions and payment for tenants.
+
+Plugs into the seams ``simple_module_tenants`` exposes and changes none of
+them: it installs ``PlanEntitlements`` as ``app.state.tenants.entitlements``
+(so the seat limit ``tenants`` already enforces comes from the tenant's plan),
+reacts to membership events to keep per-seat quantities in step, and drives
+``TenantService.set_status`` when a subscription stops being paid.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.metadata
+import logging
+import weakref
+from typing import TYPE_CHECKING
+
+from simple_module_core import ModuleBase, ModuleMeta
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+
+from sm_billing import constants as c
+
+if TYPE_CHECKING:
+    from fastapi import APIRouter, FastAPI
+    from simple_module_core.events import EventBus
+    from simple_module_core.permissions import PermissionRegistry
+    from simple_module_core.public_routes import PublicRouteRegistry
+
+logger = logging.getLogger(__name__)
+
+_VERSION = importlib.metadata.version("simple_module_billing")
+
+
+class BillingModule(ModuleBase):
+    meta = ModuleMeta(
+        name=c.MODULE_NAME,
+        route_prefix=c.ROUTE_PREFIX_API,
+        view_prefix=c.VIEW_PREFIX,
+        admin_view_prefix=c.ADMIN_VIEW_PREFIX,
+        depends_on=[c._MODULE_TENANTS, c._MODULE_SETTINGS],
+        version=_VERSION,
+        # The framework API version (1.0.0) is decoupled from the framework
+        # package version (0.0.x) — this range is correct as written.
+        requires_framework=">=1.0,<2.0",
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        from sm_billing import crypto
+        from sm_billing.services import BillingServices
+        from sm_billing.settings import BillingSettings
+
+        register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+        register_module_settings(
+            app, c.PACKAGE, BillingSettings, lambda s: BillingServices(settings=s)
+        )
+
+        # Encrypt under the secret the running app holds (hosts may inject it
+        # programmatically). Through a weakref: the provider is process-global
+        # and a strong closure would keep discarded test apps alive.
+        app_ref = weakref.ref(app)
+
+        def _live_secret() -> str:
+            live_app = app_ref()
+            sm = getattr(getattr(live_app, "state", None), "sm", None)
+            return getattr(getattr(sm, "settings", None), "secret_key", "") or ""
+
+        crypto.set_secret_provider(_live_secret)
+
+    def register_exception_handlers(self, app: FastAPI) -> None:
+        from sm_billing.errors import install_exception_handlers
+
+        install_exception_handlers(app)
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(
+            c.MODULE_NAME,
+            [c.PERM_VIEW, c.PERM_MANAGE, c.PERM_PLATFORM_VIEW, c.PERM_PLATFORM_MANAGE],
+        )
+        registry.map_role(c.ROLE_TENANT_OWNER, [c.PERM_VIEW, c.PERM_MANAGE])
+        registry.map_role(c.ROLE_TENANT_ADMIN, [c.PERM_VIEW])
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add_many(
+            [
+                MenuItem(
+                    label=c.MENU_LABEL,
+                    url=c.MENU_URL,
+                    icon=c.MENU_ICON,
+                    order=c.MENU_ORDER,
+                    section=MenuSection.SIDEBAR,
+                    permissions=[c.PERM_VIEW],
+                ),
+                MenuItem(
+                    label=c.ADMIN_MENU_LABEL,
+                    url=c.ADMIN_MENU_URL,
+                    icon=c.MENU_ICON,
+                    order=c.MENU_ORDER,
+                    section=MenuSection.ADMIN_SIDEBAR,
+                    permissions=[c.PERM_PLATFORM_VIEW],
+                    group=c.ADMIN_MENU_GROUP,
+                    group_key=c.ADMIN_MENU_GROUP_KEY,
+                ),
+            ]
+        )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from sm_billing.endpoints import routers
+
+        routers.include(api_router, view_router)
+
+    def register_admin_routes(self, admin_router: APIRouter) -> None:
+        from sm_billing.endpoints import routers
+
+        routers.include_admin(admin_router)
+
+    def register_public_routes(self, registry: PublicRouteRegistry) -> None:
+        # Stripe calls this unauthenticated; the signature is the auth.
+        registry.add_exact(c.WEBHOOK_PATH, methods={"POST"})
+
+    def register_event_handlers(self, bus: EventBus, app: FastAPI | None = None) -> None:
+        if app is None:
+            return
+        from sm_billing import seats
+
+        seats.subscribe(bus, app)
+
+    async def on_startup(self, app: FastAPI) -> None:
+        from sm_billing import startup
+
+        await startup.run(app)

sm_billing/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@simple-module-py/billing",
+  "version": "0.0.8",
+  "private": true,
+  "description": "Frontend assets for the Billing module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^3.7.0",
+    "@simple-module-py/ui": "*",
+    "sonner": "^2.0.0"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {}
+}

sm_billing/pages/Billing.tsx

@@ -0,0 +1,201 @@
+import { Head, router, usePage } from '@inertiajs/react';
+import { ConfirmActionDialog } from '@simple-module-py/ui/components/ConfirmActionDialog';
+import { InlineBanner } from '@simple-module-py/ui/components/InlineBanner';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { SegmentedControl } from '@simple-module-py/ui/components/SegmentedControl';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import { ArrowRightLeft, Info, Loader2, Lock } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { toast } from 'sonner';
+import { CurrentPlanCard } from '../components/CurrentPlanCard';
+import { PlanCard } from '../components/PlanCard';
+import { useCheckoutPolling } from '../hooks/useCheckoutPolling';
+import { api, BILLING_API } from '../utils/api';
+import { type PlanCta, planCta, priceLabel } from '../utils/format';
+import type { Interval, Plan, Status } from '../utils/types';
+
+interface Props {
+  status: Status;
+  plans: Plan[];
+  can_manage: boolean;
+  /** Suspended for non-payment: paying is the only thing offered. */
+  restore: boolean;
+  csrf_token: string;
+  checkout: string;
+}
+
+function Billing() {
+  const { status, plans, can_manage, restore, csrf_token, checkout } = usePage<{
+    props: Props;
+  }>().props as unknown as Props;
+  const [interval, setBillingInterval] = useState<Interval>(
+    status.subscription?.interval ?? 'month',
+  );
+  const [busy, setBusy] = useState(false);
+  const [pending, setPending] = useState<{ plan: Plan; cta: PlanCta } | null>(null);
+  const reload = useCallback(() => router.reload(), []);
+  const polling = useCheckoutPolling(checkout === 'success', csrf_token, reload);
+  const sellsYearly = plans.some((p) => p.stripe_price_year);
+
+  async function run(work: () => Promise<void>) {
+    setBusy(true);
+    try {
+      await work();
+    } catch (err) {
+      toast.error((err as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const openPortal = () =>
+    run(async () => {
+      const { url } = await api<{ url: string }>(`${BILLING_API}/portal`, csrf_token, {
+        body: {},
+      });
+      window.location.assign(url);
+    });
+
+  function choose(plan: Plan, cta: PlanCta) {
+    if (cta === 'checkout') {
+      void run(async () => {
+        const { url } = await api<{ url: string }>(`${BILLING_API}/checkout`, csrf_token, {
+          body: { plan_id: plan.id, interval },
+        });
+        window.location.assign(url);
+      });
+      return;
+    }
+    setPending({ plan, cta });
+  }
+
+  const confirmChange = () =>
+    run(async () => {
+      if (!pending) return;
+      await api<Status>(`${BILLING_API}/change-plan`, csrf_token, {
+        body: { plan_id: pending.plan.id, interval },
+      });
+      toast.success(
+        pending.cta === 'downgrade'
+          ? 'Your plan ends at the end of the billing period.'
+          : `Switched to ${pending.plan.name}.`,
+      );
+      setPending(null);
+      reload();
+    });
+
+  return (
+    <>
+      <Head title="Billing" />
+      <PageShell title="Billing" description="Your organisation's plan, seats and payment.">
+        <div className="space-y-8">
+          {polling === 'waiting' && (
+            <InlineBanner
+              icon={Loader2}
+              title="Activating your subscription…"
+              description="Stripe confirmed the payment; this page updates once it reaches us."
+            />
+          )}
+          {polling === 'timeout' && (
+            <InlineBanner
+              icon={Info}
+              tone="warning"
+              title="Still waiting for Stripe"
+              description="Your payment went through, but the confirmation is late. Refresh in a minute."
+            />
+          )}
+          {checkout === 'cancel' && (
+            <InlineBanner icon={Info} title="Checkout cancelled — nothing was charged." />
+          )}
+          {restore && (
+            <InlineBanner
+              icon={Lock}
+              tone="warning"
+              title="This organisation is suspended for non-payment"
+              description={
+                status.portal_available
+                  ? 'Update your payment method and settle any open invoice; access returns as soon as Stripe confirms the payment.'
+                  : 'Contact the site administrator to restore access.'
+              }
+              action={
+                status.portal_available ? (
+                  <Button size="sm" onClick={openPortal} disabled={busy}>
+                    Pay now
+                  </Button>
+                ) : undefined
+              }
+            />
+          )}
+          <CurrentPlanCard
+            status={status}
+            canManage={can_manage || restore}
+            busy={busy}
+            onPortal={openPortal}
+          />
+
+          <section className="space-y-4" hidden={restore}>
+            <div className="flex flex-wrap items-center justify-between gap-3">
+              <h2 className="text-lg font-semibold">Plans</h2>
+              {sellsYearly && (
+                <SegmentedControl
+                  aria-label="Billing period"
+                  value={interval}
+                  onChange={setBillingInterval}
+                  options={[
+                    { value: 'month', label: 'Monthly' },
+                    { value: 'year', label: 'Yearly' },
+                  ]}
+                />
+              )}
+            </div>
+            {!can_manage && (
+              <p className="text-sm text-muted-foreground">
+                Only the organisation owner can change the plan.
+              </p>
+            )}
+            {!status.checkout_available && can_manage && (
+              <p className="text-sm text-muted-foreground">
+                Online payment is not set up here — contact the site administrator to change plan.
+              </p>
+            )}
+            <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+              {plans.map((plan) => (
+                <PlanCard
+                  key={plan.id}
+                  plan={plan}
+                  interval={interval}
+                  cta={planCta(status, plan, interval)}
+                  canManage={can_manage}
+                  busy={busy}
+                  onChoose={choose}
+                />
+              ))}
+            </div>
+          </section>
+        </div>
+      </PageShell>
+      <ConfirmActionDialog
+        open={pending !== null}
+        onOpenChange={(open) => !open && setPending(null)}
+        tone="primary"
+        icon={ArrowRightLeft}
+        title={pending?.cta === 'downgrade' ? 'Downgrade to the free plan?' : 'Change plan?'}
+        description={
+          pending?.cta === 'downgrade'
+            ? 'Your paid plan stays active until the end of the current period, then ends.'
+            : `You will be moved to ${pending?.plan.name} (${
+                pending ? priceLabel(pending.plan, interval) : ''
+              }). Stripe prorates the difference on your next invoice.`
+        }
+        confirmLabel={pending?.cta === 'downgrade' ? 'Downgrade' : 'Change plan'}
+        cancelLabel="Keep current plan"
+        busy={busy}
+        onConfirm={confirmChange}
+      />
+    </>
+  );
+}
+
+Billing.layout = [AuthenticatedLayout];
+export default Billing;