@cosmicdrift/kumiko-framework 0.406.0 → 0.410.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 (212) hide show
  1. package/AGENTS.md +4 -2
  2. package/agents/api/framework-db.md +1 -0
  3. package/agents/api/framework-engine.md +17 -2
  4. package/agents/api/framework-ui-types.md +15 -0
  5. package/agents/api/renderer-web.md +156 -2
  6. package/agents/api/types.md +113 -71
  7. package/agents/api.md +4 -4
  8. package/agents/boot-rules.md +744 -0
  9. package/agents/examples/anonymous-access.md +23 -1
  10. package/agents/examples/contact.md +173 -0
  11. package/agents/examples/delivery-notifications.md +34 -1
  12. package/agents/examples/record-detail-layout.md +13 -2
  13. package/agents/examples/search.md +65 -3
  14. package/agents/examples/secrets-demo.md +96 -2
  15. package/agents/examples/tenant-inactivity.md +138 -0
  16. package/agents/examples.md +2 -0
  17. package/agents/features-index.md +4 -0
  18. package/agents/features.md +25 -1
  19. package/agents/widgets.md +12 -1
  20. package/dist/api/export/export-rows.js +1 -0
  21. package/dist/compliance/index.d.ts +1 -1
  22. package/dist/db/event-store-executor-read-where.js +15 -5
  23. package/dist/db/index.d.ts +1 -1
  24. package/dist/db/index.js +1 -1
  25. package/dist/db/migrate-generator.js +3 -1
  26. package/dist/db/queries/event-consumer.js +11 -7
  27. package/dist/db/queries/event-store.d.ts +2 -1
  28. package/dist/db/queries/event-store.js +25 -6
  29. package/dist/db/queries/rls-boot-catalog.js +3 -1
  30. package/dist/db/queries/session-advisory-lock.d.ts +7 -0
  31. package/dist/db/queries/session-advisory-lock.js +23 -0
  32. package/dist/db/query.js +7 -10
  33. package/dist/db/row-level-security-connection.js +4 -2
  34. package/dist/engine/access.js +5 -1
  35. package/dist/engine/active-membership.js +1 -0
  36. package/dist/engine/boot-validator/access-declarations.js +76 -33
  37. package/dist/engine/boot-validator/action-wiring.js +8 -6
  38. package/dist/engine/boot-validator/agent-effect-rules.d.ts +12 -0
  39. package/dist/engine/boot-validator/agent-effect-rules.js +12 -0
  40. package/dist/engine/boot-validator/agent-effect.d.ts +2 -0
  41. package/dist/engine/boot-validator/agent-effect.js +20 -0
  42. package/dist/engine/boot-validator/boot-context.js +5 -1
  43. package/dist/engine/boot-validator/boot-environment-rules.d.ts +12 -0
  44. package/dist/engine/boot-validator/boot-environment-rules.js +12 -0
  45. package/dist/engine/boot-validator/boot-phases-app.js +5 -1
  46. package/dist/engine/boot-validator/boot-phases.js +3 -1
  47. package/dist/engine/boot-validator/boot-rules.d.ts +2624 -0
  48. package/dist/engine/boot-validator/boot-rules.js +58 -0
  49. package/dist/engine/boot-validator/bundled-lists-table.js +23 -9
  50. package/dist/engine/boot-validator/config-deps.js +71 -23
  51. package/dist/engine/boot-validator/config-edit-action-rules.d.ts +17 -0
  52. package/dist/engine/boot-validator/config-edit-action-rules.js +17 -0
  53. package/dist/engine/boot-validator/config-key-rules.d.ts +117 -0
  54. package/dist/engine/boot-validator/config-key-rules.js +117 -0
  55. package/dist/engine/boot-validator/custom-screen-write-qns.js +6 -2
  56. package/dist/engine/boot-validator/derived-sql-fields-rules.d.ts +77 -0
  57. package/dist/engine/boot-validator/derived-sql-fields-rules.js +77 -0
  58. package/dist/engine/boot-validator/derived-sql-fields.js +53 -17
  59. package/dist/engine/boot-validator/detail-screens.js +10 -4
  60. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +92 -0
  61. package/dist/engine/boot-validator/entity-declaration-rules.js +92 -0
  62. package/dist/engine/boot-validator/entity-handler-access-rules.d.ts +102 -0
  63. package/dist/engine/boot-validator/entity-handler-access-rules.js +102 -0
  64. package/dist/engine/boot-validator/entity-handler.d.ts +0 -7
  65. package/dist/engine/boot-validator/entity-handler.js +259 -355
  66. package/dist/engine/boot-validator/entity-image-variants.d.ts +2 -0
  67. package/dist/engine/boot-validator/entity-image-variants.js +91 -0
  68. package/dist/engine/boot-validator/entity-list-aggregate-options.js +8 -2
  69. package/dist/engine/boot-validator/entity-reference-embedded-rules.d.ts +117 -0
  70. package/dist/engine/boot-validator/entity-reference-embedded-rules.js +117 -0
  71. package/dist/engine/boot-validator/entity-select-image-rules.d.ts +122 -0
  72. package/dist/engine/boot-validator/entity-select-image-rules.js +122 -0
  73. package/dist/engine/boot-validator/entity-select.d.ts +8 -0
  74. package/dist/engine/boot-validator/entity-select.js +197 -0
  75. package/dist/engine/boot-validator/entity-structure-rules.d.ts +107 -0
  76. package/dist/engine/boot-validator/entity-structure-rules.js +107 -0
  77. package/dist/engine/boot-validator/field-conditions-rules.d.ts +92 -0
  78. package/dist/engine/boot-validator/field-conditions-rules.js +92 -0
  79. package/dist/engine/boot-validator/field-conditions.js +67 -22
  80. package/dist/engine/boot-validator/form-derivations-rules.d.ts +77 -0
  81. package/dist/engine/boot-validator/form-derivations-rules.js +77 -0
  82. package/dist/engine/boot-validator/form-derivations.js +52 -18
  83. package/dist/engine/boot-validator/global-tenancy.js +13 -7
  84. package/dist/engine/boot-validator/handler-declaration-rules.d.ts +77 -0
  85. package/dist/engine/boot-validator/handler-declaration-rules.js +77 -0
  86. package/dist/engine/boot-validator/handler-field-references-rules.d.ts +22 -0
  87. package/dist/engine/boot-validator/handler-field-references-rules.js +22 -0
  88. package/dist/engine/boot-validator/handler-field-references.js +14 -6
  89. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +42 -0
  90. package/dist/engine/boot-validator/list-bulk-actions-rules.js +42 -0
  91. package/dist/engine/boot-validator/list-bulk-actions.js +29 -11
  92. package/dist/engine/boot-validator/list-column-layout.js +22 -10
  93. package/dist/engine/boot-validator/list-query-rules.d.ts +107 -0
  94. package/dist/engine/boot-validator/list-query-rules.js +107 -0
  95. package/dist/engine/boot-validator/list-table-aggregate-options.js +43 -15
  96. package/dist/engine/boot-validator/list-table-aggregate-query.js +7 -3
  97. package/dist/engine/boot-validator/list-table-aggregate-rules.d.ts +82 -0
  98. package/dist/engine/boot-validator/list-table-aggregate-rules.js +82 -0
  99. package/dist/engine/boot-validator/list-table-export-options.js +19 -7
  100. package/dist/engine/boot-validator/list-table-options.js +33 -13
  101. package/dist/engine/boot-validator/list-table-reject-unknown-keys.js +6 -2
  102. package/dist/engine/boot-validator/list-table-rules.d.ts +132 -0
  103. package/dist/engine/boot-validator/list-table-rules.js +132 -0
  104. package/dist/engine/boot-validator/nav-rules.d.ts +42 -0
  105. package/dist/engine/boot-validator/nav-rules.js +42 -0
  106. package/dist/engine/boot-validator/nav.js +33 -17
  107. package/dist/engine/boot-validator/ownership-rules.d.ts +27 -0
  108. package/dist/engine/boot-validator/ownership-rules.js +27 -0
  109. package/dist/engine/boot-validator/ownership.js +28 -12
  110. package/dist/engine/boot-validator/parent-ref.js +32 -20
  111. package/dist/engine/boot-validator/projection-list-screens.js +76 -35
  112. package/dist/engine/boot-validator/query-output-columns.js +9 -3
  113. package/dist/engine/boot-validator/query-refs.js +20 -10
  114. package/dist/engine/boot-validator/query-rules.d.ts +37 -0
  115. package/dist/engine/boot-validator/query-rules.js +37 -0
  116. package/dist/engine/boot-validator/read-gate.js +14 -10
  117. package/dist/engine/boot-validator/record-owned.js +5 -1
  118. package/dist/engine/boot-validator/related-list-table-rules.js +17 -7
  119. package/dist/engine/boot-validator/screens-actions-rules.d.ts +185 -0
  120. package/dist/engine/boot-validator/screens-actions-rules.js +185 -0
  121. package/dist/engine/boot-validator/screens-actions.js +169 -93
  122. package/dist/engine/boot-validator/screens-dashboard-chart-rules.d.ts +87 -0
  123. package/dist/engine/boot-validator/screens-dashboard-chart-rules.js +87 -0
  124. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +227 -0
  125. package/dist/engine/boot-validator/screens-dashboard-rules.js +227 -0
  126. package/dist/engine/boot-validator/screens-dashboard.js +222 -85
  127. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +122 -0
  128. package/dist/engine/boot-validator/screens-forms-layout-rules.js +122 -0
  129. package/dist/engine/boot-validator/screens-forms-rules.d.ts +152 -0
  130. package/dist/engine/boot-validator/screens-forms-rules.js +152 -0
  131. package/dist/engine/boot-validator/screens-forms.js +240 -112
  132. package/dist/engine/boot-validator/screens-kind-config-edit.js +72 -16
  133. package/dist/engine/boot-validator/screens-kind-entity-edit.js +15 -7
  134. package/dist/engine/boot-validator/screens-kind-entity-list.js +57 -32
  135. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +92 -0
  136. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +92 -0
  137. package/dist/engine/boot-validator/screens-kind-projection-detail.js +85 -47
  138. package/dist/engine/boot-validator/screens-kind-rules.d.ts +137 -0
  139. package/dist/engine/boot-validator/screens-kind-rules.js +137 -0
  140. package/dist/engine/boot-validator/screens-kind-secret-mint.js +18 -8
  141. package/dist/engine/boot-validator/screens-kind-shared.js +40 -22
  142. package/dist/engine/boot-validator/screens-lists-rules.d.ts +82 -0
  143. package/dist/engine/boot-validator/screens-lists-rules.js +82 -0
  144. package/dist/engine/boot-validator/screens-lists.js +90 -45
  145. package/dist/engine/boot-validator/screens-rules.d.ts +57 -0
  146. package/dist/engine/boot-validator/screens-rules.js +57 -0
  147. package/dist/engine/boot-validator/screens.js +17 -12
  148. package/dist/engine/boot-validator/transaction-phases.js +12 -4
  149. package/dist/engine/boot-validator/transfer-graph.js +17 -11
  150. package/dist/engine/boot-validator/url-prefill-fields.js +9 -5
  151. package/dist/engine/boot-validator/workspaces.js +11 -5
  152. package/dist/engine/boot-validator/zod-shape.js +6 -2
  153. package/dist/engine/entity-handlers.d.ts +1 -0
  154. package/dist/engine/entity-handlers.js +3 -0
  155. package/dist/engine/entity-list-runtime-options.js +23 -29
  156. package/dist/engine/extensions/tenant-data.d.ts +3 -0
  157. package/dist/engine/factories.d.ts +1 -1
  158. package/dist/engine/factories.js +4 -3
  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.js +7 -12
  181. package/dist/logging/utils.js +30 -60
  182. package/dist/observability/metrics-handle.js +10 -21
  183. package/dist/pipeline/cascade-handler.js +7 -6
  184. package/dist/pipeline/dispatch-query.js +18 -5
  185. package/dist/pipeline/dispatch-shared.d.ts +1 -0
  186. package/dist/pipeline/dispatch-shared.js +3 -1
  187. package/dist/pipeline/dispatch-write.js +10 -12
  188. package/dist/pipeline/dispatcher.js +12 -14
  189. package/dist/pipeline/event-dispatcher-admin.js +9 -8
  190. package/dist/pipeline/event-dispatcher-delivery.d.ts +19 -1
  191. package/dist/pipeline/event-dispatcher-delivery.js +121 -29
  192. package/dist/pipeline/event-dispatcher.d.ts +5 -1
  193. package/dist/pipeline/event-dispatcher.js +28 -21
  194. package/dist/pipeline/handler-context-phase-denials.js +2 -0
  195. package/dist/pipeline/multi-stream-apply-context.js +12 -20
  196. package/dist/pipeline/system-hooks.d.ts +4 -1
  197. package/dist/pipeline/system-hooks.js +79 -6
  198. package/dist/pipeline/system-identity-switch.js +10 -7
  199. package/dist/search/build-search-snippet.d.ts +9 -0
  200. package/dist/search/build-search-snippet.js +40 -0
  201. package/dist/search/index.d.ts +1 -0
  202. package/dist/search/index.js +1 -0
  203. package/dist/search/meilisearch-adapter.d.ts +32 -0
  204. package/dist/search/meilisearch-adapter.js +153 -56
  205. package/dist/search/meilisearch-chunking.d.ts +21 -0
  206. package/dist/search/meilisearch-chunking.js +96 -0
  207. package/dist/search/reindex-entity.d.ts +1 -0
  208. package/dist/search/reindex-entity.js +97 -52
  209. package/dist/ui-types/index.d.ts +1 -1
  210. package/dist/upgrade-cli.js +3 -14
  211. package/package.json +3 -3
  212. package/src/changes.json +79 -0
