@cosmicdrift/kumiko-framework 0.410.0 → 0.412.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 (68) hide show
  1. package/agents/api/framework-db.md +1 -1
  2. package/agents/api/framework-engine.md +50 -1
  3. package/agents/api/framework-errors.md +2 -0
  4. package/agents/api/framework-ui-types.md +10 -0
  5. package/agents/api/renderer-web.md +113 -10
  6. package/agents/api/types.md +30 -0
  7. package/agents/api.md +3 -3
  8. package/agents/boot-rules.md +4 -0
  9. package/agents/examples/api-docs.md +702 -0
  10. package/agents/examples/realtime-sse.md +37 -2
  11. package/agents/examples/record-detail-layout.md +35 -2
  12. package/agents/examples/wizard-form.md +96 -5
  13. package/agents/examples.md +1 -0
  14. package/agents/features.md +6 -0
  15. package/agents/widgets.md +6 -0
  16. package/dist/api/auth-middleware.d.ts +1 -0
  17. package/dist/api/index.d.ts +3 -0
  18. package/dist/api/index.js +3 -0
  19. package/dist/api/pat-auth-reject.d.ts +7 -0
  20. package/dist/api/pat-auth-reject.js +7 -0
  21. package/dist/api/server-middleware.js +2 -1
  22. package/dist/compliance/sub-processors.js +2 -2
  23. package/dist/config/index.d.ts +25 -0
  24. package/dist/config/index.js +28 -1
  25. package/dist/db/event-store-executor-read-paging.d.ts +1 -0
  26. package/dist/db/event-store-executor-read-paging.js +2 -1
  27. package/dist/db/queries/session-advisory-lock.js +3 -0
  28. package/dist/db/read-gate-clause.js +26 -7
  29. package/dist/db/table-builder.d.ts +1 -2
  30. package/dist/engine/boot-validator/boot-rules.d.ts +20 -0
  31. package/dist/engine/boot-validator/list-table-options.js +1 -0
  32. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +15 -0
  33. package/dist/engine/boot-validator/screens-forms-layout-rules.js +15 -0
  34. package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
  35. package/dist/engine/boot-validator/screens-forms.js +60 -3
  36. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
  37. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
  38. package/dist/engine/boot-validator/screens-kind-projection-detail.js +19 -0
  39. package/dist/engine/boot-validator/screens-lists.js +2 -2
  40. package/dist/engine/define-feature.js +3 -0
  41. package/dist/engine/entity-list-runtime-options.js +12 -0
  42. package/dist/engine/factories.d.ts +2 -0
  43. package/dist/engine/feature-builder-state.d.ts +2 -1
  44. package/dist/engine/feature-builder-state.js +1 -0
  45. package/dist/engine/index.d.ts +5 -2
  46. package/dist/engine/index.js +4 -1
  47. package/dist/engine/project-app-schema-for-roles.js +11 -10
  48. package/dist/engine/registry-facade.js +13 -0
  49. package/dist/engine/screen-helpers.d.ts +1 -0
  50. package/dist/engine/screen-helpers.js +1 -1
  51. package/dist/engine/webhook-contracts.d.ts +12 -0
  52. package/dist/engine/webhook-contracts.js +172 -0
  53. package/dist/engine/webhook-events.d.ts +34 -0
  54. package/dist/engine/webhook-events.js +71 -0
  55. package/dist/errors/docs-url.js +2 -19
  56. package/dist/errors/error-codes.d.ts +20 -0
  57. package/dist/errors/error-codes.js +19 -0
  58. package/dist/errors/index.d.ts +2 -0
  59. package/dist/errors/index.js +1 -0
  60. package/dist/i18n/required-surface-keys.d.ts +4 -0
  61. package/dist/i18n/required-surface-keys.js +15 -0
  62. package/dist/pipeline/context-services.d.ts +1 -0
  63. package/dist/pipeline/context-services.js +1 -0
  64. package/dist/pipeline/handler-context-scope.js +5 -1
  65. package/dist/pipeline/user-live-signals.d.ts +5 -0
  66. package/dist/pipeline/user-live-signals.js +20 -0
  67. package/package.json +3 -3
  68. package/src/changes.json +78 -0
@@ -14,6 +14,7 @@ Server-sent events — live updates without F5.
14
14
 
15
15
  - Entity writes that fan out over SSE
16
16
  - Client subscription shape for live lists
17
+ - Presence: `createPresenceFeature({ entities: ["message"] })` answers who else has a message open; the heartbeat is a write, the others get an SSE frame addressed to their user id (no names inside)
17
18
 
18
19
  ## Source
19
20
 
@@ -48,7 +49,7 @@ import {
48
49
  type TestStack,
49
50
  unsafeCreateEntityTable,
50
51
  } from "@cosmicdrift/kumiko-testing/stack";
51
- import { chatFeature, messageEntity } from "../feature";
52
+ import { chatFeature, messageEntity, presenceFeature } from "../feature";
52
53
 
53
54
  let stack: TestStack;
54
55
 
@@ -56,7 +57,7 @@ const admin = TestUsers.admin;
56
57
  const user = createTestUser({ id: 2, roles: ["User"] });
57
58
 
