@cosmicdrift/kumiko-samples 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 (122) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +31 -1
  3. package/packages/bundled-features/src/agent-tools/agent-doc-lint.ts +64 -3
  4. package/packages/bundled-features/src/agent-tools/agent-manifest.ts +13 -130
  5. package/packages/bundled-features/src/agent-tools/api-docs/anchors.ts +60 -0
  6. package/packages/bundled-features/src/agent-tools/api-docs/check.ts +25 -0
  7. package/packages/bundled-features/src/agent-tools/api-docs/collect-events.ts +140 -0
  8. package/packages/bundled-features/src/agent-tools/api-docs/collect.ts +175 -0
  9. package/packages/bundled-features/src/agent-tools/api-docs/curl.ts +28 -0
  10. package/packages/bundled-features/src/agent-tools/api-docs/error-table.ts +45 -0
  11. package/packages/bundled-features/src/agent-tools/api-docs/examples.ts +43 -0
  12. package/packages/bundled-features/src/agent-tools/api-docs/generate.ts +179 -0
  13. package/packages/bundled-features/src/agent-tools/api-docs/index-json.ts +29 -0
  14. package/packages/bundled-features/src/agent-tools/api-docs/index.ts +21 -0
  15. package/packages/bundled-features/src/agent-tools/api-docs/list-parameters.ts +38 -0
  16. package/packages/bundled-features/src/agent-tools/api-docs/markdown.ts +70 -0
  17. package/packages/bundled-features/src/agent-tools/api-docs/menu-path.ts +82 -0
  18. package/packages/bundled-features/src/agent-tools/api-docs/model.ts +83 -0
  19. package/packages/bundled-features/src/agent-tools/api-docs/problems.ts +58 -0
  20. package/packages/bundled-features/src/agent-tools/api-docs/render-events.ts +76 -0
  21. package/packages/bundled-features/src/agent-tools/api-docs/render-openapi.ts +216 -0
  22. package/packages/bundled-features/src/agent-tools/api-docs/render-overview.ts +86 -0
  23. package/packages/bundled-features/src/agent-tools/api-docs/render-reference.ts +79 -0
  24. package/packages/bundled-features/src/agent-tools/api-docs/render-tokens.ts +136 -0
  25. package/packages/bundled-features/src/agent-tools/api-docs/schema-fields.ts +167 -0
  26. package/packages/bundled-features/src/agent-tools/api-docs/section-ids.ts +28 -0
  27. package/packages/bundled-features/src/agent-tools/api-docs/system-only.ts +11 -0
  28. package/packages/bundled-features/src/agent-tools/api-docs/texts/de.ts +166 -0
  29. package/packages/bundled-features/src/agent-tools/api-docs/texts/en.ts +159 -0
  30. package/packages/bundled-features/src/agent-tools/api-docs/texts/es.ts +162 -0
  31. package/packages/bundled-features/src/agent-tools/api-docs/texts/fr.ts +169 -0
  32. package/packages/bundled-features/src/agent-tools/api-docs/texts/index.ts +67 -0
  33. package/packages/bundled-features/src/agent-tools/api-docs/texts/it.ts +165 -0
  34. package/packages/bundled-features/src/agent-tools/api-docs/texts/types.ts +130 -0
  35. package/packages/bundled-features/src/agent-tools/api-docs/ui-writes.ts +81 -0
  36. package/packages/bundled-features/src/agent-tools/changes.json +24 -0
  37. package/packages/bundled-features/src/agent-tools/handler-schema.ts +45 -0
  38. package/packages/bundled-features/src/agent-tools/index.ts +24 -0
  39. package/packages/bundled-features/src/agent-tools/labels.ts +181 -0
  40. package/packages/bundled-features/src/auth-email-password/changes.json +24 -0
  41. package/packages/bundled-features/src/auth-email-password/seeding.ts +84 -6
  42. package/packages/bundled-features/src/auth-email-password/web/i18n.ts +1 -0
  43. package/packages/bundled-features/src/auth-email-password/web/signup-screen.tsx +48 -3
  44. package/packages/bundled-features/src/auth-email-password/web/static-account.ts +190 -0
  45. package/packages/bundled-features/src/auth-email-password/web/static-client.ts +226 -0
  46. package/packages/bundled-features/src/foundation-shared/demo-admin-env.ts +11 -0
  47. package/packages/bundled-features/src/foundation-shared/index.ts +5 -1
  48. package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
  49. package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +99 -71
  50. package/packages/bundled-features/src/inbound-mail-foundation/feature.ts +2 -2
  51. package/packages/bundled-features/src/inbound-provider-imap/changes.json +6 -0
  52. package/packages/bundled-features/src/inbound-provider-imap/imap-client.ts +3 -1
  53. package/packages/bundled-features/src/personal-access-tokens/changes.json +6 -0
  54. package/packages/bundled-features/src/personal-access-tokens/feature.ts +5 -2
  55. package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts +7 -2
  56. package/packages/bundled-features/src/personal-access-tokens/i18n.ts +6 -1
  57. package/packages/bundled-features/src/personal-access-tokens/index.ts +37 -2
  58. package/packages/bundled-features/src/personal-access-tokens/scope-events-check.ts +28 -0
  59. package/packages/bundled-features/src/personal-access-tokens/screens.ts +9 -1
  60. package/packages/bundled-features/src/personal-access-tokens/web/constants.ts +1 -0
  61. package/packages/bundled-features/src/personal-access-tokens/web/scopes.ts +14 -0
  62. package/packages/bundled-features/src/presence/changes.json +8 -0
  63. package/packages/bundled-features/src/presence/feature.ts +25 -0
  64. package/packages/bundled-features/src/presence/handlers/heartbeat.write.ts +52 -0
  65. package/packages/bundled-features/src/presence/handlers/leave.write.ts +41 -0
  66. package/packages/bundled-features/src/presence/handlers/list.query.ts +39 -0
  67. package/packages/bundled-features/src/presence/index.ts +7 -0
  68. package/packages/bundled-features/src/presence/options.ts +30 -0
  69. package/packages/bundled-features/src/presence/payloads.ts +26 -0
  70. package/packages/bundled-features/src/presence/room.ts +65 -0
  71. package/packages/bundled-features/src/presence/store.ts +185 -0
  72. package/packages/bundled-features/src/sessions/feature.ts +6 -2
  73. package/packages/bundled-features/src/sessions/handlers/last-activity-probe.route.ts +19 -0
  74. package/packages/bundled-features/src/tenant-inactivity/changes.json +12 -0
  75. package/packages/bundled-features/src/tenant-inactivity/check-inactive-tenants.ts +14 -6
  76. package/packages/bundled-features/src/tenant-inactivity/constants.ts +4 -1
  77. package/packages/bundled-features/src/tenant-inactivity/handlers/inactivity-state.query.ts +2 -1
  78. package/packages/bundled-features/src/tenant-inactivity/handlers/keep-account.write.ts +2 -1
  79. package/packages/bundled-features/src/tenant-inactivity/options.ts +1 -0
  80. package/packages/bundled-features/src/tenant-inactivity/remote-activity.ts +6 -1
  81. package/packages/bundled-features/src/tenant-inactivity/static-keep-account.ts +37 -0
  82. package/packages/bundled-features/src/tenant-lifecycle/constants.ts +2 -0
  83. package/packages/bundled-features/src/tenant-lifecycle/handlers/cancel-destruction.write.ts +6 -2
  84. package/packages/bundled-features/src/tenant-lifecycle/handlers/request-destruction.write.ts +2 -1
  85. package/packages/bundled-features/src/tenant-lifecycle/index.ts +1 -0
  86. package/packages/bundled-features/src/waitlist/changes.json +6 -0
  87. package/packages/bundled-features/src/waitlist/static-submit.ts +56 -0
  88. package/samples/apps/styleguide/src/features/widgets/i18n.ts +143 -0
  89. package/samples/apps/styleguide/src/features/widgets/web/VariantsDemo.tsx +276 -0
  90. package/samples/apps/styleguide/src/features/widgets/web/Widgets.tsx +3 -0
  91. package/samples/apps/styleguide/src/features/workboard/feature.ts +1 -0
  92. package/samples/apps/use-all-bundled/feature-manifest.json +23 -1
  93. package/samples/apps/use-all-bundled/src/run-config.ts +3 -0
  94. package/samples/recipes/api-docs/README.md +52 -0
  95. package/samples/recipes/api-docs/api-docs/de/events.md +62 -0
  96. package/samples/recipes/api-docs/api-docs/de/overview.md +100 -0
  97. package/samples/recipes/api-docs/api-docs/de/reference/tickets.md +305 -0
  98. package/samples/recipes/api-docs/api-docs/de/tokens.md +66 -0
  99. package/samples/recipes/api-docs/api-docs/en/events.md +62 -0
  100. package/samples/recipes/api-docs/api-docs/en/overview.md +100 -0
  101. package/samples/recipes/api-docs/api-docs/en/reference/tickets.md +305 -0
  102. package/samples/recipes/api-docs/api-docs/en/tokens.md +66 -0
  103. package/samples/recipes/api-docs/api-docs/index.json +371 -0
  104. package/samples/recipes/api-docs/api-docs/openapi.json +982 -0
  105. package/samples/recipes/api-docs/api-examples/ticket-close.json +21 -0
  106. package/samples/recipes/api-docs/api-examples/ticket-create.json +42 -0
  107. package/samples/recipes/api-docs/api-examples/ticket-detail.json +28 -0
  108. package/samples/recipes/api-docs/api-examples/ticket-list.json +31 -0
  109. package/samples/recipes/api-docs/api-examples/ticket-update.json +54 -0
  110. package/samples/recipes/api-docs/api-examples/webhooks/ticket-closed.json +8 -0
  111. package/samples/recipes/api-docs/api-examples/webhooks/ticket-created.json +10 -0
  112. package/samples/recipes/api-docs/kumiko.config.ts +33 -0
  113. package/samples/recipes/api-docs/package.json +14 -0
  114. package/samples/recipes/api-docs/src/feature.ts +218 -0
  115. package/samples/recipes/api-docs/tsconfig.json +22 -0
  116. package/samples/recipes/realtime-sse/README.md +1 -0
  117. package/samples/recipes/realtime-sse/package.json +1 -0
  118. package/samples/recipes/realtime-sse/src/feature.ts +9 -0
  119. package/samples/recipes/record-detail-layout/README.md +1 -0
  120. package/samples/recipes/record-detail-layout/src/feature.ts +10 -0
  121. package/samples/recipes/wizard-form/README.md +9 -0
  122. package/samples/recipes/wizard-form/src/feature.ts +13 -2
