@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,290 @@
+// kumiko-feature-version: 1
+//
+// subscription-foundation als Kumiko bundled feature (Plugin-Host).
+//
+// **Multi-Provider von Tag 1** — der App-Builder kann mehrere Plugins
+// parallel mounten (subscription-stripe + subscription-paypal +
+// subscription-apple-iap + ...) und der Endkunde wählt beim Subscribe-
+// Klick zwischen Karte/PayPal/Apple-Pay/Klarna/SEPA (Disney+-Pattern).
+// KEIN globaler `provider`-config-key — alle gemounteten Plugins sind
+// aktiv.
+//
+// **Was diese Foundation liefert:**
+//   1. **Plugin-API** für Subscription-Provider via `r.extendsRegistrar(
+//      "subscriptionProvider", ...)`.
+//   2. **5 Domain-Events** auf dem `subscription`-stream (eine
+//      stream-id pro Tenant): created/updated/canceled/invoice-paid/
+//      invoice-payment-failed. Audit-history kommt frei vom event-store.
+//   3. **Inline-Projection** auf `read_subscriptions` (= current state
+//      pro Tenant). Apply läuft in derselben TX wie der event-append
+//      → read-your-own-write semantics.
+//   4. **process-event-handler**: programmatic write-handler den der
+//      webhook-handler aufruft, dispatcht zu type-passendem appendEvent.
+//   5. **createSubscriptionWebhookRoute**: factory for the `entry:"signature"`
+//      extraRoute `/api/subscription/webhook/:providerName`.
+//   6. **payment-received event + read_payments projection**: one-off-
+//      payments (checkout mode "payment") get their own event, own
+//      per-tenant aggregate, and own `process-payment-event` write-handler
+//      — not a sixth SubscriptionEventTypes value (fw#2791).
+//   7. **Optional billing-plans catalog** (`createBillingFoundationFeature({
+//      baseUrl, catalog })`): a `billing-foundation:query:billing-plans`
+//      query plus `start-plan-checkout`/`switch-plan` write-handlers and a
+//      dormant `billing-plans` dashboard screen/panel, all derived from the
+//      one `catalog` option — no separate per-app price wiring.
+//
+// **Was diese Foundation NICHT macht:**
+//   - Kein r.entity für `subscription`. Die Tabelle ist eine reine
+//     Read-Projection — kein CRUD-Pfad. Schreibt wird ausschließlich
+//     via projection-apply, getriggert von einem der 5 events.
+//   - Kein Tier-Sync zum tier-engine. App-Owner liest die subscription-
+//     row via `getSubscriptionForTenant(ctx, tenantId)` wenn er möchte.
+//   - Keine provider-spezifischen Configs.
+//   - Kein Marketplace-Use-Case (App-Tenant billed Endkunden via
+//     Stripe Connect). Kommt als separate `marketplace-foundation`.
+//
+// **Provider-Wechsel:** Disney+-Pattern (= Tenant cancelt Stripe-sub,
+// startet neue mit PayPal) wird heute als zweiter `subscription-created`-
+// event modelliert. UPSERT in der projection-apply überschreibt den
+// existing row mit dem neuen providerName. Reicht für MVP. Wenn das
+// business-fact "Provider-Wechsel" ein eigenes domain-event braucht
+// (z.B. für analytics: "wie viele Wechsel im Monat?"), kommt ein
+// `subscription-provider-changed`-event-type später.
+
+import {
+  defineFeature,
+  EXT_TENANT_DATA,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+// Aliased — an un-aliased `Temporal` would shadow the ambient global
+// `Temporal` TYPE `ResolvedBillingFoundationOptions.now`'s return type
+// resolves against, see event-store.ts's own import comment (#1438).
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+import {
+  BILLING_FOUNDATION_FEATURE,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+  SubscriptionFoundationHandlers,
+} from "./constants.js";
+import { registerConsumerProtection } from "./consumer-protection/register-consent.js";
+import { paymentEntity, subscriptionEntity } from "./entities.js";
+import {
+  INVOICE_PAID_EVENT_QN,
+  INVOICE_PAID_EVENT_SHORT,
+  INVOICE_PAYMENT_FAILED_EVENT_QN,
+  INVOICE_PAYMENT_FAILED_EVENT_SHORT,
+  PAYMENT_AGGREGATE_TYPE,
+  PAYMENT_RECEIVED_EVENT_QN,
+  PAYMENT_RECEIVED_EVENT_SHORT,
+  paymentEventPayloadSchema,
+  SUBSCRIPTION_AGGREGATE_TYPE,
+  SUBSCRIPTION_CANCELED_EVENT_QN,
+  SUBSCRIPTION_CANCELED_EVENT_SHORT,
+  SUBSCRIPTION_CREATED_EVENT_QN,
+  SUBSCRIPTION_CREATED_EVENT_SHORT,
+  SUBSCRIPTION_UPDATED_EVENT_QN,
+  SUBSCRIPTION_UPDATED_EVENT_SHORT,
+  subscriptionEventPayloadSchema,
+} from "./events.js";
+import { createBillingPlansQuery } from "./handlers/billing-plans.query.js";
+import { createCheckoutSessionHandler } from "./handlers/create-checkout-session.write.js";
+import { createPortalSessionHandler } from "./handlers/create-portal-session.write.js";
+import { listSubscriptionsQuery } from "./handlers/list-subscriptions.query.js";
+import { createProcessEventHandler } from "./handlers/process-event.write.js";
+import { processPaymentEventHandler } from "./handlers/process-payment-event.write.js";
+import { createStartPlanCheckoutHandler } from "./handlers/start-plan-checkout.write.js";
+import { createSwitchPlanHandler } from "./handlers/switch-plan.write.js";
+import { syncSubscriptionHandler } from "./handlers/sync-subscription.write.js";
+import { BILLING_FOUNDATION_I18N } from "./i18n.js";
+import {
+  applyInvoicePaid,
+  applyInvoicePaymentFailed,
+  applyPaymentReceived,
+  applySubscriptionCanceled,
+  applySubscriptionCreated,
+  applySubscriptionUpdated,
+  paymentsProjectionTable,
+  subscriptionsProjectionTable,
+} from "./projection.js";
+import { createBillingPlansScreen } from "./screens.js";
+import {
+  PAYMENT_TENANT_DESTROY_ARCHIVE_REASON,
+  paymentTenantDestroyHook,
+  SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON,
+  subscriptionTenantDestroyHook,
+} from "./tenant-destroy-hook.js";
+import type { BillingFoundationOptions, ResolvedBillingFoundationOptions } from "./types.js";
+import { validateOptions } from "./validate-options.js";
+
+export function createBillingFoundationFeature<TTier extends string = string>(
+  options: BillingFoundationOptions<TTier> = {},
+): FeatureDefinition {
+  validateOptions(options);
+  // Handlers take the widened, string-tiered options — `TTier` only exists
+  // to let app-callers write `catalog.plans` as a literal-tier tuple; the
+  // foundation itself treats every tier as an opaque string. This object
+  // literal (not a cast) only compiles because `BillingFoundationOptions
+  // <TTier>` uses `TTier` solely in readonly-array/Record-value positions.
+  // baseUrl is normalized once here (trailing "/" stripped) so every
+  // downstream string-concatenation site (checkout-core's joinBaseUrl, the
+  // plan-checkout/switch-plan handlers) can rely on a single canonical form
+  // instead of re-normalizing per call-site. `now` is defaulted once here
+  // too — same pattern as createDekCache's `now` option — so no handler
+  // ever calls `Temporal.Now.instant` itself.
+  const widened: ResolvedBillingFoundationOptions = {
+    ...options,
+    // @cast-boundary temporal-polyfill-vs-ambient: same TC39 Temporal.Instant
+    // at runtime — `now` is typed against the ambient Temporal global;
+    // TemporalPolyfill.Now.instant() returns the polyfill's own nominal
+    // Instant type across the two .d.ts sources.
+    now: options.now ?? (() => TemporalPolyfill.Now.instant() as unknown as Temporal.Instant),
+    ...(options.baseUrl !== undefined && {
+      baseUrl: options.baseUrl.endsWith("/") ? options.baseUrl.slice(0, -1) : options.baseUrl,
+    }),
+  };
+
+  return defineFeature(BILLING_FOUNDATION_FEATURE, (r) => {
+    r.describe(
+      "Plugin host for subscription billing — manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers and a dormant billing-plans dashboard screen/panel from the catalog. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event — catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block — use `subscription-stripe` or `subscription-mollie` unless you are writing a new payment provider.",
+    );
+    r.uiHints({
+      displayLabel: "Billing · Foundation",
+      category: "billing",
+      recommended: false,
+    });
+    r.requires("tenant-lifecycle", "compliance-profiles");
+    // 5 fine-grained domain-events. All 5 share the same payload shape (a
+    // subscription-state snapshot); the event type tags what happened.
+    // Future consumers (billing-history, accounting) listen directly on
+    // the event type, no payload discriminator needed.
+    // piiFields: "none" — provider ids are tenantOwned ciphertext, not plaintext personal data.
+    r.defineEvent(SUBSCRIPTION_CREATED_EVENT_SHORT, subscriptionEventPayloadSchema, {
+      piiFields: "none",
+    });
+    r.defineEvent(SUBSCRIPTION_UPDATED_EVENT_SHORT, subscriptionEventPayloadSchema, {
+      piiFields: "none",
+    });
+    r.defineEvent(SUBSCRIPTION_CANCELED_EVENT_SHORT, subscriptionEventPayloadSchema, {
+      piiFields: "none",
+    });
+    r.defineEvent(INVOICE_PAID_EVENT_SHORT, subscriptionEventPayloadSchema, { piiFields: "none" });
+    r.defineEvent(INVOICE_PAYMENT_FAILED_EVENT_SHORT, subscriptionEventPayloadSchema, {
+      piiFields: "none",
+    });
+    // Own event, own aggregate-type — a one-off-payment is not a subscription
+    // state transition. piiFields: "none" for the same reason as the 5 above:
+    // providerCustomerId is tenantOwned ciphertext, not plaintext personal data.
+    r.defineEvent(PAYMENT_RECEIVED_EVENT_SHORT, paymentEventPayloadSchema, { piiFields: "none" });
+
+    // Inline projection: materialized current state in `read_subscriptions`.
+    // Apply runs in the same TX as ctx.unsafeAppendEvent — read-your-own-
+    // write without a dispatcher tick.
+    r.projection({
+      name: "subscription",
+      source: SUBSCRIPTION_AGGREGATE_TYPE,
+      table: subscriptionsProjectionTable,
+      entity: subscriptionEntity,
+      apply: {
+        [SUBSCRIPTION_CREATED_EVENT_QN]: applySubscriptionCreated,
+        [SUBSCRIPTION_UPDATED_EVENT_QN]: applySubscriptionUpdated,
+        [SUBSCRIPTION_CANCELED_EVENT_QN]: applySubscriptionCanceled,
+        [INVOICE_PAID_EVENT_QN]: applyInvoicePaid,
+        [INVOICE_PAYMENT_FAILED_EVENT_QN]: applyInvoicePaymentFailed,
+      },
+    });
+
+    // Second inline projection: `read_payments`, one row per one-off-payment.
+    r.projection({
+      name: "payment",
+      source: PAYMENT_AGGREGATE_TYPE,
+      table: paymentsProjectionTable,
+      entity: paymentEntity,
+      apply: {
+        [PAYMENT_RECEIVED_EVENT_QN]: applyPaymentReceived,
+      },
+    });
+
+    // Plugin extension-point. Provider-Plugins registrieren sich hier.
+    r.extendsRegistrar(SUBSCRIPTION_PROVIDER_EXTENSION, {
+      onRegister: () => {
+        // No side-effects at register-time.
+      },
+    });
+
+    // Custom write-handlers:
+    //   - process-event: programmatic entry-point vom webhook-handler;
+    //     dispatcht zu type-passendem appendEvent
+    //   - create-checkout-session: bare priceId-driven checkout (hardened,
+    //     see checkout-core)
+    //   - create-portal-session: Tenant-Admin "Manage Subscription"-flow
+    r.writeHandler(createProcessEventHandler(widened.now));
+    r.writeHandler(createCheckoutSessionHandler(widened));
+    r.writeHandler(createPortalSessionHandler(widened));
+    //   - process-payment-event: programmatic entry-point from the webhook-
+    //     handler for one-off-payments; appends onto the payment-aggregate
+    r.writeHandler(processPaymentEventHandler);
+    //   - sync-subscription: backfill entry-point for the sync-subscriptions
+    //     job below; pulls the live provider state and appends drift as a
+    //     subscription.updated event. Registered unconditionally (not
+    //     catalog-gated) — it operates on whatever subscription already
+    //     exists for the tenant, independent of the billing-plans catalog.
+    r.writeHandler(syncSubscriptionHandler);
+
+    // Custom list-query on the subscription-projection (raw drizzle
+    // table; no r.entity since writes go through projection-apply).
+    r.queryHandler(listSubscriptionsQuery);
+
+    // Error-keys from checkout-core (redirect-origin, unknown-price, ...)
+    // fire from create-checkout-session even without a catalog — register
+    // unconditionally rather than splitting the i18n surface by option.
+    r.translations({ keys: BILLING_FOUNDATION_I18N });
+    if (widened.consumerProtection) {
+      registerConsumerProtection(r, widened, widened.consumerProtection);
+    }
+
+    if (widened.catalog) {
+      const { catalog } = widened;
+      r.queryHandler(createBillingPlansQuery(widened, catalog));
+      r.writeHandler(createStartPlanCheckoutHandler(widened, catalog));
+      r.writeHandler(createSwitchPlanHandler(widened, catalog));
+      r.screen(createBillingPlansScreen(catalog.viewRoles));
+    }
+
+    // Backfill job: catches provider-side drift (e.g. a cancel_at set on
+    // the provider's own dashboard) that never reached us as a webhook.
+    // manual-trigger + runOnBoot (not cron) — this is an on-demand/boot
+    // reconciliation pass, not a recurring sweep; an app that wants a
+    // recurring sync can dispatch billing-foundation:job:sync-subscriptions
+    // from its own cron job. perTenant + runOnBoot are compatible (only
+    // bootGate is not). Registered unconditionally, same reasoning as the
+    // sync-subscription write-handler above.
+    r.job({
+      name: "sync-subscriptions",
+      trigger: { manual: true },
+      perTenant: true,
+      runOnBoot: true,
+      handler: async (_payload, ctx) => {
+        const result = await ctx.write(SubscriptionFoundationHandlers.syncSubscription, {});
+        if (!result.isSuccess) {
+          throw new Error(
+            `billing-foundation:sync-subscriptions: sync-subscription write failed: ${JSON.stringify(result.error)}`,
+          );
+        }
+        ctx.log.info(`[billing-foundation:sync-subscriptions] ${JSON.stringify(result.data)}`);
+      },
+    });
+
+    r.useExtension(EXT_TENANT_DATA, "subscription", {
+      destroy: subscriptionTenantDestroyHook,
+      escapeHatch: { reason: SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON },
+    });
+    r.useExtension(EXT_TENANT_DATA, "payment", {
+      destroy: paymentTenantDestroyHook,
+      escapeHatch: { reason: PAYMENT_TENANT_DESTROY_ARCHIVE_REASON },
+    });
+  });
+}
+
+// Back-compat: existing consumers importing the plain const keep working
+// unchanged (no baseUrl/catalog — create-checkout-session's redirect-origin
+// check then rejects every call as UnconfiguredError, matching the
+// changes.json migration note).
+export const billingFoundationFeature = createBillingFoundationFeature();

package/packages/bundled-features/src/billing-foundation/get-subscription-for-tenant.ts

@@ -0,0 +1,58 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+// Resolver-helper: liest die current subscription-row für einen Tenant
+// aus der read_subscriptions-projection.
+
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { subscriptionAggregateId } from "./aggregate-id.js";
+import { SUBSCRIPTION_PII_FIELDS } from "./entities.js";
+import { subscriptionsProjectionTable } from "./projection.js";
+
+export type SubscriptionView = {
+  readonly tier: string;
+  readonly status: string;
+  readonly providerName: string;
+  readonly providerCustomerId: string;
+  readonly providerSubscriptionId: string;
+  readonly currentPeriodEnd: Temporal.Instant;
+  /** When the subscription ends because of a cancellation. null = it
+   *  renews. */
+  readonly cancelAt: Temporal.Instant | null;
+  /** `modified_at ?? inserted_at` — the projection's own base columns.
+   *  `modified_at` is null only for pre-existing rows written before every
+   *  apply-function started stamping it from `event.createdAt`. */
+  readonly lastChangedAt: Temporal.Instant;
+};
+
+/** Liefert die einzige subscription-row für den Tenant (deterministic
+ *  aggregate-id), oder null wenn der Tenant nie subscribed hat. Status
+ *  kann active/canceled/past_due/etc sein — Caller entscheidet was tun. */
+export async function getSubscriptionForTenant(
+  ctx: HandlerContext,
+  tenantId: string,
+): Promise<SubscriptionView | null> {
+  const aggId = subscriptionAggregateId(tenantId);
+  const rows = await ctx.db.selectMany(subscriptionsProjectionTable, { id: aggId }, { limit: 1 });
+  const row = rows[0];
+  if (!row) return null;
+  const piiKms = configuredPiiSubjectKms();
+  const decrypted = piiKms
+    ? await decryptPiiFieldValues(row as Record<string, unknown>, SUBSCRIPTION_PII_FIELDS, piiKms, {
+        requestId: `billing-foundation:get-subscription:${tenantId}`,
+      })
+    : (row as Record<string, unknown>);
+  // @cast-boundary db-row — drizzle-row carries column-as-unknown
+  return {
+    tier: decrypted["tier"] as string,
+    status: decrypted["status"] as string,
+    providerName: decrypted["providerName"] as string,
+    providerCustomerId: decrypted["providerCustomerId"] as string,
+    providerSubscriptionId: decrypted["providerSubscriptionId"] as string,
+    currentPeriodEnd: decrypted["currentPeriodEnd"] as Temporal.Instant,
+    cancelAt: (decrypted["cancelAt"] ?? null) as Temporal.Instant | null,
+    lastChangedAt: (decrypted["modifiedAt"] ?? decrypted["insertedAt"]) as Temporal.Instant,
+  };
+}

package/packages/bundled-features/src/billing-foundation/handlers/billing-plans.query.ts

@@ -0,0 +1,54 @@
+// billing-plans — lists the catalog's purchasable plans with live price,
+// benefits, the caller's current tier and per-plan action. Only registered
+// when `createBillingFoundationFeature` gets a `catalog`.
+
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { findCatalogProvider } from "../checkout-core.js";
+import {
+  type CONSENT_LOCALES,
+  CONSENT_TEXTS,
+  consentTextVersion,
+} from "../consumer-protection/consent-text.js";
+import { buildBillingPlans } from "../plan-catalog.js";
+import type {
+  BillingPlanCatalog,
+  BillingPlansResult,
+  ResolvedBillingFoundationOptions,
+} from "../types.js";
+
+const billingPlansSchema = z.object({}).strict();
+
+export function createBillingPlansQuery(
+  options: ResolvedBillingFoundationOptions,
+  catalog: BillingPlanCatalog,
+): QueryHandlerDef {
+  return {
+    name: "billing-plans",
+    description:
+      "Lists the purchasable plans with live price, benefits, the caller's current tier and which action (checkout | switch | current | unavailable | paymentPending) each plan offers.",
+    schema: billingPlansSchema,
+    access: { roles: catalog.viewRoles },
+    handler: async (_query, ctx): Promise<BillingPlansResult> => {
+      const found = findCatalogProvider(ctx, catalog);
+      const result = await buildBillingPlans(ctx, found?.plugin ?? null, catalog, options.now);
+      const { consumerProtection } = options;
+      if (!consumerProtection) return result;
+      return {
+        ...result,
+        consumerProtection: {
+          consentTexts: {
+            de: consentTextView("de"),
+            en: consentTextView("en"),
+          },
+          legalLinks: consumerProtection.legalLinks,
+        },
+      };
+    },
+  };
+}
+
+function consentTextView(locale: (typeof CONSENT_LOCALES)[number]) {
+  const { earlyPerformance, withdrawalLoss } = CONSENT_TEXTS[locale];
+  return { earlyPerformance, withdrawalLoss, consentTextVersion: consentTextVersion(locale) };
+}

package/packages/bundled-features/src/billing-foundation/handlers/create-checkout-session.write.ts

@@ -0,0 +1,132 @@
+// create-checkout-session — Tenant-Admin klickt "Upgrade to Pro" (oder
+// wählt zwischen Karte/PayPal/Apple-Pay). Handler findet den
+// providerName aus der payload, lookuppt den Plugin, ruft
+// `plugin.createCheckoutSession(ctx, ...)`, returnt hosted-page-URL.
+// Tenant-Admin wird dorthin redirected.
+//
+// **Multi-Provider-Pfad:** payload.providerName ist der entityName
+// eines registrierten Plugins ("stripe" / "paypal" / "mollie" / ...).
+// App-Builder zeigt eine UI-Liste der gemounteten provider, Endkunde
+// pickt einen, dieser handler dispatched zum richtigen Plugin.
+//
+// **Tenant-resolution:** ctx.user.tenantId wird als metadata an den
+// Provider mitgegeben. Beim subsequent webhook (subscription.created)
+// liest verifyAndParseWebhook das aus dem provider-payload zurück und
+// resolved den Tenant.
+//
+// **Hardening:** successUrl/cancelUrl must share `options.baseUrl`'s
+// origin; mode:"subscription" requires priceId to be a known price of the
+// target provider (and, with a catalog, to map to one of its plans); a
+// tenant with an existing non-terminal subscription must use
+// billing-foundation:write:switch-plan instead. Plan-driven callers should
+// prefer start-plan-checkout/switch-plan over calling this handler with a
+// hand-picked priceId.
+
+import type { HandlerContext, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { findProviderPlugin, openCheckout } from "../checkout-core.js";
+import {
+  type ConsentPayload,
+  consentCheckoutFields,
+  consentPayloadSchema,
+  prepareConsent,
+  recordConsent,
+} from "../consumer-protection/consent-gate.js";
+import type {
+  ProviderPrice,
+  ResolvedBillingFoundationOptions,
+  SubscriptionProviderPlugin,
+} from "../types.js";
+
+const createCheckoutSessionSchema = z.object({
+  /** Welcher Provider — entityName eines registrierten subscription-
+   *  Plugins ("stripe" / "paypal" / ...). */
+  providerName: z.string().min(1).max(50),
+  /** Provider-eigene price/plan-ID. */
+  priceId: z.string().min(1).max(200),
+  /** Wo der Endkunde nach erfolgreichem checkout landed. */
+  successUrl: z.string().url(),
+  /** Wo der Endkunde landed wenn er abbricht. */
+  cancelUrl: z.string().url(),
+  /** Optional: existierender provider-customer wenn der Tenant schon
+   *  einen account beim Provider hat (= Plan-Wechsel statt Neuregistrierung). */
+  providerCustomerId: z.string().max(200).optional(),
+  /** Optional: `"payment"` for a one-off checkout (e.g. credit top-up)
+   *  instead of a recurring subscription. Defaults to `"subscription"`. */
+  mode: z.enum(["subscription", "payment"]).optional(),
+});
+type CreateCheckoutSessionPayload = z.infer<typeof createCheckoutSessionSchema> & {
+  readonly consent?: ConsentPayload;
+};
+
+export function createCheckoutSessionHandler(
+  options: ResolvedBillingFoundationOptions,
+): WriteHandlerDef {
+  const consumerProtection = options.consumerProtection;
+  const schema = consumerProtection
+    ? createCheckoutSessionSchema.extend({ consent: consentPayloadSchema })
+    : createCheckoutSessionSchema;
+  return {
+    name: "create-checkout-session",
+    description:
+      'Opens a hosted checkout page at the named subscription provider for the caller\'s tenant and returns its URL; use it when a tenant admin wants to make a one-off payment (mode: "payment") or subscribe to a price already known to be valid. Redirect URLs must share the configured baseUrl origin. Prefer billing-foundation:write:start-plan-checkout / :switch-plan for catalog-driven plan purchases.',
+    schema,
+    // Tenant-Admin-only — the tenant must deliberately configure its own
+    // subscription. SystemAdmin as a fallback for operator-initiated flows.
+    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    handler: async (event, ctx) => {
+      // @cast-boundary engine-payload — dispatcher-zod-validated payload
+      const payload = event.payload as CreateCheckoutSessionPayload;
+
+      const mode = payload.mode ?? "subscription";
+      const consent =
+        consumerProtection && payload.consent
+          ? await prepareConsent(ctx, consumerProtection, payload.consent, mode)
+          : undefined;
+
+      const result = await openCheckout(
+        ctx,
+        { baseUrl: options.baseUrl, catalog: options.catalog, now: options.now },
+        {
+          providerName: payload.providerName,
+          priceId: payload.priceId,
+          successUrl: payload.successUrl,
+          cancelUrl: payload.cancelUrl,
+          ...(payload.providerCustomerId && { providerCustomerId: payload.providerCustomerId }),
+          ...(payload.mode && { mode: payload.mode }),
+          ...(consent && consentCheckoutFields(consent)),
+        },
+      );
+
+      if (consent) {
+        const plugin = findProviderPlugin(ctx, payload.providerName)?.plugin;
+        await recordConsent(ctx, consent, {
+          tier: mode === "subscription" ? (plugin?.priceToTier?.[payload.priceId] ?? null) : null,
+          priceId: payload.priceId,
+          price: await lookupPrice(ctx, plugin, payload.priceId),
+        });
+      }
+
+      return {
+        isSuccess: true as const,
+        data: { url: result.url, providerName: result.providerName },
+      };
+    },
+  };
+}
+
+// A failed price lookup must not lose a consent the buyer already gave at the
+// provider, so it degrades to null price fields.
+async function lookupPrice(
+  ctx: HandlerContext,
+  plugin: SubscriptionProviderPlugin | undefined,
+  priceId: string,
+): Promise<ProviderPrice | null> {
+  if (!plugin?.retrievePrices) return null;
+  try {
+    const prices = await plugin.retrievePrices(ctx, [priceId]);
+    return prices.find((p) => p.priceId === priceId) ?? null;
+  } catch {
+    return null;
+  }
+}

package/packages/bundled-features/src/billing-foundation/handlers/create-portal-session.write.ts

@@ -0,0 +1,103 @@
+// create-portal-session — Tenant-Admin klickt "Manage Subscription".
+// Handler findet die current subscription des Tenants, lookuppt den
+// passenden Plugin (= subscription.providerName-Spalte), ruft
+// `plugin.createPortalSession(ctx, ...)`, returnt hosted-portal-URL.
+//
+// **Provider-resolution:** anders als create-checkout-session (= der
+// Tenant wählt einen NEUEN Provider beim Subscribe) ist hier der
+// Provider durch die existing subscription-row festgelegt — Tenant
+// kann nicht zum Portal eines OTHER Providers, weil der ihn nicht
+// kennt.
+//
+// **returnUrl:** computed server-side via `portalReturnUrl` (catalog's
+// returnPath, or baseUrl itself) — the client no longer supplies one, so
+// there is no client-controlled redirect to harden against.
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { subscriptionAggregateId } from "../aggregate-id.js";
+import { portalReturnUrl, resolveProviderPlugin } from "../checkout-core.js";
+import { SUBSCRIPTION_PII_FIELDS } from "../entities.js";
+import { purchaseRolesOf } from "../plan-catalog.js";
+import { subscriptionsProjectionTable as subTable } from "../projection.js";
+import type { BillingFoundationOptions } from "../types.js";
+
+const createPortalSessionSchema = z.object({}).strict();
+
+export function createPortalSessionHandler(options: BillingFoundationOptions): WriteHandlerDef {
+  return {
+    name: "create-portal-session",
+    description:
+      "Returns a hosted billing-portal URL at the provider that already holds the tenant's subscription; use it when a tenant admin wants to change payment method, see invoices or cancel.",
+    schema: createPortalSessionSchema,
+    access: { roles: purchaseRolesOf(options.catalog) },
+    handler: async (event, ctx) => {
+      const tenantId = event.user.tenantId;
+      const returnUrl = portalReturnUrl(options);
+
+      // 1. Fetch the current subscription row for the tenant. Aggregate-id
+      //    is deterministic per tenant — one row per tenant.
+      const subAggId = subscriptionAggregateId(tenantId);
+      const rows = await selectMany(ctx.db, subTable, { id: subAggId }, { limit: 1 });
+      const row = rows[0];
+      if (!row) {
+        throw new Error(
+          "subscription-foundation: no active subscription for this tenant. Create one via create-checkout-session first.",
+        );
+      }
+      const piiKms = configuredPiiSubjectKms();
+      const decrypted = piiKms
+        ? await decryptPiiFieldValues(
+            row as Record<string, unknown>,
+            SUBSCRIPTION_PII_FIELDS,
+            piiKms,
+            {
+              requestId: `billing-foundation:create-portal-session:${tenantId}`,
+            },
+          )
+        : (row as Record<string, unknown>);
+      const providerName = row["providerName"] as string; // @cast-boundary db-row
+      const providerCustomerId = decrypted["providerCustomerId"] as string; // @cast-boundary db-row
+
+      // 2. Plugin-Lookup
+      const { plugin } = resolveProviderPluginOrThrow(ctx, providerName);
+      if (!plugin.createPortalSession) {
+        throw new Error(
+          `subscription-foundation: provider "${providerName}" has no createPortalSession-method (e.g. Apple-IAP managed Subs in der Apple-App).`,
+        );
+      }
+
+      const result = await plugin.createPortalSession(ctx, {
+        providerCustomerId,
+        returnUrl,
+      });
+
+      return {
+        isSuccess: true as const,
+        data: { url: result.url, providerName },
+      };
+    },
+  };
+}
+
+// resolveProviderPlugin's "not registered" message talks about checkout
+// providers ("provider ... not registered. Known: ..."), but here the
+// provider is fixed by the subscription row, not caller-chosen — keep the
+// portal-specific error message this handler always had.
+function resolveProviderPluginOrThrow(
+  ctx: Parameters<typeof resolveProviderPlugin>[0],
+  providerName: string,
+): ReturnType<typeof resolveProviderPlugin> {
+  try {
+    return resolveProviderPlugin(ctx, providerName);
+  } catch {
+    throw new Error(
+      `subscription-foundation: subscription belongs to provider "${providerName}" but the matching plugin is not mounted.`,
+    );
+  }
+}