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

sm_billing/seats.py

@@ -0,0 +1,63 @@
+"""Per-seat quantity sync on membership changes.
+
+The tenants module publishes ``MembershipAdded``/``MembershipRemoved`` after
+its commit, inline in the request. The handler opens its own session, and a
+provider failure is logged, never raised: the membership change already
+happened and must stand. ``reconcile`` pushes any drift left behind.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from sm_billing import constants as c
+from sm_billing.lifecycle import tenant_service
+from sm_billing.resolve import effective_plan
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from simple_module_core.events import EventBus
+
+logger = logging.getLogger(__name__)
+
+
+async def push_quantity(app: FastAPI, tenant_id: str) -> bool:
+    """Make the provider's quantity equal the member count. ``True`` if pushed."""
+    provider = getattr(app.state, c.PACKAGE).provider
+    if provider is None or not provider.supports_checkout:
+        return False
+    async with app.state.sm.db.session_factory() as session:
+        plan, sub = await effective_plan(session, tenant_id)
+        if (
+            sub is None
+            or sub.provider_subscription_id is None
+            or plan.pricing_model != c.PricingModel.PER_SEAT
+        ):
+            return False
+        counts = await tenant_service(session, app).member_counts([tenant_id])
+        members = max(1, counts.get(tenant_id, 0))
+        if members == sub.quantity:
+            return False
+        await provider.set_quantity(sub.provider_subscription_id, members)
+        sub.quantity = members
+        await session.commit()
+    return True
+
+
+def subscribe(bus: EventBus, app: FastAPI) -> None:
+    """Subscribe the membership handlers."""
+    from tenants.contracts.events import MembershipAdded, MembershipRemoved
+
+    async def _sync(event: MembershipAdded | MembershipRemoved) -> None:
+        try:
+            await push_quantity(app, event.tenant_id)
+        except Exception:
+            logger.warning(
+                "billing: seat sync failed for tenant %s; reconcile will retry",
+                event.tenant_id,
+                exc_info=True,
+            )
+
+    bus.subscribe(MembershipAdded, _sync)
+    bus.subscribe(MembershipRemoved, _sync)

sm_billing/services.py

@@ -0,0 +1,36 @@
+"""Module-scoped state on ``app.state.sm_billing``.
+
+Not frozen: the host's hydrate step assigns the DB-resolved settings onto
+this object at lifespan start, and the Settings screen assigns again on every
+save. ``provider`` is built in ``on_startup`` from the hydrated settings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sm_billing import constants as c
+from sm_billing.errors import BillingError
+from sm_billing.settings import BillingSettings
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from sm_billing.contracts.provider import BillingProvider
+
+
+@dataclass
+class BillingServices:
+    settings: BillingSettings
+    provider: BillingProvider | None = None
+    #: Why the configured provider could not be used (shown on the admin screens).
+    provider_error: str = ""
+
+
+def current_provider(app: FastAPI) -> BillingProvider:
+    """The running provider, for code that cannot proceed without one."""
+    provider = getattr(app.state, c.PACKAGE).provider
+    if provider is None:
+        raise BillingError("provider_unavailable", 503)
+    return provider

sm_billing/settings.py

@@ -0,0 +1,47 @@
+"""Billing settings — DB-backed via ``register_module_settings``.
+
+No environment, ``.env`` or secrets-file sources (``DbBackedSettings``): an
+``SM_BILLING_*`` variable is dead. Configure on the Settings screen, on
+``/admin/billing/connection`` (which encrypts the Stripe secrets), or with
+``scripts/set_setting.py``.
+
+``provider`` is read once, in ``on_startup`` — the provider object is built
+then — so changing it needs a restart.
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+from simple_module_core.settings_base import DbBackedSettings
+
+from sm_billing import constants as c
+
+_RESTART = {"requires_restart": True, "group": "Billing", "choices": list(c.PROVIDERS)}
+
+
+class BillingSettings(DbBackedSettings):
+    """Configuration for the billing module."""
+
+    provider: str = Field(
+        default=c.PROVIDER_MANUAL,
+        description=(
+            "Payment provider. 'manual': admins assign plans by hand, no payment. "
+            "'stripe': Checkout, Customer Portal and webhooks (needs both Stripe secrets)."
+        ),
+        json_schema_extra=_RESTART,
+    )
+    stripe_secret_key: str = Field(
+        default="",
+        description="Stripe secret API key (sk_live_… / sk_test_…). Stored encrypted.",
+    )
+    stripe_webhook_secret: str = Field(
+        default="",
+        description="Signing secret of the Stripe webhook endpoint (whsec_…). Stored encrypted.",
+    )
+    return_base_url: str = Field(
+        default="",
+        description=(
+            "Origin Stripe returns visitors to after Checkout and the portal, e.g. "
+            "https://app.example.com. Empty: the request's own origin."
+        ),
+    )