58
59
  beforeAll(async () => {
59
- stack = await setupTestStack({ features: [chatFeature] });
60
+ stack = await setupTestStack({ features: [chatFeature, presenceFeature] });
60
61
  await unsafeCreateEntityTable(stack.db, messageEntity);
61
62
  await createEventsTable(stack.db);
62
63
  });
@@ -151,11 +152,37 @@ describe("SSE broadcast on delete", () => {
151
152
  expect(deleteEvent?.data["id"]).toBe(created.id);
152
153
  });
153
154
  });
155
+
156
+ describe("Presence frames", () => {
157
+ test("a user opening a message they share signals the others on it, by user id", async () => {
158
+ const created = await stack.http.writeOk<SaveContext>(
159
+ "chat:write:message:create",
160
+ { channel: "general", text: "Shared" },
161
+ user,
162
+ );
163
+ await stack.eventDispatcher?.runOnce();
164
+ stack.events.reset();
165
+ const open = { entity: "message", id: created.id, activity: "viewing" };
166
+
167
+ await stack.http.writeOk("presence:write:heartbeat", open, user);
168
+ const seen = await stack.http.writeOk<{ others: Array<{ userId: string }> }>(
169
+ "presence:write:heartbeat",
170
+ open,
171
+ admin,
172
+ );
173
+
174
+ expect(seen.others.map((other) => other.userId)).toEqual([user.id]);
175
+ const frames = stack.events.sse.filter((e) => e.type === "presence:event:changed");
176
+ expect(frames.map((frame) => frame.data["userId"])).toEqual([user.id]);
177
+ expect(frames[0]?.data).not.toHaveProperty("displayName");
178
+ });
179
+ });
154
180
  ```
155
181
 
156
182
  ### src/feature.ts
157
183
 
158
184
  ```ts
185
+ import { createPresenceFeature } from "@cosmicdrift/kumiko-bundled-features/presence";
159
186
  import {
160
187
  createEntity,
161
188
  createTextField,
@@ -183,4 +210,12 @@ export const chatFeature = defineFeature("chat", (r) => {
183
210
  });
184
211
  r.writeHandler(defineEntityDeleteHandler("message", messageEntity, adminWrite));
185
212
  });
213
+
214
+ // Who else has a message open. The heartbeat is an ordinary write; the others learn about a
215
+ // change through an SSE frame addressed to them (`presence:event:changed`, no names inside),
216
+ // then refetch with `usePresence` / `usePresenceList` on the client.
217
+ export const presenceFeature = createPresenceFeature({
218
+ entities: ["message"],
219
+ roles: ["Admin", "User"],
220
+ });
186
221
  ```
@@ -17,6 +17,7 @@ header, a metrics band, and a tabbed layout instead of one long stacked form.
17
17
  rendered from the columns of the screen's own query row
18
18
  - `layout.mode: "tabs"` with two `relatedList` tabs (order items, payments)
19
19
  and one `fields` tab (master data) — each `relatedList` runs its own query
20
+ - a header action with `showOnTabs: ["payments"]`, shown only while that tab is active
20
21
  - boot-validator catching two common author mistakes: a `metrics` entry
21
22
  with an empty `label`, and a `tabs` layout with fewer than two
22
23
  sections
@@ -571,6 +572,24 @@ test.describe("record-detail-layout — tall tab panel scrolls", () => {
571
572
  await expect(end).toBeInViewport();
572
573
  });
573
574
  });
575
+
576
+ test.describe("record-detail-layout — header action per tab", () => {
577
+ const recordPayment = "order-desk.action.recordPayment";
578
+
579
+ test("record-payment shows on the payments tab only", async ({ page }) => {
580
+ await page.goto("/?tab=payments");
581
+ await expect(page.getByTestId("kumiko-screen-projection-detail-tabs")).toBeVisible();
582
+ // The third header action lands in the overflow menu.
583
+ await page.getByRole("button", { name: "More actions" }).last().click();
584
+ await expect(page.getByText(recordPayment)).toBeVisible();
585
+
586
+ await page.goto("/?tab=items");
587
+ await expect(page.getByTestId("render-list-table")).toBeVisible();
588
+ // Only two actions remain, so no overflow menu is rendered.
589
+ await expect(page.getByRole("button", { name: "More actions" })).toHaveCount(0);
590
+ await expect(page.getByText(recordPayment)).toHaveCount(0);
591
+ });
592
+ });
574
593
  ```
575
594
 
576
595
  ### e2e/padding-parity-screenshots.spec.ts
@@ -795,10 +814,14 @@ describe("record-detail-layout showcase — registration", () => {
795
814
  ]);
796
815
  });
797
816
 
