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

sm_billing/components/PlanEditor.tsx

@@ -0,0 +1,213 @@
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Checkbox } from '@simple-module-py/ui/components/ui/checkbox';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@simple-module-py/ui/components/ui/dialog';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { Label } from '@simple-module-py/ui/components/ui/label';
+import { NativeSelect, NativeSelectOption } from '@simple-module-py/ui/components/ui/native-select';
+import { Textarea } from '@simple-module-py/ui/components/ui/textarea';
+import type React from 'react';
+import { useEffect, useState } from 'react';
+import {
+  emptyPlanForm,
+  formFromPlan,
+  MAX_DESCRIPTION,
+  MAX_NAME,
+  type PlanForm,
+  validatePlanForm,
+  withPricingModel,
+} from '../utils/plan-form';
+import type { Plan, PricingModel } from '../utils/types';
+import { LimitRows } from './LimitRows';
+
+interface Props {
+  open: boolean;
+  plan: Plan | null;
+  knownKeys: string[];
+  busy: boolean;
+  /** A rejection from the API, shown in the dialog's alert area. */
+  serverError?: string | null;
+  onOpenChange: (open: boolean) => void;
+  onSave: (form: PlanForm) => void;
+}
+
+function Field({ id, label, children }: { id: string; label: string; children: React.ReactNode }) {
+  return (
+    <div className="space-y-1.5">
+      <Label htmlFor={id}>{label}</Label>
+      {children}
+    </div>
+  );
+}
+
+export function PlanEditor({
+  open,
+  plan,
+  knownKeys,
+  busy,
+  serverError = null,
+  onOpenChange,
+  onSave,
+}: Props) {
+  const [form, setForm] = useState<PlanForm>(emptyPlanForm());
+  const [error, setError] = useState<string | null>(null);
+  useEffect(() => {
+    if (open) {
+      setForm(plan ? formFromPlan(plan) : emptyPlanForm());
+      setError(null);
+    }
+  }, [open, plan]);
+
+  const set = <K extends keyof PlanForm>(key: K, value: PlanForm[K]) =>
+    setForm((f) => ({ ...f, [key]: value }));
+  const text = (key: keyof PlanForm) => (e: React.ChangeEvent<HTMLInputElement>) =>
+    set(key, e.target.value as never);
+  const paid = form.pricing_model !== 'free';
+
+  function submit(e: React.FormEvent) {
+    e.preventDefault();
+    if (busy) return;
+    const problem = validatePlanForm(form);
+    setError(problem);
+    if (!problem) onSave(form);
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-h-[90vh] overflow-y-auto sm:max-w-2xl">
+        <form onSubmit={submit} className="space-y-5">
+          <DialogHeader>
+            <DialogTitle>{plan ? `Edit ${plan.name}` : 'New plan'}</DialogTitle>
+            <DialogDescription>
+              Limits and features decide what a tenant may do; Stripe prices decide what they pay.
+            </DialogDescription>
+          </DialogHeader>
+          <div className="grid gap-4 sm:grid-cols-2">
+            <Field id="plan-key" label="Key">
+              <Input id="plan-key" value={form.key} onChange={text('key')} disabled={!!plan} />
+            </Field>
+            <Field id="plan-name" label="Name">
+              <Input
+                id="plan-name"
+                value={form.name}
+                maxLength={MAX_NAME}
+                onChange={text('name')}
+              />
+            </Field>
+            <Field id="plan-model" label="Pricing">
+              <NativeSelect
+                id="plan-model"
+                value={form.pricing_model}
+                onChange={(e) =>
+                  setForm((f) => withPricingModel(f, e.target.value as PricingModel))
+                }
+              >
+                <NativeSelectOption value="free">Free</NativeSelectOption>
+                <NativeSelectOption value="flat">Flat price</NativeSelectOption>
+                <NativeSelectOption value="per_seat">Per seat</NativeSelectOption>
+              </NativeSelect>
+            </Field>
+            <Field id="plan-currency" label="Currency">
+              <Input id="plan-currency" value={form.currency} onChange={text('currency')} />
+            </Field>
+            {paid && (
+              <>
+                <Field id="plan-price-m" label="Stripe price ID (monthly)">
+                  <Input
+                    id="plan-price-m"
+                    placeholder="price_…"
+                    value={form.stripe_price_month}
+                    onChange={text('stripe_price_month')}
+                  />
+                </Field>
+                <Field id="plan-amount-m" label="Monthly amount (display)">
+                  <Input
+                    id="plan-amount-m"
+                    value={form.amount_month}
+                    onChange={text('amount_month')}
+                  />
+                </Field>
+                <Field id="plan-price-y" label="Stripe price ID (yearly)">
+                  <Input
+                    id="plan-price-y"
+                    placeholder="price_…"
+                    value={form.stripe_price_year}
+                    onChange={text('stripe_price_year')}
+                  />
+                </Field>
+                <Field id="plan-amount-y" label="Yearly amount (display)">
+                  <Input
+                    id="plan-amount-y"
+                    value={form.amount_year}
+                    onChange={text('amount_year')}
+                  />
+                </Field>
+                <Field id="plan-trial" label="Trial days">
+                  <Input id="plan-trial" value={form.trial_days} onChange={text('trial_days')} />
+                </Field>
+              </>
+            )}
+            <Field id="plan-order" label="Sort order">
+              <Input id="plan-order" value={form.sort_order} onChange={text('sort_order')} />
+            </Field>
+          </div>
+          <Field id="plan-description" label="Description">
+            <Textarea
+              id="plan-description"
+              value={form.description}
+              maxLength={MAX_DESCRIPTION}
+              onChange={(e) => set('description', e.target.value)}
+            />
+          </Field>
+          <div className="space-y-1.5">
+            <Label>Limits</Label>
+            <LimitRows
+              rows={form.limits}
+              knownKeys={knownKeys}
+              onChange={(r) => set('limits', r)}
+            />
+          </div>
+          <Field id="plan-features" label="Features (comma separated)">
+            <Input id="plan-features" value={form.features} onChange={text('features')} />
+          </Field>
+          <div className="flex flex-wrap gap-6">
+            <Label className="flex items-center gap-2">
+              <Checkbox
+                checked={form.is_public}
+                onCheckedChange={(v) => set('is_public', v === true)}
+              />
+              Shown to tenants
+            </Label>
+            <Label className="flex items-center gap-2">
+              <Checkbox
+                checked={form.is_default}
+                disabled={paid}
+                onCheckedChange={(v) => set('is_default', v === true)}
+              />
+              Default plan for new organisations
+            </Label>
+          </div>
+          {(error ?? serverError) && (
+            <p role="alert" className="text-sm text-destructive">
+              {error ?? serverError}
+            </p>
+          )}
+          <DialogFooter>
+            <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>
+              Cancel
+            </Button>
+            <Button type="submit" disabled={busy}>
+              {plan ? 'Save plan' : 'Create plan'}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

sm_billing/components/PlansTable.tsx

@@ -0,0 +1,78 @@
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@simple-module-py/ui/components/ui/table';
+import { priceLabel } from '../utils/format';
+import type { Plan } from '../utils/types';
+
+interface Props {
+  plans: Plan[];
+  canManage: boolean;
+  onEdit: (plan: Plan) => void;
+  onArchive: (plan: Plan) => void;
+}
+
+const MODEL: Record<Plan['pricing_model'], string> = {
+  free: 'Free',
+  flat: 'Flat',
+  per_seat: 'Per seat',
+};
+
+export function PlansTable({ plans, canManage, onEdit, onArchive }: Props) {
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Plan</TableHead>
+          <TableHead>Pricing</TableHead>
+          <TableHead>Price</TableHead>
+          <TableHead>Seats</TableHead>
+          <TableHead className="text-right">Actions</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {plans.map((plan) => (
+          <TableRow key={plan.id} className={plan.archived_at ? 'opacity-60' : undefined}>
+            <TableCell>
+              <div className="flex flex-wrap items-center gap-2 font-medium">
+                {plan.name}
+                {plan.is_default && <Badge>Default</Badge>}
+                {!plan.is_public && <Badge variant="outline">Hidden</Badge>}
+                {plan.archived_at && <Badge variant="secondary">Archived</Badge>}
+              </div>
+              <div className="font-mono text-xs text-muted-foreground">{plan.key}</div>
+            </TableCell>
+            <TableCell>{MODEL[plan.pricing_model]}</TableCell>
+            <TableCell className="text-sm">
+              {priceLabel(plan, 'month')}
+              {plan.stripe_price_year && (
+                <div className="text-muted-foreground">{priceLabel(plan, 'year')}</div>
+              )}
+            </TableCell>
+            <TableCell>{plan.limits['tenants.seats'] ?? 'Unlimited'}</TableCell>
+            <TableCell className="text-right">
+              {canManage && !plan.archived_at && (
+                <div className="flex justify-end gap-2">
+                  <Button size="sm" variant="outline" onClick={() => onEdit(plan)}>
+                    Edit
+                  </Button>
+                  {!plan.is_default && (
+                    <Button size="sm" variant="ghost" onClick={() => onArchive(plan)}>
+                      Archive
+                    </Button>
+                  )}
+                </div>
+              )}
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}

sm_billing/components/StatusBadge.tsx

@@ -0,0 +1,7 @@
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { statusLabel, statusTone } from '../utils/format';
+import type { SubscriptionStatus } from '../utils/types';
+
+export function StatusBadge({ status }: { status: SubscriptionStatus | null }) {
+  return <Badge variant={statusTone(status)}>{statusLabel(status)}</Badge>;
+}

sm_billing/components/SubscriptionsTable.tsx

@@ -0,0 +1,86 @@
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@simple-module-py/ui/components/ui/table';
+import { formatDate } from '../utils/format';
+import type { SubscriptionRow } from '../utils/types';
+import { StatusBadge } from './StatusBadge';
+
+interface Props {
+  rows: SubscriptionRow[];
+  canManage: boolean;
+  /** Stripe: resync from the provider. Manual: assign a plan by hand. */
+  mode: 'resync' | 'assign';
+  busy: boolean;
+  onResync: (row: SubscriptionRow) => void;
+  onAssign: (row: SubscriptionRow) => void;
+}
+
+export function SubscriptionsTable({ rows, canManage, mode, busy, onResync, onAssign }: Props) {
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Organisation</TableHead>
+          <TableHead>Plan</TableHead>
+          <TableHead>Status</TableHead>
+          <TableHead>Members</TableHead>
+          <TableHead>Period end</TableHead>
+          <TableHead className="text-right">Actions</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {rows.map((row) => (
+          <TableRow key={row.tenant_id}>
+            <TableCell>
+              <div className="flex flex-wrap items-center gap-2 font-medium">
+                {row.tenant_name}
+                {row.tenant_status === 'suspended' && (
+                  <Badge variant="destructive">
+                    {row.suspended_by_billing ? 'Suspended (unpaid)' : 'Suspended'}
+                  </Badge>
+                )}
+              </div>
+              <div className="font-mono text-xs text-muted-foreground">{row.tenant_slug}</div>
+            </TableCell>
+            <TableCell>
+              {row.plan_name}
+              {row.interval && <span className="text-muted-foreground"> · {row.interval}ly</span>}
+            </TableCell>
+            <TableCell>
+              <StatusBadge status={row.status} />
+              {row.cancel_at_period_end && (
+                <div className="mt-1 text-xs text-muted-foreground">Ends at period end</div>
+              )}
+            </TableCell>
+            <TableCell>
+              {row.members}
+              {row.quantity !== null && row.quantity !== row.members && (
+                <span className="text-xs text-muted-foreground"> (billed {row.quantity})</span>
+              )}
+            </TableCell>
+            <TableCell>{formatDate(row.current_period_end) || '—'}</TableCell>
+            <TableCell className="text-right">
+              {canManage && mode === 'assign' && (
+                <Button size="sm" variant="outline" disabled={busy} onClick={() => onAssign(row)}>
+                  Assign plan
+                </Button>
+              )}
+              {canManage && mode === 'resync' && row.provider_subscription_id && (
+                <Button size="sm" variant="outline" disabled={busy} onClick={() => onResync(row)}>
+                  Resync
+                </Button>
+              )}
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}

sm_billing/constants.py

@@ -0,0 +1,112 @@
+"""Billing module constants.
+
+Kept out of the call sites so no module name, route, permission or page
+appears as a bare literal — see scripts/check_hardcoded_strings.py.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final
+
+PACKAGE: Final = "sm_billing"
+MODULE_NAME: Final = "Billing"
+
+ROUTE_PREFIX_API: Final = "/api/billing"
+VIEW_PREFIX: Final = "/billing"
+ADMIN_VIEW_PREFIX: Final = "/admin/billing"
+WEBHOOK_PATH: Final = "/billing/webhooks/stripe"
+
+# Modules this one depends on (value = that module's ModuleMeta.name).
+_MODULE_TENANTS: Final = "Tenants"
+_MODULE_SETTINGS: Final = "Settings"
+
+# ── Permissions ──────────────────────────────────────────────────────
+PERM_VIEW: Final = "billing.view"
+PERM_MANAGE: Final = "billing.manage"
+PERM_PLATFORM_VIEW: Final = "billing.platform.view"
+PERM_PLATFORM_MANAGE: Final = "billing.platform.manage"
+
+# Tenant roles as the tenants resolver appends them to the principal
+# (``tenants.constants.TENANT_ROLE_PREFIX`` + role) for the active tenant only.
+ROLE_TENANT_OWNER: Final = "tenant:owner"
+ROLE_TENANT_ADMIN: Final = "tenant:admin"
+TENANT_ROLE_OWNER: Final = "owner"
+
+# ── Inertia pages (pinned to files under pages/ by a test) ───────────
+_PAGE_BILLING: Final = f"{MODULE_NAME}/Billing"
+_PAGE_PLANS: Final = f"{MODULE_NAME}/Plans"
+_PAGE_SUBSCRIPTIONS: Final = f"{MODULE_NAME}/Subscriptions"
+_PAGE_CONNECTION: Final = f"{MODULE_NAME}/Connection"
+
+# ── Menu ─────────────────────────────────────────────────────────────
+MENU_LABEL: Final = "Billing"
+MENU_URL: Final = f"{VIEW_PREFIX}/"
+MENU_ICON: Final = "credit-card"
+MENU_ORDER: Final = 95  # just after Organisations (90)
+ADMIN_MENU_LABEL: Final = "Billing"
+ADMIN_MENU_URL: Final = f"{ADMIN_VIEW_PREFIX}/subscriptions"
+ADMIN_MENU_GROUP: Final = "Access"
+ADMIN_MENU_GROUP_KEY: Final = "ui.nav_groups.access"
+
+# ── Providers (stored values) ────────────────────────────────────────
+PROVIDER_MANUAL: Final = "manual"
+PROVIDER_STRIPE: Final = "stripe"
+PROVIDERS: Final = (PROVIDER_MANUAL, PROVIDER_STRIPE)
+
+# ── Entitlement keys this module knows about (suggestions in the editor)
+ENTITLEMENT_SEATS: Final = "tenants.seats"
+KNOWN_LIMIT_KEYS: Final = (ENTITLEMENT_SEATS,)
+
+DEFAULT_PLAN_KEY: Final = "free"
+DEFAULT_PLAN_NAME: Final = "Free"
+
+SECRET_FIELDS: Final = frozenset({"stripe_secret_key", "stripe_webhook_secret"})
+
+
+class PricingModel(StrEnum):
+    FREE = "free"
+    FLAT = "flat"
+    PER_SEAT = "per_seat"
+
+
+class Interval(StrEnum):
+    MONTH = "month"
+    YEAR = "year"
+
+
+class SubscriptionStatus(StrEnum):
+    TRIALING = "trialing"
+    ACTIVE = "active"
+    PAST_DUE = "past_due"
+    UNPAID = "unpaid"
+    CANCELED = "canceled"
+    INCOMPLETE = "incomplete"
+
+
+#: Statuses whose plan is in force; everything else resolves to the default plan.
+ENTITLED_STATUSES: Final = frozenset(
+    {SubscriptionStatus.TRIALING, SubscriptionStatus.ACTIVE, SubscriptionStatus.PAST_DUE}
+)
+
+#: Stripe statuses we fold onto ours (``incomplete_expired`` never paid).
+STRIPE_STATUS_MAP: Final = {
+    "trialing": SubscriptionStatus.TRIALING,
+    "active": SubscriptionStatus.ACTIVE,
+    "past_due": SubscriptionStatus.PAST_DUE,
+    "unpaid": SubscriptionStatus.UNPAID,
+    "canceled": SubscriptionStatus.CANCELED,
+    "incomplete": SubscriptionStatus.INCOMPLETE,
+    "incomplete_expired": SubscriptionStatus.CANCELED,
+    "paused": SubscriptionStatus.UNPAID,
+}
+
+#: Webhook event types that trigger a subscription re-fetch.
+HANDLED_EVENTS: Final = frozenset(
+    {
+        "checkout.session.completed",
+        "customer.subscription.created",
+        "customer.subscription.updated",
+        "customer.subscription.deleted",
+    }
+)

sm_billing/context.py

@@ -0,0 +1,68 @@
+"""Which tenant a billing request is about — including one billing suspended.
+
+The tenants resolver never makes a suspended organisation the active tenant,
+which is right everywhere except here: the owner of an organisation billing
+suspended for non-payment has to reach the Customer Portal to pay, or the
+suspension can never be lifted from inside the app. So when the session's
+chosen organisation is suspended *by billing* and the user owns it, billing
+opens it in **restore** mode — status and portal only, never checkout or plan
+changes. An organisation an admin suspended stays closed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from fastapi import Request
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from tenants.constants import SESSION_ACTIVE_TENANT, TenantStatus
+from tenants.models import Membership, Tenant
+
+from sm_billing import constants as c
+from sm_billing.resolve import subscription_for
+
+
+@dataclass(frozen=True)
+class BillingContext:
+    tenant_id: str
+    role: str
+    restore: bool = False
+
+
+async def _restorable(request: Request, db: AsyncSession) -> BillingContext | None:
+    if not getattr(request.state, "tenant_suspended", False):
+        return None
+    user = getattr(request.state, "user", None)
+    session = request.scope.get("session")
+    chosen = session.get(SESSION_ACTIVE_TENANT) if session is not None else None
+    if user is None or not chosen:
+        return None
+    stmt = select(Membership.role).where(
+        Membership.tenant_id == chosen, Membership.user_id == str(user.id)
+    )
+    if (await db.execute(stmt)).scalar_one_or_none() != c.TENANT_ROLE_OWNER:
+        return None
+    tenant = await db.get(Tenant, chosen)
+    if tenant is None or tenant.status != TenantStatus.SUSPENDED:
+        return None
+    sub = await subscription_for(db, chosen)
+    if sub is None or not sub.suspended_by_billing:
+        return None
+    return BillingContext(tenant_id=chosen, role=c.TENANT_ROLE_OWNER, restore=True)
+
+
+async def billing_context(request: Request, db: AsyncSession) -> BillingContext | None:
+    """The organisation this request bills, or ``None`` (pick one first).
+
+    The chosen-but-suspended organisation wins over the resolver's fallback:
+    it is the one the user asked for, and the one that needs paying.
+    """
+    restore = await _restorable(request, db)
+    if restore is not None:
+        return restore
+    tenant_id = getattr(request.state, "tenant_id", None)
+    role = getattr(request.state, "tenant_role", None)
+    if tenant_id is None or role is None:
+        return None
+    return BillingContext(tenant_id=tenant_id, role=role)

sm_billing/contracts/provider.py

@@ -0,0 +1,107 @@
+"""The payment-provider seam.
+
+Billing speaks to Stripe (or nothing, for ``manual``) only through this
+protocol, in plain dataclasses — no provider SDK object crosses it, so the
+sync, webhook and checkout code is testable with a scripted fake and a second
+provider would be a new class, not a refactor.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Protocol, runtime_checkable
+
+
+class ProviderError(Exception):
+    """The provider refused or failed a call (network, auth, unknown object)."""
+
+
+class InvalidWebhookSignature(ProviderError):  # noqa: N818 - reads as the condition
+    """The webhook body does not carry a valid signature → HTTP 400."""
+
+
+@dataclass(frozen=True)
+class WebhookEvent:
+    id: str
+    type: str
+    subscription_id: str | None = None
+    tenant_id: str | None = None
+    customer_id: str | None = None
+
+
+@dataclass(frozen=True)
+class SubscriptionSnapshot:
+    """The provider's current view of one subscription, already normalised.
+
+    ``status`` is the provider's raw status string; ``sync`` maps it.
+    """
+
+    id: str
+    customer_id: str | None
+    tenant_id: str | None
+    status: str
+    price_id: str | None
+    quantity: int
+    trial_end: datetime | None
+    current_period_end: datetime | None
+    cancel_at_period_end: bool
+
+
+@dataclass(frozen=True)
+class CheckoutSession:
+    id: str
+    url: str
+
+
+@dataclass(frozen=True)
+class PriceInfo:
+    id: str
+    currency: str
+    interval: str | None  # "month" / "year"; None for one-off prices
+    active: bool
+
+
+@runtime_checkable
+class BillingProvider(Protocol):
+    name: str
+    supports_checkout: bool
+
+    async def ensure_customer(self, tenant_id: str, name: str, email: str | None) -> str | None:
+        """Create the customer; returns its id (``None`` for providers without one)."""
+        ...
+
+    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: ...
+
+    async def expire_checkout(self, session_id: str) -> None:
+        """Close an open Checkout session so it can no longer be paid."""
+        ...
+
+    async def live_subscription_ids(self, customer_id: str) -> list[str]:
+        """The customer's subscriptions that still bill or grant access."""
+        ...
+
+    async def portal_url(self, customer_id: str, return_url: str) -> str: ...
+
+    async def change_plan(self, subscription_id: str, price_id: str, quantity: int) -> None: ...
+
+    async def set_quantity(self, subscription_id: str, quantity: int) -> None: ...
+
+    async def cancel_at_period_end(self, subscription_id: str) -> None: ...
+
+    def parse_webhook(self, body: bytes, headers: Mapping[str, str]) -> WebhookEvent: ...
+
+    async def fetch_subscription(self, subscription_id: str) -> SubscriptionSnapshot: ...
+
+    async def verify_price(self, price_id: str) -> PriceInfo: ...