sm_billing/startup.py

@@ -0,0 +1,27 @@
+"""Lifespan-start work: seed the default plan, build the provider, install entitlements.
+
+Runs after settings hydration and after ``tenants``' own startup
+(``depends_on``), so ``app.state.sm_billing.settings`` holds the DB values and
+``app.state.tenants`` exists.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sm_billing import constants as c
+from sm_billing.entitlements import PlanEntitlements
+from sm_billing.plans import seed_default_plan
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+
+async def run(app: FastAPI) -> None:
+    session_factory = app.state.sm.db.session_factory
+    await seed_default_plan(session_factory)
+    app.state.tenants.entitlements = PlanEntitlements(session_factory)
+    services = getattr(app.state, c.PACKAGE)
+    from sm_billing.providers.factory import install_provider
+
+    install_provider(services)

sm_billing/sync.py

@@ -0,0 +1,120 @@
+"""Write a provider snapshot onto the local mirror.
+
+One function, used by webhooks, reconcile and the admin "Resync" button, so
+there is exactly one place that decides how provider state becomes local
+state. Failures raise ``SyncError`` rather than guessing: an unknown price or
+tenant must never quietly hand a paying customer the default plan.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from sqlalchemy import select
+from tenants.models import Tenant
+
+from sm_billing.constants import ENTITLED_STATUSES, STRIPE_STATUS_MAP, SubscriptionStatus
+from sm_billing.lifecycle import apply_lifecycle
+from sm_billing.models import Customer, Subscription
+from sm_billing.plans import PlanService
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+    from sm_billing.contracts.provider import BillingProvider, SubscriptionSnapshot
+
+
+class SyncError(Exception):
+    """The snapshot cannot be mapped onto a tenant and plan."""
+
+    def __init__(self, code: str, detail: str = "") -> None:
+        super().__init__(f"{code}: {detail}" if detail else code)
+        self.code = code
+
+
+async def _tenant_for(db: AsyncSession, snap: SubscriptionSnapshot) -> str:
+    if snap.tenant_id and await db.get(Tenant, snap.tenant_id) is not None:
+        return snap.tenant_id
+    if snap.customer_id:
+        stmt = select(Customer).where(Customer.provider_customer_id == snap.customer_id)
+        customer = (await db.execute(stmt)).scalar_one_or_none()
+        if customer is not None:
+            return customer.tenant_id
+    raise SyncError("unknown_tenant", f"subscription {snap.id}")
+
+
+async def _link_customer(db: AsyncSession, tenant_id: str, customer_id: str | None, provider: str):
+    if not customer_id:
+        return
+    customer = await db.get(Customer, tenant_id)
+    if customer is None:
+        db.add(Customer(tenant_id=tenant_id, provider=provider, provider_customer_id=customer_id))
+    elif customer.provider_customer_id != customer_id:
+        customer.provider_customer_id = customer_id
+        customer.provider = provider
+
+
+async def apply_snapshot(
+    db: AsyncSession, app: FastAPI, snap: SubscriptionSnapshot, *, provider: str
+) -> Subscription:
+    """Upsert the tenant's subscription from ``snap`` and apply the lifecycle.
+
+    Flushes, never commits (see ``apply_lifecycle`` for why the caller must
+    finalize). Returns the tenant's subscription row.
+    """
+    status = STRIPE_STATUS_MAP.get(snap.status)
+    if status is None:
+        raise SyncError("unknown_status", snap.status)
+    tenant_id = await _tenant_for(db, snap)
+    stmt = select(Subscription).where(Subscription.tenant_id == tenant_id)
+    sub = (await db.execute(stmt)).scalar_one_or_none()
+
+    # A late event for a tenant's *previous* subscription (canceled before
+    # they re-subscribed) must not overwrite the live one.
+    if (
+        sub is not None
+        and sub.provider_subscription_id not in (None, snap.id)
+        and status == SubscriptionStatus.CANCELED
+    ):
+        return sub
+
+    match = await PlanService(db).by_price(snap.price_id) if snap.price_id else None
+    if match is not None:
+        plan_id, interval = match[0].id, match[1]
+    elif sub is not None and status not in ENTITLED_STATUSES:
+        # A lapse needs no plan: apply the cancel / "unpaid" on the plan they
+        # had, so an unmappable price never keeps paid access alive.
+        plan_id, interval = sub.plan_id, sub.interval
+    elif sub is None and status not in ENTITLED_STATUSES:
+        # A lapse of something never mirrored here (e.g. a checkout that was
+        # abandoned on a since-deleted price): there is no access to revoke.
+        raise SyncError("nothing_to_apply", f"{snap.status} on {snap.price_id or '(none)'}")
+    else:
+        raise SyncError("unknown_price", snap.price_id or "(none)")
+
+    await _link_customer(db, tenant_id, snap.customer_id, provider)
+    if sub is None:
+        sub = Subscription(tenant_id=tenant_id, plan_id=plan_id)
+        db.add(sub)
+    sub.plan_id = plan_id
+    sub.status = status
+    sub.interval = interval
+    sub.provider_subscription_id = snap.id
+    sub.quantity = max(1, snap.quantity)
+    sub.trial_end = snap.trial_end
+    sub.current_period_end = snap.current_period_end
+    sub.cancel_at_period_end = snap.cancel_at_period_end
+    sub.synced_at = datetime.now(UTC)
+    await db.flush()
+    await apply_lifecycle(db, app, sub)
+    return sub
+
+
+async def resync(
+    db: AsyncSession, app: FastAPI, provider: BillingProvider, subscription_id: str
+) -> Subscription:
+    """Re-fetch ``subscription_id`` from the provider and apply it."""
+    snapshot = await provider.fetch_subscription(subscription_id)
+    return await apply_snapshot(db, app, snapshot, provider=provider.name)

