@cosmicdrift/kumiko-samples 0.414.0 → 0.416.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +21 -1
  3. package/packages/bundled-features/src/agent-tools/changes.json +6 -0
  4. package/packages/bundled-features/src/agent-tools/tool-catalog.ts +20 -1
  5. package/packages/bundled-features/src/agent-tools/tool-dispatch.ts +19 -5
  6. package/packages/bundled-features/src/auth-email-password/signup-token-store.ts +2 -3
  7. package/packages/bundled-features/src/auth-email-password/web/session.tsx +2 -1
  8. package/packages/bundled-features/src/auth-mfa/changes.json +6 -0
  9. package/packages/bundled-features/src/billing-foundation/changes.json +24 -0
  10. package/packages/bundled-features/src/billing-foundation/checkout-core.ts +11 -0
  11. package/packages/bundled-features/src/billing-foundation/checkout-ledger.ts +8 -0
  12. package/packages/bundled-features/src/billing-foundation/events.ts +7 -5
  13. package/packages/bundled-features/src/billing-foundation/handlers/create-checkout-session.write.ts +2 -0
  14. package/packages/bundled-features/src/billing-foundation/handlers/process-event.write.ts +76 -24
  15. package/packages/bundled-features/src/billing-foundation/handlers/process-payment-event.write.ts +5 -4
  16. package/packages/bundled-features/src/billing-foundation/handlers/start-plan-checkout.write.ts +2 -0
  17. package/packages/bundled-features/src/billing-foundation/webhook-handler.ts +2 -2
  18. package/packages/bundled-features/src/channel-whatsapp/changes.json +30 -0
  19. package/packages/bundled-features/src/channel-whatsapp/constants.ts +1 -0
  20. package/packages/bundled-features/src/channel-whatsapp/events.ts +4 -3
  21. package/packages/bundled-features/src/channel-whatsapp/graph-client.ts +37 -1
  22. package/packages/bundled-features/src/channel-whatsapp/inbound-handlers.ts +23 -2
  23. package/packages/bundled-features/src/channel-whatsapp/webhook-normalize.ts +27 -6
  24. package/packages/bundled-features/src/compliance-profiles/changes.json +5 -0
  25. package/packages/bundled-features/src/compliance-profiles/handlers/set-profile.write.ts +2 -0
  26. package/packages/bundled-features/src/data-retention/feature.ts +1 -0
  27. package/packages/bundled-features/src/delivery/changes.json +6 -0
  28. package/packages/bundled-features/src/delivery/handlers/opted-in-user-ids.query.ts +12 -3
  29. package/packages/bundled-features/src/document-ingest-foundation/changes.json +6 -0
  30. package/packages/bundled-features/src/document-ingest-foundation/feature.ts +1 -0
  31. package/packages/bundled-features/src/document-ingest-foundation/report-ingest-progress.ts +3 -1
  32. package/packages/bundled-features/src/documents/changes.json +6 -0
  33. package/packages/bundled-features/src/documents/feature.ts +10 -5
  34. package/packages/bundled-features/src/form-draft/feature.ts +1 -0
  35. package/packages/bundled-features/src/handbook-knowledge/README.md +64 -0
  36. package/packages/bundled-features/src/handbook-knowledge/changes.json +8 -0
  37. package/packages/bundled-features/src/handbook-knowledge/constants.ts +8 -0
  38. package/packages/bundled-features/src/handbook-knowledge/feature.ts +34 -0
  39. package/packages/bundled-features/src/handbook-knowledge/handbook-index.ts +66 -0
  40. package/packages/bundled-features/src/handbook-knowledge/handlers.ts +77 -0
  41. package/packages/bundled-features/src/handbook-knowledge/index.ts +10 -0
  42. package/packages/bundled-features/src/helpdesk/changes.json +6 -0
  43. package/packages/bundled-features/src/helpdesk/feature.ts +1 -0
  44. package/packages/bundled-features/src/helpdesk/handlers/reply.write.ts +3 -3
  45. package/packages/bundled-features/src/helpdesk/handlers/report.write.ts +3 -2
  46. package/packages/bundled-features/src/helpdesk/handlers/submit.write.ts +3 -2
  47. package/packages/bundled-features/src/helpdesk/legacy-contact-streams.ts +3 -1
  48. package/packages/bundled-features/src/helpdesk/lib.ts +9 -4
  49. package/packages/bundled-features/src/inbound-mail-foundation/account-poll.ts +4 -1
  50. package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
  51. package/packages/bundled-features/src/inbound-mail-foundation/content-refetch.ts +11 -4
  52. package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +18 -9
  53. package/packages/bundled-features/src/inbound-mail-foundation/events.ts +18 -9
  54. package/packages/bundled-features/src/inbound-mail-foundation/handlers/connect-account.write.ts +2 -1
  55. package/packages/bundled-features/src/inbound-mail-foundation/handlers/forget-message.write.ts +6 -0
  56. package/packages/bundled-features/src/inbound-mail-foundation/handlers/ingest-message-schema.ts +18 -5
  57. package/packages/bundled-features/src/inbound-mail-foundation/normalize-inbound-message.ts +22 -8
  58. package/packages/bundled-features/src/inbound-mail-foundation/sanitize-inbound-html.ts +2 -5
  59. package/packages/bundled-features/src/managed-pages/web/page-edit-screen.tsx +11 -5
  60. package/packages/bundled-features/src/shared/changes.json +6 -0
  61. package/packages/bundled-features/src/shared/hmac-signature.ts +4 -2
  62. package/packages/bundled-features/src/shared/index.ts +2 -1
  63. package/packages/bundled-features/src/shared/normalize-email.ts +3 -0
  64. package/packages/bundled-features/src/shared/send-best-effort.ts +16 -6
  65. package/packages/bundled-features/src/signature/README.md +59 -0
  66. package/packages/bundled-features/src/signature/changes.json +15 -0
  67. package/packages/bundled-features/src/signature/entity.ts +192 -0
  68. package/packages/bundled-features/src/signature/feature.ts +125 -0
  69. package/packages/bundled-features/src/signature/files.ts +107 -0
  70. package/packages/bundled-features/src/signature/grant.ts +79 -0
  71. package/packages/bundled-features/src/signature/handlers/anonymous.write.ts +88 -0
  72. package/packages/bundled-features/src/signature/handlers/cancel.write.ts +40 -0
  73. package/packages/bundled-features/src/signature/handlers/issue-link.write.ts +72 -0
  74. package/packages/bundled-features/src/signature/handlers/lifecycle.write.ts +99 -0
  75. package/packages/bundled-features/src/signature/handlers/link-internal.write.ts +261 -0
  76. package/packages/bundled-features/src/signature/handlers/request.write.ts +86 -0
  77. package/packages/bundled-features/src/signature/handlers/revoke-link.write.ts +23 -0
  78. package/packages/bundled-features/src/signature/handlers/sign-in-person.write.ts +69 -0
  79. package/packages/bundled-features/src/signature/i18n.ts +52 -0
  80. package/packages/bundled-features/src/signature/index.ts +33 -0
  81. package/packages/bundled-features/src/signature/lib.ts +125 -0
  82. package/packages/bundled-features/src/signature/options.ts +49 -0
  83. package/packages/bundled-features/src/signature/payloads.ts +71 -0
  84. package/packages/bundled-features/src/signature/png.ts +169 -0
  85. package/packages/bundled-features/src/signature/screens.ts +115 -0
  86. package/packages/bundled-features/src/signature/signature-page.ts +93 -0
  87. package/packages/bundled-features/src/signature/signing.ts +77 -0
  88. package/packages/bundled-features/src/signature/static-sign.ts +98 -0
  89. package/packages/bundled-features/src/signature/sweep.ts +161 -0
  90. package/packages/bundled-features/src/signature/user-data.ts +159 -0
  91. package/packages/bundled-features/src/signature/web/constants.ts +92 -0
  92. package/packages/bundled-features/src/signature/web/index.ts +31 -0
  93. package/packages/bundled-features/src/signature/web/pad.ts +147 -0
  94. package/packages/bundled-features/src/signature/web/signature-pad.tsx +82 -0
  95. package/packages/bundled-features/src/step-dispatcher/changes.json +6 -0
  96. package/packages/bundled-features/src/step-dispatcher/deliver-dispatch-request.ts +5 -2
  97. package/packages/bundled-features/src/step-dispatcher/feature.ts +14 -0
  98. package/packages/bundled-features/src/step-dispatcher/sweep-abandoned.ts +4 -0
  99. package/packages/bundled-features/src/subscription-paddle/backfill-checkout-ledger.ts +2 -0
  100. package/packages/bundled-features/src/subscription-paddle/changes.json +6 -0
  101. package/packages/bundled-features/src/subscription-paddle/redeliver-legacy-checkout.ts +23 -2
  102. package/packages/bundled-features/src/subscription-stripe/changes.json +12 -0
  103. package/packages/bundled-features/src/subscription-stripe/feature.ts +9 -0
  104. package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts +7 -1
  105. package/packages/bundled-features/src/subscription-stripe/verify-webhook.ts +19 -5
  106. package/packages/bundled-features/src/template-resolver/changes.json +12 -0
  107. package/packages/bundled-features/src/template-resolver/seeding.ts +37 -7
  108. package/packages/bundled-features/src/template-resolver/web/web-preview-renderer.tsx +7 -1
  109. package/packages/bundled-features/src/tenant-inactivity/changes.json +6 -0
  110. package/packages/bundled-features/src/tenant-inactivity/check-inactive-tenants.ts +34 -16
  111. package/packages/bundled-features/src/tenant-inactivity/handlers/keep-account.write.ts +6 -0
  112. package/packages/bundled-features/src/tenant-inactivity/state-store.ts +12 -1
  113. package/packages/bundled-features/src/tenant-lifecycle/changes.json +6 -0
  114. package/packages/bundled-features/src/tenant-lifecycle/feature.ts +1 -0
  115. package/packages/bundled-features/src/user/resolve-verified-user-email.ts +3 -3
  116. package/packages/bundled-features/src/user-data-rights/feature.ts +1 -0
  117. package/packages/bundled-features/src/waitlist/handlers/reject.write.ts +1 -1
  118. package/packages/bundled-features/src/waitlist/handlers/submit.write.ts +2 -2
  119. package/packages/bundled-features/src/waitlist/import.ts +2 -1
  120. package/packages/bundled-features/src/waitlist/lib.ts +1 -5
  121. package/packages/bundled-features/src/waitlist/link-on-signup.ts +2 -2
  122. package/packages/bundled-features/src/workflow-runner/changes.json +6 -0
  123. package/packages/bundled-features/src/workflow-runner/handlers/resume-run.write.ts +4 -2
  124. package/samples/apps/admin-console/src/app/shell.tsx +1 -0
  125. package/samples/apps/use-all-bundled/feature-manifest.json +63 -1
  126. package/samples/apps/use-all-bundled/kumiko/migrations/0068_signature.rebuild.json +4 -0
  127. package/samples/apps/use-all-bundled/src/run-config.ts +35 -1
  128. package/samples/recipes/crypto-shredding-hr/README.md +11 -0
  129. package/samples/recipes/crypto-shredding-hr/src/feature.ts +27 -0
  130. package/samples/recipes/embedded/README.md +4 -0
  131. package/samples/recipes/embedded/src/entities/invoice.ts +6 -0
  132. package/samples/recipes/embedded/src/feature.ts +7 -1
  133. package/samples/recipes/embedded/src/handlers/invoice-receive.write.ts +1 -0
  134. package/samples/recipes/embedded/src/screens/invoice-receive.screen.ts +2 -0
  135. package/samples/recipes/handbook-knowledge/README.md +22 -0
  136. package/samples/recipes/handbook-knowledge/package.json +12 -0
  137. package/samples/recipes/handbook-knowledge/src/feature.ts +42 -0
  138. package/samples/recipes/record-detail-layout/src/feature.ts +36 -5
  139. package/samples/recipes/record-detail-layout/src/order-board.ts +10 -2
  140. package/samples/recipes/signature/README.md +21 -0
  141. package/samples/recipes/signature/package.json +13 -0
  142. package/samples/recipes/signature/src/feature.ts +26 -0
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
3
- "featureCount": 94,
3
+ "featureCount": 96,
4
4
  "features": [
5
5
  {
6
6
  "name": "account-security",
@@ -1443,6 +1443,25 @@
1443
1443
  "secrets": [],
1444
1444
  "writeHandlers": []
1445
1445
  },
1446
+ {
1447
+ "name": "handbook-knowledge",
1448
+ "description": "Gives the AI agent the app's handbook as two read-only query tools: `list-pages` returns the catalog of task and screen pages with the questions each answers, `read-page` returns one page in the caller's language with a fallback to the default language and a fixed length cap. The pages come from a build-time JSON (`kumiko handbuch knowledge`), so no table, projection or search index is involved and the handbook text stays public content.",
1449
+ "toggleableDefault": null,
1450
+ "requires": [],
1451
+ "optionalRequires": [],
1452
+ "configReads": [],
1453
+ "exposesApis": [],
1454
+ "usesApis": [],
1455
+ "extensionsUsed": [],
1456
+ "configKeys": [],
1457
+ "secrets": [],
1458
+ "writeHandlers": [],
1459
+ "uiHints": {
1460
+ "displayLabel": "Handbook Knowledge",
1461
+ "category": "ai",
1462
+ "recommended": false
1463
+ }
1464
+ },
1446
1465
  {
1447
1466
  "name": "helpdesk",
1448
1467
  "description": "Helpdesk inbox: an anonymous browser client (GET /helpdesk/client.js) submits questions, contact requests, bug reports and wishes behind a honeypot, a minimum submit time and a single-use proof-of-work challenge; signed-in users file reports from the admin. Every request is stored platform-wide and every SystemAdmin is notified by mail, optionally also in a Telegram chat (option `telegram`, off by default); the notification names only the kind, the app and a link, never name, address, phone, subject or message, because mail and Telegram cannot be shredded. SystemAdmins reply by mail (Reply-To set, attachments, quoting the original) and mark requests done; a website sender gets a fixed acknowledgement, a signed-in reporter a copy and an in-app note. Personal data is crypto-shredding-ready and the EXT_USER_DATA hooks export and erase a user's requests.",
@@ -2658,6 +2677,49 @@
2658
2677
  "recommended": false
2659
2678
  }
2660
2679
  },
