@cosmicdrift/kumiko-samples 0.387.0 → 0.389.0

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",
@@ -71,6 +71,7 @@
       "name": "audit",
       "description": "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection — the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: \"system\"` to read the app-instance system events such as `app.started`, and reads the events of every tenant (system tenant excluded) through `audit:query:list-all-tenants` and the `audit-log-all-tenants` screen. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "tenant",
         "user",
@@ -232,6 +233,7 @@
           "validated": false,
           "options": [
             "optional",
+            "systemAdmins",
             "admins",
             "all"
           ],
@@ -300,7 +302,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",
@@ -339,6 +341,7 @@
       "name": "cap-counter",
       "description": "Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [],
       "optionalRequires": [],
       "configReads": [],
@@ -362,6 +365,7 @@
       "name": "cap-overview",
       "description": "Read-only visibility into per-tenant tier assignment and cap usage. SystemAdmin gets a platform-wide tenant list with usage bars; tenant admins (or the roles in `usageVisibleTo`) get their own tenant's usage as dashboard cards. Reads tier-engine, billing-foundation, and tenant data plus app-owned usage tables via caller-supplied CapSpec callbacks — never writes.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "tenant",
         "tier-engine",
@@ -424,7 +428,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"
@@ -744,6 +748,7 @@
       "name": "delivery",
       "description": "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (the `runProdApp` and `runDevApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. An app serving its own (e.g. legacy) unsubscribe links renders the same result page with `renderUnsubscribeResultPage({ kind, locale })`. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "tenant"
       ],
@@ -895,6 +900,7 @@
       "name": "feature-toggles",
       "description": "Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: \"shared\"` syncs the snapshot across instances whenever a `toggle-set` event is appended.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [],
       "optionalRequires": [],
       "configReads": [],
@@ -1372,6 +1378,7 @@
       "name": "inbound-mail-foundation",
       "description": "Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "tenant-lifecycle"
       ],
@@ -1464,6 +1471,7 @@
       "name": "jobs",
       "description": "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI. A job that declares `tenantVisibleFailure` also records its last failed attempt per tenant and subject in `store_tenant_job_failures`, which the tenant itself reads through `jobs:query:failures` — a translation key only, never the provider's message (fw#3079). A job that declares `tenantVisibleRun` also keeps its run state per tenant and subject in `store_tenant_job_runs` (queued, running, plus the latest completed or failed run, no payload, error text or logs), which the tenant reads through `jobs:query:tenant-runs` (fw#3616); the stale-run sweep fails its stuck `running` rows and drops `queued` rows older than `retentionDays`.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [],
       "optionalRequires": [],
       "configReads": [],
@@ -1759,6 +1767,7 @@
       "name": "managed-pages",
       "description": "Tenant-editable, server-rendered public pages with per-tenant branding. Stores one Markdown `page` per `(tenantId, slug, lang)` in the `read_pages` entity table with a `published` gate plus `description`/`ogImage` SEO meta. Registers an anonymous `GET {basePath}/:slug` route that resolves the tenant from the request Host via the app-supplied `resolveApexTenant`, serves only published pages (drafts → 404), renders Markdown through the hardened `page-render` core, and isolates per-tenant content with `Vary: Host`. Ships TenantAdmin/SystemAdmin admin screens (`entityList` + `entityEdit`) backed by convention CRUD handlers (`managed-pages:write:page:{create,update,delete}`, `managed-pages:query:page:{list,detail}`); the app wires nav/workspace onto `managed-pages:screen:page-list`. Also exposes `managed-pages:query:by-tenant-published` (anonymous, SQL-filtered on `published`) for sitemap/discovery consumers such as the `seo` feature. Branding (via `config`, scope tenant): `branding-{title,description,site-url,accent-color,logo-url,layout-preset,custom-css}` keys with write-time validation (hex color, https URLs), a `configEdit` self-service screen (`managed-pages:screen:branding-settings`), and a `managed-pages:query:branding` read that the render path applies as scoped `:root` CSS vars + a logo/title header. Also exposes `managed-pages:write:set` (idempotent slug-keyed upsert, SystemAdmin cross-tenant via `tenantIdOverride`) as a provisioning API. Requires `config` + `anonymousAccess` wired at app bootstrap.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "config"
       ],
@@ -2088,6 +2097,7 @@
       "name": "personal-access-tokens",
       "description": "Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `store_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — registered as an auth-foundation tokenVerifier provider, resolved generically by the middleware. Pass { toggleable: { default: false } } to tier-gate the whole feature.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "user",
         "tenant",
