@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

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

@@ -1,18 +1,18 @@
-// 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.
+// create-checkout-session — Tenant admin clicks "Upgrade to Pro" (or
+// chooses between card/PayPal/Apple Pay). The handler reads providerName
+// from the payload, looks up the plugin, calls
+// `plugin.createCheckoutSession(ctx, ...)`, and returns the hosted-page URL.
+// The tenant admin is redirected there.
 //
-// **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.
+// **Multi-provider path:** payload.providerName is the entityName
+// of a registered plugin ("stripe" / "paypal" / "mollie" / ...).
+// The app builder shows a UI list of mounted providers; the customer
+// selects one, and this handler dispatches to the matching 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.
+// **Tenant resolution:** ctx.user.tenantId is passed to the provider as
+// metadata. On the subsequent webhook (subscription.created),
+// verifyAndParseWebhook reads it back from the provider payload and
+// resolves the tenant.
 //
 // **Hardening:** successUrl/cancelUrl must share `options.baseUrl`'s
 // origin; mode:"subscription" requires priceId to be a known price of the
@@ -51,12 +51,13 @@ const createCheckoutSessionSchema = z.object({
   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. */
+  /** Where the customer lands after a successful checkout. */
   successUrl: z.string().url(),
-  /** Wo der Endkunde landed wenn er abbricht. */
+  /** Where the customer lands if they cancel. */
   cancelUrl: z.string().url(),
-  /** Optional: existierender provider-customer wenn der Tenant schon
-   *  einen account beim Provider hat (= Plan-Wechsel statt Neuregistrierung). */
+  /** Optional: existing provider customer when the tenant already
+   *  has an account with the provider (= plan change instead of a new
+   *  registration). */
   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"`. */

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

@@ -1,17 +1,16 @@
-// 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.
+// create-portal-session — Tenant admin clicks "Manage Subscription".
+// The handler finds the tenant's current subscription, looks up the matching
+// plugin (= the `subscription.providerName` column), calls
+// `plugin.createPortalSession(ctx, ...)`, and returns the 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.
+// **Provider resolution:** unlike create-checkout-session (where the tenant
+// chooses a NEW provider when subscribing), the provider here is fixed by the
+// existing subscription row. The tenant cannot access another provider's
+// portal because the subscription does not belong to that provider.
 //
-// **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.
+// **returnUrl:** computed server-side via `portalReturnUrl` (the catalog's
+// returnPath, or baseUrl itself). The client no longer supplies one, so there
+// is no client-controlled redirect to harden against.
 
 import {
   configuredPiiSubjectKms,

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

@@ -1,7 +1,7 @@
-// list-subscriptions — sysadmin-cross-tenant list-query auf der
-// `read_subscriptions`-projection. Tenant-Admins lesen ihre eigene
-// subscription via getSubscriptionForTenant-helper (= ctx.db ist
-// tenant-scoped, gibt automatisch nur die row des Callers zurück).
+// list-subscriptions — sysadmin cross-tenant list query on the
+// `read_subscriptions` projection. Tenant admins read their own
+// subscription through the getSubscriptionForTenant helper (= ctx.db is
+// tenant-scoped and automatically returns only the caller's row).
 import {
   configuredPiiSubjectKms,
   decryptPiiFieldValues,

package/packages/bundled-features/src/billing-foundation/handlers/process-event.write.ts

@@ -1,16 +1,16 @@
-// process-event — programmatic write-handler den der webhook-handler
-// (createSubscriptionWebhookRoute) aufruft NACHDEM Plugin den raw-body
-// verifiziert + zu SubscriptionEvent normalisiert hat.
+// process-event — programmatic write handler called by the webhook handler
+// (createSubscriptionWebhookRoute) AFTER the plugin has verified the raw body
+// and normalized it into a SubscriptionEvent.
 //
-// **ES-Pattern:**
-//   1. Idempotency-check: lädt subscription-stream + scannt nach
-//      bereits gesehenem `metadata.providerEventId`. Provider-Replay
-//      (Stripe-Retry-Storm) sieht denselben event-id → duplicate=true,
-//      kein zweiter append.
-//   2. Type-mapping: SubscriptionEvent.type (= normalisiert vom Plugin)
-//      → einer der 5 ES-event-typen.
-//   3. ctx.unsafeAppendEvent — Inline-projection materialisiert die
-//      `read_subscriptions`-row in derselben TX.
+// **ES pattern:**
+//   1. Idempotency check: loads the subscription stream and scans for an
+//      already-seen `metadata.providerEventId`. A provider replay
+//      (Stripe retry storm) has the same event ID → duplicate=true,
+//      with no second append.
+//   2. Type mapping: SubscriptionEvent.type (= normalized by the plugin)
+//      → one of the 5 ES event types.
+//   3. ctx.unsafeAppendEvent — the inline projection materializes the
+//      `read_subscriptions` row in the same TX.
 
 import {
   configuredPiiSubjectKms,
@@ -42,9 +42,9 @@ import {
 } from "../web/constants.ts";
 
 // =============================================================================
-// Input-Schema = der normalisierte SubscriptionEvent (ohne tenantId, der
-// kommt aus event.user.tenantId — der webhook-handler setzt den
-// programmatic-user mit der vom Plugin aufgelösten tenantId).
+// Input schema = the normalized SubscriptionEvent (without tenantId, which
+// comes from event.user.tenantId — the webhook handler sets the
+// programmatic user with the tenantId resolved by the plugin).
 // =============================================================================
 
 const eventTypeSchema = z.enum([
@@ -208,9 +208,9 @@ export async function appendSubscriptionEvent(
   //    read_subscriptions row with a single call. The subject is the
   //    TENANT (tenantOwned) — tenant-destroy's subject-keys stage
   //    (eraseSubjectKeys) erases exactly this key, so both copies become
-  //    genuinely unreadable (#800) once that stage runs, not just
+  //    genuinely unreadable once that stage runs, not just
   //    "encrypted at rest". No adapter configured = engine off (fields
-  //    stay plaintext, pre-#724-phase-C behavior) — mirrors how the
+  //    stay plaintext) — mirrors how the
   //    event-store-executor treats an absent piiKms().
   // ---------------------------------------------------------------
   const piiKms = configuredPiiSubjectKms();
@@ -268,9 +268,9 @@ export async function appendSubscriptionEvent(
 // Handler
 // =============================================================================
 //
-// SystemAdmin-only: dieser handler wird ausschließlich vom programmatic
-// webhook-handler aufgerufen (mit einem internal SystemUser), nie vom
-// Tenant-Admin direkt.
+// SystemAdmin-only: this handler is called exclusively by the programmatic
+// webhook handler (with an internal SystemUser), never directly by the
+// tenant admin.
 // One subscription aggregate exists per tenant, but a tenant can legitimately hold two provider
 // subscriptions over time (a stale `incomplete` one superseded by a fresh checkout). A late or
 // retried event of the old subscription must not overwrite the row of the live one, so an event of a

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,
     });
   }

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

@@ -1,29 +1,29 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-// Plugin-Contract + Domain-Types der subscription-foundation. Provider-
-// Plugins (subscription-stripe, subscription-mollie, ...) implementieren
-// `SubscriptionProviderPlugin` und registrieren via
+// Plugin contract and domain types for subscription-foundation. Provider
+// plugins (subscription-stripe, subscription-mollie, ...) implement
+// `SubscriptionProviderPlugin` and register via
 // `r.useExtension("subscriptionProvider", "<name>", { build })`.
 //
 // **Two-phase plugin contract:**
-//   1. **Pre-tenant-resolution:** `verifyAndParseWebhook` läuft BEVOR
-//      ein Tenant aus dem Event aufgelöst ist — kein HandlerContext
-//      verfügbar. Das **Webhook-secret ist app-wide** (App-Owner's
-//      Stripe-/PayPal-Account, nicht Tenant-Sache). Damit ein Plugin den
-//      secret ZUR LAUFFZEIT aus dem secrets-Feature lesen kann (statt aus
-//      einem mount-time-Closure), reicht der webhook-handler einen
-//      optionalen system-scoped `SecretsContext` als 3. Arg durch — der
-//      Plugin liest seine app-wide-Secrets daraus un-audited unter
-//      SYSTEM_TENANT_ID. Plugins, die ihre Keys weiter aus einem Closure
-//      halten (z.B. mollie), ignorieren den Param → backward-compatible.
+//   1. **Pre-tenant-resolution:** `verifyAndParseWebhook` runs BEFORE
+//      a tenant is resolved from the event, so no HandlerContext is
+//      available. The **webhook secret is app-wide** (the App Owner's
+//      Stripe-/PayPal-account, not tenant-specific). To let a plugin read
+//      the secret from the secrets feature AT RUNTIME (instead of a
+//      mount-time closure), the webhook handler passes an optional
+//      system-scoped `SecretsContext` as the third argument. The plugin
+//      reads its app-wide secrets from it without auditing under
+//      SYSTEM_TENANT_ID. Plugins that keep their keys in a closure
+//      (e.g. mollie) ignore the parameter → backward-compatible.
 //   2. **Post-tenant-resolution:** `createPortalSession` +
-//      `cancelSubscription` werden aus regulären write-handlern
-//      gerufen mit voll-aufgelöstem HandlerContext. Plugin kann
-//      hier ctx.config + ctx.secrets nutzen für tenant-spezifische
-//      Konfiguration (z.B. tenant-eigene customer-id-mapping).
+//      `cancelSubscription` are called from regular write handlers with
+//      a fully resolved HandlerContext. The plugin can use ctx.config +
+//      ctx.secrets for tenant-specific configuration (e.g. tenant-owned
+//      customer-id mappings).
 //
-// Foundation nutzt nur den common-subset der Provider-Funktionalität —
-// proration, multi-currency, coupons etc. bleiben provider-spezifisch
-// und sind über den Customer-Portal-Link erreichbar.
+// Foundation uses only the common subset of provider functionality;
+// proration, multi-currency, coupons, etc. remain provider-specific and
+// are available through the Customer Portal link.
 
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
@@ -41,12 +41,12 @@ import {
 import type { ConsentLocale } from "./web/consumer-protection/consent-locale.ts";
 
 // =============================================================================
-// Normalisierter Webhook-Event
+// Normalized Webhook Event
 // =============================================================================
 //
-// Der Plugin parsed den raw provider-payload und liefert diese Form
-// zurück. Foundation kennt KEINE Stripe-/Mollie-types direkt — der
-// Plugin abstrahiert.
+// The plugin parses the raw provider payload and returns this shape.
+// Foundation has no direct knowledge of Stripe-/Mollie-types; the plugin
+// provides the abstraction.
 
 export type SubscriptionEvent = {
   /** Discriminator against PaymentEvent. Optional (instead of required) so
@@ -55,32 +55,31 @@ export type SubscriptionEvent = {
    *  `parsed.kind === BillingEventKinds.payment` correctly, because only
    *  PaymentEvent["kind"] can take that value. */
   readonly kind?: typeof BillingEventKinds.subscription;
-  /** Provider-eigene Event-ID — UNIQUE-key für Idempotency.
-   *  Stripe: "evt_..."; Mollie: payment-id oder subscription-id. */
+  /** Provider-owned event ID — UNIQUE key for idempotency.
+   *  Stripe: "evt_..."; Mollie: payment-id or subscription-id. */
   readonly providerEventId: string;
   /** Discriminator — welcher Plugin diesen Event geliefert hat. */
   readonly providerName: string;
   /** Normalisierter Event-Type. Plugin filtert provider-spezifische
    *  Sub-Types raus (Stripe hat ~80 Event-types, wir kennen 5). */
   readonly type: SubscriptionEventType;
-  /** Plattform-Tenant-ID (provider-customer-metadata oder lookup
-   *  via providerCustomerId). Plugin macht die resolution. */
+  /** Platform tenant ID (provider-customer metadata or lookup via
+   *  providerCustomerId). The plugin performs the resolution. */
   readonly tenantId: string;
   /** Consent id echoed back from checkout metadata; omitted when absent or
    *  malformed. */
   readonly consentId?: string;
-  /** Provider-eigene customer-id für späteren Lookup bei events
-   *  ohne metadata. */
+  /** Provider-owned customer ID for later lookup when events lack
+   *  metadata. */
   readonly providerCustomerId: string;
   /** Provider-eigene subscription-id. */
   readonly providerSubscriptionId: string;
   /** Normalisierter status. */
   readonly status: SubscriptionStatus;
-  /** Resolved tier — Plugin liest die price-id aus dem event und
-   *  mapped via plugin-eigenem `<plugin>:config:price-to-tier` auf
-   *  einen tier-name. Wenn der price-id im Mapping fehlt, returnt
-   *  der Plugin null aus verifyAndParseWebhook (= "unknown event,
-   *  ignore"). */
+  /** Resolved tier — the plugin reads the price ID from the event and
+   *  maps it through the plugin's `<plugin>:config:price-to-tier` to a
+   *  tier name. If the price ID is absent from the mapping, the plugin
+   *  returns null from verifyAndParseWebhook (= "unknown event, ignore"). */
   readonly tier: string;
   /** ISO-timestamp wann die aktuelle Billing-Period endet. */
   readonly currentPeriodEnd: string;
@@ -172,32 +171,32 @@ export type SubscriptionProviderPlugin = {
   ) => Promise<SubscriptionEvent | PaymentEvent | null>;
 
   /**
-   * **Post-tenant-resolution** — wird aus dem
-   * `create-checkout-session`-write-handler gerufen. Plugin baut
-   * eine provider-eigene checkout-session und returnt die hosted-
-   * page-URL — Tenant-Admin wird dorthin redirected, schließt den
-   * Bezahl-Flow ab, Provider sendet `subscription.created`-webhook
-   * mit `metadata.tenantId` zurück.
+   * **Post-tenant-resolution** — called from the
+   * `create-checkout-session` write handler. The plugin builds a
+   * provider-specific checkout session and returns its hosted-page URL;
+   * the tenant admin is redirected there to complete payment, and the
+   * provider sends a `subscription.created` webhook with
+   * `metadata.tenantId`.
    *
-   * Optional: Apple-IAP hat keinen Web-Checkout (alles in der App).
-   * Apps die ausschließlich Apple-IAP nutzen lassen das weg.
+   * Optional: Apple-IAP has no web checkout (everything happens in the app).
+   * Apps that use only Apple-IAP omit this field.
    */
   readonly createCheckoutSession?: (
     ctx: HandlerContext,
     options: {
-      /** Provider-eigene price/plan-ID die der Endkunde abonniert. */
+      /** Provider-owned price/plan ID that the customer subscribes to. */
       readonly priceId: string;
-      /** Plattform-Tenant-ID — landet als metadata im checkout-session
-       *  damit der subsequent webhook den tenant resolved (siehe
-       *  `verifyAndParseWebhook`'s metadata.tenantId-lookup). */
+      /** Platform tenant ID — stored as metadata in the checkout session
+       *  so the subsequent webhook can resolve the tenant (see the
+       *  `verifyAndParseWebhook` metadata.tenantId lookup). */
       readonly tenantId: string;
-      /** Wo der Endkunde nach erfolgreichem checkout landed. */
+      /** Where the customer lands after a successful checkout. */
       readonly successUrl: string;
-      /** Wo der Endkunde landed wenn er abbricht. */
+      /** Where the customer lands if they cancel. */
       readonly cancelUrl: string;
-      /** Optional: existierende provider-customer-id wenn der Tenant
-       *  schon einen Account beim Provider hat. Sonst legt der Provider
-       *  beim checkout einen neuen customer an. */
+      /** Optional: existing provider customer ID when the tenant already
+       *  has an account with the provider. Otherwise, the provider
+       *  creates a new customer during checkout. */
       readonly providerCustomerId?: string;
       /** Checkout mode. `"subscription"` (default) starts a recurring
        *  billing flow; `"payment"` a one-off checkout (e.g. pay-per-use
@@ -215,17 +214,17 @@ export type SubscriptionProviderPlugin = {
   ) => Promise<{ readonly url: string }>;
 
   /**
-   * **Post-tenant-resolution** — wird aus einem write-handler gerufen
-   * mit voll-aufgelöstem ctx. Erstellt einen self-service Portal-Link.
+   * **Post-tenant-resolution** — called from a write handler with a
+   * fully resolved ctx. Creates a self-service Portal link.
    * Stripe: customer-portal-session, Mollie: hosted-management-page.
-   * Tenant-Admin klickt darauf um Subscription selbst zu verwalten
-   * (cancel, payment-method, ...).
+   * The tenant admin uses it to manage the subscription themselves
+   * (cancel, payment method, ...).
    *
-   * Optional weil nicht jeder Provider einen Portal-Pattern hat
-   * (Apple-IAP managed Subs in der Apple-App, kein Web-Portal).
-   * Plugin der das nicht supported kann das Field weglassen — foundation
-   * returnt dann "portal_not_supported"-error wenn ein Tenant-Admin
-   * den Portal-Link anfordert.
+   * Optional because not every provider has a Portal pattern
+   * (Apple-IAP subscriptions are managed in the Apple app, with no web
+   * Portal). A plugin that does not support this can omit the field;
+   * the foundation then returns a "portal_not_supported" error when a
+   * tenant admin requests the Portal link.
    */
   readonly createPortalSession?: (
     ctx: HandlerContext,
@@ -236,10 +235,10 @@ export type SubscriptionProviderPlugin = {
   ) => Promise<{ readonly url: string }>;
 
   /**
-   * Optional: Cancel-aus-der-App-API. Wenn nicht implementiert, kann
-   * der Tenant nur über den Customer-Portal-Link cancellen (oder gar
-   * nicht, wenn auch createPortalSession fehlt — dann ist
-   * Cancel-Flow Provider-Dashboard-only).
+   * Optional: in-app cancellation API. If not implemented, the tenant
+   * can cancel only through the Customer Portal link (or not at all if
+   * createPortalSession is also missing — the cancellation flow is then
+   * provider-dashboard-only).
    */
   readonly cancelSubscription?: (
     ctx: HandlerContext,

package/packages/bundled-features/src/billing-foundation/web/billing-plans-panel.tsx

@@ -78,10 +78,10 @@ function manageOrReactivateAction(
   };
 }
 
-/** `!canPurchase` hides every CTA outright (spec: "keine CTAs, Hinweis
- *  purchaseNotAllowed") — distinct from the `unavailable` action's disabled
- *  CTA, which still shows a button (e.g. for a plan whose price failed to
- *  load) so this check runs before the general unavailable-fallback. */
+/** `!canPurchase` hides every CTA outright (see `purchaseNotAllowed`) — distinct
+ *  from the `unavailable` action's disabled CTA, which still shows a button
+ *  (for example, when a plan's price failed to load), so this check runs
+ *  before the general unavailable fallback. */
 
 function planCta(
   plan: BillingPlanView,

package/packages/bundled-features/src/billing-foundation/webhook-handler.ts

@@ -95,7 +95,7 @@ export function createSubscriptionWebhookRoute(options: SubscriptionWebhookRoute
         return c.json({ ignored: true }, 200);
       }
       const parsed = verified.event;
-      const tenantId = parsed.tenantId as import("@cosmicdrift/kumiko-framework/engine").TenantId;
+      const tenantId = parsed.tenantId;
       if (parsed.kind === BillingEventKinds.payment) {
         const dispatched = await deps.dispatchSystemWrite({
           handlerQn: SubscriptionFoundationHandlers.processPaymentEvent,