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

sm_billing/checkout.py

@@ -0,0 +1,203 @@
+"""What a tenant owner can do: see status, check out, open the portal, change plan.
+
+Nothing here grants a plan. Checkout returns a Stripe URL and the webhook
+writes the subscription; plan changes call the provider and then re-sync from
+its answer, so the local row always mirrors what Stripe actually did.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import TYPE_CHECKING
+
+from sm_billing import constants as c
+from sm_billing.contracts.provider import ProviderError
+from sm_billing.errors import BillingError
+from sm_billing.lifecycle import tenant_service
+from sm_billing.models import Customer, Plan, Subscription
+from sm_billing.plans import PlanService
+from sm_billing.resolve import effective_plan, subscription_for
+from sm_billing.schemas import PlanOut, StatusOut, SubscriptionOut
+from sm_billing.services import current_provider
+from sm_billing.sync import resync
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+    from sm_billing.contracts.provider import BillingProvider
+
+
+def plan_out(plan: Plan) -> PlanOut:
+    return PlanOut.model_validate(plan, from_attributes=True)
+
+
+def subscription_out(sub: Subscription | None) -> SubscriptionOut | None:
+    if sub is None:
+        return None
+    return SubscriptionOut(
+        status=sub.status,
+        interval=sub.interval,
+        quantity=sub.quantity,
+        trial_end=sub.trial_end,
+        current_period_end=sub.current_period_end,
+        cancel_at_period_end=sub.cancel_at_period_end,
+        has_provider_subscription=sub.provider_subscription_id is not None,
+    )
+
+
+class BillingService:
+    def __init__(self, db: AsyncSession, app: FastAPI, tenant_id: str) -> None:
+        self.db = db
+        self.app = app
+        self.tenant_id = tenant_id
+        self.provider: BillingProvider = current_provider(app)
+        self.plans = PlanService(db)
+        self.tenants = tenant_service(db, app)
+
+    # ── reads ───────────────────────────────────────────────────
+
+    async def members(self) -> int:
+        return (await self.tenants.member_counts([self.tenant_id])).get(self.tenant_id, 0)
+
+    async def status(self) -> StatusOut:
+        plan, sub = await effective_plan(self.db, self.tenant_id)
+        customer = await self.db.get(Customer, self.tenant_id)
+        return StatusOut(
+            plan=plan_out(plan),
+            subscription=subscription_out(sub),
+            # Pending invitations hold a seat, as in the seat guard and Members page.
+            seats={
+                "used": await self.tenants.seats_used(self.tenant_id),
+                "limit": plan.limits.get(c.ENTITLEMENT_SEATS),
+            },
+            provider=self.provider.name,
+            checkout_available=self.provider.supports_checkout,
+            portal_available=self.provider.supports_checkout
+            and customer is not None
+            and customer.provider_customer_id is not None,
+        )
+
+    async def public_plans(self) -> list[PlanOut]:
+        plans = await self.plans.list(include_archived=False)
+        return [plan_out(p) for p in plans if p.is_public]
+
+    # ── guards ──────────────────────────────────────────────────
+
+    def _require_checkout(self) -> None:
+        if not self.provider.supports_checkout:
+            raise BillingError("checkout_unavailable", 409)
+
+    async def _target(self, plan_id: int) -> Plan:
+        plan = await self.plans.get(plan_id)
+        if plan is None or plan.archived_at is not None or not plan.is_public:
+            raise BillingError("plan_not_found", 404)
+        return plan
+
+    @staticmethod
+    def _price(plan: Plan, interval: str) -> str:
+        price = plan.stripe_price_month if interval == c.Interval.MONTH else plan.stripe_price_year
+        if not price:
+            raise BillingError("interval_unavailable")
+        return price
+
+    async def _seat_guard(self, plan: Plan) -> None:
+        limit = plan.limits.get(c.ENTITLEMENT_SEATS)
+        used = await self.tenants.seats_used(self.tenant_id)
+        if limit is not None and used > limit:
+            raise BillingError("too_many_members", 409, used=used, limit=limit)
+
+    async def _quantity(self, plan: Plan) -> int:
+        if plan.pricing_model == c.PricingModel.PER_SEAT:
+            return max(1, await self.members())
+        return 1
+
+    async def _live_subscription(self) -> Subscription | None:
+        sub = await subscription_for(self.db, self.tenant_id)
+        if sub is None or sub.provider_subscription_id is None:
+            return None
+        return sub if sub.status in c.ENTITLED_STATUSES else None
+
+    # ── writes ──────────────────────────────────────────────────
+
+    async def checkout(self, plan_id: int, interval: str, *, email: str | None, base: str) -> str:
+        self._require_checkout()
+        plan = await self._target(plan_id)
+        if plan.pricing_model == c.PricingModel.FREE:
+            raise BillingError("plan_is_free")
+        price = self._price(plan, interval)
+        if await self._live_subscription() is not None:
+            raise BillingError("already_subscribed", 409)
+        await self._seat_guard(plan)
+        customer = await self._customer(email)
+        # The local row only changes when a webhook lands, so ask Stripe too:
+        # a subscription paid in another tab must not be joined by a second.
+        if await self.provider.live_subscription_ids(customer.provider_customer_id):
+            raise BillingError("already_subscribed", 409)
+        if customer.checkout_session_id:
+            # One open session per tenant: the older one can no longer be paid.
+            with contextlib.suppress(ProviderError):  # already completed or expired
+                await self.provider.expire_checkout(customer.checkout_session_id)
+        session = await self.provider.create_checkout(
+            customer_id=customer.provider_customer_id,
+            price_id=price,
+            quantity=await self._quantity(plan),
+            trial_days=0 if await self._trial_used() else plan.trial_days,
+            tenant_id=self.tenant_id,
+            success_url=f"{base}{c.VIEW_PREFIX}/?checkout=success",
+            cancel_url=f"{base}{c.VIEW_PREFIX}/?checkout=cancel",
+        )
+        customer.checkout_session_id = session.id
+        await self.db.flush()
+        return session.url
+
+    async def _customer(self, email: str | None) -> Customer:
+        customer = await self.db.get(Customer, self.tenant_id)
+        if customer is not None and customer.provider_customer_id is not None:
+            return customer
+        tenant = await self.tenants.get(self.tenant_id)
+        customer_id = await self.provider.ensure_customer(
+            self.tenant_id, tenant.name if tenant else self.tenant_id, email
+        )
+        if customer is None:
+            customer = Customer(tenant_id=self.tenant_id, provider=self.provider.name)
+            self.db.add(customer)
+        customer.provider_customer_id = customer_id
+        customer.provider = self.provider.name
+        customer.email = email
+        await self.db.flush()
+        return customer
+
+    async def _trial_used(self) -> bool:
+        """One trial per organisation: any earlier provider subscription spent it."""
+        sub = await subscription_for(self.db, self.tenant_id)
+        return sub is not None and (
+            sub.provider_subscription_id is not None or sub.trial_end is not None
+        )
+
+    async def portal(self, *, base: str) -> str:
+        self._require_checkout()
+        customer = await self.db.get(Customer, self.tenant_id)
+        if customer is None or customer.provider_customer_id is None:
+            raise BillingError("no_customer", 409)
+        return await self.provider.portal_url(
+            customer.provider_customer_id, f"{base}{c.VIEW_PREFIX}/"
+        )
+
+    async def change_plan(self, plan_id: int, interval: str) -> StatusOut:
+        self._require_checkout()
+        plan = await self._target(plan_id)
+        sub = await self._live_subscription()
+        if sub is None:
+            raise BillingError("no_subscription", 409)
+        await self._seat_guard(plan)
+        subscription_id = sub.provider_subscription_id
+        if plan.pricing_model == c.PricingModel.FREE:
+            await self.provider.cancel_at_period_end(subscription_id)
+        else:
+            price = self._price(plan, interval)
+            if sub.plan_id == plan.id and sub.interval == interval and not sub.cancel_at_period_end:
+                raise BillingError("already_on_plan", 409)
+            await self.provider.change_plan(subscription_id, price, await self._quantity(plan))
+        await resync(self.db, self.app, self.provider, subscription_id)
+        return await self.status()

sm_billing/cli.py

@@ -0,0 +1,44 @@
+"""``smpy billing reconcile [--tenant ID]`` — mounted through the framework CLI seam.
+
+Run from the repo root like every other entry point, so the host's settings
+(database URL, secret key) are the ones the app boots with.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import typer
+
+app = typer.Typer(help="Billing module administration.", no_args_is_help=True)
+
+
+@app.callback()
+def _main() -> None:
+    """Billing module administration."""
+
+
+@app.command("reconcile")
+def reconcile_command(
+    tenant: str | None = typer.Option(None, "--tenant", help="Only this tenant id."),
+) -> None:
+    """Re-fetch provider subscriptions and push drifted seat quantities."""
+    from simple_module_hosting.app_builder import create_app
+    from simple_module_hosting.settings import Settings
+
+    from sm_billing.reconcile import reconcile
+
+    fastapi_app = create_app(Settings())
+
+    async def run() -> int:
+        async with fastapi_app.router.lifespan_context(fastapi_app):
+            report = await reconcile(fastapi_app, tenant_id=tenant)
+        if report.skipped:
+            typer.echo(f"Nothing to reconcile: {report.skipped}.")
+            return 0
+        typer.echo(f"Synced {report.synced}, pushed {report.pushed} quantity change(s).")
+        for tenant_id, error in report.errors:
+            typer.echo(f"  {tenant_id}: {error}", err=True)
+        return 1 if report.errors else 0
+
+    raise typer.Exit(code=asyncio.run(run()))

