@cosmicdrift/kumiko-framework 0.405.0 → 0.409.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 (214) hide show
  1. package/agents/api/framework-db.md +1 -0
  2. package/agents/api/framework-engine.md +18 -2
  3. package/agents/api/framework-ui-types.md +15 -0
  4. package/agents/api/renderer-web.md +156 -2
  5. package/agents/api/types.md +113 -71
  6. package/agents/api.md +4 -4
  7. package/agents/boot-rules.md +743 -0
  8. package/agents/examples/contact.md +167 -0
  9. package/agents/examples/delivery-notifications.md +34 -1
  10. package/agents/examples/lane-routing.md +13 -0
  11. package/agents/examples/record-detail-layout.md +13 -2
  12. package/agents/examples/search.md +65 -3
  13. package/agents/examples/secrets-demo.md +96 -2
  14. package/agents/examples/tenant-inactivity.md +138 -0
  15. package/agents/examples.md +2 -0
  16. package/agents/features-index.md +4 -0
  17. package/agents/features.md +24 -1
  18. package/agents/widgets.md +12 -1
  19. package/dist/api/export/export-rows.js +1 -0
  20. package/dist/compliance/index.d.ts +1 -1
  21. package/dist/db/event-store-executor-read-where.js +15 -5
  22. package/dist/db/index.d.ts +1 -1
  23. package/dist/db/index.js +1 -1
  24. package/dist/db/migrate-generator.js +3 -1
  25. package/dist/db/queries/event-consumer.js +11 -7
  26. package/dist/db/queries/event-store.d.ts +2 -1
  27. package/dist/db/queries/event-store.js +25 -6
  28. package/dist/db/queries/rls-boot-catalog.js +3 -1
  29. package/dist/db/queries/session-advisory-lock.d.ts +7 -0
  30. package/dist/db/queries/session-advisory-lock.js +23 -0
  31. package/dist/db/query.js +7 -10
  32. package/dist/db/row-level-security-connection.js +4 -2
  33. package/dist/engine/active-membership.js +1 -0
  34. package/dist/engine/boot-validator/access-declarations.js +57 -33
  35. package/dist/engine/boot-validator/action-wiring.js +8 -6
  36. package/dist/engine/boot-validator/agent-effect-rules.d.ts +12 -0
  37. package/dist/engine/boot-validator/agent-effect-rules.js +12 -0
  38. package/dist/engine/boot-validator/agent-effect.d.ts +2 -0
  39. package/dist/engine/boot-validator/agent-effect.js +20 -0
  40. package/dist/engine/boot-validator/boot-context.js +5 -1
  41. package/dist/engine/boot-validator/boot-environment-rules.d.ts +12 -0
  42. package/dist/engine/boot-validator/boot-environment-rules.js +12 -0
  43. package/dist/engine/boot-validator/boot-phases-app.js +5 -1
  44. package/dist/engine/boot-validator/boot-phases.js +3 -1
  45. package/dist/engine/boot-validator/boot-rules.d.ts +2619 -0
  46. package/dist/engine/boot-validator/boot-rules.js +58 -0
  47. package/dist/engine/boot-validator/bundled-lists-table.js +23 -9
  48. package/dist/engine/boot-validator/config-deps.js +71 -23
  49. package/dist/engine/boot-validator/config-edit-action-rules.d.ts +17 -0
  50. package/dist/engine/boot-validator/config-edit-action-rules.js +17 -0
  51. package/dist/engine/boot-validator/config-key-rules.d.ts +117 -0
  52. package/dist/engine/boot-validator/config-key-rules.js +117 -0
  53. package/dist/engine/boot-validator/custom-screen-write-qns.js +6 -2
  54. package/dist/engine/boot-validator/derived-sql-fields-rules.d.ts +77 -0
  55. package/dist/engine/boot-validator/derived-sql-fields-rules.js +77 -0
  56. package/dist/engine/boot-validator/derived-sql-fields.js +53 -17
  57. package/dist/engine/boot-validator/detail-screens.js +10 -4
  58. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +92 -0
  59. package/dist/engine/boot-validator/entity-declaration-rules.js +92 -0
  60. package/dist/engine/boot-validator/entity-handler-access-rules.d.ts +102 -0
  61. package/dist/engine/boot-validator/entity-handler-access-rules.js +102 -0
  62. package/dist/engine/boot-validator/entity-handler.d.ts +0 -7
  63. package/dist/engine/boot-validator/entity-handler.js +259 -355
  64. package/dist/engine/boot-validator/entity-image-variants.d.ts +2 -0
  65. package/dist/engine/boot-validator/entity-image-variants.js +91 -0
  66. package/dist/engine/boot-validator/entity-list-aggregate-options.js +8 -2
  67. package/dist/engine/boot-validator/entity-reference-embedded-rules.d.ts +117 -0
  68. package/dist/engine/boot-validator/entity-reference-embedded-rules.js +117 -0
  69. package/dist/engine/boot-validator/entity-select-image-rules.d.ts +122 -0
  70. package/dist/engine/boot-validator/entity-select-image-rules.js +122 -0
  71. package/dist/engine/boot-validator/entity-select.d.ts +8 -0
  72. package/dist/engine/boot-validator/entity-select.js +197 -0
  73. package/dist/engine/boot-validator/entity-structure-rules.d.ts +107 -0
  74. package/dist/engine/boot-validator/entity-structure-rules.js +107 -0
  75. package/dist/engine/boot-validator/field-conditions-rules.d.ts +92 -0
  76. package/dist/engine/boot-validator/field-conditions-rules.js +92 -0
  77. package/dist/engine/boot-validator/field-conditions.js +67 -22
  78. package/dist/engine/boot-validator/form-derivations-rules.d.ts +77 -0
  79. package/dist/engine/boot-validator/form-derivations-rules.js +77 -0
  80. package/dist/engine/boot-validator/form-derivations.js +52 -18
  81. package/dist/engine/boot-validator/global-tenancy.js +13 -7
  82. package/dist/engine/boot-validator/handler-declaration-rules.d.ts +72 -0
  83. package/dist/engine/boot-validator/handler-declaration-rules.js +72 -0
  84. package/dist/engine/boot-validator/handler-field-references-rules.d.ts +22 -0
  85. package/dist/engine/boot-validator/handler-field-references-rules.js +22 -0
  86. package/dist/engine/boot-validator/handler-field-references.js +14 -6
  87. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +42 -0
  88. package/dist/engine/boot-validator/list-bulk-actions-rules.js +42 -0
  89. package/dist/engine/boot-validator/list-bulk-actions.js +29 -11
  90. package/dist/engine/boot-validator/list-column-layout.js +22 -10
  91. package/dist/engine/boot-validator/list-query-rules.d.ts +107 -0
  92. package/dist/engine/boot-validator/list-query-rules.js +107 -0
  93. package/dist/engine/boot-validator/list-table-aggregate-options.js +43 -15
  94. package/dist/engine/boot-validator/list-table-aggregate-query.js +7 -3
  95. package/dist/engine/boot-validator/list-table-aggregate-rules.d.ts +82 -0
  96. package/dist/engine/boot-validator/list-table-aggregate-rules.js +82 -0
  97. package/dist/engine/boot-validator/list-table-export-options.js +19 -7
  98. package/dist/engine/boot-validator/list-table-options.js +33 -13
  99. package/dist/engine/boot-validator/list-table-reject-unknown-keys.js +6 -2
  100. package/dist/engine/boot-validator/list-table-rules.d.ts +132 -0
  101. package/dist/engine/boot-validator/list-table-rules.js +132 -0
  102. package/dist/engine/boot-validator/nav-rules.d.ts +42 -0
  103. package/dist/engine/boot-validator/nav-rules.js +42 -0
  104. package/dist/engine/boot-validator/nav.js +29 -15
  105. package/dist/engine/boot-validator/ownership-rules.d.ts +27 -0
  106. package/dist/engine/boot-validator/ownership-rules.js +27 -0
  107. package/dist/engine/boot-validator/ownership.js +28 -12
  108. package/dist/engine/boot-validator/parent-ref.js +32 -20
  109. package/dist/engine/boot-validator/projection-list-screens.js +76 -35
  110. package/dist/engine/boot-validator/query-output-columns.js +9 -3
  111. package/dist/engine/boot-validator/query-refs.js +20 -10
  112. package/dist/engine/boot-validator/query-rules.d.ts +37 -0
  113. package/dist/engine/boot-validator/query-rules.js +37 -0
  114. package/dist/engine/boot-validator/read-gate.js +14 -10
  115. package/dist/engine/boot-validator/record-owned.js +5 -1
  116. package/dist/engine/boot-validator/related-list-table-rules.js +17 -7
  117. package/dist/engine/boot-validator/screens-actions-rules.d.ts +185 -0
  118. package/dist/engine/boot-validator/screens-actions-rules.js +185 -0
  119. package/dist/engine/boot-validator/screens-actions.js +169 -93
  120. package/dist/engine/boot-validator/screens-dashboard-chart-rules.d.ts +87 -0
  121. package/dist/engine/boot-validator/screens-dashboard-chart-rules.js +87 -0
  122. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +227 -0
  123. package/dist/engine/boot-validator/screens-dashboard-rules.js +227 -0
  124. package/dist/engine/boot-validator/screens-dashboard.js +222 -85
  125. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +122 -0
  126. package/dist/engine/boot-validator/screens-forms-layout-rules.js +122 -0
  127. package/dist/engine/boot-validator/screens-forms-rules.d.ts +152 -0
  128. package/dist/engine/boot-validator/screens-forms-rules.js +152 -0
  129. package/dist/engine/boot-validator/screens-forms.js +240 -112
  130. package/dist/engine/boot-validator/screens-kind-config-edit.js +72 -16
  131. package/dist/engine/boot-validator/screens-kind-entity-edit.js +15 -7
  132. package/dist/engine/boot-validator/screens-kind-entity-list.js +57 -32
  133. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +92 -0
  134. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +92 -0
  135. package/dist/engine/boot-validator/screens-kind-projection-detail.js +85 -47
  136. package/dist/engine/boot-validator/screens-kind-rules.d.ts +137 -0
  137. package/dist/engine/boot-validator/screens-kind-rules.js +137 -0
  138. package/dist/engine/boot-validator/screens-kind-secret-mint.js +18 -8
  139. package/dist/engine/boot-validator/screens-kind-shared.js +40 -22
  140. package/dist/engine/boot-validator/screens-lists-rules.d.ts +82 -0
  141. package/dist/engine/boot-validator/screens-lists-rules.js +82 -0
  142. package/dist/engine/boot-validator/screens-lists.js +90 -45
  143. package/dist/engine/boot-validator/screens-rules.d.ts +57 -0
  144. package/dist/engine/boot-validator/screens-rules.js +57 -0
  145. package/dist/engine/boot-validator/screens.js +17 -12
  146. package/dist/engine/boot-validator/transaction-phases.js +12 -4
  147. package/dist/engine/boot-validator/transfer-graph.js +17 -11
  148. package/dist/engine/boot-validator/url-prefill-fields.js +9 -5
  149. package/dist/engine/boot-validator/workspaces.js +11 -5
  150. package/dist/engine/boot-validator/zod-shape.js +6 -2
  151. package/dist/engine/entity-handlers.d.ts +1 -0
  152. package/dist/engine/entity-handlers.js +3 -0
  153. package/dist/engine/entity-list-runtime-options.js +23 -29
  154. package/dist/engine/extensions/tenant-data.d.ts +3 -0
  155. package/dist/engine/extensions/tenant-resource.d.ts +1 -0
  156. package/dist/engine/factories.d.ts +1 -1
  157. package/dist/engine/factories.js +4 -3
  158. package/dist/engine/feature-config-events-jobs.js +7 -0
  159. package/dist/engine/index.d.ts +4 -2
  160. package/dist/engine/index.js +2 -0
  161. package/dist/engine/project-app-schema-for-roles.js +29 -14
  162. package/dist/engine/registry-facade.js +7 -8
  163. package/dist/engine/registry-validate.js +5 -1
  164. package/dist/engine/soft-delete-cleanup.d.ts +1 -0
  165. package/dist/engine/soft-delete-cleanup.js +5 -0
  166. package/dist/engine/steps/describe-workflow-step-error.js +1 -0
  167. package/dist/es-ops/operations-schema.d.ts +1 -1
  168. package/dist/event-store/ensure-dead-letter-table.d.ts +2 -0
  169. package/dist/event-store/ensure-dead-letter-table.js +10 -0
  170. package/dist/event-store/rebuild-dead-letter.js +2 -8
  171. package/dist/event-store/upcaster-dead-letter.js +2 -8
  172. package/dist/files/copy-pending-file-refs-to-tenant.d.ts +28 -0
  173. package/dist/files/copy-pending-file-refs-to-tenant.js +87 -0
  174. package/dist/files/file-routes.d.ts +1 -1
  175. package/dist/files/file-routes.js +21 -6
  176. package/dist/files/index.d.ts +2 -0
  177. package/dist/files/index.js +1 -0
  178. package/dist/i18n/required-surface-keys.js +1 -0
  179. package/dist/jobs/job-runner-helpers.js +1 -0
  180. package/dist/jobs/job-runner-schedulers.d.ts +2 -2
  181. package/dist/jobs/job-runner-schedulers.js +8 -4
  182. package/dist/jobs/job-runner.js +14 -16
  183. package/dist/logging/utils.js +30 -60
  184. package/dist/observability/metrics-handle.js +10 -21
  185. package/dist/pipeline/cascade-handler.js +7 -6
  186. package/dist/pipeline/dispatch-query.js +18 -5
  187. package/dist/pipeline/dispatch-shared.d.ts +1 -0
  188. package/dist/pipeline/dispatch-shared.js +3 -1
  189. package/dist/pipeline/dispatch-write.js +10 -12
  190. package/dist/pipeline/dispatcher.js +12 -14
  191. package/dist/pipeline/event-dispatcher-admin.js +9 -8
  192. package/dist/pipeline/event-dispatcher-delivery.d.ts +19 -1
  193. package/dist/pipeline/event-dispatcher-delivery.js +121 -29
  194. package/dist/pipeline/event-dispatcher.d.ts +5 -1
  195. package/dist/pipeline/event-dispatcher.js +28 -21
  196. package/dist/pipeline/handler-context-phase-denials.js +2 -0
  197. package/dist/pipeline/multi-stream-apply-context.js +12 -20
  198. package/dist/pipeline/system-hooks.d.ts +4 -1
  199. package/dist/pipeline/system-hooks.js +79 -6
  200. package/dist/pipeline/system-identity-switch.js +10 -7
  201. package/dist/search/build-search-snippet.d.ts +9 -0
  202. package/dist/search/build-search-snippet.js +40 -0
  203. package/dist/search/index.d.ts +1 -0
  204. package/dist/search/index.js +1 -0
  205. package/dist/search/meilisearch-adapter.d.ts +32 -0
  206. package/dist/search/meilisearch-adapter.js +153 -56
  207. package/dist/search/meilisearch-chunking.d.ts +21 -0
  208. package/dist/search/meilisearch-chunking.js +96 -0
  209. package/dist/search/reindex-entity.d.ts +1 -0
  210. package/dist/search/reindex-entity.js +97 -52
  211. package/dist/ui-types/index.d.ts +1 -1
  212. package/dist/upgrade-cli.js +3 -14
  213. package/package.json +3 -3
  214. package/src/changes.json +85 -0
