@cosmicdrift/kumiko-samples 0.393.0 → 0.395.0

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

@@ -10,6 +10,7 @@
     "dev": "PORT=4186 bun --env-file=../../../.env run src/app/server.ts",
     "screenshots": "bun x playwright test e2e/screenshots.spec.ts --config=playwright.config.ts",
     "billing-gallery": "bun x playwright test --config=playwright.billing-gallery.config.ts",
+    "docs-guides": "bun x playwright test e2e/docs-guides.screenshots.spec.ts --config=playwright.config.ts && bun x playwright test --config=playwright.billing-docs.config.ts",
     "e2e": "bun x playwright test e2e/mfa-login.spec.ts --config=playwright.config.ts",
     "gen:manifest": "bun run scripts/gen-feature-manifest.ts",
     "gen:sample-index": "bun run scripts/gen-sample-index.ts"

package/samples/apps/use-all-bundled/playwright.billing-docs.config.ts

@@ -0,0 +1,15 @@
+// @runtime test
+// English docs screenshots of the billing plans screen. Boots the gallery server with the docs
+// variant switched on (net prices with a note, gross recurring price in the plan switch); the
+// German review gallery has its own config. Gated by SCREENSHOT_DIR, see the `billing-docs` script.
+import { defineAppE2eConfig, PLAYWRIGHT_DEMO_ENV } from "@cosmicdrift/kumiko-testing/e2e";
+import { E2E_PORTS } from "../../e2e/e2e-ports";
+import { GALLERY_DOCS_VARIANT_ENV } from "./e2e-billing-gallery/gallery-constants";
+
+export default defineAppE2eConfig({
+  port: E2E_PORTS["framework/use-all-bundled-billing-gallery"],
+  env: { ...PLAYWRIGHT_DEMO_ENV, [GALLERY_DOCS_VARIANT_ENV]: "1" },
+  locale: "en",
+  testDir: "./e2e-billing-docs",
+  serverEntry: "e2e-billing-gallery/server.ts",
+});

package/samples/apps/use-all-bundled/src/app/cap-overview-caps.ts

@@ -1,6 +1,7 @@
 import type { CapSpec } from "@cosmicdrift/kumiko-bundled-features/cap-overview";
 import { noteEntryTable } from "@cosmicdrift/kumiko-bundled-features/notes-history";
 import { tagEntity } from "@cosmicdrift/kumiko-bundled-features/tags";
+import { templateResourcesTable } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import { tenantMembershipsTable } from "@cosmicdrift/kumiko-bundled-features/tenant";
 
 import { buildEntityTable, selectMany } from "@cosmicdrift/kumiko-framework/db";
@@ -11,10 +12,11 @@ const tagTable = buildEntityTable("tag", tagEntity);
 const NOTE_LIMIT_BY_TIER: Readonly<Record<string, number>> = { free: 10, pro: 100 };
 const TAG_LIMIT_BY_TIER: Readonly<Record<string, number>> = { free: 5, pro: 50 };
 const SEAT_LIMIT_BY_TIER: Readonly<Record<string, number>> = { free: 5, pro: 20 };
+const TEMPLATE_LIMIT_BY_TIER: Readonly<Record<string, number>> = { free: 3, pro: 30 };
 const DEFAULT_LIMIT = 10;
 
-// Four example caps built from entities this sample already mounts
-// (notes-history, tags, tenant-membership) — demonstrates the caller-supplied
+// Five example caps built from entities this sample already mounts
+// (notes-history, tags, tenant-membership, template-resolver) — demonstrates the caller-supplied
 // CapSpec contract cap-overview reads against, the same shape a real app
 // would provide for its own usage tables.
 export const CAP_OVERVIEW_CAPS: readonly CapSpec[] = [
@@ -68,4 +70,16 @@ export const CAP_OVERVIEW_CAPS: readonly CapSpec[] = [
     },
     icon: "gauge",
   },
