@kernhq/module-billing 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-billing",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Kern billing module: plans, entitlements, subscriptions and Stripe — the mechanism that lets any Kern instance sell seats on itself",
   "homepage": "https://github.com/KernAIO/module-billing#readme",
   "license": "AGPL-3.0-only",
@@ -46,16 +46,16 @@
     "@orpc/contract": "^1.15.0",
     "@orpc/server": "^1.15.0",
     "drizzle-orm": "^0.45.0",
-    "stripe": "^22.5.0",
+    "stripe": "^22.6.0",
     "zod": "^4.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.0.0",
     "@changesets/cli": "^2.27.0",
     "@kernhq/contracts": "^0.7.0",
-    "@kernhq/kernel": "^0.7.0",
+    "@kernhq/kernel": "^0.9.1",
     "@kernhq/tsconfig": "^0.1.0",
-    "@kernhq/ui": "^0.12.5",
+    "@kernhq/ui": "^0.14.0",
     "@tanstack/svelte-query": "^6.1.0",
     "@types/node": "^24.0.0",
     "@types/pg": "^8.15.0",
@@ -68,8 +68,8 @@
   },
   "peerDependencies": {
     "@kernhq/contracts": "^0.7.0",
-    "@kernhq/kernel": "^0.7.0",
-    "@kernhq/ui": "^0.12.5",
+    "@kernhq/kernel": "^0.9.1",
+    "@kernhq/ui": "^0.14.0",
     "@tanstack/svelte-query": "^6.1.0",
     "svelte": "^5.46.0"
   },

package/src/client/i18n.ts