@@ -0,0 +1,21 @@
1
+ {
2
+ "request": {
3
+ "endpoint": "/api/write",
4
+ "body": {
5
+ "type": "helpdesk:write:ticket:close",
6
+ "payload": {
7
+ "id": "00000000-0000-4000-8000-000000000001",
8
+ "resolution": "Replaced the cartridge"
9
+ }
10
+ }
11
+ },
12
+ "response": {
13
+ "status": 200,
14
+ "body": {
15
+ "isSuccess": true,
16
+ "data": {
17
+ "id": "00000000-0000-4000-8000-000000000001"
18
+ }
19
+ }
20
+ }
21
+ }
@@ -0,0 +1,42 @@
1
+ {
2
+ "request": {
3
+ "endpoint": "/api/write",
4
+ "body": {
5
+ "type": "helpdesk:write:ticket:create",
6
+ "payload": {
7
+ "title": "Printer is on fire",
8
+ "priority": "high"
9
+ }
10
+ }
11
+ },
12
+ "response": {
13
+ "status": 200,
14
+ "body": {
15
+ "isSuccess": true,
16
+ "data": {
17
+ "kind": "save",
18
+ "id": "00000000-0000-4000-8000-000000000001",
19
+ "data": {
20
+ "id": "00000000-0000-4000-8000-000000000001",
21
+ "tenantId": "00000000-0000-4000-8000-000000000002",
22
+ "version": 1,
23
+ "insertedAt": "2026-01-15T09:30:00.000Z",
24
+ "modifiedAt": null,
25
+ "insertedById": "00000000-0000-4000-8000-000000000003",
26
+ "modifiedById": null,
27
+ "title": "Printer is on fire",
28
+ "status": "open",
29
+ "priority": "high"
30
+ },
31
+ "changes": {
32
+ "title": "Printer is on fire",
33
+ "status": "open",
34
+ "priority": "high"
35
+ },
36
+ "previous": {},
37
+ "isNew": true,
38
+ "entityName": "ticket"
39
+ }
40
+ }
41
+ }
42
+ }
@@ -0,0 +1,28 @@
1
+ {
2
+ "request": {
3
+ "endpoint": "/api/query",
4
+ "body": {
5
+ "type": "helpdesk:query:ticket:detail",
6
+ "payload": {
7
+ "id": "00000000-0000-4000-8000-000000000001"
8
+ }
9
+ }
10
+ },
11
+ "response": {
12
+ "status": 200,
13
+ "body": {
14
+ "data": {
15
+ "id": "00000000-0000-4000-8000-000000000001",
16
+ "tenantId": "00000000-0000-4000-8000-000000000002",
17
+ "version": 1,
18
+ "insertedAt": "2026-01-15T09:30:00.000Z",
19
+ "modifiedAt": null,
20
+ "insertedById": "00000000-0000-4000-8000-000000000003",
21
+ "modifiedById": null,
22
+ "title": "Printer is on fire",
23
+ "status": "open",
24
+ "priority": "high"
25
+ }
26
+ }
27
+ }
28
+ }
@@ -0,0 +1,31 @@
1
+ {
2
+ "request": {
3
+ "endpoint": "/api/query",
4
+ "body": {
5
+ "type": "helpdesk:query:ticket:list",
6
+ "payload": {}
7
+ }
8
+ },
9
+ "response": {
10
+ "status": 200,
11
+ "body": {
12
+ "data": {
13
+ "rows": [
14
+ {
15
+ "id": "00000000-0000-4000-8000-000000000001",
16
+ "tenantId": "00000000-0000-4000-8000-000000000002",
17
+ "version": 1,
18
+ "insertedAt": "2026-01-15T09:30:00.000Z",
19
+ "modifiedAt": null,
20
+ "insertedById": "00000000-0000-4000-8000-000000000003",
21
+ "modifiedById": null,
22
+ "title": "Printer is on fire",
23
+ "status": "open",
24
+ "priority": "high"
25
+ }
26
+ ],
27
+ "nextCursor": null
28
+ }
29
+ }
30
+ }
31
+ }
@@ -0,0 +1,54 @@
1
+ {
2
+ "request": {
3
+ "endpoint": "/api/write",
4
+ "body": {
5
+ "type": "helpdesk:write:ticket:update",
6
+ "payload": {
7
+ "id": "00000000-0000-4000-8000-000000000001",
8
+ "version": 1,
9
+ "changes": {
10
+ "priority": "normal"
11
+ }
12
+ }
13
+ }
14
+ },
15
+ "response": {
16
+ "status": 200,
17
+ "body": {
18
+ "isSuccess": true,
19
+ "data": {
20
+ "kind": "save",
21
+ "id": "00000000-0000-4000-8000-000000000001",
22
+ "data": {
23
+ "id": "00000000-0000-4000-8000-000000000001",
24
+ "tenantId": "00000000-0000-4000-8000-000000000002",
25
+ "version": 2,
26
+ "insertedAt": "2026-01-15T09:30:00.000Z",
27
+ "modifiedAt": "2026-01-15T09:30:00.000Z",
28
+ "insertedById": "00000000-0000-4000-8000-000000000003",
29
+ "modifiedById": "00000000-0000-4000-8000-000000000003",
30
+ "title": "Printer is on fire",
31
+ "status": "open",
32
+ "priority": "normal"
33
+ },
34
+ "changes": {
35
+ "priority": "normal"
36
+ },
37
+ "previous": {
38
+ "id": "00000000-0000-4000-8000-000000000001",
39
+ "tenantId": "00000000-0000-4000-8000-000000000002",
40
+ "version": 1,
41
+ "insertedAt": "2026-01-15T09:30:00.000Z",
42
+ "modifiedAt": null,
43
+ "insertedById": "00000000-0000-4000-8000-000000000003",
44
+ "modifiedById": null,
45
+ "title": "Printer is on fire",
46
+ "status": "open",
47
+ "priority": "high"
48
+ },
49
+ "isNew": false,
50
+ "entityName": "ticket"
51
+ }
52
+ }
53
+ }
54
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "event": "helpdesk:ticket-closed",
3
+ "version": 1,
4
+ "payload": {
5
+ "id": "00000000-0000-4000-8000-000000000001",
6
+ "resolution": "Replaced the roller"
7
+ }
8
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "event": "ticket.created",
3
+ "version": 1,
4
+ "payload": {
5
+ "id": "00000000-0000-4000-8000-000000000001",
6
+ "title": "Scanner jams",
7
+ "status": "open",
8
+ "priority": "low"
9
+ }
10
+ }
@@ -0,0 +1,33 @@
1
+ import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
2
+ import { defineAppConfig } from "@cosmicdrift/kumiko-framework/config";
3
+ import { localeDe } from "@cosmicdrift/kumiko-locale-de";
4
+ import { helpdeskFeature, patFeature } from "./src/feature";
5
+
6
+ const PURGE_REASON =
7
+ "Purging is an admin chore that stays in the app and is never offered to API clients.";
8
+
9
+ export default defineAppConfig({
10
+ features: [createAuthFoundationFeature(), helpdeskFeature, patFeature(), localeDe()],
11
+ includeBundled: true,
12
+ client: { entries: ["src/client.tsx"] },
13
+ ports: { dev: 4520, e2e: 4521, infra: { postgres: 15520 } },
14
+ apiDocs: {
15
+ appName: "Helpdesk",
16
+ baseUrl: "https://helpdesk.example.com",
17
+ locales: ["en", "de"],
18
+ planNote: {
19
+ en: "API tokens are included in every Helpdesk plan.",
20
+ de: "API-Tokens sind in jedem Helpdesk-Tarif enthalten.",
21
+ },
22
+ webhookDelivery: {
23
+ en: "Deliveries are signed so that you can verify the sender. A delivery that fails is retried a few times before it is dropped. Answer within a few seconds and treat repeated deliveries of the same event as one.",
24
+ de: "Zustellungen sind signiert, damit du den Absender prüfen kannst. Eine fehlgeschlagene Zustellung wird einige Male wiederholt, bevor sie verworfen wird. Antworte innerhalb weniger Sekunden und behandle wiederholte Zustellungen desselben Ereignisses als eine.",
25
+ },
26
+ uiOnlyWrites: [
27
+ {
28
+ pattern: "helpdesk:write:ticket:purge",
29
+ reason: PURGE_REASON,
30
+ },
31
+ ],
32
+ },
33
+ });
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "@cosmicdrift/kumiko-sample-api-docs",
3
+ "description": "API documentation for personal access tokens: recorded examples, kumiko api-docs and a committed golden.",
4
+ "private": true,
5
+ "dependencies": {
6
+ "@cosmicdrift/kumiko-bundled-features": "workspace:*",
7
+ "@cosmicdrift/kumiko-framework": "workspace:*",
8
+ "@cosmicdrift/kumiko-locale-de": "workspace:*",
9
+ "@cosmicdrift/kumiko-server-runtime": "workspace:*"
10
+ },
11
+ "devDependencies": {
12
+ "@cosmicdrift/kumiko-testing": "workspace:*"
13
+ }
14
+ }
@@ -0,0 +1,218 @@
1
+ // API docs sample: a helpdesk whose ticket handlers are reachable with a personal access token.
2
+ // Every handler a token scope reaches needs a description and, per locale, a title, description
3
+ // and field labels; `kumiko api-docs` turns them into the pages under api-docs/.
4
+
5
+ import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
6
+ import {
7
+ createEntity,
8
+ createEntityExecutor,
9
+ createSelectField,
10
+ createTextField,
11
+ defineFeature,
12
+ emitEvent,
13
+ setFields,
14
+ } from "@cosmicdrift/kumiko-framework/engine";
15
+ import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
16
+ import { z } from "zod";
17
+
18
+ export const ticketEntity = createEntity({
19
+ table: "read_api_docs_tickets",
20
+ webhookEvents: true,
21
+ description: "A support request with a title, a priority and an open or closed status.",
22
+ fields: {
23
+ title: createTextField({ personal: false, reason: "is_business_data", required: true }),
24
+ status: createSelectField({ options: ["open", "closed"] as const, default: "open" }),
25
+ priority: createSelectField({ options: ["low", "normal", "high"] as const, default: "normal" }),
26
+ },
27
+ });
28
+
29
+ const ticketAccess = { roles: ["Admin", "User"] } as const;
30
+
31
+ export const helpdeskFeature = defineFeature("helpdesk", (r) => {
32
+ const { table: ticketTable, executor: ticketExecutor } = createEntityExecutor(
33
+ "ticket",
34
+ ticketEntity,
35
+ );
36
+
37
+ r.crud("ticket", ticketEntity, {
38
+ write: { access: ticketAccess },
39
+ read: { access: ticketAccess },
40
+ verbs: { delete: false },
41
+ descriptions: {
42
+ create: "Opens a new ticket.",
43
+ update: "Changes the title or the priority of a ticket.",
44
+ list: "Lists tickets, newest first.",
45
+ detail: "Returns one ticket.",
46
+ },
47
+ });
48
+
49
+ const ticketClosed = r.defineEvent("ticket-closed", z.object({ resolution: z.string().min(1) }), {
50
+ piiFields: "none",
51
+ });
52
+
53
+ r.defineWebhookEvent({
54
+ name: "ticket-closed",
55
+ wireName: "ticket.closed",
56
+ description: "A ticket was closed and its resolution recorded.",
57
+ payload: z.object({
58
+ id: z.uuid().describe("ID of the closed ticket"),
59
+ resolution: z.string().describe("How the ticket was resolved"),
60
+ }),
61
+ version: 1,
62
+ });
63
+
64
+ r.writeHandler({
65
+ name: "ticket:close",
66
+ description: "Closes a ticket and records how it was resolved.",
67
+ schema: z.object({ id: z.uuid(), resolution: z.string().min(1) }),
68
+ access: ticketAccess,
69
+ handler: async (event, ctx) => {
70
+ const ticket = await ticketExecutor.detail({ id: event.payload.id }, event.user, ctx.db);
71
+ if (!ticket) return failNotFound("ticket", event.payload.id);
72
+ if (ticket["status"] === "closed") return failUnprocessable("ticket_already_closed");
73
+ await emitEvent(ctx, ticketClosed, {
74
+ aggregateId: event.payload.id,
75
+ aggregateType: "ticket",
76
+ payload: { resolution: event.payload.resolution },
77
+ });
78
+ return { isSuccess: true as const, data: { id: event.payload.id } };
79
+ },
80
+ });
81
+
82
+ // Reachable from a screen but deliberately outside every token scope: see uiOnlyWrites in kumiko.config.ts.
83
+ r.writeHandler({
84
+ name: "ticket:purge",
85
+ description: "Removes tickets that were closed long ago.",
86
+ schema: z.object({ olderThanDays: z.number().int().min(30) }),
87
+ access: { roles: ["Admin"] },
88
+ handler: async () => ({ isSuccess: true as const, data: { purged: 0 } }),
89
+ });
90
+
91
+ const markTicketClosed = setFields(ticketTable, { status: "closed" });
92
+ r.projection({
93
+ name: "ticket-status",
94
+ source: "ticket",
95
+ table: ticketTable,
96
+ apply: { [ticketClosed.name]: (event, tx, ctx) => markTicketClosed(event, tx, ctx) },
97
+ });
98
+
99
+ r.screen({
100
+ id: "ticket-list",
101
+ type: "entityList",
102
+ entity: "ticket",
103
+ columns: ["title", "status", "priority"],
104
+ });
105
+ r.screen({
106
+ id: "ticket-edit",
107
+ type: "entityEdit",
108
+ entity: "ticket",
109
+ layout: { sections: [{ title: "helpdesk:section.ticket", fields: ["title", "priority"] }] },
110
+ });
111
+ r.screen({
112
+ id: "close-ticket",
113
+ type: "actionForm",
114
+ handler: "helpdesk:write:ticket:close",
115
+ fields: { resolution: createTextField({ personal: false, reason: "is_business_data" }) },
116
+ layout: { sections: [{ title: "helpdesk:section.close", fields: ["resolution"] }] },
117
+ });
118
+ r.screen({
119
+ id: "purge-tickets",
120
+ type: "actionForm",
121
+ handler: "helpdesk:write:ticket:purge",
122
+ fields: {},
123
+ layout: { sections: [] },
124
+ });
125
+
126
+ r.nav({ id: "tickets", label: "helpdesk:nav:tickets", screen: "helpdesk:screen:ticket-list" });
127
+ r.nav({ id: "settings", label: "helpdesk:nav:settings" });
128
+ r.nav({
129
+ id: "api-tokens",
130
+ label: "helpdesk:nav:api-tokens",
131
+ parent: "helpdesk:nav:settings",
132
+ screen: "personal-access-tokens:screen:api-tokens",
133
+ });
134
+
135
+ r.translations({
136
+ keys: {
137
+ "helpdesk:nav:tickets": { en: "Tickets", de: "Tickets" },
138
+ "helpdesk:nav:settings": { en: "Settings", de: "Einstellungen" },
139
+ "helpdesk:nav:api-tokens": { en: "API tokens", de: "API-Tokens" },
140
+ "helpdesk:section.ticket": { en: "Ticket", de: "Ticket" },
141
+ "helpdesk:section.close": { en: "Close ticket", de: "Ticket schließen" },
142
+ "helpdesk:entity:ticket:field:title": { en: "Title", de: "Titel" },
143
+ "helpdesk:entity:ticket:field:status": { en: "Status", de: "Status" },
144
+ "helpdesk:entity:ticket:field:priority": { en: "Priority", de: "Priorität" },
145
+ "helpdesk:write:ticket:create:title": { en: "Create ticket", de: "Ticket anlegen" },
146
+ "helpdesk:write:ticket:create:description": {
147
+ en: "Opens a new ticket.",
148
+ de: "Legt ein neues Ticket an.",
149
+ },
150
+ "helpdesk:write:ticket:update:title": { en: "Update ticket", de: "Ticket ändern" },
151
+ "helpdesk:write:ticket:update:description": {
152
+ en: "Changes the title or the priority of a ticket.",
153
+ de: "Ändert Titel oder Priorität eines Tickets.",
154
+ },
155
+ "helpdesk:query:ticket:list:title": { en: "List tickets", de: "Tickets auflisten" },
156
+ "helpdesk:query:ticket:list:description": {
157
+ en: "Lists tickets, newest first.",
158
+ de: "Listet Tickets, neueste zuerst.",
159
+ },
160
+ "helpdesk:query:ticket:detail:title": { en: "Show ticket", de: "Ticket anzeigen" },
161
+ "helpdesk:query:ticket:detail:description": {
162
+ en: "Returns one ticket.",
163
+ de: "Liefert ein Ticket.",
164
+ },
165
+ "helpdesk:write:ticket:close:title": { en: "Close ticket", de: "Ticket schließen" },
166
+ "helpdesk:write:ticket:close:description": {
167
+ en: "Closes a ticket and records how it was resolved.",
168
+ de: "Schließt ein Ticket und hält fest, wie es gelöst wurde.",
169
+ },
170
+ "helpdesk:write:ticket:close:field:id": { en: "Ticket", de: "Ticket" },
171
+ "helpdesk:write:ticket:close:field:resolution": { en: "Resolution", de: "Lösung" },
172
+ "helpdesk:write:ticket:purge:title": { en: "Purge tickets", de: "Tickets bereinigen" },
173
+ "helpdesk:write:ticket:purge:description": {
174
+ en: "Removes tickets that were closed long ago.",
175
+ de: "Entfernt Tickets, die lange geschlossen sind.",
176
+ },
177
+ "helpdesk:write:ticket:purge:field:olderThanDays": {
178
+ en: "Closed longer than (days)",
179
+ de: "Länger geschlossen als (Tage)",
180
+ },
181
+ "helpdesk:entity:ticket": { en: "ticket", de: "Ticket" },
182
+ "helpdesk:entity:ticket:field:id": { en: "Ticket ID", de: "Ticket-ID" },
183
+ "helpdesk:webhook:ticket-closed:description": {
184
+ en: "A ticket was closed and its resolution recorded.",
185
+ de: "Ein Ticket wurde geschlossen und seine Lösung festgehalten.",
186
+ },
187
+ "helpdesk:webhook:ticket-closed:field:id": {
188
+ en: "ID of the closed ticket",
189
+ de: "ID des geschlossenen Tickets",
190
+ },
191
+ "helpdesk:webhook:ticket-closed:field:resolution": {
192
+ en: "How the ticket was resolved",
193
+ de: "Wie das Ticket gelöst wurde",
194
+ },
195
+ "helpdesk:entity:__action-form__:field:resolution": { en: "Resolution", de: "Lösung" },
196
+ },
197
+ });
198
+ });
199
+
200
+ export const PAT_RATE_LIMIT = { maxRequests: 60, windowMs: 60_000 } as const;
201
+
202
+ export function patFeature() {
203
+ return createPersonalAccessTokensFeature({
204
+ scopes: {
205
+ tickets: {
206
+ label: "Tickets",
207
+ events: ["ticket.created", "helpdesk:ticket-closed"],
208
+ read: ["helpdesk:query:ticket:*"],
209
+ write: [
210
+ "helpdesk:write:ticket:create",
211
+ "helpdesk:write:ticket:update",
212
+ "helpdesk:write:ticket:close",
213
+ ],
214
+ },
215
+ },
216
+ rateLimit: PAT_RATE_LIMIT,
217
+ });
218
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "extends": "../../../tsconfig.json",
3
+ "compilerOptions": {
4
+ "paths": {
5
+ "@cosmicdrift/kumiko-framework/*": [
6
+ "../../../packages/framework/src/*/index.ts"
7
+ ],
8
+ "@cosmicdrift/kumiko-bundled-features/*": [
9
+ "../../../packages/bundled-features/src/*/index.ts"
10
+ ],
11
+ "@cosmicdrift/kumiko-dev-server": [
12
+ "../../../packages/dev-server/src/index.ts"
13
+ ],
14
+ "@cosmicdrift/kumiko-dev-server/*": ["../../../packages/dev-server/src/*"]
15
+ },
16
+ "noEmit": true,
17
+ "rootDir": "../../..",
18
+ "lib": ["ESNext", "DOM", "DOM.Iterable"],
19
+ "types": ["bun-types"]
20
+ },
21
+ "include": ["./src", "./kumiko.config.ts"]
22
+ }
@@ -6,6 +6,7 @@ Server-sent events — live updates without F5.
6
6
 