+  {
+    id: "templates",
+    label: "cap-overview.caps.templates",
+    limit: (tier) => TEMPLATE_LIMIT_BY_TIER[tier] ?? DEFAULT_LIMIT,
+    usage: async (db, tenantId) => {
+      const rows = await selectMany(db, templateResourcesTable, { tenantId: [tenantId] });
+      return rows.length;
+    },
+    // Counter only: the limit stays enforced server-side but is not shown to the tenant.
+    showLimit: false,
+    icon: "file",
+  },
 ];

package/samples/apps/use-all-bundled/src/app/cap-overview-labels-feature.ts

@@ -1,6 +1,6 @@
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 
-// Labels for the four example caps (notes, tags, seats, apiCalls) wired up in
+// Labels for the five example caps (notes, tags, seats, apiCalls, templates) wired up in
 // cap-overview-caps.ts. Cap ids are the app's choice, so their labels are
 // too — cap-overview itself carries no vocabulary for app-owned caps, same
 // reasoning as collection-labels-feature.ts for content collections.
@@ -12,6 +12,7 @@ export const capOverviewLabelsFeature = defineFeature("cap-overview-labels", (r)
       "cap-overview.caps.tags": { de: "Tags", en: "Tags" },
       "cap-overview.caps.seats": { de: "Plätze", en: "Seats" },
       "cap-overview.caps.apiCalls": { de: "API-Aufrufe", en: "API calls" },
+      "cap-overview.caps.templates": { de: "Vorlagen", en: "Templates" },
     },
   });
   return {};

package/samples/apps/use-all-bundled/src/app/client.tsx

@@ -26,7 +26,9 @@ import { customFieldsClient } from "@cosmicdrift/kumiko-bundled-features/custom-
 import { deliveryClient } from "@cosmicdrift/kumiko-bundled-features/delivery/web";
 import { featureTogglesClient } from "@cosmicdrift/kumiko-bundled-features/feature-toggles/web";
 import { foldersClient } from "@cosmicdrift/kumiko-bundled-features/folders/web";
+import { inboundMailFoundationClient } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation/web";
 import { jobsClient } from "@cosmicdrift/kumiko-bundled-features/jobs/web";
+import { managedPagesClient } from "@cosmicdrift/kumiko-bundled-features/managed-pages/web";
 import { sessionsClient } from "@cosmicdrift/kumiko-bundled-features/sessions/web";
 import { tagsClient } from "@cosmicdrift/kumiko-bundled-features/tags/web";
 import { textBlocksClient } from "@cosmicdrift/kumiko-bundled-features/template-resolver/web";
