@cosmicdrift/kumiko-bundled-features 0.363.0 → 0.364.0

package/dist/billing-foundation/consumer-protection/termination-mail.d.ts

@@ -30,15 +30,17 @@ export type TerminationDeclaration = {
 /** The operator notice for a provider problem has no declarant data at all. */
 export type OperatorNoticeDeclaration = Pick<TerminationDeclaration, "declarationType" | "terminationKind"> & Partial<Omit<TerminationDeclaration, "declarationType" | "terminationKind">>;
 export declare function formatReceivedAt(iso: string, locale: ConsentLocale): string;
+/** The receipt carries enum fields only: free text from an anonymous caller
+ *  must not be echoed to an arbitrary address. */
+export type ReceiptDeclaration = Pick<TerminationDeclaration, "declarationType" | "terminationKind">;
 export type TerminationReceiptArgs = {
     readonly locale: ConsentLocale;
     readonly requestId: string;
     readonly receivedAtIso: string;
-    readonly declaration: TerminationDeclaration;
+    readonly declaration: ReceiptDeclaration;
     readonly operatorEmail: string;
 };
-/** Built from the declarant's own input only: the content must not depend on
- *  whether (or how) the declaration matched a contract. */
+/** The content must not depend on whether (or how) the declaration matched a contract. */
 export declare function terminationReceiptVariables(args: TerminationReceiptArgs): TerminationReceiptVariables;
 export type OperatorNoticeArgs = {
     readonly locale: ConsentLocale;

package/dist/billing-foundation/consumer-protection/termination-mail.js

@@ -32,8 +32,7 @@ function declarationLines(declaration, locale) {
     ];
     return lines.map((text) => ({ text }));
 }
-/** Built from the declarant's own input only: the content must not depend on
- *  whether (or how) the declaration matched a contract. */
+/** The content must not depend on whether (or how) the declaration matched a contract. */
 export function terminationReceiptVariables(args) {
     const texts = TERMINATION_TEXTS[args.locale];
     return {

package/dist/billing-foundation/consumer-protection/termination-receipt-limit.d.ts

@@ -0,0 +1,6 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+export declare const RECEIPT_MAILS_PER_RECIPIENT = 3;
+export declare const RECEIPT_WINDOW_SECONDS: number;
+/** Consumes one receipt token for the recipient. Fails closed when the limiter
+ *  errors or no digest key is wired: the declaration is already recorded, a missing receipt is the lesser harm. */
+export declare function mayMailReceipt(ctx: HandlerContext, email: string): Promise<boolean>;

package/dist/billing-foundation/consumer-protection/termination-receipt-limit.js

@@ -0,0 +1,34 @@
+import { normalizePayloadBucketValue } from "@cosmicdrift/kumiko-framework/pipeline";
+// The declaration itself is a statutory duty and is never refused. Only the
+// receipt mail is capped, so the endpoint cannot be used to mail one inbox
+// from the operator's sender domain.
+export const RECEIPT_MAILS_PER_RECIPIENT = 3;
+export const RECEIPT_WINDOW_SECONDS = 24 * 60 * 60;
+const RECEIPT_BUCKET_PREFIX = "termination-receipt";
+function receiptBucketKey(ctx, email) {
+    const digest = ctx.rateLimitDigest?.(normalizePayloadBucketValue(email, "email"));
+    return digest === undefined ? undefined : `${RECEIPT_BUCKET_PREFIX}:${digest}`;
+}
+/** Consumes one receipt token for the recipient. Fails closed when the limiter
+ *  errors or no digest key is wired: the declaration is already recorded, a missing receipt is the lesser harm. */
+export async function mayMailReceipt(ctx, email) {
+    // skip: no rate limiter wired, nothing to count against
+    if (!ctx.rateLimit)
+        return true;
+    try {
+        const bucketKey = receiptBucketKey(ctx, email);
+        if (bucketKey === undefined) {
+            ctx.log?.warn("[billing-foundation:termination] no rate-limit digest available, receipt mail withheld");
+            return false;
+        }
+        const decision = await ctx.rateLimit.check(bucketKey, {
+            limit: RECEIPT_MAILS_PER_RECIPIENT,
+            windowSeconds: RECEIPT_WINDOW_SECONDS,
+        });
+        return decision.allowed;
+    }
+    catch (error) {
+        ctx.log?.warn(`[billing-foundation:termination] receipt rate limiter failed: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}

package/dist/billing-foundation/consumer-protection/termination-record.d.ts

@@ -49,6 +49,8 @@ export type RecordContractTerminationResult = {
     readonly effectiveAtIso: string | null;
     readonly providerCancel: ProviderCancelOutcome;
     readonly noticeReason: Extract<OperatorNoticeReason, "provider_cannot_cancel" | "provider_error" | "no_active_subscription"> | null;
+    /** An account withdrawal arrived after the period: cancelled at period end instead. */
+    readonly withdrawalPeriodExpired: boolean;
 };
 export declare const recordUnmatchedContractTerminationSchema: z.ZodObject<{
     requestId: z.ZodString;

package/dist/billing-foundation/consumer-protection/termination-record.js

@@ -12,6 +12,7 @@ import { CONTRACT_TERMINATION_CHANNELS, CONTRACT_TERMINATION_DECLARATION_TYPES,
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
 import { CONSENT_LOCALES, FALLBACK_CONSENT_LOCALE } from "./consent-locale.js";
 import { notifyOperator } from "./termination-notify.js";
+import { isWithinWithdrawalPeriod } from "./withdrawal-period.js";
 const REQUESTED_CANCEL_TIMINGS = [
     SubscriptionCancelTimings.periodEnd,
     SubscriptionCancelTimings.immediately,
@@ -148,10 +149,14 @@ export function createRecordContractTerminationHandler(options, consumerProtecti
                         effectiveAtIso: alreadyRecorded.effectiveAtIso,
                         providerCancel: alreadyRecorded.providerCancel,
                         noticeReason: null,
+                        withdrawalPeriodExpired: false,
                     },
                 };
             }
-            const { providerCancel, effectiveAtIso, noticeReason } = await cancelAtProvider(ctx, tenantId, payload.when, receivedAtIso);
+            const withdrawalPeriodExpired = payload.declarationType === "withdrawal" &&
+                payload.when === SubscriptionCancelTimings.immediately &&
+                !isWithinWithdrawalPeriod(stream.events, options.now());
+            const { providerCancel, effectiveAtIso, noticeReason } = await cancelAtProvider(ctx, tenantId, withdrawalPeriodExpired ? SubscriptionCancelTimings.periodEnd : payload.when, receivedAtIso);
             const recorded = {
                 requestId: payload.requestId,
                 declarationType: payload.declarationType,
@@ -189,6 +194,7 @@ export function createRecordContractTerminationHandler(options, consumerProtecti
                     effectiveAtIso,
                     providerCancel,
                     noticeReason,
+                    withdrawalPeriodExpired,
                 },
             };
         },

package/dist/billing-foundation/consumer-protection/termination-request.js

@@ -14,7 +14,7 @@ import { purchaseRolesOf } from "../plan-catalog.js";
 import { resolveConsentLocale } from "./consent-text.js";
 import { terminationReceiptVariables } from "./termination-mail.js";
 import { notifyOperator, requireNotify } from "./termination-notify.js";
-const TENANT_ADMIN_ROLE = "TenantAdmin";
+import { mayMailReceipt } from "./termination-receipt-limit.js";
 const EXTRAORDINARY_REASON_MESSAGE = "reason is required for an extraordinary termination";
 const authUserRowSchema = z.object({
     id: z.string().min(1),
@@ -53,27 +53,36 @@ function needsOperatorNotice(declaration) {
     ];
 }
 async function sendTerminationMails(ctx, consumerProtection, plan) {
-    await requireNotify(ctx)(CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, {
-        route: { email: plan.declaration.email },
-        data: terminationReceiptVariables({
+    const receiptAllowed = await mayMailReceipt(ctx, plan.declaration.email);
+    if (receiptAllowed) {
+        await requireNotify(ctx)(CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE, {
+            route: { email: plan.declaration.email },
+            data: terminationReceiptVariables({
+                locale: plan.locale,
+                requestId: plan.requestId,
+                receivedAtIso: plan.receivedAtIso,
+                declaration: {
+                    declarationType: plan.declaration.declarationType,
+                    terminationKind: plan.declaration.terminationKind,
+                },
+                operatorEmail: consumerProtection.operatorEmail,
+            }),
             locale: plan.locale,
-            requestId: plan.requestId,
-            receivedAtIso: plan.receivedAtIso,
-            declaration: plan.declaration,
-            operatorEmail: consumerProtection.operatorEmail,
-        }),
-        locale: plan.locale,
-        priority: "critical",
-    });
+            priority: "critical",
+        });
+    }
+    const reasons = receiptAllowed
+        ? plan.reasons
+        : [...plan.reasons, "receipt_rate_limited"];
     // skip: no operator notice needed for this declaration
-    if (plan.reasons.length === 0)
+    if (reasons.length === 0)
         return;
-    await notifyOperator(ctx, consumerProtection, plan);
+    await notifyOperator(ctx, consumerProtection, { ...plan, reasons });
 }
 // Tenants the entered email can terminate a contract for: tenants where the
-// user is TenantAdmin and the subscription is not terminal. Every identity
+// user holds a purchase role and the subscription is not terminal. Every identity
 // below comes from the trusted lookups, never from the payload.
-async function findTerminableTenantIds(ctx, requestTenantId, email) {
+async function findTerminableTenantIds(ctx, options, requestTenantId, email) {
     declareEscapeHatch({
         reason: "anonymous declarant has no session — finds the contract by email via user:find-for-auth and tenant:memberships as a system user; the calling handler declares its own escapeHatch",
     });
@@ -85,9 +94,10 @@ async function findTerminableTenantIds(ctx, requestTenantId, email) {
     }));
     if (!memberships.success)
         return [];
+    const purchaseRoles = purchaseRolesOf(options.catalog);
     const adminTenantIds = [
         ...new Set(memberships.data
-            .filter((membership) => membership.roles.includes(TENANT_ADMIN_ROLE))
+            .filter((membership) => membership.roles.some((role) => purchaseRoles.includes(role)))
             .map((membership) => membership.tenantId)),
     ];
     const terminable = [];
@@ -105,7 +115,6 @@ export function createRequestContractTerminationHandler(options, consumerProtect
         schema: requestContractTerminationSchema,
         access: { roles: ["anonymous"] },
         rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 600 },
-        additionalRateLimits: [{ per: { payloadField: "email" }, limit: 3, windowSeconds: 86400 }],
         ...(consumerProtection.terminationScope === "platform" && { tenantlessAnonymous: true }),
         escapeHatch: {
             reason: "Anonymous declarant has no session — finds the contract by email via ctx.queryAs(system, user:find-for-auth) and tenant:memberships; the tenant written to comes only from those lookups.",
@@ -119,7 +128,7 @@ export function createRequestContractTerminationHandler(options, consumerProtect
             const reasons = [];
             const locale = resolveConsentLocale(payload.locale);
             let matchedTenantId;
-            const candidates = await findTerminableTenantIds(ctx, event.user.tenantId, payload.email);
+            const candidates = await findTerminableTenantIds(ctx, options, event.user.tenantId, payload.email);
             const [onlyCandidate] = candidates;
             if (candidates.length === 1 && onlyCandidate !== undefined) {
                 matchedTenantId = onlyCandidate;
@@ -168,7 +177,7 @@ export function createRequestContractTerminationHandler(options, consumerProtect
 export function createTerminateContractHandler(options, consumerProtection) {
     return {
         name: "terminate-contract",
-        description: "Terminates the tenant's subscription at the end of the billing period, or withdraws from the contract and cancels it immediately; sends a receipt to the caller's email.",
+        description: "Terminates the tenant's subscription at the end of the billing period, or withdraws from the contract and cancels it immediately within the 14-day withdrawal period (at period end after it); sends a receipt to the caller's email.",
         schema: terminateContractSchema,
         access: { roles: purchaseRolesOf(options.catalog) },
         escapeHatch: {
@@ -214,6 +223,7 @@ export function createTerminateContractHandler(options, consumerProtection) {
                 },
                 reasons: [
                     ...(data.noticeReason !== null ? [data.noticeReason] : []),
+                    ...(data.withdrawalPeriodExpired ? ["withdrawal_period_expired"] : []),
                     ...needsOperatorNotice(payload),
                 ],
                 tenantId,

package/dist/billing-foundation/consumer-protection/termination-texts.d.ts

@@ -58,6 +58,6 @@ export type PageTexts = {
     readonly rateLimitedTitle: string;
     readonly rateLimitedBody: string;
 };
-export declare const OPERATOR_NOTICE_REASONS: readonly ["unmatched", "ambiguous", "withdrawal", "extraordinary", "provider_cannot_cancel", "provider_error", "no_active_subscription", "recording_failed"];
+export declare const OPERATOR_NOTICE_REASONS: readonly ["unmatched", "ambiguous", "withdrawal", "extraordinary", "provider_cannot_cancel", "provider_error", "no_active_subscription", "recording_failed", "withdrawal_period_expired", "receipt_rate_limited"];
 export type OperatorNoticeReason = (typeof OPERATOR_NOTICE_REASONS)[number];
 export declare const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>>;

package/dist/billing-foundation/consumer-protection/termination-texts.js

@@ -7,6 +7,8 @@ export const OPERATOR_NOTICE_REASONS = [
     "provider_error",
     "no_active_subscription",
     "recording_failed",
+    "withdrawal_period_expired",
+    "receipt_rate_limited",
 ];
 export const TERMINATION_TEXTS = {
     de: {
@@ -46,6 +48,8 @@ export const TERMINATION_TEXTS = {
             provider_error: "Die Kündigung beim Zahlungsanbieter ist fehlgeschlagen",
             no_active_subscription: "Keine laufende Subscription beim Anbieter",
             recording_failed: "Die Erklärung konnte nicht gespeichert werden",
+            withdrawal_period_expired: "Widerruf nach Ablauf der Widerrufsfrist: zum Periodenende gekündigt, Anspruch prüfen",
+            receipt_rate_limited: "Keine Eingangsbestätigung versendet: Limit pro Empfängeradresse erreicht",
         },
         noticeReasons: "Grund der Benachrichtigung",
         channel: "Kanal",
@@ -125,6 +129,8 @@ export const TERMINATION_TEXTS = {
             provider_error: "Cancelling at the payment provider failed",
             no_active_subscription: "No running subscription at the provider",
             recording_failed: "The declaration could not be stored",
+            withdrawal_period_expired: "Withdrawal after the withdrawal period: cancelled at period end, review the claim",
+            receipt_rate_limited: "No receipt mail sent: the per-recipient limit was reached",
         },
         noticeReasons: "Reason for this notice",
         channel: "Channel",

package/dist/billing-foundation/consumer-protection/withdrawal-period.d.ts

@@ -0,0 +1,10 @@
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+export declare const WITHDRAWAL_PERIOD_DAYS = 14;
+type PeriodStartEvent = {
+    readonly type: string;
+    readonly createdAt: Temporal.Instant;
+};
+/** The period runs from the latest consent or subscription start on the stream.
+ *  A stream with neither has no provable start and counts as expired. */
+export declare function isWithinWithdrawalPeriod(events: readonly PeriodStartEvent[], now: Temporal.Instant): boolean;
+export {};

package/dist/billing-foundation/consumer-protection/withdrawal-period.js

@@ -0,0 +1,26 @@
+import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_QN } from "../events.js";
+// § 355 BGB: the withdrawal period is 14 days from conclusion of the contract.
+export const WITHDRAWAL_PERIOD_DAYS = 14;
+const HOURS_PER_DAY = 24;
+const PERIOD_START_EVENT_TYPES = new Set([
+    CHECKOUT_CONSENT_RECORDED_EVENT_QN,
+    SUBSCRIPTION_CREATED_EVENT_QN,
+]);
+/** The period runs from the latest consent or subscription start on the stream.
+ *  A stream with neither has no provable start and counts as expired. */
+export function isWithinWithdrawalPeriod(events, now) {
+    let latestStart;
+    for (const event of events) {
+        if (!PERIOD_START_EVENT_TYPES.has(event.type))
+            continue;
+        if (latestStart === undefined ||
+            event.createdAt.epochMilliseconds > latestStart.epochMilliseconds) {
+            latestStart = event.createdAt;
+        }
+    }
+    // skip: no consent or subscription-created event, nothing proves a running period
+    if (latestStart === undefined)
+        return false;
+    const periodEnd = latestStart.add({ hours: WITHDRAWAL_PERIOD_DAYS * HOURS_PER_DAY });
+    return now.epochMilliseconds <= periodEnd.epochMilliseconds;
+}

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

@@ -21,10 +21,10 @@
 // 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 { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { assertCheckoutAllowed, openCheckout, startProviderCheckout, } from "../checkout-core.js";
-import { consentCheckoutFields, consentPayloadSchema, prepareConsent, recordConsent, } from "../consumer-protection/consent-gate.js";
+import { assertValidOrderItem, consentCheckoutFields, consentPayloadSchema, prepareConsent, recordConsent, } from "../consumer-protection/consent-gate.js";
 const createCheckoutSessionSchema = z.object({
     /** Welcher Provider — entityName eines registrierten subscription-
      *  Plugins ("stripe" / "paypal" / ...). */
@@ -75,10 +75,11 @@ export function createCheckoutSessionHandler(options) {
             }
             const mode = payload.mode ?? "subscription";
             const plugin = await assertCheckoutAllowed(ctx, openOptions, checkoutInput);
-            const price = await lookupPrice(ctx, plugin, payload.priceId);
+            const price = await lookupPrice(ctx, plugin, payload.providerName, payload.priceId);
             const orderItem = mode === "payment"
                 ? await consumerProtection.oneOffItemLabel?.(ctx, payload.priceId)
                 : undefined;
+            assertValidOrderItem(orderItem, payload.priceId);
             const consent = await prepareConsent(ctx, consumerProtection, payload.consent, mode);
             const result = await startProviderCheckout(ctx, plugin, {
                 ...checkoutInput,
@@ -99,10 +100,15 @@ export function createCheckoutSessionHandler(options) {
 }
 // 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) {
+async function lookupPrice(ctx, plugin, providerName, priceId) {
+    if (!plugin.retrievePrices) {
+        throw new InternalError({
+            message: `billing-foundation: provider "${providerName}" lacks retrievePrices, required by consumerProtection`,
+        });
+    }
     let price;
     try {
-        const prices = (await plugin.retrievePrices?.(ctx, [priceId])) ?? [];
+        const prices = await plugin.retrievePrices(ctx, [priceId]);
         price = prices.find((p) => p.priceId === priceId);
     }
     catch (cause) {

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

@@ -14,7 +14,7 @@
 import { configuredPiiSubjectKms, encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id.js";
-import { isSubscriptionBlockingCheckout, SubscriptionEventTypes, SubscriptionStatuses, } from "../constants.js";
+import { isSubscriptionBlockingCheckout, isSwitchableSubscriptionStatus, 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";
@@ -154,16 +154,20 @@ export async function appendSubscriptionEvent(ctx, tenantId, payload) {
 // Tenant-Admin direkt.
 // 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.
+// retried event of the old subscription must not overwrite the row of the live one, so an event of a
+// different provider subscription only replaces a row that no longer blocks a checkout. The exception
+// is a `created` of a subscription that is itself live (a provider switch); a late `created` of a
+// never-completed `incomplete` one stays stale, since delivery order is not guaranteed.
 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);
+    if (sameSubscription || !isSubscriptionBlockingCheckout(current, now))
+        return false;
+    const supersedesCurrent = payload.type === SubscriptionEventTypes.created &&
+        isSwitchableSubscriptionStatus(payload.status);
+    return !supersedesCurrent;
 }
 export function createProcessEventHandler(now) {
     return {

package/dist/billing-foundation/i18n.js

@@ -90,6 +90,9 @@ export const BILLING_FOUNDATION_I18N = {
     "billing-foundation.errors.redirectOriginNotAllowed": {
         en: "This redirect URL is not allowed for this app.",
     },
+    "billing-foundation.errors.providerCustomerUnknown": {
+        en: "The billing account for this subscription no longer exists. Subscribe again to continue.",
+    },
     "billing-foundation.errors.providerHasNoPriceCatalog": {
         en: "This provider has no known prices configured.",
     },

package/dist/billing-foundation/subscription-tier-sync.d.ts

@@ -1,11 +1,17 @@
-import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
+import type { ExtraRouteDefinition, SignatureExtraRouteDeps } from "@cosmicdrift/kumiko-framework/api";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 export declare const SUBSCRIPTION_WEBHOOK_PATH = "/webhooks/subscription/:providerName";
 export type SubscriptionTierSyncDeps<TTier extends string> = {
     readonly isTierName: (value: string) => value is TTier;
     readonly defaultTier: TTier;
     readonly onSyncError?: "log" | "fail-webhook";
 };
+export declare const TIER_SYNC_MANUAL_GRANT_SKIPPED = "tier_sync_manual_grant_skipped";
 export declare function effectiveTierFromSubscription<TTier extends string>(status: string | undefined, tier: string | undefined, isTierName: (value: string) => value is TTier, defaultTier: TTier): TTier;
 export declare function createSubscriptionTierSync<TTier extends string>(deps: SubscriptionTierSyncDeps<TTier>): {
     createWebhookRoute: () => ExtraRouteDefinition;
+    syncTierFromSubscription: (tenantId: TenantId, routeDeps: Pick<SignatureExtraRouteDeps, "dispatchSystemQuery" | "dispatchSystemWrite">) => Promise<{
+        code: string;
+        message: string;
+    } | null>;
 };

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

@@ -10,6 +10,9 @@ import { createSubscriptionWebhookRoute } from "./webhook-handler.js";
 // Outside /api — signature routes carry their own auth (verify()) and are
 // not JWT-guarded, so provider dashboards (Stripe, PayPal, ...) point here.
 export const SUBSCRIPTION_WEBHOOK_PATH = "/webhooks/subscription/:providerName";
+// A manual grant that differs from what billing would assign is reported with this
+// code but never fails the webhook: a provider retry cannot resolve it.
+export const TIER_SYNC_MANUAL_GRANT_SKIPPED = "tier_sync_manual_grant_skipped";
 export function effectiveTierFromSubscription(status, tier, isTierName, defaultTier) {
     const usable = status === SubscriptionStatuses.active || status === SubscriptionStatuses.trialing;
     return usable && typeof tier === "string" && isTierName(tier) ? tier : defaultTier;
@@ -68,10 +71,14 @@ export function createSubscriptionTierSync(deps) {
                 }
                 return null;
             }
-            if (assignment.source === TierAssignmentSources.manual)
-                return null;
             if (assignment.tier === effective)
                 return null;
+            if (assignment.source === TierAssignmentSources.manual) {
+                return {
+                    code: TIER_SYNC_MANUAL_GRANT_SKIPPED,
+                    message: `manual tier grant "${String(assignment.tier)}" kept although the subscription yields "${effective}"`,
+                };
+            }
             const result = await routeDeps.dispatchSystemWrite({
                 handlerQn: TierEngineHandlers.update,
                 payload: {
@@ -108,8 +115,9 @@ export function createSubscriptionTierSync(deps) {
                 const syncError = await syncTierFromSubscription(tenantId, routeDeps);
                 if (syncError) {
                     // biome-ignore lint/suspicious/noConsole: operator visibility for a post-commit sync failure
-                    console.warn(`[subscription-tier-sync] tier sync failed for tenant ${tenantId} after successful webhook write: ${syncError.code} ${syncError.message}`);
-                    if (deps.onSyncError === "fail-webhook") {
+                    console.warn(`[subscription-tier-sync] tier sync for tenant ${tenantId} after successful webhook write: ${syncError.code} ${syncError.message}`);
+                    if (deps.onSyncError === "fail-webhook" &&
+                        syncError.code !== TIER_SYNC_MANUAL_GRANT_SKIPPED) {
                         return {
                             isSuccess: false,
                             error: {
@@ -125,5 +133,5 @@ export function createSubscriptionTierSync(deps) {
             },
         });
     }
-    return { createWebhookRoute };
+    return { createWebhookRoute, syncTierFromSubscription };
 }

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

@@ -289,7 +289,10 @@ export type LegalLinkSet = {
 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. */
+ *  payload and record it as an event before the buyer reaches the provider.
+ *  Every provider used with `create-checkout-session` must implement
+ *  `retrievePrices`: the live price is part of the consent record, and a
+ *  provider without it fails the checkout with an InternalError. */
 export type ConsumerProtectionOptions = {
     /** Slug of the template-resolver `text-block` holding the terms text; its
      *  content hash is stored with every recorded consent. */
@@ -304,7 +307,9 @@ export type ConsumerProtectionOptions = {
     readonly terminationScope?: TerminationScope;
     /** 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. */
+     *  i18n, so it must be qualified with the registering feature. The label key
+     *  is 1-200 characters, string params at most 100; a violation fails the
+     *  checkout with an InternalError before the provider session is created. */
     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). */

package/dist/cap-counter/calendar-cap-usage-reservation.js

@@ -12,6 +12,8 @@ export async function reserveEnforcedCalendarCap(ctx, cap) {
             profile: cap.profile,
             notify: cap.notify,
             amount: cap.amount,
+            ...(cap.periodEndIso !== undefined && { periodEndIso: cap.periodEndIso }),
+            ...(cap.i18nKey !== undefined && { i18nKey: cap.i18nKey }),
             markSoftWarnedOutsideTransaction: outsideTransaction,
         });
     }

package/dist/cap-counter/enforce-cap.d.ts

@@ -57,6 +57,9 @@ export declare function assertBelowHardCap(valueSeenByLastUnit: number, cap: {
     readonly capName: string;
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
+    readonly periodStartIso?: string;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
 }): void;
 /**
  * Synchronous read-and-check of the calling tenant's counter for
@@ -85,6 +88,8 @@ export declare function enforceCap(ctx: CapCounterContext, options: {
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
     readonly amount?: number;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
 }): Promise<EnforceCapResult>;
 /**
  * Synchronous read-and-check of the calling tenant's Rolling-Window-
@@ -120,6 +125,9 @@ export declare function enforceRollingCap(ctx: CapCounterContext, options: {
  * Thrown by enforceCap/enforceRollingCap when value ≥ hard-threshold.
  * Extends `KumikoError` — the dispatcher auto-maps this to HTTP 429
  * with `code: "cap_exceeded"`, no caller-side catch needed.
+ *
+ * Calendar caps carry `resetAt` (end of the period) and `retryAfterSeconds`, which the API
+ * answers as Retry-After. Rolling caps have no fixed reset instant, so both stay undefined.
  */
 export declare class CapExceededError extends KumikoError {
     readonly capName: string;
@@ -128,7 +136,13 @@ export declare class CapExceededError extends KumikoError {
     readonly tolerance: CapToleranceProfile;
     readonly code: "cap_exceeded";
     readonly httpStatus = 429;
-    constructor(capName: string, limit: number, currentValue: number, tolerance: CapToleranceProfile);
+    readonly resetAt: string | undefined;
+    constructor(capName: string, limit: number, currentValue: number, tolerance: CapToleranceProfile, options?: {
+        readonly resetAt?: string;
+        readonly i18nKey?: string;
+        readonly cause?: Error;
+        readonly now?: Temporal.Instant;
+    });
 }
 /**
  * Calendar-month period start in UTC. Use this for monthly caps
@@ -137,6 +151,7 @@ export declare class CapExceededError extends KumikoError {
  * Returns ISO string for the 1st of the current month at 00:00 UTC.
  */
 export declare function currentCalendarMonthStartIso(now?: Temporal.Instant): string;
+export declare function calendarMonthPeriodEndIso(periodStartIso: string): string;
 /**
  * Soft-hit-notifier callback. Caller liefert die Funktion die ein
  * delivery-event emittet (z.B. `delivery.send({to, template, payload})`).
@@ -169,6 +184,8 @@ export declare function enforceCapAndMaybeNotify(ctx: CapCounterContext, options
     readonly profile: CapToleranceProfileName;
     readonly notify: SoftHitNotifier;
     readonly amount?: number;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
     readonly markSoftWarnedOutsideTransaction?: boolean;
 }): Promise<EnforceCapResult>;
 /**