@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/subscription-mollie/feature.ts

@@ -1,26 +1,26 @@
 // kumiko-feature-version: 1
 //
-// subscription-mollie — Mollie-Plugin für die subscription-foundation
-// Plugin-API (EU-Compliance-Story für DACH-Mid-Market).
+// subscription-mollie — Mollie plugin for subscription-foundation
+// plugin API (EU compliance for the DACH mid-market).
 //
-// **Factory-Pattern (analog subscription-stripe):** liest API-key beim
-// mount-time aus den factory-options (typisch process.env aus dem App-
-// Builder-bin/server.ts). Mollie hat KEIN webhook-secret — Mollie-SDK
-// 4.5.0 bietet keine native HMAC-sig-verify-API. Sicherheit kommt aus
-// nicht-guessable IDs + API-Validation; App-Builder kann optional
-// einen URL-Token-Wrapper davor schalten.
+// **Factory pattern (analogous to subscription-stripe):** reads the API key
+// at mount time from the factory options (typically process.env from the app
+// builder's bin/server.ts). Mollie has NO webhook secret — Mollie SDK
+// 4.5.0 provides no native HMAC signature verification API. Security comes
+// from non-guessable IDs + API validation; the app builder can optionally
+// add a URL-token wrapper in front.
 //
-// **Phase-5.3-Scope:**
+// **Scope:**
 //   - verifyAndParseWebhook ✓ (lazy-fetch payment + subscription via
-//     Mollie-API, heuristisches event-type-mapping)
-//   - createCheckoutSession ✓ (Mollie's mehrstufiger flow: customer
-//     anlegen + first-payment mit sequenceType="first" → redirectUrl)
-//   - createPortalSession ✗ (Mollie hat keinen Customer-Portal)
-//   - cancelSubscription ✗ (Mollie braucht customerId zusätzlich zur
-//     subId; Plugin-Contract reicht's nicht durch — App-Builder cancelt
-//     via Mollie-Dashboard oder custom-route)
+//     Mollie API, heuristic event-type mapping)
+//   - createCheckoutSession ✓ (Mollie's multistep flow: create customer
+//     + first payment with sequenceType="first" → redirectUrl)
+//   - createPortalSession ✗ (Mollie has no customer portal)
+//   - cancelSubscription ✗ (Mollie additionally requires customerId besides
+//     subId; the plugin contract does not pass it through — the app builder
+//     cancels via the Mollie dashboard or a custom route)
 //
-// **Beispiel-Verwendung in run-config.ts:**
+// **Example usage in run-config.ts:**
 //
 //   const features = [
 //     billingFoundationFeature,
@@ -62,29 +62,28 @@ export const subscriptionMollieEnvSchema = z.object({
 });
 
 export type SubscriptionMollieOptions = {
-  /** Mollie-API-key (`test_...` oder `live_...`). App-wide, beim Plugin-
-   *  mount aus process.env oder system-config. */
+  /** Mollie API key (`test_...` or `live_...`). App-wide, mounted from
+   *  process.env or system configuration. */
   readonly apiKey: string;
-  /** Foundation-webhook-URL die der App-Builder unter Mollie-Dashboard
-   *  als webhook eingetragen hat. Plugin reicht das beim payment-
-   *  create an Mollie weiter — Mollie sendet beim payment-event
-   *  webhooks an diese URL. Typisch:
+  /** Foundation webhook URL registered by the app builder in the Mollie
+   *  dashboard. The plugin passes it to Mollie when creating a payment;
+   *  Mollie sends payment-event webhooks to this URL. Typically:
    *  `https://app.example.com/api/subscription/webhook/mollie`. */
   readonly webhookUrl: string;
-  /** Price-to-tier-Map. Plugin liest die priceId aus dem subscription-
-   *  metadata (= `metadata.priceId` den der App-Builder beim
-   *  createCheckoutSession setzt) und mappt auf einen tier-name. */
+  /** Price-to-tier map. The plugin reads the priceId from the subscription
+   *  metadata (= `metadata.priceId` set by the app builder when calling
+   *  createCheckoutSession) and maps it to a tier name. */
   readonly priceToTier: Readonly<Record<string, string>>;
-  /** Mollie-Subscription-Setup pro priceId. Mollie hat keinen nativen
-   *  price-id-Konzept — App-Builder muss pro virtuellem priceId einen
-   *  amount/interval/description bereitstellen. */
+  /** Mollie subscription setup per priceId. Mollie has no native price-ID
+   *  concept, so the app builder must provide an amount/interval/description
+   *  for each virtual priceId. */
   readonly priceToConfig: Readonly<Record<string, MolliePriceConfig>>;
-  /** @internal Test-only injection-port: ersetzt den verify-webhook-
-   *  fetch-client durch eine Mock-instance. Production left undefined —
-   *  factory baut den Adapter aus `createMollieClient(apiKey)`. Wird
-   *  vom IT (mollie-foundation.integration.ts) genutzt damit der echte
-   *  factory-Code (drift-validation, plugin-registration) im Test-pfad
-   *  durchläuft, ohne dass Mollie-API-Calls passieren. */
+  /** @internal Test-only injection port: replaces the verify-webhook fetch
+   *  client with a mock instance. Production leaves this undefined; the
+   *  factory builds the adapter from `createMollieClient(apiKey)`. The
+   *  integration test (mollie-foundation.integration.ts) uses it so the real
+   *  factory code (drift validation, plugin registration) runs in the test
+   *  path without making Mollie API calls. */
   readonly _clientShapeForTests?: MollieClientShape;
 };
 