@@ -14,6 +14,8 @@ Public endpoints without a logged-in user.
14
14
 
15
15
  - `access: "anonymous"` on handlers that must stay public
16
16
  - Rate limits that still bind anonymous callers (`per: "ip+handler"`)
17
+ - `anySignedIn: true` next to `anonymous`, so a visitor who is signed in with a role the
18
+ handler does not list is not turned away from a public form
17
19
 
18
20
  ## Source
19
21
 
@@ -63,6 +65,7 @@ const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
63
65
  // Each value is written by exactly one test; the tenant is fixed, so rows are told apart by value, not by reset.
64
66
  const PRODUCT_NAME = "Espresso Beans (anonymous read)";
65
67
  const GUEST_EMAIL = "guest-checkout@example.com";
68
+ const DRIVER_EMAIL = "driver-checkout@example.com";
66
69
 
67
70
  let stack: TestStack;
68
71
 
@@ -126,6 +129,19 @@ describe("guest checkout: anonymous write lands with placedBy=anonymous", () =>
126
129
  expect(orders[0]?.placedBy).toBe(ANONYMOUS_USER_ID);
127
130
  expect(orders[0]?.email).toBe(GUEST_EMAIL);
128
131
  });
132
+
133
+ test("a signed-in caller with a role the handler does not list still checks out", async () => {
134
+ await stack.http.writeOk(
135
+ "shop:write:guest-order:place",
136
+ { productId: "00000000-0000-4000-8000-000000000098", email: DRIVER_EMAIL },
137
+ TestUsers.driver,
138
+ );
139
+ const orders = (await selectMany(stack.db, guestOrderTable)).filter(
140
+ (order) => order.email === DRIVER_EMAIL,
141
+ );
142
+ expect(orders).toHaveLength(1);
143
+ expect(orders[0]?.placedBy).toBe(TestUsers.driver.id);
144
+ });
129
145
  });
