@cosmicdrift/kumiko-bundled-features 0.343.0 → 0.345.0

package/dist/billing-foundation/consumer-protection/consent-locale.js

@@ -1,7 +1,7 @@
 // @runtime client
 // Crypto-free so the browser panel can share the locale rule with the server.
 export const CONSENT_LOCALES = ["de", "en"];
-export const FALLBACK_CONSENT_LOCALE = "de";
+export const FALLBACK_CONSENT_LOCALE = "en";
 function isConsentLocale(value) {
     return CONSENT_LOCALES.some((locale) => locale === value);
 }

package/dist/billing-foundation/consumer-protection/issue-confirmation.js

@@ -1,8 +1,10 @@
 // § 312f contract confirmation: one mail per recorded consent, sent by the
 // system-only issue-contract-confirmation handler that the event-triggered
 // jobs (register-consent.ts) call.
-import { access, createSystemUser, } from "@cosmicdrift/kumiko-framework/engine";
+import { access, createSystemUser, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { createI18n } from "@cosmicdrift/kumiko-framework/i18n";
+import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
 import { requireTemplateResolver, TEXT_BLOCK_KIND } from "../../template-resolver/index.js";
 import { UserQueries } from "../../user/index.js";
@@ -22,7 +24,17 @@ export const issueContractConfirmationSchema = z
 const recipientRowSchema = z.object({
     email: z.string().min(1),
     isDeleted: z.boolean().optional(),
+    timezone: z.string().nullish(),
 });
+// createI18n returns the key itself for an unknown key.
+function translatedOrUndefined(translation, key) {
+    return translation === key ? undefined : translation;
+}
+function pickTimeZone(userZone, tenantZone) {
+    if (userZone && isValidIanaTimeZone(userZone))
+        return userZone;
+    return isValidIanaTimeZone(tenantZone) ? tenantZone : "UTC";
+}
 export function createIssueContractConfirmationHandler(options, consumerProtection) {
     return {
         name: "issue-contract-confirmation",
@@ -100,7 +112,7 @@ export function createIssueContractConfirmationHandler(options, consumerProtecti
             }
             const locale = resolveConsentLocale(consent.locale);
             const terms = await requireTemplateResolver(ctx, "billing-foundation").resolveTemplate({
-                tenantId,
+                tenantId: SYSTEM_TENANT_ID,
                 slug: consumerProtection.termsTextBlock,
                 kind: TEXT_BLOCK_KIND,
                 locale,
@@ -108,9 +120,19 @@ export function createIssueContractConfirmationHandler(options, consumerProtecti
             if (terms.version !== consent.termsTemplateVersion) {
                 ctx.log?.warn(`[billing-foundation:issue-contract-confirmation] terms text block changed since consent ${payload.consentId} (version ${consent.termsTemplateVersion} -> ${terms.version}); the mail carries the current text`);
             }
+            const i18n = createI18n(ctx.registry, { defaultLocale: "en" });
+            const tierLabel = consent.tier !== null && options.catalog
+                ? translatedOrUndefined(i18n.t(options.catalog.tierLabelKey(consent.tier), locale), options.catalog.tierLabelKey(consent.tier))
+                : undefined;
+            const itemLabel = consent.itemLabelKey !== undefined
+                ? translatedOrUndefined(i18n.t(consent.itemLabelKey, locale, consent.itemLabelParams), consent.itemLabelKey)
+                : undefined;
             const issuedAtIso = options.now().toString();
             const content = renderContractConfirmation({
                 consent,
+                timeZone: pickTimeZone(recipient.data.timezone, ctx.tz.tenant),
+                ...(tierLabel !== undefined && { tierLabel }),
+                ...(itemLabel !== undefined && { itemLabel }),
                 consentGivenAtIso: consentEvent.createdAt.toString(),
                 contractStartIso: issuedAtIso,
                 ...(payload.currentPeriodEndIso !== undefined && {

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

@@ -65,6 +65,8 @@ export declare const checkoutConsentRecordedPayloadSchema: z.ZodObject<{
     termsTemplateVersion: z.ZodNumber;
     locale: z.ZodString;
     actorUserId: z.ZodString;
+    itemLabelKey: z.ZodOptional<z.ZodString>;
+    itemLabelParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
 }, z.core.$strip>;
 export type CheckoutConsentRecordedPayload = z.infer<typeof checkoutConsentRecordedPayloadSchema>;
 export declare const CONTRACT_CONFIRMATION_ISSUED_EVENT_SHORT: "contract-confirmation-issued";

package/dist/billing-foundation/events.js

@@ -101,6 +101,8 @@ export const checkoutConsentRecordedPayloadSchema = z.object({
     termsTemplateVersion: z.number(),
     locale: z.string().min(2).max(35),
     actorUserId: z.string().min(1),
+    itemLabelKey: z.string().min(1).max(200).optional(),
+    itemLabelParams: z.record(z.string(), z.union([z.string().max(100), z.number()])).optional(),
 });
 // =============================================================================
 // contract-confirmation-issued — § 312f confirmation mail sent

package/dist/billing-foundation/handlers/billing-plans.query.d.ts

@@ -1,3 +1,3 @@
 import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import type { BillingPlanCatalog, ResolvedBillingFoundationOptions } from "../types.js";
+import { type BillingPlanCatalog, type ResolvedBillingFoundationOptions } from "../types.js";
 export declare function createBillingPlansQuery(options: ResolvedBillingFoundationOptions, catalog: BillingPlanCatalog): QueryHandlerDef;

package/dist/billing-foundation/handlers/billing-plans.query.js

@@ -5,6 +5,7 @@ import * as z from "zod";
 import { findCatalogProvider } from "../checkout-core.js";
 import { CONSENT_TEXTS, consentTextVersion, } from "../consumer-protection/consent-text.js";
 import { buildBillingPlans } from "../plan-catalog.js";
+import { isLegalLinkSet, } from "../types.js";
 const billingPlansSchema = z.object({}).strict();
 export function createBillingPlansQuery(options, catalog) {
     return {
@@ -25,12 +26,15 @@ export function createBillingPlansQuery(options, catalog) {
                         de: consentTextView("de"),
                         en: consentTextView("en"),
                     },
-                    legalLinks: consumerProtection.legalLinks,
+                    legalLinks: legalLinksPerLocale(consumerProtection.legalLinks),
                 },
             };
         },
     };
 }
+function legalLinksPerLocale(legalLinks) {
+    return isLegalLinkSet(legalLinks) ? { de: legalLinks, en: legalLinks } : legalLinks;
+}
 function consentTextView(locale) {
     const { earlyPerformance, withdrawalLoss } = CONSENT_TEXTS[locale];
     return { earlyPerformance, withdrawalLoss, consentTextVersion: consentTextVersion(locale) };

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

@@ -21,8 +21,9 @@
 // billing-foundation:write:switch-plan instead. Plan-driven callers should
 // prefer start-plan-checkout/switch-plan over calling this handler with a
 // hand-picked priceId.
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { findProviderPlugin, openCheckout } from "../checkout-core.js";
+import { assertCheckoutAllowed, openCheckout, startProviderCheckout, } from "../checkout-core.js";
 import { consentCheckoutFields, consentPayloadSchema, prepareConsent, recordConsent, } from "../consumer-protection/consent-gate.js";
 const createCheckoutSessionSchema = z.object({
     /** Welcher Provider — entityName eines registrierten subscription-
@@ -44,7 +45,7 @@ const createCheckoutSessionSchema = z.object({
 export function createCheckoutSessionHandler(options) {
     const consumerProtection = options.consumerProtection;
     const schema = consumerProtection
-        ? createCheckoutSessionSchema.extend({ consent: consentPayloadSchema.optional() })
+        ? createCheckoutSessionSchema.extend({ consent: consentPayloadSchema.optional() }).strict()
         : createCheckoutSessionSchema;
     return {
         name: "create-checkout-session",
@@ -56,27 +57,39 @@ export function createCheckoutSessionHandler(options) {
         handler: async (event, ctx) => {
             // @cast-boundary engine-payload — dispatcher-zod-validated payload
             const payload = event.payload;
-            const mode = payload.mode ?? "subscription";
-            const consent = consumerProtection
-                ? await prepareConsent(ctx, consumerProtection, payload.consent, mode)
-                : undefined;
-            const result = await openCheckout(ctx, { baseUrl: options.baseUrl, catalog: options.catalog, now: options.now }, {
+            const openOptions = { baseUrl: options.baseUrl, catalog: options.catalog, now: options.now };
+            const checkoutInput = {
                 providerName: payload.providerName,
                 priceId: payload.priceId,
                 successUrl: payload.successUrl,
                 cancelUrl: payload.cancelUrl,
                 ...(payload.providerCustomerId && { providerCustomerId: payload.providerCustomerId }),
                 ...(payload.mode && { mode: payload.mode }),
-                ...(consent && consentCheckoutFields(consent)),
-            });
-            if (consent) {
-                const plugin = findProviderPlugin(ctx, payload.providerName)?.plugin;
-                await recordConsent(ctx, consent, {
-                    tier: mode === "subscription" ? (plugin?.priceToTier?.[payload.priceId] ?? null) : null,
-                    priceId: payload.priceId,
-                    price: await lookupPrice(ctx, plugin, payload.priceId),
-                });
+            };
+            if (!consumerProtection) {
+                const result = await openCheckout(ctx, openOptions, checkoutInput);
+                return {
+                    isSuccess: true,
+                    data: { url: result.url, providerName: result.providerName },
+                };
             }
+            const mode = payload.mode ?? "subscription";
+            const plugin = await assertCheckoutAllowed(ctx, openOptions, checkoutInput);
+            const price = await lookupPrice(ctx, plugin, payload.priceId);
+            const orderItem = mode === "payment"
+                ? await consumerProtection.oneOffItemLabel?.(ctx, payload.priceId)
+                : undefined;
+            const consent = await prepareConsent(ctx, consumerProtection, payload.consent, mode);
+            const result = await startProviderCheckout(ctx, plugin, {
+                ...checkoutInput,
+                ...consentCheckoutFields(consent),
+            });
+            await recordConsent(ctx, consent, {
+                tier: mode === "subscription" ? (plugin.priceToTier?.[payload.priceId] ?? null) : null,
+                priceId: payload.priceId,
+                price,
+                ...(orderItem && { orderItem }),
+            });
             return {
                 isSuccess: true,
                 data: { url: result.url, providerName: result.providerName },
@@ -84,16 +97,25 @@ export function createCheckoutSessionHandler(options) {
         },
     };
 }
-// A failed price lookup must not lose a consent the buyer already gave at the
-// provider, so it degrades to null price fields.
+// The price is part of the consent record, so it must be known before the
+// buyer is sent to the provider.
 async function lookupPrice(ctx, plugin, priceId) {
-    if (!plugin?.retrievePrices)
-        return null;
+    let price;
     try {
-        const prices = await plugin.retrievePrices(ctx, [priceId]);
-        return prices.find((p) => p.priceId === priceId) ?? null;
+        const prices = (await plugin.retrievePrices?.(ctx, [priceId])) ?? [];
+        price = prices.find((p) => p.priceId === priceId);
     }
-    catch {
-        return null;
+    catch (cause) {
+        throw priceUnavailable(priceId, cause);
     }
+    if (!price)
+        throw priceUnavailable(priceId);
+    return price;
+}
+function priceUnavailable(priceId, cause) {
+    return new UnprocessableError("price_unavailable", {
+        i18nKey: "billing-foundation.errors.priceUnavailable",
+        message: `billing-foundation: no live price resolved for priceId "${priceId}"`,
+        ...(cause instanceof Error && { cause }),
+    });
 }

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

@@ -2,6 +2,8 @@ export { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id.js";
 export { type BillingInfo, type BillingInfoQueryDeps, createBillingInfoQueryConfig, } from "./billing-info-query.js";
 export { isBillingEnabled, type ResolvedProvider, resolveProviderPlugin, } from "./checkout-core.js";
 export { BILLING_FOUNDATION_FEATURE, BILLING_PLANS_PANEL_COMPONENT, BILLING_PLANS_SCREEN_ID, type BillingEventKind, BillingEventKinds, type BillingPlanAction, BillingPlanActions, DEFAULT_PURCHASE_ROLES, isSwitchableSubscriptionStatus, isTerminalSubscriptionStatus, parseProviderConsentId, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, SubscriptionCancelTimings, type SubscriptionEventType, SubscriptionEventTypes, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, type SubscriptionStatus, SubscriptionStatuses, } from "./constants.js";
+export { type ConsentPayload, consentPayloadSchema, type OrderItem, } from "./consumer-protection/consent-gate.js";
+export { CONSENT_LOCALES, type ConsentLocale, resolveConsentLocale, } from "./consumer-protection/consent-locale.js";
 export { type ContractTerminationRoutesOptions, createContractTerminationRoutes, } from "./consumer-protection/termination-pages.js";
 export { paymentEntity, subscriptionEntity } from "./entities.js";
 export { INVOICE_PAID_EVENT_QN, INVOICE_PAID_EVENT_SHORT, INVOICE_PAYMENT_FAILED_EVENT_QN, INVOICE_PAYMENT_FAILED_EVENT_SHORT, PAYMENT_AGGREGATE_TYPE, PAYMENT_RECEIVED_EVENT_QN, PAYMENT_RECEIVED_EVENT_SHORT, type PaymentEventHeaders, type PaymentEventPayload, paymentEventPayloadSchema, SUBSCRIPTION_AGGREGATE_TYPE, SUBSCRIPTION_CANCELED_EVENT_QN, SUBSCRIPTION_CANCELED_EVENT_SHORT, SUBSCRIPTION_CREATED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_SHORT, SUBSCRIPTION_UPDATED_EVENT_QN, SUBSCRIPTION_UPDATED_EVENT_SHORT, type SubscriptionEventHeaders, type SubscriptionEventPayload, subscriptionEventPayloadSchema, } from "./events.js";
@@ -10,5 +12,5 @@ export { getSubscriptionForTenant, type SubscriptionView } from "./get-subscript
 export { paymentsProjectionTable, subscriptionsProjectionTable } from "./projection.js";
 export { billingPlansPanel, createBillingPlansScreen } from "./screens.js";
 export { createSubscriptionTierSync, effectiveTierFromSubscription, SUBSCRIPTION_WEBHOOK_PATH, type SubscriptionTierSyncDeps, } from "./subscription-tier-sync.js";
-export { type BillingFoundationOptions, type BillingPlanBenefit, type BillingPlanCatalog, type BillingPlanPrice, type BillingPlansResult, type BillingPlanView, type ConsumerProtectionOptions, KNOWN_RECURRING_INTERVALS, type PaymentEvent, type ProviderPrice, type ProviderSubscriptionSnapshot, type RecurringInterval, type SubscriptionEvent, type SubscriptionProviderPlugin, } from "./types.js";
+export { type BillingFoundationOptions, type BillingPlanBenefit, type BillingPlanCatalog, type BillingPlanPrice, type BillingPlansResult, type BillingPlanView, type ConsumerProtectionOptions, KNOWN_RECURRING_INTERVALS, type LegalLinkSet, type PaymentEvent, type ProviderPrice, type ProviderSubscriptionSnapshot, type RecurringInterval, type SubscriptionEvent, type SubscriptionProviderPlugin, } from "./types.js";
 export { createSubscriptionWebhookRoute, type SubscriptionWebhookRouteOptions, } from "./webhook-handler.js";

package/dist/billing-foundation/index.js

@@ -3,6 +3,8 @@ export { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id.js";
 export { createBillingInfoQueryConfig, } from "./billing-info-query.js";
 export { isBillingEnabled, resolveProviderPlugin, } from "./checkout-core.js";
 export { BILLING_FOUNDATION_FEATURE, BILLING_PLANS_PANEL_COMPONENT, BILLING_PLANS_SCREEN_ID, BillingEventKinds, BillingPlanActions, DEFAULT_PURCHASE_ROLES, isSwitchableSubscriptionStatus, isTerminalSubscriptionStatus, parseProviderConsentId, SUBSCRIPTION_PROVIDER_EXTENSION, SubscriptionCancelTimings, SubscriptionEventTypes, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "./constants.js";
+export { consentPayloadSchema, } from "./consumer-protection/consent-gate.js";
+export { CONSENT_LOCALES, resolveConsentLocale, } from "./consumer-protection/consent-locale.js";
 export { createContractTerminationRoutes, } from "./consumer-protection/termination-pages.js";
 export { paymentEntity, subscriptionEntity } from "./entities.js";
 export { INVOICE_PAID_EVENT_QN, INVOICE_PAID_EVENT_SHORT, INVOICE_PAYMENT_FAILED_EVENT_QN, INVOICE_PAYMENT_FAILED_EVENT_SHORT, PAYMENT_AGGREGATE_TYPE, PAYMENT_RECEIVED_EVENT_QN, PAYMENT_RECEIVED_EVENT_SHORT, paymentEventPayloadSchema, SUBSCRIPTION_AGGREGATE_TYPE, SUBSCRIPTION_CANCELED_EVENT_QN, SUBSCRIPTION_CANCELED_EVENT_SHORT, SUBSCRIPTION_CREATED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_SHORT, SUBSCRIPTION_UPDATED_EVENT_QN, SUBSCRIPTION_UPDATED_EVENT_SHORT, subscriptionEventPayloadSchema, } from "./events.js";

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

@@ -3,6 +3,8 @@ 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 SubscriptionCancelTiming, type SubscriptionEventType, type SubscriptionStatus, type TerminationScope } from "./constants.js";
+import type { OrderItem } from "./consumer-protection/consent-gate.js";
+import type { ConsentLocale } from "./consumer-protection/consent-locale.js";
 export type SubscriptionEvent = {
     /** Discriminator against PaymentEvent. Optional (instead of required) so
      *  existing plugins like subscription-mollie, which don't set this field,
@@ -279,6 +281,12 @@ export type BillingPlanCatalog<TTier extends string = string> = {
     /** Defaults to the only registered provider exposing `priceToTier`. */
     readonly providerName?: string;
 };
+export type LegalLinkSet = {
+    readonly terms: string;
+    readonly withdrawal: string;
+    readonly privacy: string;
+};
+export declare function isLegalLinkSet(links: LegalLinkSet | Readonly<Record<ConsentLocale, LegalLinkSet>>): links is LegalLinkSet;
 /** 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. */
@@ -294,12 +302,13 @@ export type ConsumerProtectionOptions = {
      *  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;
-    };
+    /** Names the item of a one-off payment (mode "payment") for the consent record
+     *  and the confirmation mail; the label key is resolved through the registry
+     *  i18n, so it must be qualified with the registering feature. */
+    readonly oneOffItemLabel?: (ctx: HandlerContext, priceId: string) => Promise<OrderItem | undefined>;
+    /** Root-relative paths or absolute https URLs. One set for every locale, or
+     *  one set per consent locale (`de` and `en` required). */
+    readonly legalLinks: LegalLinkSet | Readonly<Record<ConsentLocale, LegalLinkSet>>;
 };
 export type BillingFoundationOptions<TTier extends string = string> = {
     /** Absolute http(s) URL. Its origin is the only redirect origin
@@ -361,7 +370,7 @@ export type BillingPlansResult = {
             readonly withdrawalLoss: string;
             readonly consentTextVersion: string;
         }>>;
-        readonly legalLinks: ConsumerProtectionOptions["legalLinks"];
+        readonly legalLinks: Readonly<Record<ConsentLocale, LegalLinkSet>>;
     };
 };
 declare module "@cosmicdrift/kumiko-framework/engine" {

package/dist/billing-foundation/types.js

@@ -30,3 +30,6 @@ import { SUBSCRIPTION_PROVIDER_EXTENSION, } from "./constants.js";
 // =============================================================================
 // 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"];
+export function isLegalLinkSet(links) {
+    return "terms" in links;
+}

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

@@ -1,4 +1,4 @@
-import type { BillingFoundationOptions } from "./types.js";
+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

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

@@ -4,6 +4,8 @@
 // re-exported from index.ts.
 import * as z from "zod";
 import { isTerminationScope, TERMINATION_SCOPES } from "./constants.js";
+import { CONSENT_LOCALES } from "./consumer-protection/consent-locale.js";
+import { isLegalLinkSet, } from "./types.js";
 function isRootRelativePath(path) {
     return path.startsWith("/") && !path.startsWith("//");
 }
@@ -29,12 +31,32 @@ function validateConsumerProtection(cp) {
     if (!z.email().safeParse(cp.operatorEmail).success) {
         throw new Error(`createBillingFoundationFeature: consumerProtection.operatorEmail "${cp.operatorEmail}" is not a valid email address.`);
     }
+    if (cp.oneOffItemLabel !== undefined && typeof cp.oneOffItemLabel !== "function") {
+        throw new Error("createBillingFoundationFeature: consumerProtection.oneOffItemLabel must be a function.");
+    }
     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 (isLegalLinkSet(cp.legalLinks)) {
+        validateLegalLinkSet(cp.legalLinks, "legalLinks");
+    }
+    else {
+        validatePerLocaleLegalLinks(cp.legalLinks);
+    }
+}
+function validatePerLocaleLegalLinks(legalLinks) {
+    for (const locale of CONSENT_LOCALES) {
+        const set = legalLinks[locale];
+        if (!set) {
+            throw new Error(`createBillingFoundationFeature: consumerProtection.legalLinks needs a "${locale}" entry when given per locale.`);
+        }
+        validateLegalLinkSet(set, `legalLinks.${locale}`);
+    }
+}
+function validateLegalLinkSet(set, path) {
+    for (const [key, link] of Object.entries(set)) {
         if (!isRootRelativeOrHttpsUrl(link)) {
-            throw new Error(`createBillingFoundationFeature: consumerProtection.legalLinks.${key} "${link}" must be a root-relative path ("/..." not "//") or an absolute https URL.`);
+            throw new Error(`createBillingFoundationFeature: consumerProtection.${path}.${key} "${link}" must be a root-relative path ("/..." not "//") or an absolute https URL.`);
         }
     }
 }

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

@@ -189,7 +189,7 @@ export function BillingPlansPanel(_props) {
                         date: toInstant(result.subscription.cancelAt).toLocaleString(locale, {
                             dateStyle: "medium",
                         }),
-                    }), " ", 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 &&
+                    }), " ", t("billing-foundation.plans.switchRequiresReactivation")] })), consumerProtection !== undefined && canManage && result.subscription?.cancelAt == null && (_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)

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

@@ -14,7 +14,7 @@ const TERMINATION_KINDS = ["ordinary", "extraordinary"];
 export function CancelContractDialog({ open, onOpenChange, onTerminated, }) {
     const t = useTranslation();
     const locale = useLocale().locale();
-    const { Modal, Heading, Text, Field, Input, Button, Banner } = usePrimitives();
+    const { Modal, Text, Field, Input, Button, Banner } = usePrimitives();
     const terminate = useMutation(SubscriptionFoundationHandlers.terminateContract);
     const [step, setStep] = useState("form");
     const [declarationType, setDeclarationType] = useState("termination");
@@ -38,7 +38,7 @@ export function CancelContractDialog({ open, onOpenChange, 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) => ({
+    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: [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) => ({

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

@@ -16,7 +16,7 @@ export type CheckoutConsentDialogProps = {
     readonly price: {
         readonly amount: string;
         readonly renewalKey?: string;
-        readonly count: string;
+        readonly count?: string;
     };
     readonly consumerProtection: ConsumerProtectionView;
     readonly onOrder: (consent: CheckoutConsentPayload) => Promise<WriteResult<{

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

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, 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";
@@ -7,14 +7,14 @@ export const CONSENT_TEXT_OUTDATED_CODE = "consent_text_outdated";
 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 { Modal, 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;
+    const legalLinks = consumerProtection.legalLinks[consentLocale];
     async function order() {
         setSubmitting(true);
         setErrorText(null);
@@ -34,5 +34,5 @@ export function CheckoutConsentDialog({ open, onOpenChange, planName, price, con
             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") })] })] }) }));
+    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: [_jsxs("div", { className: "flex flex-col gap-1", "data-testid": "checkout-consent-summary", children: [_jsxs(Text, { children: [planName, " \u2014 ", price.amount] }), price.renewalKey !== undefined && (_jsxs(_Fragment, { children: [_jsx(Text, { variant: "muted", children: t(price.renewalKey, price.count !== undefined ? { count: price.count } : undefined) }), _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/web/index.d.ts

@@ -1,4 +1,6 @@
 export { BILLING_PLANS_SCREEN_ID, type BillingPlanAction, BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, type SubscriptionStatus, SubscriptionStatuses, } from "../constants.js";
-export type { BillingPlanBenefit, BillingPlanCatalog, BillingPlansResult, BillingPlanView, } from "../types.js";
+export { CONSENT_LOCALES, type ConsentLocale, resolveConsentLocale, } from "../consumer-protection/consent-locale.js";
+export type { BillingPlanBenefit, BillingPlanCatalog, BillingPlansResult, BillingPlanView, LegalLinkSet, } from "../types.js";
 export { BillingPlansPanel } from "./billing-plans-panel.js";
+export { CheckoutConsentDialog, type CheckoutConsentDialogProps, type CheckoutConsentPayload, CONSENT_TEXT_OUTDATED_CODE, } from "./checkout-consent-dialog.js";
 export { type BillingFoundationClientOptions, billingFoundationClient } from "./client-plugin.js";

package/dist/billing-foundation/web/index.js

@@ -4,5 +4,7 @@
 // the server side (createBillingFoundationFeature) lives under
 // `@cosmicdrift/kumiko-bundled-features/billing-foundation` and has no React deps.
 export { BILLING_PLANS_SCREEN_ID, BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "../constants.js";
+export { CONSENT_LOCALES, resolveConsentLocale, } from "../consumer-protection/consent-locale.js";
 export { BillingPlansPanel } from "./billing-plans-panel.js";
+export { CheckoutConsentDialog, CONSENT_TEXT_OUTDATED_CODE, } from "./checkout-consent-dialog.js";
 export { billingFoundationClient } from "./client-plugin.js";

package/dist/legal-pages/constants.d.ts

@@ -4,6 +4,8 @@ export type LegalPageRoute = {
     readonly slug: string;
     readonly lang: string;
     readonly titleFallback: string;
+    /** Prepend the page title as `<h1>` to the rendered body. Default false. */
+    readonly titleHeading?: boolean;
 };
 export type LegalRequiredBlock = {
     readonly slug: string;

package/dist/legal-pages/feature.js

@@ -1,5 +1,6 @@
 import { computeRevisionEtag, etagMatches } from "@cosmicdrift/kumiko-framework/api";
 import { defineFeature, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
+import { escapeHtml } from "@cosmicdrift/kumiko-headless";
 import { cachedSecurePageResponse, redirectToCanonicalPath, slashVariantOf, } from "../page-render/index.js";
 import { LEGAL_REQUIRED_BLOCKS, LEGAL_ROUTES, } from "./constants.js";
 import { runLegalPagesBootCheck } from "./lib/boot-check.js";
@@ -85,9 +86,13 @@ export function createLegalPagesFeature(opts = {}) {
                             extra,
                         });
                     }
+                    const title = data.title || route.titleFallback;
+                    const renderedBody = renderMarkdownToHtml(data.content);
                     const html = wrapLayout({
-                        title: data.title || route.titleFallback,
-                        bodyHtml: renderMarkdownToHtml(data.content),
+                        title,
+                        bodyHtml: route.titleHeading
+                            ? `<h1>${escapeHtml(title)}</h1>${renderedBody}`
+                            : renderedBody,
                         lang: route.lang,
                         slug: route.slug,
                     });

package/dist/renderer-simple/simple-renderer.js

@@ -1,4 +1,5 @@
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { renderSafeMarkdown } from "../page-render/index.js";
 const DEFAULT_PRIMARY_COLOR = "#2563eb";
 const HEX_COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
 function isHttpUrl(value) {
@@ -95,6 +96,13 @@ function renderSection(section, primaryColor) {
     if ("text" in section) {
         return `<p style="margin:0 0 16px;color:#333;font-size:14px;line-height:1.5">${escapeHtml(section.text)}</p>`;
     }
+    if ("heading" in section) {
+        return `<h2 style="margin:24px 0 12px;color:#111;font-size:16px;font-weight:600">${escapeHtml(section.heading)}</h2>`;
+    }
+    if ("markdown" in section) {
+        const markdownHtml = renderSafeMarkdown(section.markdown);
+        return `<div style="color:#333;font-size:14px;line-height:1.5">${markdownHtml}</div>`;
+    }
     if ("button" in section) {
         return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:${escapeHtmlAttr(primaryColor)};color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
     }

package/dist/step-dispatcher/feature.js

@@ -144,7 +144,7 @@ function buildDispatchSpec(payload, fields) {
 }
 export function createStepDispatcherFeature() {
     return defineFeature("step-dispatcher", (r) => {
-        r.describe("Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`.");
+        r.describe("Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.");
         r.secretNamespace("webhook-auth", WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS);
         r.uiHints({
             displayLabel: "Step Dispatcher · Deferred Side-Effects",
@@ -206,6 +206,7 @@ export function createStepDispatcherFeature() {
                             tenantId: event.tenantId,
                             userId: event.metadata.userId || SYSTEM_USER_ID,
                             secrets: ctx.secrets,
+                            idempotencyKey: event.aggregateId,
                         })
                         : await performMailDispatch(dispatchSpec.spec);
                     if (result.ok) {

package/dist/step-dispatcher/webhook-runner.d.ts

@@ -45,5 +45,7 @@ export type WebhookDispatchDeps = {
     readonly tenantId: TenantId;
     readonly userId: string;
     readonly secrets: SecretsContext | undefined;
+    readonly idempotencyKey: string;
 };
+export declare const WEBHOOK_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
 export declare function performWebhookDispatch(spec: WebhookSpec, deps: WebhookDispatchDeps): Promise<WebhookDispatchResult>;

package/dist/step-dispatcher/webhook-runner.js

@@ -83,8 +83,15 @@ export function setWebhookFetch(fn) {
 // tenant-chosen name, but the error still reaches the tenant via the
 // dispatch-failed event, so it stays generic.
 const WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR = "webhook auth secret is not available";
+export const WEBHOOK_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
+function hasIdempotencyKeyHeader(headers) {
+    return Object.keys(headers).some((name) => name.toLowerCase() === WEBHOOK_IDEMPOTENCY_KEY_HEADER);
+}
 async function buildWebhookHeaders(spec, deps) {
     const headers = { "content-type": "application/json", ...spec.headers };
+    if (!hasIdempotencyKeyHeader(headers)) {
+        headers[WEBHOOK_IDEMPOTENCY_KEY_HEADER] = deps.idempotencyKey;
+    }
     if (!spec.auth)
         return { ok: true, headers };
     if (!deps.secrets)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.343.0",
+  "version": "0.345.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -503,12 +503,12 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.343.0",
-    "@cosmicdrift/kumiko-framework": "0.343.0",
-    "@cosmicdrift/kumiko-headless": "0.343.0",
-    "@cosmicdrift/kumiko-renderer": "0.343.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.343.0",
-    "@cosmicdrift/kumiko-types": "0.343.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.345.0",
+    "@cosmicdrift/kumiko-framework": "0.345.0",
+    "@cosmicdrift/kumiko-headless": "0.345.0",
+    "@cosmicdrift/kumiko-renderer": "0.345.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.345.0",
+    "@cosmicdrift/kumiko-types": "0.345.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -1025,8 +1025,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.343.0",
-    "@cosmicdrift/kumiko-locale-es": "0.343.0",
+    "@cosmicdrift/kumiko-locale-de": "0.345.0",
+    "@cosmicdrift/kumiko-locale-es": "0.345.0",
     "jsqr": "^1.4.0"
   }
 }