@kernhq/module-billing 0.2.0 → 0.3.0

package/src/client/mock.ts

@@ -0,0 +1,222 @@
+import type { AdminWorkspaceRow, BillingApi, Invoice, Plan, Subscription, WorkspaceBilling } from './index.js'
+
+/**
+ * Billing with no backend, for `pnpm dev:mock` and the end-to-end tests.
+ *
+ * It satisfies the same contract types as the real client, so no view has a second code path for
+ * demos. What it deliberately does *not* do is take a payment: `checkout` and `portal` throw, because
+ * the one thing a demo must never be able to imply is that money moved.
+ */
+
+const GB = 1024 ** 3
+const iso = (daysFromNow: number) => new Date(Date.now() + daysFromNow * 86_400_000).toISOString()
+
+let plans: Plan[] = [
+  {
+    id: 'plan-team',
+    slug: 'team',
+    name: 'Team',
+    description: 'The same Kern, run by us.',
+    priceMinor: 800,
+    currency: 'usd',
+    interval: 'month',
+    perSeat: true,
+    trialDays: 14,
+    limits: {
+      seats: 25,
+      storageBytes: 50 * GB,
+      modules: null,
+      sso: false,
+      auditRetentionDays: 90,
+      apiRateLimit: null,
+    },
+    stripePriceId: 'price_demo_team',
+    highlights: ['Everything in self-hosted', 'Daily backups, kept 30 days'],
+    published: true,
+    order: 10,
+    createdAt: iso(-40),
+    updatedAt: iso(-2),
+  },
+  {
+    id: 'plan-business',
+    slug: 'business',
+    name: 'Business',
+    description: 'For companies with a compliance team.',
+    priceMinor: 1600,
+    currency: 'usd',
+    interval: 'month',
+    perSeat: true,
+    trialDays: 14,
+    limits: {
+      seats: null,
+      storageBytes: 250 * GB,
+      modules: null,
+      sso: true,
+      auditRetentionDays: 730,
+      apiRateLimit: null,
+    },
+    stripePriceId: 'price_demo_business',
+    highlights: ['Everything in Team', 'SSO over OIDC and SAML'],
+    published: true,
+    order: 20,
+    createdAt: iso(-40),
+    updatedAt: iso(-2),
+  },
+]
+
+const subscription: Subscription = {
+  workspaceId: 'ws-demo' as Subscription['workspaceId'],
+  planId: 'plan-team',
+  planName: 'Team',
+  planSlug: 'team',
+  status: 'trialing',
+  seatsPurchased: 12,
+  trialEndsAt: iso(9),
+  currentPeriodEnd: iso(21),
+  cancelAtPeriodEnd: false,
+  stripeCustomerId: 'cus_demo',
+  stripeSubscriptionId: 'sub_demo',
+}
+
+const invoices: Invoice[] = [
+  {
+    id: 'inv-2',
+    workspaceId: subscription.workspaceId,
+    number: 'KERN-0002',
+    status: 'paid',
+    totalMinor: 9600,
+    currency: 'usd',
+    periodStart: iso(-30),
+    periodEnd: iso(0),
+    hostedUrl: null,
+    pdfUrl: null,
+    createdAt: iso(-30),
+  },
+  {
+    id: 'inv-1',
+    workspaceId: subscription.workspaceId,
+    number: 'KERN-0001',
+    status: 'paid',
+    totalMinor: 8800,
+    currency: 'usd',
+    periodStart: iso(-60),
+    periodEnd: iso(-30),
+    hostedUrl: null,
+    pdfUrl: null,
+    createdAt: iso(-60),
+  },
+]
+
+const adminRows: AdminWorkspaceRow[] = [
+  {
+    workspaceId: 'ws-demo' as AdminWorkspaceRow['workspaceId'],
+    workspaceName: 'Acme',
+    workspaceSlug: 'acme',
+    planName: 'Team',
+    planSlug: 'team',
+    status: 'trialing',
+    seatsUsed: 12,
+    seatsPurchased: 12,
+    storageBytes: 18 * GB,
+    trialEndsAt: iso(9),
+    currentPeriodEnd: iso(21),
+    monthlyMinor: 9600,
+    currency: 'usd',
+    overridden: false,
+    stripeCustomerId: 'cus_demo',
+  },
+  {
+    workspaceId: 'ws-two' as AdminWorkspaceRow['workspaceId'],
+    workspaceName: 'Northwind',
+    workspaceSlug: 'northwind',
+    planName: 'Business',
+    planSlug: 'business',
+    status: 'active',
+    seatsUsed: 48,
+    seatsPurchased: 50,
+    storageBytes: 190 * GB,
+    trialEndsAt: null,
+    currentPeriodEnd: iso(12),
+    monthlyMinor: 80000,
+    currency: 'usd',
+    overridden: true,
+    stripeCustomerId: 'cus_demo2',
+  },
+  {
+    workspaceId: 'ws-three' as AdminWorkspaceRow['workspaceId'],
+    workspaceName: 'Tiny Studio',
+    workspaceSlug: 'tiny',
+    planName: null,
+    planSlug: null,
+    status: 'past_due',
+    seatsUsed: 3,
+    seatsPurchased: 3,
+    storageBytes: 2 * GB,
+    trialEndsAt: null,
+    currentPeriodEnd: iso(-4),
+    monthlyMinor: 2400,
+    currency: 'usd',
+    overridden: false,
+    stripeCustomerId: null,
+  },
+]
+
+const notInDemo = (what: string) => {
+  throw new Error(`${what} is not available without a backend`)
+}
+
+export function createMockBillingApi(): BillingApi {
+  return {
+    plans: {
+      list: async ({ includeUnpublished }: { includeUnpublished?: boolean }) =>
+        includeUnpublished ? plans : plans.filter((p) => p.published),
+      public: async () => plans.filter((p) => p.published),
+      upsert: async (input: Record<string, unknown>) => {
+        const next = {
+          ...(input as Plan),
+          id: (input.id as string) ?? `plan-${plans.length + 1}`,
+          createdAt: iso(0),
+          updatedAt: iso(0),
+        }
+        plans = plans.some((p) => p.id === next.id)
+          ? plans.map((p) => (p.id === next.id ? next : p))
+          : [...plans, next]
+        return next
+      },
+      setPublished: async ({ id, published }: { id: string; published: boolean }) => {
+        plans = plans.map((p) => (p.id === id ? { ...p, published } : p))
+        return plans.find((p) => p.id === id)!
+      },
+      archive: async ({ id }: { id: string }) => {
+        plans = plans.filter((p) => p.id !== id)
+        return { ok: true as const }
+      },
+    },
+    subscription: {
+      get: async (): Promise<WorkspaceBilling> => ({
+        subscription,
+        usage: { seats: 12, storageBytes: 18 * GB, updatedAt: iso(0) },
+        limits: plans[0]!.limits,
+        active: true,
+        // true, so the demo shows the plan picker rather than the "not set up" note; the checkout
+        // itself still refuses
+        paymentsEnabled: true,
+      }),
+      invoices: async () => ({ items: invoices, nextCursor: null }),
+      checkout: async () => notInDemo('Checkout'),
+      portal: async () => notInDemo('The billing portal'),
+    },
+    admin: {
+      workspaces: async ({ q }: { q?: string }) => ({
+        items: q
+          ? adminRows.filter((r) => r.workspaceName.toLowerCase().includes(q.toLowerCase()))
+          : adminRows,
+        nextCursor: null,
+      }),
+      setPlan: async () => subscription,
+      override: async () => subscription,
+      extendTrial: async () => subscription,
+      setStatus: async () => subscription,
+    },
+  } as unknown as BillingApi
+}