@@ -99,6 +101,9 @@ createKumikoApp({
   shell: AppShell,
   clientFeatures: [
     localeDeClient(),
+    userDataRightsClient({
+      publicDeletion: { requestPath: "/account/delete", confirmPath: "/account/delete/confirm" },
+    }),
     emailPasswordClient({ mfaVerifyScreen: MfaVerifyScreen }),
     authMfaClient(),
     adminShellClient(),
@@ -112,14 +117,16 @@ createKumikoApp({
     tierEngineClient(),
     capOverviewClient(),
     userProfileClient(),
-    userDataRightsClient(),
     customFieldsClient(),
     foldersClient(),
+    inboundMailFoundationClient(),
     complianceProfilesClient(),
     featureTogglesClient(),
     // tag-list management screen (TagManager) + TagSection/TagFilter extension
     // slots + tag i18n. Required for the dev-only notesFeature host to render.
     tagsClient(),
+    // Document editor of the page-edit body section.
+    managedPagesClient(),
     // template-resolver text-block tree + editor under the app-owned "content"
     // nav node. Points at SYSTEM_TENANT because that is where the legal and
     // marketing copy is seeded.

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

@@ -5,11 +5,13 @@
 // (#1258): an open screen not reachable via nav is no longer an eligible
 // fallback candidate.
 
+import { MAIL_ACCOUNT_LIST_SCREEN_QN } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { ADMIN_NAV_QN, ADMIN_NAV_WORKSPACES } from "./admin-nav-feature";
 
 export const appScreensFeature: FeatureDefinition = defineFeature("app-screens", (r) => {
-  r.describe("App-side nav placement for the user-profile self-service page.");
-  r.requires({ features: ["user-profile"] });
+  r.describe("App-side nav placement for the user-profile self-service page and the mailbox list.");
+  r.requires({ features: ["user-profile", "inbound-mail-foundation"] });
   r.nav({
     id: "profile",
     label: "screen:profile.title",
@@ -29,8 +31,18 @@ export const appScreensFeature: FeatureDefinition = defineFeature("app-screens",
     access: { roles: ["SystemAdmin"] },
     workspaces: ["admin-shell:workspace:platform"],
   });
+  r.nav({
+    id: "mail-accounts",
+    label: "nav:mail-accounts.title",
+    icon: "mail",
+    screen: MAIL_ACCOUNT_LIST_SCREEN_QN,
+    parent: ADMIN_NAV_QN,
+    workspaces: ADMIN_NAV_WORKSPACES,
+    order: 20,
+  });
   r.translations({
     keys: {
+      "nav:mail-accounts.title": { de: "Postfächer", en: "Mailboxes" },
       "screen:profile.title": { de: "Profil", en: "Profile" },
       "nav:content.title": { de: "Inhalte", en: "Content" },
     },

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

@@ -335,7 +335,19 @@ export const seedScreenshotData: SeedFn = async (stack) => {
     slug: "about",
     lang: "en",
     title: "About Acme",
-    body: "# About Acme\n\nWe build calm software.",
+    body: [
+      "# About Acme",
+      "",
+      "We build calm software for small teams. Acme was founded in 2019 in Hamburg and now supports more than 400 companies across Europe.",
+      "",
+      "## What we stand for",
+      "",
+      "- Software that stays out of your way",
+      "- Fair, per-seat pricing without surprises",
+      "- Your data stays in the EU",
+      "",
+      "Read more about how we handle data in our [privacy policy](/legal/privacy).",
+    ].join("\n"),
     published: true,
   });
   await seedPage(stack.db, {
@@ -468,10 +480,13 @@ export const seedScreenshotData: SeedFn = async (stack) => {
   // carry whatever the handler derives instead of a hand-built projection.
   // SYSTEM_TENANT, not the dev tenant: the screenshot admin reads the system
   // tenant — the same reason the text-block tree above seeds there.
+  // The real admin, not TestUsers.systemAdmin's id: the seed signs in with a live session row,
+  // and the session list shows that row's user. The sessionChecker re-derives roles from the
+  // admin's global SystemAdmin role, which the collection's access accepts.
   const snippetAuthor: SessionUser = {
     ...TestUsers.systemAdmin,
     tenantId: SYSTEM_TENANT_ID,
-    roles: ["TenantAdmin"],
+    id: devAdminId,
   };
   for (const snippet of [
     {

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

@@ -75,8 +75,8 @@ 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 { createSubscriptionPaddleFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-paddle";
 import { createSubscriptionStripeFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 import { createTagsFeature } from "@cosmicdrift/kumiko-bundled-features/tags";
 import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
@@ -212,10 +212,12 @@ export const APP_FEATURES = [
     webhookSecret: "whsec_smoke",
     priceToTier: { price_smoke: "free" },
   }),
-  createSubscriptionDodoFeature({
-    apiKey: "dodo_smoke",
-    webhookSecret: "whsec_smoke",
-    priceToTier: { pdt_smoke: "free" },
+  createSubscriptionPaddleFeature({
+    apiKey: "paddle_smoke",
+    webhookSecret: "pdl_ntfset_smoke",
+    tenantBindingKey: "paddle_smoke_binding_key",
+    clientToken: "test_smoke_client_token",
+    priceToTier: { pri_smoke: "free" },
   }),
   createSubscriptionMollieFeature({
     apiKey: "test_smoke_key",
@@ -314,10 +316,10 @@ export const APP_FEATURES = [
           label: "templateResolver:nav.snippets",
           workspaces: ["admin-shell:workspace:platform"],
         },
-        // rich + variableSchema so the smoke app renders the WYSIWYG with
+        // document + variableSchema so the smoke app renders the WYSIWYG with
         // insertable chips, not just the plain textarea — the preview
         // substitutes these example values for `{{customerName}}` & co.
-        contentFormat: "rich",
+        contentFormat: "document",
         variableSchema: {
           customerName: "Max Mustermann",
           orderId: "A-1042",
@@ -333,7 +335,7 @@ export const APP_FEATURES = [
           label: "templateResolver:nav.signatures",
           workspaces: ["admin-shell:workspace:platform"],
         },
-        contentFormat: "rich",
+        contentFormat: "document",
       },
     ],
   }),
@@ -350,12 +352,18 @@ export const APP_FEATURES = [
   // PUPPETEER_SERVICE_URL + PUPPETEER_AUTH_TOKEN and only asked when a PDF is generated.
   createRendererPuppeteerClientFeature(),
 
-  // managed-pages: requires config (auto-bundled). Smoke resolver never serves
-  // (boot-only). allowCustomCss:true boot-validates the CSS code path + emits
+  // managed-pages: requires config (auto-bundled). Every host resolves to the
+  // dev tenant so the document-editor e2e can read a saved page back from the
+  // public route. allowCustomCss:true boot-validates the CSS code path + emits
   // the branding-custom-css key into the manifest. The managed-pages-css
   // companion toggle is handler-less, has no subpath export, and is recipe-
   // covered — not standalone-mounted here (smoke = one mount per subpath-export).
-  createManagedPagesFeature({ resolveApexTenant: () => null, allowCustomCss: true }),
+  createManagedPagesFeature({
+    // Mapping every host to the dev tenant is for this sample and its e2e only; production maps
+    // its known hosts and returns null for any other.
+    resolveApexTenant: () => DEV_TENANT_ID as TenantId,
+    allowCustomCss: true,
+  }),
 
   // Template overview, layout editor and PDF template editor; needs template-resolver and managed-pages above.
   createDocumentDesignerFeature(),

package/samples/recipes/cross-feature-events/README.md

@@ -26,6 +26,13 @@ Three building blocks:
   external system). With `table`, the apply materializes a persistent
   read model.
 
+- **`r.job(name, { trigger: { on: event.name, catchUp: true } }, run)`**
+  runs a job per stored event. With `catchUp` the job owns its own
+  consumer cursor (`job:<jobQn>`) that starts at the beginning of the
+  event store, so a job added to a running app also processes the
+  events from before its deploy. Each event enqueues at most one run.
+  Without `catchUp` a job only sees events appended after it went live.
+
 ## Flow
 
 ```
@@ -61,3 +68,6 @@ The integration test pins three guarantees:
 ```bash
 bun kumiko test integration samples/cross-feature-events
 ```
+4. **Catch-up job** — `catch-up-job.integration.test.ts` places orders
+   before the first dispatcher pass and checks that the `catchUp` job
+   invoices each of them exactly once.

package/samples/recipes/cross-feature-events/src/feature.ts

@@ -60,6 +60,7 @@ export type CapturedEvent = {
   readonly tenantId: string;
 };
 export const capturedEvents: CapturedEvent[] = [];
+export const invoicedOrderIds: string[] = [];
 
 // --- Feature ---
 
@@ -103,6 +104,19 @@ export const pubsubOrderFeature = defineFeature("pubsubOrders", (r) => {
     access: { roles: ["Admin", "Customer"] },
   });
 
+  // A job can react to the same event. `catchUp: true` gives the job its own
+  // consumer cursor that starts at the beginning of the event store, so a job
+  // added to a running app also processes the orders placed before it existed.
+  // Without catchUp the job only sees events appended after its deploy.
+  r.job(
+    "invoice-order",
+    { trigger: { on: orderPlaced.name, catchUp: true }, runIn: "worker" },
+    async (payload) => {
+      const order = orderPlaced.schema.parse(payload);
+      invoicedOrderIds.push(order.id);
+    },
+  );
+
   // Async consumer — Marten-style. Fires after commit, via the event-
   // dispatcher. No `table` means this MSP is pure side-effect (no state
   // persisted). Delivery is at-least-once and ordered per consumer.

package/samples/recipes/dashboard-stats/README.md

@@ -20,6 +20,14 @@ query and the fields to read, the query does the counting.
   `list` with `filter`, `limit: 1` and `totalCount: true`. The total is counted
   over the whole WHERE clause, so no rows are loaded just to be counted.
 - **Labels are translation keys**: declared with `r.translations`.
+- **Record-bound dashboard**: `ticket-record-dashboard` binds to a record with `record`
+  and embeds the `ticket-card` projectionDetail as a screen panel; the record id
+  becomes its entityId.
+- **Gated toolbar button**: `visibleWhen` on a toolbar action asks a flat
+  capability query; the button is hidden while it loads or fails.
+- **Fallback by reason**: `fallback: { forbidden, notFound }` renders a screen on
+  403/404 of the gate query; other reasons get the default notice or an error
+  banner with retry.
 
 ## When to reach for it
 

package/samples/recipes/dashboard-stats/src/feature.ts

@@ -1,6 +1,8 @@
 // Dashboard Stats Sample
 // Shows: a dashboard screen with a stat-group and a single stat, backed by one
-// query handler that counts in the database.
+// query handler that counts in the database. A second, record-bound dashboard embeds a
+// projectionDetail as a panel, hides a toolbar button behind a capability query, and picks its
+// fallback screen by the reason the gate closed.
 
 import {
   createEntity,
@@ -22,6 +24,7 @@ export const ticketEntity = createEntity({
 });
 
 export const TICKET_STATS_QUERY = "tickets:query:ticket:stats";
+export const TICKET_CAPABILITIES_QUERY = "tickets:query:ticket:capabilities";
 
 const readerRoles = { roles: ["Admin", "User"] } as const;
 
@@ -57,8 +60,51 @@ export const ticketFeature = defineFeature("tickets", (r) => {
     access: readerRoles,
   });
 
+  // Gate for the screens below: a flat answer with one boolean the screens test with `eq`.
+  r.queryHandler({
+    name: "ticket:capabilities",
+    schema: z.object({}),
+    outputSchema: z.object({ canClose: z.boolean() }),
+    handler: async (query) => ({ canClose: query.user.roles.includes("Admin") }),
+    access: readerRoles,
+  });
+
+  r.queryHandler({
+    name: "ticket:card",
+    schema: z.object({ id: z.string() }),
+    handler: async (query, ctx) => {
+      const page = await ticketExecutor.list(
+        { filter: { field: "id", op: "eq", value: query.payload.id }, limit: 1 },
+        query.user,
+        ctx.db,
+      );
+      const ticket = page.rows[0];
+      return { id: query.payload.id, title: ticket?.title ?? "", status: ticket?.status ?? "" };
+    },
+    access: readerRoles,
+  });
+
+  r.queryHandler({
+    name: "ticket:rows",
+    schema: z.object({}),
+    handler: async (query, ctx) => {
+      const page = await ticketExecutor.list({ limit: 50 }, query.user, ctx.db);
+      return { rows: page.rows, nextCursor: null };
+    },
+    access: readerRoles,
+  });
+
   r.translations({
     keys: {
+      "screen:ticket-list.title": { en: "Tickets" },
+      "screen:ticket-card.title": { en: "Ticket" },
+      "screen:ticket-record-dashboard.title": { en: "Ticket overview" },
+      "entity:ticket:field:title": { en: "Title" },
+      "entity:ticket:field:status": { en: "Status" },
+      "entity:__projection-detail__:field:title": { en: "Title" },
+      "entity:__projection-detail__:field:status": { en: "Status" },
+      "tickets.toolbar.close": { en: "Close all done" },
+      "tickets.dashboard.card": { en: "Ticket" },
       "tickets.dashboard.group": { en: "Tickets by status" },
       "tickets.dashboard.open": { en: "Open" },
       "tickets.dashboard.closed": { en: "Closed" },
@@ -101,4 +147,48 @@ export const ticketFeature = defineFeature("tickets", (r) => {
     ],
     access: readerRoles,
   });
+
+  // Three additions: a projectionDetail embedded in a record-bound dashboard, a gated toolbar
+  // button, and a fallback chosen by reason.
+  const gate = { query: TICKET_CAPABILITIES_QUERY, field: "canClose", eq: true } as const;
+
+  // The list doubles as the fallback target: it has no visibleWhen of its own.
+  r.screen({
+    id: "ticket-list",
+    type: "projectionList",
+    query: "tickets:query:ticket:rows",
+    columns: ["title", "status"],
+    access: readerRoles,
+    toolbarActions: [
+      {
+        kind: "writeHandler",
+        id: "close-done",
+        label: "tickets.toolbar.close",
+        handler: "tickets:write:ticket:update",
+        // Live and fail-closed: hidden while the query loads and when it fails.
+        visibleWhen: gate,
+      },
+    ],
+  });
+
+  r.screen({
+    id: "ticket-card",
+    type: "projectionDetail",
+    query: "tickets:query:ticket:card",
+    layout: { sections: [{ title: "tickets.dashboard.card", fields: ["title", "status"] }] },
+    access: readerRoles,
+    visibleWhen: gate,
+    // 403 and 404 on the gate query get their own screen; an unmet condition keeps the
+    // default notice and any other failure shows an error banner with retry.
+    fallback: { forbidden: "ticket-list", notFound: "ticket-list" },
+  });
+
+  // `record` reads the id from the URL; the embedded projectionDetail receives it as its entityId.
+  r.screen({
+    id: "ticket-record-dashboard",
+    type: "dashboard",
+    record: { param: "ticketId", payloadKey: "id" },
+    panels: [{ kind: "screen", id: "card", screen: "ticket-card" }],
+    access: readerRoles,
+  });
 });

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

@@ -10,7 +10,7 @@ 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 })`, `dodoEnvSchema({ prices })` and
+  `stripeEnvSchema({ prices })`, `paddleEnvSchema({ 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,
@@ -27,7 +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 |
+| `paddleEnvSchema({ prices })` | `subscription-paddle` | 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,7 +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 { paddleEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-paddle";
 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";
@@ -37,7 +37,7 @@ const appEnvSchema = z.object({
   ...buildInfoEnvSchema.shape,
   ...demoAdminEnvSchema.shape,
   ...stripeEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
-  ...dodoEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
+  ...paddleEnvSchema({ 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/inbound-mail-triage/README.md

@@ -28,6 +28,14 @@ mail-triage  ← this sample                                  (the app-side cons
 
 When the provider rejects the stored login, the supervisor sets the account to `auth_error` and stops fetching. With `inbound-provider-imap` mounted, the mail accounts list offers **Reconnect** on that row: the form `mail-account-reconnect-imap` is prefilled with the stored server settings (never the password), `inbound-provider-imap:write:reconnect-mailbox` checks the new login and puts the same account back to `active`. Threads, sync cursor and seen messages stay, so the next poll continues where the account stopped instead of ingesting the mailbox again. The cases are covered in `inbound-provider-imap/__tests__/reconnect-mailbox.integration.test.ts`; they need greenmail, which this sample's in-memory provider does not.
 
+## Mail content, quarantine and status
+
+Every ingested mail now carries its full text (`bodyText`, at most 32,000 characters, flagged by `bodyTextTruncated`), the original (`.eml`, or `.html` for HTML-only mails) and its attachments as file references; `inbound-mail-foundation:query:message:content` returns them, while `message:list` stays light and never carries the body. Retention removes the mail row but keeps the attachment files. Needs file storage in the app; without it the mail is still imported and the mailbox shows **Unterbrochen** (`file_storage_unavailable`).
+
+A mail the provider cannot parse is set aside in quarantine instead of blocking the mailbox: the rest imports, the sync cursor moves on, the account shows `degraded` with `lastError: message_quarantined` and the count, and `acknowledge-quarantine` clears it. Three failed polls in a row (`connection_failed`, `rate_limited`) also mark the mailbox `degraded` until the next success.
+
+A disconnected mailbox keeps its account id: `reactivate-account` (or connecting the same OAuth address again) puts it back to `active` with its cursor, so nothing is imported twice, and the mail arrives right away instead of at the next poll. Connecting an address that is already connected is refused with 409.
+
 ## Tests
 
 - E2E through `createAllInOneEntrypoint` (HTTP → dispatcher → BullMQ worker lane, no framework-internal shortcuts): connect → ingest → triage item appears.

package/samples/recipes/pdf-audit-export/src/feature.ts

@@ -4,7 +4,9 @@
 // FileRef: renderTablePdf draws the table (pure JS, no browser). The storage
 // write runs in the beforeTransaction phase, so the transaction holds no pool
 // connection while the bytes upload; the handler then only creates the
-// fileRef row from event.prepared.
+// fileRef row from event.prepared. Called from another handler (a nested
+// write) there is no such phase, so the handler renders and stores inside the
+// caller's transaction instead.
 
 import { renderTablePdf } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
 import {
@@ -19,6 +21,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import {
+  createFileRefFromBytes,
   createFileRefFromUploadedBytes,
   uploadFileBytesBeforeTransaction,
 } from "@cosmicdrift/kumiko-framework/files";
@@ -60,6 +63,62 @@ export const pdfAuditExportFeature = defineFeature("pdf-audit-export", (r) => {
   r.entity({ name: "inspection", ...inspectionEntity });
   const { executor: inspectionExecutor } = createEntityExecutor("inspection", inspectionEntity);
 
+  type AuditPayload = { assetName: string; from: string; to: string };
+  type ExecutorUser = Parameters<typeof inspectionExecutor.list>[1];
+  type ExecutorDb = Parameters<typeof inspectionExecutor.list>[2];
+
+  async function renderAudit(payload: AuditPayload, user: ExecutorUser, db: ExecutorDb) {
+    const { assetName, from, to } = payload;
+    const inspections = await inspectionExecutor.list(
+      {
+        filters: [
+          { field: "assetName", op: "eq", value: assetName },
+          { field: "inspectedOn", op: "gte", value: from },
+          { field: "inspectedOn", op: "lte", value: to },
+        ],
+        sort: "inspectedOn",
+        sortDirection: "asc",
+        limit: AUDIT_ROW_LIMIT + 1,
+      },
+      user,
+      db,
+    );
+    // A protocol that silently drops inspections would look complete.
+    if (inspections.rows.length > AUDIT_ROW_LIMIT) {
+      return writeFailure(
+        new UnprocessableError("audit_period_too_large", {
+          details: { limit: AUDIT_ROW_LIMIT },
+        }),
+      );
+    }
+
+    const { pdfBytes } = await renderTablePdf({
+      title: `Prüfprotokoll ${assetName}`,
+      meta: [
+        { label: "Zeitraum", value: `${formatGermanDate(from)} bis ${formatGermanDate(to)}` },
+        { label: "Prüfungen", value: String(inspections.rows.length) },
+      ],
+      columns: [{ header: "Datum" }, { header: "Ergebnis" }, { header: "Prüfer", weight: 2 }],
+      rows: inspections.rows.map((row) => [
+        formatGermanDate(String(row["inspectedOn"])),
+        RESULT_LABELS[z.enum(INSPECTION_RESULTS).parse(row["result"])],
+        String(row["inspector"] ?? ""),
+      ]),
+      emptyText: "Keine Prüfungen im Zeitraum",
+      footerText: `Prüfbericht ${assetName}`,
+      pageLabel: "Seite {page} von {pages}",
+    });
+
+    return {
+      isSuccess: true as const,
+      data: {
+        fileName: `audit-${toFileNameSegment(assetName)}.pdf`,
+        mimeType: "application/pdf",
+        data: pdfBytes,
+      },
+    };
+  }
+
   r.writeHandler({
     name: "inspection:create",
     schema: z.object({
@@ -77,56 +136,20 @@ export const pdfAuditExportFeature = defineFeature("pdf-audit-export", (r) => {
       name: "export-audit",
       schema: z.object({ assetName: z.string().min(1), from: z.iso.date(), to: z.iso.date() }),
       access: access.access,
+      // Nested in another command there is no phase of its own; the handler then does this work itself.
+      beforeTransactionWhenNested: "skip",
       beforeTransaction: async (event, ctx) => {
-        const { assetName, from, to } = event.payload;
-        const inspections = await inspectionExecutor.list(
-          {
-            filters: [
-              { field: "assetName", op: "eq", value: assetName },
-              { field: "inspectedOn", op: "gte", value: from },
-              { field: "inspectedOn", op: "lte", value: to },
-            ],
-            sort: "inspectedOn",
-            sortDirection: "asc",
-            limit: AUDIT_ROW_LIMIT + 1,
-          },
-          event.user,
-          ctx.db,
-        );
-        // A protocol that silently drops inspections would look complete.
-        if (inspections.rows.length > AUDIT_ROW_LIMIT) {
-          return writeFailure(
-            new UnprocessableError("audit_period_too_large", {
-              details: { limit: AUDIT_ROW_LIMIT },
-            }),
-          );
-        }
-
-        const { pdfBytes } = await renderTablePdf({
-          title: `Prüfprotokoll ${assetName}`,
-          meta: [
-            { label: "Zeitraum", value: `${formatGermanDate(from)} bis ${formatGermanDate(to)}` },
-            { label: "Prüfungen", value: String(inspections.rows.length) },
-          ],
-          columns: [{ header: "Datum" }, { header: "Ergebnis" }, { header: "Prüfer", weight: 2 }],
-          rows: inspections.rows.map((row) => [
-            formatGermanDate(String(row["inspectedOn"])),
-            RESULT_LABELS[z.enum(INSPECTION_RESULTS).parse(row["result"])],
-            String(row["inspector"] ?? ""),
-          ]),
-          emptyText: "Keine Prüfungen im Zeitraum",
-          footerText: `Prüfbericht ${assetName}`,
-          pageLabel: "Seite {page} von {pages}",
-        });
-
-        return uploadFileBytesBeforeTransaction(ctx, {
-          fileName: `audit-${toFileNameSegment(assetName)}.pdf`,
-          mimeType: "application/pdf",
-          data: pdfBytes,
-        });
+        const rendered = await renderAudit(event.payload, event.user, ctx.db);
+        if (!rendered.isSuccess) return rendered;
+        return uploadFileBytesBeforeTransaction(ctx, rendered.data);
       },
       handler: async (event, ctx) => {
-        const created = await createFileRefFromUploadedBytes(ctx, event.prepared);
+        const created =
+          event.prepared !== undefined
+            ? await createFileRefFromUploadedBytes(ctx, event.prepared)
+            : await renderAudit(event.payload, event.user, ctx.db).then((rendered) =>
+                rendered.isSuccess ? createFileRefFromBytes(ctx, rendered.data) : rendered,
+              );
         if (!created.isSuccess) return created;
         return { isSuccess: true as const, data: { fileRefId: created.data.id } };
       },