130
146
 
131
147
  describe("regression guards", () => {
@@ -259,7 +275,13 @@ export const anonymousAccessFeature = defineFeature("shop", (r) => {
259
275
  // anonymous root handler — the runtime personal-data gate
260
276
  // (write-origin.ts) requires this explicit opt-in, the same way the
261
277
  // boot validator would reject an openToAll declaration missing it.
262
- access: { roles: [...access.anonymous, "User"], personalData: "public-intake" },
278
+ // The browser sends the session cookie along, so a signed-in visitor arrives with its
279
+ // roles; anySignedIn keeps the checkout open to them whatever those roles are.
280
+ access: {
281
+ roles: [...access.anonymous, "User"],
282
+ personalData: "public-intake",
283
+ anySignedIn: true,
284
+ },
263
285
  rateLimit: { per: "ip+handler", limit: 30, windowSeconds: 60 },
264
286
  });
265
287
 
@@ -0,0 +1,173 @@
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
+ Telegram only when the app turns it on). 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`.
52
+ 2. Run `kumiko schema generate` (new tables, plus the delivery `idempotency_key` column).
53
+ 3. SystemAdmins set `contact:config:reply-to` in the admin.
54
+ 4. Embed `/contact/client.js` on the website; the form is yours. A website served by another
55
+ server can serve the same script from `CONTACT_CLIENT_SOURCE` and type its calls with
56
+ `ContactWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/contact/client`.
57
+
58
+ Telegram is optional and off by default: notifications go by mail to SystemAdmins only. An app
59
+ that turns it on (`telegram: true`) also mounts `channel-telegram` and `secrets` for the bot
60
+ token, and SystemAdmins set `contact:config:telegram-chat`.
61
+
62
+ ## Source files
63
+
64
+ ### src/__tests__/feature.integration.test.ts
65
+
66
+ ```ts
67
+ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
68
+ import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
69
+ import {
70
+ createChannelEmailFeature,
71
+ createInMemoryTransport,
72
+ } from "@cosmicdrift/kumiko-bundled-features/channel-email";
73
+ import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
74
+ import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
75
+ import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
76
+ import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
77
+ import { createFileFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
78
+ import { createFileProviderInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/file-provider-inmemory";
79
+ import { createFilesFeature } from "@cosmicdrift/kumiko-bundled-features/files";
80
+ import { createNotesHistoryFeature } from "@cosmicdrift/kumiko-bundled-features/notes-history";
81
+ import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
82
+ import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
83
+ import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
84
+ import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
85
+ import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
86
+ import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
87
+ import { contactFeature } from "../feature";
88
+
89
+ let stack: TestStack;
90
+
91
+ beforeAll(async () => {
92
+ stack = await setupTestStack({
93
+ features: [
94
+ createConfigFeature(),
95
+ createUserFeature(),
96
+ createTenantFeature(),
97
+ createDeliveryFeature(),
98
+ createChannelEmailFeature({
99
+ transport: createInMemoryTransport(),
100
+ resolveEmail: async () => null,
101
+ }),
102
+ createFilesFeature(),
103
+ createFileFoundationFeature(),
104
+ createFileProviderInMemoryFeature(),
105
+ createDataRetentionFeature(),
106
+ createComplianceProfilesFeature(),
107
+ createAuthFoundationFeature(),
108
+ createSessionsFeature(),
109
+ createUserDataRightsFeature(),
110
+ createNotesHistoryFeature(),
111
+ contactFeature,
112
+ ],
113
+ anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
114
+ });
115
+ });
116
+
117
+ afterAll(async () => {
118
+ await stack.cleanup();
119
+ });
120
+
121
+ describe("contact sample", () => {
122
+ test("an anonymous visitor gets a proof-of-work challenge and the form options", async () => {
123
+ const res = await stack.http.raw("POST", "/api/query", {
124
+ type: "contact:query:challenge",
125
+ payload: {},
126
+ });
127
+ expect(res.status).toBe(200);
128
+ const body = (await res.json()) as { data: { challenge: string; bits: number; phone: string } };
129
+ expect(body.data.bits).toBe(8);
130
+ expect(body.data.phone).toBe("optional");
131
+ expect(body.data.challenge.length).toBeGreaterThan(0);
132
+ });
133
+
134
+ test("the browser client is served as JavaScript", async () => {
135
+ const res = await stack.http.raw("GET", "/contact/client.js");
136
+ expect(res.status).toBe(200);
137
+ expect(res.headers.get("content-type")).toContain("application/javascript");
138
+ expect(await res.text()).toContain("KumikoContact");
139
+ });
140
+ });
141
+ ```
142
+
143
+ ### src/feature.ts
144
+
145
+ ```ts
146
+ // Contact sample
147
+ //
148
+ // A public website form (question, contact request, problem report) that lands with the
149
+ // SystemAdmins: mail, optional Telegram, a copy to the sender. Spam is handled without a
150
+ // captcha: honeypot field, single-use proof-of-work challenge, minimum submit time, per-IP
151
+ // and per-email rate limits. Rejected submits answer 200 with the normal body.
152
+ //
153
+ // The website embeds the anonymous client the feature serves itself:
154
+ // <script src="https://api.example.com/contact/client.js"></script>
155
+ // const { kinds, phone } = await window.KumikoContact.load();
156
+ // const result = await window.KumikoContact.submit({ kind, name, email, message, locale });
157
+ // // result.kind: "sent" | "rate-limited" (retryAfterSeconds) | "failed"
158
+ //
159
+ // Prerequisites the app wires itself:
160
+ // - `anonymousAccess` (defaultTenantId = SYSTEM_TENANT_ID) so the form needs no login
161
+ // - delivery with a mail channel (channel-telegram only with `telegram: true`, off by default)
162
+ // - a file provider, because the entities carry file fields
163
+ // - `kumiko schema generate` for the new tables
164
+
165
+ import { createContactFeature } from "@cosmicdrift/kumiko-bundled-features/contact";
166
+
167
+ export const contactFeature = createContactFeature({
168
+ appName: "Sample App",
169
+ fields: { phone: "optional" },
170
+ // Lowered only to keep the sample test fast; the default (19 bits, 3 seconds) suits production.
171
+ spamProtection: { proofOfWorkBits: 8, minSubmitSeconds: 0 },
172
+ });
173
+ ```
@@ -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,
@@ -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
  ```