@cosmicdrift/kumiko-samples 0.338.0

package/samples/recipes/field-access/README.md

@@ -0,0 +1,71 @@
+# Field-level access
+
+Restrict individual fields by role — separate read and write rules per
+field, no `if` branches in the handler. This recipe ships an `employee`
+entity where `salary` is visible to Admin and Accounting (only Admin
+writes) and `internalNotes` is Admin-only on both sides.
+
+The framework strips fields the caller cannot read on the way out and
+rejects writes that touch fields the caller cannot write. Your handler
+never sees a forbidden field on input, never produces one on output.
+
+## What it shows
+
+- **`access: { read, write }` on a field factory** — two independent
+  rules per field, both expressed as role lists.
+- **Read-side filtering** — querying as `Employee` returns the row
+  without the `salary` and `internalNotes` keys; querying as
+  `Accounting` returns `salary` but not `internalNotes`.
+- **Write-side enforcement** — a write payload that includes
+  `internalNotes` from a non-Admin role fails with
+  `field_access_denied` and the offending field path.
+- **No handler-level branching** — the same `r.queryHandler` body
+  serves all three roles; the framework filters output per call.
+
+## Feature composition
+
+```
+hr → employee entity with field-level access on salary + internalNotes
+```
+
+Single feature, no bundled dependencies — field access is declared on
+the field factories inside `createEntity`.
+
+## Flow
+
+1. Admin creates an employee with all fields populated.
+2. Accounting reads detail → sees `salary`, not `internalNotes`.
+3. Employee reads detail → sees `name`/`email` only.
+4. Accounting tries to write `salary` → `field_access_denied` (read-only).
+5. Employee updates `name` → succeeds (unrestricted field).
+
+## When to reach for it
+
+Sensitive columns that a feature still needs to expose — phone numbers,
+salary figures, internal compliance notes. The whole row stays usable
+for everyone; specific fields disappear for callers without the
+right role.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+bun kumiko test integration samples/field-access
+```
+
+Or from the recipe directory:
+
+```bash
+bun test src/__tests__/feature.integration.test.ts
+```
+
+Covers all three roles reading and writing, including the expected
+`field_access_denied` response shape.
+
+## Related samples
+
+- [basic-entity](/en/samples/recipes-basic-entity/) — start here if you
+  need standard CRUD before adding field rules.
+- [custom-handlers](/en/samples/recipes-custom-handlers/) — explicit
+  handlers when generated CRUD is not enough.

package/samples/recipes/field-access/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-field-access",
+  "description": "Field-level access control. When entity-level roles aren't granular enough.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/field-access/src/feature.ts

@@ -0,0 +1,32 @@
+import {
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const employeeEntity = createEntity({
+  table: "read_sample_employees",
+  fields: {
+    name: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    email: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    salary: createNumberField({
+      access: { read: ["Admin", "Accounting"], write: ["Admin"] },
+    }),
+    internalNotes: createTextField({
+      personal: { of: "id" },
+      find: "none",
+      access: { read: ["Admin"], write: ["Admin"] },
+    }),
+  },
+});
+
+const allRoles = { access: { roles: ["Admin", "Accounting", "Employee"] } } as const;
+
+export const employeeFeature = defineFeature("hr", (r) => {
+  r.crud("employee", employeeEntity, {
+    write: allRoles,
+    read: allRoles,
+    verbs: { delete: false, list: false, restore: false },
+  });
+});

package/samples/recipes/files-post-processing/README.md

@@ -0,0 +1,21 @@
+# Files Post Processing
+
+File upload plus post-processing hooks.
+
+## What it shows
+
+- Declarative `variants` on `createImageField` (file-derivatives)
+- Imperative `ctx.derivatives.variant()` path and the public variant route (`EXT_DERIVATIVE_PUBLIC_PREDICATE`)
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/files-post-processing
+bun test
+```