sm_billing/components/AdminNav.tsx

@@ -0,0 +1,44 @@
+import { Link } from '@inertiajs/react';
+import { Toaster } from '@simple-module-py/ui/components/ui/sonner';
+import { cn } from '@simple-module-py/ui/lib/utils';
+
+const TABS = [
+  { key: 'subscriptions', label: 'Subscriptions', href: '/admin/billing/subscriptions' },
+  { key: 'plans', label: 'Plans', href: '/admin/billing/plans' },
+  { key: 'connection', label: 'Stripe connection', href: '/admin/billing/connection' },
+] as const;
+
+export type AdminTab = (typeof TABS)[number]['key'];
+
+/**
+ * The three billing admin screens, as tabs — and their toast outlet.
+ *
+ * ``AdminLayout`` (unlike ``AuthenticatedLayout``) mounts no ``<Toaster/>``,
+ * so without this every save confirmation and every API error on these
+ * screens would be raised into nothing. Every billing admin page renders this
+ * nav, which makes it the one place that guarantees the outlet exists.
+ */
+export function AdminNav({ active }: { active: AdminTab }) {
+  return (
+    <>
+      <nav aria-label="Billing administration" className="mb-4 flex gap-1 border-b">
+        {TABS.map((tab) => (
+          <Link
+            key={tab.key}
+            href={tab.href}
+            aria-current={tab.key === active ? 'page' : undefined}
+            className={cn(
+              '-mb-px border-b-2 px-3 py-2 text-sm font-medium transition-colors max-lg:min-h-11',
+              tab.key === active
+                ? 'border-primary text-foreground'
+                : 'border-transparent text-muted-foreground hover:text-foreground',
+            )}
+          >
+            {tab.label}
+          </Link>
+        ))}
+      </nav>
+      <Toaster richColors position="top-right" />
+    </>
+  );
+}