7
7
  - Entity writes that fan out over SSE
8
8
  - Client subscription shape for live lists
9
+ - 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)
9
10
 
10
11
  ## Source
11
12
 
@@ -3,6 +3,7 @@
3
3
  "description": "Server-sent events demo. Goodbye F5.",
4
4
  "private": true,
5
5
  "dependencies": {
6
+ "@cosmicdrift/kumiko-bundled-features": "workspace:*",
6
7
  "@cosmicdrift/kumiko-framework": "workspace:*"
7
8
  },
8
9
  "devDependencies": {
@@ -1,3 +1,4 @@
1
+ import { createPresenceFeature } from "@cosmicdrift/kumiko-bundled-features/presence";
1
2
  import {
2
3
  createEntity,
3
4
  createTextField,
@@ -25,3 +26,11 @@ export const chatFeature = defineFeature("chat", (r) => {
25
26
  });
26
27
  r.writeHandler(defineEntityDeleteHandler("message", messageEntity, adminWrite));
27
28
  });
29
+
30
+ // Who else has a message open. The heartbeat is an ordinary write; the others learn about a
31
+ // change through an SSE frame addressed to them (`presence:event:changed`, no names inside),
32
+ // then refetch with `usePresence` / `usePresenceList` on the client.
33
+ export const presenceFeature = createPresenceFeature({
34
+ entities: ["message"],
35
+ roles: ["Admin", "User"],
36
+ });
@@ -9,6 +9,7 @@ header, a metrics band, and a tabbed layout instead of one long stacked form.
9
9
  rendered from the columns of the screen's own query row