sm_billing/utils/api.test.ts

@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ApiError, api, describeError } from './api';
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe('describeError', () => {
+  it('explains the seat guard with numbers', () => {
+    expect(describeError('too_many_members', { used: 5, limit: 2 })).toBe(
+      'That plan allows 2 seats and you use 5 — remove 3 first.',
+    );
+  });
+  it('falls back for unknown codes', () => {
+    expect(describeError('weird')).toBe('Something went wrong. Please try again.');
+  });
+});
+
+describe('api', () => {
+  it('sends the CSRF header on writes only', async () => {
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify({ url: 'x' })));
+    vi.stubGlobal('fetch', fetchMock);
+    await api('/a', 'tok', { body: { plan_id: 1 } });
+    await api('/b', 'tok');
+    const [, write] = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
+    const [, read] = fetchMock.mock.calls[1] as unknown as [string, RequestInit];
+    expect((write.headers as Record<string, string>)['X-CSRF-Token']).toBe('tok');
+    expect(write.method).toBe('POST');
+    expect((read.headers as Record<string, string>)['X-CSRF-Token']).toBeUndefined();
+  });
+
+  it('throws ApiError with the server detail', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ detail: 'plan_is_free' }), { status: 400 })),
+    );
+    await expect(api('/a', 't', { body: {} })).rejects.toMatchObject({
+      status: 400,
+      detail: 'plan_is_free',
+      message: 'The free plan needs no checkout.',
+    });
+    expect(ApiError).toBeDefined();
+  });
+
+  it('reads a FastAPI validation error list', async () => {
+    const detail = [
+      { loc: ['body', 'trial_days'], msg: 'Input should be less than or equal to 730' },
+    ];
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ detail }), { status: 422 })),
+    );
+    await expect(api('/a', 't', { body: {} })).rejects.toMatchObject({
+      status: 422,
+      detail: 'validation_error',
+      message: 'trial_days: Input should be less than or equal to 730.',
+    });
+  });
+});

