@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.
- package/agents/api/framework-db.md +1 -1
- package/agents/api/framework-engine.md +50 -1
- package/agents/api/framework-errors.md +2 -0
- package/agents/api/framework-ui-types.md +10 -0
- package/agents/api/renderer-web.md +113 -10
- package/agents/api/types.md +30 -0
- package/agents/api.md +3 -3
- package/agents/boot-rules.md +4 -0
- package/agents/examples/api-docs.md +702 -0
- package/agents/examples/realtime-sse.md +37 -2
- package/agents/examples/record-detail-layout.md +35 -2
- package/agents/examples/wizard-form.md +96 -5
- package/agents/examples.md +1 -0
- package/agents/features.md +6 -0
- package/agents/widgets.md +6 -0
- package/dist/api/auth-middleware.d.ts +1 -0
- package/dist/api/index.d.ts +3 -0
- package/dist/api/index.js +3 -0
- package/dist/api/pat-auth-reject.d.ts +7 -0
- package/dist/api/pat-auth-reject.js +7 -0
- package/dist/api/server-middleware.js +2 -1
- package/dist/compliance/sub-processors.js +2 -2
- package/dist/config/index.d.ts +25 -0
- package/dist/config/index.js +28 -1
- package/dist/db/event-store-executor-read-paging.d.ts +1 -0
- package/dist/db/event-store-executor-read-paging.js +2 -1
- package/dist/db/queries/session-advisory-lock.js +3 -0
- package/dist/db/read-gate-clause.js +26 -7
- package/dist/db/table-builder.d.ts +1 -2
- package/dist/engine/boot-validator/boot-rules.d.ts +20 -0
- package/dist/engine/boot-validator/list-table-options.js +1 -0
- package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +15 -0
- package/dist/engine/boot-validator/screens-forms-layout-rules.js +15 -0
- package/dist/engine/boot-validator/screens-forms.d.ts +1 -1
- package/dist/engine/boot-validator/screens-forms.js +60 -3
- package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +5 -0
- package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +5 -0
- package/dist/engine/boot-validator/screens-kind-projection-detail.js +19 -0
- package/dist/engine/boot-validator/screens-lists.js +2 -2
- package/dist/engine/define-feature.js +3 -0
- package/dist/engine/entity-list-runtime-options.js +12 -0
- package/dist/engine/factories.d.ts +2 -0
- package/dist/engine/feature-builder-state.d.ts +2 -1
- package/dist/engine/feature-builder-state.js +1 -0
- package/dist/engine/index.d.ts +5 -2
- package/dist/engine/index.js +4 -1
- package/dist/engine/project-app-schema-for-roles.js +11 -10
- package/dist/engine/registry-facade.js +13 -0
- package/dist/engine/screen-helpers.d.ts +1 -0
- package/dist/engine/screen-helpers.js +1 -1
- package/dist/engine/webhook-contracts.d.ts +12 -0
- package/dist/engine/webhook-contracts.js +172 -0
- package/dist/engine/webhook-events.d.ts +34 -0
- package/dist/engine/webhook-events.js +71 -0
- package/dist/errors/docs-url.js +2 -19
- package/dist/errors/error-codes.d.ts +20 -0
- package/dist/errors/error-codes.js +19 -0
- package/dist/errors/index.d.ts +2 -0
- package/dist/errors/index.js +1 -0
- package/dist/i18n/required-surface-keys.d.ts +4 -0
- package/dist/i18n/required-surface-keys.js +15 -0
- package/dist/pipeline/context-services.d.ts +1 -0
- package/dist/pipeline/context-services.js +1 -0
- package/dist/pipeline/handler-context-scope.js +5 -1
- package/dist/pipeline/user-live-signals.d.ts +5 -0
- package/dist/pipeline/user-live-signals.js +20 -0
- package/package.json +3 -3
- 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
|
|
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([
|
|
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
|
-
|
|
889
|
-
await expect(
|
|
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(
|
|
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
|
-
{
|
|
1261
|
-
|
|
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",
|
package/agents/examples.md
CHANGED
|
@@ -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` |
|
package/agents/features.md
CHANGED
|
@@ -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;
|
package/dist/api/index.d.ts
CHANGED
|
@@ -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";
|
|
@@ -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:
|
|
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-
|
|
90
|
+
addedAt: "2026-11-01",
|
|
91
91
|
appliesTo: ["all-tiers"],
|
|
92
|
-
status: "
|
|
92
|
+
status: "active",
|
|
93
93
|
},
|
|
94
94
|
];
|
|
95
95
|
/**
|
package/dist/config/index.d.ts
CHANGED
|
@@ -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,
|
package/dist/config/index.js
CHANGED
|
@@ -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 = [
|
|
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 ??
|
|
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
|
-
|
|
81
|
-
|
|
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
|
|
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
|
|
98
|
-
|
|
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 {
|
|
104
|
-
const ownerTable =
|
|
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:
|
|
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;
|