@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/agents/examples/delivery-notifications.md

@@ -0,0 +1,432 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/delivery-notifications. Do not edit. -->
+
+# delivery-notifications
+
+Delivery flows plus notifications. Package tracking, minus the tracking.
+
+## README
+
+# Sample: Delivery Notifications
+
+Shows how a feature sends notifications to multiple channels (InApp + Email + Push) without knowing the channel internals, and how the mail text lives in the template store where a tenant can override it.
+
+## What you learn here
+
+**Declarative notifications:** `r.notification()` declares the mail variables, the default mail text, the subject and the short inApp/push texts in one place.
+
+**Mail text is stored data:** The boot seed (`seedNotificationTemplates`) writes the declared `template` and `meta` into the template store as system templates. The email channel renders them with `renderer-mail-html`. A notification routed to email without `template` and `meta` fails its delivery.
+
+**Tenant override:** A tenant admin overrides the text through the template-resolver handlers (`upsertTenant`, then `publish`). The next mail for that tenant uses the override; the system text stays for everyone else.
+
+**Sending:** The write handler calls `ctx.notify(type, { to, data })`. The `data` keys are the template variables; sending fails loudly when a required variable is missing.
+
+**Swappable transports:** Email uses `InMemoryTransport` in tests; in a production setup it would be SMTP. Same interface, different implementation.
+
+## Feature composition
+
+The test loads these features together:
+
+```
+config            → tenant/system config
+tenant            → memberships (delivery needs tenant:query:resolve-user-ids)
+template-resolver → template store, override handlers
+renderer-foundation + renderer-mail-html → renders kind "mail"
+delivery          → core: ctx.notify, DeliveryLog, Preferences, extension points
+channel-inApp / channel-email / channel-push
+support           → our business logic (tickets + the notification declaration)
+```
+
+The `support` feature `r.requires("delivery")`: channels are features that attach to delivery, but `support` doesn't need to know them.
+
+## Flow
+
+1. The boot seed stores the `ticket-assigned` mail template
+2. Admin calls `support:write:ticket:create` over HTTP
+3. The handler inserts the ticket and calls `ctx.notify` for the assignee (no assignee, no notification)
+4. For each registered channel:
+   - InApp: `templates.inApp(data)`, DB insert + SSE push
+   - Email: stored template rendered with `data` as variables, then transport
+   - Push: `templates.push(data)`, transport
+5. DeliveryLog entry per channel
+
+## Tests
+
+- **E2E happy path:** Ticket with assignee → InApp + Email + Push + 3 DeliveryLog entries
+- **Tenant override:** a published tenant template replaces the system mail text
+- **Skip:** Ticket without assignee → no notifications
+- **Access control:** Non-Admin/Support can't create tickets
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Sample Integration Test: Delivery Notifications
+//
+// Proves the notification path end-to-end:
+// 1. The boot seed writes the declared mail template into the template store
+// 2. Admin creates a ticket with assignee (via HTTP API), the handler sends via ctx.notify
+// 3. InApp → DB + SSE
+// 4. Email → stored template → mail renderer → Transport
+// 5. Push → Transport
+// 6. DeliveryLog has entries for all 3 channels
+// 7. A tenant overrides the stored mail text and the next mail uses it
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createChannelEmailFeature,
+  createInMemoryTransport,
+  type EmailMessage,
+} from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import {
+  createChannelInAppFeature,
+  inAppMessagesTable,
+} from "@cosmicdrift/kumiko-bundled-features/channel-in-app";
+import {
+  createChannelPushFeature,
+  createInMemoryPushTransport,
+  type PushMessage,
+} from "@cosmicdrift/kumiko-bundled-features/channel-push";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  createDeliveryFeature,
+  createDeliveryTestContext,
+  deliveryAttemptsTable,
+  notificationPreferencesTable,
+} from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+import {
+  createTemplateResolverFeature,
+  TemplateResolverHandlers,
+} from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { seedNotificationTemplates } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
+import {
+  createTenantFeature,
+  TenantQueries,
+  tenantMembershipsTable,
+} from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { createRendererMailHtmlFeature } from "@cosmicdrift/kumiko-renderer-mail-html";
+import { supportFeature, TICKET_ASSIGNED, ticketTable } from "../feature";
+
+// --- Test Infrastructure ---
+
+const emailTransport = createInMemoryTransport();
+const pushTransport = createInMemoryPushTransport();
+
+// Simple resolvers: userId → address
+const testEmail = (userId: string) => `user-${userId}@example.com`;
+const testPushToken = (userId: string) => `push-token-${userId}`;
+
+// Test users
+const admin: SessionUser = TestUsers.admin;
+const assignee = createTestUser({ id: 5, roles: ["Support"] });
+
+// --- Feature Setup ---
+
+const features = [
+  createConfigFeature(),
+  createTenantFeature(),
+  createTemplateResolverFeature(),
+  createRendererFoundationFeature(),
+  createRendererMailHtmlFeature(),
+  createDeliveryFeature(),
+  createChannelInAppFeature(),
+  createChannelEmailFeature({
+    transport: emailTransport,
+    resolveEmail: async (userId) => testEmail(userId),
+  }),
+  createChannelPushFeature({
+    transport: pushTransport,
+    resolveToken: async (userId) => testPushToken(userId),
+  }),
+  supportFeature,
+];
+
+let stack: TestStack;
+let db: DbConnection;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features,
+    extraContext: (deps) =>
+      createDeliveryTestContext(deps, { tenantUserIdsQuery: TenantQueries.resolveUserIds }),
+  });
+  db = stack.db;
+
+  await unsafePushTables(db, {
+    inAppMessagesTable,
+    notificationPreferencesTable,
+    tenantMembershipsTable,
+    ticketTable,
+  });
+  await createEventsTable(db);
+  // setupTestStack does not run boot seeds; a real app seeds at boot.
+  await seedNotificationTemplates(db, stack.registry);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+// --- End-to-End Flow ---
+
+describe("delivery-notifications sample", () => {
+  test("ticket creation fires InApp + Email + Push notifications to assignee", async () => {
+    // Reset transports and SSE
+    emailTransport.sent.length = 0;
+    pushTransport.sent.length = 0;
+    stack.events.reset();
+
+    // --- Act: Admin creates a ticket with an assignee ---
+    await stack.http.writeOk(
+      "support:write:ticket:create",
+      {
+        title: "Login-Button reagiert nicht",
+        description: "Nach Klick auf Login passiert nichts in Firefox.",
+        assigneeId: assignee.id,
+        priority: "critical",
+        status: "open",
+      },
+      admin,
+    );
+
+    // --- Assert: InApp ---
+    const inAppMessages = await selectMany(db, inAppMessagesTable, { userId: assignee.id });
+    expect(inAppMessages).toHaveLength(1);
+    expect(inAppMessages[0]?.["title"]).toBe("New ticket: Login-Button reagiert nicht");
+    expect(inAppMessages[0]?.["body"]).toContain("Nach Klick auf Login");
+
+    const sseEvents = stack.events.sse.filter((e) => e.type === "channel-in-app:event:delivered");
+    expect(sseEvents).toHaveLength(1);
+    expect(sseEvents[0]?.data["userId"]).toBe(assignee.id);
+
+    // --- Assert: Email ---
+    const email = emailTransport.sent.find((e: EmailMessage) => e.to === testEmail(assignee.id));
+    expect(email).toBeDefined();
+    expect(email?.subject).toContain("Support ticket #");
+    expect(email?.subject).toContain("(critical)");
+    expect(email?.html).toContain("Login-Button reagiert nicht"); // title
+    expect(email?.html).toContain("Nach Klick auf Login"); // description
+    expect(email?.html).toContain("Priority: critical");
+    expect(email?.html).toContain("Open ticket"); // button
+    expect(email?.html).toContain("/support/tickets/"); // button URL
+
+    // --- Assert: Push ---
+    const push = pushTransport.sent.find(
+      (p: PushMessage) => p.token === testPushToken(assignee.id),
+    );
+    expect(push).toBeDefined();
+    expect(push?.title).toBe("New ticket");
+    expect(push?.body).toContain("Login-Button");
+    expect(push?.body).toContain("critical");
+
+    // --- Assert: DeliveryLog has entries for all 3 channels ---
+    const logs = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: TICKET_ASSIGNED,
+      recipientId: assignee.id,
+    });
+    expect(logs).toHaveLength(3);
+    const channels = logs.map((l) => l["channel"]);
+    expect(channels).toContain("inApp");
+    expect(channels).toContain("email");
+    expect(channels).toContain("push");
+    expect(logs.every((l) => l["status"] === "sent")).toBe(true);
+  });
+
+  test("a tenant override of the stored mail text replaces the system text", async () => {
+    emailTransport.sent.length = 0;
+    const tenantAdmin = { ...admin, roles: ["TenantAdmin"] };
+
+    const draft = await stack.http.writeOk<{ id: string }>(
+      TemplateResolverHandlers.upsertTenant,
+      {
+        slug: TICKET_ASSIGNED,
+        kind: "mail",
+        locale: "en",
+        content:
+          '<p>Tenant text: <span data-variable="title"></span></p><p><span data-variable="description"></span> (<span data-variable="priority"></span>)</p><p><a data-button href="{{url}}">Open</a></p>',
+        contentFormat: "html",
+        meta: { subject: "Tenant subject #{{ticketId}}" },
+        variableSchema: {},
+      },
+      tenantAdmin,
+    );
+    await stack.http.writeOk(TemplateResolverHandlers.publish, { id: draft.id }, tenantAdmin);
+
+    await stack.http.writeOk(
+      "support:write:ticket:create",
+      { title: "Printer on fire", assigneeId: assignee.id, priority: "normal", status: "open" },
+      admin,
+    );
+
+    const email = emailTransport.sent.find((e: EmailMessage) => e.to === testEmail(assignee.id));
+    expect(email?.subject).toContain("Tenant subject #");
+    expect(email?.html).toContain("Tenant text: Printer on fire");
+  });
+
+  test("ticket without assignee skips notification (recipient returns null)", async () => {
+    emailTransport.sent.length = 0;
+    pushTransport.sent.length = 0;
+
+    await stack.http.writeOk(
+      "support:write:ticket:create",
+      {
+        title: "Dokumentation ueberarbeiten",
+        description: "Die API-Docs sind veraltet.",
+        priority: "low",
+        status: "open",
+      },
+      admin,
+    );
+
+    // No notifications sent — no assignee
+    expect(emailTransport.sent).toHaveLength(0);
+    expect(pushTransport.sent).toHaveLength(0);
+  });
+
+  test("access control: non-Admin/Support cannot create tickets", async () => {
+    const normalUser = createTestUser({ id: 99, roles: ["User"] });
+    const error = await stack.http.writeErr(
+      "support:write:ticket:create",
+      {
+        title: "Hacked ticket",
+        priority: "normal",
+        status: "open",
+      },
+      normalUser,
+    );
+    expectErrorIncludes(error, "access_denied");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Delivery Notifications Sample
+//
+// A support ticket is created and its assignee is notified via inApp, email
+// and push. The mail is a stored template: `r.notification` declares the
+// variables, the default text and the subject, the boot seed writes the text
+// into the template store, and a tenant can override it there.
+//
+// The feature code only declares WHAT to notify. HOW is handled by Delivery.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  QnTypes,
+  qn,
+  templateVariable,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+// --- Entity ---
+
+export const ticketEntity = createEntity({
+  table: "read_sample_delivery_tickets",
+  fields: {
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      maxLength: 200,
+    }),
+    description: createTextField({ personal: false, reason: "is_business_data", maxLength: 2000 }),
+    assigneeId: createTextField({ personal: "ref" }),
+    priority: createTextField({ personal: false, reason: "is_business_data", required: true }), // "low" | "normal" | "critical"
+    status: createTextField({ personal: false, reason: "is_business_data", required: true }),
+  },
+});
+
+export const ticketTable = buildEntityTable("ticket", ticketEntity);
+
+function ticketExecutor() {
+  return createEventStoreExecutor(ticketTable, ticketEntity, { entityName: "ticket" });
+}
+
+// --- Feature ---
+
+export const TICKET_ASSIGNED = qn("support", QnTypes.notify, "ticket-assigned");
+
+export const supportFeature = defineFeature("support", (r) => {
+  r.requires("delivery");
+
+  r.entity("ticket", ticketEntity);
+
+  r.notification("ticket-assigned", {
+    variables: {
+      ticketId: templateVariable.text({ required: true }),
+      title: templateVariable.text({ required: true }),
+      description: templateVariable.text({ required: true }),
+      priority: templateVariable.text({ required: true }),
+      url: templateVariable.link({ required: true }),
+    },
+    template: {
+      en: {
+        body: '<h1>New ticket: <span data-variable="title"></span></h1><p><span data-variable="description"></span></p><p>Priority: <span data-variable="priority"></span></p><p><a data-button href="{{url}}">Open ticket</a></p>',
+      },
+    },
+    meta: { en: { subject: "Support ticket #{{ticketId}} ({{priority}})" } },
+    // inApp and push build their own short text; email renders the stored
+    // template with the notify data as variables.
+    templates: {
+      inApp: (data) => ({
+        title: `New ticket: ${data["title"]}`,
+        body: (data["description"] as string) || "A ticket was assigned to you.",
+      }),
+      push: (data) => ({
+        title: "New ticket",
+        body: `${data["title"]} (${data["priority"]})`,
+      }),
+    },
+  });
+
+  r.writeHandler(
+    "ticket:create",
+    z.object({
+      title: z.string().min(1),
+      description: z.string().optional(),
+      assigneeId: z.uuid().optional(),
+      priority: z.enum(["low", "normal", "critical"]),
+      status: z.string().default("open"),
+    }),
+    async (event, ctx) => {
+      const created = await ticketExecutor().create(event.payload, event.user, ctx.db);
+      const assigneeId = event.payload.assigneeId;
+      // No assignee, no notification.
+      if (!created.isSuccess || assigneeId === undefined) return created;
+      if (ctx.notify === undefined) {
+        throw new Error("ticket:create needs ctx.notify, mount the delivery feature");
+      }
+      const ticketId = created.data.id;
+      await ctx.notify(TICKET_ASSIGNED, {
+        to: assigneeId,
+        data: {
+          ticketId,
+          title: event.payload.title,
+          description: event.payload.description ?? "",
+          priority: event.payload.priority,
+          url: `https://app.example.com/support/tickets/${ticketId}`,
+        },
+      });
+      return created;
+    },
+    { access: { roles: ["Admin", "Support"] } },
+  );
+});
+```

package/agents/examples/designer-demo.md

@@ -0,0 +1,86 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/designer-demo. Do not edit. -->
+
+# designer-demo
+
+Kumiko sample feature — scaffolded by `bun kumiko create`
+
+## README
+
+# Designer Demo
+
+Designer-driven feature — live schema edits via the UI skeleton.
+
+## What it shows
+
+- Patterns from the three hand-rolled view categories the designer targets
+- A minimal feature surface the designer can open and mutate
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+No dedicated automated tests in this folder yet — use it as a composition sample.
+
+## Source files
+
+### src/feature.ts
+
+```ts
+// kumiko-feature-version: 1
+// Demo-Feature für den Designer-Skeleton (C5).
+// Enthält bewusst Patterns aus den 3 hand-rollten View-Kategorien:
+//   - entity      → Tabelle der Fields
+//   - writeHandler → Header + Code-Blocks (schema + handler)
+//   - nav         → ID/Label/Screen-Card
+// Plus optionalRequires + metric als JSON-Dump-Fallback.
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+defineFeature("designerDemo", (r) => {
+  r.optionalRequires("analytics");
+
+  r.entity("task", {
+    fields: {
+      title: { type: "text", required: true },
+      done: { type: "boolean", default: false },
+      priority: { type: "select", options: ["low", "medium", "high"], default: "medium" },
+    },
+  });
+
+  r.writeHandler({
+    name: "task:create",
+    schema: z.object({ title: z.string(), priority: z.string().optional() }),
+    handler: async (_event, _ctx) => {
+      return { isSuccess: true, data: { id: "x" } };
+    },
+    access: { roles: ["user", "admin"] },
+  });
+
+  r.writeHandler({
+    name: "task:complete",
+    schema: z.object({ id: z.string() }),
+    handler: async (_event, _ctx) => {
+      return { isSuccess: true, data: {} };
+    },
+    access: {
+      openToAll: {
+        reason:
+          "sample handler: any signed-in user may complete a task in this designer-skeleton " +
+          "demo; there is no per-user task ownership",
+      },
+    },
+  });
+
+  r.nav({
+    id: "tasks",
+    label: "Tasks",
+    icon: "list",
+    screen: "designerDemo:screen:task-list",
+  });
+
+  r.metric("tasks_created", { type: "counter" });
+});
+```