798
- test("screen-level actions carry refresh-order and keep download-invoice inline", () => {
817
+ test("screen-level actions carry refresh-order, inline download-invoice and the payments-only record-payment", () => {
799
818
  const screen = registry.getScreen("order-desk:screen:order-detail");
800
819
  if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
801
- expect(screen.actions?.map((a) => a.id)).toEqual(["refresh-order", "download-invoice"]);
820
+ expect(screen.actions?.map((a) => a.id)).toEqual([
821
+ "refresh-order",
822
+ "download-invoice",
823
+ "record-payment",
824
+ ]);
802
825
  expect(screen.inlineActions).toEqual(["download-invoice"]);
803
826
  });
804
827
 
@@ -890,6 +913,8 @@ describe("record-detail-layout showcase — boot-validator catches author mistak
890
913
  // not inside any tab's Card. `inlineActions` keeps download-invoice a visible
891
914
  // button next to it where the page header would otherwise fold it into the menu.
892
915
  //
916
+ // 6. `showOnTabs` limits the record-payment action to the payments tab.
917
+ //
893
918
  // projectionDetail has no entity — it binds to an explicit query instead, so
894
919
  // every field name below (header, metrics, fields) is a column of that
895
920
  // query's row, not an entity field.
@@ -1032,6 +1057,14 @@ export function createOrderDeskFeature(): FeatureDefinition {
1032
1057
  screen: "order-detail",
1033
1058
  icon: "download",
1034
1059
  },
1060
+ {
1061
+ kind: "navigate",
1062
+ id: "record-payment",
1063
+ label: "order-desk.action.recordPayment",
1064
+ screen: "order-detail",
1065
+ icon: "plus",
1066
+ showOnTabs: ["payments"],
1067
+ },
1035
1068
  ],
1036
1069
  inlineActions: ["download-invoice"],
1037
1070
  access: { roles: ["Support", "Admin"] },
@@ -32,6 +32,15 @@ the user left off.
32
32
  mounted alongside this one (both enforced at boot). The actual
33
33
  save/resume/discard wiring happens automatically inside `RenderEdit` —
34
34
  this recipe never calls a form-draft handler from its own code.
35
+ - **Step rail texts** — a section's `subtitle` is the line under its step in
36
+ the rail (opt-in, `description` is never used there); `summaryField`
37
+ replaces it with the entered value once the step is done. `wizard.aside`
38
+ adds the "up next" card, and `finishDescription` the finish card on the
39
+ last step. Extension steps take the same three texts; on an `actionForm`
40
+ `summaryField` and `submitDisabledWhen` may name a field of its `fields`.
41
+ - **Footer options** — `wizard.saveAndCloseOnCreate` offers "Save and close" (also on the last step)
42
+ while creating; `wizard.submitDisabledWhen` disables Finish while a field
43
+ condition holds. It is UI-only: enforce the rule in a validation hook too.
35
44
 
36
45
  ## Feature composition
37
46
 
@@ -881,12 +890,15 @@ test.describe("wizard-form — step navigation, validation, draft resume", () =>
881
890
  const rail = page.getByTestId("render-edit-wizard-steps");
882
891
  const step0 = page.getByTestId("render-edit-wizard-steps-step-0");
883
892
  const step1 = page.getByTestId("render-edit-wizard-steps-step-1");
893
+ const step2 = page.getByTestId("render-edit-wizard-steps-step-2");
884
894
 
885
895
  await expect(rail).toBeVisible();
886
896
  await expect(page.getByTestId("render-edit-wizard-progress")).toHaveCount(0);
887
897
  await expect(step0).toHaveAttribute("aria-current", "step");
888
- await expect(step0).toHaveCSS("height", "36px");
889
- await expect(step1).toHaveCSS("height", "36px");
898
+ // Rows with a subtitle grow past 36px; the subtitle-less Review row pins the exact box.
899
+ await expect(step2).toHaveCSS("height", "36px");
900
+ expect((await step0.boundingBox())?.height).toBeGreaterThanOrEqual(36);
901
+ expect((await step1.boundingBox())?.height).toBeGreaterThanOrEqual(36);
890
902
 
891
903
  await page.getByTestId("field-title").locator("input").fill("Vintage desk lamp");
892
904
  await selectCombobox(page, "category", "furniture");
@@ -894,7 +906,75 @@ test.describe("wizard-form — step navigation, validation, draft resume", () =>
894
906
 
895
907
  await expect(step1).toHaveAttribute("aria-current", "step");
896
908
  await expect(step0).not.toHaveAttribute("aria-current", "step");
897
- await expect(step1).toHaveCSS("height", "36px");
909
+ await expect(step2).toHaveCSS("height", "36px");
910
+ });
911
+
912
+ test("the rail shows the other steps' subtitles and, once a step is done, its summaryField value", async ({
913
+ page,
914
+ }) => {
915
+ await gotoWizard(page);
916
+ await expect(page.getByTestId("render-edit-wizard-steps-subtitle-0")).toHaveCount(0);
917
+ await expect(page.getByTestId("render-edit-wizard-steps-subtitle-1")).toHaveText(
918
+ "Price and condition",
919
+ );
920
+
921
+ await page.getByTestId("field-title").locator("input").fill("Vintage desk lamp");
922
+ await selectCombobox(page, "category", "furniture");
923
+ await page.getByTestId("render-edit-wizard-next").click();
924
+
925
+ await expect(page.getByTestId("render-edit-wizard-steps-subtitle-0")).toHaveText(
926
+ "Vintage desk lamp",
927
+ );
928
+ await expect(page.getByTestId("render-edit-wizard-steps-subtitle-1")).toHaveCount(0);
929
+ });
930
+
931
+ test("the up-next card names the next step and, on the last step, the finish action", async ({
932
+ page,
933
+ }) => {
934
+ await gotoWizard(page);
935
+ const upNext = page.getByTestId("render-edit-wizard-steps-up-next");
936
+ await expect(upNext).toContainText("Pricing");
937
+ await expect(upNext).toContainText("Price and condition");
938
+
939
+ await page.getByTestId("field-title").locator("input").fill("Vintage desk lamp");
940
+ await selectCombobox(page, "category", "furniture");
941
+ await page.getByTestId("render-edit-wizard-next").click();
942
+ await expect(upNext).toContainText("Review");
943
+ await page.getByTestId("field-price").locator("input").fill("42");
944
+ await page.getByTestId("render-edit-wizard-next").click();
945
+
946
+ await expect(upNext).toContainText("Publishes the listing.");
947
+ });
948
+
949
+ test("Save and close is offered while creating and creates the listing", async ({ page }) => {
950
+ await gotoWizard(page);
951
+ await page.getByTestId("field-title").locator("input").fill("Quick save lamp");
952
+ await selectCombobox(page, "category", "furniture");
953
+
954
+ await page.getByTestId("render-edit-wizard-save-close").click();
955
+
956
+ await expect
957
+ .poll(async () => (await createdListings(page)).map((listing) => listing["title"]))
958
+ .toEqual(["Quick save lamp"]);
959
+ });
960
+
961
+ test("submitDisabledWhen disables Finish while the category is vehicles", async ({ page }) => {
962
+ await gotoWizard(page);
963
+ await page.getByTestId("field-title").locator("input").fill("Old bicycle");
964
+ await selectCombobox(page, "category", "vehicles");
965
+ await page.getByTestId("render-edit-wizard-next").click();
966
+ await page.getByTestId("field-price").locator("input").fill("150");
967
+ await page.getByTestId("render-edit-wizard-next").click();
968
+
969
+ await expect(page.getByTestId("render-edit-submit")).toBeDisabled();
970
+
971
+ await page.getByTestId("render-edit-wizard-back").click();
972
+ await page.getByTestId("render-edit-wizard-back").click();
973
+ await selectCombobox(page, "category", "furniture");
974
+ await page.getByTestId("render-edit-wizard-next").click();
975
+ await page.getByTestId("render-edit-wizard-next").click();
976
+
977
+ await expect(page.getByTestId("render-edit-submit")).toBeEnabled();
898
978
  });
899
979
 
900
980
  test("an empty required field blocks Next and shows a field error", async ({ page }) => {
@@ -1256,9 +1336,20 @@ export const listingsFeature = defineFeature("listings", (r) => {
1256
1336
  layout: {
1257
1337
  mode: "wizard",
1258
1338
  draft: true,
1339
+ wizard: {
1340
+ aside: { upNext: true, finishDescription: "Publishes the listing." },
1341
+ saveAndCloseOnCreate: true,
1342
+ // UI-only: the write handler would still accept a vehicle listing.
1343
+ submitDisabledWhen: { field: "category", eq: "vehicles" },
1344
+ },
1259
1345
  sections: [
1260
- { title: "Basics", fields: ["title", "category"] },
1261
- { title: "Pricing", fields: ["price", "condition"] },
1346
+ {
1347
+ title: "Basics",
1348
+ subtitle: "Title and category",
1349
+ summaryField: "title",
1350
+ fields: ["title", "category"],
1351
+ },
1352
+ { title: "Pricing", subtitle: "Price and condition", fields: ["price", "condition"] },
1262
1353
  {
1263
1354
  kind: "extension",
1264
1355
  title: "Review",
@@ -9,6 +9,7 @@
9
9
  | `anonymous-access-multitenant` | Subdomain-based tenant resolution for anonymous-access — SaaS shop / CMS pattern with per-tenant public surface. | `examples/anonymous-access-multitenant.md` |
10
10
  | `apex-landing` | Apex landing page composed from other features — hero copy from template-resolver, prices and caps from tier-engine — rendered to one static HTML string. | `examples/apex-landing.md` |
11
11
  | `apex-surface-auth` | Apex-Surface: öffentliche Account-Flows (Login/Register/PW/Löschen) via createPublicSurface + AuthShell, inkl. anonymem email-verifiziertem Deletion-Flow. | `examples/apex-surface-auth.md` |
12
+ | `api-docs` | API documentation for personal access tokens: recorded examples, kumiko api-docs and a committed golden. | `examples/api-docs.md` |
12
13
  | `api-worker-split` | Split deploy topology: API process (runSingleInstance:false, enqueue-only) + worker process (consumes worker-lane jobs, applies multiStreamProjections, writes results back through the worker dispatcher). | `examples/api-worker-split.md` |
13
14
  | `app-config` | kumiko.config.ts with defineAppConfig: the one feature list, client entries and ports the tooling reads. | `examples/app-config.md` |
14
15
  | `auth-claims` | r.authClaims() — features contribute identity facts into the JWT at login time with auto-prefixed keys. | `examples/auth-claims.md` |
@@ -558,6 +558,12 @@ Category: identity
558
558
 
559
559
  Requires: `user`, `tenant`, `auth-foundation`
560
560
 
561
+ ## presence
562
+
563
+ Who else is on this record right now: a browser sends a heartbeat every 15 seconds for one row of an allow-listed entity and gets the other viewers and editors back, with a live signal to them on a change. State is ephemeral (Redis hash per tenant, entity and row, in-memory without Redis), keyed by the session tenant, expires after ttlSeconds without a heartbeat and holds user ids only; display names are looked up per response. A caller sees presence only for rows visible to them. Mount with createPresenceFeature({ entities: ["task"] }).
564
+
565
+ Category: communication
566
+
561
567
  ## rate-limiting
562
568
 
563
569
  Adds an ops-side `rate-limiting:query:status` query handler for inspecting current bucket state; the actual request throttling is wired automatically by the dispatcher when any handler declares a `rateLimit` option (e.g. `{ per: 'user', limit: 3, windowSeconds: 60 }`) or when you pass `context.rateLimit` to `buildServer`. Loading this feature is optional if you only need L3 per-handler rate limits and have no need for ops introspection.
package/agents/widgets.md CHANGED
@@ -23,6 +23,7 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
23
23
  | `ClampedText` | Clamps content to `lines`; the toggle shows only while the content actually overflows. |
24
24
  | `CollapsibleSection` | Collapsible section using native <details> with React-controlled state; otherwise the open attribute resets to its initial value on every parent re-render. |
25
25
  | `ComparisonTable` | Transposed comparison table: row = metric, column = variant, with the best column optionally highlighted for each metric. |
26
+ | `Composer` | Chat input: a label-less textarea with a text send button inside the field frame, bottom right. |
26
27
  | `DateField` | Date field = Field + Input(kind:"date"), ISO yyyy-mm-dd. |
27
28
  | `DefaultAppShell` | |
28
29
  | `DetailList` | Read-only key-value list for detail views (dimmed label on the left, value on the right). |
@@ -69,6 +70,8 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
69
70
  | `PlainContentEditor` | |
70
71
  | `PlanCard` | |
71
72
  | `PlanGrid` | |
73
+ | `PresenceAvatars` | Small round avatars of the people on a row, with "+n" for the rest; for list rows. |
74
+ | `PresenceNotice` | One quiet line above a record: who else is on it and for how long. |
72
75
  | `PrimitivesProvider` | |
73
76
  | `ProfileMenu` | |
74
77
  | `ProgressBar` | Progress bar, `value` 0..1 (clamped). |
@@ -86,6 +89,7 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
86
89
  | `ResultTable` | Static, prop-driven result table for calculated rows (tranches, scenarios). |
87
90
  | `ScreenWidthProvider` | |
88
91
  | `SectionCard` | Section with a title and optional action slot (range switcher, filter) — replaces repeated `<section className={CARD}>…<h2>` blocks in custom screens. |
92
+ | `SectionNavLayout` | Content column plus an "On this page" navigation in a right column (from xl), for custom screens. |
89
93
  | `SelectField` | Select field = Field + Input(kind:"select"). |
90
94
  | `SenderFrame` | Sand frame with one white sheet inside, for content that mimics a letter or mail. |
91
95
  | `SenderSheet` | The white sheet alone, for a frame that holds several sheets (PDF pages, thumbnails). |
@@ -134,6 +138,8 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
134
138
  | `useLiveEvents` | Hook for a useQuery-like consumer. |
135
139
  | `useLocale` | Provides the current LocaleResolver and automatically subscribes to locale changes — the calling component re-renders when the language changes. |
136
140
  | `useNav` | |
141
+ | `usePresence` | Announces the user on one record: a heartbeat right away and every 15 s, a leave when the record closes. |
142
+ | `usePresenceList` | Who else is on each of the given rows, for badges in a list. |
137
143
  | `usePrimitives` | |
138
144
  | `useQuery` | |
139
145
  | `useResolvers` | |
@@ -33,6 +33,7 @@ export type AnonymousAccessResolved = AnonymousAccessConfig & {
33
33
  readonly tenantExists?: TenantExists;
34
34
  readonly resolverTrust?: "authoritative" | "fallback-only";
35
35
  };
36
+ export type MiddlewareRejectCode = "missing_token" | "invalid_token" | "ambiguous_auth" | "session_invalid" | "tenant_required" | "tenant_not_found" | "tenant_mismatch" | "invalid_tenant_format" | "tenant_unavailable";
36
37
  export declare function identifyOptionalSession(c: Context, jwt: JwtHelper): Promise<void>;
37
38
  export declare function authMiddleware(jwt: JwtHelper, options?: AuthMiddlewareOptions): (c: Context, next: Next) => Promise<Response | undefined>;
38
39
  export declare function getUser(c: Context): SessionUser;
@@ -17,6 +17,8 @@ export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongE
17
17
  export type { JwtHelper } from "./jwt.ts";
18
18
  export { loadJwtSecretOrKeyring } from "./jwt.ts";
19
19
  export { publicOriginOf } from "./origin-middleware.ts";
20
+ export { PAT_RATE_LIMITED_CODE, patAuthRejectHttpStatus } from "./pat-auth-reject.ts";
21
+ export { patAllows, qnMatches } from "./pat-scope.ts";
20
22
  export type { PostAuthLandingArgs, PostAuthLandingResolver, } from "./post-auth-landing.ts";
21
23
  export type { RedisSseBroker } from "./redis-sse-broker.ts";
22
24
  export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.ts";
@@ -24,6 +26,7 @@ export { readonlyRequestContext as requestContext } from "./request-context-scop
24
26
  export { buildRequestContextDataFromRequest } from "./request-id-middleware.ts";
25
27
  export type { MetricsRouteOptions } from "./route-registrars.ts";
26
28
  export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.ts";
29
+ export { MAX_PAYLOAD_DEPTH } from "./routes.ts";
27
30
  export type { ServerOptions } from "./server.ts";
28
31
  export { buildServer } from "./server.ts";
29
32
  export { resolveBaseDbAndSearchAdapter } from "./server-event-dispatcher.ts";
package/dist/api/index.js CHANGED
@@ -10,10 +10,13 @@ export { ExtraRouteRejection, signatureRoute } from "./extra-route.js";
10
10
  export { cacheControlHeader, cachedResponse, computeRevisionEtag, computeStrongEtag, computeWeakEtag, etagMatches, } from "./http-cache.js";
11
11
  export { loadJwtSecretOrKeyring } from "./jwt.js";
12
12
  export { publicOriginOf } from "./origin-middleware.js";
13
+ export { PAT_RATE_LIMITED_CODE, patAuthRejectHttpStatus } from "./pat-auth-reject.js";
14
+ export { patAllows, qnMatches } from "./pat-scope.js";
13
15
  export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
14
16
  export { readonlyRequestContext as requestContext } from "./request-context-scopes.js";
15
17
  export { buildRequestContextDataFromRequest } from "./request-id-middleware.js";
16
18
  export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
19
+ export { MAX_PAYLOAD_DEPTH } from "./routes.js";
17
20
  export { buildServer } from "./server.js";
18
21
  export { resolveBaseDbAndSearchAdapter } from "./server-event-dispatcher.js";
19
22
  export { makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, } from "./server-extra-routes.js";
@@ -0,0 +1,7 @@
1
+ export declare const PAT_RATE_LIMITED_CODE = "pat_rate_limited";
2
+ export declare const patAuthRejectHttpStatus: {
3
+ readonly missing_token: 401;
4
+ readonly invalid_token: 401;
5
+ readonly ambiguous_auth: 400;
6
+ readonly pat_rate_limited: 429;
7
+ };
@@ -0,0 +1,7 @@
1
+ export const PAT_RATE_LIMITED_CODE = "pat_rate_limited";
2
+ export const patAuthRejectHttpStatus = {
3
+ missing_token: 401,
4
+ invalid_token: 401,
5
+ ambiguous_auth: 400,
6
+ [PAT_RATE_LIMITED_CODE]: 429,
7
+ };
@@ -6,6 +6,7 @@ import { assertSessionCallbacksPaired } from "./auth-routes.js";
6
6
  import { csrfMiddleware } from "./csrf-middleware.js";
7
7
  import { observabilityMiddleware } from "./observability-middleware.js";
8
8
  import { assertOriginGuardConfig, normalizeOrigin, resolveOriginGuard, } from "./origin-middleware.js";
9
+ import { PAT_RATE_LIMITED_CODE } from "./pat-auth-reject.js";
9
10
  import { patRouteGuard } from "./pat-route-guard.js";
10
11
  import { piiCiphertextResponseGuard } from "./pii-leak-guard.js";
11
12
  import { requestIdMiddleware } from "./request-id-middleware.js";
@@ -189,7 +190,7 @@ function buildPatRateLimitGuard(patRateLimiter) {
189
190
  if (pat && !(await patRateLimiter.check(pat.tokenId))) {
190
191
  return c.json({
191
192
  error: {
192
- code: "pat_rate_limited",
193
+ code: PAT_RATE_LIMITED_CODE,
193
194
  httpStatus: 429,
194
195
  message: "personal access token rate limit exceeded",
195
196
  i18nKey: "auth.errors.patRateLimited",
@@ -87,9 +87,9 @@ export const KUMIKO_SUB_PROCESSORS = [
87
87
  purpose: "Platform key custody (Key Manager) and Transactional Email Delivery",
88
88
  region: "EU (France)",
89
89
  dpa: "https://www.scaleway.com/en/contracts/",
90
- addedAt: "2026-09-18",
90
+ addedAt: "2026-11-01",
91
91
  appliesTo: ["all-tiers"],
92
- status: "planned",
92
+ status: "active",
93
93
  },
94
94
  ];
95
95
  /**
@@ -21,6 +21,28 @@ export type AppPorts = {
21
21
  };
22
22
  /** The boot-validator options an app owns; `env` and the cipher are injected by the runners. */
23
23
  export type AppValidateBootOptions = Pick<ValidateBootOptions, "navAllowlist" | "navAllowlistExempt" | "requiredLocales" | "requireFieldValueTranslations" | "warnOnUniqueAccessRoles">;
24
+ /** Settings of `kumiko api-docs`, the generator for the HTTP API developer docs. */
25
+ export type AppApiDocsConfig = {
26
+ /** Locales of the generated pages; default en. */
27
+ readonly locales?: readonly string[];
28
+ readonly outDir?: string;
29
+ /** Host that the curl examples and the OpenAPI `servers` entry point to. */
30
+ readonly baseUrl?: string;
31
+ readonly appName?: string;
32
+ /** One paragraph per locale, appended to the tokens page (plan or tier limits). */
33
+ readonly planNote?: Readonly<Record<string, string>>;
34
+ /** One text per locale for the delivery section of the events page: signature, timeouts, retries. Required for every requested locale once an event is public. */
35
+ readonly webhookDelivery?: Readonly<Record<string, string>>;
36
+ /** Writes triggered by screens that are deliberately not reachable with an API token. `pattern` is a QN or a glob ending in `*`. */
37
+ readonly uiOnlyWrites?: readonly {
38
+ readonly pattern: string;
39
+ readonly reason: string;
40
+ }[];
41
+ /** Paragraph overrides per locale and text key; the page structure stays fixed. */
42
+ readonly texts?: Readonly<Record<string, Readonly<Record<string, string>>>>;
43
+ /** Directory of recorded request/response examples; default `api-examples`. */
44
+ readonly examplesDir?: string;
45
+ };
24
46
  export type AppConfig = {
25
47
  /** Features mounted in every environment: dev, tests, prod. */
26
48
  readonly features: readonly FeatureDefinition[];
@@ -38,6 +60,7 @@ export type AppConfig = {
38
60
  readonly bundledLists?: BundledListsOptions;
39
61
  /** "on" enforces tenant isolation in Postgres via row level security; schema tooling and every runner read this one value. Default "on". */
40
62
  readonly rowLevelSecurity?: RowLevelSecurityMode;
63
+ readonly apiDocs?: AppApiDocsConfig;
41
64
  };
42
65
  export declare const APP_CONFIG_FILE = "kumiko.config.ts";
43
66
  declare const INFRA_PORT_NAMES: readonly ["postgres", "redis", "meilisearch", "s3"];
@@ -46,6 +69,8 @@ export type AppPortRole = "dev" | "e2e" | (typeof INFRA_PORT_NAMES)[number];
46
69
  export declare function listAppPorts(ports: AppPorts): readonly AppPortEntry[];
47
70
  /** Problems with the declared ports: out of range or claimed twice by this app. */
48
71
  export declare function findAppPortProblems(ports: AppPorts): readonly string[];
72
+ /** Problems with the declared `apiDocs` block: empty or duplicate locales, a `uiOnlyWrites` entry without reason. */
73
+ export declare function findApiDocsConfigProblems(apiDocs: AppApiDocsConfig): readonly string[];
49
74
  export declare function defineAppConfig(config: AppConfig): AppConfig;
50
75
  /**
51
76
  * Raw `features` plus `prodFeatures`, without the bundled foundation: the runners compose it,
@@ -46,8 +46,35 @@ export function findAppPortProblems(ports) {
46
46
  // Entries end up in the server's bundle list and in generated files, so only
47
47
  // plain relative paths inside the app are accepted.
48
48
  const CLIENT_ENTRY_RE = /^(?!\/)(?!.*\.\.)[A-Za-z0-9_./-]+\.(ts|tsx)$/;
49
+ /** Problems with the declared `apiDocs` block: empty or duplicate locales, a `uiOnlyWrites` entry without reason. */
50
+ export function findApiDocsConfigProblems(apiDocs) {
51
+ const problems = [];
52
+ const { locales, uiOnlyWrites } = apiDocs;
53
+ if (locales !== undefined) {
54
+ if (locales.length === 0)
55
+ problems.push("apiDocs.locales must not be empty");
56
+ if (new Set(locales).size !== locales.length) {
57
+ problems.push("apiDocs.locales must not contain duplicates");
58
+ }
59
+ }
60
+ for (const [locale, text] of Object.entries(apiDocs.webhookDelivery ?? {})) {
61
+ if (text.trim() === "")
62
+ problems.push(`apiDocs.webhookDelivery: "${locale}" text must not be empty`);
63
+ }
64
+ for (const entry of uiOnlyWrites ?? []) {
65
+ if (entry.pattern.trim() === "")
66
+ problems.push("apiDocs.uiOnlyWrites: pattern must not be empty");
67
+ if (entry.reason.trim() === "") {
68
+ problems.push(`apiDocs.uiOnlyWrites: "${entry.pattern}" needs a non-empty reason`);
69
+ }
70
+ }
71
+ return problems;
72
+ }
49
73
  export function defineAppConfig(config) {
50
- const problems = [...findAppPortProblems(config.ports)];
74
+ const problems = [
75
+ ...findAppPortProblems(config.ports),
76
+ ...(config.apiDocs ? findApiDocsConfigProblems(config.apiDocs) : []),
77
+ ];
51
78
  if (config.client.entries.length === 0)
52
79
  problems.push("client.entries must name at least one entry");
53
80
  for (const entry of config.client.entries) {
@@ -2,6 +2,7 @@ import type { DbRunner } from "./connection.ts";
2
2
  import type { Table } from "./event-store-executor-context.ts";
3
3
  import type { ListWhere } from "./event-store-executor-read-filter.ts";
4
4
  import { type ListSort } from "./event-store-executor-read-sort.ts";
5
+ export declare const DEFAULT_LIST_LIMIT = 50;
5
6
  export declare function resolveListPagination(payload: {
6
7
  readonly limit?: unknown;
7
8
  readonly offset?: unknown;
@@ -8,8 +8,9 @@ import { physicalColumnName } from "./table-builder.js";
8
8
  // handlers that pass their payload straight through — a non-integer limit
9
9
  // would otherwise be interpolated raw into `LIMIT ${limit}` SQL text.
10
10
  const MAX_LIST_LIMIT = 200; // keep in sync with engine/entity-handlers.ts MAX_LIST_LIMIT
11
+ export const DEFAULT_LIST_LIMIT = 50;
11
12
  export function resolveListPagination(payload) {
12
- const limit = payload.limit ?? 50;
13
+ const limit = payload.limit ?? DEFAULT_LIST_LIMIT;
13
14
  const offset = payload.offset ?? 0;
14
15
  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 0) {
15
16
  throw new UnprocessableError("invalid_list_limit", {
@@ -8,6 +8,8 @@ export async function withSessionAdvisoryLock(db, key, fn) {
8
8
  }
9
9
  const conn = await client.reserve();
10
10
  try {
11
+ // Waiting for a peer must not hit the pool's statement_timeout (57014 would crash the waiter's boot).
12
+ await conn.unsafe("SET statement_timeout = 0");
11
13
  await conn.unsafe(`SELECT pg_advisory_lock($1)`, [key]);
12
14
  try {
13
15
  return await fn();
@@ -15,6 +17,7 @@ export async function withSessionAdvisoryLock(db, key, fn) {
15
17
  finally {
16
18
  // A dropped session already released its lock; failing here would mask fn's outcome.
17
19
  await conn.unsafe(`SELECT pg_advisory_unlock($1)`, [key]).catch(() => undefined);
20
+ await conn.unsafe("RESET statement_timeout").catch(() => undefined);
18
21
  }
19
22
  }
20
23
  finally {
@@ -77,12 +77,25 @@ function linkClause(input, link, mode) {
77
77
  }
78
78
  return { kind: "sql", sqlText, params: sql.params };
79
79
  }
80
- // Every registered entity with a file field can own a file. Join rows and gated entities
81
- // are left out: their readability is not resolvable without recursion.
80
+ function hasRowReadRule(entity) {
81
+ return Object.keys(entity.access?.read ?? {}).length > 0;
82
+ }
83
+ // A read model is served by hand-written queries that filter rows themselves; only its own
84
+ // access.read can be reproduced here, so without one every role of its detail query would read every row.
85
+ function ownerSources(option) {
86
+ const sources = [...option.entities].map(([name, entity]) => ({ name, entity }));
87
+ for (const [name, { entity, table }] of option.readModelEntities ?? []) {
88
+ if (!option.entities.has(name) && hasRowReadRule(entity)) {
89
+ sources.push({ name, entity, projectionTable: table });
90
+ }
91
+ }
92
+ return sources;
93
+ }
94
+ // Join rows and gated entities are left out: their readability is not resolvable without recursion.
82
95
  function ownerCandidates(input, selfName) {
83
96
  const { option } = input;
84
97
  const owners = [];
85
- for (const [name, entity] of option.entities) {
98
+ for (const { name, entity, projectionTable } of ownerSources(option)) {
86
99
  if (name === FILE_REF_ENTITY_NAME || name === selfName)
87
100
  continue;
88
101
  if (entity.parentRef !== undefined || entity.readGate !== undefined)
@@ -94,14 +107,20 @@ function ownerCandidates(input, selfName) {
94
107
  const fileFields = Object.entries(entity.fields)
95
108
  .filter(([, field]) => isFileField(field))
96
109
  .map(([fieldName]) => fieldName);
97
- if (fileFields.length > 0)
98
- owners.push({ name, entity, fileFields });
110
+ if (fileFields.length === 0)
111
+ continue;
112
+ owners.push({
113
+ name,
114
+ entity,
115
+ table: projectionTable ?? tableOf(option, name, entity),
116
+ fileFields,
117
+ });
99
118
  }
100
119
  return owners;
101
120
  }
102
121
  function ownerBranch(input, owner, refTable, sql) {
103
- const { option, user, db } = input;
104
- const ownerTable = tableOf(option, owner.name, owner.entity);
122
+ const { user, db } = input;
123
+ const ownerTable = owner.table;
105
124
  const ownerTableName = String(schemaTableName(ownerTable));
106
125
  const ownership = buildOwnershipClause(user, owner.entity.access?.read, ownerTable, 1, ownerTableName);
107
126
  if (ownership.kind === "empty")
@@ -2,13 +2,12 @@
2
2
  import type { EntityDefinition, FieldDefinition, FieldsMap } from "@cosmicdrift/kumiko-types/fields";
3
3
  import type { EntityRelations } from "@cosmicdrift/kumiko-types/relations";
4
4
  import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
5
- import type { Table } from "./event-store-executor-context.ts";
6
5
  import type { LocatedTimestampRead } from "./located-timestamp.ts";
7
6
  import type { MoneyRead } from "./money.ts";
8
7
  export { toSnakeCase } from "../utils/case.ts";
9
8
  import { type ColumnBuilder, type ColumnHandle, type SchemaTable, type TableColumns } from "./dialect.ts";
10
9
  export { SOFT_DELETE_LIVE_ROW_PREDICATE } from "./entity-table-indexes.ts";
11
- export declare function physicalColumnName(table: Table, field: string): string;
10
+ export declare function physicalColumnName(table: unknown, field: string): string;
12
11
  export type AnyPgColumn = ColumnHandle;
13
12
  export declare const READ_MODEL_PREFIX = "read_";
14
13
  export declare function toTableName(entityName: string): string;