package/samples/recipes/files-post-processing/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-files-post-processing",
+  "description": "The three ways to generate an image variant: declarative field variants, imperative ctx.derivatives.variant() with region-blur, and the public route behind a default-deny predicate.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "sharp": "^0.35.3"
+  }
+}

package/samples/recipes/files-post-processing/src/feature.ts

@@ -0,0 +1,138 @@
+// Files Post-Processing Sample
+//
+// The three ways to get an image variant out of a FileRef — see
+// docs/reference/core-files.md for the full write-up of the contract and
+// security model behind each.
+//
+//   1. Declarative — `original`'s `variants` map on the `photo` entity. The
+//      normal case (profile picture, hero image, floor plan): the framework
+//      resolves + caches the variant behind the auth-gated
+//      `GET /api/files/:id/variant/:name` route, no handler code needed.
+//   2. Imperative — the `set-cover` write-handler calls
+//      `ctx.derivatives.variant()` directly. This is for apps that track
+//      images as their own records (ordering, a chosen cover image) and for
+//      region-blur, whose coordinates are runtime data that can't live in a
+//      static field declaration.
+//   3. The public route with a predicate — the part people get wrong. Only
+//      entityIds explicitly marked published resolve; everything else 404s,
+//      indistinguishable from "doesn't exist".
+
+import type { DerivativePublicPredicateArgs } from "@cosmicdrift/kumiko-bundled-features/file-derivatives";
+import {
+  createEntity,
+  createImageField,
+  defineFeature,
+  EXT_DERIVATIVE_PUBLIC_PREDICATE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+
+// The `variants` map IS the whitelist the auth-gated variant route resolves
+// against — no separate registration step. Named `thumb`/`hero` on purpose:
+// the public route's fixed presets (thumb/card/hero/full, entry point 3)
+// share the name `thumb` but are a completely separate spec — same label,
+// different whitelist, different actual pixels.
+const photoEntity = createEntity({
+  table: "files_post_processing_photos",
+  fields: {
+    original: createImageField({
+      variants: {
+        thumb: { maxEdge: 200, fit: "cover", format: "webp" },
+        hero: { maxEdge: 1200, fit: "inside", format: "webp" },
+      },
+    }),
+  },
+});
+
+// A real app would check a `published` column via the entity's read model.
+// This recipe tracks it in memory to stay a single file — the predicate
+// below is what matters, not where the flag is stored. Keyed by
+// `${tenantId}:${entityId}`, not entityId alone — two tenants can each have
+// their own entityId "p3", and an entityId-only key would leak tenant A's
+// publish state onto tenant B's photo.
+export const publishedPhotoIds = new Set<string>();
+
+// Exported so the integration test can assert the imperative path ran.
+export const coverOrder: string[] = [];
+
+export const filesPostProcessingFeature = defineFeature("files-post-processing", (r) => {
+  r.requires("file-derivatives");
+  r.entity("photo", photoEntity);
+
+  // Entry point 2 — imperative. A real app would gate this behind real
+  // roles; `openToAll` keeps the recipe's HTTP wiring to one line.
+  r.writeHandler(
+    "set-cover",
+    z.object({
+      fileRefId: z.string(),
+      // Relative to the ORIGINAL image's pixels, clamped before resize —
+      // runtime data (e.g. a detected face box), which is exactly why this
+      // can only be expressed imperatively, not in a static field def.
+      blurRegion: z
+        .object({
+          x: z.number().nonnegative(),
+          y: z.number().nonnegative(),
+          width: z.number().positive(),
+          height: z.number().positive(),
+        })
+        .optional(),
+    }),
+    async (event, ctx) => {
+      if (!ctx.derivatives) {
+        return writeFailure(
+          new InternalError({ message: "ctx.derivatives missing — is file-derivatives mounted?" }),
+        );
+      }
+      const { fileRefId, blurRegion } = event.payload;
+      const result = await ctx.derivatives.variant(
+        fileRefId,
+        {
+          maxEdge: 800,
+          fit: "cover",
+          format: "webp",
+          ...(blurRegion ? { blurRegions: [blurRegion] } : {}),
+        },
+        "cover",
+      );
+      coverOrder.push(fileRefId);
+      return { isSuccess: true as const, data: { fileRefId, storageKey: result.storageKey } };
+    },
+    {
+      access: {
+        openToAll: {
+          reason:
+            "demo recipe: any signed-in user may generate a cover-image derivative for " +
+            "a file; there is no per-user file ownership check in this sample",
+        },
+      },
+    },
+  );
+
+  // A real app would gate this behind real roles; `openToAll` keeps the
+  // recipe's HTTP wiring to one line.
+  r.writeHandler(
+    "publish",
+    z.object({ entityId: z.string() }),
+    async (event) => {
+      publishedPhotoIds.add(`${event.user.tenantId}:${event.payload.entityId}`);
+      return { isSuccess: true as const, data: { entityId: event.payload.entityId } };
+    },
+    {
+      access: {
+        openToAll: {
+          reason:
+            "demo recipe: any signed-in user may mark a photo entity published; a real " +
+            "app would replace this with a role check as noted above",
+        },
+      },
+    },
+  );
+
+  // Entry point 3 — default-deny. No registration here means every entityId
+  // 404s; a registration that returns false does the same. Only an explicit
+  // `true` serves bytes.
+  r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "photo", {
+    isPublic: ({ entityId, tenantId }: DerivativePublicPredicateArgs) =>
+      publishedPhotoIds.has(`${tenantId}:${entityId}`),
+  });
+});

