@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/billing-foundation/subscription-tier-sync.js

@@ -0,0 +1,119 @@
+// Generic Stripe/PayPal-webhook → tier-engine sync route. Extracted from the
+// near-identical webhook-route.ts app copies in show-pony and publicstatus
+// (infra#446) — the only per-app variables were the TierName union/default,
+// so it is now a factory parameter.
+import { TierEngineHandlers, TierEngineQueries, tierAssignmentAggregateId, } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
+import { subscriptionAggregateId } from "./aggregate-id.js";
+import { SubscriptionFoundationQueries, SubscriptionStatuses } from "./constants.js";
+import { createSubscriptionWebhookRoute } from "./webhook-handler.js";
+// Outside /api — signature routes carry their own auth (verify()) and are
+// not JWT-guarded, so provider dashboards (Stripe, PayPal, ...) point here.
+export const SUBSCRIPTION_WEBHOOK_PATH = "/webhooks/subscription/:providerName";
+export function effectiveTierFromSubscription(status, tier, isTierName, defaultTier) {
+    const usable = status === SubscriptionStatuses.active || status === SubscriptionStatuses.trialing;
+    return usable && typeof tier === "string" && isTierName(tier) ? tier : defaultTier;
+}
+// Narrows an unknown dispatchSystemQuery result to its `{ rows }` list
+// shape without an unchecked cast — a query returning something else
+// (handler bug, or the handlerQn resolving to a non-list query) fails
+// loudly instead of crashing on `.find` against `undefined`.
+function asRows(result) {
+    if (typeof result === "object" &&
+        result !== null &&
+        Array.isArray(result.rows)) {
+        return result.rows;
+    }
+    throw new Error("expected a { rows: [...] } list-query result");
+}
+export function createSubscriptionTierSync(deps) {
+    async function syncTierFromSubscription(tenantId, routeDeps) {
+        try {
+            const subscriptionId = subscriptionAggregateId(tenantId);
+            const subscriptionRows = asRows(await routeDeps.dispatchSystemQuery({
+                handlerQn: SubscriptionFoundationQueries.listSubscriptions,
+                payload: {},
+                tenantId,
+            }));
+            const sub = subscriptionRows.find((row) => row["id"] === subscriptionId);
+            if (!sub)
+                return null;
+            const effective = effectiveTierFromSubscription(typeof sub["status"] === "string" ? sub["status"] : undefined, typeof sub["tier"] === "string" ? sub["tier"] : undefined, deps.isTierName, deps.defaultTier);
+            const tierAssignmentRows = asRows(await routeDeps.dispatchSystemQuery({
+                handlerQn: TierEngineQueries.list,
+                payload: {},
+                tenantId,
+            }));
+            const assignment = tierAssignmentRows.find((row) => row["tenantId"] === tenantId);
+            if (!assignment ||
+                typeof assignment["id"] !== "string" ||
+                typeof assignment["version"] !== "number") {
+                const created = await routeDeps.dispatchSystemWrite({
+                    handlerQn: TierEngineHandlers.create,
+                    payload: { id: tierAssignmentAggregateId(tenantId), tier: effective },
+                    tenantId,
+                });
+                if (!created.isSuccess) {
+                    return {
+                        code: "tier_sync_failed",
+                        message: `tier-engine create with "${effective}" failed: ${created.error?.code ?? "unknown"}`,
+                    };
+                }
+                return null;
+            }
+            if (assignment["tier"] === effective)
+                return null;
+            const result = await routeDeps.dispatchSystemWrite({
+                handlerQn: TierEngineHandlers.update,
+                payload: {
+                    id: assignment["id"],
+                    version: assignment["version"],
+                    changes: { tier: effective },
+                },
+                tenantId,
+            });
+            if (!result.isSuccess) {
+                return {
+                    code: "tier_sync_failed",
+                    message: `tier-engine update to "${effective}" failed: ${result.error?.code ?? "unknown"}`,
+                };
+            }
+            return null;
+        }
+        catch (error) {
+            // dispatchSystemQuery throws (AccessDenied/NotFound/Validation) rather
+            // than returning an error envelope — e.g. a consumer that mounts
+            // billing-foundation without tier-engine. Surface it the same way as
+            // a failed dispatchSystemWrite instead of letting it bubble into the
+            // webhook response as an unhandled 500.
+            return {
+                code: "tier_sync_failed",
+                message: error instanceof Error ? error.message : "tier sync threw a non-Error value",
+            };
+        }
+    }
+    function createWebhookRoute() {
+        return createSubscriptionWebhookRoute({
+            path: SUBSCRIPTION_WEBHOOK_PATH,
+            afterDispatch: async (dispatched, tenantId, routeDeps) => {
+                const syncError = await syncTierFromSubscription(tenantId, routeDeps);
+                if (syncError) {
+                    // biome-ignore lint/suspicious/noConsole: operator visibility for a post-commit sync failure
+                    console.warn(`[subscription-tier-sync] tier sync failed for tenant ${tenantId} after successful webhook write: ${syncError.code} ${syncError.message}`);
+                    if (deps.onSyncError === "fail-webhook") {
+                        return {
+                            isSuccess: false,
+                            error: {
+                                code: syncError.code,
+                                httpStatus: 500,
+                                i18nKey: "errors.subscriptionTierSyncFailed",
+                                message: syncError.message,
+                            },
+                        };
+                    }
+                }
+                return dispatched;
+            },
+        });
+    }
+    return { createWebhookRoute };
+}

