@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

package/dist/auth-mfa/handlers/regenerate-recovery.write.d.ts

@@ -6,4 +6,4 @@ export declare function createRegenerateRecoveryHandler(opts: RegenerateRecovery
     code: z.ZodString;
 }, z.core.$strip>, {
     recoveryCodes: string[];
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/auth-mfa/handlers/verify.write.d.ts

@@ -11,4 +11,4 @@ export declare function createMfaVerifyHandler(opts: MfaVerifyOptions): import("
 }, z.core.$strip>, {
     kind: string;
     session: SessionUser;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/auth-mfa/web/mfa-client.js

@@ -6,7 +6,7 @@
 // false, error}) because auth-routes.ts uses mintSessionAndRespond() for both
 // routes.
 // kumiko-lint-ignore cross-feature-import client-only types, the feature's server barrel has no web/ re-export
-import { toLoginResponse, } from "../../auth-email-password/web/index.js";
+import { failureFromErrorField, toLoginResponse, } from "../../auth-email-password/web/index.js";
 export async function verifyMfaChallenge(challengeToken, code) {
     const res = await fetch("/api/auth/mfa/verify", {
         method: "POST",
@@ -25,20 +25,7 @@ export async function verifyMfaChallenge(challengeToken, code) {
             data: toLoginResponse(body.token, body.user, body.landingPath),
         };
     }
-    const err = body.error;
-    if (typeof err === "string") {
-        return { kind: "failure", error: { reason: err } };
-    }
-    const reason = err?.details?.reason ?? err?.code ?? "mfa_verify_failed";
-    const retry = err?.details?.retryAfterSeconds;
-    return {
-        kind: "failure",
-        error: {
-            reason,
-            ...(err?.message !== undefined && { message: err.message }),
-            ...(retry !== undefined && { retryAfterSeconds: retry }),
-        },
-    };
+    return { kind: "failure", error: failureFromErrorField(body.error, "mfa_verify_failed") };
 }
 // Browser side of POST /api/auth/mfa/preauth-enable-start — lets a user
 // blocked at login by MFA enforcement generate a TOTP secret/QR without a
@@ -71,20 +58,7 @@ export async function startMfaSetupPreauth(preauthSetupToken, accountLabel) {
             },
         };
     }
-    const err = body.error;
-    if (typeof err === "string") {
-        return { kind: "failure", error: { reason: err } };
-    }
-    const reason = err?.details?.reason ?? err?.code ?? "setup_failed";
-    const retry = err?.details?.retryAfterSeconds;
-    return {
-        kind: "failure",
-        error: {
-            reason,
-            ...(err?.message !== undefined && { message: err.message }),
-            ...(retry !== undefined && { retryAfterSeconds: retry }),
-        },
-    };
+    return { kind: "failure", error: failureFromErrorField(body.error, "setup_failed") };
 }
 // Browser side of POST /api/auth/mfa/preauth-confirm — completes both the
 // enrollment started by startMfaSetupPreauth and the login
@@ -110,18 +84,5 @@ export async function confirmMfaSetupPreauth(setupToken, code) {
             data: toLoginResponse(body.token, body.user, body.landingPath),
         };
     }
-    const err = body.error;
-    if (typeof err === "string") {
-        return { kind: "failure", error: { reason: err } };
-    }
-    const reason = err?.details?.reason ?? err?.code ?? "mfa_setup_confirm_failed";
-    const retry = err?.details?.retryAfterSeconds;
-    return {
-        kind: "failure",
-        error: {
-            reason,
-            ...(err?.message !== undefined && { message: err.message }),
-            ...(retry !== undefined && { retryAfterSeconds: retry }),
-        },
-    };
+    return { kind: "failure", error: failureFromErrorField(body.error, "mfa_setup_confirm_failed") };
 }

package/dist/billing-foundation/checkout-core.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { getSubscriptionForTenant } from "./get-subscription-for-tenant.ts";
-import type { BillingPlanCatalog, SubscriptionProviderPlugin } from "./types.ts";
+import type { BillingFoundationOptions, BillingPlanCatalog, SubscriptionProviderPlugin } from "./types.ts";
 /** Narrows a `readonly string[]` to the non-empty tuple shape `z.enum`
  *  needs. Callers only reach this with a catalog's `plans` — the feature
  *  factory already rejected an empty `plans` array at mount time, so the
@@ -75,6 +75,7 @@ export type OpenCheckoutOptions = {
     readonly baseUrl?: string;
     readonly catalog?: BillingPlanCatalog;
     readonly now: () => Temporal.Instant;
+    readonly authorizeOneOffCheckout?: BillingFoundationOptions["authorizeOneOffCheckout"];
     /** The caller already ran `assertBillingEnabled` under its own handler name
      *  (before a costly provider lookup), so the gate is not repeated here. */
     readonly billingEnabledChecked?: boolean;