package/samples/recipes/i18n/README.md

@@ -0,0 +1,36 @@
+# i18n
+
+Feature-scoped translations — 'Hallo' and 'Hello' in the same app.
+
+## What it shows
+
+- `r.translations()` for multi-language feature keys
+- Plurals
+
+## Plurals
+
+A translation value can be a CLDR plural-forms object instead of a plain
+string. `other` is required; the rest (`zero`/`one`/`two`/`few`/`many`) only
+exist where the locale's grammar needs them:
+
+```ts
+"greeting.unread_count": {
+  de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
+  en: { one: "{count} unread message", other: "{count} unread messages" },
+},
+```
+
+`t(key, locale, { count })` picks the CLDR category for `count` via
+`Intl.PluralRules(locale)`, then interpolates `{count}` (and any other
+`{name}` placeholder) into the chosen form.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/i18n
+bun test
+```

package/samples/recipes/i18n/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-i18n",
+  "description": "Feature-scoped translations. 'Hallo' and 'Hello' in the same app.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/i18n/src/feature.ts

@@ -0,0 +1,52 @@
+// i18n Sample
+// Shows: r.translations() for multi-language feature keys, and plural forms
+// (CLDR categories) for a count-dependent key
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+export const greetingFeature = defineFeature("greeting", (r) => {
+  r.translations({
+    keys: {
+      "greeting.welcome": {
+        de: "Willkommen",
+        en: "Welcome",
+        fr: "Bienvenue",
+      },
+      "greeting.goodbye": {
+        de: "Auf Wiedersehen",
+        en: "Goodbye",
+        fr: "Au revoir",
+      },
+      "greeting.hello_name": {
+        de: "Hallo, {name}!",
+        en: "Hello, {name}!",
+        fr: "Bonjour, {name}!",
+      },
+      "greeting.unread_count": {
+        de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
+        en: { one: "{count} unread message", other: "{count} unread messages" },
+        pl: {
+          one: "{count} nieprzeczytana wiadomość",
+          few: "{count} nieprzeczytane wiadomości",
+          many: "{count} nieprzeczytanych wiadomości",
+          other: "{count} nieprzeczytanej wiadomości",
+        },
+      },
+    },
+  });
+});
+
+export const errorFeature = defineFeature("errors", (r) => {
+  r.translations({
+    keys: {
+      "errors.not_found": {
+        de: "Nicht gefunden",
+        en: "Not found",
+      },
+      "errors.access_denied": {
+        de: "Zugriff verweigert",
+        en: "Access denied",
+      },
+    },
+  });
+});

package/samples/recipes/idempotency/README.md

@@ -0,0 +1,21 @@
+# Idempotency
+
+Same request, same result — dedupe on request ID.
+
+## What it shows
+
+- `requestId` prevents duplicate inserts and returns the cached result
+- Custom write handler that owns business defaults
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/idempotency
+bun test
+```