package/dist/billing-foundation/tenant-destroy-hook.d.ts

@@ -0,0 +1,14 @@
+import { type TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
+export declare const SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON = "tenant-destroy looks up the compliance profile and archives the subscription event-stream before the projection row is redacted/deleted";
+export declare const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON = "tenant-destroy looks up the compliance profile and archives the payment event-stream before the projection rows are redacted/deleted";
+/** Tenant-destroy hook for billing PII (#800). HGB retains the accounting
+ *  row but redacts the two provider-subject PII fields; other profiles
+ *  hard-delete the row. Either way the subscription stream is archived so a
+ *  future projection rebuild can't resurrect what was erased. */
+export declare function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void>;
+/** Tenant-destroy hook for payment PII (#800). Unlike subscriptionTenantDestroyHook
+ *  (one row per tenant, targeted by `id`), a tenant can have many payment
+ *  rows — the predicate here is `tenantId`, not `id`. The payment-stream
+ *  itself is still one stream per tenant (paymentAggregateId), so
+ *  archiveStream targets that single aggregateId as usual. */
+export declare function paymentTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void>;

package/dist/billing-foundation/tenant-destroy-hook.js

@@ -0,0 +1,68 @@
+import { declareEscapeHatch } from "@cosmicdrift/kumiko-framework/engine";
+import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
+import { resolveProfileForTenant } from "../compliance-profiles/index.js";
+import { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id.js";
+import { PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE } from "./events.js";
+import { paymentsProjectionTable, subscriptionsProjectionTable } from "./projection.js";
+// providerCustomerId/providerSubscriptionId are `personal: "tenant"` on the
+// entity (envelope-encrypted with the tenant subject key, see entities.ts) —
+// eraseSubjectKeys crypto-shreds them for tenants that hard-delete. HGB
+// can not: it needs the accounting facts (status/tier/period) to survive, so
+// it redacts the projection row directly instead of relying on key erasure.
+const REDACTED_PII_VALUE = "[erased]";
+// Compliance-profile lookup and event-stream archive both sit outside TenantDb's own methods — need the escape hatch.
+export const SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON = "tenant-destroy looks up the compliance profile and archives the subscription event-stream before the projection row is redacted/deleted";
+export const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON = "tenant-destroy looks up the compliance profile and archives the payment event-stream before the projection rows are redacted/deleted";
+/** Tenant-destroy hook for billing PII (#800). HGB retains the accounting
+ *  row but redacts the two provider-subject PII fields; other profiles
+ *  hard-delete the row. Either way the subscription stream is archived so a
+ *  future projection rebuild can't resurrect what was erased. */
+export async function subscriptionTenantDestroyHook(ctx) {
+    declareEscapeHatch({ reason: SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON });
+    const { profile } = await resolveProfileForTenant({
+        db: ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON),
+        tenantId: ctx.tenantId,
+    });
+    const aggregateId = subscriptionAggregateId(ctx.tenantId);
+    if (profile.key === "de-hr-dsgvo-hgb") {
+        await ctx.db.updateMany(subscriptionsProjectionTable, { providerCustomerId: REDACTED_PII_VALUE, providerSubscriptionId: REDACTED_PII_VALUE }, { id: aggregateId });
+    }
+    else {
+        await ctx.db.deleteMany(subscriptionsProjectionTable, { id: aggregateId });
+    }
+    await archiveStream(ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON), {
+        tenantId: ctx.tenantId,
+        aggregateId,
+        aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
+        archivedBy: "tenant-lifecycle:destroy",
+        reason: "tenant_destroy",
+    });
+}
+/** Tenant-destroy hook for payment PII (#800). Unlike subscriptionTenantDestroyHook
+ *  (one row per tenant, targeted by `id`), a tenant can have many payment
+ *  rows — the predicate here is `tenantId`, not `id`. The payment-stream
+ *  itself is still one stream per tenant (paymentAggregateId), so
+ *  archiveStream targets that single aggregateId as usual. */
+export async function paymentTenantDestroyHook(ctx) {
+    declareEscapeHatch({ reason: PAYMENT_TENANT_DESTROY_ARCHIVE_REASON });
+    const { profile } = await resolveProfileForTenant({
+        db: ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON),
+        tenantId: ctx.tenantId,
+    });
+    const aggregateId = paymentAggregateId(ctx.tenantId);
+    if (profile.key === "de-hr-dsgvo-hgb") {
+        await ctx.db.updateMany(paymentsProjectionTable, { providerCustomerId: REDACTED_PII_VALUE }, { tenantId: ctx.tenantId });
+    }
+    else {
+        await ctx.db.deleteMany(paymentsProjectionTable, {
+            tenantId: ctx.tenantId,
+        });
+    }
+    await archiveStream(ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON), {
+        tenantId: ctx.tenantId,
+        aggregateId,
+        aggregateType: PAYMENT_AGGREGATE_TYPE,
+        archivedBy: "tenant-lifecycle:destroy",
+        reason: "tenant_destroy",
+    });
+}

