@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.387.0

package/dist/subscription-stripe/feature.js

@@ -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 { access, createSystemConfig, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
 import { featureWithEnvSchema } from "@cosmicdrift/kumiko-framework/env";
 import * as z from "zod";
@@ -92,11 +93,11 @@ function validateOneOffPriceIds(priceIds) {
     }
 }
 /**
- * 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 = {}) {
     validateOneOffPriceIds(options.oneOffPriceIds ?? []);
@@ -118,15 +119,15 @@ export function createSubscriptionStripeFeature(options = {}) {
         // 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/dist/subscription-stripe/index.js

@@ -1,9 +1,9 @@
-// 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, StripeEventTypes, SUBSCRIPTION_STRIPE_FEATURE, } from "./constants.js";
 export { createSubscriptionStripeFeature, stripeEnvSchema, subscriptionStripeEnvSchema, } from "./feature.js";

package/dist/subscription-stripe/plugin-methods.js

@@ -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 { KNOWN_RECURRING_INTERVALS, SubscriptionCancelTimings, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { ConflictError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
@@ -79,11 +79,11 @@ function isUnknownCustomerStripeError(error) {
 }
 export function createStripeCheckoutSession(runtime, { paymentInvoiceCreation = true } = {}) {
     return async (ctx, options) => {
-        // #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/dist/subscription-stripe/runtime.d.ts

@@ -19,7 +19,7 @@ export type StripeRuntimeDeps = {
 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

package/dist/subscription-stripe/runtime.js

@@ -41,7 +41,7 @@ export function createStripeClientCache() {
         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;

package/dist/subscription-stripe/verify-webhook.d.ts

@@ -5,17 +5,17 @@ import Stripe from "stripe";
 import type { StripeWebhookRuntime } from "./runtime.ts";
 export declare function isResourceMissingStripeError(error: unknown): error is Stripe.errors.StripeInvalidRequestError;
 export type StripeWebhookOptions = {
-    /** Price-to-tier-Map. Plugin liest die price-id aus dem event und
-     *  mapped auf tier-name. Fehlt die price-id im Mapping → null. App-
-     *  spezifisch, bleibt eine factory-option (kein Secret). */
+    /** Price-to-tier map. The plugin reads the price ID from the event and
+     *  maps it to a tier name. Returns null when the price ID is not mapped.
+     *  App-specific and remains a factory option, not a secret. */
     readonly priceToTier: Readonly<Record<string, string>>;
 };
 /**
- * Stripe-webhook-handler. Implementiert den Plugin-Contract
- * `verifyAndParseWebhook`. **Pre-tenant-resolution** — kein
- * HandlerContext; statt eines mount-time-Clients löst der `runtime` den
- * Stripe-Client + das webhook-secret zur Call-Zeit aus dem optionalen
- * system-SecretsContext (3. Arg) auf.
+ * Stripe webhook handler implementing the plugin contract
+ * `verifyAndParseWebhook`. **Pre-tenant resolution** — there is no
+ * HandlerContext; instead of using a mount-time client, `runtime` resolves
+ * the Stripe client and webhook secret at call time from the optional
+ * system SecretsContext (third argument).
  */
 export declare function verifyAndParseStripeWebhook(runtime: StripeWebhookRuntime, options: StripeWebhookOptions): (rawBody: string, headers: Record<string, string>, systemSecrets?: SecretsContext) => Promise<SubscriptionEvent | PaymentEvent | null>;
 export type MappedStripeSubscriptionState = {
@@ -37,7 +37,7 @@ export declare function mapStripeSubscriptionState(sub: Pick<Stripe.Subscription
 export declare function stripeCancelAtIso(sub: Pick<Stripe.Subscription, "cancel_at" | "cancel_at_period_end">, currentPeriodEndIso: string): string | null;
 /** Stripe-event-type → normalisiert. null = ignore. */
 export declare function mapStripeEventType(stripeType: string): SubscriptionEventType | null;
-/** Stripe-status → normalisiert. Defensive: unbekannte Status →
- *  incomplete (Plugin sollte das nicht erreichen, aber wir wollen
- *  kein ungültiger status-string in der DB). */
+/** Maps Stripe statuses to normalized statuses. Unknown statuses are
+ *  mapped defensively to incomplete; the plugin should not receive them, but
+ *  an invalid status string must not be stored in the database. */
 export declare function mapStripeStatus(stripeStatus: Stripe.Subscription.Status): SubscriptionStatus;

package/dist/subscription-stripe/verify-webhook.js

@@ -1,35 +1,34 @@
-// verifyAndParseStripeWebhook — Stripe-spezifische sig-verify +
-// event-mapping. Wird vom Plugin-Build (feature.ts) als
-// `verifyAndParseWebhook` registriert.
+// verifyAndParseStripeWebhook — Stripe-specific signature verification +
+// event mapping. Registered by the plugin build (feature.ts) as
+// `verifyAndParseWebhook`.
 //
 // **Steps:**
-//   1. Sig-verify via stripe.webhooks.constructEvent (HMAC-SHA-256
-//      gegen rawBody + Stripe-Signature-Header). Wirft bei mismatch
-//      oder älter als 5min (Replay-Protection).
+//   1. Verify the signature via stripe.webhooks.constructEvent (HMAC-SHA-256
+//      against rawBody + Stripe-Signature header). Throws on mismatch or
+//      timestamps older than 5 minutes (replay protection).
 //   1b. checkout.session.completed / .async_payment_succeeded branch off
 //       here into a PaymentEvent (one-off-payment, own aggregate) — see
-//       "One-off-payment" section below. Everything else falls through.
-//   2. Event-type-Filter: nur die 5 event-types die wir auf
-//      SubscriptionEventTypes mappen kommen weiter; alles andere
-//      returnt null (foundation antwortet 200 ignored).
-//   3. Stripe-payload → SubscriptionEvent normalisieren
-//      (status-mapping, tenant-id aus metadata, price-to-tier-Lookup).
+//       the "One-off-payment" section below. Everything else falls through.
+//   2. Event-type filter: only the 5 event types mapped to
+//      SubscriptionEventTypes continue; everything else returns null
+//      (the foundation responds with 200 ignored).
+//   3. Normalize the Stripe payload into a SubscriptionEvent
+//      (status mapping, tenant ID from metadata, price-to-tier lookup).
 //
-// **Runtime-keys (pre-tenant):** api-key + webhook-secret kommen NICHT
-// mehr aus einem mount-time-Closure, sondern werden zur Webhook-Zeit aus
-// dem `StripeWebhookRuntime` aufgelöst. Der foundation-webhook-handler
-// reicht einen system-scoped SecretsContext als 3. Arg durch; der runtime
-// liest beide Keys daraus (un-audited, system-internal) mit Fallback auf
-// die factory-options. Damit rotiert ein Key ohne Redeploy — und der
-// invoice-lazy-fetch (unten) nutzt denselben rotierten Client wie der
-// sig-verify, kein split-brain.
+// **Runtime keys (pre-tenant):** the API key and webhook secret no longer
+// come from a mount-time closure; they are resolved from `StripeWebhookRuntime`
+// at webhook time. The foundation webhook handler passes a system-scoped
+// SecretsContext as the third argument; the runtime reads both keys from it
+// (unaudited, system-internal), falling back to the factory options. This
+// allows key rotation without a redeploy, and the invoice lazy-fetch below
+// uses the same rotated client as signature verification, avoiding split-brain.
 //
 // **Invoice-event lazy-fetch:**
-// Invoice payloads carry only the subscription id (Stripe does not expand
-// subscription in webhooks), so the plugin lazy-fetches via
+// Invoice payloads carry only the subscription ID (Stripe does not expand
+// subscriptions in webhooks), so the plugin lazy-fetches via
 // `stripe.subscriptions.retrieve(subId)` to get the full subscription for
 // status/tier/period-end mapping. resource_missing (deleted between webhook
-// and retrieve) returns null; any other Stripe error becomes 503 so Stripe
+// and retrieval) returns null; any other Stripe error becomes 503 so Stripe
 // redelivers.
 import { BillingEventKinds, parseProviderConsentId, SubscriptionEventTypes, SubscriptionStatuses, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { ExtraRouteRejection } from "@cosmicdrift/kumiko-framework/api";
@@ -47,11 +46,11 @@ function transientProviderRejection(error) {
     return new ExtraRouteRejection(503, { error: { code: "subscription_provider_transient" } }, `stripe retrieve failed: ${error instanceof Error ? error.message : String(error)}`);
 }
 /**
- * Stripe-webhook-handler. Implementiert den Plugin-Contract
- * `verifyAndParseWebhook`. **Pre-tenant-resolution** — kein
- * HandlerContext; statt eines mount-time-Clients löst der `runtime` den
- * Stripe-Client + das webhook-secret zur Call-Zeit aus dem optionalen
- * system-SecretsContext (3. Arg) auf.
+ * Stripe webhook handler implementing the plugin contract
+ * `verifyAndParseWebhook`. **Pre-tenant resolution** — there is no
+ * HandlerContext; instead of using a mount-time client, `runtime` resolves
+ * the Stripe client and webhook secret at call time from the optional
+ * system SecretsContext (third argument).
  */
 export function verifyAndParseStripeWebhook(runtime, options) {
     return async (rawBody, headers, systemSecrets) => {
@@ -59,15 +58,15 @@ export function verifyAndParseStripeWebhook(runtime, options) {
         if (!sigHeader) {
             throw new Error("subscription-stripe: stripe-signature header missing");
         }
-        // 0. Runtime-resolve: api-key (für client + lazy-fetch) + webhook-
-        //    secret (für sig-verify) aus system-secrets, Fallback factory-
-        //    options. Wirft wenn beide unkonfiguriert.
+        // 0. Resolve at runtime: obtain the API key (for the client and lazy fetch)
+        //    and webhook secret (for signature verification) from system secrets,
+        //    falling back to the factory options. Throws if neither is configured.
         const { stripe, webhookSecret } = await runtime.resolve(systemSecrets);
-        // 1. Sig-verify. constructEvent throws bei mismatch (= invalid sig)
-        //    oder timestamp-tolerance-violation (default 5min). Foundation
-        //    mapped throw → HTTP 401. Applies to BOTH branches below — the
-        //    payment-branch only branches off AFTER this check; there's no
-        //    path that bypasses signature verification.
+        // 1. Verify the signature. constructEvent throws on a mismatch (invalid
+        //    signature) or timestamp-tolerance violation (default: 5 minutes).
+        //    The foundation maps the thrown error to HTTP 401. This applies to
+        //    BOTH branches below: the payment branch is selected only AFTER this
+        //    check, so no path bypasses signature verification.
         let event;
         try {
             event = await stripe.webhooks.constructEventAsync(rawBody, sigHeader, webhookSecret);
@@ -84,28 +83,27 @@ export function verifyAndParseStripeWebhook(runtime, options) {
         if (isCheckoutSessionEventType(event.type)) {
             return await parsePaymentEvent(event, stripe);
         }
-        // 2. Event-type-Filter — wir kennen nur 5.
+        // 2. Event-type filter — only 5 event types are supported.
         const normalizedType = mapStripeEventType(event.type);
         if (!normalizedType) {
             return null; // foundation returnt 200 ignored
         }
-        // 3. Payload-extraction. Stripe liefert je nach event.type
-        //    verschiedene data.object-shapes. Wir extrahieren die
-        //    Subscription-Daten — entweder direkt (subscription-events)
-        //    oder via lazy-fetch (invoice-events).
+        // 3. Extract the payload. Stripe uses different data.object shapes
+        //    depending on event.type. Extract subscription data either directly
+        //    (subscription events) or through a lazy fetch (invoice events).
         const sub = await extractSubscriptionFromEvent(event, stripe);
         if (!sub) {
-            // event-type war unter den 5 (oben gefiltert), aber payload-shape
-            // matched nicht — Stripe-SDK-Schema-Drift, defensive null.
+            // The event type passed the 5-item filter, but its payload shape did not
+            // match — treat this as Stripe SDK schema drift and return null defensively.
             return null;
         }
-        // 4. Tenant-resolution aus metadata. App-Builder setzt
-        //    `metadata.tenantId` beim createCheckoutSession-call.
+        // 4. Resolve the tenant from metadata. The app builder sets
+        //    `metadata.tenantId` when calling createCheckoutSession.
         const tenantId = sub.metadata?.["tenantId"];
         if (!tenantId || tenantId.length === 0) {
-            // Subscription ohne tenant-metadata → kann kein subscription
-            // erstellen ohne tenant-resolution. Drop the event silent
-            // (foundation 200 ignored). App-Owner-Bug, nicht foundation-Bug.
+            // A subscription without tenant metadata cannot be created without tenant
+            // resolution. Drop the event silently (the foundation responds with 200
+            // ignored). This is an app-owner error, not a foundation error.
             return null;
         }
         // 5+6. Price-to-tier-Mapping + status/period-end/cancel_at — shared with
@@ -151,7 +149,7 @@ export function mapStripeSubscriptionState(sub, priceToTier) {
     const periodEndUnixSec = sub.items.data[0]?.current_period_end ?? 0;
     // Stripe returns Unix-seconds; Temporal.Instant.fromEpochMilliseconds
     // expects ms. Multiply, then ISO. (No-Date-API-Guard forbids
-    // `new Date()` — static import above, not the ambient global, see #1490.)
+    // `new Date()` — static import above, not the ambient global.)
     const currentPeriodEnd = Temporal.Instant.fromEpochMilliseconds(periodEndUnixSec * 1000).toString();
     const cancelAt = stripeCancelAtIso(sub, currentPeriodEnd);
     return { status, tier, currentPeriodEnd, cancelAt };
@@ -187,9 +185,9 @@ export function mapStripeEventType(stripeType) {
             return null;
     }
 }
-/** Stripe-status → normalisiert. Defensive: unbekannte Status →
- *  incomplete (Plugin sollte das nicht erreichen, aber wir wollen
- *  kein ungültiger status-string in der DB). */
+/** Maps Stripe statuses to normalized statuses. Unknown statuses are
+ *  mapped defensively to incomplete; the plugin should not receive them, but
+ *  an invalid status string must not be stored in the database. */
 export function mapStripeStatus(stripeStatus) {
     switch (stripeStatus) {
         case "active":
@@ -215,9 +213,9 @@ export function mapStripeStatus(stripeStatus) {
             return SubscriptionStatuses.incomplete;
     }
 }
-/** Holt die Subscription aus dem Event. Subscription-events haben sie
- *  direkt im data.object; invoice-events haben nur die subscription-id
- *  und brauchen einen lazy-fetch via stripe.subscriptions.retrieve. */
+/** Gets the subscription from the event. Subscription events include it
+ *  directly in data.object; invoice events include only the subscription ID
+ *  and require a lazy fetch via stripe.subscriptions.retrieve. */
 // @wrapper-known semantic-alias
 async function extractSubscriptionFromEvent(event, stripe) {
     switch (event.type) {
@@ -227,16 +225,16 @@ async function extractSubscriptionFromEvent(event, stripe) {
             return event.data.object; // @cast-boundary engine-bridge
         case StripeEventTypes.invoicePaid:
         case StripeEventTypes.invoicePaymentFailed: {
-            // Lazy-fetch der subscription. invoice.subscription ist eine
-            // string-id (Stripe-Webhooks expanden nicht auto). Wir holen das
-            // full subscription-Object damit der downstream-mapping
-            // (status, tier via priceId, period-end) konsistent funktioniert.
+            // Lazy-fetch the subscription. invoice.subscription is a string ID because
+            // Stripe webhooks do not expand it automatically. Fetch the full
+            // subscription so downstream status, tier via priceId, and period-end
+            // mapping remain consistent.
             const invoice = event.data.object; // @cast-boundary engine-bridge
             const subRef = invoice // @cast-boundary engine-payload
                 .subscription;
             if (!subRef) {
-                // Invoice ohne subscription-reference (= one-shot-invoice, nicht
-                // recurring). Nicht unsere Domain — ignorieren.
+                // An invoice without a subscription reference is a one-shot invoice, not a
+                // recurring invoice. It is outside this domain and should be ignored.
                 return null;
             }
             const subId = typeof subRef === "string" ? subRef : subRef.id;

package/dist/tags/feature.d.ts

@@ -21,9 +21,9 @@ export type TagsFeatureOptions = {
     /** Row-level ownership on the tag-assignment rows themselves — orthogonal to
      *  `access`, which only gates whether a caller may dispatch assign/remove/list
      *  at all. `ownership.read` is no longer what keeps a caller from reading
-     *  assignments on host entities they can't see: that gate is default-on since
-     *  fw#2766 and derives from the entity's `parentRef`. Use `ownership.read` for
-     *  an ADDITIONAL row rule on the assignment row itself; it is AND-ed with the
+     *  assignments on host entities they can't see: that gate is default-on and
+     *  derives from the entity's `parentRef`. Use `ownership.read` for an
+     *  ADDITIONAL row rule on the assignment row itself; it is AND-ed with the
      *  host-visibility gate, never a replacement for it. Applies only to
      *  `tag-assignment`; the `tag` catalog stays tenant-wide by design.
      *

package/dist/tags/screens.js

@@ -1,6 +1,6 @@
 import { i18nKey, } from "@cosmicdrift/kumiko-framework/engine";
 import { DEFAULT_TAG_ACCESS, TAGS_EDIT_SCREEN_ID, TAGS_SCREEN_ID } from "./web/constants.js";
-// Declarative catalog screens (Phase-3 / #2312). Access matches create/update/
+// Declarative catalog screens. Access matches create/update/
 // delete so createTagsFeature({ access|roles }) stays consistent. TagManager
 // remains for TagPicker/TagSection — only the standalone admin screen moved.
 export function createTagListScreen(access = DEFAULT_TAG_ACCESS) {

package/dist/template-resolver/api.js

@@ -89,19 +89,19 @@ function pickActiveLayoutRow(rows, locale) {
 async function fetchTemplate(db, tenantId, slug, kind, locale) {
     const rows = await selectMany(db, templateResourcesTable, { tenantId, slug, kind, locale }, { limit: 1 });
     // @cast-boundary db-row — db.select returnt unbenanntes unknown[],
-    // Row-Shape ist via templateResourcesTable + buildBaseColumns garantiert.
+    // The row shape is guaranteed by templateResourcesTable + buildBaseColumns.
     return rows[0] ?? null;
 }
 function toPublic(row) {
     // @cast-boundary db-row — Drizzle-Schema typisiert kind/contentFormat/
-    // scope/status als generic text. CHECK-Constraints in der DB schränken
-    // sie auf die Union-Types ein; Cast assertet das Schema-Wissen.
+    // scope/status as generic text. Database CHECK constraints restrict
+    // them to the union types; the cast asserts that schema knowledge.
     const kind = row.kind;
-    // @cast-boundary db-row — siehe kind.
+    // @cast-boundary db-row — see kind.
     const contentFormat = row.contentFormat;
-    // @cast-boundary db-row — siehe kind.
+    // @cast-boundary db-row — see kind.
     const scope = row.scope;
-    // @cast-boundary db-row — siehe kind.
+    // @cast-boundary db-row — see kind.
     const status = row.status;
     const linkedEntries = parseLinkedResourceEntries(row.linkedResources);
     return {
@@ -143,7 +143,7 @@ function parseJson(raw) {
     try {
         const parsed = JSON.parse(raw);
         // @cast-boundary engine-payload — JSON.parse returnt unknown, typeof-Guard
-        // grenzt auf object ein; Record<string, unknown> ist der minimale common-shape.
+        // narrows it to object; Record<string, unknown> is the minimal common shape.
         return typeof parsed === "object" && parsed !== null ? parsed : {};
     }
     catch {
@@ -158,11 +158,11 @@ export class TemplateNotFoundError extends Error {
         this.name = "TemplateNotFoundError";
     }
 }
-// Single point of truth für "dieser Handler braucht template-resolver".
-// Pattern symmetrisch zu requireTextContent.
+// Single source of truth for "this handler requires template-resolver".
+// Pattern symmetric with requireTextContent.
 export function requireTemplateResolver(ctx, callerName) {
     // @cast-boundary engine-bridge — templateResolver kommt per extraContext
-    // aus App-Bootstrap, Framework-Container kennt das Feld nicht von sich aus.
+    // from App-Bootstrap; the framework container does not know this field on its own.
     const api = ctx.templateResolver;
     if (!api) {
         throw new InternalError({

package/dist/template-resolver/handlers/find-by-id.query.js

@@ -5,11 +5,11 @@ import { templateResourcesTable } from "../table.js";
 import { deliveryPolicyOf, isRowServedTo } from "../template-delivery-policy.js";
 import { draftViewerTenantId, isHiddenSystemDraft, toWorkingRow } from "../template-draft.js";
 import { isSystemOnlyTemplateHiddenFrom } from "../template-system-only.js";
-// Admin-Lookup für UI-Edit-Flow. Returnt das raw Template inkl. draft/
-// archived Status. Tenant-Isolation: User sieht nur Templates des
-// eigenen Tenants oder SYSTEM_TENANT (system-defaults sind public-
-// readable); ctx.db is tenant-scoped for every role, so the check below is defense in depth. Anonymous bleibt aus — Public-
-// Read geht über resolveTemplate aus der API, nicht hier.
+// Admin lookup for the UI editing flow. Returns the raw template, including draft/
+// archived status. Tenant isolation: users see only templates belonging to their own
+// tenant or SYSTEM_TENANT (system defaults are publicly readable); ctx.db is tenant-
+// scoped for every role, so the check below is defense in depth. Anonymous access is
+// excluded—public reads go through resolveTemplate in the API, not here.
 export const findByIdQuery = defineQueryHandler({
     name: "find-by-id",
     schema: z.object({ id: z.string().min(1) }),

package/dist/template-resolver/handlers/list.query.js

@@ -35,7 +35,7 @@ export const listQuery = defineQueryHandler({
         if (query.payload.status) {
             where["status"] = query.payload.status;
         }
-        // @cast-boundary db-row — selectMany returnt unknown[]; Row-Shape ist
+        // @cast-boundary db-row — selectMany returns unknown[]; Row shape is
         // durch templateResourcesTable + buildBaseColumns garantiert.
         const rows = (await selectMany(ctx.db, templateResourcesTable, where, {
             limit: 500,

package/dist/template-resolver/handlers/shared.js

@@ -30,8 +30,8 @@ export const folderSchema = z
 export const titleSchema = z.string().min(1).max(200);
 export const contentFormatSchema = z.enum(CONTENT_FORMATS);
 export const statusSchema = z.enum(TEMPLATE_STATUSES);
-// Common Upsert-Payload — geteilt zwischen upsertSystem + upsertTenant.
-// Unterschied: ACL + tenantId-Bestimmung, sonst identisch.
+// Common upsert payload shared by upsertSystem and upsertTenant.
+// Only ACL and tenantId determination differ.
 export const upsertPayloadSchema = z.object({
     slug: templateSlugSchema,
     kind: kindSchema,

package/dist/template-resolver/handlers/template-write.js

@@ -148,9 +148,9 @@ export async function writeTemplateRow(args) {
     }, user, db, { streamTenantId });
     if (!result.isSuccess)
         return result;
-    // @cast-boundary db-row — executor.create returnt Record-row aus
-    // INSERT RETURNING; shape { id } ist garantiert weil PK in der
-    // Returning-Klausel ist.
+    // @cast-boundary db-row — executor.create returns a row from
+    // INSERT RETURNING; the { id } shape is guaranteed because the primary key is in the
+    // RETURNING clause.
     const createdRow = result.data;
     return {
         isSuccess: true,

package/dist/template-resolver/handlers/upsert-system.write.js

@@ -2,10 +2,9 @@ import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framew
 import { resolveTemplateVariables } from "../template-validation.js";
 import { upsertPayloadSchema } from "./shared.js";
 import { writeTemplateRow } from "./template-write.js";
-// System-Template anlegen/updaten. Liegt unter SYSTEM_TENANT_ID,
-// scope='system'. Nur SystemAdmin (globale Rolle). TenantAdmin kann
-// keine System-Defaults überschreiben — der nutzt upsertTenant für
-// Overrides.
+// Creates or updates a system template under SYSTEM_TENANT_ID with
+// scope='system'. Only SystemAdmin can change these global defaults;
+// TenantAdmin uses upsertTenant for overrides instead.
 export const upsertSystemWrite = defineWriteHandler({
     name: "upsert-system",
     schema: upsertPayloadSchema,

package/dist/template-resolver/handlers/upsert-tenant.write.js

@@ -4,11 +4,10 @@ import { refuseTemplateEdit, templateEditAccess, } from "../template-edit-policy
 import { resolveTemplateVariables } from "../template-validation.js";
 import { upsertPayloadSchema } from "./shared.js";
 import { writeTemplateRow } from "./template-write.js";
-// Tenant-Override anlegen/updaten. Liegt unter event.user.tenantId,
-// scope='tenant'. Default-Status='draft' — User publisht explizit
-// via publish-Handler. SystemAdmin kann via tenantIdOverride für
-// einen anderen Tenant schreiben (typisch: Plattform-Admin-UI das
-// Tenant-Templates kuratiert).
+// Creates or updates a tenant override under event.user.tenantId with scope='tenant'.
+// The default status is 'draft'; users must publish explicitly via the publish handler.
+// SystemAdmin can write for another tenant through tenantIdOverride, typically to
+// curate tenant templates from a platform admin UI.
 export function makeUpsertTenantWrite(policy) {
     return defineWriteHandler({
         name: "upsert-tenant",