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

sm_billing/pages/Connection.tsx

@@ -0,0 +1,219 @@
+import { Head, router, usePage } from '@inertiajs/react';
+import { CopyableId } from '@simple-module-py/ui/components/CopyableId';
+import { InlineBanner } from '@simple-module-py/ui/components/InlineBanner';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { PasswordInput } from '@simple-module-py/ui/components/PasswordInput';
+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 { Checkbox } from '@simple-module-py/ui/components/ui/checkbox';
+import { Input } from '@simple-module-py/ui/components/ui/input';
+import { Label } from '@simple-module-py/ui/components/ui/label';
+import { AdminLayout } from '@simple-module-py/ui/layouts/AdminLayout';
+import { AlertTriangle, Info } from 'lucide-react';
+import type React from 'react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { AdminNav } from '../components/AdminNav';
+import { ADMIN_API, ApiError, api } from '../utils/api';
+import type { AdminCommon, Connection as ConnectionInfo } from '../utils/types';
+
+interface Props extends AdminCommon {
+  connection: ConnectionInfo;
+  webhook_url: string;
+}
+
+const RETURN_URL_MAX = 255;
+const RETURN_URL_RULE =
+  'Return URL must be an http(s) origin such as https://app.example.com — no path, query or fragment, at most 255 characters.';
+
+/** Mirrors the server's `normalise_return_url`: blank is fine, else an http(s) origin. */
+function returnUrlError(raw: string): string {
+  const value = raw.trim();
+  if (!value) return '';
+  if (value.length > RETURN_URL_MAX || /[\s?#@]/.test(value)) return RETURN_URL_RULE;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return RETURN_URL_RULE;
+  }
+  const httpish = url.protocol === 'http:' || url.protocol === 'https:';
+  return httpish && url.hostname && url.pathname === '/' ? '' : RETURN_URL_RULE;
+}
+
+function SecretField(props: {
+  id: string;
+  label: string;
+  stored: boolean;
+  value: string;
+  clear: boolean;
+  onValue: (v: string) => void;
+  onClear: (v: boolean) => void;
+}) {
+  return (
+    <div className="space-y-1.5">
+      <Label htmlFor={props.id}>{props.label}</Label>
+      <PasswordInput
+        id={props.id}
+        autoComplete="off"
+        showLabel="Show"
+        hideLabel="Hide"
+        placeholder={props.stored ? 'Stored — leave blank to keep' : 'Not set'}
+        value={props.value}
+        disabled={props.clear}
+        onChange={(e: React.ChangeEvent<HTMLInputElement>) => props.onValue(e.target.value)}
+      />
+      {props.stored && (
+        <Label className="flex items-center gap-2 text-xs font-normal text-muted-foreground">
+          <Checkbox checked={props.clear} onCheckedChange={(v) => props.onClear(v === true)} />
+          Remove the stored value
+        </Label>
+      )}
+    </div>
+  );
+}
+
+function Connection() {
+  const { connection, webhook_url, csrf_token, can_manage } = usePage<{ props: Props }>()
+    .props as unknown as Props;
+  const [secret, setSecret] = useState('');
+  const [webhook, setWebhook] = useState('');
+  const [clearSecret, setClearSecret] = useState(false);
+  const [clearWebhook, setClearWebhook] = useState(false);
+  const [returnUrl, setReturnUrl] = useState(connection.return_base_url);
+  const [returnUrlMsg, setReturnUrlMsg] = useState('');
+  const [busy, setBusy] = useState(false);
+
+  async function save(e: React.FormEvent) {
+    e.preventDefault();
+    const urlError = returnUrlError(returnUrl);
+    setReturnUrlMsg(urlError);
+    if (urlError) return;
+    setBusy(true);
+    try {
+      await api(`${ADMIN_API}/connection`, csrf_token, {
+        method: 'PUT',
+        body: {
+          stripe_secret_key: secret,
+          stripe_webhook_secret: webhook,
+          clear_secret_key: clearSecret,
+          clear_webhook_secret: clearWebhook,
+          return_base_url: returnUrl,
+        },
+      });
+      toast.success('Stripe connection saved');
+      setSecret('');
+      setWebhook('');
+      router.reload();
+    } catch (err) {
+      if (err instanceof ApiError && err.detail === 'invalid_return_url') {
+        setReturnUrlMsg(String(err.body.message ?? RETURN_URL_RULE));
+        return;
+      }
+      toast.error((err as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const stripeChosen = connection.provider === 'stripe';
+  return (
+    <>
+      <Head title="Stripe connection" />
+      <PageShell title="Billing" description="How this site talks to Stripe.">
+        <AdminNav active="connection" />
+        <div className="max-w-2xl space-y-6">
+          {connection.provider_error && (
+            <InlineBanner
+              icon={AlertTriangle}
+              tone="warning"
+              title="Stripe is configured but not in use"
+              description={`${connection.provider_error}. Billing runs on the manual provider until this is fixed.`}
+            />
+          )}
+          {!stripeChosen && (
+            <InlineBanner
+              icon={Info}
+              title="The manual provider is active"
+              description="Set the billing provider to 'stripe' on the Settings screen and restart to take payments."
+            />
+          )}
+          <Card>
+            <CardHeader>
+              <CardTitle>Webhook endpoint</CardTitle>
+              <CardDescription>
+                Add this URL in Stripe → Developers → Webhooks, with the events
+                checkout.session.completed and customer.subscription.*.
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <CopyableId value={webhook_url} title="Copy webhook URL" />
+            </CardContent>
+          </Card>
+          <Card>
+            <CardHeader>
+              <CardTitle>Secrets</CardTitle>
+              <CardDescription>Stored encrypted with the app&apos;s secret key.</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <form onSubmit={save} className="space-y-4">
+                <SecretField
+                  id="stripe-secret"
+                  label="Secret key (sk_…)"
+                  stored={connection.has_secret_key}
+                  value={secret}
+                  clear={clearSecret}
+                  onValue={setSecret}
+                  onClear={setClearSecret}
+                />
+                <SecretField
+                  id="stripe-webhook"
+                  label="Webhook signing secret (whsec_…)"
+                  stored={connection.has_webhook_secret}
+                  value={webhook}
+                  clear={clearWebhook}
+                  onValue={setWebhook}
+                  onClear={setClearWebhook}
+                />
+                <div className="space-y-1.5">
+                  <Label htmlFor="return-url">Return URL origin</Label>
+                  <Input
+                    id="return-url"
+                    placeholder="https://app.example.com"
+                    maxLength={RETURN_URL_MAX}
+                    value={returnUrl}
+                    aria-invalid={returnUrlMsg ? true : undefined}
+                    aria-describedby={returnUrlMsg ? 'return-url-error' : undefined}
+                    onChange={(e) => {
+                      setReturnUrl(e.target.value);
+                      setReturnUrlMsg('');
+                    }}
+                  />
+                  {returnUrlMsg && (
+                    <p id="return-url-error" role="alert" className="text-xs text-destructive">
+                      {returnUrlMsg}
+                    </p>
+                  )}
+                </div>
+                {can_manage && (
+                  <Button type="submit" disabled={busy}>
+                    Save connection
+                  </Button>
+                )}
+              </form>
+            </CardContent>
+          </Card>
+        </div>
+      </PageShell>
+    </>
+  );
+}
+
+Connection.layout = [AdminLayout];
+export default Connection;

sm_billing/pages/Plans.tsx

@@ -0,0 +1,122 @@
+import { Head, router, usePage } from '@inertiajs/react';
+import { ConfirmActionDialog } from '@simple-module-py/ui/components/ConfirmActionDialog';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card } from '@simple-module-py/ui/components/ui/card';
+import { AdminLayout } from '@simple-module-py/ui/layouts/AdminLayout';
+import { Archive, Plus } from 'lucide-react';
+import { useRef, useState } from 'react';
+import { toast } from 'sonner';
+import { AdminNav } from '../components/AdminNav';
+import { PlanEditor } from '../components/PlanEditor';
+import { PlansTable } from '../components/PlansTable';
+import { ADMIN_API, api } from '../utils/api';
+import { type PlanForm, planPayload } from '../utils/plan-form';
+import type { AdminCommon, Plan } from '../utils/types';
+
+interface Props extends AdminCommon {
+  plans: Plan[];
+  known_limit_keys: string[];
+}
+
+function Plans() {
+  const { plans, known_limit_keys, csrf_token, can_manage } = usePage<{ props: Props }>()
+    .props as unknown as Props;
+  const [editing, setEditing] = useState<Plan | null>(null);
+  const [editorOpen, setEditorOpen] = useState(false);
+  const [archiving, setArchiving] = useState<Plan | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [saveError, setSaveError] = useState<string | null>(null);
+  // Synchronous in-flight guard: `busy` state only lands on the next render,
+  // so a fast double click would otherwise send two POSTs.
+  const inFlight = useRef(false);
+
+  async function run(work: () => Promise<void>, onError?: (message: string) => void) {
+    if (inFlight.current) return;
+    inFlight.current = true;
+    setBusy(true);
+    try {
+      await work();
+      router.reload();
+    } catch (err) {
+      const message = (err as Error).message;
+      onError?.(message);
+      toast.error(message);
+    } finally {
+      inFlight.current = false;
+      setBusy(false);
+    }
+  }
+
+  const open = (plan: Plan | null) => {
+    setEditing(plan);
+    setSaveError(null);
+    setEditorOpen(true);
+  };
+
+  const save = (form: PlanForm) =>
+    run(async () => {
+      setSaveError(null);
+      const body = planPayload(form);
+      if (editing) {
+        await api(`${ADMIN_API}/plans/${editing.id}`, csrf_token, { method: 'PUT', body });
+      } else {
+        await api(`${ADMIN_API}/plans`, csrf_token, { body });
+      }
+      toast.success(editing ? 'Plan saved' : 'Plan created');
+      setEditorOpen(false);
+    }, setSaveError);
+
+  const archive = () =>
+    run(async () => {
+      if (!archiving) return;
+      await api(`${ADMIN_API}/plans/${archiving.id}/archive`, csrf_token, { body: {} });
+      toast.success(`${archiving.name} archived`);
+      setArchiving(null);
+    });
+
+  return (
+    <>
+      <Head title="Billing plans" />
+      <PageShell
+        title="Billing"
+        description="Plans decide each organisation's limits; Stripe prices decide what they pay."
+        actions={
+          can_manage ? (
+            <Button onClick={() => open(null)}>
+              <Plus aria-hidden="true" /> New plan
+            </Button>
+          ) : undefined
+        }
+      >
+        <AdminNav active="plans" />
+        <Card className="overflow-hidden p-0">
+          <PlansTable plans={plans} canManage={can_manage} onEdit={open} onArchive={setArchiving} />
+        </Card>
+      </PageShell>
+      <PlanEditor
+        open={editorOpen}
+        plan={editing}
+        knownKeys={known_limit_keys}
+        busy={busy}
+        serverError={saveError}
+        onOpenChange={setEditorOpen}
+        onSave={save}
+      />
+      <ConfirmActionDialog
+        open={archiving !== null}
+        onOpenChange={(o) => !o && setArchiving(null)}
+        icon={Archive}
+        title={`Archive ${archiving?.name ?? ''}?`}
+        description="Tenants already on it keep it; it disappears from the plan picker."
+        confirmLabel="Archive"
+        cancelLabel="Cancel"
+        busy={busy}
+        onConfirm={archive}
+      />
+    </>
+  );
+}
+
+Plans.layout = [AdminLayout];
+export default Plans;

sm_billing/pages/Subscriptions.tsx

@@ -0,0 +1,123 @@
+import { Head, router, usePage } from '@inertiajs/react';
+import { EmptyState } from '@simple-module-py/ui/components/EmptyState';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Card } from '@simple-module-py/ui/components/ui/card';
+import { Label } from '@simple-module-py/ui/components/ui/label';
+import { NativeSelect, NativeSelectOption } from '@simple-module-py/ui/components/ui/native-select';
+import { AdminLayout } from '@simple-module-py/ui/layouts/AdminLayout';
+import { Building2 } from 'lucide-react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { AdminNav } from '../components/AdminNav';
+import { AssignDialog } from '../components/AssignDialog';
+import { SubscriptionsTable } from '../components/SubscriptionsTable';
+import { ADMIN_API, api } from '../utils/api';
+import { STATUS_LABEL } from '../utils/format';
+import type { AdminCommon, Plan, SubscriptionRow, SubscriptionStatus } from '../utils/types';
+
+interface Props extends AdminCommon {
+  rows: SubscriptionRow[];
+  plans: Plan[];
+  status_filter: string;
+}
+
+const VIEW_URL = '/admin/billing/subscriptions';
+
+function Subscriptions() {
+  const { rows, plans, status_filter, csrf_token, can_manage, checkout_available, provider } =
+    usePage<{ props: Props }>().props as unknown as Props;
+  const [assigning, setAssigning] = useState<SubscriptionRow | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function run(work: () => Promise<void>) {
+    setBusy(true);
+    try {
+      await work();
+      router.reload();
+    } catch (err) {
+      toast.error((err as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const resync = (row: SubscriptionRow) =>
+    run(async () => {
+      await api(`${ADMIN_API}/subscriptions/${row.tenant_id}/resync`, csrf_token, { body: {} });
+      toast.success(`${row.tenant_name} resynced from Stripe`);
+    });
+
+  const assign = (planId: number, status: SubscriptionStatus) =>
+    run(async () => {
+      if (!assigning) return;
+      await api(`${ADMIN_API}/subscriptions/${assigning.tenant_id}/assign`, csrf_token, {
+        body: { plan_id: planId, status },
+      });
+      toast.success(`Plan assigned to ${assigning.tenant_name}`);
+      setAssigning(null);
+    });
+
+  const filter = (value: string) =>
+    router.get(VIEW_URL, value ? { status: value } : {}, { preserveScroll: true });
+
+  return (
+    <>
+      <Head title="Billing subscriptions" />
+      <PageShell
+        title="Billing"
+        description={
+          checkout_available
+            ? 'Every organisation and its Stripe subscription.'
+            : `Provider: ${provider}. Assign plans by hand; nobody is charged.`
+        }
+      >
+        <AdminNav active="subscriptions" />
+        <div className="mb-4 flex max-w-xs items-center gap-2">
+          <Label htmlFor="status-filter" className="shrink-0">
+            Status
+          </Label>
+          <NativeSelect
+            id="status-filter"
+            value={status_filter}
+            onChange={(e) => filter(e.target.value)}
+          >
+            <NativeSelectOption value="">All</NativeSelectOption>
+            {(Object.keys(STATUS_LABEL) as SubscriptionStatus[]).map((s) => (
+              <NativeSelectOption key={s} value={s}>
+                {STATUS_LABEL[s]}
+              </NativeSelectOption>
+            ))}
+          </NativeSelect>
+        </div>
+        <Card className="overflow-hidden p-0">
+          {rows.length === 0 ? (
+            <EmptyState
+              icon={Building2}
+              title="No organisations"
+              description={status_filter ? 'None match this status.' : 'Nobody has signed up yet.'}
+            />
+          ) : (
+            <SubscriptionsTable
+              rows={rows}
+              canManage={can_manage}
+              mode={checkout_available ? 'resync' : 'assign'}
+              busy={busy}
+              onResync={resync}
+              onAssign={setAssigning}
+            />
+          )}
+        </Card>
+      </PageShell>
+      <AssignDialog
+        row={assigning}
+        plans={plans}
+        busy={busy}
+        onClose={() => setAssigning(null)}
+        onAssign={assign}
+      />
+    </>
+  );
+}
+
+Subscriptions.layout = [AdminLayout];
+export default Subscriptions;

sm_billing/plans.py

@@ -0,0 +1,227 @@
+"""Plan CRUD and the invariants that keep entitlement resolution total.
+
+Resolution always needs a default plan, so the service guarantees there is
+exactly one, that it is free, and that it can be neither unset nor archived —
+a new default is made by marking another free plan default. The session is
+the caller's; nothing here commits.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+
+from sqlalchemy import or_, select, update
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from sm_billing import constants as c
+from sm_billing.models import Plan, Subscription
+from sm_billing.schemas import PlanIn
+
+logger = logging.getLogger(__name__)
+
+
+class PlanError(Exception):
+    """A plan write that would break an invariant. ``code`` is the API detail."""
+
+    def __init__(self, code: str, status_code: int = 400) -> None:
+        super().__init__(code)
+        self.code = code
+        self.status_code = status_code
+
+
+def _check(data: PlanIn) -> None:
+    has_price = bool(data.stripe_price_month or data.stripe_price_year)
+    if data.pricing_model == c.PricingModel.FREE:
+        if has_price:
+            raise PlanError("free_plan_has_price")
+        if data.trial_days:
+            raise PlanError("free_plan_has_trial")
+    elif not has_price:
+        raise PlanError("paid_plan_needs_price")
+    if data.is_default and data.pricing_model != c.PricingModel.FREE:
+        raise PlanError("default_must_be_free")
+
+
+def _conflict_code(exc: IntegrityError) -> str:
+    """Which unique constraint fired, from the driver's message.
+
+    SQLite names the column (``billing_plan.stripe_price_month``); Postgres
+    names the constraint (``billing_plan_stripe_price_month_key``) — the key
+    column's is ``ix_billing_plan_key``.
+    """
+    return "price_taken" if "stripe_price" in str(exc.orig) else "plan_key_taken"
+
+
+class PlanService:
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    async def list(self, *, include_archived: bool = True) -> list[Plan]:
+        stmt = select(Plan).order_by(Plan.sort_order, Plan.id)
+        if not include_archived:
+            stmt = stmt.where(Plan.archived_at.is_(None))
+        return list((await self.db.execute(stmt)).scalars())
+
+    async def get(self, plan_id: int) -> Plan | None:
+        return await self.db.get(Plan, plan_id)
+
+    async def by_key(self, key: str) -> Plan | None:
+        return (await self.db.execute(select(Plan).where(Plan.key == key))).scalar_one_or_none()
+
+    async def by_price(self, price_id: str) -> tuple[Plan, str] | None:
+        stmt = select(Plan).where(
+            or_(Plan.stripe_price_month == price_id, Plan.stripe_price_year == price_id)
+        )
+        plan = (await self.db.execute(stmt)).scalar_one_or_none()
+        if plan is None:
+            return None
+        interval = c.Interval.MONTH if plan.stripe_price_month == price_id else c.Interval.YEAR
+        return plan, interval
+
+    async def default(self) -> Plan:
+        stmt = select(Plan).where(Plan.is_default.is_(True)).limit(1)
+        plan = (await self.db.execute(stmt)).scalar_one_or_none()
+        if plan is None:  # pragma: no cover - startup seeds one and writes keep it
+            raise PlanError("no_default_plan", status_code=500)
+        return plan
+
+    async def _ensure_unique(self, data: PlanIn, plan_id: int | None) -> None:
+        existing = await self.by_key(data.key)
+        if existing is not None and existing.id != plan_id:
+            raise PlanError("plan_key_taken", status_code=409)
+        for price in (data.stripe_price_month, data.stripe_price_year):
+            if price is None:
+                continue
+            match = await self.by_price(price)
+            if match is not None and match[0].id != plan_id:
+                raise PlanError("price_taken", status_code=409)
+        if data.stripe_price_month and data.stripe_price_month == data.stripe_price_year:
+            raise PlanError("price_taken", status_code=409)
+
+    async def _flush_unique(self, data: PlanIn, plan_id: int | None, apply) -> None:
+        """Run ``apply`` and flush inside a savepoint; a unique clash is a 409.
+
+        ``_ensure_unique`` is check-then-write, so two concurrent requests can
+        both pass it. The constraint then fires at flush; roll back just the
+        savepoint (the request session stays usable) and report which one.
+        """
+        try:
+            async with self.db.begin_nested():
+                apply()
+                await self.db.flush()
+        except IntegrityError as exc:
+            await self._ensure_unique(data, plan_id)
+            raise PlanError(_conflict_code(exc), status_code=409) from exc
+
+    async def _take_default(self, plan_id: int) -> None:
+        await self.db.execute(
+            update(Plan)
+            .where(Plan.id != plan_id, Plan.is_default.is_(True))
+            .values(is_default=False)
+        )
+
+    async def create(self, data: PlanIn) -> Plan:
+        _check(data)
+        await self._ensure_unique(data, None)
+        plan = Plan(**data.model_dump())
+        await self._flush_unique(data, None, lambda: self.db.add(plan))
+        if plan.is_default:
+            await self._take_default(plan.id)
+        return plan
+
+    async def update(self, plan_id: int, data: PlanIn) -> Plan:
+        plan = await self.get(plan_id)
+        if plan is None:
+            raise PlanError("plan_not_found", status_code=404)
+        if data.key != plan.key:
+            raise PlanError("plan_key_immutable")
+        _check(data)
+        if plan.is_default and not data.is_default:
+            raise PlanError("default_required", status_code=409)
+        if data.is_default and plan.archived_at is not None:
+            raise PlanError("cannot_archive_default", status_code=409)
+        await self._guard_prices_in_use(plan, data)
+        await self._ensure_unique(data, plan.id)
+
+        def apply() -> None:
+            for field, value in data.model_dump().items():
+                setattr(plan, field, value)
+            plan.updated_at = datetime.now(UTC)
+
+        await self._flush_unique(data, plan.id, apply)
+        if plan.is_default:
+            await self._take_default(plan.id)
+        return plan
+
+    async def _guard_prices_in_use(self, plan: Plan, data: PlanIn) -> None:
+        """A price someone is subscribed on cannot be swapped or removed.
+
+        Webhooks map a subscription to its plan through the price; change it
+        under a live subscriber and every later event for them — including the
+        cancel or the "unpaid" — can no longer be mapped.
+        """
+        changes = (
+            (c.Interval.MONTH, plan.stripe_price_month, data.stripe_price_month),
+            (c.Interval.YEAR, plan.stripe_price_year, data.stripe_price_year),
+        )
+        for interval, old, new in changes:
+            if not old or old == new:
+                continue
+            stmt = (
+                select(Subscription.id)
+                .where(
+                    Subscription.plan_id == plan.id,
+                    Subscription.interval == interval,
+                    Subscription.provider_subscription_id.is_not(None),
+                    Subscription.status != c.SubscriptionStatus.CANCELED,
+                )
+                .limit(1)
+            )
+            if (await self.db.execute(stmt)).first() is not None:
+                raise PlanError("price_in_use", status_code=409)
+
+    async def archive(self, plan_id: int) -> Plan:
+        plan = await self.get(plan_id)
+        if plan is None:
+            raise PlanError("plan_not_found", status_code=404)
+        if plan.is_default:
+            raise PlanError("cannot_archive_default", status_code=409)
+        if plan.archived_at is None:
+            plan.archived_at = datetime.now(UTC)
+            await self.db.flush()
+        return plan
+
+
+async def seed_default_plan(session_factory: async_sessionmaker) -> None:
+    """Make sure a free default plan exists. Idempotent; runs at every startup."""
+    async with session_factory() as session:
+        default = (
+            await session.execute(select(Plan).where(Plan.is_default.is_(True)).limit(1))
+        ).scalar_one_or_none()
+        if default is not None:
+            return
+        existing = (
+            await session.execute(select(Plan).where(Plan.key == c.DEFAULT_PLAN_KEY))
+        ).scalar_one_or_none()
+        if existing is not None and existing.pricing_model == c.PricingModel.FREE:
+            existing.is_default = True
+            existing.archived_at = None
+        else:
+            key = c.DEFAULT_PLAN_KEY if existing is None else f"{c.DEFAULT_PLAN_KEY}-default"
+            session.add(
+                Plan(
+                    key=key,
+                    name=c.DEFAULT_PLAN_NAME,
+                    pricing_model=c.PricingModel.FREE,
+                    is_default=True,
+                )
+            )
+        try:
+            await session.commit()
+        except IntegrityError:
+            # Another worker seeded it between our check and commit.
+            await session.rollback()
+            return
+        logger.info("billing: seeded the free default plan")