@@ -0,0 +1,167 @@
1
+ <!-- Generated by `bun run gen:agent-docs` from samples/recipes/contact. Do not edit. -->
2
+
3
+ # contact
4
+
5
+ Public contact form backend: the contact bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client.
6
+
7
+ ## README
8
+
9
+ # Recipe: contact
10
+
11
+ Public contact form backend. The `contact` bundled feature stores questions, contact
12
+ requests and problem reports from website visitors and notifies every SystemAdmin (mail,
13
+ optional Telegram). The notification names only the kind, the app and a link into the inbox:
14
+ no name, address, phone, subject or message. Telegram is a third party where nothing can be
15
+ shredded or recalled, so it gets the same minimal text. Website senders get a fixed
16
+ acknowledgement that repeats nothing they typed; signed-in admin reports get a copy.
17
+ SystemAdmins reply from the admin. Phone is off and Telegram is not mounted unless the app
18
+ turns them on (`fields.phone`, `telegram: true`).
19
+
20
+ **What the recipe demonstrates:**
21
+ - Mounting `createContactFeature` with its companions (delivery, user-data-rights, files)
22
+ - The anonymous flow: `contact:query:challenge` hands out a proof-of-work challenge,
23
+ `contact:write:submit` verifies it; spam gets the same 200 body and stores nothing
24
+ - The browser client at `GET /contact/client.js` (`window.KumikoContact.load()` / `submit()`)
25
+
26
+ ## Layout
27
+
28
+ ```
29
+ samples/recipes/contact/
30
+ ├── package.json
31
+ ├── README.md
32
+ └── src/
33
+ ├── feature.ts # createContactFeature options
34
+ └── __tests__/
35
+ └── feature.integration.test.ts # challenge query + client route
36
+ ```
37
+
38
+ The behavior (submit, silent drops, replies, Telegram, GDPR export and erasure, retention) is
39
+ covered by the integration tests next to the feature in
40
+ `packages/bundled-features/src/contact/__tests__/`.
41
+
42
+ ## Run tests
43
+
44
+ ```bash
45
+ bun test --config=bunfig.integration.toml samples/recipes/contact
46
+ ```
47
+
48
+ ## Integration into a real app
49
+
50
+ 1. Mount `createContactFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
51
+ `files` with a file provider, and `config`/`secrets` for the Telegram bot token.
52
+ 2. Run `kumiko schema generate` (new tables, plus the delivery `idempotency_key` column).
53
+ 3. SystemAdmins set `contact:config:reply-to` and `contact:config:telegram-chat` in the admin.
54
+ 4. Embed `/contact/client.js` on the website; the form is yours.
55
+
56
+ ## Source files
57
+
58
+ ### src/__tests__/feature.integration.test.ts
59
+
60
+ ```ts
61
+ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
62
+ import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
63
+ import {
64
+ createChannelEmailFeature,
65
+ createInMemoryTransport,
66
+ } from "@cosmicdrift/kumiko-bundled-features/channel-email";
67
+ import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
68
+ import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
69
+ import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
70
+ import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
71
+ import { createFileFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
72
+ import { createFileProviderInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/file-provider-inmemory";
73
+ import { createFilesFeature } from "@cosmicdrift/kumiko-bundled-features/files";
74
+ import { createNotesHistoryFeature } from "@cosmicdrift/kumiko-bundled-features/notes-history";
75
+ import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
76
+ import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
77
+ import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
78
+ import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
79
+ import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
80
+ import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
81
+ import { contactFeature } from "../feature";
82
+
83
+ let stack: TestStack;
84
+
85
+ beforeAll(async () => {
86
+ stack = await setupTestStack({
87
+ features: [
88
+ createConfigFeature(),
89
+ createUserFeature(),
90
+ createTenantFeature(),
91
+ createDeliveryFeature(),
92
+ createChannelEmailFeature({
93
+ transport: createInMemoryTransport(),
94
+ resolveEmail: async () => null,
95
+ }),
96
+ createFilesFeature(),
97
+ createFileFoundationFeature(),
98
+ createFileProviderInMemoryFeature(),
99
+ createDataRetentionFeature(),
100
+ createComplianceProfilesFeature(),
101
+ createAuthFoundationFeature(),
102
+ createSessionsFeature(),
103
+ createUserDataRightsFeature(),
104
+ createNotesHistoryFeature(),
105
+ contactFeature,
106
+ ],
107
+ anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
108
+ });
109
+ });
110
+
111
+ afterAll(async () => {
112
+ await stack.cleanup();
113
+ });
114
+
115
+ describe("contact sample", () => {
116
+ test("an anonymous visitor gets a proof-of-work challenge and the form options", async () => {
117
+ const res = await stack.http.raw("POST", "/api/query", {
118
+ type: "contact:query:challenge",
119
+ payload: {},
120
+ });
121
+ expect(res.status).toBe(200);
122
+ const body = (await res.json()) as { data: { challenge: string; bits: number; phone: string } };
123
+ expect(body.data.bits).toBe(8);
124
+ expect(body.data.phone).toBe("optional");
125
+ expect(body.data.challenge.length).toBeGreaterThan(0);
126
+ });
127
+
128
+ test("the browser client is served as JavaScript", async () => {
129
+ const res = await stack.http.raw("GET", "/contact/client.js");
130
+ expect(res.status).toBe(200);
131
+ expect(res.headers.get("content-type")).toContain("application/javascript");
132
+ expect(await res.text()).toContain("KumikoContact");
133
+ });
134
+ });
135
+ ```
136
+
137
+ ### src/feature.ts
138
+
139
+ ```ts
140
+ // Contact sample
141
+ //
142
+ // A public website form (question, contact request, problem report) that lands with the
143
+ // SystemAdmins: mail, optional Telegram, a copy to the sender. Spam is handled without a
144
+ // captcha: honeypot field, single-use proof-of-work challenge, minimum submit time, per-IP
145
+ // and per-email rate limits. Rejected submits answer 200 with the normal body.
146
+ //
147
+ // The website embeds the anonymous client the feature serves itself:
148
+ // <script src="https://api.example.com/contact/client.js"></script>
149
+ // const { kinds, phone } = await window.KumikoContact.load();
150
+ // const result = await window.KumikoContact.submit({ kind, name, email, message, locale });
151
+ // // result.kind: "sent" | "rate-limited" (retryAfterSeconds) | "failed"
152
+ //
153
+ // Prerequisites the app wires itself:
154
+ // - `anonymousAccess` (defaultTenantId = SYSTEM_TENANT_ID) so the form needs no login
155
+ // - delivery with a mail channel (and channel-telegram for the optional Telegram forward)
156
+ // - a file provider, because the entities carry file fields
157
+ // - `kumiko schema generate` for the new tables
158
+
159
+ import { createContactFeature } from "@cosmicdrift/kumiko-bundled-features/contact";
160
+
161
+ export const contactFeature = createContactFeature({
162
+ appName: "Sample App",
163
+ fields: { phone: "optional" },
164
+ // Lowered only to keep the sample test fast; the default (19 bits, 3 seconds) suits production.
165
+ spamProtection: { proofOfWorkBits: 8, minSubmitSeconds: 0 },
166
+ });
167
+ ```
@@ -162,7 +162,10 @@ beforeAll(async () => {
162
162
  stack = await setupTestStack({
163
163
  features,
164
164
  extraContext: (deps) =>
165
- createDeliveryTestContext(deps, { tenantUserIdsQuery: TenantQueries.resolveUserIds }),
165
+ createDeliveryTestContext(deps, {
166
+ tenantUserIdsQuery: TenantQueries.resolveUserIds,
167
+ idempotencyRedis: deps.redis,
168
+ }),
166
169
  });
167
170
  db = stack.db;
168
171
 
@@ -246,6 +249,33 @@ describe("delivery-notifications sample", () => {
246
249
  expect(logs.every((l) => l["status"] === "sent")).toBe(true);
247
250
  });
248
251
 
252
+ test("the idempotency key tells a SystemAdmin when the assignee read the in-app message", async () => {
253
+ const created = await stack.http.writeOk<{ id: string }>(
254
+ "support:write:ticket:create",
255
+ { title: "Read me", assigneeId: assignee.id, priority: "normal", status: "open" },
256
+ admin,
257
+ );
258
+ const key = `ticket-assigned:${created.id}`;
259
+ const readState = () =>
260
+ stack.http.queryOk<{ rows: { key: string; readAt: unknown }[] }>(
261
+ "channel-in-app:query:read-state-by-keys",
262
+ { keys: [key] },
263
+ TestUsers.systemAdmin,
264
+ );
265
+
266
+ expect((await readState()).rows).toEqual([{ key, readAt: null }]);
267
+
268
+ const [message] = await selectMany(db, inAppMessagesTable, { idempotencyKey: key });
269
+ await stack.http.writeOk(
270
+ "channel-in-app:write:mark-read",
271
+ { id: Number(message?.["id"]) },
272
+ assignee,
273
+ );
274
+ const [row] = (await readState()).rows;
275
+ expect(row?.key).toBe(key);
276
+ expect(row?.readAt).not.toBeNull();
277
+ });
278
+
249
279
  test("a tenant override of the stored mail text replaces the system text", async () => {
250
280
  emailTransport.sent.length = 0;
251
281
  const tenantAdmin = { ...admin, roles: ["TenantAdmin"] };
@@ -438,6 +468,9 @@ export const supportFeature = defineFeature("support", (r) => {
438
468
  const ticketId = created.data.id;
439
469
  await ctx.notify(TICKET_ASSIGNED, {
440
470
  to: assigneeId,
471
+ // Known key per ticket: dedups a replayed handler and lets an admin screen ask
472
+ // channel-in-app:query:read-state-by-keys whether the assignee has seen it.
473
+ idempotencyKey: `ticket-assigned:${ticketId}`,
441
474
  data: {
442
475
  ticketId,
443
476
  title: event.payload.title,
@@ -14,6 +14,7 @@ Pin jobs to deploy lanes (`api` | `worker`) with event-triggered fan-out.
14
14
 
15
15
  - `r.job({ runIn: "worker" })` after an HTTP write
16
16
  - `trigger: { maintenance: true }` for a daily housekeeping job in the app's maintenance window (`KUMIKO_MAINTENANCE_WINDOW`)
17
+ - `wakesSleepingApp: false` on a cron trigger for upkeep that must not wake a sleeping shared app
17
18
  - End-to-end verification via `createAllInOneEntrypoint`
18
19
 
19
20
  ## Source
@@ -145,6 +146,10 @@ describe("lane-routing sample", () => {
145
146
  expect(registry.getJob("orders:job:prune-old-receipts")?.trigger).toEqual({
146
147
  maintenance: true,
147
148
  });
149
+ expect(registry.getJob("orders:job:warm-receipt-cache")?.trigger).toEqual({
150
+ cron: "*/15 * * * *",
151
+ wakesSleepingApp: false,
152
+ });
148
153
  const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
149
154
  const entry = createAllInOneEntrypoint({
150
155
  rowLevelSecurity: "off",
@@ -279,6 +284,14 @@ export function createLaneRoutingFeature(): FeatureDefinition {
279
284
  r.job("prune-old-receipts", { trigger: { maintenance: true }, runIn: "worker" }, async () => {
280
285
  pruneRuns.push(Date.now());
281
286
  });
287
+
288
+ // Optional upkeep: `wakesSleepingApp: false` keeps a sleeping shared app asleep when a run is
289
+ // due; the run happens on the next wake instead.
290
+ r.job(
291
+ "warm-receipt-cache",
292
+ { trigger: { cron: "*/15 * * * *", wakesSleepingApp: false }, runIn: "worker" },
293
+ async () => {},
294
+ );
282
295
  });
283
296
  }
284
297
  ```
@@ -769,7 +769,10 @@ describe("record-detail-layout showcase — registration", () => {
769
769
  if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
770
770
  expect(screen.header).toEqual({
771
771
  title: "customerName",
772
- subtitle: "orderNumber",
772
+ subtitle: [
773
+ "orderNumber",
774
+ { field: "placedAt", format: { format: "date", dateStyle: "medium" } },
775
+ ],
773
776
  status: "status",
774
777
  });
775
778
  expect(screen.metrics?.map((metric) => metric.field)).toEqual([
@@ -948,7 +951,15 @@ export function createOrderDeskFeature(): FeatureDefinition {
948
951
  id: "order-detail",
949
952
  type: "projectionDetail",
950
953
  query: "order-desk:query:order:detail",
951
- header: { title: "customerName", subtitle: "orderNumber", status: "status" },
954
+ header: {
955
+ title: "customerName",
956
+ // Parts are joined by a separator; `format` formats the raw field value.
957
+ subtitle: [
958
+ "orderNumber",
959
+ { field: "placedAt", format: { format: "date", dateStyle: "medium" } },
960
+ ],
961
+ status: "status",
962
+ },
952
963
  metrics: [
953
964
  { field: "totalAmount", label: "order-desk.metric.totalAmount" },
954
965
  { field: "outstandingAmount", label: "order-desk.metric.outstandingAmount" },
@@ -14,6 +14,8 @@ Tenant-scoped full-text search (Meilisearch / in-memory adapter).
14
14
 
15
15
  - `searchable` / `searchWeight` on fields
16
16
  - Handler reads via `ctx.services.searchAdapter`
17
+ - `createLongTextField({ personal: "tenant", find: "fuzzy" })`: a long body is searchable, decrypted for the index (Meilisearch splits it into pieces)
18
+ - Trash list: `softDelete` entity, list with `onlyDeleted: true`, restore via `article:restore`
17
19
 
18
20
  ## Source
19
21
 
@@ -44,7 +46,7 @@ import {
44
46
  type TestStack,
45
47
  unsafeCreateEntityTable,
46
48
  } from "@cosmicdrift/kumiko-testing/stack";
47
- import { productEntity, productFeature } from "../feature";
49
+ import { articleEntity, productEntity, productFeature } from "../feature";
48
50
 
49
51
  let stack: TestStack;
50
52
 
@@ -53,6 +55,7 @@ const admin = TestUsers.admin;
53
55
  beforeAll(async () => {
54
56
  stack = await setupTestStack({ features: [productFeature] });
55
57
  await unsafeCreateEntityTable(stack.db, productEntity);
58
+ await unsafeCreateEntityTable(stack.db, articleEntity, "article");
56
59
  await createEventsTable(stack.db);
57
60
  });
58
61
 
@@ -153,18 +156,60 @@ describe("search indexing", () => {
153
156
  expect(results).toHaveLength(0);
154
157
  });
155
158
  });
159
+
160
+ describe("longText find: fuzzy and the trash list", () => {
161
+ type ArticleList = { rows: Record<string, unknown>[] };
162
+ const listArticles = (payload: Record<string, unknown>) =>
163
+ stack.http.queryOk<ArticleList>("shop:query:article:list", payload, admin);
164
+
165
+ test("a word deep inside a long body is found, and a deleted article moves to the trash and back", async () => {
166
+ const body = `${"filler ".repeat(5_000)}deepneedle`;
167
+ const created = await stack.http.writeOk<{ id: string }>(
168
+ "shop:write:article:create",
169
+ { title: "Handbook", body },
170
+ admin,
171
+ );
172
+ await stack.eventDispatcher?.runOnce();
173
+ expect((await listArticles({ search: "deepneedle" })).rows.map((r) => r["id"])).toEqual([
174
+ created.id,
175
+ ]);
176
+
177
+ await stack.http.writeOk("shop:write:article:delete", { id: created.id }, admin);
178
+ await stack.eventDispatcher?.runOnce();
179
+ expect((await listArticles({ search: "deepneedle" })).rows).toEqual([]);
180
+ expect((await listArticles({})).rows.some((r) => r["id"] === created.id)).toBe(false);
181
+ expect((await listArticles({ onlyDeleted: true })).rows.map((r) => r["id"])).toEqual([
182
+ created.id,
183
+ ]);
184
+
185
+ await stack.http.writeOk("shop:write:article:restore", { id: created.id }, admin);
186
+ await stack.eventDispatcher?.runOnce();
187
+ expect((await listArticles({ onlyDeleted: true })).rows).toEqual([]);
188
+ expect((await listArticles({ search: "deepneedle" })).rows.map((r) => r["id"])).toEqual([
189
+ created.id,
190
+ ]);
191
+ });
192
+ });
156
193
  ```
157
194
 
158
195
  ### src/feature.ts
159
196
 
160
197
  ```ts
161
198
  // Search Sample
162
- // Shows: searchable fields, searchWeight, search via InMemory SearchAdapter.
199
+ // Shows: searchable fields, searchWeight, search via InMemory SearchAdapter, a longText field
200
+ // with find: "fuzzy" (chunked in Meilisearch) and a trash list (onlyDeleted) for restore.
163
201
  // Each handler builds its executor inline so `ctx.services.searchAdapter` is read fresh
164
202
  // per call — tests swap the adapter between runs.
165
203
 
166
204
  import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
167
- import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
205
+ import {
206
+ createEntity,
207
+ createLongTextField,
208
+ createTextField,
209
+ defineEntityQueryHandler,
210
+ defineEntityWriteHandler,
211
+ defineFeature,
212
+ } from "@cosmicdrift/kumiko-framework/engine";
168
213
  import { z } from "zod";
169
214
 
170
215
  export const productEntity = createEntity({
@@ -183,10 +228,27 @@ export const productEntity = createEntity({
183
228
  searchWeight: 10,
184
229
  });
185
230
 
231
+ // A long body is searched like any text field; softDelete gives the trash list and restore.
232
+ export const articleEntity = createEntity({
233
+ table: "read_sample_articles",
234
+ softDelete: true,
235
+ fields: {
236
+ title: createTextField({ personal: false, reason: "is_business_data", required: true }),
237
+ body: createLongTextField({ personal: "tenant", find: "fuzzy" }),
238
+ },
239
+ });
240
+
186
241
  const productTable = buildEntityTable("product", productEntity);
187
242
 
188
243
  export const productFeature = defineFeature("shop", (r) => {
189
244
  r.entity({ name: "product", ...productEntity });
245
+ r.entity({ name: "article", ...articleEntity });
246
+
247
+ const articleAccess = { access: { roles: ["Admin"] } };
248
+ for (const verb of ["create", "delete", "restore"] as const) {
249
+ r.writeHandler(defineEntityWriteHandler(`article:${verb}`, articleEntity, articleAccess));
250
+ }
251
+ r.queryHandler(defineEntityQueryHandler("article:list", articleEntity, articleAccess));
190
252
 
191
253
  r.writeHandler({
192
254
  name: "product:create",
@@ -14,6 +14,7 @@ Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation.
14
14
 
15
15
  - `r.secret` + `ctx.services.secrets.get` (audited reads)
16
16
  - Charge-style handler that never returns the plaintext key
17
+ - A system-scope secret edited on a `configEdit` screen (`secretKeys`) with a handler button row (`actions`)
17
18
 
18
19
  ## Source
19
20
 
@@ -76,7 +77,7 @@ import {
76
77
  unsafePushTables,
77
78
  } from "@cosmicdrift/kumiko-testing/stack";
78
79
  import { z } from "zod";
79
- import { createBillingFeature, STRIPE_API_KEY } from "../feature";
80
+ import { createBillingFeature, STRIPE_API_KEY, WEBHOOK_SIGNING_KEY } from "../feature";
80
81
 
81
82
  // Stable KEK bytes across provider rebuilds — mimics ops flipping env vars
82
83
  // across a redeploy without rotating the actual key material.
@@ -126,7 +127,12 @@ beforeAll(async () => {
126
127
  providerRef = createMutableMasterKeyProvider(initialProvider);
127
128
 
128
129
  stack = await setupTestStack({
129
- features: [createJobsFeature(), createSecretsFeature(), createBillingFeature(), leakyFeature],
130
+ features: [
131
+ createJobsFeature(),
132
+ createSecretsFeature({ roles: ["TenantAdmin", "SystemAdmin"] }),
133
+ createBillingFeature(),
134
+ leakyFeature,
135
+ ],
130
136
  // Typed masterKeyProvider option: lands in AppContext as a typed field,
131
137
  // no Record<string, unknown>-via-extraContext. The rotation job reads
132
138
  // it from ctx.services.masterKeyProvider directly.
@@ -323,6 +329,38 @@ describe("5. KEK rotation via the core job + real BullMQ dispatch", () => {
323
329
  });
324
330
  });
325
331
  });
332
+
333
+ describe("system-scope secret on a configEdit screen", () => {
334
+ const systemAdmin = createTestUser({
335
+ id: "00000000-0000-4000-8000-000000000011",
336
+ tenantId: "00000000-0000-4000-8000-000000000001",
337
+ roles: ["SystemAdmin"],
338
+ });
339
+
340
+ test("the screen carries the secret field and a handler action", () => {
341
+ const screen = stack.registry.getScreen("billing:screen:webhook-settings");
342
+ if (screen?.type !== "configEdit") throw new Error("expected configEdit");
343
+ expect(screen.secretKeys).toEqual({ signingKey: WEBHOOK_SIGNING_KEY.name });
344
+ expect(screen.actions?.map((action) => action.handler)).toEqual([
345
+ "billing:write:webhook-send-test",
346
+ ]);
347
+ });
348
+
349
+ test("the action works on the stored secret and a TenantAdmin may not call it", async () => {
350
+ const missing = await stack.http.writeErr("billing:write:webhook-send-test", {}, systemAdmin);
351
+ expect(missing.httpStatus).toBe(422);
352
+
353
+ await stack.http.writeOk(
354
+ SecretsHandlers.set,
355
+ { key: WEBHOOK_SIGNING_KEY.name, value: "whsec_platform_signing_key" },
356
+ systemAdmin,
357
+ );
358
+ await stack.http.writeOk("billing:write:webhook-send-test", {}, systemAdmin);
359
+
360
+ const denied = await stack.http.writeErr("billing:write:webhook-send-test", {}, tenantAdmin);
361
+ expect(denied.httpStatus).toBe(403);
362
+ });
363
+ });
326
364
  ```
327
365
 
328
366
  ### src/feature.ts
@@ -335,6 +373,8 @@ describe("5. KEK rotation via the core job + real BullMQ dispatch", () => {
335
373
 
336
374
  import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
337
375
  import {
376
+ access,
377
+ createTextField,
338
378
  defineFeature,
339
379
  defineWriteHandler,
340
380
  type FeatureDefinition,
@@ -396,6 +436,26 @@ const chargeWrite = defineWriteHandler({
396
436
  },
397
437
  });
398
438
 
439
+ // Platform-wide secret edited on a configEdit screen. The declaration keeps scope "tenant" (the
440
+ // only declared scope); the screen's scope "system" stores one value for the whole platform under
441
+ // the system tenant, and only a SystemAdmin may write it.
442
+ export let WEBHOOK_SIGNING_KEY: SecretKeyHandle;
443
+
444
+ const webhookSendTestWrite = defineWriteHandler({
445
+ name: "webhook-send-test",
446
+ schema: z.object({}),
447
+ access: { roles: access.systemAdmin },
448
+ handler: async (event, ctx) => {
449
+ const secrets = requireSecretsContext(
450
+ { secrets: ctx.services.secrets, user: ctx.user },
451
+ "billing:write:webhook-send-test",
452
+ );
453
+ const key = await secrets.get(event.user.tenantId, WEBHOOK_SIGNING_KEY);
454
+ if (!key) return failUnprocessable("webhook_key_missing");
455
+ return { isSuccess: true, data: { signed: true } };
456
+ },
457
+ });
458
+
399
459
  export function createBillingFeature(): FeatureDefinition {
400
460
  return defineFeature("billing", (r) => {
401
461
  // Typed declaration of the secret this feature needs. Admin UIs can
@@ -416,7 +476,41 @@ export function createBillingFeature(): FeatureDefinition {
416
476
  },
417
477
  scope: "tenant",
418
478
  });
479
+ WEBHOOK_SIGNING_KEY = r.secret("webhook.signingKey", {
480
+ label: { de: "Webhook-Signaturschlüssel", en: "Webhook signing key" },
481
+ scope: "tenant",
482
+ });
419
483
  r.writeHandler(chargeWrite);
484
+ r.writeHandler(webhookSendTestWrite);
485
+ r.screen({
486
+ id: "webhook-settings",
487
+ type: "configEdit",
488
+ dormant: true,
489
+ scope: "system",
490
+ configKeys: {},
491
+ secretKeys: { signingKey: WEBHOOK_SIGNING_KEY.name },
492
+ fields: {
493
+ signingKey: createTextField({
494
+ writeOnly: true,
495
+ maxLength: 200,
496
+ personal: false,
497
+ reason: "is_business_data",
498
+ }),
499
+ },
500
+ layout: { variant: "settings-list", sections: [{ fields: ["signingKey"] }] },
501
+ // A button row calls a handler with {} on the stored values; it is disabled while the
502
+ // form has unsaved changes.
503
+ actions: [
504
+ {
505
+ id: "send-test",
506
+ handler: "billing:write:webhook-send-test",
507
+ label: "billing.webhook.test.label",
508
+ buttonLabel: "billing.webhook.test.button",
509
+ afterField: "signingKey",
510
+ },
511
+ ],
512
+ access: { roles: access.systemAdmin },
513
+ });
420
514
  });
421
515
  }
422
516
  ```