@@ -102,8 +101,8 @@ export function createSubscriptionMollieFeature(
     );
   }
 
-  // Drift-Guard: priceToTier + priceToConfig müssen identische Keys
-  // haben — sonst silent-null-returns aus verifyAndParseWebhook.
+  // Drift guard: priceToTier and priceToConfig must have identical keys;
+  // otherwise verifyAndParseWebhook silently returns null.
   const tierKeys = new Set(Object.keys(options.priceToTier));
   const configKeys = new Set(Object.keys(options.priceToConfig));
   const missingInConfig = [...tierKeys].filter((k) => !configKeys.has(k));
@@ -118,9 +117,9 @@ export function createSubscriptionMollieFeature(
 
   const client = createMollieClient({ apiKey: options.apiKey });
 
-  // Adapter um den Plugin's verify-fetch-client an den vollen Mollie-
-  // Client zu binden. Plugin-fetch-API ist minimal damit Tests ohne
-  // den vollen MollieClient mocken können.
+  // Adapter that binds the plugin's minimal fetch client to the full Mollie
+  // client. The minimal plugin fetch API lets tests mock it without mocking
+  // the full MollieClient.
   const fetchAdapter: MollieClientShape = options._clientShapeForTests ?? {
     payments: { get: (id: string) => client.payments.get(id) },
     customerSubscriptions: {
@@ -160,8 +159,8 @@ export function createSubscriptionMollieFeature(
     const plugin: SubscriptionProviderPlugin = {
       verifyAndParseWebhook: verifyAndParse,
       createCheckoutSession: checkoutSession,
-      // createPortalSession + cancelSubscription bewusst nicht — siehe
-      // plugin-methods.ts für Begründung.
+      // createPortalSession and cancelSubscription are intentionally omitted;
+      // see plugin-methods.ts for why.
       priceToTier: options.priceToTier,
     };
     r.useExtension("subscriptionProvider", MOLLIE_PROVIDER_NAME, plugin);

package/packages/bundled-features/src/subscription-mollie/index.ts

@@ -1,9 +1,9 @@
 // Public API of the subscription-mollie bundled-feature.
 //
-// **Internal-only** (NICHT im public-barrel — App-Builder nutzt das nie direkt):
-//   - verifyAndParseMollieWebhook (intern vom feature.ts factory aufgerufen)
+// **Internal-only** (not in the public barrel—the App Builder never uses it directly):
+//   - verifyAndParseMollieWebhook (called internally by the feature.ts factory)
 //   - mapMollieEventType / mapMollieStatus / extractMollieId (pure helpers,
-//     test-only — direct-import aus dem File wenn echt mal extern gebraucht)
+//     test-only—direct-import from the file if ever genuinely needed externally)
 
 export { MOLLIE_PROVIDER_NAME, SUBSCRIPTION_MOLLIE_FEATURE } from "./constants.ts";
 export {

package/packages/bundled-features/src/subscription-mollie/plugin-methods.ts

@@ -1,17 +1,18 @@
-// Mollie-Plugin-Methoden für die POST-tenant-resolution-Phase:
-// createCheckoutSession (only). createPortalSession + cancelSubscription
-// nicht implementiert weil Mollie's API die Patterns nicht 1:1 bietet:
+// Mollie plugin methods for the POST-tenant-resolution phase:
+// createCheckoutSession only. createPortalSession and cancelSubscription
+// are not implemented because Mollie's API does not provide these patterns
+// 1:1:
 //
-// - **Portal:** Mollie hat keinen Customer-Portal — App-Builder UI muss
-//   das selbst rendern.
-// - **Cancel:** Mollie braucht (customerId, subId), Plugin-Contract
-//   reicht aber nur subId durch — App-Builder cancelt via Mollie-
-//   Dashboard oder eigener Route bis Foundation-Contract erweitert ist.
+// - **Portal:** Mollie has no customer portal, so the App Builder UI must
+//   render it itself.
+// - **Cancel:** Mollie requires (customerId, subId), but the plugin contract
+//   passes through only subId. The App Builder cancels through the Mollie
+//   dashboard or a custom route until the Foundation contract is extended.
 //
-// **Mollie-Checkout-Flow ist mehrstufig:** Customer anlegen → first-
-// payment mit sequenceType="first" (= Mandate-setup) → User bezahlt →
-// Mollie-webhook → verify-webhook erstellt die Mollie-Subscription
-// idempotent (siehe verify-webhook.ts ensureSubscriptionForMandate).
+// **The Mollie checkout flow has multiple steps:** create customer → first
+// payment with sequenceType="first" (= mandate setup) → user pays →
+// Mollie webhook → verify-webhook creates the Mollie subscription
+// idempotently (see verify-webhook.ts ensureSubscriptionForMandate).
 
 import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
@@ -22,8 +23,8 @@ export type MollieCheckoutOptions = Parameters<
   NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>
 >[1];
 
-/** Mollie hat keinen nativen price-id-Konzept — App-Builder pflegt
- *  pro virtuellem priceId einen amount/interval/description. */
+/** Mollie has no native price ID concept; the App Builder maintains
+ *  an amount/interval/description for each virtual priceId. */
 export type MolliePriceConfig = {
   /** Mollie-format: 2-decimal string, z.B. `"9.99"`. */
   readonly amountValue: string;
@@ -67,8 +68,8 @@ export function createMollieCheckoutSession(
     // any mandate/subscription handling.
     const sequenceType = options.mode === "payment" ? SequenceType.oneoff : SequenceType.first;
 
-    // payments.create ist overloaded (Promise OR void mit callback);
-    // explicit cast auf Promise<Payment>-overload.
+    // payments.create is overloaded (Promise or void with a callback);
+    // explicitly cast to the Promise<Payment> overload.
     const payment = (await (client.payments.create({
       amount: { currency: priceCfg.amountCurrency, value: priceCfg.amountValue },
       description: priceCfg.description,

package/packages/bundled-features/src/subscription-mollie/verify-webhook.ts

@@ -1,18 +1,18 @@
-// verifyAndParseMollieWebhook — Mollie-spezifische lazy-fetch +
-// event-type-Heuristik. Wird vom Plugin-Build (feature.ts) als
-// `verifyAndParseWebhook` registriert.
+// verifyAndParseMollieWebhook: Mollie-specific lazy fetch plus event-type
+// heuristic. The plugin build (feature.ts) registers it as
+// `verifyAndParseWebhook`.
 //
-// Mollie's classic-webhook sendet nur eine `id` (form-urlencoded oder
-// JSON). Wir lazy-fetchen payment + subscription via Mollie-API. Sub-
-// xxx-events werden NICHT supported — App-Builder bekommt sie indirekt
-// via tr_xxx-payment-events (Mollie sendet beide parallel bei normalen
-// Lifecycle-Events).
+// Mollie's classic webhook sends only an `id` (form-urlencoded or JSON), so
+// the payment and subscription are lazily fetched through the Mollie API.
+// sub_xxx events are NOT supported; app builders get them indirectly through
+// tr_xxx payment events (Mollie sends both in parallel for normal lifecycle
+// events).
 //
-// **Mandate-setup-flow:** first-payment-paid kommt mit
-// `payment.subscriptionId === null` (Mollie's Pattern: App-Builder
-// muss `customerSubscriptions.create` selbst aufrufen). Wir machen
-// das im Plugin (idempotent via list-check), damit Foundation einen
-// Created-Event mit subscription-id bekommt.
+// **Mandate setup flow:** the first paid payment arrives with
+// `payment.subscriptionId === null` (Mollie's pattern: the app builder must
+// call `customerSubscriptions.create` itself). The plugin does that
+// (idempotent via a list check) so the foundation receives a created event
+// with a subscription id.
 
 import {
   parseProviderConsentId,
@@ -33,9 +33,9 @@ import type { MolliePriceConfig } from "./plugin-methods.ts";
 
 const log = createFallbackLogger("subscription-mollie");
 
-/** Minimal-Subset des Mollie-Clients, das der Plugin nutzt — separat
- *  damit Tests ohne den vollen MollieClient mocken können. Adapter in
- *  feature.ts bridged das gegen den echten SDK. */
+/** Minimal subset of the Mollie client used by the plugin — kept separate
+ *  so tests can mock it without the full MollieClient. The adapter in
+ *  feature.ts bridges it to the real SDK. */
 export type MollieClientShape = {
   readonly payments: { readonly get: (id: string) => Promise<MolliePayment> };
   readonly customerSubscriptions: {
@@ -54,11 +54,11 @@ export type MollieClientShape = {
 };
 
 export type MollieWebhookOptions = {
-  /** priceId (= virtueller Schlüssel aus subscription.metadata) → tier-name. */
+  /** priceId (= virtual key from subscription.metadata) → tier name. */
   readonly priceToTier: Readonly<Record<string, string>>;
-  /** priceId → amount/interval/description. Wird beim mandate-setup-
-   *  flow zum `customerSubscriptions.create`-Call gebraucht. App-
-   *  Builder pflegt die Map einmal in den factory-options. */
+  /** priceId → amount/interval/description. Needed for the mandate-setup
+   *  flow's `customerSubscriptions.create` call. The app builder maintains
+   *  this map once in the factory options. */
   readonly priceToConfig: Readonly<Record<string, MolliePriceConfig>>;
 };
 
@@ -97,7 +97,7 @@ export function verifyAndParseMollieWebhook(
         subscription = await ensureSubscriptionForMandate(client, options, payment);
         if (!subscription) return null;
       } else {
-        // One-shot oder first-payment-failed → nicht unsere Domain.
+        // One-shot or first-payment-failed events are outside our domain.
         return null;
       }
     } else if (id.startsWith("sub_")) {
@@ -121,8 +121,8 @@ export function verifyAndParseMollieWebhook(
     const status = mapMollieStatus(subscription.status);
     const periodEndSource = subscription.nextPaymentDate ?? subscription.startDate;
     if (!periodEndSource) {
-      // Mollie-API-Drift: valid Subs haben mindestens startDate. Loud-
-      // fail damit App-Owner's monitoring den drift sieht.
+      // Mollie API drift: valid subscriptions have at least startDate. Fail
+      // loudly so the app owner's monitoring can detect the drift.
       throw new Error(
         `subscription-mollie: subscription ${subscription.id} has neither nextPaymentDate nor startDate`,
       );
@@ -149,9 +149,9 @@ export function verifyAndParseMollieWebhook(
 // Mandate-setup: subscription on-the-fly erstellen
 // =============================================================================
 
-/** first-payment-paid OHNE subscriptionId → Mollie-Sub erstellen.
- *  Idempotent via list-check (replay-safe). Returns null bei
- *  unvollständiger metadata oder unbekanntem priceId. */
+/** `first-payment-paid` without subscriptionId → create a Mollie subscription.
+ *  Idempotent via a list check (replay-safe). Returns null for incomplete
+ *  metadata or an unknown priceId. */
 async function ensureSubscriptionForMandate(
   client: MollieClientShape,
   options: MollieWebhookOptions,
@@ -188,10 +188,10 @@ async function ensureSubscriptionForMandate(
 }
 
 // =============================================================================
-// Helpers (exported für Tests)
+// Helpers (exported for tests)
 // =============================================================================
 
-/** Extract `id` aus rawBody — handelt form-urlencoded + JSON. */
+/** Extracts `id` from rawBody — supports form-urlencoded and JSON. */
 export function extractMollieId(rawBody: string, headers: Record<string, string>): string | null {
   const contentType = headers["content-type"] ?? "";
   if (contentType.includes("application/json")) {
@@ -210,8 +210,8 @@ export function extractMollieId(rawBody: string, headers: Record<string, string>
   return params.get("id");
 }
 
-/** Mollie-subscription + optional payment → SubscriptionEventType.
- *  Heuristik (Mollie hat keine explicit-typed events). */
+/** Mollie subscription + optional payment → SubscriptionEventType.
+ *  Heuristic because Mollie has no explicitly typed events. */
 export function mapMollieEventType(
   subscription: MollieSubscription,
   triggerPayment: MolliePayment | null,
@@ -240,10 +240,10 @@ export function mapMollieStatus(mollieStatus: MollieSubscription["status"]): Sub
       return SubscriptionStatuses.active;
     case "canceled":
     case "completed":
-      // completed = alle `times`-charges durchgelaufen → wie canceled.
+      // completed = all `times` charges have run → treat it like canceled.
       return SubscriptionStatuses.canceled;
     case "suspended":
-      // Mandate ungültig / payment-method failed → grace-period.
+      // Invalid mandate / payment method failed → grace period.
       return SubscriptionStatuses.pastDue;
     case "pending":
       return SubscriptionStatuses.incomplete;
@@ -252,8 +252,8 @@ export function mapMollieStatus(mollieStatus: MollieSubscription["status"]): Sub
   }
 }
 
-/** Mollie liefert dates als YYYY-MM-DD; foundation will ISO-Instant.
- *  Throws bei malformed input (= Mollie-API-Drift, soll loud-fail). */
+/** Mollie provides dates as YYYY-MM-DD; Foundation requires an ISO Instant.
+ *  Throws on malformed input (= Mollie API drift, which should fail loudly). */
 function mollieDateStringToInstantIso(dateString: string): string {
   return Temporal.Instant.from(`${dateString.slice(0, 10)}T00:00:00Z`).toString();
 }

package/packages/bundled-features/src/subscription-stripe/constants.ts

@@ -1,8 +1,8 @@
 // Feature name
 export const SUBSCRIPTION_STRIPE_FEATURE = "subscription-stripe" as const;
 
-// entityName under den der Plugin gegen "subscriptionProvider"
-// registriert. Matcht den path-segment in der webhook-URL
+// entityName under which the plugin registers itself as
+// "subscriptionProvider". It must match the path segment in the webhook URL
 // `/api/subscription/webhook/stripe`.
 export const STRIPE_PROVIDER_NAME = "stripe" as const;
 
@@ -14,10 +14,8 @@ export const STRIPE_API_KEY_CONFIG = "api-key" as const;
 export const STRIPE_WEBHOOK_SECRET_CONFIG = "webhook-secret" as const;
 export const STRIPE_BILLING_LIVE_CONFIG = "billingLive" as const;
 
-// =============================================================================
-// Stripe-event-types die wir auf normalisierte SubscriptionEventTypes
-// mappen. Stripe hat ~80 event-types insgesamt; wir filtern auf 5.
-// =============================================================================
+// Stripe event types that map to normalized SubscriptionEventTypes.
+// Stripe has approximately 80 event types; we filter to five.
 
 export const StripeEventTypes = {
   customerSubscriptionCreated: "customer.subscription.created",

package/packages/bundled-features/src/subscription-stripe/feature.ts

@@ -1,35 +1,36 @@
 // kumiko-feature-version: 3
 //
-// subscription-stripe — Stripe-Plugin für die billing-foundation
-// Plugin-API.
+// subscription-stripe — Stripe plugin for the billing-foundation
+// plugin API.
 //
-// **Runtime-config (v3):** Stripe-credentials + der billing-live-Master-
-// Switch kommen ZUR LAUFZEIT aus dem config-Feature, nicht mehr aus einem
-// mount-time-Closure. Damit lassen sich Keys rotieren und prod live-
-// schalten ohne Redeploy — und die Eingabe-Maske entsteht von selbst.
+// **Runtime config (v3):** Stripe credentials and the billing-live master
+// switch come from the config feature AT RUNTIME, no longer from a
+// mount-time closure. This allows keys to rotate and production to go live
+// without a redeploy — and the input form is generated automatically.
 //   - `subscription-stripe:config:api-key` + `:webhook-secret` → system
-//     config keys mit **backing:"secrets"**: der Wert lebt envelope-
-//     verschlüsselt im secrets-Store unter SYSTEM_TENANT_ID, adressiert
-//     wird er als config-Key. `mask` leitet den Sysadmin-configEdit-Screen
-//     + Settings-Hub-Nav ab — kein handgeschriebenes r.screen/r.nav in der
-//     App mehr (v2 hatte die Keys als `r.secret` + App-eigene Maske).
+//     config keys with **backing:"secrets"**: the value is envelope-encrypted
+//     in the secrets store under SYSTEM_TENANT_ID and addressed as a
+//     config key. `mask` derives the sysadmin configEdit screen +
+//     Settings-Hub navigation — the app no longer needs handwritten
+//     r.screen/r.nav entries (v2 used `r.secret` keys + an app-owned form).
 //   - `subscription-stripe:config:billing-live` (shortKey `billingLive`,
-//     kebab-qualifiziert von r.config) → **system config**
-//     (boolean, default false). Der Master-Switch: ohne ihn darf kein
-//     checkout eine Stripe-Session erzeugen (#104-Invariante, write-side
-//     im createCheckoutSession-Gate durchgesetzt).
+//     kebab-qualified by r.config) → **system config**
+//     (boolean, default false). The master switch: without it, checkout may
+//     not create a Stripe session; this is enforced in the
+//     createCheckoutSession gate.
 //
-// **Factory-options als Fallback:** `createSubscriptionStripeFeature({
-// apiKey, webhookSecret, priceToTier })` bleibt — apiKey/webhookSecret
-// sind jetzt OPTIONAL und dienen nur als Fallback während der env→secrets-
-// Bridge-Phase und in Tests, die keinen secrets-context wiren. `priceToTier`
-// (Stripe-price-id → app-tier-name) bleibt eine factory-option: app-
-// spezifisch, kein Secret, ändert sich selten.
+// **Factory options as fallback:** `createSubscriptionStripeFeature({
+// apiKey, webhookSecret, priceToTier })` remains — apiKey/webhookSecret
+// are now OPTIONAL and serve only as fallbacks during the env→secrets
+// bridge phase and in tests that do not wire a secrets context. `priceToTier`
+// (Stripe price ID → app tier name) remains a factory option: it is
+// app-specific, is not a secret, and changes infrequently.
 //
-// **Webhook + system-secrets:** verifyAndParseWebhook ist pre-tenant
-// (kein ctx). Der billing-foundation-webhook-handler reicht einen system-
-// scoped SecretsContext als 3. Arg durch, aus dem der Plugin api-key +
-// webhook-secret un-audited liest (sanctioned framework-internal read).
+// **Webhook + system secrets:** verifyAndParseWebhook is pre-tenant
+// (no ctx). The billing-foundation webhook handler passes a system-scoped
+// SecretsContext as the third argument, from which the plugin reads the
+// api key + webhook secret without auditing (a sanctioned framework-internal
+// read).
 
 import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import {
@@ -115,17 +116,17 @@ export function stripeEnvSchema<const TPrice extends string>(options: {
 }
 
 export type SubscriptionStripeOptions = {
-  /** Bridge-fallback webhook-secret. Optional: v2 liest aus dem
-   *  `subscription-stripe:config:webhook-secret`-Key (backing:"secrets").
-   *  Gesetzt nur während der env→secrets-Übergangsphase / in Tests. */
+  /** Bridge-fallback webhook secret. Optional: v2 reads from the
+   *  `subscription-stripe:config:webhook-secret` key (backing:"secrets").
+   *  Set only during the env→secrets transition phase / in tests. */
   readonly webhookSecret?: string;
-  /** Bridge-fallback api-key. Optional: v2 liest aus dem
-   *  `subscription-stripe:config:api-key`-Key (backing:"secrets"). */
+  /** Bridge-fallback API key. Optional: v2 reads from the
+   *  `subscription-stripe:config:api-key` key (backing:"secrets"). */
   readonly apiKey?: string;
-  /** Price-to-tier-Mapping. Plugin liest die price-id aus dem Stripe-event
-   *  (subscription.items.data[0].price.id) und mappt auf einen tier-name.
-   *  App-spezifisch → bleibt factory-option. Fehlt die price-id im Mapping
-   *  → null (event ignored). */
+  /** Price-to-tier mapping. The plugin reads the price ID from the Stripe
+   *  event (subscription.items.data[0].price.id) and maps it to a tier name.
+   *  App-specific, so it remains a factory option. If the price ID is absent
+   *  from the mapping → null (event ignored). */
   readonly priceToTier?: Readonly<Record<string, string>>;
   /** Whether a mode:"payment" checkout (one-off top-ups etc.) gets a Stripe
    *  invoice — a receipt/invoice document Stripe generates and sends to the
@@ -161,11 +162,11 @@ function validateOneOffPriceIds(priceIds: readonly string[]): void {
 }
 
 /**
- * Factory für das subscription-stripe-feature. Mountet IMMER (kein
- * key-presence-Guard mehr) — die Aktivität wird runtime über config/secrets
- * gegatet (Muster wie feature-toggles). Der returnte FeatureDefinition
- * registriert den Plugin gegen billing-foundation's "subscriptionProvider"-
- * extension unter entityName "stripe".
+ * Factory for the subscription-stripe feature. Always mounts (no
+ * key-presence guard) — activity is gated at runtime through config/secrets
+ * (following the feature-toggles pattern). The returned FeatureDefinition
+ * registers the plugin under billing-foundation's "subscriptionProvider"
+ * extension with entityName "stripe".
  */
 export function createSubscriptionStripeFeature(
   options: SubscriptionStripeOptions = {},
@@ -192,15 +193,15 @@ export function createSubscriptionStripeFeature(
     // the value lives envelope-encrypted in the secrets store under
     // SYSTEM_TENANT_ID, while `mask` derives the sysadmin settings screen +
     // Settings-Hub nav (no hand-written r.screen/r.nav in the consuming app).
-    // billingLive is the #104 master switch. The factory-fallback
+    // billingLive is the master switch. The factory-fallback
     // (options.apiKey/.webhookSecret) covers the env→secrets bridge + tests.
     const configKeys = r.config({
       keys: {
         [STRIPE_API_KEY_CONFIG]: createSystemConfig("text", {
           backing: "secrets",
-          // Prefix-Guard, deckungsgleich mit subscriptionStripeEnvSchema:
-          // fängt den Paste-the-wrong-field-Fehler (pk_/price_), ohne den
-          // base62-Body zu constrainen. Anchored, kein Backtracking → kein ReDoS.
+          // Prefix guard, matching subscriptionStripeEnvSchema:
+          // catches the wrong-field paste error (pk_/price_) without
+          // constraining the base62 body. Anchored, with no backtracking → no ReDoS.
           pattern: { regex: "^(sk|rk)_(test|live)_" },
           write: access.systemAdmin,
           read: access.admin,

package/packages/bundled-features/src/subscription-stripe/index.ts

@@ -1,10 +1,10 @@
-// Public API of the subscription-stripe bundled-feature.
+// Public API of the subscription-stripe bundled feature.
 //
-// **Internal-only** (NICHT im public-barrel — App-Builder nutzt das nie direkt):
-//   - StripeWebhookOptions / verifyAndParseStripeWebhook (intern vom
-//     feature.ts factory aufgerufen)
-//   - mapStripeEventType / mapStripeStatus (pure helpers, test-only;
-//     direct-import aus dem File wenn echt mal extern gebraucht)
+// **Internal-only** (not in the public barrel — the App Builder never uses it directly):
+//   - StripeWebhookOptions / verifyAndParseStripeWebhook (called internally by the
+//     feature.ts factory)
+//   - mapStripeEventType / mapStripeStatus (pure helpers, for tests only;
+//     import directly from the file only if truly needed externally)
 
 export {
   STRIPE_PROVIDER_NAME,

package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts

@@ -1,19 +1,19 @@
-// Stripe-Plugin-Methoden für die POST-tenant-resolution-Phase:
+// Stripe plugin methods for the POST-tenant-resolution phase:
 // createCheckoutSession, createPortalSession, cancelSubscription,
-// retrieveSubscription, retrievePrices, planSwitchSession.
+// retrieveSubscription, retrievePrices, and planSwitchSession.
 //
-// Werden vom Plugin-build (feature.ts) als methods auf dem
-// SubscriptionProviderPlugin registriert. Anders als
-// verifyAndParseWebhook (= pre-tenant) bekommen diese den vollen
-// HandlerContext — sie lösen den Stripe-Client zur CALL-Zeit aus dem
-// runtime auf (api-key aus system-secrets, audited), statt aus einem
-// mount-time-Closure. Key-Rotation wirkt damit ohne Redeploy.
+// The plugin build (`feature.ts`) registers these as methods on
+// `SubscriptionProviderPlugin`. Unlike verifyAndParseWebhook (= pre-tenant),
+// they receive the full HandlerContext and resolve the Stripe client from
+// the runtime at call time (using the audited api-key from system-secrets),
+// rather than from a mount-time closure. Key rotation therefore works
+// without a redeploy.
 //
-// **Type-Ableitung:** die options-shapes der methods werden
-// **direkt vom Plugin-Contract** abgeleitet (`Parameters<NonNullable
-// <SubscriptionProviderPlugin["...method"]>>[1]`). Wenn Foundation den
-// Contract erweitert (z.B. neuer optionaler Field), bemerkt der
-// Stripe-Plugin das beim TS-Compile, nicht erst zur Laufzeit.
+// **Type derivation:** method option shapes are derived **directly from the
+// plugin contract** (`Parameters<NonNullable
+// <SubscriptionProviderPlugin["...method"]>>[1]`). If Foundation extends the
+// contract (for example, with a new optional field), the Stripe plugin detects
+// it at TypeScript compile time rather than at runtime.
 
 import { createHash } from "node:crypto";
 import {
@@ -30,15 +30,10 @@ import Stripe from "stripe";
 import type { StripeCtxRuntime } from "./runtime.ts";
 import { isResourceMissingStripeError, mapStripeSubscriptionState } from "./verify-webhook.ts";
 
-// =============================================================================
-// createCheckoutSession
-// =============================================================================
-//
-// Stripe-Checkout-Session erstellen. Der hosted-page-URL wird returnt;
-// der App-Builder redirected den Tenant-Admin dorthin. Nach erfolgreichem
-// checkout sendet Stripe `customer.subscription.created` mit
-// `metadata.tenantId` zurück — das ist wie der subsequent webhook den
-// Tenant resolved.
+// Create a Stripe Checkout Session and return its hosted-page URL for the
+// app builder to redirect the tenant admin. After checkout, Stripe sends
+// `customer.subscription.created` with `metadata.tenantId`; the subsequent
+// webhook uses it to resolve the tenant.
 
 export type StripeCheckoutOptions = Parameters<
   NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>
@@ -120,11 +115,11 @@ export function createStripeCheckoutSession(
   { paymentInvoiceCreation = true }: StripeCheckoutSessionRuntimeOptions = {},
 ) {
   return async (ctx: HandlerContext, options: StripeCheckoutOptions): Promise<{ url: string }> => {
-    // #104-Invariante: ohne billing-live darf keine Stripe-Session
-    // entstehen (sk_test_-Keys in prod erzeugen sonst einen Test-Mode-
-    // Checkout). Throw VOR jedem Stripe-Call. Früher hielt diese Schranke
-    // das ungemountete Plugin; jetzt mountet stripe immer, also gatet der
-    // billing-live-config-key write-side.
+    // Invariant: without billing-live, no Stripe session may be created
+    // (sk_test_-keys in production would otherwise create a test-mode checkout).
+    // Throw before every Stripe call. The guard used to be provided by the
+    // unmounted plugin; Stripe is now always mounted, so the
+    // billing-live-config-key gates the write side.
     await runtime.assertBillingLive(ctx);
     const stripe = await runtime.clientForCtx(ctx);
     const mode = options.mode ?? "subscription";

package/packages/bundled-features/src/subscription-stripe/runtime.ts

@@ -49,7 +49,7 @@ export function createStripeClientCache(): (apiKey: string) => Stripe {
     const cached = cache.get(apiKey);
     if (cached) return cached;
     // No apiVersion pin — a string literal breaks consumers' typecheck on newer
-    // stripe SDKs (#256); the SDK's own default keeps wire-version and types aligned.
+    // stripe SDKs; the SDK's own default keeps wire-version and types aligned.
     const client = new Stripe(apiKey);
     cache.set(apiKey, client);
     return client;
@@ -83,7 +83,7 @@ function parseStoredSecret(raw: string | undefined): string | undefined {
 export type StripeCtxRuntime = {
   readonly clientForCtx: (ctx: HandlerContext) => Promise<Stripe>;
   /** Throws FeatureDisabledError unless `billing-live` config is true. The
-   *  #104 invariant: no Stripe session may be created while billing is not
+   *  invariant: no Stripe session may be created while billing is not
    *  live (sk_test_ keys in prod must not produce a live checkout).
    *  `handlerName` names the write-handler in the thrown error — defaults to
    *  "create-checkout-session" for existing callers, but plan-switch/portal