package/dist/billing-foundation/types.d.ts

@@ -0,0 +1,325 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { type BillingEventKinds, type BillingPlanAction, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionEventType, type SubscriptionStatus } from "./constants.js";
+export type SubscriptionEvent = {
+    /** Discriminator against PaymentEvent. Optional (instead of required) so
+     *  existing plugins like subscription-mollie, which don't set this field,
+     *  stay backward-compatible without changes — TS still narrows
+     *  `parsed.kind === BillingEventKinds.payment` correctly, because only
+     *  PaymentEvent["kind"] can take that value. */
+    readonly kind?: typeof BillingEventKinds.subscription;
+    /** Provider-eigene Event-ID — UNIQUE-key für Idempotency.
+     *  Stripe: "evt_..."; Mollie: payment-id oder subscription-id. */
+    readonly providerEventId: string;
+    /** Discriminator — welcher Plugin diesen Event geliefert hat. */
+    readonly providerName: string;
+    /** Normalisierter Event-Type. Plugin filtert provider-spezifische
+     *  Sub-Types raus (Stripe hat ~80 Event-types, wir kennen 5). */
+    readonly type: SubscriptionEventType;
+    /** Plattform-Tenant-ID (provider-customer-metadata oder lookup
+     *  via providerCustomerId). Plugin macht die resolution. */
+    readonly tenantId: string;
+    /** Provider-eigene customer-id für späteren Lookup bei events
+     *  ohne metadata. */
+    readonly providerCustomerId: string;
+    /** Provider-eigene subscription-id. */
+    readonly providerSubscriptionId: string;
+    /** Normalisierter status. */
+    readonly status: SubscriptionStatus;
+    /** Resolved tier — Plugin liest die price-id aus dem event und
+     *  mapped via plugin-eigenem `<plugin>:config:price-to-tier` auf
+     *  einen tier-name. Wenn der price-id im Mapping fehlt, returnt
+     *  der Plugin null aus verifyAndParseWebhook (= "unknown event,
+     *  ignore"). */
+    readonly tier: string;
+    /** ISO-timestamp wann die aktuelle Billing-Period endet. */
+    readonly currentPeriodEnd: string;
+    /** ISO instant a scheduled cancellation ends the subscription. null =
+     *  it keeps renewing; undefined = the provider doesn't report it (e.g.
+     *  Mollie), so projection.ts leaves the column unchanged instead of
+     *  nulling it. */
+    readonly cancelAt?: string | null;
+    /** Raw provider-payload — wird 1:1 in subscription-event.rawPayload
+     *  archiviert. Plugin liefert das als JSON-stringified-string. */
+    readonly rawPayload: string;
+};
+export type PaymentEvent = {
+    /** Required — distinguishes this union member at runtime from
+     *  SubscriptionEvent (whose `kind` is optional and never "payment"). */
+    readonly kind: typeof BillingEventKinds.payment;
+    /** Provider's own event-ID — UNIQUE key for idempotency. */
+    readonly providerEventId: string;
+    /** Discriminator — which plugin delivered this event. */
+    readonly providerName: string;
+    /** Platform-tenant-ID. **Must** come from provider-verified metadata
+     *  (e.g. the PaymentIntent metadata the app itself set at checkout-
+     *  create time) — never from a freely-choosable payload field, or an
+     *  attacker could attribute payments to someone else's tenant. */
+    readonly tenantId: string;
+    /** Provider's own customer-id. */
+    readonly providerCustomerId: string;
+    /** Provider's own price/plan-ID of the purchased item. */
+    readonly priceId: string;
+    /** Raw provider-payload — archived 1:1 into payment-event.rawPayload.
+     *  Plugin delivers this as a JSON-stringified string. */
+    readonly rawPayload: string;
+};
+export type SubscriptionProviderPlugin = {
+    /**
+     * Verify webhook signature + parse provider-event into normalized
+     * form. **Pre-tenant-resolution** — no HandlerContext, because at
+     * sig-verify time the tenant hasn't been resolved yet (the plugin
+     * does the tenant-resolution itself from the provider-payload
+     * metadata).
+     *
+     * App-wide-secret = the App-Owner's own provider account. The plugin
+     * reads it either from a mount-time closure OR — rotatable at
+     * runtime — from the optional `systemSecrets` arg (system-scoped
+     * SecretsContext, passed through by the webhook-handler).
+     * `systemSecrets` is undefined when the App-Owner hasn't wired one;
+     * plugins then fall back to their closure fallback.
+     *
+     * Returns null for events the plugin doesn't understand or that the
+     * foundation doesn't need (= filter out, foundation returns 200
+     * "ignored").
+     *
+     * **Throws** on sig-mismatch — the webhook-handler maps that to 401
+     * so the provider doesn't retry (sig-fail = config-bug, not
+     * transient).
+     *
+     * Returns `PaymentEvent` for one-off-payment-webhooks (checkout mode
+     * "payment"). Plugins without one-off-payment support never deliver this
+     * union member — the return-type extension is covariant, so a
+     * `Promise<SubscriptionEvent | null>` implementor stays assignable
+     * without any change.
+     */
+    readonly verifyAndParseWebhook: (rawBody: string, headers: Record<string, string>, systemSecrets?: SecretsContext) => Promise<SubscriptionEvent | PaymentEvent | null>;
+    /**
+     * **Post-tenant-resolution** — wird aus dem
+     * `create-checkout-session`-write-handler gerufen. Plugin baut
+     * eine provider-eigene checkout-session und returnt die hosted-
+     * page-URL — Tenant-Admin wird dorthin redirected, schließt den
+     * Bezahl-Flow ab, Provider sendet `subscription.created`-webhook
+     * mit `metadata.tenantId` zurück.
+     *
+     * Optional: Apple-IAP hat keinen Web-Checkout (alles in der App).
+     * Apps die ausschließlich Apple-IAP nutzen lassen das weg.
+     */
+    readonly createCheckoutSession?: (ctx: HandlerContext, options: {
+        /** Provider-eigene price/plan-ID die der Endkunde abonniert. */
+        readonly priceId: string;
+        /** Plattform-Tenant-ID — landet als metadata im checkout-session
+         *  damit der subsequent webhook den tenant resolved (siehe
+         *  `verifyAndParseWebhook`'s metadata.tenantId-lookup). */
+        readonly tenantId: string;
+        /** Wo der Endkunde nach erfolgreichem checkout landed. */
+        readonly successUrl: string;
+        /** Wo der Endkunde landed wenn er abbricht. */
+        readonly cancelUrl: string;
+        /** Optional: existierende provider-customer-id wenn der Tenant
+         *  schon einen Account beim Provider hat. Sonst legt der Provider
+         *  beim checkout einen neuen customer an. */
+        readonly providerCustomerId?: string;
+        /** Checkout mode. `"subscription"` (default) starts a recurring
+         *  billing flow; `"payment"` a one-off checkout (e.g. pay-per-use
+         *  credit top-ups). Optional with default `"subscription"` — existing
+         *  callers are unaffected. */
+        readonly mode?: "subscription" | "payment";
+    }) => Promise<{
+        readonly url: string;
+    }>;
+    /**
+     * **Post-tenant-resolution** — wird aus einem write-handler gerufen
+     * mit voll-aufgelöstem ctx. Erstellt einen self-service Portal-Link.
+     * Stripe: customer-portal-session, Mollie: hosted-management-page.
+     * Tenant-Admin klickt darauf um Subscription selbst zu verwalten
+     * (cancel, payment-method, ...).
+     *
+     * Optional weil nicht jeder Provider einen Portal-Pattern hat
+     * (Apple-IAP managed Subs in der Apple-App, kein Web-Portal).
+     * Plugin der das nicht supported kann das Field weglassen — foundation
+     * returnt dann "portal_not_supported"-error wenn ein Tenant-Admin
+     * den Portal-Link anfordert.
+     */
+    readonly createPortalSession?: (ctx: HandlerContext, options: {
+        readonly providerCustomerId: string;
+        readonly returnUrl: string;
+    }) => Promise<{
+        readonly url: string;
+    }>;
+    /**
+     * Optional: Cancel-aus-der-App-API. Wenn nicht implementiert, kann
+     * der Tenant nur über den Customer-Portal-Link cancellen (oder gar
+     * nicht, wenn auch createPortalSession fehlt — dann ist
+     * Cancel-Flow Provider-Dashboard-only).
+     */
+    readonly cancelSubscription?: (ctx: HandlerContext, providerSubscriptionId: string) => Promise<void>;
+    /**
+     * The provider's own price/plan-id → app-tier-name mapping. This is the
+     * one source `checkout-core`/`plan-catalog` derive both hardening
+     * (unknown-priceId rejection) and the billing-plans catalog from — see
+     * `architektur/billing-price-to-tier-quelle`. Optional only for
+     * backward-compat with providers that predate this field (their
+     * `create-checkout-session` calls now reject every mode:"subscription"
+     * price as `provider_has_no_price_catalog` until they add it).
+     */
+    readonly priceToTier?: Readonly<Record<string, string>>;
+    /**
+     * Allowlist of the provider's own price/plan-ids that may be checked out
+     * with `mode: "payment"` (one-off top-ups etc.) — mirrors `priceToTier`'s
+     * role for `mode: "subscription"`. Missing or empty → every mode:"payment"
+     * checkout is rejected as `unknown_price`, since without a list there is
+     * no way to tell a legitimate one-off price from an arbitrary caller-
+     * supplied string.
+     */
+    readonly oneOffPriceIds?: readonly string[];
+    /**
+     * Whether the provider is ready to accept live checkouts right now
+     * (credentials configured, master-switch on, ...). Missing → foundation
+     * treats billing as enabled (no readiness gate to check).
+     */
+    readonly isBillingEnabled?: (ctx: HandlerContext) => Promise<boolean>;
+    /**
+     * Bulk price lookup for the billing-plans catalog. Missing → every plan's
+     * price stays null (catalog still renders, just without live prices).
+     * A priceId the provider can't load (deleted, wrong account, ...) is
+     * simply absent from the result — no throw per-price.
+     */
+    readonly retrievePrices?: (ctx: HandlerContext, priceIds: readonly string[]) => Promise<readonly ProviderPrice[]>;
+    /**
+     * Opens the provider's own confirmation page for switching an existing,
+     * non-terminal subscription to a different plan tier (Stripe: a Customer
+     * Portal `subscription_update_confirm` flow). Missing → the foundation
+     * rejects `switch-plan` with `plan_switch_not_supported`.
+     */
+    readonly createPlanSwitchSession?: (ctx: HandlerContext, options: {
+        readonly providerSubscriptionId: string;
+        readonly targetPriceId: string;
+        readonly allowedPriceIds: readonly string[];
+        readonly returnUrl: string;
+    }) => Promise<{
+        readonly url: string;
+    }>;
+    /**
+     * Fetches the live provider-side state of one subscription, for the
+     * `sync-subscriptions` backfill job — catches drift (e.g. a `cancel_at`
+     * set on the provider's own dashboard) that never reached us as a
+     * webhook. Missing → sync-subscription reports `provider_cannot_retrieve`
+     * instead of throwing. Null → the implementation could not resolve a
+     * snapshot for this id — the subscription no longer exists at the
+     * provider (deleted account, ...), or its state no longer maps onto this
+     * app's config (e.g. Stripe's price-to-tier — same silent-drop the
+     * webhook path already applies to an unmapped price).
+     */
+    readonly retrieveSubscription?: (ctx: HandlerContext, providerSubscriptionId: string) => Promise<ProviderSubscriptionSnapshot | null>;
+};
+export type ProviderSubscriptionSnapshot = {
+    readonly providerCustomerId: string;
+    readonly providerSubscriptionId: string;
+    readonly status: SubscriptionStatus;
+    readonly tier: string;
+    /** ISO instant string, same shape as `SubscriptionEventPayload.currentPeriodEndIso`. */
+    readonly currentPeriodEnd: string;
+    readonly cancelAt: string | null;
+    readonly rawPayload: string;
+};
+export declare const KNOWN_RECURRING_INTERVALS: readonly ["day", "week", "month", "year"];
+export type RecurringInterval = (typeof KNOWN_RECURRING_INTERVALS)[number];
+export type ProviderPrice = {
+    readonly priceId: string;
+    /** Smallest currency unit (e.g. cents). Null for prices with no flat
+     *  amount (tiered/usage-based prices). */
+    readonly unitAmount: number | null;
+    /** Lower-case ISO currency code, as returned by the provider. */
+    readonly currency: string;
+    /** Null for a one-off (non-recurring) price, or an interval the provider
+     *  returned that isn't in KNOWN_RECURRING_INTERVALS. */
+    readonly interval: RecurringInterval | null;
+    readonly intervalCount: number | null;
+    readonly active: boolean;
+    readonly metadata: Readonly<Record<string, string>>;
+};
+export type BillingPlanBenefit = {
+    readonly labelKey: string;
+    readonly params?: Readonly<Record<string, string | number>>;
+};
+export type BillingPlanCatalog<TTier extends string = string> = {
+    /** Purchasable tiers, in display order. */
+    readonly plans: readonly TTier[];
+    /** Also used for the caller's current tier even when it isn't purchasable
+     *  (e.g. a legacy or free tier not in `plans`). */
+    readonly tierLabelKey: (tier: string) => string;
+    readonly benefits: (tier: string) => readonly BillingPlanBenefit[];
+    readonly resolveCurrentTier: (db: TenantDb, tenantId: TenantId) => Promise<string>;
+    readonly viewRoles: readonly string[];
+    /** Defaults to DEFAULT_PURCHASE_ROLES. */
+    readonly purchaseRoles?: readonly string[];
+    /** Appended to `baseUrl` after a successful plan checkout; must start
+     *  with "/" (and not "//"). */
+    readonly successPath: string;
+    readonly cancelPath: string;
+    /** Portal return-path — used both by `create-portal-session` (defaults to
+     *  `baseUrl` itself when unset) and by `switch-plan` after a plan switch
+     *  (defaults to `successPath` there instead). */
+    readonly returnPath?: string;
+    /** Defaults to the only registered provider exposing `priceToTier`. */
+    readonly providerName?: string;
+};
+export type BillingFoundationOptions<TTier extends string = string> = {
+    /** Absolute http(s) URL. Its origin is the only redirect origin
+     *  create-checkout-session/create-portal-session (when set) and the plan
+     *  handlers accept — see checkout-core's `assertRedirectOrigins`. May
+     *  carry a path prefix (e.g. "https://app.example.com/tenant-x"); plan
+     *  URLs are built by string-concatenating it with the plan paths below,
+     *  NOT via `new URL(path, baseUrl)` (which would drop the prefix). */
+    readonly baseUrl?: string;
+    readonly catalog?: BillingPlanCatalog<TTier>;
+    /** Injectable clock for the stale-incomplete-subscription check
+     *  (constants.ts's `isSubscriptionBlockingCheckout`) — same always-
+     *  optional, real-time-default shape as `createDekCache`'s `now` option.
+     *  Defaults to `Temporal.Now.instant` when omitted. */
+    readonly now?: () => Temporal.Instant;
+};
+/** `BillingFoundationOptions` after `createBillingFoundationFeature`'s own
+ *  defaulting — `now` is always present. Handler-factories that call
+ *  `options.now()` take this instead of the still-optional public type. */
+export type ResolvedBillingFoundationOptions = BillingFoundationOptions & {
+    readonly now: () => Temporal.Instant;
+};
+export type BillingPlanPrice = {
+    readonly unitAmount: number;
+    readonly currency: string;
+    readonly interval: ProviderPrice["interval"];
+    readonly intervalCount: number | null;
+};
+export type BillingPlanView = {
+    readonly tier: string;
+    readonly labelKey: string;
+    readonly price: BillingPlanPrice | null;
+    readonly benefits: readonly BillingPlanBenefit[];
+    readonly isCurrent: boolean;
+    readonly action: BillingPlanAction;
+};
+export type BillingPlansResult = {
+    readonly enabled: boolean;
+    readonly currentTier: {
+        readonly tier: string;
+        readonly labelKey: string;
+        readonly benefits: readonly BillingPlanBenefit[];
+    };
+    readonly subscription: {
+        readonly status: string;
+        readonly tier: string;
+        readonly terminal: boolean;
+        readonly currentPeriodEnd: string;
+        readonly cancelAt: string | null;
+    } | null;
+    readonly canPurchase: boolean;
+    readonly plans: readonly BillingPlanView[];
+};
+declare module "@cosmicdrift/kumiko-framework/engine" {
+    interface KumikoExtensionOptionsMap {
+        [SUBSCRIPTION_PROVIDER_EXTENSION]: SubscriptionProviderPlugin;
+    }
+}

