@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

package/packages/bundled-features/src/auth-mfa/web/mfa-client.ts

@@ -8,6 +8,7 @@
 
 // kumiko-lint-ignore cross-feature-import client-only types, the feature's server barrel has no web/ re-export
 import {
+  failureFromErrorField,
   type LoginFailure,
   type LoginResponse,
   toLoginResponse,
@@ -36,13 +37,7 @@ export async function verifyMfaChallenge(
     token?: string;
     user?: LoginResponse["user"];
     landingPath?: string;
-    error?:
-      | {
-          code?: string;
-          message?: string;
-          details?: { reason?: string; retryAfterSeconds?: number };
-        }
-      | string;
+    error?: unknown;
   };
   if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
     return {
@@ -50,20 +45,7 @@ export async function verifyMfaChallenge(
       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") };
 }
 
 export type MfaSetupPreauthStart = {
@@ -101,13 +83,7 @@ export async function startMfaSetupPreauth(
     setupToken?: string;
     otpauthUri?: string;
     recoveryCodes?: readonly string[];
-    error?:
-      | {
-          code?: string;
-          message?: string;
-          details?: { reason?: string; retryAfterSeconds?: number };
-        }
-      | string;
+    error?: unknown;
   };
   if (
     body.isSuccess === true &&
@@ -124,20 +100,7 @@ export async function startMfaSetupPreauth(
       },
     };
   }
-  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
@@ -165,13 +128,7 @@ export async function confirmMfaSetupPreauth(
     token?: string;
     user?: LoginResponse["user"];
     landingPath?: string;
-    error?:
-      | {
-          code?: string;
-          message?: string;
-          details?: { reason?: string; retryAfterSeconds?: number };
-        }
-      | string;
+    error?: unknown;
   };
   if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
     return {
@@ -179,18 +136,5 @@ export async function confirmMfaSetupPreauth(
       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/packages/bundled-features/src/billing-foundation/changes.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "authorizeOneOffCheckout hook gates one-off checkouts per tenant",
+    "detail": "BillingFoundationOptions.authorizeOneOffCheckout runs before every one-off (mode payment) checkout, after the oneOffPriceIds gate and before any provider call. A rejection becomes an UnprocessableError with the hook's reason as code. Without the hook the behavior is unchanged."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "One-off checkouts reuse the tenant's provider customer",
+    "detail": "create-checkout-session with mode payment and no providerCustomerId now passes the customer id of the tenant's own subscription at the same provider, so Stripe also receives the customer on one-off checkouts. The foreign-customer guard still applies."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "PaymentEvent carries the bought quantity",
+    "detail": "PaymentEvent.quantity (absent means 1) reaches the stored payment-received event payload, which stays readable for events stored before. Apps that grant credits per pack have to multiply by it. No read-model column."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Plan-switch preview shows the recurring price gross",
+    "detail": "PlanSwitchPreview.recurringAmount and recurringTax carry the provider's gross recurring price; the confirm dialog shows them with the tax when set and falls back to the catalog price otherwise. subscription-paddle fills them from recurring_transaction_details."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Plan cards can show a note under the price",
+    "detail": "`BillingPlanCatalog.priceNoteKey` (an app i18n key) renders a small note under the price of every plan card, e.g. \"plus VAT\" when catalog prices are net. `PlanCardPrice` gets an optional `note`."
+  },
   {
     "version": "0.390.0",
     "type": "fix",

package/packages/bundled-features/src/billing-foundation/checkout-core.ts

@@ -12,7 +12,12 @@ import {
   UnprocessableError,
 } from "@cosmicdrift/kumiko-framework/errors";
 import { getSubscriptionForTenant } from "./get-subscription-for-tenant.ts";
-import type { BillingPlanCatalog, SubscriptionProviderPlugin } from "./types.ts";
+import { assertOneOffAuthorized, assertOneOffPriceAllowed } from "./one-off-checkout-gate.ts";
+import type {
+  BillingFoundationOptions,
+  BillingPlanCatalog,
+  SubscriptionProviderPlugin,
+} from "./types.ts";
 import {
   BILLING_FOUNDATION_FEATURE,
   isSubscriptionBlockingCheckout,
@@ -264,6 +269,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;
@@ -311,21 +317,6 @@ function assertSubscriptionPriceAllowed(
   }
 }
 
-// Missing/empty oneOffPriceIds rejects every payment checkout: same
-// "no gate configured yet = closed" default as the priceToTier gate.
-function assertOneOffPriceAllowed(
-  plugin: SubscriptionProviderPlugin,
-  input: OpenCheckoutInput,
-): void {
-  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`,
-    });
-  }
-}
-
 type CheckoutCapableProvider = SubscriptionProviderPlugin & {
   readonly createCheckoutSession: NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>;
 };
@@ -373,6 +364,7 @@ export async function assertCheckoutAllowed(
         : await assertNoActiveSubscription(ctx, options.now());
   } else {
     assertOneOffPriceAllowed(plugin, input);
+    await assertOneOffAuthorized(ctx, options.authorizeOneOffCheckout, input);
   }
 
   // Rejects a foreign tenant's provider-customer id — otherwise the checkout

package/packages/bundled-features/src/billing-foundation/events.ts

@@ -105,6 +105,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(),
 });
 export type PaymentEventPayload = z.infer<typeof paymentEventPayloadSchema>;

package/packages/bundled-features/src/billing-foundation/feature.ts

@@ -138,7 +138,7 @@ export function createBillingFoundationFeature<TTier extends string = string>(
     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.",
+        "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",

package/packages/bundled-features/src/billing-foundation/handlers/create-checkout-session.write.ts

@@ -39,6 +39,7 @@ import {
   prepareConsent,
   recordConsent,
 } from "../consumer-protection/consent-gate.ts";
+import { withOwnProviderCustomer } from "../one-off-customer.ts";
 import type {
   ProviderPrice,
   ResolvedBillingFoundationOptions,
@@ -86,8 +87,13 @@ export function createCheckoutSessionHandler(
       // @cast-boundary engine-payload — dispatcher-zod-validated payload
       const payload = event.payload as CreateCheckoutSessionPayload;
 
-      const openOptions = { baseUrl: options.baseUrl, catalog: options.catalog, now: options.now };
-      const checkoutInput: OpenCheckoutInput = {
+      const openOptions = {
+        baseUrl: options.baseUrl,
+        catalog: options.catalog,
+        now: options.now,
+        authorizeOneOffCheckout: options.authorizeOneOffCheckout,
+      };
+      const requestedInput: OpenCheckoutInput = {
         providerName: payload.providerName,
         priceId: payload.priceId,
         successUrl: payload.successUrl,
@@ -95,6 +101,7 @@ export function createCheckoutSessionHandler(
         ...(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);

package/packages/bundled-features/src/billing-foundation/handlers/process-payment-event.write.ts

@@ -31,6 +31,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(),
 });
 type ProcessPaymentEventPayload = z.infer<typeof processPaymentEventSchema>;
@@ -97,6 +98,7 @@ export const processPaymentEventHandler: WriteHandlerDef = {
       providerName: payload.providerName,
       providerCustomerId: encryptedFields.providerCustomerId,
       priceId: payload.priceId,
+      ...(payload.quantity !== undefined && { quantity: payload.quantity }),
       ...(payload.consentId !== undefined && { consentId: payload.consentId }),
     };
     const headers: PaymentEventHeaders = {

package/packages/bundled-features/src/billing-foundation/index.ts

@@ -66,6 +66,8 @@ export {
   type ConsumerProtectionOptions,
   KNOWN_RECURRING_INTERVALS,
   type LegalLinkSet,
+  type OneOffCheckoutRequest,
+  type OneOffCheckoutVerdict,
   type PaymentEvent,
   type PlanSwitchPreview,
   type ProviderPrice,

package/packages/bundled-features/src/billing-foundation/one-off-checkout-gate.ts

@@ -0,0 +1,44 @@
+// Gates for mode:"payment" checkouts, run before any provider call.
+
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import type { BillingFoundationOptions, SubscriptionProviderPlugin } from "./types.ts";
+
+type OneOffCheckoutInput = { readonly providerName: string; readonly priceId: string };
+
+// Missing/empty oneOffPriceIds rejects every payment checkout: same
+// "no gate configured yet = closed" default as the priceToTier gate.
+export function assertOneOffPriceAllowed(
+  plugin: SubscriptionProviderPlugin,
+  input: OneOffCheckoutInput,
+): void {
+  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: HandlerContext,
+  authorize: BillingFoundationOptions["authorizeOneOffCheckout"],
+  input: OneOffCheckoutInput,
+): Promise<void> {
+  const verdict = authorize
+    ? await authorize(ctx, {
+        tenantId: ctx.user.tenantId,
+        providerName: input.providerName,
+        priceId: input.priceId,
+      })
+    : { allowed: true as const };
+  if (!verdict.allowed) {
+    throw new UnprocessableError(verdict.reason, {
+      i18nKey: verdict.i18nKey,
+      message: `billing-foundation: authorizeOneOffCheckout rejected the one-off checkout (${verdict.reason})`,
+    });
+  }
+}

package/packages/bundled-features/src/billing-foundation/one-off-customer.ts

@@ -0,0 +1,17 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { OpenCheckoutInput } from "./checkout-core.ts";
+import { getSubscriptionForTenant } from "./get-subscription-for-tenant.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 async function withOwnProviderCustomer(
+  ctx: HandlerContext,
+  input: OpenCheckoutInput,
+): Promise<OpenCheckoutInput> {
+  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/packages/bundled-features/src/billing-foundation/plan-catalog.ts

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

package/packages/bundled-features/src/billing-foundation/types.ts

@@ -129,6 +129,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;
 };
 
 // =============================================================================
@@ -368,6 +370,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;
 };
 
@@ -445,6 +451,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 = {
@@ -504,6 +512,16 @@ export type ConsumerProtectionOptions = {
   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
@@ -513,6 +531,12 @@ 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
@@ -587,6 +611,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<

package/packages/bundled-features/src/billing-foundation/web/billing-plans-panel.tsx

@@ -238,6 +238,7 @@ export function BillingPlansPanel(_props: ExtensionSectionProps): ReactNode {
             : {
                 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/packages/bundled-features/src/billing-foundation/web/plan-switch-confirm-dialog.tsx

@@ -15,6 +15,7 @@ import {
 import { SubscriptionFoundationHandlers, SubscriptionFoundationQueries } from "./constants.ts";
 import { resolveConsentLocale } from "./consumer-protection/consent-locale.ts";
 import { intervalKey } from "./plan-price.ts";
+import { recurringAmountsOf } from "./plan-switch-recurring.ts";
 
 type ConsumerProtectionView = NonNullable<BillingPlansResult["consumerProtection"]>;
 
@@ -99,13 +100,18 @@ export function PlanSwitchConfirmDialog({
   const reply = previewQuery.data;
   const money = (amount: number, currency: string) => formatMoney(amount, currency, locale);
   const recurringKey = reply === null ? undefined : intervalKey(reply.target);
+  const recurring = reply === null ? null : recurringAmountsOf(reply);
   const recurringPrice =
-    reply === null
+    reply === null || recurring === null
       ? ""
-      : `${money(reply.target.unitAmount, reply.target.currency)}${
+      : `${money(recurring.amount, recurring.currency)}${
           recurringKey === undefined
             ? ""
             : ` ${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 (

package/packages/bundled-features/src/billing-foundation/web/plan-switch-recurring.ts

@@ -0,0 +1,23 @@
+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 function recurringAmountsOf({ preview, target }: RecurringSource): RecurringAmounts {
+  return preview.recurringAmount === undefined
+    ? { amount: target.unitAmount, currency: target.currency, tax: null }
+    : {
+        amount: preview.recurringAmount,
+        currency: preview.currency,
+        tax: preview.recurringTax ?? null,
+      };
+}

package/packages/bundled-features/src/billing-foundation/webhook-handler.ts

@@ -105,6 +105,7 @@ export function createSubscriptionWebhookRoute(options: SubscriptionWebhookRoute
             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/packages/bundled-features/src/cap-overview/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Add CapSpec.showLimit to hide a cap's limit from the dashboard",
+    "detail": "showLimit: false makes caps:usage send limit null so the card shows the counter only; cap-counter enforcement is unchanged."
+  },
   {
     "version": "0.392.1",
     "type": "fix",

package/packages/bundled-features/src/cap-overview/handlers/caps-usage.query.ts

@@ -81,7 +81,7 @@ export function createCapsUsageQuery(
       const rows: CapUsageWithMeta[] = 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,
@@ -90,8 +90,8 @@ export function createCapsUsageQuery(
             ...(cap.icon !== undefined && { icon: cap.icon }),
             ...(cap.accentColor !== undefined && { accentColor: cap.accentColor }),
           };
-          if (used === null) {
-            return { ...base, used: null, fraction: 0, tone: "default" as const, percent: null };
+          if (used === null || cap.showLimit === false) {
+            return { ...base, used, fraction: 0, tone: "default" as const, percent: null };
           }
           const fraction = computeFraction(used, limit);
           return {

package/packages/bundled-features/src/cap-overview/types.ts

@@ -38,6 +38,8 @@ export type CapSpec = {
     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/packages/bundled-features/src/compliance-profiles/web/compliance-profile-catalog.tsx

@@ -22,6 +22,14 @@ type ListProfilesResponse = {
   readonly profiles: readonly ProfileSummary[];
 };
 
+// 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: ProfileSummary, t: (key: string) => string): string {
+  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: ExtensionSectionProps): ReactNode {
   const { Banner, Text } = usePrimitives();
   const t = useTranslation();
@@ -46,7 +54,8 @@ export function ComplianceProfileCatalog(_props: ExtensionSectionProps): ReactNo
     <ul className="flex flex-col gap-2 text-sm" data-testid="compliance-profile-catalog">
       {(query.data?.profiles ?? []).map((profile) => (
         <li key={profile.key} data-profile-key={profile.key}>
-          <strong>{profile.label}</strong> — {profile.region} — {profile.authorityContact}
+          <strong>{profileLabel(profile, t)}</strong> — {profile.region} —{" "}
+          {profile.authorityContact}
         </li>
       ))}
     </ul>

package/packages/bundled-features/src/file-foundation/read-file-ref-content.ts

@@ -13,9 +13,12 @@ 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;
 };
 
 type FileRefRow = {
+  readonly fileName: string;
   readonly storageKey: string;
   readonly mimeType: string;
   readonly tenantId: string;
@@ -61,7 +64,6 @@ export class FileStorageUnavailableError extends Error {
   }
 }
 
-// fileName of the row is never used: it is personal data and may be a PII ciphertext.
 export async function readFileRefContent(args: {
   readonly db: DbRunner | TenantDb;
   readonly filesForTenant: (tenantId: string) => FileContext | undefined;
@@ -85,7 +87,8 @@ export async function readFileRefContent(args: {
   });
   if (row === undefined) return null;
   const size = Number(row.size);
-  if (args.maxBytes !== undefined && size > args.maxBytes) {
+  // A size that is not a number counts as too large, so the limit cannot be skipped.
+  if (args.maxBytes !== undefined && !(size <= args.maxBytes)) {
     throw new FileRefTooLargeError(size);
   }
   const files = args.filesForTenant(row.tenantId);
@@ -93,5 +96,11 @@ export async function readFileRefContent(args: {
     throw new FileStorageUnavailableError();
   }
   const content = await files.refFromFileRef(row).read();
-  return { content, contentType: row.mimeType, tenantId: row.tenantId, size };
+  return {
+    content,
+    contentType: row.mimeType,
+    tenantId: row.tenantId,
+    size,
+    fileName: row.fileName,
+  };
 }

package/packages/bundled-features/src/files/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "createFileRefFromBytes takes a per-call maxSize",
+    "detail": "`CreateFileRefInput.maxSize` (bytes) replaces the route default for that call, so server-side generated files such as mail attachments can exceed the 10 MB upload default without raising it for browsers. A file field's own maxSize still applies first. `configuredMaxUploadBytes(registry)` returns the configured route limit in bytes, or undefined."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "canCallerReadFileRef answers the file read decision in handlers",
+    "detail": "`canCallerReadFileRef(ctx, fileRef)` applies the same rule as GET /files/:id: the configured accessGuard, otherwise the default guard with the configured privilegedRoles and the bound record's detail query. `createDefaultGuard` is exported from the files barrel. A handler that lists or links files no longer needs its own copy of the rule."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Projection entities are server-side attach targets for files",
+    "detail": "An entity declared on a projection (r.projection with entity) is a read-model entity: a files field on it can be the attachTo target of createFileRefFromBytes and uploadFileBytesBeforeTransaction, and the file read check uses the owning feature's `<name>:detail` query for it. The registry gets getReadModelEntity and getReadModelEntityOwner; two projections declaring an entity for the same source fail the boot. POST /files still accepts only r.entity targets, so a client can never attach to a read model. deleteFileRefsBoundToRecord soft-deletes the fileRefs of one record for owners that remove it without an r.entity delete."
+  },
   {
     "version": "0.379.0",
     "type": "improvement",