package/dist/billing-foundation/checkout-core.js

@@ -5,6 +5,7 @@
 // checkout into a plan-aware one. Internal — not re-exported from index.ts.
 import { ConflictError, FeatureDisabledError, UnconfiguredError, UnprocessableError, } from "@cosmicdrift/kumiko-framework/errors";
 import { getSubscriptionForTenant } from "./get-subscription-for-tenant.js";
+import { assertOneOffAuthorized, assertOneOffPriceAllowed } from "./one-off-checkout-gate.js";
 import { BILLING_FOUNDATION_FEATURE, isSubscriptionBlockingCheckout, SUBSCRIPTION_PROVIDER_EXTENSION, } from "./web/constants.js";
 /** Narrows a `readonly string[]` to the non-empty tuple shape `z.enum`
  *  needs. Callers only reach this with a catalog's `plans` — the feature
@@ -208,17 +209,6 @@ function assertSubscriptionPriceAllowed(plugin, catalog, input) {
         });
     }
 }
-// Missing/empty oneOffPriceIds rejects every payment checkout: same
-// "no gate configured yet = closed" default as the priceToTier gate.
-function assertOneOffPriceAllowed(plugin, input) {
-    const oneOffPriceIds = plugin.oneOffPriceIds ?? [];
-    if (!oneOffPriceIds.includes(input.priceId)) {
-        throw new UnprocessableError("unknown_price", {
-            i18nKey: "billing-foundation.errors.unknownPrice",
-            message: `subscription-foundation: priceId "${input.priceId}" is not in provider "${input.providerName}"'s oneOffPriceIds`,
-        });
-    }
-}
 function canCreateCheckoutSession(plugin) {
     return plugin.createCheckoutSession !== undefined;
 }
@@ -251,6 +241,7 @@ export async function assertCheckoutAllowed(ctx, options, input) {
     }
     else {
         assertOneOffPriceAllowed(plugin, input);
+        await assertOneOffAuthorized(ctx, options.authorizeOneOffCheckout, input);
     }
     // Rejects a foreign tenant's provider-customer id — otherwise the checkout
     // would attach to that customer's stored payment methods and invoices.

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

@@ -39,6 +39,7 @@ export declare const paymentEventPayloadSchema: z.ZodObject<{
     providerName: z.ZodString;
     providerCustomerId: z.ZodString;
     priceId: z.ZodString;
+    quantity: z.ZodOptional<z.ZodNumber>;
     consentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type PaymentEventPayload = z.infer<typeof paymentEventPayloadSchema>;

package/dist/billing-foundation/events.js

@@ -79,6 +79,8 @@ export const paymentEventPayloadSchema = z.object({
     // subscriptionEventPayloadSchema's same rationale.
     providerCustomerId: z.string().min(1).max(1000),
     priceId: z.string().min(1).max(200),
+    // Optional so payloads stored before quantity existed still parse; absent = 1.
+    quantity: z.number().int().positive().optional(),
     consentId: z.string().min(1).max(100).optional(),
 });
 // =============================================================================

package/dist/billing-foundation/feature.js

@@ -90,7 +90,7 @@ export function createBillingFoundationFeature(options = {}) {
         }),
     };
     return defineFeature(BILLING_FOUNDATION_FEATURE, (r) => {
-        r.describe("Plugin host for subscription billing. Manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers, a `plan-switch-preview` query and a dormant billing-plans dashboard screen/panel from the catalog. Several providers can be mounted at once: new checkouts are offered by every enabled provider (enabled means keys set and billingLive on, or simply mounted for plugins without `isBillingEnabled`), the customer picks one in the plan panel and `start-plan-checkout` takes a `providerName`. An existing subscription stays with the provider that stored it, so the plan list and every switch follow that provider. A plan switch is either hosted (`createPlanSwitchSession` answers a url) or in-app (`previewPlanSwitch` shows the proration, `applyPlanSwitch` runs after the customer confirms; `switch-plan` then answers `{ applied: true }` and records the consent). `consumerProtection.providerTexts` overrides the checkout note and the VAT note per provider. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event, which catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block: use `subscription-stripe`, `subscription-mollie` or `subscription-dodo` unless you are writing a new payment provider.");
+        r.describe("Plugin host for subscription billing. Manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers, a `plan-switch-preview` query and a dormant billing-plans dashboard screen/panel from the catalog. Several providers can be mounted at once: new checkouts are offered by every enabled provider (enabled means keys set and billingLive on, or simply mounted for plugins without `isBillingEnabled`), the customer picks one in the plan panel and `start-plan-checkout` takes a `providerName`. An existing subscription stays with the provider that stored it, so the plan list and every switch follow that provider. A plan switch is either hosted (`createPlanSwitchSession` answers a url) or in-app (`previewPlanSwitch` shows the proration, `applyPlanSwitch` runs after the customer confirms; `switch-plan` then answers `{ applied: true }` and records the consent). `consumerProtection.providerTexts` overrides the checkout note and the VAT note per provider. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event, which catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block: use `subscription-stripe`, `subscription-mollie` or `subscription-paddle` unless you are writing a new payment provider.");
         r.uiHints({
             displayLabel: "Billing · Foundation",
             category: "billing",

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

@@ -25,6 +25,7 @@ import { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework
 import * as z from "zod";
 import { assertCheckoutAllowed, openCheckout, startProviderCheckout, } from "../checkout-core.js";
 import { assertValidOrderItem, consentCheckoutFields, consentPayloadSchema, prepareConsent, recordConsent, } from "../consumer-protection/consent-gate.js";
+import { withOwnProviderCustomer } from "../one-off-customer.js";
 const createCheckoutSessionSchema = z.object({
     /** Welcher Provider — entityName eines registrierten subscription-
      *  Plugins ("stripe" / "paypal" / ...). */
