@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/idempotency.md

@@ -0,0 +1,179 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/idempotency. Do not edit. -->
+
+# idempotency
+
+Same request, same result. Dedupes on request ID.
+
+## README
+
+# 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
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Idempotency Sample — Integration Test
+// Proves: duplicate requestId returns cached result, no double insert
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { orderEntity, orderFeature } from "../feature";
+
+let stack: TestStack;
+
+const customer = createTestUser({ roles: ["Customer"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [orderFeature] });
+  await unsafeCreateEntityTable(stack.db, orderEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  stack.events.reset();
+});
+
+describe("idempotent writes", () => {
+  test("same requestId returns cached result, no duplicate", async () => {
+    const requestId = "order-idem-001";
+
+    const first = await stack.http.writeOk<SaveContext>(
+      "orders:write:order:place",
+      { customerName: "Alice", product: "Widget" },
+      customer,
+      requestId,
+    );
+
+    const second = await stack.http.writeOk<SaveContext>(
+      "orders:write:order:place",
+      { customerName: "Alice", product: "Widget" },
+      customer,
+      requestId,
+    );
+
+    // Same ID = cached, not a new record
+    expect(second.id).toBe(first.id);
+  });
+
+  test("different requestIds create separate records", async () => {
+    const first = await stack.http.writeOk<SaveContext>(
+      "orders:write:order:place",
+      { customerName: "Bob", product: "Gadget A" },
+      customer,
+      "order-a",
+    );
+
+    const second = await stack.http.writeOk<SaveContext>(
+      "orders:write:order:place",
+      { customerName: "Bob", product: "Gadget B" },
+      customer,
+      "order-b",
+    );
+
+    expect(first.id).not.toBe(second.id);
+  });
+
+  test("no requestId = always creates new record", async () => {
+    const first = await stack.http.writeOk<SaveContext>(
+      "orders:write:order:place",
+      { customerName: "Carol", product: "Same" },
+      customer,
+    );
+
+    const second = await stack.http.writeOk<SaveContext>(
+      "orders:write:order:place",
+      { customerName: "Carol", product: "Same" },
+      customer,
+    );
+
+    expect(first.id).not.toBe(second.id);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// 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/agents/examples/inbound-mail-triage.md

@@ -0,0 +1,315 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/inbound-mail-triage. Do not edit. -->
+
+# inbound-mail-triage
+
+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.
+
+## README
+
+# 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.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Inbound-Mail Triage Sample — End-to-End Proof
+//
+// What we're proving (via createAllInOneEntrypoint + BullMQ + Hono — no
+// framework-internal shortcuts):
+//   1. connect-account creates a mail account (event-sourced stream +
+//      projection row).
+//   2. ingest-message lands on the HTTP surface (in production the
+//      watch-supervisor dispatches it), the inline projection
+//      materializes read_inbound_messages, and the handler-trigger
+//      fires the worker-lane triage job with the plaintext payload.
+//   3. An idempotent replay (same providerMessageId) does NOT create a
+//      second message row — and the keyed triage store keeps exactly
+//      one item even though the trigger fires again.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  InboundMailFoundationHandlers,
+  inboundMailFoundationFeature,
+  inboundMessageEntity,
+  mailAccountEntity,
+  mailThreadEntity,
+  seenMessageEntity,
+  syncCursorEntity,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { inboundProviderInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/inbound-provider-inmemory";
+import { createTenantFeature, tenantEntity } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createTenantLifecycleFeature } from "@cosmicdrift/kumiko-bundled-features/tenant-lifecycle";
+import { createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { createAllInOneEntrypoint } from "@cosmicdrift/kumiko-framework/entrypoint";
+import {
+  createArchivedStreamsTable,
+  createEventsTable,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import { createEventConsumerStateTable } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  createTestDb,
+  createTestRedis,
+  type TestDb,
+  type TestRedis,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
+import { createMailTriageFeature, triageInbox } from "../feature";
+
+const JWT = "inbound-mail-triage-secret-minimum-32-chars!";
+const adminUser = { ...TestUsers.systemAdmin, roles: ["SystemAdmin", "TenantAdmin"] };
+
+let testDb: TestDb;
+let testRedis: TestRedis;
+
+beforeAll(async () => {
+  [testDb, testRedis] = await Promise.all([createTestDb(), createTestRedis()]);
+  await createEventsTable(testDb.db);
+  await createArchivedStreamsTable(testDb.db);
+  await createEventConsumerStateTable(testDb.db);
+  // Entity-/Projection-Tables des Flows — der Entrypoint pusht (anders
+  // als setupTestStack) keine Tabellen.
+  await unsafeCreateEntityTable(testDb.db, tenantEntity);
+  await unsafeCreateEntityTable(testDb.db, tenantComplianceProfileEntity);
+  await unsafeCreateEntityTable(testDb.db, mailAccountEntity);
+  await unsafeCreateEntityTable(testDb.db, inboundMessageEntity);
+  await unsafeCreateEntityTable(testDb.db, mailThreadEntity);
+  await unsafeCreateEntityTable(testDb.db, syncCursorEntity);
+  await unsafeCreateEntityTable(testDb.db, seenMessageEntity);
+});
+
+afterAll(async () => {
+  await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
+});
+
+function ingestPayload(accountId: string) {
+  return {
+    accountId,
+    ownerUserId: null,
+    providerName: "inmemory",
+    providerMessageId: "uid-triage-1",
+    messageIdHeader: "triage-1@example.com",
+    providerThreadId: null,
+    references: [],
+    from: "Mieterin <mieterin@example.com>",
+    to: ["inbox@acme.example"],
+    cc: [],
+    subject: "Heizung defekt",
+    snippet: "Die Heizung im 2. OG faellt seit gestern aus …",
+    receivedAtIso: "2026-07-10T08:30:00Z",
+    bodyRef: "",
+    scope: "inbox",
+    providerCursor: '{"offset":1}',
+  };
+}
+
+describe("inbound-mail triage sample", () => {
+  test("inbound mail → ingest → worker-lane triage job; replay stays idempotent", async () => {
+    triageInbox.clear();
+    const registry = createRegistry([
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      inboundMailFoundationFeature,
+      inboundProviderInMemoryFeature,
+      createMailTriageFeature(),
+    ]);
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const entry = createAllInOneEntrypoint({
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl,
+      queueNamePrefix: `inbound-mail-triage-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    });
+    await entry.start();
+    try {
+      const token = await entry.jwt.sign(adminUser);
+      const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+      };
+
+      // 1. Postfach verbinden (shared: ownerUserId=null).
+      const connectRes = await entry.app.request("/api/write", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          type: InboundMailFoundationHandlers.connectAccount,
+          payload: {
+            provider: "inmemory",
+            authMethod: "password",
+            displayName: "Team-Inbox",
+            address: "inbox@acme.example",
+            scope: "shared",
+          },
+        }),
+      });
+      expect(connectRes.status).toBe(200);
+      const connectBody = (await connectRes.json()) as {
+        data: { accountId: string };
+      };
+      const accountId = connectBody.data.accountId;
+      expect(accountId).toBeDefined();
+
+      // 2. Mail ingest'en — in Produktion dispatcht das der
+      //    Watch-Supervisor (IDLE-Push) bzw. der Reconciliation-Poll.
+      const ingestRes = await entry.app.request("/api/write", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          type: InboundMailFoundationHandlers.ingestMessage,
+          payload: ingestPayload(accountId),
+        }),
+      });
+      expect(ingestRes.status).toBe(200);
+      const ingestBody = (await ingestRes.json()) as {
+        data: { duplicate: boolean };
+      };
+      expect(ingestBody.data.duplicate).toBe(false);
+
+      // 3. Der Business-Prozess (worker-lane job) feuert asynchron.
+      await waitFor(() => {
+        expect(triageInbox.size).toBe(1);
+      });
+      const item = triageInbox.get("uid-triage-1");
+      expect(item?.from).toContain("mieterin@example.com");
+      expect(item?.subject).toBe("Heizung defekt");
+      expect(item?.scope).toBe("inbox");
+      expect(item?.threadHint).toBe("triage-1@example.com");
+
+      // 4. Replay (IDLE-Doppel-Notify / Cursor-Overlap): Handler meldet
+      //    duplicate, Trigger feuert erneut — der keyed Store bleibt
+      //    bei genau einem Item.
+      const replayRes = await entry.app.request("/api/write", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          type: InboundMailFoundationHandlers.ingestMessage,
+          payload: ingestPayload(accountId),
+        }),
+      });
+      expect(replayRes.status).toBe(200);
+      const replayBody = (await replayRes.json()) as {
+        data: { duplicate: boolean };
+      };
+      expect(replayBody.data.duplicate).toBe(true);
+      // Trigger-Nachlauf abwarten, dann Idempotenz prüfen.
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      expect(triageInbox.size).toBe(1);
+    } finally {
+      await entry.stop();
+    }
+  }, 30_000);
+});
+```
+
+### src/feature.ts
+
+```ts
+// 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,
+        });
+      },
+    );
+  });
+}
+```