@@ -2417,6 +2427,7 @@
       "name": "sessions",
       "description": "Tracks signed-in clients in the `store_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the same callbacks are also registered as an auth-foundation sessionStore provider, resolvable generically via `resolveSessionStore()`. The feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "user",
         "auth-foundation"
@@ -2467,6 +2478,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.",
@@ -2594,6 +2722,7 @@
       "name": "tags",
       "description": "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`, with optional `color` and `scope`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Catalog screens are declarative (`entityList` + `entityEdit`) and use convention QNs `tag:{create,update,delete}`; TagManager/TagPicker keep `create-tag`/`update-tag`/`delete-tag`. Also: `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. A tag with empty `scope` is global; a `scope` of an entityType restricts it to that type in the picker. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: { reason } } }) or pin roles with createTagsFeature({ roles }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [],
       "optionalRequires": [],
       "configReads": [],
@@ -2709,6 +2838,7 @@
       "name": "tenant",
       "description": "Registers the three core multi-tenancy entities — `tenant`, `tenant-membership`, and `tenant-invitation` (DB tables `read_tenants`, `read_tenant_memberships`, and `read_tenant_invitations`) — along with write handlers for create/update/disable/enable/addMember/removeMember/updateMemberRoles and the matching queries. It also declares a set of per-tenant config keys (companyName, timezone, locale, SMTP credentials) and system-only keys (priceModel, maxUsers) via `r.config({ keys: { ... } })`. Use this feature in every multi-tenant app; membership resolution and invitation flows depend on it, and `auth-email-password` requires it.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "config"
       ],
@@ -3075,6 +3205,7 @@
       "name": "user",
       "description": "Manages the cross-tenant user identity: the `read_users` table holds each user's email, `displayName`, global `roles`, `emailVerified` flag, and lifecycle `status` (active / restricted / deletionRequested / deleted). Because users exist above any individual tenant, the feature runs with `r.systemScope()` — membership and tenant-specific roles live in the `tenant` feature instead. Add this feature whenever your app needs a persistent, tenant-agnostic user record that auth and GDPR pipelines can reference.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [],
       "optionalRequires": [],
       "configReads": [],
@@ -3102,6 +3233,7 @@
       "name": "user-data-rights",
       "description": "Implements GDPR Art. 15 (access / `my-audit-log` query), Art. 17 (erasure / `request-deletion` + `cancel-deletion`, plus the anonymous email-verified `request-deletion-by-email` + `confirm-deletion-by-token` flow for lockout-safe self-service, + cron cleanup with grace period), Art. 18 (restriction / `restrict-account` + `lift-restriction`), and Art. 20 (portability / async `request-export` → ZIP via `file-foundation`, Magic-Link download) as first-class HTTP handlers and cron jobs. Each domain feature opts in by calling `r.useExtension(EXT_USER_DATA, \"<entity>\", { export, delete })` — the feature then orchestrates the export and forget pipelines across all registered hooks automatically. When `mail-foundation` and a `mail-transport-*` are mounted, it also sends the four GDPR notifications (export ready/failed, deletion requested/executed) itself with no app callback code, rendered in each recipient’s locale. Requires `user`, `data-retention`, `compliance-profiles`, and `sessions`.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "user",
         "data-retention",
@@ -3269,6 +3401,7 @@
       "name": "waitlist",
       "description": "Public waitlist: an anonymous, rate-limited `submit` handler collects name, email and optional company, portfolio and message (a honeypot field and per-email dedupe keep bots and repeat submits out, and the response body is identical whether or not an address was already listed), and mails the submitter a confirmation. SystemAdmins review entries in a list screen and invite or reject them; an invite creates the entrant's own tenant (or joins one shared tenant) and mails an accept link with the configured membership role, never a global role. Entries are platform-wide, their personal data is crypto-shredding-ready, and the EXT_USER_DATA hooks export and erase entries matching a user's email.",
       "toggleableDefault": null,