sm_billing/components/AssignDialog.tsx

@@ -0,0 +1,87 @@
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@simple-module-py/ui/components/ui/dialog';
+import { Label } from '@simple-module-py/ui/components/ui/label';
+import { NativeSelect, NativeSelectOption } from '@simple-module-py/ui/components/ui/native-select';
+import { useEffect, useState } from 'react';
+import { STATUS_LABEL } from '../utils/format';
+import type { Plan, SubscriptionRow, SubscriptionStatus } from '../utils/types';
+
+interface Props {
+  row: SubscriptionRow | null;
+  plans: Plan[];
+  busy: boolean;
+  onClose: () => void;
+  onAssign: (planId: number, status: SubscriptionStatus) => void;
+}
+
+/** Manual provider: set an organisation's plan and status by hand. */
+export function AssignDialog({ row, plans, busy, onClose, onAssign }: Props) {
+  const choices = plans.filter((p) => !p.archived_at);
+  const [planId, setPlanId] = useState<number>(row?.plan_id ?? choices[0]?.id ?? 0);
+  const [status, setStatus] = useState<SubscriptionStatus>(row?.status ?? 'active');
+  useEffect(() => {
+    if (row) {
+      setPlanId(row.plan_id);
+      setStatus(row.status ?? 'active');
+    }
+  }, [row]);
+
+  return (
+    <Dialog open={row !== null} onOpenChange={(open) => !open && onClose()}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Assign a plan to {row?.tenant_name}</DialogTitle>
+          <DialogDescription>
+            &ldquo;Unpaid&rdquo; suspends the organisation; any other status lifts a suspension
+            billing made.
+          </DialogDescription>
+        </DialogHeader>
+        <div className="grid gap-4 sm:grid-cols-2">
+          <div className="space-y-1.5">
+            <Label htmlFor="assign-plan">Plan</Label>
+            <NativeSelect
+              id="assign-plan"
+              value={String(planId)}
+              onChange={(e) => setPlanId(Number(e.target.value))}
+            >
+              {choices.map((p) => (
+                <NativeSelectOption key={p.id} value={String(p.id)}>
+                  {p.name}
+                </NativeSelectOption>
+              ))}
+            </NativeSelect>
+          </div>
+          <div className="space-y-1.5">
+            <Label htmlFor="assign-status">Status</Label>
+            <NativeSelect
+              id="assign-status"
+              value={status}
+              onChange={(e) => setStatus(e.target.value as SubscriptionStatus)}
+            >
+              {(Object.keys(STATUS_LABEL) as SubscriptionStatus[]).map((s) => (
+                <NativeSelectOption key={s} value={s}>
+                  {STATUS_LABEL[s]}
+                </NativeSelectOption>
+              ))}
+            </NativeSelect>
+          </div>
+        </div>
+        <DialogFooter>
+          <Button variant="outline" onClick={onClose}>
+            Cancel
+          </Button>
+          <Button disabled={busy || !planId} onClick={() => onAssign(planId, status)}>
+            Assign
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

sm_billing/components/CurrentPlanCard.tsx

@@ -0,0 +1,86 @@
+import { InlineBanner } from '@simple-module-py/ui/components/InlineBanner';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@simple-module-py/ui/components/ui/card';
+import { AlertTriangle, CreditCard } from 'lucide-react';
+import { formatDate } from '../utils/format';
+import { seatsLabel } from '../utils/seats';
+import type { Status } from '../utils/types';
+import { StatusBadge } from './StatusBadge';
+
+interface Props {
+  status: Status;
+  canManage: boolean;
+  busy: boolean;
+  onPortal: () => void;
+}
+
+/** The plan in force, its renewal or end date, seats, and the payment-trouble banner. */
+export function CurrentPlanCard({ status, canManage, busy, onPortal }: Props) {
+  const sub = status.subscription;
+  const { used, limit } = status.seats;
+  const seats = seatsLabel(used, limit);
+  const portal = canManage && status.portal_available;
+
+  return (
+    <div className="space-y-4">
+      {sub?.status === 'past_due' && (
+        <InlineBanner
+          icon={AlertTriangle}
+          tone="warning"
+          title="Your last payment failed"
+          description="Stripe is retrying the charge. Update your payment method to keep your plan."
+          action={
+            portal ? (
+              <Button size="sm" onClick={onPortal} disabled={busy}>
+                Update payment method
+              </Button>
+            ) : undefined
+          }
+        />
+      )}
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex flex-wrap items-center gap-2">
+            {status.plan.name}
+            {sub && <StatusBadge status={sub.status} />}
+          </CardTitle>
+          <CardDescription>{status.plan.description || 'Your current plan.'}</CardDescription>
+        </CardHeader>
+        <CardContent className="flex flex-wrap items-end justify-between gap-4">
+          <dl className="grid gap-1 text-sm">
+            <div className="flex gap-2">
+              <dt className="text-muted-foreground">Seats</dt>
+              <dd>{seats}</dd>
+            </div>
+            {sub?.status === 'trialing' && sub.trial_end && (
+              <div className="flex gap-2">
+                <dt className="text-muted-foreground">Trial ends</dt>
+                <dd>{formatDate(sub.trial_end)}</dd>
+              </div>
+            )}
+            {sub?.current_period_end && (
+              <div className="flex gap-2">
+                <dt className="text-muted-foreground">
+                  {sub.cancel_at_period_end ? 'Ends on' : 'Renews on'}
+                </dt>
+                <dd>{formatDate(sub.current_period_end)}</dd>
+              </div>
+            )}
+          </dl>
+          {portal && (
+            <Button variant="outline" onClick={onPortal} disabled={busy}>
+              <CreditCard aria-hidden="true" />
+              Manage payment &amp; invoices
+            </Button>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

sm_billing/components/LimitRows.tsx

@@ -0,0 +1,80 @@
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { Plus, X } from 'lucide-react';
+
+interface Row {
+  key: string;
+  value: string;
+}
+
+interface Props {
+  rows: Row[];
+  knownKeys: string[];
+  onChange: (rows: Row[]) => void;
+}
+
+/** Key/number rows for a plan's limits. An absent key is unlimited; 0 forbids. */
+export function LimitRows({ rows, knownKeys, onChange }: Props) {
+  const update = (index: number, patch: Partial<Row>) =>
+    onChange(rows.map((row, i) => (i === index ? { ...row, ...patch } : row)));
+  const missing = knownKeys.filter((key) => !rows.some((row) => row.key === key));
+
+  return (
+    <div className="space-y-2">
+      {rows.map((row, index) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: rows have no identity until saved
+        <div key={index} className="flex items-center gap-2">
+          <Input
+            aria-label="Limit key"
+            placeholder="tenants.seats"
+            value={row.key}
+            onChange={(e) => update(index, { key: e.target.value })}
+            list="billing-known-limit-keys"
+          />
+          <Input
+            aria-label={`Limit for ${row.key || 'new key'}`}
+            className="w-28"
+            inputMode="numeric"
+            value={row.value}
+            onChange={(e) => update(index, { value: e.target.value })}
+          />
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon"
+            aria-label={`Remove ${row.key || 'row'}`}
+            onClick={() => onChange(rows.filter((_, i) => i !== index))}
+          >
+            <X aria-hidden="true" />
+          </Button>
+        </div>
+      ))}
+      <datalist id="billing-known-limit-keys">
+        {knownKeys.map((key) => (
+          <option key={key} value={key} />
+        ))}
+      </datalist>
+      <div className="flex flex-wrap gap-2">
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          onClick={() => onChange([...rows, { key: '', value: '' }])}
+        >
+          <Plus aria-hidden="true" /> Add limit
+        </Button>
+        {missing.map((key) => (
+          <Button
+            key={key}
+            type="button"
+            variant="ghost"
+            size="sm"
+            onClick={() => onChange([...rows, { key, value: '' }])}
+          >
+            <Plus aria-hidden="true" /> {key}
+          </Button>
+        ))}
+      </div>
+    </div>
+  );
+}

sm_billing/components/PlanCard.tsx

@@ -0,0 +1,82 @@
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from '@simple-module-py/ui/components/ui/card';
+import { cn } from '@simple-module-py/ui/lib/utils';
+import { Check } from 'lucide-react';
+import { type PlanCta, priceLabel } from '../utils/format';
+import type { Interval, Plan } from '../utils/types';
+
+interface Props {
+  plan: Plan;
+  interval: Interval;
+  cta: PlanCta;
+  canManage: boolean;
+  busy: boolean;
+  onChoose: (plan: Plan, cta: PlanCta) => void;
+}
+
+const LABEL: Record<PlanCta, string> = {
+  current: 'Current plan',
+  checkout: 'Subscribe',
+  change: 'Switch to this plan',
+  downgrade: 'Downgrade at period end',
+  unavailable: 'Not available',
+};
+
+function limitLines(plan: Plan): string[] {
+  const seats = plan.limits['tenants.seats'];
+  const lines = [seats === undefined ? 'Unlimited seats' : `Up to ${seats} seats`];
+  for (const [key, value] of Object.entries(plan.limits)) {
+    if (key !== 'tenants.seats') lines.push(`${key}: ${value}`);
+  }
+  return lines;
+}
+
+export function PlanCard({ plan, interval, cta, canManage, busy, onChoose }: Props) {
+  const actionable = canManage && cta !== 'current' && cta !== 'unavailable';
+  return (
+    <Card
+      className={cn('flex flex-col', cta === 'current' && 'border-primary ring-1 ring-primary')}
+    >
+      <CardHeader>
+        <CardTitle className="flex items-center justify-between gap-2">
+          {plan.name}
+          {plan.trial_days > 0 && cta === 'checkout' && (
+            <Badge variant="secondary">{plan.trial_days}-day trial</Badge>
+          )}
+        </CardTitle>
+        <CardDescription className="text-base font-medium text-foreground">
+          {priceLabel(plan, interval)}
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="flex-1 space-y-3 text-sm">
+        {plan.description && <p className="text-muted-foreground">{plan.description}</p>}
+        <ul className="space-y-1.5">
+          {[...limitLines(plan), ...plan.features].map((line) => (
+            <li key={line} className="flex items-start gap-2">
+              <Check className="mt-0.5 size-4 shrink-0 text-primary" aria-hidden="true" />
+              <span>{line}</span>
+            </li>
+          ))}
+        </ul>
+      </CardContent>
+      <CardFooter>
+        <Button
+          className="w-full max-lg:min-h-11"
+          variant={cta === 'downgrade' ? 'outline' : 'default'}
+          disabled={!actionable || busy}
+          onClick={() => onChoose(plan, cta)}
+        >
+          {LABEL[cta]}
+        </Button>
+      </CardFooter>
+    </Card>
+  );
+}