sm_billing/utils/api.ts

@@ -0,0 +1,95 @@
+/** fetch wrapper for the billing API: JSON in/out, CSRF header, readable errors. */
+
+const CSRF_HEADER = 'X-CSRF-Token';
+
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly detail: string,
+    public readonly body: Record<string, unknown>,
+  ) {
+    super(describeError(detail, body));
+  }
+}
+
+const MESSAGES: Record<string, string> = {
+  checkout_unavailable: 'Online payment is not set up for this site.',
+  plan_not_found: 'That plan is no longer available.',
+  plan_is_free: 'The free plan needs no checkout.',
+  interval_unavailable: 'That plan is not sold for this billing period.',
+  already_subscribed: 'You already have a subscription — change plan instead.',
+  already_on_plan: 'You are already on this plan.',
+  no_subscription: 'There is no paid subscription to change yet.',
+  no_customer: 'There is no billing account yet — subscribe to a plan first.',
+  tenant_owner_required: 'Only the organisation owner can change billing.',
+  tenant_required: 'Pick an organisation first.',
+  provider_error: 'The payment provider refused the request.',
+  provider_managed: 'Subscriptions are managed by Stripe; use Resync instead.',
+  no_provider_subscription: 'This tenant has no Stripe subscription to resync.',
+  tenant_not_found: 'That organisation no longer exists.',
+  paid_plan_needs_price: 'A paid plan needs at least one Stripe price ID.',
+  free_plan_has_price: 'Free plans have no Stripe price.',
+  free_plan_has_trial: 'Free plans have no trial.',
+  default_must_be_free: 'Only a free plan can be the default.',
+  default_required: 'Mark another free plan as default first.',
+  cannot_archive_default: 'The default plan cannot be archived.',
+  plan_key_taken: 'Another plan already uses that key.',
+  plan_key_immutable: 'A plan key cannot change once created.',
+  price_taken: 'Another plan already uses that Stripe price.',
+  price_not_found: 'Stripe has no price with that ID.',
+  invalid_return_url: 'The return URL must be an http(s) origin like https://app.example.com.',
+};
+
+export function describeError(detail: string, body: Record<string, unknown> = {}): string {
+  if (detail === 'too_many_members') {
+    const over = Number(body.used) - Number(body.limit);
+    return `That plan allows ${body.limit} seats and you use ${body.used} — remove ${over} first.`;
+  }
+  if (detail === 'validation_error' && typeof body.message === 'string') return body.message;
+  if (detail === 'price_mismatch') return `Stripe price ${body.price}: ${body.reason}.`;
+  if (detail === 'provider_error' && typeof body.message === 'string') {
+    return `${MESSAGES.provider_error} ${body.message}`;
+  }
+  return MESSAGES[detail] ?? 'Something went wrong. Please try again.';
+}
+
+/** FastAPI's 422 body: `detail` is a list of `{loc, msg}`; show the first. */
+function validationMessage(items: unknown[]): string {
+  const first = (items[0] ?? {}) as { loc?: unknown; msg?: unknown };
+  const msg = typeof first.msg === 'string' ? first.msg : 'Invalid input';
+  const field = Array.isArray(first.loc) ? first.loc[first.loc.length - 1] : undefined;
+  return field === undefined ? `${msg}.` : `${field}: ${msg}.`;
+}
+
+export async function api<T>(
+  url: string,
+  csrf: string,
+  init: { method?: string; body?: unknown } = {},
+): Promise<T> {
+  const method = init.method ?? (init.body === undefined ? 'GET' : 'POST');
+  const response = await fetch(url, {
+    method,
+    credentials: 'same-origin',
+    headers: {
+      Accept: 'application/json',
+      ...(init.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      ...(method === 'GET' ? {} : { [CSRF_HEADER]: csrf }),
+    },
+    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+  });
+  const body = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+  if (!response.ok) {
+    if (Array.isArray(body.detail)) {
+      throw new ApiError(response.status, 'validation_error', {
+        ...body,
+        message: validationMessage(body.detail),
+      });
+    }
+    const detail = typeof body.detail === 'string' ? body.detail : `http_${response.status}`;
+    throw new ApiError(response.status, detail, body);
+  }
+  return body as T;
+}
+
+export const BILLING_API = '/api/billing';
+export const ADMIN_API = '/api/billing/admin';

sm_billing/utils/format.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { formatMoney, isActivated, planCta, priceLabel, statusTone } from './format';
+import type { Plan, Status } from './types';
+
+const plan = (over: Partial<Plan> = {}): Plan => ({
+  id: 2,
+  key: 'team',
+  name: 'Team',
+  description: '',
+  pricing_model: 'flat',
+  currency: 'eur',
+  amount_month: 1900,
+  amount_year: 19000,
+  stripe_price_month: 'pm',
+  stripe_price_year: 'py',
+  trial_days: 0,
+  limits: {},
+  features: [],
+  is_default: false,
+  is_public: true,
+  sort_order: 0,
+  archived_at: null,
+  ...over,
+});
+
+const free = plan({
+  id: 1,
+  key: 'free',
+  pricing_model: 'free',
+  is_default: true,
+  stripe_price_month: null,
+  stripe_price_year: null,
+  amount_month: null,
+  amount_year: null,
+});
+
+const status = (over: Partial<Status> = {}): Status => ({
+  plan: free,
+  subscription: null,
+  seats: { used: 1, limit: null },
+  provider: 'stripe',
+  checkout_available: true,
+  portal_available: false,
+  ...over,
+});
+
+const paidSub = {
+  status: 'active' as const,
+  interval: 'month' as const,
+  quantity: 1,
+  trial_end: null,
+  current_period_end: null,
+  cancel_at_period_end: false,
+  has_provider_subscription: true,
+};
+
+describe('formatMoney', () => {
+  it('formats minor units in the plan currency', () => {
+    expect(formatMoney(1900, 'eur', 'en-US')).toBe('€19.00');
+    expect(formatMoney(0, 'usd', 'en-US')).toBe('$0.00');
+  });
+  it('returns an empty string for a missing amount', () => {
+    expect(formatMoney(null, 'eur')).toBe('');
+  });
+});
+
+describe('priceLabel', () => {
+  it('shows free plans as Free', () => {
+    expect(priceLabel(free, 'month')).toBe('Free');
+  });
+  it('adds per seat and the interval', () => {
+    const seat = plan({ pricing_model: 'per_seat' });
+    expect(priceLabel(seat, 'month', 'en-US')).toBe('€19.00 / seat / month');
+    expect(priceLabel(plan(), 'year', 'en-US')).toBe('€190.00 / year');
+  });
+  it('says when an interval is not sold', () => {
+    expect(priceLabel(plan({ stripe_price_year: null }), 'year')).toBe('Not available yearly');
+  });
+});
+
+describe('planCta', () => {
+  it('marks the plan in force as current', () => {
+    expect(planCta(status(), free, 'month')).toBe('current');
+  });
+  it('sends a free tenant to checkout', () => {
+    expect(planCta(status(), plan(), 'month')).toBe('checkout');
+  });
+  it('switches between paid plans on a live subscription', () => {
+    const s = status({ plan: plan(), subscription: paidSub });
+    expect(planCta(s, plan({ id: 3, key: 'pro' }), 'month')).toBe('change');
+    expect(planCta(s, plan(), 'year')).toBe('change');
+    expect(planCta(s, plan(), 'month')).toBe('current');
+  });
+  it('downgrades to free by cancelling at period end', () => {
+    const s = status({ plan: plan(), subscription: paidSub });
+    expect(planCta(s, free, 'month')).toBe('downgrade');
+    const ending = status({
+      plan: plan(),
+      subscription: { ...paidSub, cancel_at_period_end: true },
+    });
+    expect(planCta(ending, free, 'month')).toBe('current');
+  });
+  it('is unavailable without checkout or without a price', () => {
+    expect(planCta(status({ checkout_available: false }), plan(), 'month')).toBe('unavailable');
+    expect(planCta(status(), plan({ stripe_price_year: null }), 'year')).toBe('unavailable');
+  });
+});
+
+describe('isActivated', () => {
+  it('needs a live provider subscription, not a stale canceled one', () => {
+    expect(isActivated(status({ subscription: paidSub }))).toBe(true);
+    expect(isActivated(status({ subscription: { ...paidSub, status: 'trialing' } }))).toBe(true);
+    expect(isActivated(status({ subscription: { ...paidSub, status: 'canceled' } }))).toBe(false);
+    expect(isActivated(status())).toBe(false);
+  });
+});
+
+describe('statusTone', () => {
+  it('flags payment problems', () => {
+    expect(statusTone('past_due')).toBe('destructive');
+    expect(statusTone('unpaid')).toBe('destructive');
+    expect(statusTone('active')).toBe('default');
+    expect(statusTone(null)).toBe('outline');
+  });
+});

sm_billing/utils/format.ts

@@ -0,0 +1,91 @@
+import type { Interval, Plan, Status, SubscriptionStatus } from './types';
+
+/** Minor units → localized currency string; '' when there is no amount. */
+export function formatMoney(minor: number | null, currency: string, locale?: string): string {
+  if (minor === null || minor === undefined) return '';
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: currency.toUpperCase(),
+  }).format(minor / 100);
+}
+
+export function formatDate(iso: string | null, locale?: string): string {
+  if (!iso) return '';
+  return new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(new Date(iso));
+}
+
+export function priceFor(plan: Plan, interval: Interval): string | null {
+  return interval === 'month' ? plan.stripe_price_month : plan.stripe_price_year;
+}
+
+export function priceLabel(plan: Plan, interval: Interval, locale?: string): string {
+  if (plan.pricing_model === 'free') return 'Free';
+  if (!priceFor(plan, interval)) {
+    return interval === 'month' ? 'Not available monthly' : 'Not available yearly';
+  }
+  const amount = interval === 'month' ? plan.amount_month : plan.amount_year;
+  const money = formatMoney(amount, plan.currency, locale) || 'Paid';
+  const seat = plan.pricing_model === 'per_seat' ? ' / seat' : '';
+  return `${money}${seat} / ${interval}`;
+}
+
+const LIVE: ReadonlyArray<SubscriptionStatus> = ['active', 'trialing', 'past_due'];
+
+/**
+ * Checkout has landed: a provider subscription that grants access. Not just
+ * "has a provider id" — a tenant re-subscribing still carries their old,
+ * canceled one, which would end the wait before the new one arrived.
+ */
+export function isActivated(status: Status): boolean {
+  const sub = status.subscription;
+  return Boolean(sub?.has_provider_subscription && sub.status && LIVE.includes(sub.status));
+}
+
+/** What the plan picker's button does for ``target``. */
+export type PlanCta = 'current' | 'checkout' | 'change' | 'downgrade' | 'unavailable';
+
+export function planCta(status: Status, target: Plan, interval: Interval): PlanCta {
+  const sub = status.subscription;
+  const live =
+    sub?.has_provider_subscription &&
+    (sub.status === 'active' || sub.status === 'trialing' || sub.status === 'past_due');
+  if (target.pricing_model === 'free') {
+    if (!live) return status.plan.id === target.id ? 'current' : 'unavailable';
+    return sub?.cancel_at_period_end ? 'current' : 'downgrade';
+  }
+  if (status.plan.id === target.id && (!live || sub?.interval === interval)) {
+    if (!sub?.cancel_at_period_end) return 'current';
+  }
+  if (!status.checkout_available || !priceFor(target, interval)) return 'unavailable';
+  return live ? 'change' : 'checkout';
+}
+
+export type BadgeTone = 'default' | 'secondary' | 'destructive' | 'outline';
+
+export function statusTone(status: SubscriptionStatus | null): BadgeTone {
+  switch (status) {
+    case 'past_due':
+    case 'unpaid':
+      return 'destructive';
+    case 'active':
+    case 'trialing':
+      return 'default';
+    case null:
+      return 'outline';
+    default:
+      return 'secondary';
+  }
+}
+
+export const STATUS_LABEL: Record<SubscriptionStatus, string> = {
+  trialing: 'Trial',
+  active: 'Active',
+  past_due: 'Payment failed',
+  unpaid: 'Unpaid',
+  canceled: 'Canceled',
+  incomplete: 'Incomplete',
+};
+
+export function statusLabel(status: SubscriptionStatus | null): string {
+  return status ? STATUS_LABEL[status] : 'No subscription';
+}