+      "adoptsBundledLists": true,
       "requires": [
         "tenant",
         "auth-email-password",

package/samples/apps/use-all-bundled/kumiko/schema.ts

@@ -11,6 +11,7 @@
 import { collectTableMetas, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";
+import { BUNDLED_LISTS } from "../src/bundled-lists";
 import { APP_FEATURES, AUTH_COMPOSE_OPTIONS, VALIDATE_BOOT_OPTIONS } from "../src/run-config";
 
 export { VALIDATE_BOOT_OPTIONS };
@@ -18,6 +19,7 @@ export { VALIDATE_BOOT_OPTIONS };
 export const FEATURES: readonly FeatureDefinition[] = composeFeatures(APP_FEATURES, {
   includeBundled: true,
   authOptions: AUTH_COMPOSE_OPTIONS,
+  bundledLists: BUNDLED_LISTS,
 });
 
 // collectTableMetas erfasst neben entities auch

package/samples/apps/use-all-bundled/kumiko.config.ts

@@ -12,11 +12,13 @@ import {
 } from "@cosmicdrift/kumiko-server-runtime/compose-features";
 import { notesFeature } from "./src/app/notes-feature";
 import { appScreensFeature } from "./src/app/screens-feature";
+import { BUNDLED_LISTS } from "./src/bundled-lists";
 import { APP_FEATURES, AUTH_COMPOSE_OPTIONS } from "./src/run-config";
 
 export default {
   features: composeFeatures([...APP_FEATURES, appScreensFeature, notesFeature], {
     includeBundled: true,
+    bundledLists: BUNDLED_LISTS,
     ...(buildComposeAuthOptions(AUTH_COMPOSE_OPTIONS) !== undefined && {
       authOptions: buildComposeAuthOptions(AUTH_COMPOSE_OPTIONS),
     }),

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

@@ -33,6 +33,7 @@
     "@cosmicdrift/kumiko-locale-it": "workspace:*"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "workspace:*"
+    "@cosmicdrift/kumiko-testing": "workspace:*",
+    "fflate": "^0.8.2"
   }
 }

package/samples/apps/use-all-bundled/src/app/dev-app-options.ts

@@ -13,6 +13,7 @@
 import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import type { RunDevAppOptions } from "@cosmicdrift/kumiko-dev-server";
 import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { BUNDLED_LISTS } from "../bundled-lists";
 import { AUTH_COMPOSE_OPTIONS, BOOT_FEATURES, VALIDATE_BOOT_OPTIONS } from "../run-config";
 import { ADMIN_EMAIL, ADMIN_PASSWORD, BETA_TENANT_ID, DEV_TENANT_ID } from "./auth-constants";
 import { invoiceReportsFeature } from "./invoice-reports-feature";
@@ -31,6 +32,7 @@ export const devAppOptions = {
   features: [...BOOT_FEATURES, appScreensFeature, notesFeature, invoiceReportsFeature],
   featureToggles: true,
   validateBootOptions: VALIDATE_BOOT_OPTIONS,
+  bundledLists: BUNDLED_LISTS,
   port: Number.parseInt(process.env["PORT"] ?? "4186", 10),
   clientEntry: "./src/app/client.tsx",
   htmlPath: "./public/index.html",

package/samples/apps/use-all-bundled/src/app/notes-feature.ts

@@ -45,6 +45,7 @@ export const noteEntity = createEntity({
       required: true,
       maxLength: 200,
       sortable: true,
+      searchable: true,
     }),
     customFields: customFieldsField(),
   },
@@ -65,6 +66,7 @@ const noteListScreen: EntityListScreenDefinition = {
     },
   ],
   searchable: true,
+  table: { export: { xlsx: true } },
   defaultSort: { field: "title", dir: "asc" },
   slots: { header: { react: { __component: TAGS_FILTER_EXTENSION_NAME } } },
   rowActions: [

package/samples/apps/use-all-bundled/src/bundled-lists.ts

@@ -0,0 +1,15 @@
+import type { BundledListsOptions } from "@cosmicdrift/kumiko-framework/engine";
+
+export const BUNDLED_LISTS = {
+  table: {
+    rememberState: true,
+    resetAll: true,
+    columnPicker: true,
+    density: { userChoice: true },
+    pinning: true,
+    resizing: true,
+    keyboardNavigation: true,
+    export: { xlsx: true },
+  },
+  pinFirstColumn: true,
+} as const satisfies BundledListsOptions;

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/golden-path/src/feature.ts

@@ -7,7 +7,7 @@ import {
   emitEvent,
   setFields,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 
 export const ticketEntity = createEntity({
@@ -43,6 +43,7 @@ export const helpdeskFeature = defineFeature("helpdesk", (r) => {
       if (!ticket) {
         return failNotFound("ticket", event.payload.id);
       }
+      if (ticket["isClosed"]) return failUnprocessable("ticket_already_closed");
       await emitEvent(ctx, ticketClosed, {
         aggregateId: event.payload.id,
         aggregateType: "ticket",

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),
   }),
 });