@cosmicdrift/kumiko-bundled-features 0.385.0 → 0.387.0

package/dist/auth-mfa/web/mfa-client.js

@@ -1,10 +1,10 @@
-// Browser-Seite von POST /api/auth/mfa/verify — completes the two-step
-// login LoginScreen started when the server responded mfaRequired. Same
-// fetch/CSRF pattern as auth-email-password's login() (pre-session, no
-// csrfHeader() — there's no session yet to protect). Response shape is
+// Browser side of POST /api/auth/mfa/verify — completes the two-step
+// login that LoginScreen started when the server responded with mfaRequired.
+// Uses the same fetch/CSRF pattern as auth-email-password's login(), but runs
+// before a session exists, so it does not call csrfHeader(). The response is
 // byte-identical to /auth/login's ({isSuccess, token, user} | {isSuccess:
-// false, error}) since auth-routes.ts mints via the same
-// mintSessionAndRespond() for both routes.
+// false, error}) because auth-routes.ts uses mintSessionAndRespond() for both
+// routes.
 // kumiko-lint-ignore cross-feature-import client-only types, the feature's server barrel has no web/ re-export
 import { toLoginResponse, } from "../../auth-email-password/web/index.js";
 export async function verifyMfaChallenge(challengeToken, code) {
@@ -40,11 +40,12 @@ export async function verifyMfaChallenge(challengeToken, code) {
         },
     };
 }
-// Browser-Seite von POST /api/auth/mfa/preauth-enable-start — lets a user
+// Browser side of POST /api/auth/mfa/preauth-enable-start — lets a user
 // blocked at login by MFA enforcement generate a TOTP secret/QR without a