10
10
  - `layout.mode: "tabs"` with two `relatedList` tabs (order items, payments)
11
11
  and one `fields` tab (master data) — each `relatedList` runs its own query
12
+ - a header action with `showOnTabs: ["payments"]`, shown only while that tab is active
12
13
  - boot-validator catching two common author mistakes: a `metrics` entry
13
14
  with an empty `label`, and a `tabs` layout with fewer than two
14
15
  sections
@@ -16,6 +16,8 @@
16
16
  // not inside any tab's Card. `inlineActions` keeps download-invoice a visible
17
17
  // button next to it where the page header would otherwise fold it into the menu.
18
18
  //
19
+ // 6. `showOnTabs` limits the record-payment action to the payments tab.
20
+ //
19
21
  // projectionDetail has no entity — it binds to an explicit query instead, so
20
22
  // every field name below (header, metrics, fields) is a column of that
21
23
  // query's row, not an entity field.
@@ -158,6 +160,14 @@ export function createOrderDeskFeature(): FeatureDefinition {
158
160
  screen: "order-detail",
159
161
  icon: "download",
160
162
  },
163
+ {
164
+ kind: "navigate",
165
+ id: "record-payment",
166
+ label: "order-desk.action.recordPayment",
167
+ screen: "order-detail",
168
+ icon: "plus",
169
+ showOnTabs: ["payments"],
170
+ },
161
171
  ],
