@cosmicdrift/kumiko-samples 0.387.0 → 0.388.0

package/samples/apps/use-all-bundled/e2e-billing-gallery/gallery-features.ts

@@ -16,9 +16,12 @@ import {
   createChannelEmailFeature,
   createInMemoryTransport,
 } from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import {
+  GALLERY_MOR_PRICE_IDS,
+  GALLERY_MOR_PROVIDER,
   GALLERY_OPERATOR_EMAIL,
   GALLERY_PLAN_PATH,
   GALLERY_PRICE_IDS,
@@ -28,25 +31,44 @@ import {
 
 export const galleryMailTransport = createInMemoryTransport();
 
-const PRICES: readonly ProviderPrice[] = [
-  {
-    priceId: GALLERY_PRICE_IDS.starter,
-    unitAmount: 900,
-    currency: "eur",
-    interval: "month",
-    intervalCount: 1,
-    active: true,
-    metadata: {},
-  },
-  {
-    priceId: GALLERY_PRICE_IDS.pro,
-    unitAmount: 1900,
+// The merchant-of-record mock is only offered to tenants the spec opts in, so
+// the single-provider flows keep their original screens.
+const morEnabledTenants = new Set<string>();
+
+export const GALLERY_MOR_ENABLE_PATH = "/gallery/mor/:tenantId";
+
+export function createGalleryMorEnableRoute(): ExtraRouteDefinition {
+  return {
+    method: "POST",
+    path: GALLERY_MOR_ENABLE_PATH,
+    entry: "anonymous",
+    handler: (c) => {
+      morEnabledTenants.add(c.req.param("tenantId") ?? "");
+      return c.body(null, 204);
+    },
+  };
+}
+
+function monthlyPrice(priceId: string, unitAmount: number): ProviderPrice {
+  return {
+    priceId,
+    unitAmount,
     currency: "eur",
     interval: "month",
     intervalCount: 1,
     active: true,
     metadata: {},
-  },
+  };
+}
+
+const PRICES: readonly ProviderPrice[] = [
+  monthlyPrice(GALLERY_PRICE_IDS.starter, 900),
+  monthlyPrice(GALLERY_PRICE_IDS.pro, 1900),
+];
+
+const MOR_PRICES: readonly ProviderPrice[] = [
+  monthlyPrice(GALLERY_MOR_PRICE_IDS.starter, 990),
+  monthlyPrice(GALLERY_MOR_PRICE_IDS.pro, 1990),
 ];
 
 async function resolveCurrentTier(db: TenantDb, tenantId: string): Promise<string> {
@@ -74,7 +96,6 @@ export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition
       viewRoles: ["TenantAdmin", "SystemAdmin"],
       successPath: GALLERY_PLAN_PATH,
       cancelPath: GALLERY_PLAN_PATH,
-      providerName: GALLERY_PROVIDER,
       contact: {
         labelKey: "gallery-screens:plan.enterprise.label",
         benefits: [{ labelKey: "gallery-screens:plan.enterprise.benefit" }],
@@ -85,6 +106,24 @@ export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition
     consumerProtection: {
       termsTextBlock: GALLERY_TERMS_SLUG,
       vatNote: { de: "Preise inkl. USt.", en: "Prices include VAT." },
+      providerTexts: {
+        [GALLERY_PROVIDER]: {
+          checkoutNote: {
+            de: "Rechnung von Gallery Beispiel GmbH",
+            en: "Invoiced by Gallery Beispiel GmbH",
+          },
+        },
+        [GALLERY_MOR_PROVIDER]: {
+          checkoutNote: {
+            de: "Verkäufer ist Dodo Payments · Rechnung und USt von Dodo Payments",
+            en: "Sold by Dodo Payments · invoice and VAT from Dodo Payments",
+          },
+          vatNote: {
+            de: "Rechnung und Umsatzsteuer stellt Dodo Payments als Merchant of Record.",
+            en: "Dodo Payments, as merchant of record, issues the invoice and charges the VAT.",
+          },
+        },
+      },
       operatorEmail: GALLERY_OPERATOR_EMAIL,
       terminationScope: "platform",
       legalLinks: {
@@ -105,6 +144,7 @@ export function createGalleryEmailFeature(): FeatureDefinition {
 // The page URL carries the consent id so the spec can echo it on the webhook,
 // exactly as a real provider echoes the checkout metadata.
 const galleryProviderPlugin: SubscriptionProviderPlugin = {
+  displayName: "Stripe",
   verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody),
   priceToTier: {
     [GALLERY_PRICE_IDS.starter]: "starter",
@@ -119,12 +159,47 @@ const galleryProviderPlugin: SubscriptionProviderPlugin = {
   cancelSubscription: async () => {},
 };
 
+// Merchant-of-record stand-in: switches plans in the app with fixed figures
+// (Starter to Pro: 6.67 EUR due now, 1.06 EUR of it VAT). Applying without a
+// consent id fails, so a successful switch in the spec proves the consent went
+// through.
+const galleryMorProviderPlugin: SubscriptionProviderPlugin = {
+  displayName: "Dodo Payments",
+  isBillingEnabled: async (ctx) => morEnabledTenants.has(ctx.user.tenantId),
+  verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody),
+  priceToTier: {
+    [GALLERY_MOR_PRICE_IDS.starter]: "starter",
+    [GALLERY_MOR_PRICE_IDS.pro]: "pro",
+  },
+  retrievePrices: async (_ctx, priceIds) => MOR_PRICES.filter((p) => priceIds.includes(p.priceId)),
+  createCheckoutSession: async (_ctx, options) => {
+    const url = new URL(options.successUrl);
+    url.searchParams.set("provider", "mor");
+    if (options.consentId !== undefined) url.searchParams.set("consentId", options.consentId);
+    return { url: url.toString() };
+  },
+  cancelSubscription: async () => {},
+  previewPlanSwitch: async () => ({
+    amountDueNow: 667,
+    tax: 106,
+    currency: "eur",
+    credit: 333,
+    effectiveAt: "2027-01-15T00:00:00Z",
+  }),
+  applyPlanSwitch: async (_ctx, options) => {
+    if (options.consentId === undefined) {
+      throw new Error("gallery MoR mock: plan switch applied without a consent id");
+    }
+  },
+};
+
 export const galleryProviderFeature: FeatureDefinition = defineFeature(
   "gallery-mock-provider",
   (r) => {
     r.describe("E2E-only mock subscription provider for the consent/termination gallery.");
     r.requires({ features: ["billing-foundation"] });
     r.useExtension("subscriptionProvider", GALLERY_PROVIDER, galleryProviderPlugin);
+    r.useExtension("subscriptionProvider", GALLERY_MOR_PROVIDER, galleryMorProviderPlugin);
   },
 );
 

package/samples/apps/use-all-bundled/e2e-billing-gallery/server.ts

@@ -20,6 +20,7 @@ import { GALLERY_TENANT_HOST, GALLERY_TERMS_SLUG } from "./gallery-constants";
 import {
   createGalleryBillingFeature,
   createGalleryEmailFeature,
+  createGalleryMorEnableRoute,
   galleryMailTransport,
   galleryProviderFeature,
   galleryScreensFeature,
@@ -29,14 +30,22 @@ const port = Number.parseInt(process.env["PORT"] ?? "4196", 10);
 
 const BILLING_FEATURE = "billing-foundation";
 const EMAIL_FEATURE = "channel-email";
+// The stock app mounts the real Mollie and Dodo providers; the gallery's
+// provider choice is the two mocks, which never call out.
+const REAL_PROVIDER_FEATURES: ReadonlySet<string> = new Set([
+  "subscription-mollie",
+  "subscription-dodo",
+]);
 
 const features = [
-  ...devAppOptions.features.map((feature) => {
-    if (feature.name === BILLING_FEATURE)
-      return createGalleryBillingFeature(`http://localhost:${port}`);
-    if (feature.name === EMAIL_FEATURE) return createGalleryEmailFeature();
-    return feature;
-  }),
+  ...devAppOptions.features
+    .filter((feature) => !REAL_PROVIDER_FEATURES.has(feature.name))
+    .map((feature) => {
+      if (feature.name === BILLING_FEATURE)
+        return createGalleryBillingFeature(`http://localhost:${port}`);
+      if (feature.name === EMAIL_FEATURE) return createGalleryEmailFeature();
+      return feature;
+    }),
   galleryProviderFeature,
   galleryScreensFeature,
 ];
@@ -77,6 +86,7 @@ await runDevApp({
   extraRoutes: [
     ...createE2eSeedRoutes({ mailOutbox: galleryMailTransport }),
     createSubscriptionWebhookRoute(),
+    createGalleryMorEnableRoute(),
     ...createContractTerminationRoutes(),
   ],
 });

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1,6 +1,6 @@
 {
   "source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
-  "featureCount": 87,
+  "featureCount": 88,
   "features": [
     {
       "name": "account-security",
@@ -300,7 +300,7 @@
     },
     {
       "name": "billing-foundation",
-      "description": "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 and a dormant billing-plans dashboard screen/panel from the catalog. 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 — 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` or `subscription-mollie` unless you are writing a new payment provider.",
+      "description": "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.",
       "toggleableDefault": null,
       "requires": [
         "tenant-lifecycle",
@@ -424,7 +424,7 @@
     },
     {
       "name": "channel-email",
-      "description": "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send the notifications declared with `tenantTransport: true` through the sending tenant's own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`; every other notification (password reset, sign-in) always goes through the app `transport`. `transport` may be left out when `tenantTransport` is set; a mail that then has no transport fails with `missing_credentials`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.",
+      "description": "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send the notifications declared with `tenantTransport: true` through the sending tenant's own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`; every other notification (password reset, sign-in) always goes through the app `transport`. `transport` may be left out when `tenantTransport` is set, but then only notifications declared with `tenantTransport: true` are delivered: every other notification (password reset, sign-in, invitations) fails with `missing_credentials`, so an app without an app SMTP server must mark every notification that should go out or keep an app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.",
       "toggleableDefault": null,
       "requires": [
         "delivery"
@@ -2467,6 +2467,123 @@
         "recommended": false
       }
     },
+    {
+      "name": "subscription-dodo",
+      "description": "Dodo Payments provider plugin for `billing-foundation`. Dodo acts as merchant of record: it sells to the customer and issues invoice and VAT, so the consumer-protection texts for this provider come from `consumerProtection.providerTexts`. Reads its API key and webhook secret from system config keys with `backing:\"secrets\"` (envelope-encrypted in the secrets store under the system tenant), plus a `billingLive` master switch and an `environment` key (test | live). `environment` is its own key because Dodo serves test and live mode from different API hosts and a live key must never hit the test host or the other way round; `billingLive` only decides whether checkouts are offered at all. All four are runtime config, so keys rotate and prod goes live without a redeploy, and the `mask` on each derives the sysadmin settings screen and nav. Mount via `createSubscriptionDodoFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env to secrets bridge fallbacks (`DODO_PAYMENTS_API_KEY`, `DODO_PAYMENTS_WEBHOOK_KEY`). The plugin always mounts; `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true. Webhooks arrive at `/api/subscription/webhook/dodo` and are verified per the Standard Webhooks spec (HMAC-SHA256 over id, timestamp and the raw body, 5 minute tolerance); events for products outside `priceToTier` or without tenant metadata are dropped. Implements hosted checkout, customer portal, cancel and resume, `retrievePrices` (10-minute TTL cache), `retrieveSubscription` for the sync job, and an in-app plan switch: `previewPlanSwitch` shows the proration before the customer confirms, `applyPlanSwitch` changes the plan without a hosted page and waits for the `plan_changed` webhook to move the tier. A plan switch in Dodo requires all plan products to belong to one Product Collection.",
+      "toggleableDefault": null,
+      "requires": [
+        "billing-foundation",
+        "config",
+        "secrets"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [
+        {
+          "extensionName": "subscriptionProvider",
+          "entityName": "dodo"
+        }
+      ],
+      "configKeys": [
+        {
+          "key": "api-key",
+          "qualifiedName": "subscription-dodo:config:api-key",
+          "type": "text",
+          "scope": "system",
+          "default": null,
+          "encrypted": true,
+          "computed": false,
+          "validated": false,
+          "options": null,
+          "bounds": null,
+          "pattern": null,
+          "writeRoles": [
+            "SystemAdmin"
+          ],
+          "readRoles": [
+            "TenantAdmin",
+            "Admin",
+            "SystemAdmin"
+          ]
+        },
+        {
+          "key": "billing-live",
+          "qualifiedName": "subscription-dodo:config:billing-live",
+          "type": "boolean",
+          "scope": "system",
+          "default": false,
+          "encrypted": false,
+          "computed": false,
+          "validated": false,
+          "options": null,
+          "bounds": null,
+          "pattern": null,
+          "writeRoles": [
+            "system",
+            "SystemAdmin"
+          ],
+          "readRoles": [
+            "TenantAdmin",
+            "Admin",
+            "SystemAdmin"
+          ]
+        },
+        {
+          "key": "environment",
+          "qualifiedName": "subscription-dodo:config:environment",
+          "type": "select",
+          "scope": "system",
+          "default": "test",
+          "encrypted": false,
+          "computed": false,
+          "validated": false,
+          "options": [
+            "test",
+            "live"
+          ],
+          "bounds": null,
+          "pattern": null,
+          "writeRoles": [
+            "SystemAdmin"
+          ],
+          "readRoles": [
+            "TenantAdmin",
+            "Admin",
+            "SystemAdmin"
+          ]
+        },
+        {
+          "key": "webhook-secret",
+          "qualifiedName": "subscription-dodo:config:webhook-secret",
+          "type": "text",
+          "scope": "system",
+          "default": null,
+          "encrypted": true,
+          "computed": false,
+          "validated": false,
+          "options": null,
+          "bounds": null,
+          "pattern": null,
+          "writeRoles": [
+            "SystemAdmin"
+          ],
+          "readRoles": [
+            "TenantAdmin",
+            "Admin",
+            "SystemAdmin"
+          ]
+        }
+      ],
+      "secrets": [],
+      "writeHandlers": [],
+      "uiHints": {
+        "displayLabel": "Billing · Dodo Payments",
+        "category": "billing",
+        "recommended": false
+      }
+    },
     {
       "name": "subscription-mollie",
       "description": "Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case. Mount via `createSubscriptionMollieFeature({ apiKey, webhookUrl, priceToTier, priceToConfig })` — the factory validates that `priceToTier` and `priceToConfig` keys are identical at boot time. Implements `verifyAndParseWebhook` (lazy Mollie-API fetch + heuristic event-type mapping) and `createCheckoutSession` (customer + first-payment with `sequenceType=\"first\"`); `createPortalSession` and `cancelSubscription` are not available because Mollie has no customer portal and requires a `customerId` that the plugin contract does not carry.",

package/samples/apps/use-all-bundled/src/run-config.ts

@@ -75,6 +75,7 @@ import { createRendererPdfFeature } from "@cosmicdrift/kumiko-bundled-features/r
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { createSeoFeature } from "@cosmicdrift/kumiko-bundled-features/seo";
 import { createStepDispatcherFeature } from "@cosmicdrift/kumiko-bundled-features/step-dispatcher";
+import { createSubscriptionDodoFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-dodo";
 import { createSubscriptionMollieFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-mollie";
 import { createSubscriptionStripeFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 import { createTagsFeature } from "@cosmicdrift/kumiko-bundled-features/tags";
@@ -209,6 +210,11 @@ export const APP_FEATURES = [
     webhookSecret: "whsec_smoke",
     priceToTier: { price_smoke: "free" },
   }),
+  createSubscriptionDodoFeature({
+    apiKey: "dodo_smoke",
+    webhookSecret: "whsec_smoke",
+    priceToTier: { pdt_smoke: "free" },
+  }),
   createSubscriptionMollieFeature({
     apiKey: "test_smoke_key",
     webhookUrl: "https://smoke.example/webhook",
@@ -416,12 +422,12 @@ export const BOOT_FEATURES = APP_FEATURES.filter(
   (feature) => feature.name !== FEATURE_TOGGLES_FEATURE,
 );
 
-// Smoke signup — enables createAuthSelfRegistrationToggleFeature via
-// composeFeatures when passed as authOptions (#1521 Option A). Same shape
-// as run{Dev,Prod}App's auth.signup; appUrl is a stub (no real mail in boot).
 // locale-de is mounted, so every translation key must exist in German and English.
 export const VALIDATE_BOOT_OPTIONS = { requiredLocales: ["de", "en"] } as const;
 
+// Smoke signup — enables createAuthSelfRegistrationToggleFeature via
+// composeFeatures when passed as authOptions (#1521 Option A). Same shape
+// as run{Dev,Prod}App's auth.signup; appUrl is a stub (no real mail in boot).
 export const AUTH_COMPOSE_OPTIONS = {
   signup: {
     appUrl: "http://localhost:4186/signup",

package/samples/recipes/auth-mfa/README.md

@@ -75,8 +75,13 @@ features: [..., createSessionsFeature(), mfaFeature, createAccountSecurityFeatur
 5. **MFA state changes revoke every OTHER live session** (stolen-session defense) — never the session that made the change.
 6. **Enforcement is opt-in.** Without a tenant enabling `auth-mfa:config:required`, users choose for themselves whether to enroll.
 
+## Confirmation code input
+
+`src/web/confirmation-code-step.tsx` shows the `Input kind="code"` renderer primitive outside the MFA screen, for example an e-mail or invite confirmation code. Pass `length` (here 6), `autoFocus` and `onComplete`. The input accepts digits only, so pasting "123 456" yields `123456`, and `onComplete` fires once when the value reaches `length`. `autoComplete` defaults to `one-time-code`, so mobile keyboards offer the code from the SMS or mail. After a wrong code the step clears the value and bumps a `key`, which remounts the input and returns focus to it.
+
 ## Tests
 
 - **Baseline:** a user without MFA enrolled still gets a JWT straight from `/auth/login`.
 - **End-to-end:** enroll via `enable-start`/`enable-confirm`, log in (gets a challenge, no JWT), complete via `/auth/mfa/verify` (gets a JWT) — copies the `buildServer({ auth: ... })` block from the sample comment verbatim.
 - **Account security:** the composed screen boot-validates next to `auth-mfa` and `sessions` and shows a sidebar entry once `nav` is set.
+- **Confirmation code step:** typing or pasting six digits calls `onConfirm` once; a rejected code shows the error, clears the field and refocuses it.

package/samples/recipes/auth-mfa/package.json

@@ -4,9 +4,12 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
-    "@cosmicdrift/kumiko-framework": "workspace:*"
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "@cosmicdrift/kumiko-renderer": "workspace:*",
+    "react": "^19.2.6"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "workspace:*"
+    "@cosmicdrift/kumiko-testing": "workspace:*",
+    "@types/react": "^19.2.14"
   }
 }

package/samples/recipes/auth-mfa/src/web/confirmation-code-step.tsx

@@ -0,0 +1,49 @@
+import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+
+const CONFIRMATION_CODE_LENGTH = 6;
+
+export type ConfirmationCodeStepProps = {
+  /** Resolves true when the server accepted the code. */
+  readonly onConfirm: (code: string) => Promise<boolean>;
+};
+
+export function ConfirmationCodeStep({ onConfirm }: ConfirmationCodeStepProps): ReactNode {
+  const { Input, Banner } = usePrimitives();
+  const [code, setCode] = useState("");
+  const [attempt, setAttempt] = useState(0);
+  const [pending, setPending] = useState(false);
+  const [rejected, setRejected] = useState(false);
+
+  const confirm = async (submittedCode: string): Promise<void> => {
+    if (pending) return;
+    setPending(true);
+    setRejected(false);
+    const accepted = await onConfirm(submittedCode).finally(() => setPending(false));
+    if (accepted) return;
+    setRejected(true);
+    setCode("");
+    // The input was disabled while pending and lost focus; remounting restores autoFocus.
+    setAttempt((n) => n + 1);
+  };
+
+  return (
+    <>
+      <Input
+        key={attempt}
+        kind="code"
+        length={CONFIRMATION_CODE_LENGTH}
+        id="confirmation-code"
+        name="confirmation-code"
+        testId="confirmation-code"
+        value={code}
+        onChange={setCode}
+        onComplete={(next) => void confirm(next)}
+        disabled={pending}
+        hasError={rejected}
+        autoFocus
+      />
+      {rejected ? <Banner variant="error">That code is not valid. Try again.</Banner> : null}
+    </>
+  );
+}

package/samples/recipes/auth-mfa/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx"
+  },
+  "include": ["src"]
+}

package/samples/recipes/env-composition/README.md

@@ -10,7 +10,8 @@ instead of keeping a hand-written copy of every feature's variables.
   `kmsEnvSchema` and `s3EnvSchema`. `composeEnvSchema` collects them and
   records which feature declared each variable.
 - **App-level blocks in `extend`**: `buildInfoEnvSchema`, `demoAdminEnvSchema`,
-  `stripeEnvSchema({ prices })` and `createS3EnvSchema({ prefix })` for a
+  `stripeEnvSchema({ prices })`, `dodoEnvSchema({ prices })` and
+  `createS3EnvSchema({ prefix })` for a
   second bucket. These belong to no mounted feature, so the app adds them.
 - **Typed result**: `parseEnv(composed.schema, …)` returns the merged type,
   so `parsed.S3_BUCKET` is `string | undefined` and `parsed.APP_PUBLIC_URL` is
@@ -26,6 +27,7 @@ instead of keeping a hand-written copy of every feature's variables.
 | `smtpEnvSchema` | `channel-email` | `createChannelEmailFeature()` |
 | `s3EnvSchema`, `createS3EnvSchema({ prefix })` | `file-provider-s3` | `createFileProviderS3Feature({ fromEnv: true })` |
 | `stripeEnvSchema({ prices })` | `subscription-stripe` | app (`extend`); the feature registers the bridge keys |
+| `dodoEnvSchema({ prices })` | `subscription-dodo` | app (`extend`); the feature registers the bridge keys |
 | `mfaTokenSecretsEnvSchema` | `auth-mfa` | `createAuthMfaFeature()` |
 | `buildInfoEnvSchema`, `demoAdminEnvSchema` | `foundation-shared` | app (`extend`) |
 | `prometheusMetricsEnvSchema` | `framework/observability` | app (`extend`) |

package/samples/recipes/env-composition/src/env.ts

@@ -15,6 +15,7 @@ import {
   demoAdminEnvSchema,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { dodoEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-dodo";
 import { stripeEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";
 import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
@@ -36,6 +37,7 @@ const appEnvSchema = z.object({
   ...buildInfoEnvSchema.shape,
   ...demoAdminEnvSchema.shape,
   ...stripeEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
+  ...dodoEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
   ...createS3EnvSchema({ prefix: "RELEASES_S3_" }).shape,
   APP_PUBLIC_URL: z.url().describe("Public origin of the app, used in mail links."),
 });

package/samples/recipes/legal-pages/README.md

@@ -72,7 +72,7 @@ await runProdApp({
   // Required (1): routes run anonymous, need tenant resolution
   anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
   // Required (2): boot check + internal lookup use ctx.templateResolver
-  extraContext: ({ db }) => ({
+  extraContext: ({ db, registry }) => ({
     templateResolver: createTemplateResolverApi(db, registry),
   }),
 });

package/samples/recipes/rate-limiting/README.md

@@ -28,6 +28,24 @@ exhausted) and no bucket is charged. Each `per` may appear once; an empty list f
 An anonymous handler needs every bucket to be ip-keyed, and `{ disabled: true, reason }`
 stays a single declaration.
 
+## Cost per payload element
+
+A bulk handler books one token per item instead of one per request. Declare `rateLimitCost`
+next to `rateLimit`:
+
+```ts illustration
+r.writeHandler({
+  // ...
+  rateLimit: { per: "tenant+handler", limit: 20, windowSeconds: 600 },
+  rateLimitCost: (payload) => payload.files.length,
+});
+```
+
+The cost is computed from the validated payload and booked on every declared bucket, so an
+invalid payload costs nothing and a rejected request consumes nothing. Results below 1 count
+as 1. Because it books after the parse, boot rejects `rateLimitCost` on anonymous or ip-limited
+handlers.
+
 ## Per-payload limits
 
 A public write handler that mails an address typed by the caller is also limited per

package/samples/recipes/rate-limiting/src/feature.ts

@@ -33,5 +33,17 @@ export function createRateLimitShowcaseFeature(): FeatureDefinition {
         { per: "tenant+handler", limit: 3, windowSeconds: 3600 },
       ],
     });
+
+    // Bulk upload: a request books one token per item instead of one per request. The cost
+    // comes from the validated payload, so a schema-invalid request costs nothing; a request
+    // that would exceed the remaining budget is rejected and consumes nothing.
+    r.writeHandler({
+      name: "bulk-upload",
+      schema: z.object({ files: z.array(z.string()).min(1).max(20) }),
+      handler: async () => ({ isSuccess: true as const, data: {} }),
+      access: { roles: ["Admin", "User"] },
+      rateLimit: { per: "tenant+handler", limit: 20, windowSeconds: 600 },
+      rateLimitCost: (payload) => payload.files.length,
+    });
   });
 }

package/packages/bundled-features/src/billing-foundation/consumer-protection/stored-user-email.ts

@@ -1,12 +0,0 @@
-import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
-import { decryptStoredPii } from "../../shared/index.ts";
-
-// findForAuth returns the stored column, which is ciphertext under an active KMS;
-// channel-email refuses to mail a ciphertext address. Null for an erased subject.
-export async function openStoredUserEmail(
-  stored: string,
-  fallbackRequestId: string,
-): Promise<string | null> {
-  const email = await decryptStoredPii(stored, "email", fallbackRequestId);
-  return email === PII_ERASED_SENTINEL ? null : email;
-}