@cosmicdrift/kumiko-bundled-features 0.337.1 → 0.339.0

package/dist/billing-foundation/events.js

@@ -11,6 +11,7 @@
 // type ohne payload-discriminator.
 import * as z from "zod";
 import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./constants.js";
+import { CONSENT_LOCALES } from "./consumer-protection/consent-locale.js";
 // Aggregate-type für den event-store. Eine subscription pro Tenant ist
 // ein stream; der subscriptionAggregateId-helper liefert die stream-id.
 export const SUBSCRIPTION_AGGREGATE_TYPE = "subscription";
@@ -36,8 +37,8 @@ const statusEnum = z.enum([
 ]);
 // Common payload — alle 5 events tragen denselben subscription-state-
 // snapshot. Event-type tagged was passiert ist, payload den state-after.
-// Provider-spezifischer rawPayload ist in metadata.rawPayload (nicht in
-// payload — payload ist domain-clean, metadata ist provider-truth).
+// The raw provider event is deliberately not stored: it carries plaintext
+// PII and event headers are not crypto-shreddable.
 export const subscriptionEventPayloadSchema = z.object({
     providerName: z.string().min(1).max(50),
     // 1000, not 200: these two are `tenantOwned: true` on the entity (see
@@ -54,6 +55,7 @@ export const subscriptionEventPayloadSchema = z.object({
     // upcaster. null = the subscription renews; undefined = the provider
     // doesn't report cancelAt at all — projection.ts tells the two apart.
     cancelAtIso: z.string().min(1).nullable().optional(),
+    consentId: z.string().min(1).max(100).optional(),
 });
 // =============================================================================
 // payment-received — one-off-payments (checkout mode "payment")
@@ -74,4 +76,88 @@ export const paymentEventPayloadSchema = z.object({
     // subscriptionEventPayloadSchema's same rationale.
     providerCustomerId: z.string().min(1).max(1000),
     priceId: z.string().min(1).max(200),
+    consentId: z.string().min(1).max(100).optional(),
+});
+// =============================================================================
+// checkout-consent-recorded — consumer-protection consent
+// =============================================================================
+//
+// Appended onto the subscription- or payment-stream (by checkout mode) after
+// the provider handed out the checkout URL. No projection applies it. Carries
+// no email or IP: the consenting user is identified by `actorUserId` only.
+export const CHECKOUT_CONSENT_RECORDED_EVENT_SHORT = "checkout-consent-recorded";
+export const CHECKOUT_CONSENT_RECORDED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${CHECKOUT_CONSENT_RECORDED_EVENT_SHORT}`;
+export const checkoutConsentRecordedPayloadSchema = z.object({
+    consentId: z.string().min(1).max(100),
+    mode: z.enum(["subscription", "payment"]),
+    tier: z.string().min(1).max(50).nullable(),
+    priceId: z.string().min(1).max(200),
+    unitAmount: z.number().nullable(),
+    currency: z.string().nullable(),
+    interval: z.string().nullable(),
+    intervalCount: z.number().nullable(),
+    consentTextVersion: z.string().min(1).max(64),
+    termsHash: z.string().length(64),
+    termsTemplateVersion: z.number(),
+    locale: z.string().min(2).max(35),
+    actorUserId: z.string().min(1),
+});
+// =============================================================================
+// contract-confirmation-issued — § 312f confirmation mail sent
+// =============================================================================
+//
+// Appended onto the stream that carries the consent, BEFORE the mail is
+// handed to delivery: the append is the optimistic-concurrency guard that
+// keeps a concurrent or replayed run from sending a second mail.
+export const CONTRACT_CONFIRMATION_ISSUED_EVENT_SHORT = "contract-confirmation-issued";
+export const CONTRACT_CONFIRMATION_ISSUED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${CONTRACT_CONFIRMATION_ISSUED_EVENT_SHORT}`;
+export const contractConfirmationIssuedPayloadSchema = z.object({
+    consentId: z.string().min(1).max(100),
+    issuedAtIso: z.string().min(1),
+    locale: z.string().min(2).max(35),
+    termsTemplateVersion: z.number(),
+});
+// =============================================================================
+// contract-termination-requested / -unmatched — § 312k cancellation
+// =============================================================================
+//
+// Payloads carry no name, email or reason: those only travel in the mails.
+// `requested` goes onto the tenant's subscription stream; `unmatched` onto a
+// system-tenant stream of its own, keyed by the request id.
+export const CONTRACT_TERMINATION_DECLARATION_TYPES = ["termination", "withdrawal"];
+export const CONTRACT_TERMINATION_KINDS = ["ordinary", "extraordinary"];
+export const CONTRACT_TERMINATION_CHANNELS = ["public", "account"];
+export const PROVIDER_CANCEL_OUTCOMES = ["period-end", "immediately", "none"];
+export const CONTRACT_TERMINATION_REQUESTED_EVENT_SHORT = "contract-termination-requested";
+export const CONTRACT_TERMINATION_REQUESTED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${CONTRACT_TERMINATION_REQUESTED_EVENT_SHORT}`;
+export const contractTerminationRequestedPayloadSchema = z.object({
+    requestId: z.string().min(1).max(100),
+    declarationType: z.enum(CONTRACT_TERMINATION_DECLARATION_TYPES),
+    terminationKind: z.enum(CONTRACT_TERMINATION_KINDS),
+    channel: z.enum(CONTRACT_TERMINATION_CHANNELS),
+    receivedAtIso: z.string().min(1),
+    effectiveAtIso: z.string().min(1).nullable(),
+    providerCancel: z.enum(PROVIDER_CANCEL_OUTCOMES),
+});
+// A public declaration matched to this tenant. The provider cancel runs in a
+// job triggered by this event, so the request itself only looks up and appends.
+export const CONTRACT_TERMINATION_DECLARED_EVENT_SHORT = "contract-termination-declared";
+export const CONTRACT_TERMINATION_DECLARED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${CONTRACT_TERMINATION_DECLARED_EVENT_SHORT}`;
+export const contractTerminationDeclaredPayloadSchema = z.object({
+    requestId: z.string().min(1).max(100),
+    declarationType: z.enum(CONTRACT_TERMINATION_DECLARATION_TYPES),
+    terminationKind: z.enum(CONTRACT_TERMINATION_KINDS),
+    receivedAtIso: z.string().min(1),
+    locale: z.enum(CONSENT_LOCALES),
+});
+export const CONTRACT_TERMINATION_UNMATCHED_AGGREGATE_TYPE = "contract-termination-unmatched";
+export const CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT = "contract-termination-unmatched";
+export const CONTRACT_TERMINATION_UNMATCHED_EVENT_QN = `${BILLING_FOUNDATION_FEATURE}:event:${CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT}`;
+export const contractTerminationUnmatchedPayloadSchema = z.object({
+    requestId: z.string().min(1).max(100),
+    declarationType: z.enum(CONTRACT_TERMINATION_DECLARATION_TYPES),
+    terminationKind: z.enum(CONTRACT_TERMINATION_KINDS),
+    channel: z.literal("public"),
+    receivedAtIso: z.string().min(1),
+    matchResult: z.enum(["none", "ambiguous"]),
 });

package/dist/billing-foundation/feature.js

@@ -55,13 +55,14 @@ import { defineFeature, EXT_TENANT_DATA, } from "@cosmicdrift/kumiko-framework/e
 // resolves against, see event-store.ts's own import comment (#1438).
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 import { BILLING_FOUNDATION_FEATURE, SUBSCRIPTION_PROVIDER_EXTENSION, SubscriptionFoundationHandlers, } from "./constants.js";
+import { registerConsumerProtection } from "./consumer-protection/register-consent.js";
 import { paymentEntity, subscriptionEntity } from "./entities.js";
 import { 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";
 import { createBillingPlansQuery } from "./handlers/billing-plans.query.js";
 import { createCheckoutSessionHandler } from "./handlers/create-checkout-session.write.js";
 import { createPortalSessionHandler } from "./handlers/create-portal-session.write.js";
 import { listSubscriptionsQuery } from "./handlers/list-subscriptions.query.js";
-import { processEventHandler } from "./handlers/process-event.write.js";
+import { createProcessEventHandler } from "./handlers/process-event.write.js";
 import { processPaymentEventHandler } from "./handlers/process-payment-event.write.js";
 import { createStartPlanCheckoutHandler } from "./handlers/start-plan-checkout.write.js";
 import { createSwitchPlanHandler } from "./handlers/switch-plan.write.js";
@@ -163,7 +164,7 @@ export function createBillingFoundationFeature(options = {}) {
         //   - create-checkout-session: bare priceId-driven checkout (hardened,
         //     see checkout-core)
         //   - create-portal-session: Tenant-Admin "Manage Subscription"-flow
-        r.writeHandler(processEventHandler);
+        r.writeHandler(createProcessEventHandler(widened.now));
         r.writeHandler(createCheckoutSessionHandler(widened));
         r.writeHandler(createPortalSessionHandler(widened));
         //   - process-payment-event: programmatic entry-point from the webhook-
@@ -182,6 +183,9 @@ export function createBillingFoundationFeature(options = {}) {
         // fire from create-checkout-session even without a catalog — register
         // unconditionally rather than splitting the i18n surface by option.
         r.translations({ keys: BILLING_FOUNDATION_I18N });
+        if (widened.consumerProtection) {
+            registerConsumerProtection(r, widened, widened.consumerProtection);
+        }
         if (widened.catalog) {
             const { catalog } = widened;
             r.queryHandler(createBillingPlansQuery(widened, catalog));

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

@@ -3,6 +3,7 @@
 // when `createBillingFoundationFeature` gets a `catalog`.
 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";
 const billingPlansSchema = z.object({}).strict();
 export function createBillingPlansQuery(options, catalog) {
@@ -13,7 +14,24 @@ export function createBillingPlansQuery(options, catalog) {
         access: { roles: catalog.viewRoles },
         handler: async (_query, ctx) => {
             const found = findCatalogProvider(ctx, catalog);
-            return buildBillingPlans(ctx, found?.plugin ?? null, catalog, options.now);
+            const result = await buildBillingPlans(ctx, found?.plugin ?? null, catalog, options.now);
+            const { consumerProtection } = options;
+            if (!consumerProtection)
+                return result;
+            return {
+                ...result,
+                consumerProtection: {
+                    consentTexts: {
+                        de: consentTextView("de"),
+                        en: consentTextView("en"),
+                    },
+                    legalLinks: consumerProtection.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

@@ -22,7 +22,8 @@
 // prefer start-plan-checkout/switch-plan over calling this handler with a
 // hand-picked priceId.
 import * as z from "zod";
-import { openCheckout } from "../checkout-core.js";
+import { findProviderPlugin, openCheckout } 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-
      *  Plugins ("stripe" / "paypal" / ...). */
@@ -41,16 +42,24 @@ const createCheckoutSessionSchema = z.object({
     mode: z.enum(["subscription", "payment"]).optional(),
 });
 export function createCheckoutSessionHandler(options) {
+    const consumerProtection = options.consumerProtection;
+    const schema = consumerProtection
+        ? createCheckoutSessionSchema.extend({ consent: consentPayloadSchema.optional() })
+        : createCheckoutSessionSchema;
     return {
         name: "create-checkout-session",
         description: 'Opens a hosted checkout page at the named subscription provider for the caller\'s tenant and returns its URL; use it when a tenant admin wants to make a one-off payment (mode: "payment") or subscribe to a price already known to be valid. Redirect URLs must share the configured baseUrl origin. Prefer billing-foundation:write:start-plan-checkout / :switch-plan for catalog-driven plan purchases.',
-        schema: createCheckoutSessionSchema,
+        schema,
         // Tenant-Admin-only — the tenant must deliberately configure its own
         // subscription. SystemAdmin as a fallback for operator-initiated flows.
         access: { roles: ["TenantAdmin", "SystemAdmin"] },
         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 }, {
                 providerName: payload.providerName,
                 priceId: payload.priceId,
@@ -58,7 +67,16 @@ export function createCheckoutSessionHandler(options) {
                 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),
+                });
+            }
             return {
                 isSuccess: true,
                 data: { url: result.url, providerName: result.providerName },
@@ -66,3 +84,16 @@ 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.
+async function lookupPrice(ctx, plugin, priceId) {
+    if (!plugin?.retrievePrices)
+        return null;
+    try {
+        const prices = await plugin.retrievePrices(ctx, [priceId]);
+        return prices.find((p) => p.priceId === priceId) ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/billing-foundation/handlers/process-event.write.d.ts

@@ -22,11 +22,11 @@ export declare const processEventSchema: z.ZodObject<{
     tier: z.ZodString;
     currentPeriodEndIso: z.ZodString;
     cancelAtIso: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    rawPayload: z.ZodString;
+    consentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ProcessEventPayload = z.infer<typeof processEventSchema>;
 export declare function appendSubscriptionEvent(ctx: HandlerContext, tenantId: string, payload: ProcessEventPayload): Promise<{
     readonly duplicate: boolean;
     readonly subscriptionAggregateId: string;
 }>;
-export declare const processEventHandler: WriteHandlerDef;
+export declare function createProcessEventHandler(now: () => Temporal.Instant): WriteHandlerDef;

package/dist/billing-foundation/handlers/process-event.write.js

@@ -14,9 +14,10 @@
 import { configuredPiiSubjectKms, encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id.js";
-import { SubscriptionEventTypes, SubscriptionStatuses } from "../constants.js";
+import { isSubscriptionBlockingCheckout, SubscriptionEventTypes, SubscriptionStatuses, } from "../constants.js";
 import { SUBSCRIPTION_PII_FIELDS, subscriptionEntity } from "../entities.js";
 import { INVOICE_PAID_EVENT_QN, INVOICE_PAYMENT_FAILED_EVENT_QN, SUBSCRIPTION_AGGREGATE_TYPE, SUBSCRIPTION_CANCELED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_QN, SUBSCRIPTION_UPDATED_EVENT_QN, } from "../events.js";
+import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
 // =============================================================================
 // Input-Schema = der normalisierte SubscriptionEvent (ohne tenantId, der
 // kommt aus event.user.tenantId — der webhook-handler setzt den
@@ -46,7 +47,7 @@ export const processEventSchema = z.object({
     tier: z.string().min(1).max(50),
     currentPeriodEndIso: z.string().min(1),
     cancelAtIso: z.string().min(1).nullable().optional(),
-    rawPayload: z.string().min(1),
+    consentId: z.string().min(1).max(100).optional(),
 });
 // Map normalized SubscriptionEventType → fully-qualified ES event-name.
 const NORMALIZED_TO_ES_EVENT = {
@@ -129,11 +130,11 @@ export async function appendSubscriptionEvent(ctx, tenantId, payload) {
         tier: payload.tier,
         currentPeriodEndIso: payload.currentPeriodEndIso,
         ...(payload.cancelAtIso !== undefined && { cancelAtIso: payload.cancelAtIso }),
+        ...(payload.consentId !== undefined && { consentId: payload.consentId }),
     };
     const headers = {
         providerEventId: payload.providerEventId,
         providerName: payload.providerName,
-        rawPayload: payload.rawPayload,
     };
     await ctx.unsafeAppendEvent({
         aggregateId: aggId,
@@ -151,15 +152,42 @@ export async function appendSubscriptionEvent(ctx, tenantId, payload) {
 // SystemAdmin-only: dieser handler wird ausschließlich vom programmatic
 // webhook-handler aufgerufen (mit einem internal SystemUser), nie vom
 // Tenant-Admin direkt.
-export const processEventHandler = {
-    name: "process-event",
-    agent: { expose: false },
-    schema: processEventSchema,
-    access: { roles: ["SystemAdmin"] },
-    handler: async (event, ctx) => {
-        // @cast-boundary engine-payload — dispatcher-zod-validated payload
-        const payload = event.payload;
-        const result = await appendSubscriptionEvent(ctx, event.user.tenantId, payload);
-        return { isSuccess: true, data: result };
-    },
-};
+// One subscription aggregate exists per tenant, but a tenant can legitimately hold two provider
+// subscriptions over time (a stale `incomplete` one superseded by a fresh checkout). A late or
+// retried event of the old subscription must not overwrite the row of the live one, so only a
+// `created` event may replace a blocking row that belongs to a different provider subscription.
+function isStaleSubscriptionEvent(current, payload, now) {
+    if (current === null)
+        return false;
+    if (payload.type === SubscriptionEventTypes.created)
+        return false;
+    const sameSubscription = current.providerName === payload.providerName &&
+        current.providerSubscriptionId === payload.providerSubscriptionId;
+    return !sameSubscription && isSubscriptionBlockingCheckout(current, now);
+}
+export function createProcessEventHandler(now) {
+    return {
+        name: "process-event",
+        agent: { expose: false },
+        schema: processEventSchema,
+        access: { roles: ["SystemAdmin"] },
+        handler: async (event, ctx) => {
+            // @cast-boundary engine-payload — dispatcher-zod-validated payload
+            const payload = event.payload;
+            const current = await getSubscriptionForTenant(ctx, event.user.tenantId);
+            if (isStaleSubscriptionEvent(current, payload, now())) {
+                ctx.log?.warn(`[billing-foundation:process-event] dropped stale ${payload.type} ${payload.providerEventId}: tenant already tracks another subscription`);
+                return {
+                    isSuccess: true,
+                    data: {
+                        duplicate: false,
+                        stale: true,
+                        subscriptionAggregateId: subscriptionAggregateId(event.user.tenantId),
+                    },
+                };
+            }
+            const result = await appendSubscriptionEvent(ctx, event.user.tenantId, payload);
+            return { isSuccess: true, data: result };
+        },
+    };
+}

package/dist/billing-foundation/handlers/process-payment-event.write.d.ts

@@ -3,8 +3,9 @@ import * as z from "zod";
 export declare const processPaymentEventSchema: z.ZodObject<{
     providerEventId: z.ZodString;
     providerName: z.ZodString;
+    providerCheckoutId: z.ZodOptional<z.ZodString>;
     providerCustomerId: z.ZodString;
     priceId: z.ZodString;
-    rawPayload: z.ZodString;
+    consentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const processPaymentEventHandler: WriteHandlerDef;

package/dist/billing-foundation/handlers/process-payment-event.write.js

@@ -17,9 +17,10 @@ import { PAYMENT_AGGREGATE_TYPE, PAYMENT_RECEIVED_EVENT_QN, } from "../events.js
 export const processPaymentEventSchema = z.object({
     providerEventId: z.string().min(1).max(200),
     providerName: z.string().min(1).max(50),
+    providerCheckoutId: z.string().min(1).max(200).optional(),
     providerCustomerId: z.string().min(1).max(200),
     priceId: z.string().min(1).max(200),
-    rawPayload: z.string().min(1),
+    consentId: z.string().min(1).max(100).optional(),
 });
 // SystemAdmin-only: this handler is called exclusively by the programmatic
 // webhook-handler (with an internal SystemUser), never directly by the
@@ -71,11 +72,14 @@ export const processPaymentEventHandler = {
             providerName: payload.providerName,
             providerCustomerId: encryptedFields["providerCustomerId"],
             priceId: payload.priceId,
+            ...(payload.consentId !== undefined && { consentId: payload.consentId }),
         };
         const headers = {
             providerEventId: payload.providerEventId,
             providerName: payload.providerName,
-            rawPayload: payload.rawPayload,
+            ...(payload.providerCheckoutId !== undefined && {
+                providerCheckoutId: payload.providerCheckoutId,
+            }),
         };
         await ctx.unsafeAppendEvent({
             aggregateId: aggId,

package/dist/billing-foundation/handlers/start-plan-checkout.write.js

@@ -5,13 +5,18 @@
 import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { assertBillingEnabled, assertNoActiveSubscription, isNonEmptyStringArray, joinBaseUrl, openCheckout, resolveCatalogProvider, } from "../checkout-core.js";
+import { consentCheckoutFields, consentPayloadSchema, prepareConsent, recordConsent, } from "../consumer-protection/consent-gate.js";
 import { purchaseRolesOf, resolvePlanPrices } from "../plan-catalog.js";
 export function createStartPlanCheckoutHandler(options, catalog) {
     const plans = catalog.plans;
     if (!isNonEmptyStringArray(plans)) {
         throw new Error("start-plan-checkout: catalog.plans must not be empty");
     }
-    const schema = z.object({ tier: z.enum(plans) }).strict();
+    const consumerProtection = options.consumerProtection;
+    const tierSchema = z.object({ tier: z.enum(plans) });
+    const schema = (consumerProtection
+        ? tierSchema.extend({ consent: consentPayloadSchema.optional() })
+        : tierSchema).strict();
     return {
         name: "start-plan-checkout",
         description: "Starts a hosted checkout for a plan tier when the tenant has no active subscription; the server picks price and redirect URLs.",
@@ -31,6 +36,9 @@ export function createStartPlanCheckoutHandler(options, catalog) {
                     message: `subscription-foundation: no live price resolved for tier "${payload.tier}"`,
                 });
             }
+            const consent = consumerProtection
+                ? await prepareConsent(ctx, consumerProtection, payload.consent, "subscription")
+                : undefined;
             const baseUrl = options.baseUrl ?? "";
             const result = await openCheckout(ctx, { baseUrl: options.baseUrl, catalog, now: options.now }, {
                 providerName,
@@ -38,9 +46,17 @@ export function createStartPlanCheckoutHandler(options, catalog) {
                 successUrl: joinBaseUrl(baseUrl, catalog.successPath),
                 cancelUrl: joinBaseUrl(baseUrl, catalog.cancelPath),
                 mode: "subscription",
+                ...(consent && consentCheckoutFields(consent)),
                 ...(existing?.providerName === providerName &&
                     existing.providerCustomerId && { providerCustomerId: existing.providerCustomerId }),
             });
+            if (consent) {
+                await recordConsent(ctx, consent, {
+                    tier: payload.tier,
+                    priceId: resolved.priceId,
+                    price: resolved.price,
+                });
+            }
             return { isSuccess: true, data: { url: result.url } };
         },
     };

package/dist/billing-foundation/handlers/sync-subscription.write.js

@@ -116,7 +116,6 @@ export const syncSubscriptionHandler = {
             tier: snapshot.tier,
             currentPeriodEndIso: snapshot.currentPeriodEnd,
             cancelAtIso: snapshot.cancelAt,
-            rawPayload: snapshot.rawPayload,
         });
         return {
             isSuccess: true,

package/dist/billing-foundation/i18n.js

@@ -35,6 +35,58 @@ export const BILLING_FOUNDATION_I18N = {
     "billing-foundation.plans.subscriptionPending": {
         en: "Your plan change is being processed.",
     },
+    "billing-foundation.consent.title": { en: "Review your order" },
+    "billing-foundation.consent.cancelAnytime": {
+        en: "You can cancel at any time, effective at the end of the current period.",
+    },
+    "billing-foundation.consent.renews.day": { en: "Renews every day until cancelled." },
+    "billing-foundation.consent.renews.week": { en: "Renews every week until cancelled." },
+    "billing-foundation.consent.renews.month": { en: "Renews every month until cancelled." },
+    "billing-foundation.consent.renews.year": { en: "Renews every year until cancelled." },
+    "billing-foundation.consent.renewsEvery.day": {
+        en: "Renews every {count} days until cancelled.",
+    },
+    "billing-foundation.consent.renewsEvery.week": {
+        en: "Renews every {count} weeks until cancelled.",
+    },
+    "billing-foundation.consent.renewsEvery.month": {
+        en: "Renews every {count} months until cancelled.",
+    },
+    "billing-foundation.consent.renewsEvery.year": {
+        en: "Renews every {count} years until cancelled.",
+    },
+    "billing-foundation.consent.link.terms": { en: "Terms" },
+    "billing-foundation.consent.link.withdrawal": { en: "Withdrawal policy" },
+    "billing-foundation.consent.link.privacy": { en: "Privacy policy" },
+    "billing-foundation.consent.order": { en: "Order with obligation to pay" },
+    "billing-foundation.consent.back": { en: "Back" },
+    "billing-foundation.cancel.open": { en: "Cancel contract here" },
+    "billing-foundation.cancel.title": { en: "Cancel contract" },
+    "billing-foundation.cancel.declaration": { en: "Declaration" },
+    "billing-foundation.cancel.declaration.termination": { en: "Termination" },
+    "billing-foundation.cancel.declaration.withdrawal": { en: "Withdrawal" },
+    "billing-foundation.cancel.withdrawalHint": {
+        en: "A withdrawal is only possible within the statutory withdrawal period.",
+    },
+    "billing-foundation.cancel.kind": { en: "Type of termination" },
+    "billing-foundation.cancel.kind.ordinary": { en: "Ordinary" },
+    "billing-foundation.cancel.kind.extraordinary": { en: "Extraordinary (for cause)" },
+    "billing-foundation.cancel.reason": { en: "Reason" },
+    "billing-foundation.cancel.continue": { en: "Continue" },
+    "billing-foundation.cancel.back": { en: "Back" },
+    "billing-foundation.cancel.close": { en: "Close" },
+    "billing-foundation.cancel.confirmQuestion": {
+        en: "Do you want to submit this declaration now? Declaration: {declaration}, type: {kind}.",
+    },
+    "billing-foundation.cancel.submit": { en: "Cancel now" },
+    "billing-foundation.cancel.receivedAt": { en: "We received your declaration on {date}." },
+    "billing-foundation.cancel.effectiveAt": { en: "It takes effect on {date}." },
+    "billing-foundation.cancel.effectiveUnknown": {
+        en: "We will confirm the effective date by email.",
+    },
+    "billing-foundation.cancel.emailConfirmation": {
+        en: "You will receive a confirmation by email.",
+    },
     "billing-foundation.errors.redirectOriginNotAllowed": {
         en: "This redirect URL is not allowed for this app.",
     },
@@ -67,4 +119,13 @@ export const BILLING_FOUNDATION_I18N = {
     "billing-foundation.errors.priceUnavailable": {
         en: "This plan's price is temporarily unavailable.",
     },
+    "billing-foundation.errors.consentRequired": {
+        en: "Confirm both consent boxes before you continue.",
+    },
+    "billing-foundation.errors.consentTextOutdated": {
+        en: "The consent text has changed. Reload the page and confirm again.",
+    },
+    "billing-foundation.errors.termsUnavailable": {
+        en: "The terms are temporarily unavailable. Please try again later.",
+    },
 };

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

@@ -1,7 +1,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, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionEventType, SubscriptionEventTypes, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, type SubscriptionStatus, SubscriptionStatuses, } from "./constants.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 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";
 export { billingFoundationFeature, createBillingFoundationFeature } from "./feature.js";
@@ -9,5 +10,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, 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 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

@@ -2,7 +2,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, SUBSCRIPTION_PROVIDER_EXTENSION, SubscriptionEventTypes, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "./constants.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 { 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";
 export { billingFoundationFeature, createBillingFoundationFeature } from "./feature.js";

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

@@ -20,7 +20,7 @@ export const PAYMENT_TENANT_DESTROY_ARCHIVE_REASON = "tenant-destroy looks up th
 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),
+        db: ctx.db.unsafeRaw(),
         tenantId: ctx.tenantId,
     });
     const aggregateId = subscriptionAggregateId(ctx.tenantId);
@@ -30,7 +30,7 @@ export async function subscriptionTenantDestroyHook(ctx) {
     else {
         await ctx.db.deleteMany(subscriptionsProjectionTable, { id: aggregateId });
     }
-    await archiveStream(ctx.db.unsafeRaw(SUBSCRIPTION_TENANT_DESTROY_ARCHIVE_REASON), {
+    await archiveStream(ctx.db.unsafeRaw(), {
         tenantId: ctx.tenantId,
         aggregateId,
         aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
@@ -46,7 +46,7 @@ export async function subscriptionTenantDestroyHook(ctx) {
 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),
+        db: ctx.db.unsafeRaw(),
         tenantId: ctx.tenantId,
     });
     const aggregateId = paymentAggregateId(ctx.tenantId);
@@ -58,7 +58,7 @@ export async function paymentTenantDestroyHook(ctx) {
             tenantId: ctx.tenantId,
         });
     }
-    await archiveStream(ctx.db.unsafeRaw(PAYMENT_TENANT_DESTROY_ARCHIVE_REASON), {
+    await archiveStream(ctx.db.unsafeRaw(), {
         tenantId: ctx.tenantId,
         aggregateId,
         aggregateType: PAYMENT_AGGREGATE_TYPE,