@cosmicdrift/kumiko-bundled-features 0.337.1 → 0.339.0

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

@@ -2,7 +2,7 @@
 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";
+import { type BillingEventKinds, type BillingPlanAction, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, type SubscriptionEventType, type SubscriptionStatus, type TerminationScope } 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,
@@ -21,6 +21,9 @@ export type SubscriptionEvent = {
     /** Plattform-Tenant-ID (provider-customer-metadata oder lookup
      *  via providerCustomerId). Plugin macht die resolution. */
     readonly tenantId: string;
+    /** Consent id echoed back from checkout metadata; omitted when absent or
+     *  malformed. */
+    readonly consentId?: string;
     /** Provider-eigene customer-id für späteren Lookup bei events
      *  ohne metadata. */
     readonly providerCustomerId: string;
@@ -41,9 +44,6 @@ export type SubscriptionEvent = {
      *  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
@@ -58,13 +58,16 @@ export type PaymentEvent = {
      *  create time) — never from a freely-choosable payload field, or an
      *  attacker could attribute payments to someone else's tenant. */
     readonly tenantId: string;
+    /** Consent id echoed back from checkout metadata; omitted when absent or
+     *  malformed. */
+    readonly consentId?: string;
+    /** Provider's checkout/payment object id (Stripe checkout session id) —
+     *  lets consumers key their own grants without the raw provider payload. */
+    readonly providerCheckoutId?: 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 = {
     /**
@@ -127,6 +130,13 @@ export type SubscriptionProviderPlugin = {
          *  credit top-ups). Optional with default `"subscription"` — existing
          *  callers are unaffected. */
         readonly mode?: "subscription" | "payment";
+        /** Id of the consumer-protection consent recorded for this checkout.
+         *  Travels as provider metadata and comes back on the webhook event. */
+        readonly consentId?: string;
+        /** App locale (BCP-47-ish, e.g. "de", "de-DE") for the hosted page. */
+        readonly locale?: string;
+        /** Text shown next to the submit button on the hosted page. */
+        readonly submitMessage?: string;
     }) => Promise<{
         readonly url: string;
     }>;
@@ -155,7 +165,10 @@ export type SubscriptionProviderPlugin = {
      * nicht, wenn auch createPortalSession fehlt — dann ist
      * Cancel-Flow Provider-Dashboard-only).
      */
-    readonly cancelSubscription?: (ctx: HandlerContext, providerSubscriptionId: string) => Promise<void>;
+    readonly cancelSubscription?: (ctx: HandlerContext, options: {
+        readonly providerSubscriptionId: string;
+        readonly when: SubscriptionCancelTiming;
+    }) => 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
@@ -223,7 +236,6 @@ export type ProviderSubscriptionSnapshot = {
     /** 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];
@@ -267,6 +279,28 @@ export type BillingPlanCatalog<TTier extends string = string> = {
     /** Defaults to the only registered provider exposing `priceToTier`. */
     readonly providerName?: string;
 };
+/** Consumer-protection consent gate (§ 312j / § 356 BGB style). When set,
+ *  `start-plan-checkout` and `create-checkout-session` require a `consent`
+ *  payload and record it as an event before the buyer reaches the provider. */
+export type ConsumerProtectionOptions = {
+    /** Slug of the template-resolver `text-block` holding the terms text; its
+     *  content hash is stored with every recorded consent. */
+    readonly termsTextBlock: string;
+    /** Per-locale VAT note; must carry at least `de` and `en`. */
+    readonly vatNote: Readonly<Record<string, string>>;
+    readonly operatorEmail: string;
+    /** Where the public § 312k declaration is reachable. `"tenant-host"`
+     *  (default): on a host that resolves a tenant. `"platform"`: also on a
+     *  host that resolves none (the platform apex) — the declaration then runs
+     *  without a request tenant and finds the contract by the declarant's email. */
+    readonly terminationScope?: TerminationScope;
+    /** Root-relative paths or absolute https URLs. */
+    readonly legalLinks: {
+        readonly terms: string;
+        readonly withdrawal: string;
+        readonly privacy: 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
@@ -276,6 +310,8 @@ export type BillingFoundationOptions<TTier extends string = string> = {
      *  NOT via `new URL(path, baseUrl)` (which would drop the prefix). */
     readonly baseUrl?: string;
     readonly catalog?: BillingPlanCatalog<TTier>;
+    /** Enables the consent gate on checkout; requires `baseUrl`. */
+    readonly consumerProtection?: ConsumerProtectionOptions;
     /** Injectable clock for the stale-incomplete-subscription check
      *  (constants.ts's `isSubscriptionBlockingCheckout`) — same always-
      *  optional, real-time-default shape as `createDekCache`'s `now` option.
@@ -318,6 +354,15 @@ export type BillingPlansResult = {
     } | null;
     readonly canPurchase: boolean;
     readonly plans: readonly BillingPlanView[];
+    /** Present only when `consumerProtection` is configured. */
+    readonly consumerProtection?: {
+        readonly consentTexts: Readonly<Record<"de" | "en", {
+            readonly earlyPerformance: string;
+            readonly withdrawalLoss: string;
+            readonly consentTextVersion: string;
+        }>>;
+        readonly legalLinks: ConsumerProtectionOptions["legalLinks"];
+    };
 };
 declare module "@cosmicdrift/kumiko-framework/engine" {
     interface KumikoExtensionOptionsMap {

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

@@ -2,25 +2,66 @@
 // 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.
+import * as z from "zod";
+import { isTerminationScope, TERMINATION_SCOPES } from "./constants.js";
 function isRootRelativePath(path) {
     return path.startsWith("/") && !path.startsWith("//");
 }
+function isRootRelativeOrHttpsUrl(link) {
+    if (isRootRelativePath(link))
+        return true;
+    try {
+        return new URL(link).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function validateConsumerProtection(cp) {
+    if (cp.termsTextBlock.trim() === "") {
+        throw new Error("createBillingFoundationFeature: consumerProtection.termsTextBlock is empty.");
+    }
+    for (const locale of ["de", "en"]) {
+        if (!cp.vatNote[locale]?.trim()) {
+            throw new Error(`createBillingFoundationFeature: consumerProtection.vatNote needs a non-empty "${locale}" entry.`);
+        }
+    }
+    if (!z.email().safeParse(cp.operatorEmail).success) {
+        throw new Error(`createBillingFoundationFeature: consumerProtection.operatorEmail "${cp.operatorEmail}" is not a valid email address.`);
+    }
+    if (cp.terminationScope !== undefined && !isTerminationScope(cp.terminationScope)) {
+        throw new Error(`createBillingFoundationFeature: consumerProtection.terminationScope "${String(cp.terminationScope)}" must be one of ${TERMINATION_SCOPES.map((scope) => `"${scope}"`).join(", ")}.`);
+    }
+    for (const [key, link] of Object.entries(cp.legalLinks)) {
+        if (!isRootRelativeOrHttpsUrl(link)) {
+            throw new Error(`createBillingFoundationFeature: consumerProtection.legalLinks.${key} "${link}" must be a root-relative path ("/..." not "//") or an absolute https URL.`);
+        }
+    }
+}
+function validateBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`createBillingFoundationFeature: baseUrl "${baseUrl}" is not a parseable absolute URL.`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`createBillingFoundationFeature: baseUrl "${baseUrl}" must use http or https (parsed protocol "${parsed.protocol}").`);
+    }
+}
 /** 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}").`);
+    if (options.baseUrl !== undefined)
+        validateBaseUrl(options.baseUrl);
+    if (options.consumerProtection) {
+        if (options.baseUrl === undefined) {
+            throw new Error("createBillingFoundationFeature: consumerProtection requires baseUrl (checkout redirect URLs are built from it).");
         }
+        validateConsumerProtection(options.consumerProtection);
     }
     const { catalog } = options;
     // skip: no catalog configured, nothing more to validate.

package/dist/billing-foundation/web/billing-plans-panel.js

@@ -5,6 +5,8 @@ import { useLocale, useMutation, usePrimitives, useQuery, useTranslation, } from
 import { formatMoney, PlanCard, PlanGrid, } from "@cosmicdrift/kumiko-renderer-web";
 import { useState } from "react";
 import { BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "../constants.js";
+import { CancelContractDialog } from "./cancel-contract-dialog.js";
+import { CheckoutConsentDialog } from "./checkout-consent-dialog.js";
 function intervalKey(price) {
     if (price === null || price.interval === null)
         return undefined;
@@ -12,6 +14,13 @@ function intervalKey(price) {
         ? `billing-foundation.plans.everyInterval.${price.interval}`
         : `billing-foundation.plans.perInterval.${price.interval}`;
 }
+function renewalKey(price) {
+    if (price === null || price.interval === null)
+        return undefined;
+    return price.intervalCount !== null && price.intervalCount > 1
+        ? `billing-foundation.consent.renewsEvery.${price.interval}`
+        : `billing-foundation.consent.renews.${price.interval}`;
+}
 function localizedParams(params, locale) {
     if (params === undefined)
         return undefined;
@@ -73,7 +82,7 @@ function planCta(plan, result, t, onAction, redirecting) {
 export function BillingPlansPanel(_props) {
     const t = useTranslation();
     const locale = useLocale().locale();
-    const { Banner } = usePrimitives();
+    const { Banner, Button } = usePrimitives();
     const query = useQuery(SubscriptionFoundationQueries.billingPlans, {});
     const checkoutMutation = useMutation(SubscriptionFoundationHandlers.startPlanCheckout);
     const switchMutation = useMutation(SubscriptionFoundationHandlers.switchPlan);
@@ -84,7 +93,21 @@ export function BillingPlansPanel(_props) {
     // enabled during its own in-flight request — a double-click risk — and
     // `mutation.pending` alone drops before `window.location.assign` completes.
     const [redirecting, setRedirecting] = useState(false);
+    const [consentTier, setConsentTier] = useState(null);
+    const [cancelOpen, setCancelOpen] = useState(false);
+    async function orderWithConsent(tier, consent) {
+        const result = await checkoutMutation.mutate({ tier, consent });
+        if (result.isSuccess) {
+            setRedirecting(true);
+            window.location.assign(result.data.url);
+        }
+        return result;
+    }
     async function handleAction(tier, kind) {
+        if (kind === "checkout" && query.data?.consumerProtection !== undefined) {
+            setConsentTier(tier);
+            return;
+        }
         setRedirecting(true);
         const mutation = kind === "checkout" ? checkoutMutation : switchMutation;
         const result = await mutation.mutate({ tier });
@@ -114,7 +137,10 @@ export function BillingPlansPanel(_props) {
     if (!query.data)
         return null;
     const result = query.data;
-    const mutationError = checkoutMutation.error ?? switchMutation.error ?? portalMutation.error;
+    // The consent dialog shows the checkout error itself.
+    const mutationError = (consentTier === null ? checkoutMutation.error : null) ??
+        switchMutation.error ??
+        portalMutation.error;
     const canManage = result.subscription !== null && !result.subscription.terminal && result.canPurchase;
     function toCardProps(plan) {
         const key = intervalKey(plan.price);
@@ -151,6 +177,8 @@ export function BillingPlansPanel(_props) {
     // (a legacy/free/pilot tier outside `catalog.plans`) — when none of the
     // rendered plans is the current one, a synthetic current-tier card (no
     // price, no cta) keeps it visible regardless of enabled/disabled.
+    const consentPlan = consentTier !== null ? result.plans.find((plan) => plan.tier === consentTier) : undefined;
+    const consumerProtection = result.consumerProtection;
     const currentTierInPlans = result.plans.some((plan) => plan.isCurrent);
     const visiblePlans = result.enabled
         ? result.plans
@@ -161,5 +189,14 @@ export function BillingPlansPanel(_props) {
                         date: toInstant(result.subscription.cancelAt).toLocaleString(locale, {
                             dateStyle: "medium",
                         }),
-                    }), " ", t("billing-foundation.plans.switchRequiresReactivation")] })), _jsxs(PlanGrid, { testId: "billing-plans-grid", children: [!currentTierInPlans && (_jsx(PlanCard, { title: t(result.currentTier.labelKey), current: true, testId: "billing-plan-card-current", features: result.currentTier.benefits.map((benefit) => t(benefit.labelKey, localizedParams(benefit.params, locale))), secondaryAction: manageOrReactivateAction(canManage, result.subscription, t, handleManage, redirecting) })), visiblePlans.map((plan) => (_jsx(PlanCard, { testId: `billing-plan-card-${plan.tier}`, ...toCardProps(plan) }, plan.tier)))] })] }));
+                    }), " ", t("billing-foundation.plans.switchRequiresReactivation")] })), consumerProtection !== undefined && canManage && (_jsx("div", { children: _jsx(Button, { variant: "secondary", onClick: () => setCancelOpen(true), testId: "billing-plans-cancel-contract", children: t("billing-foundation.cancel.open") }) })), _jsxs(PlanGrid, { testId: "billing-plans-grid", children: [!currentTierInPlans && (_jsx(PlanCard, { title: t(result.currentTier.labelKey), current: true, testId: "billing-plan-card-current", features: result.currentTier.benefits.map((benefit) => t(benefit.labelKey, localizedParams(benefit.params, locale))), secondaryAction: manageOrReactivateAction(canManage, result.subscription, t, handleManage, redirecting) })), visiblePlans.map((plan) => (_jsx(PlanCard, { testId: `billing-plan-card-${plan.tier}`, ...toCardProps(plan) }, plan.tier)))] }), consumerProtection !== undefined &&
+                consentPlan !== undefined &&
+                consentPlan.price !== null && (_jsx(CheckoutConsentDialog, { open: true, onOpenChange: (open) => {
+                    if (!open)
+                        setConsentTier(null);
+                }, planName: t(consentPlan.labelKey), price: {
+                    amount: formatMoney(consentPlan.price.unitAmount, consentPlan.price.currency, locale),
+                    renewalKey: renewalKey(consentPlan.price),
+                    count: new Intl.NumberFormat(locale).format(consentPlan.price.intervalCount ?? 1),
+                }, consumerProtection: consumerProtection, onOrder: (consent) => orderWithConsent(consentPlan.tier, consent), onConsentTextOutdated: () => void query.refetch() })), consumerProtection !== undefined && canManage && (_jsx(CancelContractDialog, { open: cancelOpen, onOpenChange: setCancelOpen, onTerminated: () => void query.refetch() }))] }));
 }

package/dist/billing-foundation/web/cancel-contract-dialog.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from "react";
+export type CancelContractDialogProps = {
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+    readonly onTerminated: () => void;
+};
+export declare function CancelContractDialog({ open, onOpenChange, onTerminated, }: CancelContractDialogProps): ReactNode;

package/dist/billing-foundation/web/cancel-contract-dialog.js

@@ -0,0 +1,57 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// @runtime client
+import { toInstant } from "@cosmicdrift/kumiko-headless";
+import { useLocale, useMutation, usePrimitives, useTranslation, } from "@cosmicdrift/kumiko-renderer";
+import { ModeSwitch } from "@cosmicdrift/kumiko-renderer-web";
+import { useState } from "react";
+import { SubscriptionFoundationHandlers } from "../constants.js";
+const DECLARATION_TYPES = [
+    "termination",
+    "withdrawal",
+];
+const TERMINATION_KINDS = ["ordinary", "extraordinary"];
+// kumiko-lint-ignore no-custom-primitives Uses usePrimitives().Modal internally, name is a billing domain action, not a primitive reimplementation
+export function CancelContractDialog({ open, onOpenChange, onTerminated, }) {
+    const t = useTranslation();
+    const locale = useLocale().locale();
+    const { Modal, Heading, Text, Field, Input, Button, Banner } = usePrimitives();
+    const terminate = useMutation(SubscriptionFoundationHandlers.terminateContract);
+    const [step, setStep] = useState("form");
+    const [declarationType, setDeclarationType] = useState("termination");
+    const [terminationKind, setTerminationKind] = useState("ordinary");
+    const [reason, setReason] = useState("");
+    const [receipt, setReceipt] = useState(null);
+    const reasonMissing = terminationKind === "extraordinary" && reason.trim().length === 0;
+    async function submit() {
+        const trimmedReason = reason.trim();
+        const result = await terminate.mutate({
+            declarationType,
+            terminationKind,
+            ...(trimmedReason.length > 0 && { reason: trimmedReason }),
+        });
+        if (!result.isSuccess)
+            return;
+        setReceipt(result.data);
+        setStep("receipt");
+        onTerminated();
+    }
+    function formatInstant(iso) {
+        return toInstant(iso).toLocaleString(locale, { dateStyle: "medium", timeStyle: "short" });
+    }
+    return (_jsx(Modal, { open: open, onOpenChange: onOpenChange, title: t("billing-foundation.cancel.title"), testId: "cancel-contract-dialog", children: _jsxs("div", { className: "flex flex-col gap-4", children: [_jsx(Heading, { variant: "page", children: t("billing-foundation.cancel.title") }), step === "form" && (_jsxs(_Fragment, { children: [_jsx(Text, { variant: "muted", children: t("billing-foundation.cancel.declaration") }), _jsx(ModeSwitch, { value: declarationType, options: DECLARATION_TYPES.map((value) => ({
+                                value,
+                                label: t(`billing-foundation.cancel.declaration.${value}`),
+                            })), onChange: setDeclarationType, ariaLabel: t("billing-foundation.cancel.declaration"), testId: "cancel-declaration-type" }), declarationType === "withdrawal" && (_jsx(Text, { variant: "muted", children: t("billing-foundation.cancel.withdrawalHint") })), _jsx(Text, { variant: "muted", children: t("billing-foundation.cancel.kind") }), _jsx(ModeSwitch, { value: terminationKind, options: TERMINATION_KINDS.map((value) => ({
+                                value,
+                                label: t(`billing-foundation.cancel.kind.${value}`),
+                            })), onChange: setTerminationKind, ariaLabel: t("billing-foundation.cancel.kind"), testId: "cancel-termination-kind" }), terminationKind === "extraordinary" && (_jsx(Field, { id: "cancel-reason", label: t("billing-foundation.cancel.reason"), required: true, children: _jsx(Input, { kind: "textarea", id: "cancel-reason", name: "cancel-reason", value: reason, onChange: setReason, required: true, rows: 3 }) })), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "secondary", onClick: () => onOpenChange(false), testId: "cancel-contract-close", children: t("billing-foundation.cancel.close") }), _jsx(Button, { disabled: reasonMissing, onClick: () => setStep("confirm"), testId: "cancel-contract-continue", children: t("billing-foundation.cancel.continue") })] })] })), step === "confirm" && (_jsxs(_Fragment, { children: [_jsx(Text, { children: t("billing-foundation.cancel.confirmQuestion", {
+                                declaration: t(`billing-foundation.cancel.declaration.${declarationType}`),
+                                kind: t(`billing-foundation.cancel.kind.${terminationKind}`),
+                            }) }), terminate.error !== null && (_jsx(Banner, { variant: "error", testId: "cancel-contract-error", children: t(terminate.error.i18nKey, terminate.error.i18nParams) })), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "secondary", disabled: terminate.pending, onClick: () => setStep("form"), testId: "cancel-contract-back", children: t("billing-foundation.cancel.back") }), _jsx(Button, { variant: "danger", disabled: terminate.pending, loading: terminate.pending, onClick: submit, testId: "cancel-contract-submit", children: t("billing-foundation.cancel.submit") })] })] })), step === "receipt" && receipt !== null && (_jsxs(_Fragment, { children: [_jsxs("div", { className: "flex flex-col gap-1", "data-testid": "cancel-contract-receipt", children: [_jsx(Text, { children: t("billing-foundation.cancel.receivedAt", {
+                                        date: formatInstant(receipt.receivedAtIso),
+                                    }) }), _jsx(Text, { children: receipt.effectiveAtIso !== null
+                                        ? t("billing-foundation.cancel.effectiveAt", {
+                                            date: formatInstant(receipt.effectiveAtIso),
+                                        })
+                                        : t("billing-foundation.cancel.effectiveUnknown") }), _jsx(Text, { variant: "muted", children: t("billing-foundation.cancel.emailConfirmation") })] }), _jsx("div", { className: "flex justify-end", children: _jsx(Button, { onClick: () => onOpenChange(false), testId: "cancel-contract-done", children: t("billing-foundation.cancel.close") }) })] }))] }) }));
+}

package/dist/billing-foundation/web/checkout-consent-dialog.d.ts

@@ -0,0 +1,28 @@
+import type { WriteResult } from "@cosmicdrift/kumiko-headless";
+import { type ReactNode } from "react";
+import type { BillingPlansResult } from "../types.js";
+export declare const CONSENT_TEXT_OUTDATED_CODE = "consent_text_outdated";
+type ConsumerProtectionView = NonNullable<BillingPlansResult["consumerProtection"]>;
+export type CheckoutConsentPayload = {
+    readonly earlyPerformanceRequested: true;
+    readonly withdrawalLossAcknowledged: true;
+    readonly consentTextVersion: string;
+    readonly locale: string;
+};
+export type CheckoutConsentDialogProps = {
+    readonly open: boolean;
+    readonly onOpenChange: (open: boolean) => void;
+    readonly planName: string;
+    readonly price: {
+        readonly amount: string;
+        readonly renewalKey?: string;
+        readonly count: string;
+    };
+    readonly consumerProtection: ConsumerProtectionView;
+    readonly onOrder: (consent: CheckoutConsentPayload) => Promise<WriteResult<{
+        url: string;
+    }>>;
+    readonly onConsentTextOutdated: () => void;
+};
+export declare function CheckoutConsentDialog({ open, onOpenChange, planName, price, consumerProtection, onOrder, onConsentTextOutdated, }: CheckoutConsentDialogProps): ReactNode;
+export {};

package/dist/billing-foundation/web/checkout-consent-dialog.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLocale, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { useState } from "react";
+import { resolveConsentLocale } from "../consumer-protection/consent-locale.js";
+export const CONSENT_TEXT_OUTDATED_CODE = "consent_text_outdated";
+// kumiko-lint-ignore no-custom-primitives Uses usePrimitives().Modal internally, name is a billing domain action, not a primitive reimplementation
+export function CheckoutConsentDialog({ open, onOpenChange, planName, price, consumerProtection, onOrder, onConsentTextOutdated, }) {
+    const t = useTranslation();
+    const uiLocale = useLocale().locale();
+    const { Modal, Heading, Text, Field, Input, Button, Link, Banner } = usePrimitives();
+    const [earlyPerformance, setEarlyPerformance] = useState(false);
+    const [withdrawalLoss, setWithdrawalLoss] = useState(false);
+    const [submitting, setSubmitting] = useState(false);
+    const [errorText, setErrorText] = useState(null);
+    const consentLocale = resolveConsentLocale(uiLocale);
+    const texts = consumerProtection.consentTexts[consentLocale];
+    const { legalLinks } = consumerProtection;
+    async function order() {
+        setSubmitting(true);
+        setErrorText(null);
+        const result = await onOrder({
+            earlyPerformanceRequested: true,
+            withdrawalLossAcknowledged: true,
+            consentTextVersion: texts.consentTextVersion,
+            locale: consentLocale,
+        });
+        if (result.isSuccess)
+            return;
+        setSubmitting(false);
+        setErrorText(t(result.error.i18nKey, result.error.i18nParams));
+        if (result.error.code === CONSENT_TEXT_OUTDATED_CODE) {
+            setEarlyPerformance(false);
+            setWithdrawalLoss(false);
+            onConsentTextOutdated();
+        }
+    }
+    return (_jsx(Modal, { open: open, onOpenChange: onOpenChange, title: t("billing-foundation.consent.title"), testId: "checkout-consent-dialog", children: _jsxs("div", { className: "flex flex-col gap-4", children: [_jsx(Heading, { variant: "page", children: t("billing-foundation.consent.title") }), _jsxs("div", { className: "flex flex-col gap-1", "data-testid": "checkout-consent-summary", children: [_jsxs(Text, { children: [planName, " \u2014 ", price.amount] }), price.renewalKey !== undefined && (_jsx(Text, { variant: "muted", children: t(price.renewalKey, { count: price.count }) })), _jsx(Text, { variant: "muted", children: t("billing-foundation.consent.cancelAnytime") })] }), _jsxs("div", { className: "flex flex-wrap gap-4", children: [_jsx(Link, { href: legalLinks.terms, target: "_blank", children: t("billing-foundation.consent.link.terms") }), _jsx(Link, { href: legalLinks.withdrawal, target: "_blank", children: t("billing-foundation.consent.link.withdrawal") }), _jsx(Link, { href: legalLinks.privacy, target: "_blank", children: t("billing-foundation.consent.link.privacy") })] }), _jsx(Field, { id: "consent-early-performance", label: texts.earlyPerformance, layout: "inline", children: _jsx(Input, { kind: "boolean", id: "consent-early-performance", name: "consent-early-performance", value: earlyPerformance, onChange: setEarlyPerformance, disabled: submitting }) }), _jsx(Field, { id: "consent-withdrawal-loss", label: texts.withdrawalLoss, layout: "inline", children: _jsx(Input, { kind: "boolean", id: "consent-withdrawal-loss", name: "consent-withdrawal-loss", value: withdrawalLoss, onChange: setWithdrawalLoss, disabled: submitting }) }), errorText !== null && (_jsx(Banner, { variant: "error", testId: "checkout-consent-error", children: errorText })), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "secondary", disabled: submitting, onClick: () => onOpenChange(false), testId: "checkout-consent-cancel", children: t("billing-foundation.consent.back") }), _jsx(Button, { disabled: !earlyPerformance || !withdrawalLoss || submitting, loading: submitting, onClick: order, testId: "checkout-consent-order", children: t("billing-foundation.consent.order") })] })] }) }));
+}

package/dist/billing-foundation/webhook-handler.js

@@ -61,7 +61,10 @@ export function createSubscriptionWebhookRoute(options = {}) {
                         providerName: parsed.providerName,
                         providerCustomerId: parsed.providerCustomerId,
                         priceId: parsed.priceId,
-                        rawPayload: parsed.rawPayload,
+                        ...(parsed.consentId !== undefined && { consentId: parsed.consentId }),
+                        ...(parsed.providerCheckoutId !== undefined && {
+                            providerCheckoutId: parsed.providerCheckoutId,
+                        }),
                     },
                 });
                 return respondFromDispatch(c, dispatched.isSuccess && options.afterDispatch
@@ -81,7 +84,7 @@ export function createSubscriptionWebhookRoute(options = {}) {
                     tier: parsed.tier,
                     currentPeriodEndIso: parsed.currentPeriodEnd,
                     ...(parsed.cancelAt !== undefined && { cancelAtIso: parsed.cancelAt }),
-                    rawPayload: parsed.rawPayload,
+                    ...(parsed.consentId !== undefined && { consentId: parsed.consentId }),
                 },
             });
             return respondFromDispatch(c, dispatched.isSuccess && options.afterDispatch

package/dist/cap-counter/with-cap-enforcement.js

@@ -9,9 +9,13 @@
 // Wrapper macht das Pattern explizit + co-located.
 //
 // **Atomicity caveat:** calendar booking runs in-process via bookCapUsage
-// (see book-cap-usage.ts). Rolling booking still dispatches the
-// SystemAdmin-only increment-rolling handler (event ownership), so rolling
-// callers need a SystemAdmin identity.
+// (see book-cap-usage.ts).
+// Rolling booking still dispatches the SystemAdmin-only increment-rolling
+// handler. In-process booking would work today only because the entity
+// executor appends without the event-ownership check (that check runs in
+// appendDomainEventCore alone); relying on that gap would break once the
+// executor path enforces ownership, so rolling callers need a SystemAdmin
+// identity until cap-counter declares an explicit foreign-booking opt-in.
 //
 // No automatic markSoftWarned here — that's inside enforceCapAndMaybeNotify
 // (enforce-cap.ts).

package/dist/cap-overview/access.d.ts

@@ -1 +1,2 @@
-export declare const MY_CAPS_ACCESS_ROLES: readonly string[];
+export declare const DEFAULT_CAP_USAGE_ROLES: readonly string[];
+export declare function resolveCapUsageRoles(usageVisibleTo: readonly string[] | undefined): readonly string[];

package/dist/cap-overview/access.js

@@ -1,8 +1,29 @@
 import { access } from "@cosmicdrift/kumiko-framework/engine";
-// Every built-in membership rank (role-assignment.ts: User < Editor < Admin <
-// TenantAdmin < SystemAdmin), so a regular team member can see their own
-// tenant's usage. Deliberately not `access.authenticated` — that preset omits
-// TenantAdmin and would revoke the access TenantAdmins already have. The
+// Usage numbers are an operator concern by default; wider visibility is an
+// explicit `usageVisibleTo` opt-in on createCapOverviewFeature. The my-caps
 // screen and the query that fills its cards must carry the SAME rule, or the
 // dashboard renders and every card 403s.
-export const MY_CAPS_ACCESS_ROLES = access.roles("User", "Editor", ...access.admin);
+export const DEFAULT_CAP_USAGE_ROLES = access.roles(...access.admin);
+// Roles the engine itself knows (role-assignment.ts ranks). App-declared roles
+// (assignableRole) only exist once the registry is composed, which is after
+// this feature is defined, so they cannot be validated here.
+const BUILT_IN_USAGE_VISIBLE_ROLES = new Set([
+    "User",
+    "Member",
+    "Editor",
+    "Admin",
+    "TenantAdmin",
+    "SystemAdmin",
+]);
+export function resolveCapUsageRoles(usageVisibleTo) {
+    if (usageVisibleTo === undefined)
+        return DEFAULT_CAP_USAGE_ROLES;
+    if (usageVisibleTo.length === 0) {
+        throw new Error("createCapOverviewFeature: `usageVisibleTo` must not be empty.");
+    }
+    const unknown = usageVisibleTo.filter((role) => !BUILT_IN_USAGE_VISIBLE_ROLES.has(role));
+    if (unknown.length > 0) {
+        throw new Error(`createCapOverviewFeature: usageVisibleTo has unknown role(s) ${unknown.map((r) => `"${r}"`).join(", ")} — known roles: ${[...BUILT_IN_USAGE_VISIBLE_ROLES].join(", ")}`);
+    }
+    return usageVisibleTo;
+}

package/dist/cap-overview/feature.d.ts

@@ -10,5 +10,9 @@ export type CreateCapOverviewOptions = {
      *  from (see screens.ts doc). "Filter by tier" was explicitly requested;
      *  omitting `tiers` silently drops that filter, not a supported default. */
     readonly tiers?: readonly string[];
+    /** Roles that may read their own tenant's usage (`caps:usage` + the my-caps
+     *  screen). Defaults to the admin roles (TenantAdmin, Admin, SystemAdmin);
+     *  list "User"/"Editor" to show usage to regular members. Built-in roles only. */
+    readonly usageVisibleTo?: readonly string[];
 };
 export declare function createCapOverviewFeature(opts: CreateCapOverviewOptions): FeatureDefinition;

package/dist/cap-overview/feature.js

@@ -5,8 +5,8 @@
 //      platform-wide table of every tenant's tier, billing status, and
 //      usage against a configurable set of caps.
 //   2. caps:usage query + my-caps / platform-tenant-caps dashboards —
-//      per-tenant usage cards. Every member of a tenant sees their own
-//      tenant; SystemAdmin can additionally view any tenant via `tenantId`.
+//      per-tenant usage cards. Tenant admins see their own
+//      tenant (`usageVisibleTo` widens it); SystemAdmin can additionally view any tenant via `tenantId`.
 //
 // **What this feature does NOT do:**
 //   - No writes. Reads tier-engine's read_tier_assignments, billing-
@@ -16,16 +16,18 @@
 //
 // **Boot-Dependencies:** tenant, tier-engine, billing-foundation.
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveCapUsageRoles } from "./access.js";
 import { CAP_OVERVIEW_FEATURE } from "./constants.js";
 import { createCapsUsageQuery } from "./handlers/caps-usage.query.js";
 import { createTenantCapsListQuery } from "./handlers/tenant-caps-list.query.js";
 import { tenantOptionsQuery } from "./handlers/tenant-options.query.js";
 import { CAP_OVERVIEW_I18N } from "./i18n.js";
-import { createTenantCapListScreen, myCapsScreen, platformTenantCapsScreen } from "./screens.js";
+import { createMyCapsScreen, createTenantCapListScreen, platformTenantCapsScreen, } from "./screens.js";
 export function createCapOverviewFeature(opts) {
     if (opts.caps.length === 0) {
         throw new Error("createCapOverviewFeature: `caps` must not be empty.");
     }
+    const usageRoles = resolveCapUsageRoles(opts.usageVisibleTo);
     const capIds = new Set(opts.caps.map((cap) => cap.id));
     const listCaps = opts.listCaps ?? opts.caps.slice(0, 3).map((cap) => cap.id);
     for (const id of listCaps) {
@@ -34,7 +36,7 @@ export function createCapOverviewFeature(opts) {
         }
     }
     return defineFeature(CAP_OVERVIEW_FEATURE, (r) => {
-        r.describe("Read-only visibility into per-tenant tier assignment and cap usage. SystemAdmin gets a platform-wide tenant list with usage bars; every member of a tenant gets their own tenant's usage as dashboard cards. Reads tier-engine, billing-foundation, and tenant data plus app-owned usage tables via caller-supplied CapSpec callbacks — never writes.");
+        r.describe("Read-only visibility into per-tenant tier assignment and cap usage. SystemAdmin gets a platform-wide tenant list with usage bars; tenant admins (or the roles in `usageVisibleTo`) get their own tenant's usage as dashboard cards. Reads tier-engine, billing-foundation, and tenant data plus app-owned usage tables via caller-supplied CapSpec callbacks — never writes.");
         r.uiHints({
             displayLabel: "Cap Overview · Tier & Usage Visibility",
             category: "operations",
@@ -45,10 +47,10 @@ export function createCapOverviewFeature(opts) {
         r.requires("tier-engine");
         r.requires("billing-foundation");
         r.queryHandler(createTenantCapsListQuery(opts.caps, listCaps));
-        r.queryHandler(createCapsUsageQuery(opts.caps));
+        r.queryHandler(createCapsUsageQuery(opts.caps, usageRoles));
         r.queryHandler(tenantOptionsQuery);
         r.screen(createTenantCapListScreen(opts.caps, listCaps, opts.tiers));
-        r.screen(myCapsScreen);
+        r.screen(createMyCapsScreen(usageRoles));
         r.screen(platformTenantCapsScreen);
         r.translations({ keys: CAP_OVERVIEW_I18N });
     });

package/dist/cap-overview/handlers/caps-usage.query.d.ts

@@ -1,3 +1,3 @@
 import { type QueryHandlerDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import type { CapSpec } from "../types.js";
-export declare function createCapsUsageQuery(caps: readonly CapSpec[]): QueryHandlerDefinition;
+export declare function createCapsUsageQuery(caps: readonly CapSpec[], usageRoles: readonly string[]): QueryHandlerDefinition;

package/dist/cap-overview/handlers/caps-usage.query.js

@@ -4,15 +4,14 @@ import { crossTenantOverrideDenied, defineQueryHandler, } from "@cosmicdrift/kum
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { tierAssignmentEntity } from "../../tier-engine/index.js";
-import { MY_CAPS_ACCESS_ROLES } from "../access.js";
 import { computeFraction, computeTone, computeUnclampedFraction } from "../usage-math.js";
 const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
-export function createCapsUsageQuery(caps) {
+export function createCapsUsageQuery(caps, usageRoles) {
     return defineQueryHandler({
         name: "caps:usage",
         description: "Returns the calling user's own tenant's configured caps with used amount, tier limit and utilisation fraction; use it to answer how close a tenant is to its quota (only SystemAdmin may target another tenant via tenantId).",
         schema: z.object({ tenantId: z.string().min(1).optional() }),
-        access: { roles: MY_CAPS_ACCESS_ROLES },
+        access: { roles: usageRoles },
         // COUNT/SUM/AVG are covered by TenantDb.count/TenantDb.aggregate; the grant
         // stays for app-owned CapSpec.usage() providers that still use unsafeRaw.
         escapeHatch: {
@@ -48,9 +47,12 @@ export function createCapsUsageQuery(caps) {
                 ? ctx.systemDb.assertRowsTenant(assignmentRows, "tenantId")
                 : assignmentRows;
             const tier = checkedRows[0]?.tier ?? "";
+            // Override path: limits must read the TARGET tenant's config, not the
+            // SystemAdmin caller's.
+            const config = override === undefined ? ctx.config : ctx.configFor?.(targetTenantId);
             const rows = await Promise.all(caps.map(async (cap) => {
                 const used = await cap.usage(db, targetTenantId);
-                const limit = await cap.limit(tier, { config: ctx.config });
+                const limit = await cap.limit(tier, { config });
                 const base = {
                     id: cap.id,
                     label: cap.label,