-// session, using the preauthSetupToken login()'s mfa-setup-required result
-// carries. No JWT/cookie here (see auth-routes.ts's route comment) — the
-// response's setupToken is consumed by confirmMfaSetupPreauth below.
+// session, using the preauthSetupToken carried by login()'s
+// mfa-setup-required result. No JWT/cookie is issued here (see the route
+// comment in auth-routes.ts); the response's
+// setupToken is consumed by confirmMfaSetupPreauth below.
 export async function startMfaSetupPreauth(preauthSetupToken, accountLabel) {
     const res = await fetch("/api/auth/mfa/preauth-enable-start", {
         method: "POST",
@@ -85,12 +86,12 @@ export async function startMfaSetupPreauth(preauthSetupToken, accountLabel) {
         },
     };
 }
-// Browser-Seite von POST /api/auth/mfa/preauth-confirm — completes both
-// the enrollment startMfaSetupPreauth began and the login mfa-setup-
-// required block. Response shape mirrors /auth/mfa/verify's (mints via
-// the same mintSessionAndRespond()), same as verifyMfaChallenge above —
-// kept as its own function rather than a shared helper so this file's
-// two already-tested request shapes stay independently editable.
+// Browser side of POST /api/auth/mfa/preauth-confirm — completes both the
+// enrollment started by startMfaSetupPreauth and the login
+// mfa-setup-required block. Its response mirrors /auth/mfa/verify's and is
+// minted via the same mintSessionAndRespond(). It remains a separate function
+// so this file's two already-tested request shapes stay independently
+// editable.
 export async function confirmMfaSetupPreauth(setupToken, code) {
     const res = await fetch("/api/auth/mfa/preauth-confirm", {
         method: "POST",

package/dist/auth-mfa/web/mfa-verify-screen.js

@@ -1,10 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// Login-Challenge-Step, gerendert wenn LoginScreen's onMfaChallenge feuert
-// (/auth/login antwortete mfaRequired). Stilistisch wie login-screen.tsx:
-// useState + direkter fetch-Call, kein Dispatcher — es existiert noch kein
-// JWT. Nach Erfolg ruft es session.refresh() statt eines Hard-Reloads, weil
-// der Aufrufer (typisch ein Wizard-State im App-Root) sofort neu rendern
-// will, sobald status:"authenticated" ankommt.
+// Login challenge step, rendered when LoginScreen's onMfaChallenge fires
+// (/auth/login returned mfaRequired). It follows login-screen.tsx:
+// useState plus a direct fetch call, without a dispatcher because no JWT
+// exists yet. After success, it calls session.refresh() instead of a hard
+// reload so the caller (typically wizard state in the app root) can render
+// immediately when status:"authenticated" arrives.
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { useState } from "react";
 // kumiko-lint-ignore cross-feature-import client-only barrel, the feature's server barrel has no web/ re-export

package/dist/billing-foundation/aggregate-id.d.ts

@@ -1,9 +1,9 @@
 /**
- * Deterministic aggregate-id für die subscription eines Plattform-
- * Tenants. EINE Subscription pro Tenant (Add-Ons sind line-items in
- * derselben subscription, nicht eigene). Provider-Wechsel (z.B.
- * Stripe→Mollie-Migration) appended einen neuen event auf denselben
- * Stream — selber Tenant, selber Aggregate-Stream.
+ * Deterministic aggregate ID for a platform tenant's subscription. Exactly
+ * one subscription exists per tenant; add-ons are line items in that
+ * subscription, not separate aggregates. A provider change, such as a
+ * Stripe→Mollie migration, appends a new event to the same stream because
+ * the tenant and aggregate stream remain the same.
  */
 export declare function subscriptionAggregateId(tenantId: string): string;
 /**

package/dist/billing-foundation/aggregate-id.js

@@ -1,10 +1,9 @@
 import { v5 as uuidv5 } from "uuid";
-// Fixed UUID-namespace für die deterministic aggregate-id-Ableitung.
-// Generiert einmalig (2026-05-03), in Stein gemeißelt: ein Wechsel
-// würde jeden existing aggregate-Stream re-keyen → kaputter
-// Subscription-State, kaputte Audit-History. Drift-Pin in
-// __tests__/feature.test.ts pinnt die UUID.
-/** Pro Plattform-Tenant existiert genau EIN subscription-Aggregate. */
+// Fixed UUID namespace for deterministic aggregate-id derivation.
+// Generated once and immutable: changing it would re-key every existing
+// aggregate stream, breaking subscription state and audit history. The drift
+// pin in __tests__/feature.test.ts locks the UUID.
+/** Exactly one subscription aggregate exists per platform tenant. */
 const SUBSCRIPTION_NAMESPACE = "5c3b2d1e-9a4f-4e8c-b7a3-1f8d6c2e9a4b";
 /** Exactly ONE payment-aggregate-stream exists per platform tenant (it
  *  collects many payment-received events — one stream per tenant, not one
@@ -20,11 +19,11 @@ const PAYMENT_ROW_NAMESPACE = "3a1c9f4e-6b2d-4c8a-9e5f-7d4b1a2c8e6f";
  *  declaration (one stream per request). Generated 2026-10-03, set in stone. */
 const TERMINATION_UNMATCHED_NAMESPACE = "7e2f4b9a-3c1d-4a68-8d05-b6c9e1f27a34";
 /**
- * Deterministic aggregate-id für die subscription eines Plattform-
- * Tenants. EINE Subscription pro Tenant (Add-Ons sind line-items in
- * derselben subscription, nicht eigene). Provider-Wechsel (z.B.
- * Stripe→Mollie-Migration) appended einen neuen event auf denselben
- * Stream — selber Tenant, selber Aggregate-Stream.
+ * Deterministic aggregate ID for a platform tenant's subscription. Exactly
+ * one subscription exists per tenant; add-ons are line items in that
+ * subscription, not separate aggregates. A provider change, such as a
+ * Stripe→Mollie migration, appends a new event to the same stream because
+ * the tenant and aggregate stream remain the same.
  */
 // @wrapper-known uuid-domain
 export function subscriptionAggregateId(tenantId) {

package/dist/billing-foundation/entities.js

@@ -1,38 +1,38 @@
 import { collectPiiSubjectFields } from "@cosmicdrift/kumiko-framework/crypto";
 import { createEntity, createTextField, createTimestampField, } from "@cosmicdrift/kumiko-framework/engine";
-// `subscription` — current state pro Plattform-Tenant (= Read-Model)
+// `subscription` — current state per platform tenant (= read model)
 // =============================================================================
 //
-// Inline-Projection-Target. Geschrieben vom `subscription`-projection-
-// apply (siehe feature.ts), NIE direkt vom handler. Source-of-truth ist
-// der event-store stream `subscription` mit aggregate-id =
+// Inline projection target. Written by the `subscription` projection-
+// apply (see feature.ts), NEVER directly by the handler. Source of truth is
+// the event-store stream `subscription` with aggregate-id =
 // uuidv5(SUBSCRIPTION_NAMESPACE, tenantId).
 //
-// EINE Row pro Plattform-Tenant. Aggregate-ID ist deterministic, damit
-// Webhook-Replays (Stripe sendet bei Hängern bis zu 5x in 4h) auf
-// denselben Stream schreiben statt zwei Rows zu erzeugen.
+// ONE row per platform tenant. The aggregate ID is deterministic so that
+// webhook replays (Stripe sends up to 5 times in 4 hours when delivery is
+// stalled) write to the same stream instead of creating two rows.
 //
-// **Felder:**
-//   - providerName: "stripe" / "mollie" — welcher Provider die
-//     Subscription hält. Provider-Wechsel = neuer event auf demselben
-//     Stream, projection überschreibt.
-//   - providerCustomerId / providerSubscriptionId: provider-eigene
-//     IDs.
+// **Fields:**
+//   - providerName: "stripe" / "mollie" — the provider holding the
+//     subscription. A provider change is a new event on the same stream;
+//     the projection overwrites the value.
+//   - providerCustomerId / providerSubscriptionId: provider-specific IDs.
 //   - status: active / past_due / canceled / trialing / incomplete —
-//     normalisiert über provider-grenzen hinweg.
-//   - tier: "free" / "pro" / ... — vom tier-engine konsumiert. Aus
-//     price-to-tier-Map resolved im Plugin.
-//   - currentPeriodEnd: wann läuft die aktuelle Billing-Period aus.
+//     normalized across providers.
+//   - tier: "free" / "pro" / ... — consumed by the tier engine. Resolved
+//     from the price-to-tier map in the plugin.
+//   - currentPeriodEnd: when the current billing period ends.
 //   - cancelAt: when a scheduled cancellation ends the subscription;
 //     nullable because a renewing subscription has none.
 //
-// **Was hier NICHT ist:**
-//   - invoice-history, payment-method, line-items, tax-info → all das
-//     fetcht der Tenant via customer-portal-session direkt vom Provider.
+// **Not included here:**
+//   - invoice-history, payment-method, line-items, tax-info — the tenant
+//     fetches all of these directly from the provider via a
+//     customer-portal-session.
 //
-// **Audit/event-history:** lebt im event-store unter dem `subscription`-
-// stream — KEIN eigene `subscription-event`-Tabelle mehr (= ES ist die
-// audit-truth, replay-fähig durch upcasters).
+// **Audit/event history:** lives in the event store under the `subscription`
+// stream — there is NO separate `subscription-event` table (= ES is the
+// audit source of truth and can be replayed through upcasters).
 export const subscriptionEntity = createEntity({
     table: "read_subscriptions",
     fields: {
@@ -43,10 +43,10 @@ export const subscriptionEntity = createEntity({
             reason: "technical_reference",
         }),
         // `personal: "tenant"` (not `encrypted`): the field must crypto-shred when
-        // eraseSubjectKeys erases the tenant's subject key on tenant-destroy
-        // (#800). `encrypted: true` uses the app-wide master key instead — that
+        // eraseSubjectKeys erases the tenant's subject key on tenant-destroy.
+        // `encrypted: true` uses the app-wide master key instead — that
         // key is never erased per-tenant, so it would only add encryption-at-
-        // rest, not the erasure guarantee #800 actually asks for.
+        // rest, not the erasure guarantee.
         // maxLength 1000, not 200: the stored value is PII-ciphertext
         // (`kumiko-pii:v1:<subject>:<blob>`), not the raw provider id — a
         // 200-char plaintext id becomes ~300+ chars of ciphertext. Matches
@@ -106,7 +106,7 @@ export const paymentEntity = createEntity({
             reason: "technical_reference",
         }),
         // Same `personal: "tenant"` rationale as subscriptionEntity above —
-        // crypto-shreds on tenant-destroy (#800) via eraseSubjectKeys.
+        // crypto-shreds on tenant-destroy via eraseSubjectKeys.
         providerCustomerId: createTextField({
             required: true,
             maxLength: 1000,

package/dist/billing-foundation/events.js

@@ -1,22 +1,22 @@
-// Domain-events für subscription-foundation.
+// Domain events for subscription-foundation.
 //
-// **Pattern:** event-sourced — jeder Provider-Webhook (nach Plugin-
-// verify) wird zu einem domain-event auf dem subscription-stream
-// (= ein stream pro Tenant via subscriptionAggregateId(tenantId)).
-// Read-model = inline projection in `subscriptions`-Tabelle.
+// **Pattern:** event-sourced — each provider webhook (after plugin
+// verification) becomes a domain event on the subscription stream
+// (= one stream per tenant via subscriptionAggregateId(tenantId)).
+// The read model is an inline projection in the `subscriptions` table.
 //
-// 5 fine-grained event-typen statt einem generic "webhook-received"-
-// bucket — events sind business-facts: future-consumer (billing-history,
-// accounting-export, churn-analytics) listenen direkt auf den event-
-// type ohne payload-discriminator.
+// Five fine-grained event types instead of a generic "webhook-received"
+// bucket — events are business facts: future consumers (billing-history,
+// accounting-export, churn-analytics) listen directly for the event type
+// without a payload discriminator.
 import * as z from "zod";
 import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./web/constants.js";
 import { CONSENT_LOCALES } from "./web/consumer-protection/consent-locale.js";
-// Aggregate-type für den event-store. Eine subscription pro Tenant ist
-// ein stream; der subscriptionAggregateId-helper liefert die stream-id.
+// Aggregate type for the event store. One subscription per tenant is
+// one stream; the subscriptionAggregateId helper provides the stream ID.
 export const SUBSCRIPTION_AGGREGATE_TYPE = "subscription";
-// Event-name-Konstanten — short-form (für r.defineEvent) + qualifizierte
-// FQN (für ctx.unsafeAppendEvent + projection-apply-keys).
+// Event-name constants — short form (for r.defineEvent) and qualified
+// FQN (for ctx.unsafeAppendEvent and projection-apply keys).
 export const SUBSCRIPTION_CREATED_EVENT_SHORT = "subscription-created";
 export const SUBSCRIPTION_UPDATED_EVENT_SHORT = "subscription-updated";
 export const SUBSCRIPTION_CANCELED_EVENT_SHORT = "subscription-canceled";
@@ -27,7 +27,7 @@ export const SUBSCRIPTION_UPDATED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:even
 export const SUBSCRIPTION_CANCELED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${SUBSCRIPTION_CANCELED_EVENT_SHORT}`;
 export const INVOICE_PAID_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${INVOICE_PAID_EVENT_SHORT}`;
 export const INVOICE_PAYMENT_FAILED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${INVOICE_PAYMENT_FAILED_EVENT_SHORT}`;
-// Status-enum für event-payloads (= subscription-state-snapshot vom Provider).
+// Status enum for event payloads (= the provider's subscription-state snapshot).
 const statusEnum = z.enum([
     SubscriptionStatuses.active,
     SubscriptionStatuses.trialing,
@@ -35,10 +35,11 @@ const statusEnum = z.enum([
     SubscriptionStatuses.canceled,
     SubscriptionStatuses.incomplete,
 ]);
-// Common payload — alle 5 events tragen denselben subscription-state-
-// snapshot. Event-type tagged was passiert ist, payload den state-after.
+// Common payload — all five events carry the same subscription-state
+// snapshot. The event type identifies what happened; the payload contains
+// the resulting state.
 // The raw provider event is deliberately not stored: it carries plaintext
-// PII and event headers are not crypto-shreddable.
+// PII, and event headers cannot be crypto-shredded.
 export const subscriptionEventPayloadSchema = z.object({
     providerName: z.string().min(1).max(50),
     // 1000, not 200: these two are `tenantOwned: true` on the entity (see

package/dist/billing-foundation/feature.js

@@ -1,54 +1,53 @@
 // kumiko-feature-version: 1
 //
-// subscription-foundation als Kumiko bundled feature (Plugin-Host).
+// subscription-foundation as a 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.
+// **Multi-provider from day one** — the app builder can mount multiple plugins
+// in parallel (subscription-stripe + subscription-paypal +
+// subscription-apple-iap + ...), and the end user chooses between
+// card/PayPal/Apple Pay/Klarna/SEPA at checkout (Disney+ pattern).
+// There is no global `provider` config key — all mounted plugins are active.
 //
-// **Was diese Foundation liefert:**
-//   1. **Plugin-API** für Subscription-Provider via `r.extendsRegistrar(
+// **What this foundation provides:**
+//   1. **Plugin API** for subscription providers 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
+//   2. **5 domain events** on the `subscription` stream (one stream ID per
+//      tenant): created/updated/canceled/invoice-paid/invoice-payment-failed.
+//      Audit history is provided automatically by the event store.
+//   3. **Inline projection** onto `read_subscriptions` (current state per
+//      tenant). Apply runs in the same TX as the event append
 //      → read-your-own-write semantics.
-//   4. **process-event-handler**: programmatic write-handler den der
-//      webhook-handler aufruft, dispatcht zu type-passendem appendEvent.
+//   4. **process-event handler**: a programmatic write handler called by the
+//      webhook handler that dispatches to the type-matched 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).
+//   6. **payment-received event + read_payments projection**: one-off payments
+//      (checkout mode "payment") get their own event, per-tenant aggregate,
+//      and `process-payment-event` write handler — not a sixth
+//      SubscriptionEventTypes value.
 //   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
+//      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.
+//      single `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`.
+// **What this foundation does NOT do:**
+//   - No r.entity for `subscription`. The table is a read-only projection —
+//     there is no CRUD path. It is written exclusively via projection-apply,
+//     triggered by one of the 5 events.
+//   - No tier sync with tier-engine. App owners can read the subscription row
+//     via `getSubscriptionForTenant(ctx, tenantId)` if needed.
+//   - No provider-specific configs.
+//   - No marketplace use case (the app tenant bills end customers via Stripe
+//     Connect). That comes later as a 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.
+// **Provider changes:** The Disney+ pattern (the tenant cancels a Stripe
+// subscription and starts a new one with PayPal) is currently modeled as a
+// second `subscription-created` event. UPSERT in projection-apply overwrites
+// the existing row with the new providerName. This is sufficient for the MVP.
+// If the business fact "provider change" needs its own domain event (for
+// example, for analytics such as "how many changes per month?"), a
+// `subscription-provider-changed` event type can be added later.
 import { defineFeature, EXT_TENANT_DATA, } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { registerConsumerProtection } from "./consumer-protection/register-consent.js";
@@ -147,18 +146,18 @@ export function createBillingFoundationFeature(options = {}) {
                 [PAYMENT_RECEIVED_EVENT_QN]: applyPaymentReceived,
             },
         });
-        // Plugin extension-point. Provider-Plugins registrieren sich hier.
+        // Plugin extension point. Provider plugins register here.
         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
+        // Custom write handlers:
+        //   - process-event: programmatic entry point called by the webhook
+        //     handler; dispatches to the type-matched appendEvent
         //   - create-checkout-session: bare priceId-driven checkout (hardened,
         //     see checkout-core)
-        //   - create-portal-session: Tenant-Admin "Manage Subscription"-flow
+        //   - create-portal-session: Tenant Admin "Manage Subscription" flow
         r.writeHandler(createProcessEventHandler(widened.now));
         r.writeHandler(createCheckoutSessionHandler(widened));
         r.writeHandler(createPortalSessionHandler(widened));

package/dist/billing-foundation/get-subscription-for-tenant.d.ts

@@ -15,7 +15,7 @@ export type SubscriptionView = {
      *  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. */
+/** Returns the tenant's only subscription row (deterministic
+ *  aggregate ID), or null if the tenant has never subscribed. The status
+ *  may be active/canceled/past_due/etc.; the caller decides what to do. */
 export declare function getSubscriptionForTenant(ctx: HandlerContext, tenantId: string): Promise<SubscriptionView | null>;

package/dist/billing-foundation/get-subscription-for-tenant.js

@@ -1,13 +1,11 @@
 /// <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 { subscriptionAggregateId } from "./aggregate-id.js";
 import { SUBSCRIPTION_PII_FIELDS } from "./entities.js";
 import { subscriptionsProjectionTable } from "./projection.js";
-/** 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. */
+/** Returns the tenant's only subscription row (deterministic
+ *  aggregate ID), or null if the tenant has never subscribed. The status
+ *  may be active/canceled/past_due/etc.; the caller decides what to do. */
 export async function getSubscriptionForTenant(ctx, tenantId) {
     const aggId = subscriptionAggregateId(tenantId);
     const rows = await ctx.db.selectMany(subscriptionsProjectionTable, { id: aggId }, { limit: 1 });

package/dist/billing-foundation/handlers/create-checkout-session.write.js

@@ -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
@@ -31,12 +31,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/dist/billing-foundation/handlers/create-portal-session.write.js

@@ -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, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import * as z from "zod";

package/dist/billing-foundation/handlers/list-subscriptions.query.js

@@ -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, } from "@cosmicdrift/kumiko-framework/crypto";
 import * as z from "zod";
 import { SUBSCRIPTION_PII_FIELDS } from "../entities.js";

package/dist/billing-foundation/handlers/process-event.write.js

@@ -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, encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
@@ -21,9 +21,9 @@ import { INVOICE_PAID_EVENT_QN, INVOICE_PAYMENT_FAILED_EVENT_QN, SUBSCRIPTION_AG
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
 import { BILLING_SUBSCRIPTION_LOCK_NAMESPACE, isSubscriptionBlockingCheckout, isSwitchableSubscriptionStatus, SubscriptionEventTypes, SubscriptionStatuses, } from "../web/constants.js";
 // =============================================================================
-// 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([
     SubscriptionEventTypes.created,
@@ -153,9 +153,9 @@ export async function appendSubscriptionEvent(ctx, tenantId, rawPayload, now = T
     //    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();
@@ -203,9 +203,9 @@ export async function appendSubscriptionEvent(ctx, tenantId, rawPayload, now = T
 // 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