@cosmicdrift/kumiko-framework 0.363.0 → 0.365.0

package/agents/examples/pdf-audit-export.md

@@ -0,0 +1,306 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/pdf-audit-export. Do not edit. -->
+
+# pdf-audit-export
+
+Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and uploads the bytes before the transaction (uploadFileBytesBeforeTransaction) and stores them as a FileRef (createFileRefFromUploadedBytes).
+
+## README
+
+# PDF Audit Export
+
+A write handler exports tenant data as a PDF and keeps it as a FileRef.
+
+## What it shows
+
+- `renderTablePdf` (`@cosmicdrift/kumiko-bundled-features/renderer-pdf`) draws a table document in pure JavaScript: repeating header, weighted columns, page footer. The handler passes ready-formatted strings.
+- The export is a `beforeTransaction` handler: it reads the rows (reads work in that phase), renders the PDF and calls `uploadFileBytesBeforeTransaction` (`@cosmicdrift/kumiko-framework/files`), which validates the bytes and writes them to the tenant-prefixed storage key. The upload runs before the transaction because storage I/O inside it would hold a pool connection for as long as the upload takes.
+- The handler itself calls `createFileRefFromUploadedBytes(ctx, event.prepared)` and creates the `file_refs` row and the `fileRef.created` event in the transaction. If the transaction does not commit, the phase's `release` deletes the uploaded bytes again (only when no row exists for the storage key). A crash between upload and commit leaves the bytes in storage; nothing sweeps them.
+- The result is a normal FileRef: `GET /api/files/:id` serves it with `Content-Type: application/pdf`, other tenants get 404.
+
+## Source
+
+Feature entry point: `src/feature.ts`. The export reads at most 200 inspections per call.
+
+## 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/pdf-audit-export
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// PDF Audit Export Sample — Integration Test
+//
+// Proves the whole path through real HTTP calls: inspections are written,
+// the export handler renders and stores a PDF, GET /api/files/:id serves it
+// and its text contains exactly the inspections of the requested period.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createFilesFeature,
+  createInMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { extractText, getDocumentProxy } from "unpdf";
+import { inspectionEntity, pdfAuditExportFeature } from "../feature";
+
+let stack: TestStack;
+
+const userA = createTestUser({ id: 1, tenantId: testTenantId(1), roles: ["Admin"] });
+const userB = createTestUser({ id: 2, tenantId: testTenantId(2), roles: ["Admin"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createFilesFeature(), pdfAuditExportFeature],
+    files: { storageProvider: createInMemoryFileProvider() },
+  });
+  await unsafeCreateEntityTable(stack.db, inspectionEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function addInspection(
+  inspectedOn: string,
+  result: "ok" | "defect",
+  inspector: string,
+  assetName = "Kessel 3",
+): Promise<void> {
+  await stack.http.writeOk(
+    "pdf-audit-export:write:inspection:create",
+    { assetName, inspectedOn, result, inspector },
+    userA,
+  );
+}
+
+async function download(user: typeof userA, fileRefId: string): Promise<Response> {
+  const token = await stack.jwt.sign(user);
+  return stack.app.request(`/api/files/${fileRefId}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+}
+
+describe("export-audit", () => {
+  test("stores a PDF FileRef containing only the inspections of the period and asset", async () => {
+    await addInspection("2026-01-10", "ok", "Zeile-vor-Zeitraum");
+    await addInspection("2026-02-05", "defect", "Zeile-im-Zeitraum-Eins");
+    await addInspection("2026-03-20", "ok", "Zeile-im-Zeitraum-Zwei");
+    await addInspection("2026-05-02", "ok", "Zeile-nach-Zeitraum");
+    await addInspection("2026-02-06", "ok", "Zeile-anderer-Asset", "Pumpe 7");
+
+    const { fileRefId } = await stack.http.writeOk<{ fileRefId: string }>(
+      "pdf-audit-export:write:export-audit",
+      { assetName: "Kessel 3", from: "2026-02-01", to: "2026-03-31" },
+      userA,
+    );
+
+    const res = await download(userA, fileRefId);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("application/pdf");
+    const proxy = await getDocumentProxy(new Uint8Array(await res.arrayBuffer()));
+    const { text } = await extractText(proxy, { mergePages: true });
+
+    expect(text).toContain("Prüfprotokoll Kessel 3");
+    expect(text).toContain("05.02.2026");
+    expect(text).toContain("Mangel");
+    expect(text).toContain("Zeile-im-Zeitraum-Eins");
+    expect(text).toContain("20.03.2026");
+    expect(text).toContain("Zeile-im-Zeitraum-Zwei");
+    expect(text).not.toContain("Zeile-vor-Zeitraum");
+    expect(text).not.toContain("Zeile-nach-Zeitraum");
+    expect(text).not.toContain("Zeile-anderer-Asset");
+    expect(text).toContain("Seite 1 von 1");
+  });
+
+  test("a user of another tenant gets 404 for the exported file", async () => {
+    await addInspection("2026-02-05", "ok", "Zeile-Tenant-A");
+    const { fileRefId } = await stack.http.writeOk<{ fileRefId: string }>(
+      "pdf-audit-export:write:export-audit",
+      { assetName: "Kessel 3", from: "2026-02-01", to: "2026-03-31" },
+      userA,
+    );
+
+    expect((await download(userB, fileRefId)).status).toBe(404);
+  });
+
+  test("a period without inspections still yields a PDF with the empty hint", async () => {
+    const { fileRefId } = await stack.http.writeOk<{ fileRefId: string }>(
+      "pdf-audit-export:write:export-audit",
+      { assetName: "Unbekannte Anlage", from: "2026-02-01", to: "2026-03-31" },
+      userA,
+    );
+
+    const res = await download(userA, fileRefId);
+    const proxy = await getDocumentProxy(new Uint8Array(await res.arrayBuffer()));
+    const { text } = await extractText(proxy, { mergePages: true });
+    expect(text).toContain("Keine Prüfungen im Zeitraum");
+  });
+
+  test("a period with more inspections than the export holds is rejected instead of cut off", async () => {
+    const assetName = "Großanlage";
+    for (let day = 0; day < 101; day += 1) {
+      const inspectedOn = new Date(Date.UTC(2025, 0, 1 + day)).toISOString().slice(0, 10);
+      await addInspection(inspectedOn, "ok", `Prüfer-${day}`, assetName);
+    }
+
+    const err = await stack.http.writeErr(
+      "pdf-audit-export:write:export-audit",
+      { assetName, from: "2025-01-01", to: "2025-12-31" },
+      userA,
+    );
+    expect(err.httpStatus).toBe(422);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// PDF Audit Export Sample
+//
+// A write handler turns tenant data into a PDF and keeps it as a regular
+// 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.
+
+import { renderTablePdf } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
+import {
+  createDateField,
+  createEntity,
+  createEntityExecutor,
+  createSelectField,
+  createTextField,
+  defineFeature,
+  defineWriteHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  createFileRefFromUploadedBytes,
+  uploadFileBytesBeforeTransaction,
+} from "@cosmicdrift/kumiko-framework/files";
+import * as z from "zod";
+
+export const INSPECTION_RESULTS = ["ok", "defect"] as const;
+
+export const inspectionEntity = createEntity({
+  table: "read_sample_inspections",
+  fields: {
+    assetName: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    inspectedOn: createDateField({ required: true }),
+    result: createSelectField({ options: INSPECTION_RESULTS, required: true }),
+    inspector: createTextField({ personal: "ref" }),
+  },
+});
+
+const RESULT_LABELS: Readonly<Record<(typeof INSPECTION_RESULTS)[number], string>> = {
+  ok: "In Ordnung",
+  defect: "Mangel",
+};
+
+// The renderer takes ready-formatted strings, so date formatting stays with the caller.
+function formatGermanDate(isoDate: string): string {
+  const [year, month, day] = isoDate.split("-");
+  return `${day}.${month}.${year}`;
+}
+
+function toFileNameSegment(text: string): string {
+  return text.replaceAll(/[^A-Za-z0-9_-]+/g, "-");
+}
+
+// One row above the limit tells "exactly full" from "cut off"; entity lists cap at 200 rows.
+const AUDIT_ROW_LIMIT = 100;
+
+const access = { access: { roles: ["Admin", "User"] } } as const;
+
+export const pdfAuditExportFeature = defineFeature("pdf-audit-export", (r) => {
+  r.entity("inspection", inspectionEntity);
+  const { executor: inspectionExecutor } = createEntityExecutor("inspection", inspectionEntity);
+
+  r.writeHandler(
+    "inspection:create",
+    z.object({
+      assetName: z.string().min(1),
+      inspectedOn: z.iso.date(),
+      result: z.enum(INSPECTION_RESULTS),
+      inspector: z.string().optional(),
+    }),
+    async (event, ctx) => inspectionExecutor.create(event.payload, event.user, ctx.db),
+    access,
+  );
+
+  r.writeHandler(
+    defineWriteHandler({
+      name: "export-audit",
+      schema: z.object({ assetName: z.string().min(1), from: z.iso.date(), to: z.iso.date() }),
+      access: access.access,
+      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,
+        });
+      },
+      handler: async (event, ctx) => {
+        const created = await createFileRefFromUploadedBytes(ctx, event.prepared);
+        if (!created.isSuccess) return created;
+        return { isSuccess: true as const, data: { fileRefId: created.data.id } };
+      },
+    }),
+  );
+});
+```