package/samples/recipes/idempotency/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-idempotency",
+  "description": "Same request, same result. Dedupes on request ID.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/idempotency/src/feature.ts

@@ -0,0 +1,50 @@
+// Idempotency Sample
+// Shows: requestId prevents duplicate inserts, returns cached result.
+// Custom `order:place` handler so we can inject a default status — a generic
+// `order:create` would not know about the business rule "new orders start as
+// pending".
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const orderEntity = createEntity({
+  table: "read_sample_orders",
+  fields: {
+    customerName: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    product: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    status: createTextField({ personal: false, reason: "is_business_data", default: "pending" }),
+  },
+});
+
+const orderTable = buildEntityTable("order", orderEntity);
+export const orderFeature = defineFeature("orders", (r) => {
+  r.entity("order", orderEntity);
+
+  const orderExecutor = createEventStoreExecutor(orderTable, orderEntity, { entityName: "order" });
+
+  r.writeHandler(
+    "order:place",
+    z.object({
+      customerName: z.string().min(1),
+      product: z.string().min(1),
+    }),
+    async (event, ctx) =>
+      orderExecutor.create({ ...event.payload, status: "pending" }, event.user, ctx.db),
+    { access: { roles: ["Admin", "Customer"] } },
+  );
+
+  r.queryHandler(
+    "order:list",
+    z.object({ limit: z.number().optional() }),
+    async (query, ctx) => orderExecutor.list(query.payload, query.user, ctx.db),
+    {
+      access: {
+        openToAll: {
+          reason:
+            "any signed-in user may list orders in this recipe; placing an order still requires a role above",
+        },
+      },
+    },
+  );
+});

package/samples/recipes/inbound-mail-triage/README.md

@@ -0,0 +1,30 @@
+# Sample: Inbound-Mail Triage
+
+Attach a business process to inbound e-mail: `inbound-mail-foundation` owns transport, dedup and PII — this sample's `mail-triage` feature turns every ingested mail into a triage item via a worker-lane job.
+
+## What you learn here
+
+- **Consumer pattern**: hook your business process onto the foundation's ingest write-handler with `r.job({ trigger: { on: InboundMailFoundationHandlers.ingestMessage } })` — the job receives the plaintext normalized mail (PII encryption happens inside the handler, after your trigger payload was captured).
+- **Idempotency discipline**: the trigger also fires on idempotent replays (duplicate ingest returns success) — key your side-effects by `providerMessageId` so replays overwrite instead of duplicating.
+- **Provider swap**: the test drives `inbound-provider-inmemory`; production mounts `inbound-provider-imap` (password/app-password, IMAP IDLE) against the same contract — the consumer code does not change.
+
+## Feature composition
+
+```
+tenant-lifecycle (transitively pulls tenant + config + compliance-profiles)
+inbound-mail-foundation                                     (streams, projections, ingest)
+inbound-provider-inmemory                                   (scriptable provider)
+mail-triage  ← this sample                                  (the app-side consumer)
+```
+
+## Flow
+
+1. `connect-account` creates a mail account (shared mailbox, `ownerUserId = null`).
+2. A mail is ingested — in production the watch-supervisor (IMAP IDLE push) or the reconciliation poll dispatches `ingest-message`; the inline projection materializes `read_inbound_messages` in the same transaction.
+3. The handler-trigger fans the write out to the worker lane; the triage job records `{ from, subject, scope, threadHint }`.
+4. A replay of the same `providerMessageId` reports `duplicate: true`, creates no second row — and the keyed triage store stays at one item.
+
+## Tests
+
+- E2E through `createAllInOneEntrypoint` (HTTP → dispatcher → BullMQ worker lane, no framework-internal shortcuts): connect → ingest → triage item appears.
+- Replay scenario: duplicate ingest stays idempotent on both the projection and the consumer side.