package/src/client/module.ts

@@ -0,0 +1,60 @@
+import { defineClientModule } from '@kernhq/ui'
+import { BILLING_PERMISSIONS } from '../contract.js'
+import { billingMessageBundles, t } from './i18n.js'
+
+/**
+ * Billing as the shell sees it.
+ *
+ * No navigation: what a workspace pays is not somewhere people go, it is somewhere an owner goes
+ * once a month. One workspace settings page for the customer, and two instance pages for whoever
+ * runs the instance — which on a self-hosted Kern is the same person, and on Kern Cloud is us.
+ *
+ * The instance pages carry no `capability` and are not filtered on whether this workspace has
+ * billing enabled: the console is not about a workspace, and an operator looking at what every
+ * workspace is billed must still see the screen from a workspace that has it switched off.
+ *
+ * Labels are getters because a module is defined once at import time while the interface language
+ * can change afterwards; reading them on render keeps them in the language actually chosen.
+ */
+export const billingClientModule = defineClientModule({
+  id: 'billing',
+  name: 'Billing',
+  icon: 'credit-card',
+  messages: billingMessageBundles,
+
+  settingsPages: [
+    {
+      id: 'plan',
+      get label() {
+        return t('settings_nav')
+      },
+      icon: 'credit-card',
+      scope: 'workspace',
+      permission: BILLING_PERMISSIONS.view,
+      order: 60,
+      component: () => import('./settings/PlanSettings.svelte'),
+    },
+    {
+      id: 'subscriptions',
+      get label() {
+        return t('admin_subscriptions_nav')
+      },
+      icon: 'credit-card',
+      scope: 'instance',
+      order: 20,
+      component: () => import('./admin/SubscriptionsAdmin.svelte'),
+    },
+    {
+      id: 'plans',
+      get label() {
+        return t('admin_plans_nav')
+      },
+      icon: 'tag',
+      scope: 'instance',
+      order: 30,
+      component: () => import('./admin/PlansAdmin.svelte'),
+    },
+  ],
+})
+
+export default billingClientModule