@@ -58,8 +59,13 @@ export function createCheckoutSessionHandler(options) {
         handler: async (event, ctx) => {
             // @cast-boundary engine-payload — dispatcher-zod-validated payload
             const payload = event.payload;
-            const openOptions = { baseUrl: options.baseUrl, catalog: options.catalog, now: options.now };
-            const checkoutInput = {
+            const openOptions = {
+                baseUrl: options.baseUrl,
+                catalog: options.catalog,
+                now: options.now,
+                authorizeOneOffCheckout: options.authorizeOneOffCheckout,
+            };
+            const requestedInput = {
                 providerName: payload.providerName,
                 priceId: payload.priceId,
                 successUrl: payload.successUrl,
@@ -67,6 +73,7 @@ export function createCheckoutSessionHandler(options) {
                 ...(payload.providerCustomerId && { providerCustomerId: payload.providerCustomerId }),
                 ...(payload.mode && { mode: payload.mode }),
             };
+            const checkoutInput = await withOwnProviderCustomer(ctx, requestedInput);
             if (!consumerProtection) {
                 const result = await openCheckout(ctx, openOptions, checkoutInput);
                 return {

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

@@ -6,6 +6,7 @@ export declare const processPaymentEventSchema: z.ZodObject<{
     providerCheckoutId: z.ZodOptional<z.ZodString>;
     providerCustomerId: z.ZodString;
     priceId: z.ZodString;
+    quantity: z.ZodOptional<z.ZodNumber>;
     consentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const processPaymentEventHandler: WriteHandlerDef;

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

@@ -20,6 +20,7 @@ export const processPaymentEventSchema = z.object({
     providerCheckoutId: z.string().min(1).max(200).optional(),
     providerCustomerId: z.string().min(1).max(200),
     priceId: z.string().min(1).max(200),
+    quantity: z.number().int().positive().optional(),
     consentId: z.string().min(1).max(100).optional(),
 });
 // SystemAdmin-only: this handler is called exclusively by the programmatic
@@ -72,6 +73,7 @@ export const processPaymentEventHandler = {
             providerName: payload.providerName,
             providerCustomerId: encryptedFields.providerCustomerId,
             priceId: payload.priceId,
+            ...(payload.quantity !== undefined && { quantity: payload.quantity }),
             ...(payload.consentId !== undefined && { consentId: payload.consentId }),
         };
         const headers = {

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

@@ -10,7 +10,7 @@ export { getSubscriptionForTenant, type SubscriptionView } from "./get-subscript
 export { paymentsProjectionTable, subscriptionsProjectionTable } from "./projection.ts";
 export { billingPlansPanel, createBillingPlansScreen } from "./screens.ts";
 export { createSubscriptionTierSync, effectiveTierFromSubscription, SUBSCRIPTION_WEBHOOK_PATH, type SubscriptionTierSyncDeps, type TierSyncResult, } from "./subscription-tier-sync.ts";
-export { type BillingFoundationOptions, type BillingPlanBenefit, type BillingPlanCatalog, type BillingPlanContactCard, type BillingPlanPrice, type BillingPlansResult, type BillingPlanView, type BillingProviderView, type ConsumerProtectionOptions, KNOWN_RECURRING_INTERVALS, type LegalLinkSet, type PaymentEvent, type PlanSwitchPreview, type ProviderPrice, type ProviderSubscriptionSnapshot, type RecurringInterval, type SubscriptionEvent, type SubscriptionProviderPlugin, } from "./types.ts";
+export { type BillingFoundationOptions, type BillingPlanBenefit, type BillingPlanCatalog, type BillingPlanContactCard, type BillingPlanPrice, type BillingPlansResult, type BillingPlanView, type BillingProviderView, type ConsumerProtectionOptions, KNOWN_RECURRING_INTERVALS, type LegalLinkSet, type OneOffCheckoutRequest, type OneOffCheckoutVerdict, type PaymentEvent, type PlanSwitchPreview, type ProviderPrice, type ProviderSubscriptionSnapshot, type RecurringInterval, type SubscriptionEvent, type SubscriptionProviderPlugin, } from "./types.ts";
 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 "./web/constants.ts";
 export { CONSENT_LOCALES, type ConsentLocale, resolveConsentLocale, } from "./web/consumer-protection/consent-locale.ts";
 export { createSubscriptionWebhookRoute, type SubscriptionWebhookRouteOptions, } from "./webhook-handler.ts";

package/dist/billing-foundation/one-off-checkout-gate.d.ts

@@ -0,0 +1,9 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { BillingFoundationOptions, SubscriptionProviderPlugin } from "./types.ts";
+type OneOffCheckoutInput = {
+    readonly providerName: string;
+    readonly priceId: string;
+};
+export declare function assertOneOffPriceAllowed(plugin: SubscriptionProviderPlugin, input: OneOffCheckoutInput): void;
+export declare function assertOneOffAuthorized(ctx: HandlerContext, authorize: BillingFoundationOptions["authorizeOneOffCheckout"], input: OneOffCheckoutInput): Promise<void>;
+export {};

package/dist/billing-foundation/one-off-checkout-gate.js

@@ -0,0 +1,30 @@
+// Gates for mode:"payment" checkouts, run before any provider call.
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+// Missing/empty oneOffPriceIds rejects every payment checkout: same
+// "no gate configured yet = closed" default as the priceToTier gate.
+export function assertOneOffPriceAllowed(plugin, input) {
+    const oneOffPriceIds = plugin.oneOffPriceIds ?? [];
+    if (!oneOffPriceIds.includes(input.priceId)) {
+        throw new UnprocessableError("unknown_price", {
+            i18nKey: "billing-foundation.errors.unknownPrice",
+            message: `subscription-foundation: priceId "${input.priceId}" is not in provider "${input.providerName}"'s oneOffPriceIds`,
+        });
+    }
+}
+// The app's own gate (for example a tier check): without it every price in
+// oneOffPriceIds is open to any TenantAdmin.
+export async function assertOneOffAuthorized(ctx, authorize, input) {
+    const verdict = authorize
+        ? await authorize(ctx, {
+            tenantId: ctx.user.tenantId,
+            providerName: input.providerName,
+            priceId: input.priceId,
+        })
+        : { allowed: true };
+    if (!verdict.allowed) {
+        throw new UnprocessableError(verdict.reason, {
+            i18nKey: verdict.i18nKey,
+            message: `billing-foundation: authorizeOneOffCheckout rejected the one-off checkout (${verdict.reason})`,
+        });
+    }
+}

package/dist/billing-foundation/one-off-customer.d.ts

@@ -0,0 +1,6 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { OpenCheckoutInput } from "./checkout-core.ts";
+/** A one-off checkout without an explicit customer reuses the provider customer of the
+ *  tenant's own subscription at the same provider, so the buyer is not asked again and
+ *  does not become a second customer. The foreign-customer guard still runs afterwards. */
+export declare function withOwnProviderCustomer(ctx: HandlerContext, input: OpenCheckoutInput): Promise<OpenCheckoutInput>;

package/dist/billing-foundation/one-off-customer.js

@@ -0,0 +1,12 @@
+import { getSubscriptionForTenant } from "./get-subscription-for-tenant.js";
+/** A one-off checkout without an explicit customer reuses the provider customer of the
+ *  tenant's own subscription at the same provider, so the buyer is not asked again and
+ *  does not become a second customer. The foreign-customer guard still runs afterwards. */
+export async function withOwnProviderCustomer(ctx, input) {
+    if (input.mode !== "payment" || input.providerCustomerId)
+        return input;
+    const own = await getSubscriptionForTenant(ctx, ctx.user.tenantId);
+    return own && own.providerName === input.providerName && own.providerCustomerId
+        ? { ...input, providerCustomerId: own.providerCustomerId }
+        : input;
+}

package/dist/billing-foundation/plan-catalog.js

@@ -169,5 +169,6 @@ export function toBillingPlansResult(catalog, base, views) {
         plans: views.plans,
         ...(views.inAppSwitch && { inAppPlanSwitch: true }),
         ...(catalog.contact !== undefined && { contact: catalog.contact }),
+        ...(catalog.priceNoteKey !== undefined && { priceNoteKey: catalog.priceNoteKey }),
     };
 }

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

@@ -73,6 +73,8 @@ export type PaymentEvent = {
     readonly providerCustomerId: string;
     /** Provider's own price/plan-ID of the purchased item. */
     readonly priceId: string;
+    /** Number of units bought; absent = 1. */
+    readonly quantity?: number;
 };
 export type SubscriptionProviderPlugin = {
     /** Human-readable provider name for the plan panel's provider switch. */
@@ -270,6 +272,10 @@ export type PlanSwitchPreview = {
     readonly currency: string;
     /** Credit for the unused time on the old plan, smallest currency unit. */
     readonly credit: number;
+    /** Recurring price per period as charged by the provider, smallest unit, tax included. */
+    readonly recurringAmount?: number;
+    /** Tax part of `recurringAmount`; null when the provider reports none. */
+    readonly recurringTax?: number | null;
     readonly effectiveAt: string;
 };
 export type ProviderSubscriptionSnapshot = {
@@ -332,6 +338,8 @@ export type BillingPlanCatalog<TTier extends string = string> = {
     readonly providerName?: string;
     /** Rendered as the last card, no price, visible to `viewRoles` regardless of `purchaseRoles`. */
     readonly contact?: BillingPlanContactCard;
+    /** App i18n key for a small note under every card's price, e.g. "plus VAT" when catalog prices are net. */
+    readonly priceNoteKey?: string;
 };
 export type LegalLinkSet = {
     readonly terms: string;
@@ -375,6 +383,18 @@ export type ConsumerProtectionOptions = {
      *  one set per consent locale (`de` and `en` required). */
     readonly legalLinks: LegalLinkSet | Readonly<Record<ConsentLocale, LegalLinkSet>>;
 };
+export type OneOffCheckoutRequest = {
+    readonly tenantId: TenantId;
+    readonly providerName: string;
+    readonly priceId: string;
+};
+export type OneOffCheckoutVerdict = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+    readonly i18nKey: string;
+};
 export type BillingFoundationOptions<TTier extends string = string> = {
     /** Absolute http(s) URL. Its origin is the only redirect origin
      *  create-checkout-session/create-portal-session (when set) and the plan
@@ -384,6 +404,9 @@ export type BillingFoundationOptions<TTier extends string = string> = {
      *  NOT via `new URL(path, baseUrl)` (which would drop the prefix). */
     readonly baseUrl?: string;
     readonly catalog?: BillingPlanCatalog<TTier>;
+    /** Runs before every one-off (mode "payment") checkout, after the oneOffPriceIds gate and
+     *  before any provider call; a rejection becomes an UnprocessableError with `reason` as code. */
+    readonly authorizeOneOffCheckout?: (ctx: HandlerContext, request: OneOffCheckoutRequest) => Promise<OneOffCheckoutVerdict>;
     /** Enables the consent gate on checkout; requires `baseUrl`. */
     readonly consumerProtection?: ConsumerProtectionOptions;
     /** Injectable clock for the stale-incomplete-subscription check
@@ -446,6 +469,8 @@ export type BillingPlansResult = {
     readonly inAppPlanSwitch?: true;
     /** Present only when `catalog.contact` is configured. */
     readonly contact?: BillingPlanContactCard;
+    /** Present only when `catalog.priceNoteKey` is configured. */
+    readonly priceNoteKey?: string;
     /** Present only when `consumerProtection` is configured. */
     readonly consumerProtection?: {
         readonly consentTexts: Readonly<Record<"de" | "en", {

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

@@ -166,6 +166,7 @@ export function BillingPlansPanel(_props) {
                     : {
                         amount: formatMoney(shownPrice.unitAmount, shownPrice.currency, locale),
                         ...(fromPrice !== undefined && { prefix: t("billing-foundation.plans.priceFrom") }),
+                        ...(result.priceNoteKey !== undefined && { note: t(result.priceNoteKey) }),
                         ...(key !== undefined && {
                             period: t(key, {
                                 count: new Intl.NumberFormat(locale).format(shownPrice.intervalCount ?? 1),

package/dist/billing-foundation/web/plan-switch-confirm-dialog.js

@@ -6,6 +6,7 @@ import { CONSENT_TEXT_OUTDATED_CODE, } from "./checkout-consent-dialog.js";
 import { SubscriptionFoundationHandlers, SubscriptionFoundationQueries } from "./constants.js";
 import { resolveConsentLocale } from "./consumer-protection/consent-locale.js";
 import { intervalKey } from "./plan-price.js";
+import { recurringAmountsOf } from "./plan-switch-recurring.js";
 // kumiko-lint-ignore no-custom-primitives Uses usePrimitives().Modal internally, name is a billing domain action, not a primitive reimplementation
 export function PlanSwitchConfirmDialog({ open, onOpenChange, tier, fromPlanName, toPlanName, consumerProtection, onApplied, onConsentTextOutdated, }) {
     const t = useTranslation();
@@ -48,11 +49,14 @@ export function PlanSwitchConfirmDialog({ open, onOpenChange, tier, fromPlanName
     const reply = previewQuery.data;
     const money = (amount, currency) => formatMoney(amount, currency, locale);
     const recurringKey = reply === null ? undefined : intervalKey(reply.target);
-    const recurringPrice = reply === null
+    const recurring = reply === null ? null : recurringAmountsOf(reply);
+    const recurringPrice = reply === null || recurring === null
         ? ""
-        : `${money(reply.target.unitAmount, reply.target.currency)}${recurringKey === undefined
+        : `${money(recurring.amount, recurring.currency)}${recurringKey === undefined
             ? ""
-            : ` ${t(recurringKey, { count: new Intl.NumberFormat(locale).format(reply.target.intervalCount ?? 1) })}`}`;
+            : ` ${t(recurringKey, { count: new Intl.NumberFormat(locale).format(reply.target.intervalCount ?? 1) })}`}${recurring.tax === null
+            ? ""
+            : ` (${t("billing-foundation.planSwitch.includesTax", { tax: money(recurring.tax, recurring.currency) })})`}`;
     return (_jsx(Modal, { open: open, onOpenChange: onOpenChange, title: t("billing-foundation.planSwitch.title"), testId: "plan-switch-confirm-dialog", children: _jsxs("div", { className: "flex flex-col gap-4", children: [_jsx(Text, { children: t("billing-foundation.planSwitch.summary", { from: fromPlanName, to: toPlanName }) }), previewQuery.error !== null && (_jsx(Banner, { variant: "error", testId: "plan-switch-preview-error", children: t(previewQuery.error.i18nKey, previewQuery.error.i18nParams) })), previewQuery.loading && reply === null && (_jsx(Banner, { variant: "loading", testId: "plan-switch-preview-loading", children: t("kumiko.widget.loading") })), reply !== null && (_jsxs("div", { className: "flex flex-col gap-1", "data-testid": "plan-switch-summary", children: [_jsxs(Text, { children: [t("billing-foundation.planSwitch.dueNow", {
                                     amount: money(reply.preview.amountDueNow, reply.preview.currency),
                                 }), reply.preview.tax !== null &&

package/dist/billing-foundation/web/plan-switch-recurring.d.ts

@@ -0,0 +1,16 @@
+import type { PlanSwitchPreview } from "../types.ts";
+type RecurringSource = {
+    readonly preview: PlanSwitchPreview;
+    readonly target: {
+        readonly unitAmount: number;
+        readonly currency: string;
+    };
+};
+export type RecurringAmounts = {
+    readonly amount: number;
+    readonly currency: string;
+    readonly tax: number | null;
+};
+/** The provider's gross recurring price when it reports one, else the catalog's unit amount. */
+export declare function recurringAmountsOf({ preview, target }: RecurringSource): RecurringAmounts;
+export {};

package/dist/billing-foundation/web/plan-switch-recurring.js

@@ -0,0 +1,10 @@
+/** The provider's gross recurring price when it reports one, else the catalog's unit amount. */
+export function recurringAmountsOf({ preview, target }) {
+    return preview.recurringAmount === undefined
+        ? { amount: target.unitAmount, currency: target.currency, tax: null }
+        : {
+            amount: preview.recurringAmount,
+            currency: preview.currency,
+            tax: preview.recurringTax ?? null,
+        };
+}

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

@@ -61,6 +61,7 @@ export function createSubscriptionWebhookRoute(options = {}) {
                         providerName: parsed.providerName,
                         providerCustomerId: parsed.providerCustomerId,
                         priceId: parsed.priceId,
+                        ...(parsed.quantity !== undefined && { quantity: parsed.quantity }),
                         ...(parsed.consentId !== undefined && { consentId: parsed.consentId }),
                         ...(parsed.providerCheckoutId !== undefined && {
                             providerCheckoutId: parsed.providerCheckoutId,

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

@@ -54,7 +54,7 @@ export function createCapsUsageQuery(caps, usageRoles) {
             const config = override === undefined ? ctx.config : ctx.tenants.config?.(targetTenantId);
             const rows = await Promise.all(caps.map(async (cap) => {
                 const used = await cap.usage(db, targetTenantId);
-                const limit = await cap.limit(tier, { config });
+                const limit = cap.showLimit === false ? null : await cap.limit(tier, { config });
                 const base = {
                     id: cap.id,
                     label: cap.label,
@@ -63,8 +63,8 @@ export function createCapsUsageQuery(caps, usageRoles) {
                     ...(cap.icon !== undefined && { icon: cap.icon }),
                     ...(cap.accentColor !== undefined && { accentColor: cap.accentColor }),
                 };
-                if (used === null) {
-                    return { ...base, used: null, fraction: 0, tone: "default", percent: null };
+                if (used === null || cap.showLimit === false) {
+                    return { ...base, used, fraction: 0, tone: "default", percent: null };
                 }
                 const fraction = computeFraction(used, limit);
                 return {

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

@@ -10,6 +10,8 @@ export type CapSpec = {
     readonly usage: (db: TenantDb, tenantId: TenantId) => Promise<number | null>;
     readonly usageBatch?: (db: TenantDb, tenantIds: readonly TenantId[]) => Promise<Map<TenantId, number | null>>;
     readonly unit?: CapUnit;
+    /** `false` shows the counter only: the limit is not sent to the client; enforcement stays with cap-counter. Default true. */
+    readonly showLimit?: boolean;
     /** Icon chip on the dashboard cards. Optional — omitted renders the card
      *  without an icon, same as before this field existed. */
     readonly icon?: CapIconKey;

package/dist/channel-in-app/handlers/mark-all-read.write.d.ts

@@ -1,4 +1,4 @@
 import * as z from "zod";
 export declare const markAllReadWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"markAllRead", z.ZodObject<{}, z.core.$strip>, {
     marked: number;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/channel-in-app/handlers/mark-read.write.d.ts

@@ -3,4 +3,4 @@ export declare const markReadWrite: import("@cosmicdrift/kumiko-types/define-han
     id: z.ZodNumber;
 }, z.core.$strip>, {
     id: number | undefined;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/compliance-profiles/handlers/set-profile.write.d.ts

@@ -10,4 +10,4 @@ export declare const setProfileWrite: import("@cosmicdrift/kumiko-types/define-h
 }, z.core.$strip>, {
     profileKey: "de-hr-dsgvo-hgb" | "eu-dsgvo" | "swiss-dsg";
     isNew: boolean;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/compliance-profiles/web/compliance-profile-catalog.js

@@ -5,6 +5,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // this is reference material for the tenant admin.
 import { usePrimitives, useQuery, useTranslation, } from "@cosmicdrift/kumiko-renderer";
 import { ComplianceProfileQueries } from "./constants.js";
+// The select options above carry locale translations; the catalog reuses them so both
+// name a profile alike. A profile without an option key keeps its source label.
+function profileLabel(profile, t) {
+    const optionKey = `compliance-profiles:entity:__action-form__:field:profileKey:option:${profile.key}`;
+    const translated = t(optionKey);
+    return translated === optionKey ? profile.label : translated;
+}
 export function ComplianceProfileCatalog(_props) {
     const { Banner, Text } = usePrimitives();
     const t = useTranslation();
@@ -15,5 +22,5 @@ export function ComplianceProfileCatalog(_props) {
     if (query.error) {
         return (_jsx(Banner, { variant: "error", testId: "compliance-profile-catalog-error", children: _jsx(Text, { children: t(query.error.i18nKey, query.error.i18nParams) }) }));
     }
-    return (_jsx("ul", { className: "flex flex-col gap-2 text-sm", "data-testid": "compliance-profile-catalog", children: (query.data?.profiles ?? []).map((profile) => (_jsxs("li", { "data-profile-key": profile.key, children: [_jsx("strong", { children: profile.label }), " \u2014 ", profile.region, " \u2014 ", profile.authorityContact] }, profile.key))) }));
+    return (_jsx("ul", { className: "flex flex-col gap-2 text-sm", "data-testid": "compliance-profile-catalog", children: (query.data?.profiles ?? []).map((profile) => (_jsxs("li", { "data-profile-key": profile.key, children: [_jsx("strong", { children: profileLabel(profile, t) }), " \u2014 ", profile.region, " \u2014", " ", profile.authorityContact] }, profile.key))) }));
 }

package/dist/config/handlers/reset.write.d.ts

@@ -9,4 +9,4 @@ export declare const resetWrite: import("@cosmicdrift/kumiko-types/define-handle
 }, z.core.$strip>, {
     key: string;
     scope: import("@cosmicdrift/kumiko-types/config-scope").ConfigScope;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/config/handlers/set.write.d.ts

@@ -11,4 +11,4 @@ export declare const setWrite: import("@cosmicdrift/kumiko-types/define-handler"
     key: string;
     value: string | number | boolean;
     scope: import("@cosmicdrift/kumiko-types/config-scope").ConfigScope;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/crypto-shredding/handlers/forget-subject.write.d.ts

@@ -48,4 +48,4 @@ export declare const forgetSubjectWrite: import("@cosmicdrift/kumiko-types/defin
     reason: z.ZodString;
 }, z.core.$strip>, {
     subjectKey: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/delivery/handlers/resubscribe-address.write.d.ts

@@ -6,4 +6,4 @@ export declare const resubscribeAddressWrite: import("@cosmicdrift/kumiko-types/
 }, z.core.$strip>, {
     notificationType: string;
     channel: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/delivery/handlers/resubscribe-user.write.d.ts

@@ -6,4 +6,4 @@ export declare const resubscribeUserWrite: import("@cosmicdrift/kumiko-types/def
 }, z.core.$strip>, {
     notificationType: string;
     channel: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/delivery/handlers/set-preference.write.d.ts

@@ -7,4 +7,4 @@ export declare const setPreferenceWrite: import("@cosmicdrift/kumiko-types/defin
     notificationType: string;
     channel: string;
     enabled: boolean;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/delivery/handlers/unsubscribe-address.write.d.ts

@@ -12,4 +12,4 @@ export declare const unsubscribeAddressWrite: import("@cosmicdrift/kumiko-types/
 }, z.core.$strip>, {
     notificationType: string;
     channel: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/delivery/handlers/unsubscribe-user.write.d.ts

@@ -6,4 +6,4 @@ export declare const unsubscribeUserWrite: import("@cosmicdrift/kumiko-types/def
 }, z.core.$strip>, {
     notificationType: string;
     channel: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/feature-toggles/handlers/set.write.d.ts

@@ -7,4 +7,4 @@ export declare function createSetWriteHandler(getRuntime: (() => GlobalFeatureTo
     featureName: string;
     enabled: boolean;
     previousEnabled: boolean | null;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/file-foundation/read-file-ref-content.d.ts

@@ -5,6 +5,8 @@ export type FileRefContent = {
     readonly contentType: string;
     readonly tenantId: string;
     readonly size: number;
+    /** As stored: personal data that may be PII ciphertext. Decrypt before showing or sending it. */
+    readonly fileName: string;
 };
 export declare function fileContextForTenant(ctx: {
     readonly services: {