@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

package/packages/bundled-features/src/billing-foundation/plan-catalog.ts

@@ -6,12 +6,14 @@
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { isPluginBillingEnabled } from "./checkout-core.ts";
 import { getSubscriptionForTenant } from "./get-subscription-for-tenant.ts";
-import type {
-  BillingPlanCatalog,
-  BillingPlansResult,
-  BillingPlanView,
-  ProviderPrice,
-  SubscriptionProviderPlugin,
+import {
+  type BillingPlanCatalog,
+  type BillingPlansResult,
+  type BillingPlanView,
+  canSwitchPlans,
+  canSwitchPlansInApp,
+  type ProviderPrice,
+  type SubscriptionProviderPlugin,
 } from "./types.ts";
 import {
   BillingPlanActions,
@@ -51,7 +53,7 @@ function invertPriceToTier(
   return byTier;
 }
 
-type ResolvedPlanPrice = { readonly priceId: string; readonly price: ProviderPrice } | null;
+export type ResolvedPlanPrice = { readonly priceId: string; readonly price: ProviderPrice } | null;
 
 /** Resolves one active, flat-amount price per plan tier. 0 or >1 active
  *  flat-amount prices for a tier is ambiguous — the caller can't tell which
@@ -120,7 +122,7 @@ function canSwitchToTier(
     isSwitchableSubscriptionStatus(subscription.status) &&
     tier !== subscription.tier &&
     subscription.cancelAt === null &&
-    plugin?.createPlanSwitchSession !== undefined
+    canSwitchPlans(plugin)
   );
 }
 
@@ -157,37 +159,60 @@ function resolvePlanAction(
     : BillingPlanActions.unavailable;
 }
 
-/** `plugin === null` — no provider is registered/resolvable for this
- *  catalog (see checkout-core's `findCatalogProvider`) — collapses onto the
- *  same "enabled: false" result a disabled provider produces, rather than
- *  a separate error shape the panel would need to special-case. */
-export async function buildBillingPlans(
+/** Tenant-level state every provider's plan list is measured against; loaded
+ *  once so a multi-provider result does not repeat the reads per provider. */
+export type BillingPlansBase = {
+  readonly currentTierValue: string;
+  readonly subscriptionView: Awaited<ReturnType<typeof getSubscriptionForTenant>>;
+  readonly subscription: BillingPlansResult["subscription"];
+  readonly blockingSubscription: boolean;
+  readonly canPurchase: boolean;
+};
+
+export async function loadBillingPlansBase(
   ctx: HandlerContext,
-  plugin: SubscriptionProviderPlugin | null,
   catalog: BillingPlanCatalog,
   now: () => Temporal.Instant,
-): Promise<BillingPlansResult> {
+): Promise<BillingPlansBase> {
   const currentTierValue = await catalog.resolveCurrentTier(ctx.db, ctx.user.tenantId);
-  const enabled = plugin !== null && (await isPluginBillingEnabled(ctx, plugin));
-  const resolvedPrices =
-    enabled && plugin
-      ? await resolvePlanPrices(ctx, plugin, catalog)
-      : new Map<string, ResolvedPlanPrice>(catalog.plans.map((tier) => [tier, null]));
-
   const subscriptionView = await getSubscriptionForTenant(ctx, ctx.user.tenantId);
-  const nowInstant = now();
+  const blockingSubscription =
+    subscriptionView !== null && isSubscriptionBlockingCheckout(subscriptionView, now());
   const subscription = subscriptionView
     ? {
         status: subscriptionView.status,
         tier: subscriptionView.tier,
-        terminal: !isSubscriptionBlockingCheckout(subscriptionView, nowInstant),
+        terminal: !blockingSubscription,
         currentPeriodEnd: subscriptionView.currentPeriodEnd.toString(),
         cancelAt: subscriptionView.cancelAt?.toString() ?? null,
       }
     : null;
+  const canPurchase = userHasAnyRole(ctx.user.roles, purchaseRolesOf(catalog));
+  return { currentTierValue, subscriptionView, subscription, blockingSubscription, canPurchase };
+}
+
+export type ProviderPlanViews = {
+  readonly enabled: boolean;
+  readonly inAppSwitch: boolean;
+  readonly plans: readonly BillingPlanView[];
+};
 
-  const purchaseRoles = purchaseRolesOf(catalog);
-  const canPurchase = userHasAnyRole(ctx.user.roles, purchaseRoles);
+/** `plugin === null` — no provider is registered/resolvable for this
+ *  catalog (see checkout-core's `listCatalogProviders`) — collapses onto the
+ *  same "enabled: false" result a disabled provider produces, rather than
+ *  a separate error shape the panel would need to special-case. */
+export async function buildProviderPlanViews(
+  ctx: HandlerContext,
+  plugin: SubscriptionProviderPlugin | null,
+  catalog: BillingPlanCatalog,
+  base: BillingPlansBase,
+): Promise<ProviderPlanViews> {
+  const { currentTierValue, subscription, canPurchase } = base;
+  const enabled = plugin !== null && (await isPluginBillingEnabled(ctx, plugin));
+  const resolvedPrices =
+    enabled && plugin
+      ? await resolvePlanPrices(ctx, plugin, catalog)
+      : new Map<string, ResolvedPlanPrice>(catalog.plans.map((tier) => [tier, null]));
 
   const plans: BillingPlanView[] = catalog.plans.map((tier) => {
     const isCurrent = tier === currentTierValue;
@@ -221,8 +246,17 @@ export async function buildBillingPlans(
     };
   });
 
+  return { enabled, inAppSwitch: plugin !== null && canSwitchPlansInApp(plugin), plans };
+}
+
+export function toBillingPlansResult(
+  catalog: BillingPlanCatalog,
+  base: BillingPlansBase,
+  views: ProviderPlanViews,
+): BillingPlansResult {
+  const { currentTierValue, subscription, canPurchase } = base;
   return {
-    enabled,
+    enabled: views.enabled,
     currentTier: {
       tier: currentTierValue,
       labelKey: catalog.tierLabelKey(currentTierValue),
@@ -230,7 +264,8 @@ export async function buildBillingPlans(
     },
     subscription,
     canPurchase,
-    plans,
+    plans: views.plans,
+    ...(views.inAppSwitch && { inAppPlanSwitch: true as const }),
     ...(catalog.contact !== undefined && { contact: catalog.contact }),
   };
 }

package/packages/bundled-features/src/billing-foundation/plan-switch.ts

@@ -0,0 +1,84 @@
+// Pre-checks shared by switch-plan and plan-switch-preview: both must agree on
+// which subscription, provider and target price a plan switch means.
+// Internal — not re-exported from index.ts.
+
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { ConflictError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  assertBillingEnabled,
+  findProviderPlugin,
+  listCatalogProviders,
+  type ResolvedProvider,
+} from "./checkout-core.ts";
+import { getSubscriptionForTenant, type SubscriptionView } from "./get-subscription-for-tenant.ts";
+import { type ResolvedPlanPrice, resolvePlanPrices } from "./plan-catalog.ts";
+import { type BillingPlanCatalog, canSwitchPlans } from "./types.ts";
+import { isSwitchableSubscriptionStatus } from "./web/constants.ts";
+
+export type PreparedPlanSwitch = {
+  readonly provider: ResolvedProvider;
+  readonly subscription: SubscriptionView;
+  readonly target: NonNullable<ResolvedPlanPrice>;
+  readonly allowedPriceIds: readonly string[];
+};
+
+export async function preparePlanSwitch(
+  ctx: HandlerContext,
+  catalog: BillingPlanCatalog,
+  tier: string,
+  handlerName: string,
+): Promise<PreparedPlanSwitch> {
+  const subscription = await getSubscriptionForTenant(ctx, ctx.user.tenantId);
+  if (!subscription || !isSwitchableSubscriptionStatus(subscription.status)) {
+    throw new ConflictError({
+      i18nKey: "billing-foundation.errors.noActiveSubscription",
+      message:
+        "tenant has no switchable subscription; use billing-foundation:write:start-plan-checkout to start one",
+    });
+  }
+  // providerSubscriptionId only exists at the subscription's own provider; a catalog that
+  // no longer sells through that provider cannot switch it.
+  const provider = findProviderPlugin(ctx, subscription.providerName);
+  const isCatalogProvider =
+    provider !== null &&
+    listCatalogProviders(ctx, catalog).some((candidate) => candidate.name === provider.name);
+  if (!provider || !isCatalogProvider) {
+    throw new ConflictError({
+      i18nKey: "billing-foundation.errors.providerMismatch",
+      message: `tenant's active subscription is on provider "${subscription.providerName}", which the plan catalog does not sell through — switch-plan cannot switch across providers`,
+    });
+  }
+  await assertBillingEnabled(ctx, provider.plugin, handlerName);
+  if (subscription.cancelAt !== null) {
+    throw new ConflictError({
+      i18nKey: "billing-foundation.errors.cancellationScheduled",
+      message:
+        "subscription has a scheduled cancellation; reactivate it via billing-foundation:write:create-portal-session before switching plans",
+    });
+  }
+  if (tier === subscription.tier) {
+    throw new ConflictError({
+      i18nKey: "billing-foundation.errors.alreadyOnPlan",
+      message: `tenant is already on plan "${tier}"`,
+    });
+  }
+  if (!canSwitchPlans(provider.plugin)) {
+    throw new UnprocessableError("plan_switch_not_supported", {
+      i18nKey: "billing-foundation.errors.planSwitchNotSupported",
+      message: `subscription-foundation: provider "${subscription.providerName}" supports neither createPlanSwitchSession nor previewPlanSwitch + applyPlanSwitch`,
+    });
+  }
+
+  const prices = await resolvePlanPrices(ctx, provider.plugin, catalog);
+  const target = prices.get(tier);
+  if (!target) {
+    throw new UnprocessableError("price_unavailable", {
+      i18nKey: "billing-foundation.errors.priceUnavailable",
+      message: `subscription-foundation: no live price resolved for tier "${tier}"`,
+    });
+  }
+  const allowedPriceIds = [...prices.values()]
+    .filter((p): p is NonNullable<typeof p> => p !== null)
+    .map((p) => p.priceId);
+  return { provider, subscription, target, allowedPriceIds };
+}

package/packages/bundled-features/src/billing-foundation/projection.ts

@@ -1,18 +1,18 @@
-// Inline-projection für `read_subscriptions`. Materialisiert die 5
-// subscription-events in eine row pro Tenant.
+// Inline projection for `read_subscriptions`. Materializes the 5
+// subscription events into one row per tenant.
 //
-// Apply läuft in derselben TX wie ctx.unsafeAppendEvent — Caller sieht
-// seinen Schreib-State sofort (kein dispatcher-tick nötig). PK = event.
-// aggregateId (= deterministic uuidv5 pro Tenant) → replays kollidieren
-// auf der PK statt doppelte rows zu erzeugen.
+// Apply runs in the same transaction as ctx.unsafeAppendEvent, so the caller
+// sees its write state immediately (no dispatcher tick required). The PK is
+// event.aggregateId (= deterministic uuidv5 per tenant), so replays collide
+// on the PK instead of creating duplicate rows.
 //
-// **Production-deployment caveat:** der Generator in
-// `samples/apps/platform/drizzle/generate.ts` scant `feature.entities` —
-// `subscriptionsProjectionTable` ist als raw drizzle-pgTable in der
-// projection registriert, NICHT als r.entity. Apps die subscription-
-// foundation production mounten müssen die Tabelle in ihre eigene
-// `drizzle/generate.ts` ergänzen (= via subscriptionsProjectionTable-
-// import). setupTestStack pusht sie automatisch via r.projection.table.
+// **Production-deployment caveat:** the generator in
+// `samples/apps/platform/drizzle/generate.ts` scans `feature.entities` —
+// `subscriptionsProjectionTable` is registered in the projection as a raw
+// drizzle-pgTable, NOT as r.entity. Apps mounting subscription-foundation in
+// production must add the table to their own `drizzle/generate.ts` (via an
+// import of subscriptionsProjectionTable). setupTestStack pushes it
+// automatically via r.projection.table.
 
 import {
   buildEntityTable,
@@ -26,9 +26,9 @@ import { paymentRowId } from "./aggregate-id.ts";
 import { paymentEntity, subscriptionEntity } from "./entities.ts";
 import type { PaymentEventPayload, SubscriptionEventPayload } from "./events.ts";
 
-// Drizzle-table-instance aus dem entity-shape. Wird sowohl von der
-// projection-apply als auch von list-query / get-helper genutzt damit
-// alle drei Stellen denselben column-namespace teilen.
+// This Drizzle table instance is derived from the entity shape and is shared
+// by the projection apply, list query, and get helper so all three use the
+// same column namespace.
 export const subscriptionsProjectionTable = buildEntityTable("subscription", subscriptionEntity);
 
 // Same production-deployment caveat as subscriptionsProjectionTable above:
@@ -38,11 +38,11 @@ export const paymentsProjectionTable = buildEntityTable("payment", paymentEntity
 
 // Unbranded metas: the apply functions below ARE the executor of these
 // projections, so they may write through the typed helpers.
-const subscriptionsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
+export const subscriptionsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
   subscriptionsProjectionTable,
   "subscription",
 );
-const paymentsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
+export const paymentsProjectionMeta: EntityTableMeta = requireEntityTableMeta(
   paymentsProjectionTable,
   "payment",
 );
@@ -99,10 +99,10 @@ async function upsert(
   }>,
   fullPayload: SubscriptionEventPayload,
 ): Promise<void> {
-  // INSERT-fallback braucht ALL fields (NOT NULL constraints). Wenn
-  // jemand nur teil-felder updated (z.B. invoice-payment-failed nur
-  // status+tier), nutzen wir trotzdem den vollen payload für den
-  // INSERT-Pfad und nur den teil-`set` für ON CONFLICT.
+  // The INSERT fallback requires ALL fields because of NOT NULL constraints.
+  // If an update changes only some fields (for example, invoice-payment-failed
+  // changes only status+tier), the full payload is still used for the INSERT
+  // path, while only the partial `set` is used for ON CONFLICT.
   const insertCols = {
     id: event.aggregateId,
     tenantId: event.tenantId,
@@ -123,23 +123,23 @@ async function upsert(
 }
 
 // =============================================================================
-// Apply-functions — eine pro event-typ
+// Apply functions — one per event type
 //
-// Alle UPSERT für defensive consistency: ein out-of-order event
-// (z.B. rebuild-from-events) kann in jeder Reihenfolge ankommen
-// und die row korrekt materialisieren.
+// All use UPSERT for defensive consistency: an out-of-order event (for
+// example, during a rebuild-from-events) can arrive in any order and still
+// materialize the row correctly.
 // =============================================================================
 
-/** subscription-created → UPSERT mit allen Feldern. PK = aggregateId =
- *  subscriptionAggregateId(tenantId), one row pro Tenant. UPSERT damit
- *  Disney+-Wechsel-Pattern (= zweiter Provider sendet create für selben
- *  Tenant) den existing row überschreibt statt PK-conflict. */
+/** subscription-created → UPSERT with all fields. PK = aggregateId =
+ *  subscriptionAggregateId(tenantId), with one row per tenant. UPSERT allows
+ *  the Disney+-change pattern (a second provider sends create for the same
+ *  tenant) to overwrite the existing row instead of causing a PK conflict. */
 export const applySubscriptionCreated = defineApply<SubscriptionEventPayload>(async (event, tx) => {
   const full = fullSetFromPayload(event.payload);
   await upsert(tx, event, { ...full, ...cancelAtSetFromPayload(event.payload) }, event.payload);
 });
 
-/** subscription-updated → UPSERT mit allen Feldern. */
+/** subscription-updated → UPSERT with all fields. */
 export const applySubscriptionUpdated = defineApply<SubscriptionEventPayload>(async (event, tx) => {
   const full = fullSetFromPayload(event.payload);
   await upsert(tx, event, { ...full, ...cancelAtSetFromPayload(event.payload) }, event.payload);
@@ -163,8 +163,9 @@ export const applySubscriptionCanceled = defineApply<SubscriptionEventPayload>(
   },
 );
 
-/** invoice-paid → state-update (status, tier, currentPeriodEnd).
- *  Invoice-history selbst lebt im event-store (= Replay-fähig). */
+/** invoice-paid → state update (status, tier, currentPeriodEnd).
+ *  The invoice history itself lives in the event store, so it remains
+ *  replayable. */
 export const applyInvoicePaid = defineApply<SubscriptionEventPayload>(async (event, tx) => {
   const p = event.payload;
   await upsert(
@@ -180,10 +181,10 @@ export const applyInvoicePaid = defineApply<SubscriptionEventPayload>(async (eve
   );
 });
 
-/** invoice-payment-failed → status (typisch past_due) + tier. tier-
- *  engine liest die row + entscheidet ob downgrade. currentPeriodEnd
- *  bewusst nicht — die Period ist noch nicht "vorbei", payment hat
- *  nur nicht geklappt. */
+/** invoice-payment-failed → status (typically past_due) + tier. The tier
+ *  engine reads the row and decides whether to downgrade. currentPeriodEnd is
+ *  intentionally unchanged: the period has not "ended"; payment simply
+ *  failed. */
 export const applyInvoicePaymentFailed = defineApply<SubscriptionEventPayload>(
   async (event, tx) => {
     const p = event.payload;

package/packages/bundled-features/src/billing-foundation/subscription-tier-sync.ts

@@ -1,7 +1,7 @@
 // Generic Stripe/PayPal-webhook → tier-engine sync route. Extracted from the
-// near-identical webhook-route.ts app copies in show-pony and publicstatus
-// (infra#446) — the only per-app variables were the TierName union/default,
-// so it is now a factory parameter.
+// near-identical webhook-route.ts app copies in show-pony and publicstatus — the
+// only per-app variables were the TierName union/default, so it is now a factory
+// parameter.
 
 import {
   isTierAssignmentSource,

package/packages/bundled-features/src/billing-foundation/tenant-destroy-hook.ts

@@ -1,10 +1,9 @@
-import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { declareEscapeHatch, type TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
 import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
 import { resolveProfileForTenant } from "../compliance-profiles/index.ts";
 import { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id.ts";
 import { PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE } from "./events.ts";
-import { paymentsProjectionTable, subscriptionsProjectionTable } from "./projection.ts";
+import { paymentsProjectionMeta, subscriptionsProjectionMeta } from "./projection.ts";
 
 // providerCustomerId/providerSubscriptionId are `personal: "tenant"` on the
 // entity (envelope-encrypted with the tenant subject key, see entities.ts) —
@@ -19,7 +18,7 @@ export const SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON =
 export const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON =
   "tenant-destroy looks up the compliance profile and archives the payment event-stream before the projection rows are redacted/deleted";
 
-/** Tenant-destroy hook for billing PII (#800). HGB retains the accounting
+/** Tenant-destroy hook for billing PII. HGB retains the accounting
  *  row but redacts the two provider-subject PII fields; other profiles
  *  hard-delete the row. Either way the subscription stream is archived so a
  *  future projection rebuild can't resurrect what was erased. */
@@ -32,12 +31,12 @@ export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Pro
   const aggregateId = subscriptionAggregateId(ctx.tenantId);
   if (profile.key === "de-hr-dsgvo-hgb") {
     await ctx.db.updateMany(
-      subscriptionsProjectionTable as EntityTableMeta,
+      subscriptionsProjectionMeta,
       { providerCustomerId: REDACTED_PII_VALUE, providerSubscriptionId: REDACTED_PII_VALUE },
       { id: aggregateId },
     );
   } else {
-    await ctx.db.deleteMany(subscriptionsProjectionTable as EntityTableMeta, { id: aggregateId });
+    await ctx.db.deleteMany(subscriptionsProjectionMeta, { id: aggregateId });
   }
   await archiveStream(ctx.db.unsafeRaw(), {
     tenantId: ctx.tenantId,
@@ -48,7 +47,7 @@ export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Pro
   });
 }
 
-/** Tenant-destroy hook for payment PII (#800). Unlike subscriptionTenantDestroyHook
+/** Tenant-destroy hook for payment PII. Unlike subscriptionTenantDestroyHook
  *  (one row per tenant, targeted by `id`), a tenant can have many payment
  *  rows — the predicate here is `tenantId`, not `id`. The payment-stream
  *  itself is still one stream per tenant (paymentAggregateId), so
@@ -62,12 +61,12 @@ export async function paymentTenantDestroyHook(ctx: TenantDataHookCtx): Promise<
   const aggregateId = paymentAggregateId(ctx.tenantId);
   if (profile.key === "de-hr-dsgvo-hgb") {
     await ctx.db.updateMany(
-      paymentsProjectionTable as EntityTableMeta,
+      paymentsProjectionMeta,
       { providerCustomerId: REDACTED_PII_VALUE },
       { tenantId: ctx.tenantId },
     );
   } else {
-    await ctx.db.deleteMany(paymentsProjectionTable as EntityTableMeta, {
+    await ctx.db.deleteMany(paymentsProjectionMeta, {
       tenantId: ctx.tenantId,
     });
   }