package/dist/billing-foundation/types.js

@@ -0,0 +1,31 @@
+// Plugin-Contract + Domain-Types der subscription-foundation. Provider-
+// Plugins (subscription-stripe, subscription-mollie, ...) implementieren
+// `SubscriptionProviderPlugin` und registrieren via
+// `r.useExtension("subscriptionProvider", "<name>", { build })`.
+//
+// **Two-phase plugin contract:**
+//   1. **Pre-tenant-resolution:** `verifyAndParseWebhook` läuft BEVOR
+//      ein Tenant aus dem Event aufgelöst ist — kein HandlerContext
+//      verfügbar. Das **Webhook-secret ist app-wide** (App-Owner's
+//      Stripe-/PayPal-Account, nicht Tenant-Sache). Damit ein Plugin den
+//      secret ZUR LAUFFZEIT aus dem secrets-Feature lesen kann (statt aus
+//      einem mount-time-Closure), reicht der webhook-handler einen
+//      optionalen system-scoped `SecretsContext` als 3. Arg durch — der
+//      Plugin liest seine app-wide-Secrets daraus un-audited unter
+//      SYSTEM_TENANT_ID. Plugins, die ihre Keys weiter aus einem Closure
+//      halten (z.B. mollie), ignorieren den Param → backward-compatible.
+//   2. **Post-tenant-resolution:** `createPortalSession` +
+//      `cancelSubscription` werden aus regulären write-handlern
+//      gerufen mit voll-aufgelöstem HandlerContext. Plugin kann
+//      hier ctx.config + ctx.secrets nutzen für tenant-spezifische
+//      Konfiguration (z.B. tenant-eigene customer-id-mapping).
+//
+// Foundation nutzt nur den common-subset der Provider-Funktionalität —
+// proration, multi-currency, coupons etc. bleiben provider-spezifisch
+// und sind über den Customer-Portal-Link erreichbar.
+import { SUBSCRIPTION_PROVIDER_EXTENSION, } from "./constants.js";
+// =============================================================================
+// Provider price + billing-plans catalog
+// =============================================================================
+// Closed set a provider's recurring-price interval narrows to; an unrecognized provider value maps to null instead of widening this type.
+export const KNOWN_RECURRING_INTERVALS = ["day", "week", "month", "year"];

