@cosmicdrift/kumiko-samples 0.411.0 → 0.413.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 (182) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +13 -13
  3. package/packages/bundled-features/src/admin-shell/feature.ts +1 -1
  4. package/packages/bundled-features/src/agent-tools/agent-doc-lint.ts +64 -3
  5. package/packages/bundled-features/src/agent-tools/agent-manifest.ts +13 -130
  6. package/packages/bundled-features/src/agent-tools/api-docs/anchors.ts +60 -0
  7. package/packages/bundled-features/src/agent-tools/api-docs/check.ts +25 -0
  8. package/packages/bundled-features/src/agent-tools/api-docs/collect-events.ts +140 -0
  9. package/packages/bundled-features/src/agent-tools/api-docs/collect.ts +175 -0
  10. package/packages/bundled-features/src/agent-tools/api-docs/curl.ts +28 -0
  11. package/packages/bundled-features/src/agent-tools/api-docs/error-table.ts +45 -0
  12. package/packages/bundled-features/src/agent-tools/api-docs/examples.ts +43 -0
  13. package/packages/bundled-features/src/agent-tools/api-docs/generate.ts +179 -0
  14. package/packages/bundled-features/src/agent-tools/api-docs/index-json.ts +29 -0
  15. package/packages/bundled-features/src/agent-tools/api-docs/index.ts +21 -0
  16. package/packages/bundled-features/src/agent-tools/api-docs/list-parameters.ts +38 -0
  17. package/packages/bundled-features/src/agent-tools/api-docs/markdown.ts +70 -0
  18. package/packages/bundled-features/src/agent-tools/api-docs/menu-path.ts +82 -0
  19. package/packages/bundled-features/src/agent-tools/api-docs/model.ts +83 -0
  20. package/packages/bundled-features/src/agent-tools/api-docs/problems.ts +58 -0
  21. package/packages/bundled-features/src/agent-tools/api-docs/render-events.ts +76 -0
  22. package/packages/bundled-features/src/agent-tools/api-docs/render-openapi.ts +216 -0
  23. package/packages/bundled-features/src/agent-tools/api-docs/render-overview.ts +86 -0
  24. package/packages/bundled-features/src/agent-tools/api-docs/render-reference.ts +79 -0
  25. package/packages/bundled-features/src/agent-tools/api-docs/render-tokens.ts +136 -0
  26. package/packages/bundled-features/src/agent-tools/api-docs/schema-fields.ts +167 -0
  27. package/packages/bundled-features/src/agent-tools/api-docs/section-ids.ts +28 -0
  28. package/packages/bundled-features/src/agent-tools/api-docs/system-only.ts +11 -0
  29. package/packages/bundled-features/src/agent-tools/api-docs/texts/de.ts +166 -0
  30. package/packages/bundled-features/src/agent-tools/api-docs/texts/en.ts +159 -0
  31. package/packages/bundled-features/src/agent-tools/api-docs/texts/es.ts +162 -0
  32. package/packages/bundled-features/src/agent-tools/api-docs/texts/fr.ts +169 -0
  33. package/packages/bundled-features/src/agent-tools/api-docs/texts/index.ts +67 -0
  34. package/packages/bundled-features/src/agent-tools/api-docs/texts/it.ts +165 -0
  35. package/packages/bundled-features/src/agent-tools/api-docs/texts/types.ts +130 -0
  36. package/packages/bundled-features/src/agent-tools/api-docs/ui-writes.ts +81 -0
  37. package/packages/bundled-features/src/agent-tools/changes.json +24 -0
  38. package/packages/bundled-features/src/agent-tools/handler-schema.ts +45 -0
  39. package/packages/bundled-features/src/agent-tools/index.ts +24 -0
  40. package/packages/bundled-features/src/agent-tools/labels.ts +181 -0
  41. package/packages/bundled-features/src/auth-email-password/boot-rules.ts +9 -0
  42. package/packages/bundled-features/src/auth-email-password/feature.ts +6 -19
  43. package/packages/bundled-features/src/auth-email-password/validate-options.ts +20 -0
  44. package/packages/bundled-features/src/billing-foundation/boot-rules.ts +26 -0
  45. package/packages/bundled-features/src/billing-foundation/validate-options.ts +59 -46
  46. package/packages/bundled-features/src/cap-overview/boot-rules.ts +14 -0
  47. package/packages/bundled-features/src/cap-overview/feature.ts +12 -5
  48. package/packages/bundled-features/src/documents/boot-rules.ts +14 -0
  49. package/packages/bundled-features/src/documents/feature.ts +8 -4
  50. package/packages/bundled-features/src/file-derivatives/boot-rules.ts +9 -0
  51. package/packages/bundled-features/src/file-derivatives/feature.ts +6 -3
  52. package/packages/bundled-features/src/folders/boot-rules.ts +9 -0
  53. package/packages/bundled-features/src/folders/feature.ts +6 -3
  54. package/packages/bundled-features/src/helpdesk/boot-rules.ts +9 -0
  55. package/packages/bundled-features/src/{contact → helpdesk}/challenge.ts +2 -2
  56. package/packages/bundled-features/src/{contact → helpdesk}/changes.json +6 -0
  57. package/packages/bundled-features/src/{contact/client/contact-client-source.ts → helpdesk/client/helpdesk-client-source.ts} +4 -4
  58. package/packages/bundled-features/src/helpdesk/client/helpdesk-website-client.ts +29 -0
  59. package/packages/bundled-features/src/helpdesk/client/index.ts +9 -0
  60. package/packages/bundled-features/src/{contact → helpdesk}/entity.ts +35 -31
  61. package/packages/bundled-features/src/{contact → helpdesk}/feature.ts +56 -52
  62. package/packages/bundled-features/src/{contact → helpdesk}/handlers/attempts.ts +3 -3
  63. package/packages/bundled-features/src/{contact → helpdesk}/handlers/challenge.query.ts +10 -10
  64. package/packages/bundled-features/src/{contact → helpdesk}/handlers/forward-request.write.ts +25 -23
  65. package/packages/bundled-features/src/{contact → helpdesk}/handlers/mark-done.write.ts +11 -11
  66. package/packages/bundled-features/src/{contact → helpdesk}/handlers/notify-reporter-in-app.write.ts +14 -14
  67. package/packages/bundled-features/src/{contact → helpdesk}/handlers/open-count.query.ts +4 -4
  68. package/packages/bundled-features/src/{contact → helpdesk}/handlers/open-count.ts +2 -2
  69. package/packages/bundled-features/src/{contact → helpdesk}/handlers/replies.query.ts +6 -6
  70. package/packages/bundled-features/src/{contact → helpdesk}/handlers/reply.write.ts +30 -30
  71. package/packages/bundled-features/src/{contact → helpdesk}/handlers/report.write.ts +29 -29
  72. package/packages/bundled-features/src/{contact → helpdesk}/handlers/request-delivery.query.ts +40 -40
  73. package/packages/bundled-features/src/{contact → helpdesk}/handlers/request-detail.query.ts +15 -15
  74. package/packages/bundled-features/src/{contact → helpdesk}/handlers/request-list.query.ts +2 -2
  75. package/packages/bundled-features/src/{contact → helpdesk}/handlers/send-reply-mail.write.ts +24 -24
  76. package/packages/bundled-features/src/{contact → helpdesk}/handlers/send-test.write.ts +18 -14
  77. package/packages/bundled-features/src/{contact → helpdesk}/handlers/submit.write.ts +32 -31
  78. package/packages/bundled-features/src/{contact → helpdesk}/handlers/take-over-uploads.ts +5 -5
  79. package/packages/bundled-features/src/{contact → helpdesk}/i18n.ts +78 -75
  80. package/packages/bundled-features/src/helpdesk/index.ts +29 -0
  81. package/packages/bundled-features/src/{contact → helpdesk}/lib.ts +32 -28
  82. package/packages/bundled-features/src/{contact → helpdesk}/mail.ts +56 -56
  83. package/packages/bundled-features/src/{contact → helpdesk}/options.ts +18 -16
  84. package/packages/bundled-features/src/helpdesk/panels.ts +28 -0
  85. package/packages/bundled-features/src/{contact → helpdesk}/payloads.ts +33 -33
  86. package/packages/bundled-features/src/{contact → helpdesk}/screens.ts +104 -104
  87. package/packages/bundled-features/src/{contact → helpdesk}/subject.ts +3 -3
  88. package/packages/bundled-features/src/{contact → helpdesk}/user-data-hooks.ts +17 -17
  89. package/packages/bundled-features/src/helpdesk/web/constants.ts +160 -0
  90. package/packages/bundled-features/src/helpdesk/web/index.ts +29 -0
  91. package/packages/bundled-features/src/host-routing/boot-rules.ts +27 -0
  92. package/packages/bundled-features/src/host-routing/validate-options.ts +36 -27
  93. package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
  94. package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +99 -71
  95. package/packages/bundled-features/src/inbound-mail-foundation/feature.ts +2 -2
  96. package/packages/bundled-features/src/jobs/boot-rules.ts +9 -0
  97. package/packages/bundled-features/src/jobs/feature.ts +9 -4
  98. package/packages/bundled-features/src/legal-pages/boot-rules.ts +19 -0
  99. package/packages/bundled-features/src/legal-pages/feature.ts +6 -3
  100. package/packages/bundled-features/src/legal-pages/lib/validate-routes.ts +11 -5
  101. package/packages/bundled-features/src/metrics/boot-rules.ts +15 -0
  102. package/packages/bundled-features/src/metrics/validate.ts +8 -2
  103. package/packages/bundled-features/src/notes-history/boot-rules.ts +9 -0
  104. package/packages/bundled-features/src/notes-history/feature.ts +6 -3
  105. package/packages/bundled-features/src/personal-access-tokens/boot-rules.ts +9 -0
  106. package/packages/bundled-features/src/personal-access-tokens/changes.json +6 -0
  107. package/packages/bundled-features/src/personal-access-tokens/feature.ts +5 -2
  108. package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts +7 -2
  109. package/packages/bundled-features/src/personal-access-tokens/i18n.ts +6 -1
  110. package/packages/bundled-features/src/personal-access-tokens/index.ts +37 -2
  111. package/packages/bundled-features/src/personal-access-tokens/scope-events-check.ts +31 -0
  112. package/packages/bundled-features/src/personal-access-tokens/screens.ts +9 -1
  113. package/packages/bundled-features/src/personal-access-tokens/web/constants.ts +1 -0
  114. package/packages/bundled-features/src/personal-access-tokens/web/scopes.ts +14 -0
  115. package/packages/bundled-features/src/presence/boot-rules.ts +9 -0
  116. package/packages/bundled-features/src/presence/options.ts +5 -1
  117. package/packages/bundled-features/src/readiness/boot-rules.ts +14 -0
  118. package/packages/bundled-features/src/readiness/probe-boot-check.ts +8 -6
  119. package/packages/bundled-features/src/shared/assert-no-where-rule-in-ownership-write.ts +6 -4
  120. package/packages/bundled-features/src/shared/boot-rules.ts +9 -0
  121. package/packages/bundled-features/src/subscription-mollie/boot-rules.ts +19 -0
  122. package/packages/bundled-features/src/subscription-mollie/feature.ts +18 -10
  123. package/packages/bundled-features/src/tags/boot-rules.ts +9 -0
  124. package/packages/bundled-features/src/tags/feature.ts +6 -3
  125. package/packages/bundled-features/src/template-resolver/boot-rules.ts +19 -0
  126. package/packages/bundled-features/src/template-resolver/feature.ts +14 -10
  127. package/packages/bundled-features/src/tenant/boot-rules.ts +9 -0
  128. package/packages/bundled-features/src/tenant/feature.ts +5 -3
  129. package/samples/apps/marketing-demo/README.md +1 -1
  130. package/samples/apps/marketing-demo/playwright.config.ts +1 -1
  131. package/samples/apps/marketing-demo/src/app/client.tsx +3 -3
  132. package/samples/apps/marketing-demo/src/app/seed-data.ts +1 -1
  133. package/samples/apps/marketing-demo/src/app/seed.ts +4 -4
  134. package/samples/apps/marketing-demo/src/app/server.ts +3 -3
  135. package/samples/apps/marketing-demo/src/features/{helpdesk → ticketing}/feature.ts +15 -12
  136. package/samples/apps/marketing-demo/src/features/ticketing/i18n.ts +100 -0
  137. package/samples/apps/marketing-demo/src/features/{helpdesk → ticketing}/schema/ticket.ts +4 -4
  138. package/samples/apps/marketing-demo/src/features/ticketing/web/index.ts +7 -0
  139. package/samples/apps/use-all-bundled/feature-manifest.json +67 -67
  140. package/samples/apps/use-all-bundled/kumiko/migrations/0064_helpdesk-rename.rebuild.json +4 -0
  141. package/samples/apps/use-all-bundled/package.json +1 -1
  142. package/samples/apps/use-all-bundled/src/app/client.tsx +1 -1
  143. package/samples/apps/use-all-bundled/src/app/screens-feature.ts +10 -10
  144. package/samples/apps/use-all-bundled/src/run-config.ts +6 -6
  145. package/samples/recipes/api-docs/README.md +52 -0
  146. package/samples/recipes/api-docs/api-docs/de/events.md +62 -0
  147. package/samples/recipes/api-docs/api-docs/de/overview.md +100 -0
  148. package/samples/recipes/api-docs/api-docs/de/reference/tickets.md +305 -0
  149. package/samples/recipes/api-docs/api-docs/de/tokens.md +66 -0
  150. package/samples/recipes/api-docs/api-docs/en/events.md +62 -0
  151. package/samples/recipes/api-docs/api-docs/en/overview.md +100 -0
  152. package/samples/recipes/api-docs/api-docs/en/reference/tickets.md +305 -0
  153. package/samples/recipes/api-docs/api-docs/en/tokens.md +66 -0
  154. package/samples/recipes/api-docs/api-docs/index.json +371 -0
  155. package/samples/recipes/api-docs/api-docs/openapi.json +982 -0
  156. package/samples/recipes/api-docs/api-examples/ticket-close.json +21 -0
  157. package/samples/recipes/api-docs/api-examples/ticket-create.json +42 -0
  158. package/samples/recipes/api-docs/api-examples/ticket-detail.json +28 -0
  159. package/samples/recipes/api-docs/api-examples/ticket-list.json +31 -0
  160. package/samples/recipes/api-docs/api-examples/ticket-update.json +54 -0
  161. package/samples/recipes/api-docs/api-examples/webhooks/ticket-closed.json +8 -0
  162. package/samples/recipes/api-docs/api-examples/webhooks/ticket-created.json +10 -0
  163. package/samples/recipes/api-docs/kumiko.config.ts +33 -0
  164. package/samples/recipes/api-docs/package.json +14 -0
  165. package/samples/recipes/api-docs/src/feature.ts +218 -0
  166. package/samples/recipes/api-docs/tsconfig.json +22 -0
  167. package/samples/recipes/golden-path/src/feature.ts +1 -1
  168. package/samples/recipes/{contact → helpdesk}/README.md +16 -16
  169. package/samples/recipes/{contact → helpdesk}/package.json +2 -2
  170. package/samples/recipes/{contact → helpdesk}/src/feature.ts +6 -6
  171. package/packages/bundled-features/src/contact/client/contact-website-client.ts +0 -29
  172. package/packages/bundled-features/src/contact/client/index.ts +0 -9
  173. package/packages/bundled-features/src/contact/index.ts +0 -29
  174. package/packages/bundled-features/src/contact/panels.ts +0 -28
  175. package/packages/bundled-features/src/contact/web/constants.ts +0 -160
  176. package/packages/bundled-features/src/contact/web/index.ts +0 -29
  177. package/samples/apps/marketing-demo/src/features/helpdesk/i18n.ts +0 -100
  178. package/samples/apps/marketing-demo/src/features/helpdesk/web/index.ts +0 -7
  179. /package/packages/bundled-features/src/{contact → helpdesk}/handlers/access.ts +0 -0
  180. /package/packages/bundled-features/src/{contact → helpdesk}/pow.ts +0 -0
  181. /package/packages/bundled-features/src/{contact → helpdesk}/user-agent.ts +0 -0
  182. /package/samples/apps/marketing-demo/src/features/{helpdesk → ticketing}/schema/index.ts +0 -0