2680
+ {
2681
+ "name": "signature",
2682
+ "description": "Signature requests: a signed-in user asks several people to sign one PDF of the tenant. Each signer draws a signature on a display in person or through a link in the URL fragment (14 days, limited opens, revocable, single-use, one answer for every rejection). The last signature moves the request to all-signed; a job renders a signature page through the injected print function, appends it to the unchanged original and completes the request. Events completed, declined and expired report the outcome; signer name, email, image, IP and user agent are personal data.",
2683
+ "toggleableDefault": null,
2684
+ "adoptsBundledLists": true,
2685
+ "requires": [
2686
+ "files",
2687
+ "user-data-rights"
2688
+ ],
2689
+ "optionalRequires": [],
2690
+ "configReads": [],
2691
+ "exposesApis": [],
2692
+ "usesApis": [],
2693
+ "extensionsUsed": [
2694
+ {
2695
+ "extensionName": "userData",
2696
+ "entityName": "signatureSigner"
2697
+ }
2698
+ ],
2699
+ "configKeys": [],
2700
+ "secrets": [],
2701
+ "writeHandlers": [
2702
+ "signature:write:cancel",
2703
+ "signature:write:decline-by-link",
2704
+ "signature:write:expire",
2705
+ "signature:write:finish",
2706
+ "signature:write:issue-link",
2707
+ "signature:write:link-decline",
2708
+ "signature:write:link-open",
2709
+ "signature:write:link-sign",
2710
+ "signature:write:open-by-link",
2711
+ "signature:write:reconcile",
2712
+ "signature:write:request",
2713
+ "signature:write:revoke-link",
2714
+ "signature:write:sign-by-link",
2715
+ "signature:write:sign-in-person"
2716
+ ],
2717
+ "uiHints": {
2718
+ "displayLabel": "Signatures",
2719
+ "category": "data",
2720
+ "recommended": false
2721
+ }
2722
+ },
2661
2723
  {
2662
2724
  "name": "step-dispatcher",
2663
2725
  "description": "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. An `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event enqueues one `step-dispatcher:job:deliver` BullMQ job per dispatch (Redis carries only the stream id and tenant, never the request payload). The job performs the actual HTTP or mail delivery and appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream, so the outcome is recorded in the event log without a separate status table. Transient failures (network error, timeout, 5xx, 408, 429, any mail adapter failure) are retried 3 times with exponential backoff; the outcome is recorded after the final attempt and the payload key is erased only then. A request that still has no outcome after 24 hours (job stalled or lost, or its final attempt could not record one) is closed by the daily `step-dispatcher:job:sweep-abandoned` cron (it pages through all such requests; requests that already have an outcome are not swept) with a generic `dispatch-failed` event and its payload key is erased. Permanent failures (invalid url, blocked host, other 4xx, unavailable auth secret) are recorded immediately. At most 2 deliveries per tenant run at once (`maxPerTenant` with `onLimit: \"defer\"`), so a slow receiver of one tenant does not delay other tenants. Requires a job runner (Redis) and a worker consuming the job's default `worker` lane; without a job runner the projection fails loudly. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across retries and redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.",
@@ -0,0 +1,4 @@
1
+ {
2
+ "version": 1,
3
+ "tables": ["read_signature_requests", "read_signature_signers"]
4
+ }
@@ -55,6 +55,7 @@ import { createFoldersFeature } from "@cosmicdrift/kumiko-bundled-features/folde
55
55
  import { createFoldersUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/folders-user-data";
56
56
  import { createFormDraftFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft";
57
57
  import { createFormDraftUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft-user-data";
58
+ import { createHandbookKnowledgeFeature } from "@cosmicdrift/kumiko-bundled-features/handbook-knowledge";
58
59
  import {
59
60
  createHelpdeskFeature,
60
61
  helpdeskOpenRequestsPanels,
@@ -81,6 +82,7 @@ import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-fea
81
82
  import { createRendererPdfFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
82
83
  import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
83
84
  import { createSeoFeature } from "@cosmicdrift/kumiko-bundled-features/seo";
85
+ import { createSignatureFeature } from "@cosmicdrift/kumiko-bundled-features/signature";
84
86
  import { createStepDispatcherFeature } from "@cosmicdrift/kumiko-bundled-features/step-dispatcher";
85
87
  import { createSubscriptionMollieFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-mollie";
86
88
  import { createSubscriptionPaddleFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-paddle";
@@ -106,7 +108,10 @@ import {
106
108
  import { createDocumentDesignerFeature } from "@cosmicdrift/kumiko-document-designer";
107
109
  import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
108
110
  import { localeDe } from "@cosmicdrift/kumiko-locale-de";
109
- import { createRendererPuppeteerClientFeature } from "@cosmicdrift/kumiko-renderer-puppeteer-client";
111
+ import {
112
+ createRendererPuppeteerClientFeature,
113
+ renderHtmlToPdf,
114
+ } from "@cosmicdrift/kumiko-renderer-puppeteer-client";
110
115
  import { ADMIN_NAV_QN, ADMIN_NAV_WORKSPACES, adminNavFeature } from "./app/admin-nav-feature";
111
116
  import { DEV_TENANT_ID } from "./app/auth-constants";
112
117
  import { CAP_OVERVIEW_CAPS } from "./app/cap-overview-caps";
@@ -374,6 +379,35 @@ export const APP_FEATURES = [
374
379
  // PDF printing for document templates; the print service is reached through
375
380
  // PUPPETEER_SERVICE_URL + PUPPETEER_AUTH_TOKEN and only asked when a PDF is generated.
376
381
  createRendererPuppeteerClientFeature(),
382
+ // signature: needs files; the print function is the real client, asked only when a request completes.
383
+ // deliverLink is smoke-only: boot never sends a link.
384
+ createSignatureFeature({
385
+ retention: { keepFor: "10y" },
386
+ renderHtmlToPdf,
387
+ linkSecret: SMOKE_HMAC_SECRET,
388
+ signaturePageUrl: "https://use-all-bundled.example/sign",
389
+ deliverLink: async () => {
390
+ /* smoke-only */
391
+ },
392
+ }),
393
+ createHandbookKnowledgeFeature({
394
+ pages: {
395
+ defaultLocale: "en",
396
+ locales: {
397
+ en: [
398
+ {
399
+ id: "sign-a-document",
400
+ kind: "process",
401
+ title: "Sign a document",
402
+ questions: ["How do I get a document signed?"],
403
+ screens: [],
404
+ bodyMd: "Create a signature request, add the signers and send each a link.",
405
+ },
406
+ ],
407
+ },
408
+ },
409
+ access: { roles: ["TenantAdmin", "TenantMember", "SystemAdmin"] },
410
+ }),
377
411
 
378
412
  // managed-pages: requires config (auto-bundled). Every host resolves to the
379
413
  // dev tenant so the document-editor e2e can read a saved page back from the
@@ -72,3 +72,14 @@ deletion grace period.
72
72
  blind index immediately (`nullBlindIndexesForSubject`), and every
73
73
  projection rebuild recomputes it from the (now undecryptable) ciphertext
74
74
  to `NULL`.
75
+
76
+ ## Irreversible operations in jobs
77
+
78
+ `forget`, hard deletes, `kms.eraseKey` and writes to `readAsInstruction` fields are gated: they run only from a
79
+ handler marked `agent: { risk: "high" }`. A job or an event consumer has no handler entry, so it must declare
80
+ `irreversibleWithoutEntryHandler` on `r.job` or `r.multiStreamProjection`, or the gate refuses with
81
+ `irreversible_operation_without_entry_handler`. The value names why no entry handler exists:
82
+ `rebuildable-derived-data` (the data is derived and a rebuild recreates it), `high-risk-or-cron-pipeline`
83
+ (a maintenance pipeline that is high-risk by design, like `purge-archived-comments`) or
84
+ `per-dispatch-record-key` (the key belongs to one dispatch record). Hooks and routes never inherit the
85
+ declaration; they dispatch a `risk: "high"` handler instead.
@@ -1,4 +1,6 @@
1
+ import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
1
2
  import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
3
+ import * as z from "zod";
2
4
 
3
5
  export const employeeEntity = createEntity({
4
6
  table: "read_hr_employees",
@@ -20,6 +22,13 @@ export const hrCommentEntity = createEntity({
20
22
  softDelete: true,
21
23
  });
22
24
 
25
+ const hrCommentTable = buildEntityTable("hr-comment", hrCommentEntity);
26
+ const hrCommentExecutor = createEventStoreExecutor(hrCommentTable, hrCommentEntity, {
27
+ entityName: "hr-comment",
28
+ });
29
+
30
+ const purgeArchivedCommentsPayload = z.object({ commentIds: z.array(z.uuid()) });
31
+
23
32
  const hrWrite = { access: { roles: ["Admin"] } } as const;
24
33
  const hrRead = { access: { roles: ["Admin"] } } as const;
25
34
 
@@ -35,4 +44,22 @@ export const hrFeature = defineFeature("hr", (r) => {
35
44
  read: hrRead,
36
45
  verbs: { update: false, delete: false, restore: false, list: false },
37
46
  });
47
+
48
+ // A job runs without a write-handler entry, so the irreversible-operation gate refuses
49
+ // `forget` here unless the job declares why it may. Remove the declaration and the run fails.
50
+ r.job(
51
+ "purge-archived-comments",
52
+ {
53
+ trigger: { maintenance: true },
54
+ runIn: "worker",
55
+ irreversibleWithoutEntryHandler: "high-risk-or-cron-pipeline",
56
+ },
57
+ async (payload, ctx) => {
58
+ const { commentIds } = purgeArchivedCommentsPayload.parse(payload);
59
+ for (const id of commentIds) {
60
+ const result = await hrCommentExecutor.forget({ id }, ctx.systemUser, ctx.db);
61
+ if (!result.isSuccess) throw new Error(`purge of hr-comment ${id} failed`);
62
+ }
63
+ },
64
+ );
38
65
  });
@@ -26,6 +26,10 @@ object and an embedded list rendered by a declarative `entityEdit` screen.
26
26
  entries (`{ label, from }`). The handler wraps its schema with
27
27
  `withFormDerivations(schema, screen)` (`src/handlers/invoice-receive.write.ts`),
28
28
  so totals sent by the client are replaced on the server.
29
+ - **Redirect with search params**: after submit, `invoice-receive` redirects to
30
+ `invoice-list` with `searchParams: { "invoice-list.q": "invoiceNumber" }`, so the list opens
31
+ with the number the handler returns in its search box. The receive handler stores nothing in
32
+ this recipe; the search finds invoices saved through `invoice-edit` with that number.
29
33
 
30
34
  ## When to reach for it
31
35
 
@@ -13,6 +13,12 @@ export const invoiceEntity = createEntity({
13
13
  table: "read_sample_invoices",
14
14
  fields: {
15
15
  customer: createTextField({ personal: { of: "id" }, find: "none", required: true }),
16
+ // Business data, so the list can search it: invoice-receive redirects here by number.
17
+ invoiceNumber: createTextField({
18
+ personal: false,
19
+ reason: "is_business_data",
20
+ searchable: true,
21
+ }),
16
22
  lines: createEmbeddedListField(
17
23
  {
18
24
  product: { type: "reference", entity: "product", required: true },
@@ -58,9 +58,15 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
58
58
  type: "entityEdit",
59
59
  entity: "invoice",
60
60
  layout: {
61
- sections: [{ columns: 1, fields: ["customer", "lines"] }],
61
+ sections: [{ columns: 1, fields: ["invoiceNumber", "customer", "lines"] }],
62
62
  },
63
63
  });
64
64
 
65
+ r.screen({
66
+ id: "invoice-list",
67
+ type: "entityList",
68
+ entity: "invoice",
69
+ columns: ["invoiceNumber", "customer"],
70
+ });
65
71
  r.screen(invoiceReceiveScreen);
66
72
  });
@@ -29,6 +29,7 @@ export const invoiceReceive = defineWriteHandler({
29
29
  handler: async (event) => ({
30
30
  isSuccess: true,
31
31
  data: {
32
+ invoiceNumber: event.payload.invoiceNumber,
32
33
  netTotal: event.payload.netTotal,
33
34
  vatTotal: event.payload.vatTotal,
34
35
  grossTotal: event.payload.grossTotal,
@@ -30,6 +30,8 @@ export const invoiceReceiveScreen: ActionFormScreenDefinition = {
30
30
  id: "invoice-receive",
31
31
  type: "actionForm",
32
32
  handler: "contacts:write:invoice:receive",
33
+ // Lands on the invoice list with its search box filled from the result.
34
+ redirect: { screen: "invoice-list", searchParams: { "invoice-list.q": "invoiceNumber" } },
33
35
  fields: {
34
36
  supplier: createTextField({ required: true, personal: "tenant", find: "none" }),
35
37
  invoiceNumber: createTextField({
@@ -0,0 +1,22 @@
1
+ # Handbook knowledge
2
+
3
+ Serves the app's handbook to the AI assistant. `kumiko handbuch knowledge` exports
4
+ the pages per locale as JSON; the `handbook-knowledge` bundled feature mounts them
5
+ as two query tools, so the assistant can answer how-do-I questions from the real
6
+ handbook text.
7
+
8
+ ## What it shows
9
+
10
+ - **Feature** — `createHandbookKnowledgeFeature({ pages, access, publicPath })`.
11
+ No entity, no migration; `access` decides which roles see the tools.
12
+ - **list-pages** — catalog of id, kind, title and questions in the caller's language.
13
+ - **read-page** — one page body; the language falls back to the handbook's default
14
+ language, long pages are cut with a visible notice, unknown ids are `not_found`.
15
+ - **Test** — `setupTestStack` and HTTP with an `X-Locale` header.
16
+
17
+ ## Files
18
+
19
+ ```
20
+ src/feature.ts fixed handbook JSON and the feature
21
+ src/__tests__/feature.integration.test.ts list-pages, read-page, fallback, not found
22
+ ```
@@ -0,0 +1,12 @@
1
+ {
2
+ "name": "@cosmicdrift/kumiko-sample-handbook-knowledge",
3
+ "description": "The handbook-knowledge bundled feature: a fixed handbook JSON served to the AI assistant as list-pages and read-page query tools.",
4
+ "private": true,
5
+ "dependencies": {
6
+ "@cosmicdrift/kumiko-bundled-features": "workspace:*",
7
+ "@cosmicdrift/kumiko-framework": "workspace:*"
8
+ },
9
+ "devDependencies": {
10
+ "@cosmicdrift/kumiko-testing": "workspace:*"
11
+ }
12
+ }
@@ -0,0 +1,42 @@
1
+ import { createHandbookKnowledgeFeature } from "@cosmicdrift/kumiko-bundled-features/handbook-knowledge";
2
+
3
+ // In an app this object is the output of `kumiko handbuch knowledge <config> --out <file>`.
4
+ const handbook = {
5
+ defaultLocale: "en",
6
+ locales: {
7
+ en: [
8
+ {
9
+ id: "prozess-add-tenant",
10
+ kind: "process" as const,
11
+ title: "Add a tenant",
12
+ questions: ["How do I add a tenant?"],
13
+ screens: [],
14
+ bodyMd: "Open the lease, choose Add tenant and confirm the change.",
15
+ },
16
+ {
17
+ id: "lease-detail",
18
+ kind: "screen" as const,
19
+ title: "Lease",
20
+ questions: [],
21
+ screens: [],
22
+ bodyMd: "The lease screen shows tenants, rent and documents.",
23
+ },
24
+ ],
25
+ de: [
26
+ {
27
+ id: "prozess-add-tenant",
28
+ kind: "process" as const,
29
+ title: "Mieter hinzufügen",
30
+ questions: ["Wie füge ich einen Mieter hinzu?"],
31
+ screens: [],
32
+ bodyMd: "Vertrag öffnen, Mieter hinzufügen wählen und die Änderung bestätigen.",
33
+ },
34
+ ],
35
+ },
36
+ };
37
+
38
+ export const handbookKnowledgeFeature = createHandbookKnowledgeFeature({
39
+ pages: handbook,
40
+ access: { roles: ["User"] },
41
+ publicPath: "/handbuch",
42
+ });
@@ -27,6 +27,10 @@
27
27
  // 10. `focus: true` gives the detail a focused shell; phones get a top bar with the
28
28
  // record title, a back arrow to the list and the page-header overflow menu.
29
29
  //
30
+ // 11. Phone card values: two `showOnNarrowOnly` columns with `narrowInline` stand side by side on one line.
31
+ // The named-filter select sits behind the filter icon on phones (`narrowPlacement: "behind-filter"`),
32
+ // and the "reminder due" empty state fills its description from a query (`emptyState.paramsQuery`).
33
+ //
30
34
  // projectionDetail binds to an explicit query, not an entity: every field name below
31
35
  // (header, metrics, fields) is a column of that query's row.
32
36
 
@@ -37,6 +41,7 @@ import {
37
41
  answerCustomers,
38
42
  answerDeadlines,
39
43
  answerMoney,
44
+ answerNextReminder,
40
45
  answerNowList,
41
46
  answerOrderDetail,
42
47
  answerOrderList,
@@ -76,6 +81,13 @@ export function createOrderDeskFeature(): FeatureDefinition {
76
81
  access: accessRoles,
77
82
  });
78
83
 
84
+ r.queryHandler({
85
+ name: "order:next-reminder",
86
+ schema: noPayloadSchema,
87
+ handler: async () => answerNextReminder(),
88
+ access: accessRoles,
89
+ });
90
+
79
91
  r.queryHandler({
80
92
  name: "order:briefing",
81
93
  schema: noPayloadSchema,
@@ -163,6 +175,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
163
175
  "order-desk.orders.nothing-open": { en: "Nothing to do" },
164
176
  "order-desk.orders.all-done": { en: "All done" },
165
177
  "order-desk.orders.all-done-hint": { en: "No order needs you right now." },
178
+ "order-desk.orders.next-reminder": { en: "Next reminder: {customer}, due {due}." },
166
179
  "order-desk.filter.action-needed": { en: "Needs action" },
167
180
  "order-desk.filter.reminder-due": { en: "Reminder due" },
168
181
  "order-desk.filter.ending-soon": { en: "Ending soon" },
@@ -188,7 +201,8 @@ export function createOrderDeskFeature(): FeatureDefinition {
188
201
  "order-desk.today.inbox-link": { en: "All orders" },
189
202
  "order-desk.today.deadlines": { en: "Deadlines" },
190
203
  "order-desk.today.deadlines-all": { en: "All deadlines" },
191
- "order-desk.col.narrow-meta": { en: "Details" },
204
+ "order-desk.col.narrow-open": { en: "Open amount" },
205
+ "order-desk.col.narrow-status": { en: "Status" },
192
206
  "order-desk.today.customers": { en: "Customers" },
193
207
  "order-desk.today.money": { en: "Money" },
194
208
  "order-desk.today.money-sub": { en: "Across all open orders" },
@@ -232,7 +246,7 @@ export function createOrderDeskFeature(): FeatureDefinition {
232
246
  rowToneField: "tone",
233
247
  columns: [
234
248
  { field: "orderNumber", label: "order-desk.col.order" },
235
- { field: "customerName", label: "order-desk.col.customer" },
249
+ { field: "customerName", label: "order-desk.col.customer", hideOnNarrow: true },
236
250
  {
237
251
  field: "urgencyLabel",
238
252
  label: "order-desk.col.urgency",
@@ -254,7 +268,18 @@ export function createOrderDeskFeature(): FeatureDefinition {
254
268
  minWidth: 240,
255
269
  },
256
270
  { field: "openAmount", label: "order-desk.col.open-amount", hideOnNarrow: true },
257
- { field: "narrowMeta", label: "order-desk.col.narrow-meta", showOnNarrowOnly: true },
271
+ {
272
+ field: "narrowOpen",
273
+ label: "order-desk.col.narrow-open",
274
+ showOnNarrowOnly: true,
275
+ narrowInline: true,
276
+ },
277
+ {
278
+ field: "narrowStatus",
279
+ label: "order-desk.col.narrow-status",
280
+ showOnNarrowOnly: true,
281
+ narrowInline: true,
282
+ },
258
283
  ],
259
284
  defaultSort: { field: "urgency", dir: "desc" },
260
285
  sortOptions: [
@@ -276,12 +301,18 @@ export function createOrderDeskFeature(): FeatureDefinition {
276
301
  label: "order-desk.filter.reminder-due",
277
302
  emptyState: {
278
303
  title: "order-desk.orders.all-done",
279
- description: "order-desk.orders.all-done-hint",
304
+ description: "order-desk.orders.next-reminder",
305
+ paramsQuery: "order-desk:query:order:next-reminder",
280
306
  },
281
307
  },
282
308
  { id: "ending-soon", label: "order-desk.filter.ending-soon" },
283
309
  ],
284
- namedFilterFacet: { display: "select", showCounts: true, label: "order-desk.orders.todo" },
310
+ namedFilterFacet: {
311
+ display: "select",
312
+ showCounts: true,
313
+ label: "order-desk.orders.todo",
314
+ narrowPlacement: "behind-filter",
315
+ },
285
316
  narrowFacets: "pills",
286
317
  table: {
287
318
  frame: "card",
@@ -266,7 +266,8 @@ export type OrderListAnswer =
266
266
  }
267
267
  | {
268
268
  readonly rows: readonly (OrderRow & {
269
- readonly narrowMeta: string;
269
+ readonly narrowOpen: string;
270
+ readonly narrowStatus: string;
270
271
  readonly actionScreen?: string;
271
272
  readonly actionParams?: { readonly entityId: string };
272
273
  })[];
@@ -294,7 +295,8 @@ export function answerOrderList(payload: OrderListPayload): OrderListAnswer {
294
295
  const offset = payload.offset ?? 0;
295
296
  const rows = ordered.slice(offset, offset + (payload.limit ?? DEFAULT_PAGE_SIZE)).map((row) => ({
296
297
  ...row,
297
- narrowMeta: `${euro(row.openAmount)} open · ${row.status}`,
298
+ narrowOpen: `${euro(row.openAmount)} open`,
299
+ narrowStatus: row.status,
298
300
  nextStepShort: row.nextStepDue === "" ? "" : `${row.nextStepDue} · ${euro(row.openAmount)}`,
299
301
  ...(row.nextStep !== "" && {
300
302
  actionScreen: ORDER_DETAIL_SCREEN_QN,
@@ -349,6 +351,12 @@ export function answerNowList() {
349
351
  };
350
352
  }
351
353
 
354
+ // The params of the "reminder due" empty state; null while no order is waiting for a reminder.
355
+ export function answerNextReminder(): { readonly customer: string; readonly due: string } | null {
356
+ const next = ORDER_ROWS.find((row) => row.canRemind);
357
+ return next === undefined ? null : { customer: next.customerName, due: next.nextStepDue };
358
+ }
359
+
352
360
  export function answerBriefing() {
353
361
  const open = actionNeededRows(ORDER_ROWS.length);
354
362
  const [first] = open;
@@ -0,0 +1,21 @@
1
+ # Signature
2
+
3
+ Several people sign one PDF of the tenant, in person on a display or through a link. The last
4
+ signature moves the request to `all-signed`; a job renders a signature page, appends it to the
5
+ unchanged original and completes the request.
6
+
7
+ ## What it shows
8
+
9
+ - **Feature** - `createSignatureFeature({ retention, linkSecret, renderHtmlToPdf, deliverLink, signaturePageUrl })`.
10
+ Needs `files` and `user-data-rights` (exports and erases signer data); the test mounts user-data-rights with its own dependencies.
11
+ - **deliverLink** - `issue-link` hands the signing link to the app (mail) and returns only
12
+ `{ signerId, linkSentAt }`: whoever may issue a link must not be able to sign with it.
13
+ - **renderHtmlToPdf** - injected; in an app it is the client of `@cosmicdrift/kumiko-renderer-puppeteer-client`.
14
+ - **Test** - `setupTestStack` and HTTP: request, issue-link, anonymous sign-by-link, sweep job, completed.
15
+
16
+ ## Files
17
+
18
+ ```
19
+ src/feature.ts the feature with a link outbox and a stand-in printer
20
+ src/__tests__/feature.integration.test.ts request to completed request over HTTP
21
+ ```
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "@cosmicdrift/kumiko-sample-signature",
3
+ "description": "The signature bundled feature: a request for several signers, a signing link that is delivered by the app, and a completed PDF with a signature page.",
4
+ "private": true,
5
+ "dependencies": {
6
+ "@cosmicdrift/kumiko-bundled-features": "workspace:*",
7
+ "@cosmicdrift/kumiko-framework": "workspace:*",
8
+ "pdf-lib": "^1.17.1"
9
+ },
10
+ "devDependencies": {
11
+ "@cosmicdrift/kumiko-testing": "workspace:*"
12
+ }
13
+ }
@@ -0,0 +1,26 @@
1
+ import { createSignatureFeature } from "@cosmicdrift/kumiko-bundled-features/signature";
2
+ import { PDFDocument } from "pdf-lib";
3
+
4
+ // In an app `deliverLink` sends a mail to the signer. The recipe keeps the links in a map so the
5
+ // test can open them: the link is never part of a handler result.
6
+ export const deliveredLinks = new Map<string, string>();
7
+
8
+ // In an app this is `renderHtmlToPdf` from @cosmicdrift/kumiko-renderer-puppeteer-client, which
9
+ // needs the print service; the recipe prints a blank page instead.
10
+ async function printSignaturePage(): Promise<Uint8Array> {
11
+ const pdf = await PDFDocument.create();
12
+ pdf.addPage();
13
+ return pdf.save();
14
+ }
15
+
16
+ export const SIGNATURE_LINK_SECRET = "signature-recipe-link-secret-0123456789";
17
+
18
+ export const signatureFeature = createSignatureFeature({
19
+ retention: { keepFor: "10y" },
20
+ linkSecret: SIGNATURE_LINK_SECRET,
21
+ renderHtmlToPdf: printSignaturePage,
22
+ signaturePageUrl: "https://app.example/sign",
23
+ deliverLink: async (_ctx, { signerId, url }) => {
24
+ deliveredLinks.set(signerId, url);
25
+ },
26
+ });