package/samples/recipes/inbound-mail-triage/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-inbound-mail-triage",
+  "description": "Inbound-mail consumer pattern: inbound-mail-foundation + in-memory provider, a worker-lane triage job attached to the ingest handler, verified end-to-end through createAllInOneEntrypoint.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/inbound-mail-triage/src/feature.ts

@@ -0,0 +1,68 @@
+// Inbound-Mail Triage Sample
+//
+// Shows the consumer pattern for `inbound-mail-foundation`: the
+// foundation owns transport, dedup and PII handling — the app attaches
+// its business process to the ingest write-handler via a worker-lane
+// job. Every inbound mail becomes a triage item; a real app would
+// create a ticket, run an AI classification, extract an invoice or
+// draft a reply here.
+//
+// Feature composition (see the test):
+//   inbound-mail-foundation   — streams, projections, ingest handler
+//   inbound-provider-inmemory — scriptable provider (tests/demos)
+//   mail-triage (this file)   — the app-side consumer
+//
+// The trigger fires AFTER every successful ingest-message write — that
+// includes idempotent replays (duplicate ingest returns success). The
+// triage store is therefore keyed by providerMessageId: replays
+// overwrite instead of duplicating. Key your side-effects the same way.
+
+import {
+  InboundMailFoundationHandlers,
+  type RawInboundMessage,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+export type TriageItem = {
+  readonly from: string;
+  readonly subject: string;
+  readonly scope: string;
+  readonly threadHint: string | null;
+};
+
+// In-memory store so the integration-test can assert the job ran with
+// the right payload. A real app would do domain writes / AI calls /
+// notifications — the side-effect is opaque to the framework.
+export const triageInbox = new Map<string, TriageItem>();
+
+export function createMailTriageFeature(): FeatureDefinition {
+  return defineFeature("mail-triage", (r) => {
+    r.describe(
+      "Sample consumer for inbound-mail-foundation: a worker-lane job triggered by the ingest-message write-handler turns every inbound mail into a triage item.",
+    );
+    r.requires("inbound-mail-foundation");
+
+    // The job receives the dispatcher-validated ingest payload — i.e.
+    // the PLAINTEXT normalized mail (PII encryption happens inside the
+    // handler right before the event append, so consumers on the
+    // handler-trigger path never deal with ciphertext).
+    r.job(
+      "triage-inbound",
+      {
+        trigger: { on: InboundMailFoundationHandlers.ingestMessage },
+        runIn: "worker",
+      },
+      async (rawPayload) => {
+        // Dispatcher-validated ingest payload — one cast at the job boundary
+        // to the foundation's own message shape instead of per-field casts.
+        const payload = rawPayload as unknown as RawInboundMessage;
+        triageInbox.set(payload.providerMessageId, {
+          from: payload.from,
+          subject: payload.subject,
+          scope: payload.scope,
+          threadHint: payload.messageIdHeader,
+        });
+      },
+    );
+  });
+}

package/samples/recipes/lane-routing/README.md

@@ -0,0 +1,21 @@
+# Lane Routing
+
+Pin jobs to deploy lanes (`api` | `worker`) with event-triggered fan-out.
+
+## What it shows
+
+- `r.job({ runIn: "worker" })` after an HTTP write
+- End-to-end verification via `createAllInOneEntrypoint`
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/lane-routing
+bun test
+```

package/samples/recipes/lane-routing/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-lane-routing",
+  "description": "runIn lane-routing: r.job pinned to api/worker deploy-lanes, event-chain via ctx.appendEvent, verified end-to-end through createAllInOneEntrypoint.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}