package/src/client/settings/PlanSettings.svelte

@@ -0,0 +1,356 @@
+<script lang="ts">
+import {
+  Badge,
+  Button,
+  Card,
+  EmptyState,
+  messageLocale,
+  ProgressBar,
+  Skeleton,
+  session,
+  Table,
+  TableCell,
+  TableHeader,
+  TableRow,
+  Tooltip,
+  toast,
+} from '@kernhq/ui'
+import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { getBillingApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import type { Plan } from '../index.js'
+import {
+  BILLING_PERMISSIONS,
+  formatBytes,
+  formatMoney,
+  planBlockedReason,
+  trialDaysLeft,
+  usageRatio,
+} from '../index.js'
+
+/**
+ * What this workspace is on, what it uses, and what it has been charged.
+ *
+ * Everything money-shaped is read from the server rather than worked out here: a second opinion
+ * about somebody's bill, computed in a browser, is the one kind of disagreement this screen must not
+ * be able to have.
+ */
+
+const api = getBillingApi()
+const queryClient = useQueryClient()
+
+/**
+ * The shell passes these; a module page does not read the router.
+ *
+ * `$app/state` is a SvelteKit alias, and a package is type-checked on its own — reaching for the
+ * router here fails standalone even though it resolves inside the app. `ModuleRoute` already hands
+ * every module page the workspace it is rendering.
+ */
+interface Props {
+  workspaceId: string
+  workspaceSlug: string
+}
+const { workspaceId, workspaceSlug: slug }: Props = $props()
+const canManage = $derived(session.can(BILLING_PERMISSIONS.manage))
+const locale = $derived(messageLocale())
+
+const billing = createQuery(() => ({
+  queryKey: ['billing', 'subscription', workspaceId],
+  queryFn: () => api.subscription.get({ workspaceId }),
+  enabled: Boolean(workspaceId),
+}))
+
+const plans = createQuery(() => ({
+  queryKey: ['billing', 'plan', 'offered'],
+  queryFn: () => api.plans.list({ includeUnpublished: false }),
+  enabled: Boolean(workspaceId),
+}))
+
+const invoices = createQuery(() => ({
+  queryKey: ['billing', 'invoice', workspaceId],
+  queryFn: () => api.subscription.invoices({ workspaceId, limit: 24 }),
+  enabled: Boolean(workspaceId),
+}))
+
+const data = $derived(billing.data)
+const sub = $derived(data?.subscription ?? null)
+const usage = $derived(data?.usage ?? { seats: 0, storageBytes: 0, updatedAt: '' })
+
+const STATUS_LABEL: Record<string, () => string> = {
+  trialing: () => t('status_trialing'),
+  active: () => t('status_active'),
+  past_due: () => t('status_past_due'),
+  canceled: () => t('status_canceled'),
+  suspended: () => t('status_suspended'),
+}
+const STATUS_TONE: Record<string, 'info' | 'success' | 'warning' | 'danger' | 'grey'> = {
+  trialing: 'info',
+  active: 'success',
+  past_due: 'warning',
+  canceled: 'grey',
+  suspended: 'danger',
+}
+
+const trialLeft = $derived(trialDaysLeft(sub?.trialEndsAt ?? null))
+
+function priceNote(plan: Plan): string {
+  if (plan.priceMinor === 0) return t('free')
+  if (plan.interval === 'year') return plan.perSeat ? t('per_user_year') : t('per_year')
+  return plan.perSeat ? t('per_user_month') : t('per_month')
+}
+
+// every number a person reads goes through Intl, counts included — a Latin seat count beside a
+// Persian byte count is the one untranslated thing on the screen
+const nf = $derived(new Intl.NumberFormat(locale))
+const dateFmt = $derived(new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }))
+const day = (iso: string | null) => (iso ? dateFmt.format(new Date(iso)) : '—')
+
+/** Sends the person to Stripe. Kept as a mutation so the button can show it is working. */
+const checkout = createMutation(() => ({
+  mutationFn: (planSlug: string) => api.subscription.checkout({ workspaceId, planSlug }),
+  onSuccess: ({ url }) => {
+    window.location.href = url
+  },
+  onError: (e: Error) => toast.error(e.message),
+}))
+
+const portal = createMutation(() => ({
+  mutationFn: () => api.subscription.portal({ workspaceId, returnPath: `/${slug}/settings/billing/plan` }),
+  onSuccess: ({ url }) => {
+    window.location.href = url
+  },
+  onError: (e: Error) => toast.error(e.message),
+}))
+
+const reload = () => {
+  void queryClient.invalidateQueries({ queryKey: ['billing'] })
+}
+</script>
+
+<svelte:head><title>{t('title')} · {t('common.settings')}</title></svelte:head>
+
+<!-- `limit` is already formatted by the caller: bytes have to arrive as "50 GB", never as the
+     number itself, and a snippet that took a number could not tell the two apart. -->
+{#snippet meter(label: string, used: string, limit: string | null, ratio: number | null)}
+  <div class="grid gap-1.5">
+    <div class="flex items-baseline justify-between gap-3">
+      <span class="text-[13px] text-[var(--kern-ink-700)]">{label}</span>
+      <span class="font-[var(--kern-font-mono)] text-[12px] text-[var(--kern-ink-400)]">
+        {limit === null ? used : t('usage_of', { used, limit })}
+      </span>
+    </div>
+    {#if ratio === null}
+      <div class="text-[12px] text-[var(--kern-ink-400)]">{t('unlimited')}</div>
+    {:else}
+      <ProgressBar value={ratio * 100} tone={ratio >= 1 ? 'danger' : ratio > 0.85 ? 'info' : 'accent'} />
+    {/if}
+  </div>
+{/snippet}
+
+<div class="grid gap-6">
+  <header class="grid gap-1">
+    <h1 class="text-[20px] font-medium text-[var(--kern-ink-900)]">{t('title')}</h1>
+    <p class="text-[13px] text-[var(--kern-ink-400)]">{t('subtitle')}</p>
+  </header>
+
+  {#if billing.isPending}
+    <Skeleton class="h-[132px] w-full rounded-[var(--kern-r-md)]" />
+    <Skeleton class="h-[180px] w-full rounded-[var(--kern-r-md)]" />
+  {:else if billing.isError}
+    <EmptyState title={t('error')} icon="triangle-alert">
+      {#snippet actions()}
+        <Button variant="secondary" onclick={reload}>{t('retry')}</Button>
+      {/snippet}
+    </EmptyState>
+  {:else}
+    <!-- current plan -->
+    <Card>
+      <div class="grid gap-4 p-5">
+        <div class="flex flex-wrap items-start justify-between gap-3">
+          <div class="grid gap-1">
+            <span class="text-[12px] text-[var(--kern-ink-400)]">{t('current_plan')}</span>
+            <div class="flex items-center gap-2">
+              <span class="text-[17px] font-medium text-[var(--kern-ink-900)]">
+                {sub?.planName ?? t('no_plan')}
+              </span>
+              {#if sub}
+                <Badge tone={STATUS_TONE[sub.status] ?? 'grey'}>
+                  {(STATUS_LABEL[sub.status] ?? (() => t('status_active')))()}
+                </Badge>
+              {/if}
+            </div>
+            {#if !sub}
+              <p class="text-[13px] text-[var(--kern-ink-400)]">{t('no_plan_hint')}</p>
+            {:else if sub.status === 'trialing' && trialLeft !== null}
+              <p class="text-[13px] text-[var(--kern-ink-400)]">
+                {trialLeft === 0 ? t('trial_ends_today') : t('trial_days_left', { count: trialLeft })}
+              </p>
+            {:else if sub.currentPeriodEnd}
+              <p class="text-[13px] text-[var(--kern-ink-400)]">
+                {sub.cancelAtPeriodEnd ? t('cancels') : t('renews')}
+                {day(sub.currentPeriodEnd)}
+              </p>
+            {/if}
+          </div>
+
+          {#if data?.paymentsEnabled && sub?.stripeCustomerId}
+            <!-- disabled controls say why: a dead button with no explanation is a bug -->
+            <Tooltip text={t('no_permission')} disabled={canManage}>
+              {#snippet children(props)}
+                <span {...props}>
+                  <Button
+                    variant="secondary"
+                    disabled={!canManage || portal.isPending}
+                    loading={portal.isPending}
+                    onclick={() => portal.mutate()}
+                  >
+                    {t('manage_payment')}
+                  </Button>
+                </span>
+              {/snippet}
+            </Tooltip>
+          {/if}
+        </div>
+
+        {#if sub?.status === 'past_due'}
+          <p class="rounded-[var(--kern-r-sm)] bg-[var(--kern-warning-tint)] px-3 py-2 text-[13px] text-[var(--kern-ink-900)]">
+            {t('past_due_hint')}
+          </p>
+        {:else if sub?.status === 'suspended'}
+          <p class="rounded-[var(--kern-r-sm)] bg-[var(--kern-danger-tint)] px-3 py-2 text-[13px] text-[var(--kern-ink-900)]">
+            {t('suspended_hint')}
+          </p>
+        {/if}
+
+        <div class="grid gap-4 sm:grid-cols-2">
+          {@render meter(
+            t('seats'),
+            nf.format(usage.seats),
+            data?.limits.seats == null ? null : nf.format(data.limits.seats),
+            usageRatio(usage.seats, data?.limits.seats ?? null),
+          )}
+          {@render meter(
+            t('storage'),
+            formatBytes(usage.storageBytes, locale),
+            data?.limits.storageBytes == null ? null : formatBytes(data.limits.storageBytes, locale),
+            usageRatio(usage.storageBytes, data?.limits.storageBytes ?? null),
+          )}
+        </div>
+      </div>
+    </Card>
+
+    <!-- what can be bought -->
+    {#if !data?.paymentsEnabled}
+      <p class="text-[13px] text-[var(--kern-ink-400)]">{t('payments_disabled')}</p>
+    {:else if plans.isPending}
+      <Skeleton class="h-[160px] w-full rounded-[var(--kern-r-md)]" />
+    {:else if (plans.data ?? []).length === 0}
+      <EmptyState title={t('no_plans')} description={t('no_plans_hint')} icon="tag" />
+    {:else}
+      <!-- `grid-auto-rows:1fr` + `display:grid` on the cell, so a longer description does not leave
+           the card beside it visibly short -->
+      <ul class="grid gap-3 sm:grid-cols-2 lg:grid-cols-3" style="grid-auto-rows: 1fr">
+        {#each plans.data ?? [] as plan (plan.id)}
+          {@const isCurrent = sub?.planId === plan.id}
+          {@const blocked = planBlockedReason(plan, { seats: usage.seats })}
+          <li class="grid">
+            <Card class="grid content-between gap-4 p-4">
+              <div class="grid gap-2">
+                <div class="flex items-center justify-between gap-2">
+                  <span class="text-[15px] font-medium text-[var(--kern-ink-900)]">{plan.name}</span>
+                  {#if isCurrent}<Badge tone="accent">{t('current')}</Badge>{/if}
+                </div>
+                <div class="flex items-baseline gap-1.5">
+                  <span class="text-[22px] font-medium text-[var(--kern-ink-900)]">
+                    {formatMoney(plan.priceMinor, plan.currency, locale)}
+                  </span>
+                  <span class="text-[12px] text-[var(--kern-ink-400)]">{priceNote(plan)}</span>
+                </div>
+                {#if plan.description}
+                  <p class="text-[13px] text-[var(--kern-ink-700)]">{plan.description}</p>
+                {/if}
+                {#if plan.highlights.length}
+                  <ul class="mt-1 grid gap-1">
+                    {#each plan.highlights as h (h)}
+                      <li class="text-[12.5px] text-[var(--kern-ink-700)]">{h}</li>
+                    {/each}
+                  </ul>
+                {/if}
+              </div>
+              <!-- A plan smaller than the workspace names the number it cannot fit, rather than
+                   refusing on submit with nothing to act on. -->
+              <Tooltip
+                text={blocked === 'seats'
+                  ? t('blocked_seats', {
+                      seats: nf.format(plan.limits.seats ?? 0),
+                      used: nf.format(usage.seats),
+                    })
+                  : t('no_permission')}
+                disabled={blocked === null && canManage}
+              >
+                {#snippet children(props)}
+                  <span class="block w-full" {...props}>
+                    <Button
+                      class="w-full"
+                      variant={isCurrent ? 'secondary' : 'primary'}
+                      disabled={isCurrent || !canManage || blocked !== null || checkout.isPending}
+                      loading={checkout.isPending && checkout.variables === plan.slug}
+                      onclick={() => checkout.mutate(plan.slug)}
+                    >
+                      {isCurrent ? t('current') : t('choose_plan')}
+                    </Button>
+                  </span>
+                {/snippet}
+              </Tooltip>
+            </Card>
+          </li>
+        {/each}
+      </ul>
+    {/if}
+
+    <!-- invoices -->
+    <section class="grid gap-2">
+      <h2 class="text-[14px] font-medium text-[var(--kern-ink-900)]">{t('invoices_section')}</h2>
+      {#if invoices.isPending}
+        <Skeleton class="h-[96px] w-full rounded-[var(--kern-r-md)]" />
+      {:else if (invoices.data?.items ?? []).length === 0}
+        <EmptyState
+          title={t('invoices_empty')}
+          description={t('invoices_empty_hint')}
+          icon="file-text"
+          compact
+        />
+      {:else}
+        <div class="overflow-x-auto">
+          <Table columns="minmax(120px,1fr) minmax(120px,1fr) minmax(100px,auto) minmax(80px,auto)">
+            <TableHeader>
+              <TableCell header>{t('invoice_number')}</TableCell>
+              <TableCell header>{t('invoice_date')}</TableCell>
+              <TableCell header end>{t('invoice_amount')}</TableCell>
+              <TableCell header end></TableCell>
+            </TableHeader>
+            {#each invoices.data?.items ?? [] as inv (inv.id)}
+              <TableRow>
+                <TableCell>{inv.number ?? '—'}</TableCell>
+                <TableCell>{day(inv.createdAt)}</TableCell>
+                <TableCell end>{formatMoney(inv.totalMinor, inv.currency, locale)}</TableCell>
+                <TableCell end>
+                  {#if inv.hostedUrl}
+                    <a
+                      class="text-[13px] text-[var(--kern-accent-deep)] underline-offset-2 hover:underline"
+                      href={inv.hostedUrl}
+                      target="_blank"
+                      rel="noreferrer noopener"
+                    >
+                      {t('invoice_view')}
+                    </a>
+                  {/if}
+                </TableCell>
+              </TableRow>
+            {/each}
+          </Table>
+        </div>
+      {/if}
+    </section>
+  {/if}
+</div>