162
172
  inlineActions: ["download-invoice"],
163
173
  access: { roles: ["Support", "Admin"] },
@@ -24,6 +24,15 @@ the user left off.
24
24
  mounted alongside this one (both enforced at boot). The actual
25
25
  save/resume/discard wiring happens automatically inside `RenderEdit` —
26
26
  this recipe never calls a form-draft handler from its own code.
27
+ - **Step rail texts** — a section's `subtitle` is the line under its step in
28
+ the rail (opt-in, `description` is never used there); `summaryField`
29
+ replaces it with the entered value once the step is done. `wizard.aside`
30
+ adds the "up next" card, and `finishDescription` the finish card on the
31
+ last step. Extension steps take the same three texts; on an `actionForm`
32
+ `summaryField` and `submitDisabledWhen` may name a field of its `fields`.
33
+ - **Footer options** — `wizard.saveAndCloseOnCreate` offers "Save and close" (also on the last step)
34
+ while creating; `wizard.submitDisabledWhen` disables Finish while a field
35
+ condition holds. It is UI-only: enforce the rule in a validation hook too.
27
36
 
28
37
  ## Feature composition
29
38
 
@@ -33,9 +33,20 @@ export const listingsFeature = defineFeature("listings", (r) => {
33
33
  layout: {
34
34
  mode: "wizard",
35
35
  draft: true,
36
+ wizard: {
37
+ aside: { upNext: true, finishDescription: "Publishes the listing." },
38
+ saveAndCloseOnCreate: true,
39
+ // UI-only: the write handler would still accept a vehicle listing.
40
+ submitDisabledWhen: { field: "category", eq: "vehicles" },
41
+ },
36
42
  sections: [
37
- { title: "Basics", fields: ["title", "category"] },
38
- { title: "Pricing", fields: ["price", "condition"] },
43
+ {
44
+ title: "Basics",
45
+ subtitle: "Title and category",
46
+ summaryField: "title",
47
+ fields: ["title", "category"],
48
+ },
49
+ { title: "Pricing", subtitle: "Price and condition", fields: ["price", "condition"] },
39
50
  {
40
51
  kind: "extension",
41
52
  title: "Review",