@@ -0,0 +1,21 @@
1
+ {
2
+ "request": {
3
+ "endpoint": "/api/write",
4
+ "body": {
5
+ "type": "ticketing: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": "ticketing: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": "ticketing: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": "ticketing: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": "ticketing: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": "ticketing: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 { patFeature, ticketingFeature } 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(), ticketingFeature, 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://ticketing.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: "ticketing: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 ticketing app 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 ticketingFeature = defineFeature("ticketing", (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: "ticketing:section.ticket", fields: ["title", "priority"] }] },
110
+ });
111
+ r.screen({
112
+ id: "close-ticket",
113
+ type: "actionForm",
114
+ handler: "ticketing:write:ticket:close",
115
+ fields: { resolution: createTextField({ personal: false, reason: "is_business_data" }) },
116
+ layout: { sections: [{ title: "ticketing:section.close", fields: ["resolution"] }] },
117
+ });
118
+ r.screen({
119
+ id: "purge-tickets",
120
+ type: "actionForm",
121
+ handler: "ticketing:write:ticket:purge",
122
+ fields: {},
123
+ layout: { sections: [] },
124
+ });
125
+
126
+ r.nav({ id: "tickets", label: "ticketing:nav:tickets", screen: "ticketing:screen:ticket-list" });
127
+ r.nav({ id: "settings", label: "ticketing:nav:settings" });
128
+ r.nav({
129
+ id: "api-tokens",
130
+ label: "ticketing:nav:api-tokens",
131
+ parent: "ticketing:nav:settings",
132
+ screen: "personal-access-tokens:screen:api-tokens",
133
+ });
134
+
135
+ r.translations({
136
+ keys: {
137
+ "ticketing:nav:tickets": { en: "Tickets", de: "Tickets" },
138
+ "ticketing:nav:settings": { en: "Settings", de: "Einstellungen" },
139
+ "ticketing:nav:api-tokens": { en: "API tokens", de: "API-Tokens" },
140
+ "ticketing:section.ticket": { en: "Ticket", de: "Ticket" },
141
+ "ticketing:section.close": { en: "Close ticket", de: "Ticket schließen" },
142
+ "ticketing:entity:ticket:field:title": { en: "Title", de: "Titel" },
143
+ "ticketing:entity:ticket:field:status": { en: "Status", de: "Status" },
144
+ "ticketing:entity:ticket:field:priority": { en: "Priority", de: "Priorität" },
145
+ "ticketing:write:ticket:create:title": { en: "Create ticket", de: "Ticket anlegen" },
146
+ "ticketing:write:ticket:create:description": {
147
+ en: "Opens a new ticket.",
148
+ de: "Legt ein neues Ticket an.",
149
+ },
150
+ "ticketing:write:ticket:update:title": { en: "Update ticket", de: "Ticket ändern" },
151
+ "ticketing: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
+ "ticketing:query:ticket:list:title": { en: "List tickets", de: "Tickets auflisten" },
156
+ "ticketing:query:ticket:list:description": {
157
+ en: "Lists tickets, newest first.",
158
+ de: "Listet Tickets, neueste zuerst.",
159
+ },
160
+ "ticketing:query:ticket:detail:title": { en: "Show ticket", de: "Ticket anzeigen" },
161
+ "ticketing:query:ticket:detail:description": {
162
+ en: "Returns one ticket.",
163
+ de: "Liefert ein Ticket.",
164
+ },
165
+ "ticketing:write:ticket:close:title": { en: "Close ticket", de: "Ticket schließen" },
166
+ "ticketing: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
+ "ticketing:write:ticket:close:field:id": { en: "Ticket", de: "Ticket" },
171
+ "ticketing:write:ticket:close:field:resolution": { en: "Resolution", de: "Lösung" },
172
+ "ticketing:write:ticket:purge:title": { en: "Purge tickets", de: "Tickets bereinigen" },
173
+ "ticketing:write:ticket:purge:description": {
174
+ en: "Removes tickets that were closed long ago.",
175
+ de: "Entfernt Tickets, die lange geschlossen sind.",
176
+ },
177
+ "ticketing:write:ticket:purge:field:olderThanDays": {
178
+ en: "Closed longer than (days)",
179
+ de: "Länger geschlossen als (Tage)",
180
+ },
181
+ "ticketing:entity:ticket": { en: "ticket", de: "Ticket" },
182
+ "ticketing:entity:ticket:field:id": { en: "Ticket ID", de: "Ticket-ID" },
183
+ "ticketing: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
+ "ticketing:webhook:ticket-closed:field:id": {
188
+ en: "ID of the closed ticket",
189
+ de: "ID des geschlossenen Tickets",
190
+ },
191
+ "ticketing:webhook:ticket-closed:field:resolution": {
192
+ en: "How the ticket was resolved",
193
+ de: "Wie das Ticket gelöst wurde",
194
+ },
195
+ "ticketing: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", "ticketing:ticket-closed"],
208
+ read: ["ticketing:query:ticket:*"],
209
+ write: [
210
+ "ticketing:write:ticket:create",
211
+ "ticketing:write:ticket:update",
212
+ "ticketing: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
+ }
@@ -18,7 +18,7 @@ export const ticketEntity = createEntity({
18
18
  },
19
19
  });
20
20
 
21
- export const helpdeskFeature = defineFeature("helpdesk", (r) => {
21
+ export const ticketingFeature = defineFeature("ticketing", (r) => {
22
22
  const { table: ticketTable, executor: ticketExecutor } = createEntityExecutor(
23
23
  "ticket",
24
24
  ticketEntity,
@@ -1,6 +1,6 @@
1
- # Recipe: contact
1
+ # Recipe: helpdesk
2
2
 
3
- Public contact form backend. The `contact` bundled feature stores questions, contact
3
+ Public contact form backend. The `helpdesk` bundled feature stores questions, contact
4
4
  requests and problem reports from website visitors and notifies every SystemAdmin (mail,
5
5
  Telegram only when the app turns it on). The notification names only the kind, the app and a link into the inbox:
6
6
  no name, address, phone, subject or message. Telegram is a third party where nothing can be
@@ -10,43 +10,43 @@ SystemAdmins reply from the admin. Phone is off and Telegram is not mounted unle
10
10
  turns them on (`fields.phone`, `telegram: true`).
11
11
 
12
12
  **What the recipe demonstrates:**
13
- - Mounting `createContactFeature` with its companions (delivery, user-data-rights, files)
14
- - The anonymous flow: `contact:query:challenge` hands out a proof-of-work challenge,
15
- `contact:write:submit` verifies it; spam gets the same 200 body and stores nothing
16
- - The browser client at `GET /contact/client.js` (`window.KumikoContact.load()` / `submit()`)
13
+ - Mounting `createHelpdeskFeature` with its companions (delivery, user-data-rights, files)
14
+ - The anonymous flow: `helpdesk:query:challenge` hands out a proof-of-work challenge,
15
+ `helpdesk:write:submit` verifies it; spam gets the same 200 body and stores nothing
16
+ - The browser client at `GET /helpdesk/client.js` (`window.KumikoHelpdesk.load()` / `submit()`)
17
17
 
18
18
  ## Layout
19
19
 
20
20
  ```
21
- samples/recipes/contact/
21
+ samples/recipes/helpdesk/
22
22
  ├── package.json
23
23
  ├── README.md
24
24
  └── src/
25
- ├── feature.ts # createContactFeature options
25
+ ├── feature.ts # createHelpdeskFeature options
26
26
  └── __tests__/
27
27
  └── feature.integration.test.ts # challenge query + client route
28
28
  ```
29
29
 
30
30
  The behavior (submit, silent drops, replies, Telegram, GDPR export and erasure, retention) is
31
31
  covered by the integration tests next to the feature in
32
- `packages/bundled-features/src/contact/__tests__/`.
32
+ `packages/bundled-features/src/helpdesk/__tests__/`.
33
33
 
34
34
  ## Run tests
35
35
 
36
36
  ```bash
37
- bun test --config=bunfig.integration.toml samples/recipes/contact
37
+ bun test --config=bunfig.integration.toml samples/recipes/helpdesk
38
38
  ```
39
39
 
40
40
  ## Integration into a real app
41
41
 
42
- 1. Mount `createContactFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
42
+ 1. Mount `createHelpdeskFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
43
43
  `files` with a file provider and `config`.
44
44
  2. Run `kumiko schema generate` (new tables, plus the delivery `idempotency_key` column).
45
- 3. SystemAdmins set `contact:config:reply-to` in the admin.
46
- 4. Embed `/contact/client.js` on the website; the form is yours. A website served by another
47
- server can serve the same script from `CONTACT_CLIENT_SOURCE` and type its calls with
48
- `ContactWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/contact/client`.
45
+ 3. SystemAdmins set `helpdesk:config:reply-to` in the admin.
46
+ 4. Embed `/helpdesk/client.js` on the website; the form is yours. A website served by another
47
+ server can serve the same script from `HELPDESK_CLIENT_SOURCE` and type its calls with
48
+ `HelpdeskWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/helpdesk/client`.
49
49
 
50
50
  Telegram is optional and off by default: notifications go by mail to SystemAdmins only. An app
51
51
  that turns it on (`telegram: true`) also mounts `channel-telegram` and `secrets` for the bot
52
- token, and SystemAdmins set `contact:config:telegram-chat`.
52
+ token, and SystemAdmins set `helpdesk:config:telegram-chat`.
@@ -1,6 +1,6 @@
1
1
  {
2
- "name": "@cosmicdrift/kumiko-sample-contact",
3
- "description": "Public contact form backend: the contact bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client.",
2
+ "name": "@cosmicdrift/kumiko-sample-helpdesk",
3
+ "description": "Public contact form backend: the helpdesk bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client.",
4
4
  "private": true,
5
5
  "dependencies": {
6
6
  "@cosmicdrift/kumiko-bundled-features": "workspace:*",
@@ -1,4 +1,4 @@
1
- // Contact sample
1
+ // Helpdesk sample
2
2
  //
3
3
  // A public website form (question, contact request, problem report) that lands with the
4
4
  // SystemAdmins: mail, optional Telegram, a copy to the sender. Spam is handled without a
@@ -6,9 +6,9 @@
6
6
  // and per-email rate limits. Rejected submits answer 200 with the normal body.
7
7
  //
8
8
  // The website embeds the anonymous client the feature serves itself:
9
- // <script src="https://api.example.com/contact/client.js"></script>
10
- // const { kinds, phone } = await window.KumikoContact.load();
11
- // const result = await window.KumikoContact.submit({ kind, name, email, message, locale });
9
+ // <script src="https://api.example.com/helpdesk/client.js"></script>
10
+ // const { kinds, phone } = await window.KumikoHelpdesk.load();
11
+ // const result = await window.KumikoHelpdesk.submit({ kind, name, email, message, locale });
12
12
  // // result.kind: "sent" | "rate-limited" (retryAfterSeconds) | "failed"
13
13
  //
14
14
  // Prerequisites the app wires itself:
@@ -17,9 +17,9 @@
17
17
  // - a file provider, because the entities carry file fields
18
18
  // - `kumiko schema generate` for the new tables
19
19
 
20
- import { createContactFeature } from "@cosmicdrift/kumiko-bundled-features/contact";
20
+ import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk";
21
21
 
22
- export const contactFeature = createContactFeature({
22
+ export const helpdeskFeature = createHelpdeskFeature({
23
23
  appName: "Sample App",
24
24
  fields: { phone: "optional" },
25
25
  // Lowered only to keep the sample test fast; the default (19 bits, 3 seconds) suits production.
@@ -1,29 +0,0 @@
1
- import type * as z from "zod";
2
- import type { ContactSubmitSchema } from "../payloads.ts";
3
- import type { CONTACT_WEBSITE_KINDS, ContactPhoneMode } from "../web/constants.ts";
4
-
5
- export type ContactWebsiteKind = (typeof CONTACT_WEBSITE_KINDS)[number];
6
-
7
- export type ContactWebsiteFormOptions = {
8
- readonly phone: ContactPhoneMode;
9
- readonly kinds: readonly ContactWebsiteKind[];
10
- };
11
-
12
- // The client adds challenge and nonce itself and falls back to the page language for locale.
13
- export type ContactWebsiteSubmitFields = Omit<
14
- z.input<typeof ContactSubmitSchema>,
15
- "challenge" | "nonce" | "locale"
16
- > & { readonly locale?: z.input<typeof ContactSubmitSchema>["locale"] };
17
-
18
- export type ContactWebsiteSubmitResult =
19
- | { readonly kind: "sent" }
20
- | { readonly kind: "rate-limited"; readonly retryAfterSeconds?: number }
21
- | { readonly kind: "failed" };
22
-
23
- export type ContactWebsiteClient = {
24
- load(): Promise<ContactWebsiteFormOptions>;
25
- submit(fields: ContactWebsiteSubmitFields): Promise<ContactWebsiteSubmitResult>;
26
- };
27
-
28
- // Registered by CONTACT_CLIENT_SOURCE as window.KumikoContact.
29
- export type ContactWebsiteWindow = { readonly KumikoContact?: ContactWebsiteClient };
@@ -1,9 +0,0 @@
1
- export { CONTACT_CLIENT_SOURCE } from "./contact-client-source.ts";
2
- export type {
3
- ContactWebsiteClient,
4
- ContactWebsiteFormOptions,
5
- ContactWebsiteKind,
6
- ContactWebsiteSubmitFields,
7
- ContactWebsiteSubmitResult,
8
- ContactWebsiteWindow,
9
- } from "./contact-website-client.ts";