@@ -102,9 +102,21 @@ export const en: Record<string, Message> = {
   'billing.blocked_seats': 'This plan includes {seats} seats and this workspace has {used} members.',
   'billing.cancels': 'Ends',
   'billing.change_plan': 'Change plan',
+  'billing.checkout_cancelled': 'Checkout cancelled',
+  'billing.checkout_cancelled_hint': 'Nothing was charged, and the plan has not changed.',
+  'billing.checkout_changed': 'Plan changed',
+  'billing.checkout_done': 'Payment received',
+  'billing.checkout_done_hint': 'The new plan is active.',
+  'billing.checkout_pending': 'Payment received',
+  'billing.checkout_pending_hint':
+    'Stripe has taken the payment and we are waiting for it to confirm. This page updates itself.',
+  'billing.checkout_slow': 'Confirmation is taking longer than usual',
+  'billing.checkout_slow_hint':
+    'Stripe has taken the payment but its confirmation has not arrived. Reload in a few minutes, and contact support if the plan still has not changed.',
   'billing.choose_plan': 'Choose',
   'billing.current': 'Current',
   'billing.current_plan': 'Current plan',
+  'billing.dismiss': 'Dismiss',
   'billing.error': 'Billing could not be loaded',
   'billing.free': 'Free',
   'billing.invoice_amount': 'Amount',
@@ -127,6 +139,8 @@ export const en: Record<string, Message> = {
   'billing.per_user_month': 'per user, per month',
   'billing.per_user_year': 'per user, per year',
   'billing.per_year': 'per year',
+  'billing.plan_changed':
+    'The new plan is active. We have billed the difference for the rest of this period.',
   'billing.plan_section': 'Plan',
   'billing.renews': 'Renews',
   'billing.retry': 'Try again',
@@ -243,9 +257,20 @@ const ar: Record<string, Message> = {
   'billing.blocked_seats': 'تتضمن هذه الخطة {seats} مقعداً، ولدى مساحة العمل {used} عضواً.',
   'billing.cancels': 'تنتهي في',
   'billing.change_plan': 'تغيير الخطة',
+  'billing.checkout_cancelled': 'أُلغيت عملية الدفع',
+  'billing.checkout_cancelled_hint': 'لم يُخصم أي مبلغ، ولم تتغيّر الخطة.',
+  'billing.checkout_changed': 'تغيّرت الخطة',
+  'billing.checkout_done': 'وصلت الدفعة',
+  'billing.checkout_done_hint': 'الخطة الجديدة سارية الآن.',
+  'billing.checkout_pending': 'وصلت الدفعة',
+  'billing.checkout_pending_hint': 'استلم Stripe الدفعة وننتظر تأكيدها. تُحدِّث هذه الصفحة نفسها بنفسها.',
+  'billing.checkout_slow': 'التأكيد يستغرق وقتًا أطول من المعتاد',
+  'billing.checkout_slow_hint':
+    'استلم Stripe الدفعة لكن لم يصلنا تأكيدها. أعِد تحميل الصفحة بعد بضع دقائق، وتواصل مع الدعم إن بقيت الخطة كما هي.',
   'billing.choose_plan': 'اختيار',
   'billing.current': 'الحالية',
   'billing.current_plan': 'الخطة الحالية',
+  'billing.dismiss': 'إخفاء',
   'billing.error': 'تعذّر تحميل الفوترة',
   'billing.free': 'مجاني',
   'billing.invoice_amount': 'المبلغ',
@@ -267,6 +292,7 @@ const ar: Record<string, Message> = {
   'billing.per_user_month': 'لكل مستخدم شهرياً',
   'billing.per_user_year': 'لكل مستخدم سنوياً',
   'billing.per_year': 'سنوياً',
+  'billing.plan_changed': 'الخطة الجديدة سارية الآن، وحُسب فرق القيمة لما تبقّى من هذه الدورة.',
   'billing.plan_section': 'الخطة',
   'billing.renews': 'تتجدد في',
   'billing.retry': 'أعد المحاولة',
@@ -391,9 +417,21 @@ const de: Record<string, Message> = {
     'Dieser Tarif enthält {seats} Plätze, dieser Arbeitsbereich hat {used} Mitglieder.',
   'billing.cancels': 'Endet am',
   'billing.change_plan': 'Tarif wechseln',
+  'billing.checkout_cancelled': 'Bezahlung abgebrochen',
+  'billing.checkout_cancelled_hint': 'Es wurde nichts berechnet, und der Tarif ist unverändert.',
+  'billing.checkout_changed': 'Tarif gewechselt',
+  'billing.checkout_done': 'Zahlung eingegangen',
+  'billing.checkout_done_hint': 'Der neue Tarif ist aktiv.',
+  'billing.checkout_pending': 'Zahlung eingegangen',
+  'billing.checkout_pending_hint':
+    'Stripe hat die Zahlung angenommen, wir warten auf die Bestätigung. Diese Seite aktualisiert sich von selbst.',
+  'billing.checkout_slow': 'Die Bestätigung dauert länger als sonst',
+  'billing.checkout_slow_hint':
+    'Stripe hat die Zahlung angenommen, aber die Bestätigung ist nicht eingetroffen. Laden Sie die Seite in einigen Minuten neu und wenden Sie sich an den Support, wenn der Tarif sich immer noch nicht geändert hat.',
   'billing.choose_plan': 'Auswählen',
   'billing.current': 'Aktuell',
   'billing.current_plan': 'Aktueller Tarif',
+  'billing.dismiss': 'Ausblenden',
   'billing.error': 'Die Abrechnung konnte nicht geladen werden',
   'billing.free': 'Kostenlos',
   'billing.invoice_amount': 'Betrag',
@@ -416,6 +454,8 @@ const de: Record<string, Message> = {
   'billing.per_user_month': 'pro Person und Monat',
   'billing.per_user_year': 'pro Person und Jahr',
   'billing.per_year': 'pro Jahr',
+  'billing.plan_changed':
+    'Der neue Tarif ist aktiv. Die Differenz für den Rest dieses Zeitraums wurde berechnet.',
   'billing.plan_section': 'Tarif',
   'billing.renews': 'Verlängert am',
   'billing.retry': 'Erneut versuchen',
@@ -532,9 +572,20 @@ const fa: Record<string, Message> = {
   'billing.blocked_seats': 'این طرح {seats} کاربر دارد و این فضای کاری {used} عضو دارد.',
   'billing.cancels': 'پایان',
   'billing.change_plan': 'تغییر طرح',
+  'billing.checkout_cancelled': 'پرداخت لغو شد',
+  'billing.checkout_cancelled_hint': 'مبلغی کم نشد و طرح هم تغییری نکرد.',
+  'billing.checkout_changed': 'طرح تغییر کرد',
+  'billing.checkout_done': 'پرداخت رسید',
+  'billing.checkout_done_hint': 'طرح تازه فعال است.',
+  'billing.checkout_pending': 'پرداخت رسید',
+  'billing.checkout_pending_hint': 'Stripe پرداخت را گرفته و منتظر تأیید آن هستیم. این صفحه خودش تازه می‌شود.',
+  'billing.checkout_slow': 'تأیید بیش از حد معمول طول کشیده است',
+  'billing.checkout_slow_hint':
+    'Stripe پرداخت را گرفته اما تأیید آن نرسیده است. چند دقیقه دیگر صفحه را تازه کنید و اگر طرح همچنان تغییر نکرد با پشتیبانی تماس بگیرید.',
   'billing.choose_plan': 'انتخاب',
   'billing.current': 'کنونی',
   'billing.current_plan': 'طرح کنونی',
+  'billing.dismiss': 'بستن',
   'billing.error': 'اطلاعات پرداخت بارگذاری نشد',
   'billing.free': 'رایگان',
   'billing.invoice_amount': 'مبلغ',
@@ -556,6 +607,7 @@ const fa: Record<string, Message> = {
   'billing.per_user_month': 'برای هر کاربر، ماهانه',
   'billing.per_user_year': 'برای هر کاربر، سالانه',
   'billing.per_year': 'سالانه',
+  'billing.plan_changed': 'طرح تازه فعال است و تفاوت مبلغ برای باقی‌مانده‌ی این دوره حساب شد.',
   'billing.plan_section': 'طرح',
   'billing.renews': 'تمدید',
   'billing.retry': 'تلاش دوباره',
@@ -673,9 +725,20 @@ const tr: Record<string, Message> = {
   'billing.blocked_seats': 'Bu tarife {seats} kullanıcı içeriyor ve bu çalışma alanında {used} üye var.',
   'billing.cancels': 'Bitiş',
   'billing.change_plan': 'Tarifeyi değiştir',
+  'billing.checkout_cancelled': 'Ödeme iptal edildi',
+  'billing.checkout_cancelled_hint': 'Hiçbir ücret alınmadı ve tarife değişmedi.',
+  'billing.checkout_changed': 'Tarife değişti',
+  'billing.checkout_done': 'Ödeme alındı',
+  'billing.checkout_done_hint': 'Yeni tarife etkin.',
+  'billing.checkout_pending': 'Ödeme alındı',
+  'billing.checkout_pending_hint': 'Stripe ödemeyi aldı, onayını bekliyoruz. Bu sayfa kendini günceller.',
+  'billing.checkout_slow': 'Onay her zamankinden uzun sürüyor',
+  'billing.checkout_slow_hint':
+    'Stripe ödemeyi aldı ama onayı bize ulaşmadı. Birkaç dakika sonra sayfayı yenileyin; tarife hâlâ değişmediyse destek ekibine başvurun.',
   'billing.choose_plan': 'Seç',
   'billing.current': 'Şu anki',
   'billing.current_plan': 'Şu anki tarife',
+  'billing.dismiss': 'Kapat',
   'billing.error': 'Ödeme bilgileri yüklenemedi',
   'billing.free': 'Ücretsiz',
   'billing.invoice_amount': 'Tutar',
@@ -698,6 +761,7 @@ const tr: Record<string, Message> = {
   'billing.per_user_month': 'kullanıcı başına, aylık',
   'billing.per_user_year': 'kullanıcı başına, yıllık',
   'billing.per_year': 'yıllık',
+  'billing.plan_changed': 'Yeni tarife etkin. Bu dönemin kalanı için aradaki fark faturalandırıldı.',
   'billing.plan_section': 'Tarife',
   'billing.renews': 'Yenilenme',
   'billing.retry': 'Yeniden dene',

package/src/client/settings/PlanSettings.svelte

@@ -54,10 +54,47 @@ const { workspaceId, workspaceSlug: slug }: Props = $props()
 const canManage = $derived(session.can(BILLING_PERMISSIONS.manage))
 const locale = $derived(messageLocale())
 
+/** Where Stripe sends the person back to, and where the portal returns them. */
+const returnPath = $derived(`/${slug}/settings/billing/plan`)
+
+/**
+ * What Stripe said on the way back, from `?checkout=`.
+ *
+ * Read from `window.location` rather than the router: a module page cannot import `$app/state` — it
+ * is a SvelteKit alias, and this package is type-checked on its own. The parameter is stripped once
+ * read, so a refresh half an hour later does not announce a payment again.
+ *
+ * Nothing used to read it at all: the person came back from paying to a page that looked exactly
+ * as it had before they left, which reads as a payment that did not work.
+ */
+type Outcome = 'done' | 'cancelled' | 'changed'
+let outcome = $state<Outcome | null>(null)
+/** True between "Stripe took the card" and "the webhook told us about it". */
+let awaitingWebhook = $state(false)
+/** How long a webhook may take before the page stops promising it is coming. */
+const WEBHOOK_GRACE_MS = 90_000
+/** When waiting stops being honest. Fixed once, when the wait starts. */
+let waitDeadline = $state<number | null>(null)
+
+$effect(() => {
+  const url = new URL(window.location.href)
+  const value = url.searchParams.get('checkout')
+  if (value !== 'done' && value !== 'cancelled' && value !== 'changed') return
+  outcome = value
+  awaitingWebhook = value === 'done'
+  waitDeadline = value === 'done' ? Date.now() + WEBHOOK_GRACE_MS : null
+  url.searchParams.delete('checkout')
+  window.history.replaceState(null, '', `${url.pathname}${url.search}${url.hash}`)
+})
+
 const billing = createQuery(() => ({
   queryKey: ['billing', 'subscription', workspaceId],
   queryFn: () => api.subscription.get({ workspaceId }),
   enabled: Boolean(workspaceId),
+  // Stripe redirects the browser back before it has delivered the webhook, so the subscription is
+  // genuinely not there yet for a second or two. Polling is what turns "nothing happened" into a
+  // page that fills itself in.
+  refetchInterval: awaitingWebhook ? 3_000 : false,
 }))
 
 const plans = createQuery(() => ({
@@ -76,6 +113,46 @@ const data = $derived(billing.data)
 const sub = $derived(data?.subscription ?? null)
 const usage = $derived(data?.usage ?? { seats: 0, storageBytes: 0, updatedAt: '' })
 
+/**
+ * Stop waiting — either because the webhook landed, or because it is not going to.
+ *
+ * A poll with no end is the failure mode here: if `STRIPE_WEBHOOK_SECRET` is wrong, every delivery
+ * is rejected and the subscription never appears, so a page promising "this updates itself" refetches
+ * every three seconds for as long as the tab is open and never stops lying. The deadline is fixed
+ * when the wait starts rather than restarted here, because this effect re-runs on every poll — a
+ * timer created inside it would be cleared and rebuilt each time and could never fire.
+ */
+let webhookStalled = $state(false)
+
+$effect(() => {
+  if (!awaitingWebhook) return
+  /**
+   * `stripeSubscriptionId` is the signal, and it has to be — a status is not one.
+   *
+   * A workspace that is about to pay for the first time already has a subscription *row*: signup
+   * writes one on the default plan, `trialing`, with no Stripe subscription behind it. So "there is
+   * a row, and it is not cancelled" is true before the customer ever reaches Stripe, and waiting on
+   * it declares the payment confirmed on the first poll — which is the same lie the wait exists to
+   * avoid, told faster. `applySubscription` is what fills this column in, and it only ever runs from
+   * a webhook that verified.
+   */
+  if (sub?.stripeSubscriptionId) {
+    awaitingWebhook = false
+    return
+  }
+  const left = (waitDeadline ?? 0) - Date.now()
+  if (left <= 0) {
+    awaitingWebhook = false
+    webhookStalled = true
+    return
+  }
+  const timer = setTimeout(() => {
+    awaitingWebhook = false
+    webhookStalled = true
+  }, left)
+  return () => clearTimeout(timer)
+})
+
 const STATUS_LABEL: Record<string, () => string> = {
   trialing: () => t('status_trialing'),
   active: () => t('status_active'),
@@ -105,25 +182,56 @@ 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 reload = () => {
+  void queryClient.invalidateQueries({ queryKey: ['billing'] })
+}
+
+/**
+ * Buying a plan, or moving to another one.
+ *
+ * The server decides which of the two it is — a workspace with a subscription is repriced in place,
+ * one without goes through Checkout — and says so in `changed`. A repriced plan is already live, so
+ * there is nowhere to send the browser.
+ */
 const checkout = createMutation(() => ({
-  mutationFn: (planSlug: string) => api.subscription.checkout({ workspaceId, planSlug }),
-  onSuccess: ({ url }) => {
+  mutationFn: (planSlug: string) => api.subscription.checkout({ workspaceId, planSlug, returnPath }),
+  onSuccess: ({ url, changed }) => {
+    if (changed) {
+      toast.success(t('plan_changed'))
+      reload()
+      return
+    }
     window.location.href = url
   },
   onError: (e: Error) => toast.error(e.message),
+  onSettled: () => {
+    leaving = false
+  },
 }))
 
 const portal = createMutation(() => ({
-  mutationFn: () => api.subscription.portal({ workspaceId, returnPath: `/${slug}/settings/billing/plan` }),
+  mutationFn: () => api.subscription.portal({ workspaceId, returnPath }),
   onSuccess: ({ url }) => {
     window.location.href = url
   },
   onError: (e: Error) => toast.error(e.message),
+  onSettled: () => {
+    leaving = false
+  },
 }))
 
-const reload = () => {
-  void queryClient.invalidateQueries({ queryKey: ['billing'] })
+/**
+ * Guards the second click, which `disabled={mutation.isPending}` does not.
+ *
+ * The attribute reaches the button on the next render and two quick clicks are one render apart —
+ * on this screen that opens two Stripe Checkout sessions, or files two plan changes, each of which
+ * is a proration the customer sees on their bill.
+ */
+let leaving = $state(false)
+function once(run: () => void) {
+  if (leaving) return
+  leaving = true
+  run()
 }
 </script>
 
@@ -153,6 +261,53 @@ const reload = () => {
     <p class="text-[13px] text-[var(--kern-ink-400)]">{t('subtitle')}</p>
   </header>
 
+  <!-- What happened at Stripe. Coming back from a payment to a page that looks exactly as it did
+       before you left reads as a payment that failed, so the page says which of the three it was —
+       including the honest middle one, where the money has moved and the webhook has not landed. -->
+  {#if outcome}
+    {@const pending = outcome === 'done' && awaitingWebhook}
+    {@const stalled = outcome === 'done' && webhookStalled}
+    {@const tone =
+      outcome === 'cancelled'
+        ? 'var(--kern-slate-tint)'
+        : stalled
+          ? 'var(--kern-warning-tint)'
+          : pending
+            ? 'var(--kern-info-tint)'
+            : 'var(--kern-success-tint)'}
+    <div
+      class="flex items-start justify-between gap-3 rounded-[var(--kern-r-sm)] px-3 py-2.5"
+      style="background: {tone}"
+      role="status"
+    >
+      <div class="grid gap-0.5">
+        <span class="text-[13px] font-medium text-[var(--kern-ink-900)]">
+          {outcome === 'cancelled'
+            ? t('checkout_cancelled')
+            : outcome === 'changed'
+              ? t('checkout_changed')
+              : stalled
+                ? t('checkout_slow')
+                : pending
+                  ? t('checkout_pending')
+                  : t('checkout_done')}
+        </span>
+        <span class="text-[13px] text-[var(--kern-ink-700)]">
+          {outcome === 'cancelled'
+            ? t('checkout_cancelled_hint')
+            : outcome === 'changed'
+              ? t('plan_changed')
+              : stalled
+                ? t('checkout_slow_hint')
+                : pending
+                  ? t('checkout_pending_hint')
+                  : t('checkout_done_hint')}
+        </span>
+      </div>
+      <Button variant="ghost" size="sm" onclick={() => (outcome = null)}>{t('dismiss')}</Button>
+    </div>
+  {/if}
+
   {#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)]" />
@@ -202,7 +357,7 @@ const reload = () => {
                     variant="secondary"
                     disabled={!canManage || portal.isPending}
                     loading={portal.isPending}
-                    onclick={() => portal.mutate()}
+                    onclick={() => once(() => portal.mutate())}
                   >
                     {t('manage_payment')}
                   </Button>
@@ -295,7 +450,7 @@ const reload = () => {
                       variant={isCurrent ? 'secondary' : 'primary'}
                       disabled={isCurrent || !canManage || blocked !== null || checkout.isPending}
                       loading={checkout.isPending && checkout.variables === plan.slug}
-                      onclick={() => checkout.mutate(plan.slug)}
+                      onclick={() => once(() => checkout.mutate(plan.slug))}
                     >
                       {isCurrent ? t('current') : t('choose_plan')}
                     </Button>

package/src/contract.ts

@@ -224,11 +224,30 @@ export const billingContract = {
       .route({ method: 'GET', path: '/subscription/invoices', tags: ['billing'] })
       .input(ws.extend(PageInput.shape))
       .output(page(Invoice)),
-    /** Stripe Checkout for a new subscription or a plan change; returns a URL to send the user to. */
+    /**
+     * Buy a plan, or move to a different one.
+     *
+     * Two different acts behind one procedure, because the caller does not know which it is: a
+     * workspace with no Stripe subscription needs Checkout (a card has to be collected), and one
+     * that already has a subscription needs its existing subscription repriced — opening a second
+     * Checkout there leaves the first subscription running and bills the customer twice.
+     *
+     * `changed` says which happened. When it is true the plan is already live and `url` is simply
+     * where to send the person back to; when it is false `url` is Stripe's hosted Checkout.
+     *
+     * `returnPath` is the workspace-relative path to come back to, exactly as `portal` takes it —
+     * billing knows workspace ids and not slugs, so the caller supplies the route.
+     */
     checkout: baseContract
       .route({ method: 'POST', path: '/subscription/checkout', tags: ['billing'] })
-      .input(ws.extend({ planSlug: z.string(), seats: z.number().int().positive().optional() }))
-      .output(z.object({ url: z.string() })),
+      .input(
+        ws.extend({
+          planSlug: z.string(),
+          seats: z.number().int().positive().optional(),
+          returnPath: z.string().default('/'),
+        }),
+      )
+      .output(z.object({ url: z.string(), changed: z.boolean().default(false) })),
     /** Stripe's own billing portal: payment method, cancellation, invoice download. */
     portal: baseContract
       .route({ method: 'POST', path: '/subscription/portal', tags: ['billing'] })