package/dist/billing-foundation/validate-options.d.ts

@@ -0,0 +1,6 @@
+import type { BillingFoundationOptions } from "./types.js";
+/** Validates `options` and throws a plain `Error` with a clear message at
+ *  feature-definition time — same pattern as `createCapOverviewFeature`.
+ *  `createBillingFoundationFeature()` (no options) always succeeds; the
+ *  extra checks only fire once a caller opts into `baseUrl`/`catalog`. */
+export declare function validateOptions(options: BillingFoundationOptions): void;

package/dist/billing-foundation/validate-options.js

@@ -0,0 +1,54 @@
+// Feature-definition-time validation for createBillingFoundationFeature's
+// options — split out of feature.ts to keep that file at registration-only
+// concerns (app-feature-structure guard's 300-line budget). Internal — not
+// re-exported from index.ts.
+function isRootRelativePath(path) {
+    return path.startsWith("/") && !path.startsWith("//");
+}
+/** Validates `options` and throws a plain `Error` with a clear message at
+ *  feature-definition time — same pattern as `createCapOverviewFeature`.
+ *  `createBillingFoundationFeature()` (no options) always succeeds; the
+ *  extra checks only fire once a caller opts into `baseUrl`/`catalog`. */
+export function validateOptions(options) {
+    if (options.baseUrl !== undefined) {
+        let parsed;
+        try {
+            parsed = new URL(options.baseUrl);
+        }
+        catch {
+            throw new Error(`createBillingFoundationFeature: baseUrl "${options.baseUrl}" is not a parseable absolute URL.`);
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            throw new Error(`createBillingFoundationFeature: baseUrl "${options.baseUrl}" must use http or https (parsed protocol "${parsed.protocol}").`);
+        }
+    }
+    const { catalog } = options;
+    // skip: no catalog configured, nothing more to validate.
+    if (!catalog)
+        return;
+    if (options.baseUrl === undefined) {
+        throw new Error("createBillingFoundationFeature: catalog requires baseUrl (plan checkouts need it to build success/cancel/return URLs).");
+    }
+    if (catalog.plans.length === 0) {
+        throw new Error("createBillingFoundationFeature: catalog.plans must not be empty.");
+    }
+    const seen = new Set();
+    for (const tier of catalog.plans) {
+        if (seen.has(tier)) {
+            throw new Error(`createBillingFoundationFeature: catalog.plans has a duplicate tier "${tier}".`);
+        }
+        seen.add(tier);
+    }
+    for (const [key, path] of [
+        ["successPath", catalog.successPath],
+        ["cancelPath", catalog.cancelPath],
+        ["returnPath", catalog.returnPath],
+    ]) {
+        if (path !== undefined && !isRootRelativePath(path)) {
+            throw new Error(`createBillingFoundationFeature: catalog.${key} "${path}" must start with "/" and not "//".`);
+        }
+    }
+    if (catalog.viewRoles.length === 0) {
+        throw new Error("createBillingFoundationFeature: catalog.viewRoles must not be empty.");
+    }
+}

package/dist/billing-foundation/web/billing-plans-panel.d.ts

@@ -0,0 +1,3 @@
+import { type ExtensionSectionProps } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode } from "react";
+export declare function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode;