@cosmicdrift/kumiko-framework 0.412.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 (52) hide show
  1. package/agents/boot-rules.md +343 -0
  2. package/agents/examples/api-docs.md +79 -71
  3. package/agents/examples/golden-path.md +11 -11
  4. package/agents/examples/{contact.md → helpdesk.md} +31 -31
  5. package/agents/examples.md +1 -1
  6. package/agents/features-index.md +2 -2
  7. package/agents/features.md +16 -16
  8. package/dist/engine/boot-validator/boot-report.d.ts +3 -0
  9. package/dist/engine/boot-validator/boot-report.js +2 -2
  10. package/dist/engine/boot-validator/boot-rules.d.ts +570 -0
  11. package/dist/engine/boot-validator/boot-rules.js +20 -0
  12. package/dist/engine/boot-validator/definition-config-events-jobs-rules.d.ts +77 -0
  13. package/dist/engine/boot-validator/definition-config-events-jobs-rules.js +77 -0
  14. package/dist/engine/boot-validator/definition-events-rules.d.ts +42 -0
  15. package/dist/engine/boot-validator/definition-events-rules.js +42 -0
  16. package/dist/engine/boot-validator/definition-feature-rules.d.ts +42 -0
  17. package/dist/engine/boot-validator/definition-feature-rules.js +42 -0
  18. package/dist/engine/boot-validator/definition-field-factories-rules.d.ts +17 -0
  19. package/dist/engine/boot-validator/definition-field-factories-rules.js +17 -0
  20. package/dist/engine/boot-validator/definition-handlers-rules.d.ts +72 -0
  21. package/dist/engine/boot-validator/definition-handlers-rules.js +72 -0
  22. package/dist/engine/boot-validator/definition-ownership-from-rules.d.ts +27 -0
  23. package/dist/engine/boot-validator/definition-ownership-from-rules.js +27 -0
  24. package/dist/engine/boot-validator/definition-probes-rules.d.ts +47 -0
  25. package/dist/engine/boot-validator/definition-probes-rules.js +47 -0
  26. package/dist/engine/boot-validator/definition-role-assignment-rules.d.ts +27 -0
  27. package/dist/engine/boot-validator/definition-role-assignment-rules.js +27 -0
  28. package/dist/engine/boot-validator/definition-ui-extensions-rules.d.ts +197 -0
  29. package/dist/engine/boot-validator/definition-ui-extensions-rules.js +197 -0
  30. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +32 -0
  31. package/dist/engine/boot-validator/definition-webhook-events-rules.js +32 -0
  32. package/dist/engine/define-feature.js +26 -9
  33. package/dist/engine/define-handler.js +8 -4
  34. package/dist/engine/definition-violations.d.ts +14 -0
  35. package/dist/engine/definition-violations.js +71 -0
  36. package/dist/engine/entity-handlers.js +39 -13
  37. package/dist/engine/event-def.js +32 -12
  38. package/dist/engine/factories.js +16 -5
  39. package/dist/engine/feature-config-events-jobs.js +63 -27
  40. package/dist/engine/feature-entity-handlers.js +15 -6
  41. package/dist/engine/feature-probes.js +29 -9
  42. package/dist/engine/feature-ui-extensions.js +178 -92
  43. package/dist/engine/object-form.js +8 -2
  44. package/dist/engine/ownership.js +17 -5
  45. package/dist/engine/role-assignment.js +17 -5
  46. package/dist/engine/webhook-events.js +20 -6
  47. package/dist/files/file-routes.js +1 -1
  48. package/dist/schema-cli/shared.d.ts +11 -0
  49. package/dist/schema-cli/shared.js +37 -3
  50. package/dist/schema-cli/validate-command.js +10 -3
  51. package/package.json +3 -3
  52. package/src/changes.json +12 -0
@@ -8,7 +8,7 @@ API documentation for personal access tokens: recorded examples, kumiko api-docs
8
8
 
9
9
  # API docs
10
10
 
11
- API documentation for personal access tokens, generated from the app itself. A helpdesk
11
+ API documentation for personal access tokens, generated from the app itself. A ticketing
12
12
  feature exposes its ticket handlers through token scopes; `kumiko api-docs` turns the
13
13
  registry, the translations and recorded requests into Markdown pages, an OpenAPI file and
14
14
  an `index.json` that a website or an agent can read.
@@ -16,7 +16,7 @@ an `index.json` that a website or an agent can read.
16
16
  ## What it shows
17
17
 
18
18
  - **Scopes decide the content.** Only handlers that a scope of the token feature reaches
19
- appear. `helpdesk:write:ticket:purge` is reachable from a screen but in no scope, so it is
19
+ appear. `ticketing:write:ticket:purge` is reachable from a screen but in no scope, so it is
20
20
  listed under `apiDocs.uiOnlyWrites` with a reason; without that entry the generator reports it.
21
21
  - **Texts come from the feature.** Titles, descriptions and field labels per locale use the
22
22
  keys `<handler qn>:title`, `:description` and `:field:<name>`; the German pages need the
@@ -52,7 +52,7 @@ those two files differ from a real run of the command.
52
52
 
53
53
  ```
54
54
  kumiko.config.ts features and the apiDocs block
55
- src/feature.ts helpdesk feature and the token feature with its scopes
55
+ src/feature.ts ticketing feature and the token feature with its scopes
56
56
  src/__tests__/api-docs.integration.test.ts mints a token, records the examples, checks scope limits
57
57
  src/__tests__/api-docs.golden.test.ts generator output equals api-docs/
58
58
  api-examples/ recorded requests and responses
@@ -67,19 +67,19 @@ api-docs/ the golden output
67
67
  import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
68
68
  import { defineAppConfig } from "@cosmicdrift/kumiko-framework/config";
69
69
  import { localeDe } from "@cosmicdrift/kumiko-locale-de";
70
- import { helpdeskFeature, patFeature } from "./src/feature";
70
+ import { patFeature, ticketingFeature } from "./src/feature";
71
71
 
72
72
  const PURGE_REASON =
73
73
  "Purging is an admin chore that stays in the app and is never offered to API clients.";
74
74
 
75
75
  export default defineAppConfig({
76
- features: [createAuthFoundationFeature(), helpdeskFeature, patFeature(), localeDe()],
76
+ features: [createAuthFoundationFeature(), ticketingFeature, patFeature(), localeDe()],
77
77
  includeBundled: true,
78
78
  client: { entries: ["src/client.tsx"] },
79
79
  ports: { dev: 4520, e2e: 4521, infra: { postgres: 15520 } },
80
80
  apiDocs: {
81
81
  appName: "Helpdesk",
82
- baseUrl: "https://helpdesk.example.com",
82
+ baseUrl: "https://ticketing.example.com",
83
83
  locales: ["en", "de"],
84
84
  planNote: {
85
85
  en: "API tokens are included in every Helpdesk plan.",
@@ -91,7 +91,7 @@ export default defineAppConfig({
91
91
  },
92
92
  uiOnlyWrites: [
93
93
  {
94
- pattern: "helpdesk:write:ticket:purge",
94
+ pattern: "ticketing:write:ticket:purge",
95
95
  reason: PURGE_REASON,
96
96
  },
97
97
  ],
@@ -262,7 +262,7 @@ import {
262
262
  unsafePushTables,
263
263
  } from "@cosmicdrift/kumiko-testing/stack";
264
264
  import { z } from "zod";
265
- import { helpdeskFeature, patFeature } from "../feature";
265
+ import { patFeature, ticketingFeature } from "../feature";
266
266
 
267
267
  const TENANT: TenantId = testTenantId(1);
268
268
  const EXAMPLES_DIR = join(import.meta.dir, "../../api-examples");
@@ -287,7 +287,7 @@ beforeAll(async () => {
287
287
  createTenantFeature(),
288
288
  createAuthEmailPasswordFeature(),
289
289
  createAuthFoundationFeature(),
290
- helpdeskFeature,
290
+ ticketingFeature,
291
291
  patFeature(),
292
292
  ],
293
293
  authConfig: {
@@ -339,7 +339,7 @@ async function denied(token: string, type: string, payload: unknown) {
339
339
  return { status: response.status, body: await response.json() };
340
340
  }
341
341
 
342
- describe("helpdesk API with a personal access token", () => {
342
+ describe("ticketing API with a personal access token", () => {
343
343
  test("create, list, detail, update and close a ticket", async () => {
344
344
  const token = await mintToken(["tickets:write"]);
345
345
  const record = (
@@ -356,17 +356,17 @@ describe("helpdesk API with a personal access token", () => {
356
356
  token,
357
357
  });
358
358
 
359
- const created = await record("ticket-create", "/api/write", "helpdesk:write:ticket:create", {
359
+ const created = await record("ticket-create", "/api/write", "ticketing:write:ticket:create", {
360
360
  title: "Printer is on fire",
361
361
  priority: "high",
362
362
  });
363
363
  expect(created.status).toBe(200);
364
364
  const id = CreatedSchema.parse(created.body).data.id;
365
365
 
366
- const listed = await record("ticket-list", "/api/query", "helpdesk:query:ticket:list", {});
366
+ const listed = await record("ticket-list", "/api/query", "ticketing:query:ticket:list", {});
367
367
  expect(ListedSchema.parse(listed.body).data.rows.map((row) => row.id)).toContain(id);
368
368
 
369
- const detail = await record("ticket-detail", "/api/query", "helpdesk:query:ticket:detail", {
369
+ const detail = await record("ticket-detail", "/api/query", "ticketing:query:ticket:detail", {
370
370
  id,
371
371
  });
372
372
  expect(DetailSchema.parse(detail.body).data).toMatchObject({
@@ -375,35 +375,35 @@ describe("helpdesk API with a personal access token", () => {
375
375
  priority: "high",
376
376
  });
377
377
 
378
- const updated = await record("ticket-update", "/api/write", "helpdesk:write:ticket:update", {
378
+ const updated = await record("ticket-update", "/api/write", "ticketing:write:ticket:update", {
379
379
  id,
380
380
  version: 1,
381
381
  changes: { priority: "normal" },
382
382
  });
383
383
  expect(updated.status).toBe(200);
384
384
 
385
- const closed = await record("ticket-close", "/api/write", "helpdesk:write:ticket:close", {
385
+ const closed = await record("ticket-close", "/api/write", "ticketing:write:ticket:close", {
386
386
  id,
387
387
  resolution: "Replaced the cartridge",
388
388
  });
389
389
  expect(closed.status).toBe(200);
390
- const after = await stack.http.queryOk("helpdesk:query:ticket:detail", { id }, actor);
390
+ const after = await stack.http.queryOk("ticketing:query:ticket:detail", { id }, actor);
391
391
  expect(TicketRowSchema.parse(after)).toMatchObject({ status: "closed", priority: "normal" });
392
392
  });
393
393
 
394
394
  test("webhook payloads built from the appended events satisfy their contracts and are recorded", async () => {
395
395
  const created = await stack.http.writeOk<{ id: string }>(
396
- "helpdesk:write:ticket:create",
396
+ "ticketing:write:ticket:create",
397
397
  { title: "Scanner jams", priority: "low" },
398
398
  actor,
399
399
  );
400
400
  await stack.http.writeOk(
401
- "helpdesk:write:ticket:update",
401
+ "ticketing:write:ticket:update",
402
402
  { id: created.id, version: 1, changes: { priority: "high" } },
403
403
  actor,
404
404
  );
405
405
  await stack.http.writeOk(
406
- "helpdesk:write:ticket:close",
406
+ "ticketing:write:ticket:close",
407
407
  { id: created.id, resolution: "Replaced the roller" },
408
408
  actor,
409
409
  );
@@ -447,10 +447,10 @@ describe("helpdesk API with a personal access token", () => {
447
447
  expect(Object.keys(updatedWebhook.payload).sort()).toEqual(["changes", "id", "previous"]);
448
448
  expect(updatedWebhook.payload["changes"]).toEqual({ priority: "high" });
449
449
 
450
- const closedContract = stack.registry.getWebhookEventContract("helpdesk:ticket-closed");
450
+ const closedContract = stack.registry.getWebhookEventContract("ticketing:ticket-closed");
451
451
  const closedEvent = stored.find((event) => event.type.endsWith("ticket-closed"));
452
452
  if (closedContract === undefined || closedEvent === undefined) {
453
- throw new Error("helpdesk:ticket-closed has no contract or no appended event");
453
+ throw new Error("ticketing:ticket-closed has no contract or no appended event");
454
454
  }
455
455
  const recordedClosed = await recordWebhookExample({
456
456
  name: "ticket-closed",
@@ -462,17 +462,25 @@ describe("helpdesk API with a personal access token", () => {
462
462
  });
463
463
 
464
464
  test("a read-only token cannot create a ticket", async () => {
465
- const result = await denied(await mintToken(["tickets:read"]), "helpdesk:write:ticket:create", {
466
- title: "Nope",
467
- });
465
+ const result = await denied(
466
+ await mintToken(["tickets:read"]),
467
+ "ticketing:write:ticket:create",
468
+ {
469
+ title: "Nope",
470
+ },
471
+ );
468
472
  expect(result.status).toBe(403);
469
473
  expect(result.body).toMatchObject({ error: { code: "access_denied" } });
470
474
  });
471
475
 
472
476
  test("a write token cannot reach the UI-only purge", async () => {
473
- const result = await denied(await mintToken(["tickets:write"]), "helpdesk:write:ticket:purge", {
474
- olderThanDays: 30,
475
- });
477
+ const result = await denied(
478
+ await mintToken(["tickets:write"]),
479
+ "ticketing:write:ticket:purge",
480
+ {
481
+ olderThanDays: 30,
482
+ },
483
+ );
476
484
  expect(result.status).toBe(403);
477
485
  });
478
486
  });
@@ -481,7 +489,7 @@ describe("helpdesk API with a personal access token", () => {
481
489
  ### src/feature.ts
482
490
 
483
491
  ```ts
484
- // API docs sample: a helpdesk whose ticket handlers are reachable with a personal access token.
492
+ // API docs sample: a ticketing app whose ticket handlers are reachable with a personal access token.
485
493
  // Every handler a token scope reaches needs a description and, per locale, a title, description
486
494
  // and field labels; `kumiko api-docs` turns them into the pages under api-docs/.
487
495
 
@@ -511,7 +519,7 @@ export const ticketEntity = createEntity({
511
519
 
512
520
  const ticketAccess = { roles: ["Admin", "User"] } as const;
513
521
 
514
- export const helpdeskFeature = defineFeature("helpdesk", (r) => {
522
+ export const ticketingFeature = defineFeature("ticketing", (r) => {
515
523
  const { table: ticketTable, executor: ticketExecutor } = createEntityExecutor(
516
524
  "ticket",
517
525
  ticketEntity,
@@ -589,93 +597,93 @@ export const helpdeskFeature = defineFeature("helpdesk", (r) => {
589
597
  id: "ticket-edit",
590
598
  type: "entityEdit",
591
599
  entity: "ticket",
592
- layout: { sections: [{ title: "helpdesk:section.ticket", fields: ["title", "priority"] }] },
600
+ layout: { sections: [{ title: "ticketing:section.ticket", fields: ["title", "priority"] }] },
593
601
  });
594
602
  r.screen({
595
603
  id: "close-ticket",
596
604
  type: "actionForm",
597
- handler: "helpdesk:write:ticket:close",
605
+ handler: "ticketing:write:ticket:close",
598
606
  fields: { resolution: createTextField({ personal: false, reason: "is_business_data" }) },
599
- layout: { sections: [{ title: "helpdesk:section.close", fields: ["resolution"] }] },
607
+ layout: { sections: [{ title: "ticketing:section.close", fields: ["resolution"] }] },
600
608
  });
601
609
  r.screen({
602
610
  id: "purge-tickets",
603
611
  type: "actionForm",
604
- handler: "helpdesk:write:ticket:purge",
612
+ handler: "ticketing:write:ticket:purge",
605
613
  fields: {},
606
614
  layout: { sections: [] },
607
615
  });
608
616
 
609
- r.nav({ id: "tickets", label: "helpdesk:nav:tickets", screen: "helpdesk:screen:ticket-list" });
610
- r.nav({ id: "settings", label: "helpdesk:nav:settings" });
617
+ r.nav({ id: "tickets", label: "ticketing:nav:tickets", screen: "ticketing:screen:ticket-list" });
618
+ r.nav({ id: "settings", label: "ticketing:nav:settings" });
611
619
  r.nav({
612
620
  id: "api-tokens",
613
- label: "helpdesk:nav:api-tokens",
614
- parent: "helpdesk:nav:settings",
621
+ label: "ticketing:nav:api-tokens",
622
+ parent: "ticketing:nav:settings",
615
623
  screen: "personal-access-tokens:screen:api-tokens",
616
624
  });
617
625
 
618
626
  r.translations({
619
627
  keys: {
620
- "helpdesk:nav:tickets": { en: "Tickets", de: "Tickets" },
621
- "helpdesk:nav:settings": { en: "Settings", de: "Einstellungen" },
622
- "helpdesk:nav:api-tokens": { en: "API tokens", de: "API-Tokens" },
623
- "helpdesk:section.ticket": { en: "Ticket", de: "Ticket" },
624
- "helpdesk:section.close": { en: "Close ticket", de: "Ticket schließen" },
625
- "helpdesk:entity:ticket:field:title": { en: "Title", de: "Titel" },
626
- "helpdesk:entity:ticket:field:status": { en: "Status", de: "Status" },
627
- "helpdesk:entity:ticket:field:priority": { en: "Priority", de: "Priorität" },
628
- "helpdesk:write:ticket:create:title": { en: "Create ticket", de: "Ticket anlegen" },
629
- "helpdesk:write:ticket:create:description": {
628
+ "ticketing:nav:tickets": { en: "Tickets", de: "Tickets" },
629
+ "ticketing:nav:settings": { en: "Settings", de: "Einstellungen" },
630
+ "ticketing:nav:api-tokens": { en: "API tokens", de: "API-Tokens" },
631
+ "ticketing:section.ticket": { en: "Ticket", de: "Ticket" },
632
+ "ticketing:section.close": { en: "Close ticket", de: "Ticket schließen" },
633
+ "ticketing:entity:ticket:field:title": { en: "Title", de: "Titel" },
634
+ "ticketing:entity:ticket:field:status": { en: "Status", de: "Status" },
635
+ "ticketing:entity:ticket:field:priority": { en: "Priority", de: "Priorität" },
636
+ "ticketing:write:ticket:create:title": { en: "Create ticket", de: "Ticket anlegen" },
637
+ "ticketing:write:ticket:create:description": {
630
638
  en: "Opens a new ticket.",
631
639
  de: "Legt ein neues Ticket an.",
632
640
  },
633
- "helpdesk:write:ticket:update:title": { en: "Update ticket", de: "Ticket ändern" },
634
- "helpdesk:write:ticket:update:description": {
641
+ "ticketing:write:ticket:update:title": { en: "Update ticket", de: "Ticket ändern" },
642
+ "ticketing:write:ticket:update:description": {
635
643
  en: "Changes the title or the priority of a ticket.",
636
644
  de: "Ändert Titel oder Priorität eines Tickets.",
637
645
  },
638
- "helpdesk:query:ticket:list:title": { en: "List tickets", de: "Tickets auflisten" },
639
- "helpdesk:query:ticket:list:description": {
646
+ "ticketing:query:ticket:list:title": { en: "List tickets", de: "Tickets auflisten" },
647
+ "ticketing:query:ticket:list:description": {
640
648
  en: "Lists tickets, newest first.",
641
649
  de: "Listet Tickets, neueste zuerst.",
642
650
  },
643
- "helpdesk:query:ticket:detail:title": { en: "Show ticket", de: "Ticket anzeigen" },
644
- "helpdesk:query:ticket:detail:description": {
651
+ "ticketing:query:ticket:detail:title": { en: "Show ticket", de: "Ticket anzeigen" },
652
+ "ticketing:query:ticket:detail:description": {
645
653
  en: "Returns one ticket.",
646
654
  de: "Liefert ein Ticket.",
647
655
  },
648
- "helpdesk:write:ticket:close:title": { en: "Close ticket", de: "Ticket schließen" },
649
- "helpdesk:write:ticket:close:description": {
656
+ "ticketing:write:ticket:close:title": { en: "Close ticket", de: "Ticket schließen" },
657
+ "ticketing:write:ticket:close:description": {
650
658
  en: "Closes a ticket and records how it was resolved.",
651
659
  de: "Schließt ein Ticket und hält fest, wie es gelöst wurde.",
652
660
  },
653
- "helpdesk:write:ticket:close:field:id": { en: "Ticket", de: "Ticket" },
654
- "helpdesk:write:ticket:close:field:resolution": { en: "Resolution", de: "Lösung" },
655
- "helpdesk:write:ticket:purge:title": { en: "Purge tickets", de: "Tickets bereinigen" },
656
- "helpdesk:write:ticket:purge:description": {
661
+ "ticketing:write:ticket:close:field:id": { en: "Ticket", de: "Ticket" },
662
+ "ticketing:write:ticket:close:field:resolution": { en: "Resolution", de: "Lösung" },
663
+ "ticketing:write:ticket:purge:title": { en: "Purge tickets", de: "Tickets bereinigen" },
664
+ "ticketing:write:ticket:purge:description": {
657
665
  en: "Removes tickets that were closed long ago.",
658
666
  de: "Entfernt Tickets, die lange geschlossen sind.",
659
667
  },
660
- "helpdesk:write:ticket:purge:field:olderThanDays": {
668
+ "ticketing:write:ticket:purge:field:olderThanDays": {
661
669
  en: "Closed longer than (days)",
662
670
  de: "Länger geschlossen als (Tage)",
663
671
  },
664
- "helpdesk:entity:ticket": { en: "ticket", de: "Ticket" },
665
- "helpdesk:entity:ticket:field:id": { en: "Ticket ID", de: "Ticket-ID" },
666
- "helpdesk:webhook:ticket-closed:description": {
672
+ "ticketing:entity:ticket": { en: "ticket", de: "Ticket" },
673
+ "ticketing:entity:ticket:field:id": { en: "Ticket ID", de: "Ticket-ID" },
674
+ "ticketing:webhook:ticket-closed:description": {
667
675
  en: "A ticket was closed and its resolution recorded.",
668
676
  de: "Ein Ticket wurde geschlossen und seine Lösung festgehalten.",
669
677
  },
670
- "helpdesk:webhook:ticket-closed:field:id": {
678
+ "ticketing:webhook:ticket-closed:field:id": {
671
679
  en: "ID of the closed ticket",
672
680
  de: "ID des geschlossenen Tickets",
673
681
  },
674
- "helpdesk:webhook:ticket-closed:field:resolution": {
682
+ "ticketing:webhook:ticket-closed:field:resolution": {
675
683
  en: "How the ticket was resolved",
676
684
  de: "Wie das Ticket gelöst wurde",
677
685
  },
678
- "helpdesk:entity:__action-form__:field:resolution": { en: "Resolution", de: "Lösung" },
686
+ "ticketing:entity:__action-form__:field:resolution": { en: "Resolution", de: "Lösung" },
679
687
  },
680
688
  });
681
689
  });
@@ -687,12 +695,12 @@ export function patFeature() {
687
695
  scopes: {
688
696
  tickets: {
689
697
  label: "Tickets",
690
- events: ["ticket.created", "helpdesk:ticket-closed"],
691
- read: ["helpdesk:query:ticket:*"],
698
+ events: ["ticket.created", "ticketing:ticket-closed"],
699
+ read: ["ticketing:query:ticket:*"],
692
700
  write: [
693
- "helpdesk:write:ticket:create",
694
- "helpdesk:write:ticket:update",
695
- "helpdesk:write:ticket:close",
701
+ "ticketing:write:ticket:create",
702
+ "ticketing:write:ticket:update",
703
+ "ticketing:write:ticket:close",
696
704
  ],
697
705
  },
698
706
  },
@@ -45,7 +45,7 @@ src/__tests__/feature.integration.test.ts write → read back, access, not fou
45
45
  import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
46
46
  import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
47
47
  import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
48
- import { helpdeskFeature } from "../feature";
48
+ import { ticketingFeature } from "../feature";
49
49
 
50
50
  type TicketRow = { id: string; title: string; isClosed: boolean };
51
51
 
@@ -55,7 +55,7 @@ let admin = createTestUser({ roles: ["Admin"], tenantId: testTenantId(nextTenant
55
55
  let agent = createTestUser({ id: 2, roles: ["User"], tenantId: testTenantId(nextTenant) });
56
56
 
57
57
  beforeAll(async () => {
58
- stack = await setupTestStack({ features: [helpdeskFeature], systemHooks: [] });
58
+ stack = await setupTestStack({ features: [ticketingFeature], systemHooks: [] });
59
59
  });
60
60
 
61
61
  afterAll(async () => {
@@ -71,7 +71,7 @@ beforeEach(() => {
71
71
 
72
72
  async function openTicket(title: string): Promise<string> {
73
73
  const created = await stack.http.writeOk<{ id: string }>(
74
- "helpdesk:write:ticket:create",
74
+ "ticketing:write:ticket:create",
75
75
  { title },
76
76
  agent,
77
77
  );
@@ -79,7 +79,7 @@ async function openTicket(title: string): Promise<string> {
79
79
  }
80
80
 
81
81
  async function readTicket(id: string): Promise<TicketRow> {
82
- return stack.http.queryOk<TicketRow>("helpdesk:query:ticket:detail", { id }, agent);
82
+ return stack.http.queryOk<TicketRow>("ticketing:query:ticket:detail", { id }, agent);
83
83
  }
84
84
 
85
85
  describe("golden path: ticket", () => {
@@ -93,14 +93,14 @@ describe("golden path: ticket", () => {
93
93
  const id = await openTicket("Login fails");
94
94
 
95
95
  await stack.http.writeOk(
96
- "helpdesk:write:ticket:close",
96
+ "ticketing:write:ticket:close",
97
97
  { id, resolution: "Password reset" },
98
98
  admin,
99
99
  );
100
100
 
101
101
  expect(await readTicket(id)).toMatchObject({ title: "Login fails", isClosed: true });
102
102
  const list = await stack.http.queryOk<{ rows: TicketRow[] }>(
103
- "helpdesk:query:ticket:list",
103
+ "ticketing:query:ticket:list",
104
104
  { filter: { field: "isClosed", op: "eq", value: true } },
105
105
  agent,
106
106
  );
@@ -110,9 +110,9 @@ describe("golden path: ticket", () => {
110
110
  test("closing an already closed ticket is rejected with 422", async () => {
111
111
  const id = await openTicket("Duplicate close");
112
112
  const close = { id, resolution: "Fixed" };
113
- await stack.http.writeOk("helpdesk:write:ticket:close", close, admin);
113
+ await stack.http.writeOk("ticketing:write:ticket:close", close, admin);
114
114
 
115
- const again = await stack.http.writeErr("helpdesk:write:ticket:close", close, admin);
115
+ const again = await stack.http.writeErr("ticketing:write:ticket:close", close, admin);
116
116
 
117
117
  expect(again.httpStatus).toBe(422);
118
118
  expect(again.details).toEqual({ reason: "ticket_already_closed" });
@@ -122,7 +122,7 @@ describe("golden path: ticket", () => {
122
122
  const id = await openTicket("Slow wifi");
123
123
 
124
124
  const denied = await stack.http.writeErr(
125
- "helpdesk:write:ticket:close",
125
+ "ticketing:write:ticket:close",
126
126
  { id, resolution: "Moved the router" },
127
127
  agent,
128
128
  );
@@ -133,7 +133,7 @@ describe("golden path: ticket", () => {
133
133
 
134
134
  test("closing an unknown ticket fails with not_found", async () => {
135
135
  const missing = await stack.http.writeErr(
136
- "helpdesk:write:ticket:close",
136
+ "ticketing:write:ticket:close",
137
137
  { id: "99999999-9999-4999-8999-999999999999", resolution: "n/a" },
138
138
  admin,
139
139
  );
@@ -166,7 +166,7 @@ export const ticketEntity = createEntity({
166
166
  },
167
167
  });
168
168
 
169
- export const helpdeskFeature = defineFeature("helpdesk", (r) => {
169
+ export const ticketingFeature = defineFeature("ticketing", (r) => {
170
170
  const { table: ticketTable, executor: ticketExecutor } = createEntityExecutor(
171
171
  "ticket",
172
172
  ticketEntity,
@@ -1,14 +1,14 @@
1
- <!-- Generated by `bun run gen:agent-docs` from samples/recipes/contact. Do not edit. -->
1
+ <!-- Generated by `bun run gen:agent-docs` from samples/recipes/helpdesk. Do not edit. -->
2
2
 
3
- # contact
3
+ # helpdesk
4
4
 
5
- Public contact form backend: the contact bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client.
5
+ Public contact form backend: the helpdesk bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client.
6
6
 
7
7
  ## README
8
8
 
9
- # Recipe: contact
9
+ # Recipe: helpdesk
10
10
 
11
- Public contact form backend. The `contact` bundled feature stores questions, contact
11
+ Public contact form backend. The `helpdesk` bundled feature stores questions, contact
12
12
  requests and problem reports from website visitors and notifies every SystemAdmin (mail,
13
13
  Telegram only when the app turns it on). The notification names only the kind, the app and a link into the inbox:
14
14
  no name, address, phone, subject or message. Telegram is a third party where nothing can be
@@ -18,46 +18,46 @@ SystemAdmins reply from the admin. Phone is off and Telegram is not mounted unle
18
18
  turns them on (`fields.phone`, `telegram: true`).
19
19
 
20
20
  **What the recipe demonstrates:**
21
- - Mounting `createContactFeature` with its companions (delivery, user-data-rights, files)
22
- - The anonymous flow: `contact:query:challenge` hands out a proof-of-work challenge,
23
- `contact:write:submit` verifies it; spam gets the same 200 body and stores nothing
24
- - The browser client at `GET /contact/client.js` (`window.KumikoContact.load()` / `submit()`)
21
+ - Mounting `createHelpdeskFeature` with its companions (delivery, user-data-rights, files)
22
+ - The anonymous flow: `helpdesk:query:challenge` hands out a proof-of-work challenge,
23
+ `helpdesk:write:submit` verifies it; spam gets the same 200 body and stores nothing
24
+ - The browser client at `GET /helpdesk/client.js` (`window.KumikoHelpdesk.load()` / `submit()`)
25
25
 
26
26
  ## Layout
27
27
 
28
28
  ```
29
- samples/recipes/contact/
29
+ samples/recipes/helpdesk/
30
30
  ├── package.json
31
31
  ├── README.md
32
32
  └── src/
33
- ├── feature.ts # createContactFeature options
33
+ ├── feature.ts # createHelpdeskFeature options
34
34
  └── __tests__/
35
35
  └── feature.integration.test.ts # challenge query + client route
36
36
  ```
37
37
 
38
38
  The behavior (submit, silent drops, replies, Telegram, GDPR export and erasure, retention) is
39
39
  covered by the integration tests next to the feature in
40
- `packages/bundled-features/src/contact/__tests__/`.
40
+ `packages/bundled-features/src/helpdesk/__tests__/`.
41
41
 
42
42
  ## Run tests
43
43
 
44
44
  ```bash
45
- bun test --config=bunfig.integration.toml samples/recipes/contact
45
+ bun test --config=bunfig.integration.toml samples/recipes/helpdesk
46
46
  ```
47
47
 
48
48
  ## Integration into a real app
49
49
 
50
- 1. Mount `createContactFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
50
+ 1. Mount `createHelpdeskFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
51
51
  `files` with a file provider and `config`.
52
52
  2. Run `kumiko schema generate` (new tables, plus the delivery `idempotency_key` column).
53
- 3. SystemAdmins set `contact:config:reply-to` in the admin.
54
- 4. Embed `/contact/client.js` on the website; the form is yours. A website served by another
55
- server can serve the same script from `CONTACT_CLIENT_SOURCE` and type its calls with
56
- `ContactWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/contact/client`.
53
+ 3. SystemAdmins set `helpdesk:config:reply-to` in the admin.
54
+ 4. Embed `/helpdesk/client.js` on the website; the form is yours. A website served by another
55
+ server can serve the same script from `HELPDESK_CLIENT_SOURCE` and type its calls with
56
+ `HelpdeskWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/helpdesk/client`.
57
57
 
58
58
  Telegram is optional and off by default: notifications go by mail to SystemAdmins only. An app
59
59
  that turns it on (`telegram: true`) also mounts `channel-telegram` and `secrets` for the bot
60
- token, and SystemAdmins set `contact:config:telegram-chat`.
60
+ token, and SystemAdmins set `helpdesk:config:telegram-chat`.
61
61
 
62
62
  ## Source files
63
63
 
@@ -84,7 +84,7 @@ import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
84
84
  import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
85
85
  import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
86
86
  import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
87
- import { contactFeature } from "../feature";
87
+ import { helpdeskFeature } from "../feature";
88
88
 
89
89
  let stack: TestStack;
90
90
 
@@ -108,7 +108,7 @@ beforeAll(async () => {
108
108
  createSessionsFeature(),
109
109
  createUserDataRightsFeature(),
110
110
  createNotesHistoryFeature(),
111
- contactFeature,
111
+ helpdeskFeature,
112
112
  ],
113
113
  anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
114
114
  });
@@ -118,10 +118,10 @@ afterAll(async () => {
118
118
  await stack.cleanup();
119
119
  });
120
120
 
121
- describe("contact sample", () => {
121
+ describe("helpdesk sample", () => {
122
122
  test("an anonymous visitor gets a proof-of-work challenge and the form options", async () => {
123
123
  const res = await stack.http.raw("POST", "/api/query", {
124
- type: "contact:query:challenge",
124
+ type: "helpdesk:query:challenge",
125
125
  payload: {},
126
126
  });
127
127
  expect(res.status).toBe(200);
@@ -132,10 +132,10 @@ describe("contact sample", () => {
132
132
  });
133
133
 
134
134
  test("the browser client is served as JavaScript", async () => {
135
- const res = await stack.http.raw("GET", "/contact/client.js");
135
+ const res = await stack.http.raw("GET", "/helpdesk/client.js");
136
136
  expect(res.status).toBe(200);
137
137
  expect(res.headers.get("content-type")).toContain("application/javascript");
138
- expect(await res.text()).toContain("KumikoContact");
138
+ expect(await res.text()).toContain("KumikoHelpdesk");
139
139
  });
140
140
  });
141
141
  ```
@@ -143,7 +143,7 @@ describe("contact sample", () => {
143
143
  ### src/feature.ts
144
144
 
145
145
  ```ts
146
- // Contact sample
146
+ // Helpdesk sample
147
147
  //
148
148
  // A public website form (question, contact request, problem report) that lands with the
149
149
  // SystemAdmins: mail, optional Telegram, a copy to the sender. Spam is handled without a
@@ -151,9 +151,9 @@ describe("contact sample", () => {
151
151
  // and per-email rate limits. Rejected submits answer 200 with the normal body.
152
152
  //
153
153
  // The website embeds the anonymous client the feature serves itself:
154
- // <script src="https://api.example.com/contact/client.js"></script>
155
- // const { kinds, phone } = await window.KumikoContact.load();
156
- // const result = await window.KumikoContact.submit({ kind, name, email, message, locale });
154
+ // <script src="https://api.example.com/helpdesk/client.js"></script>
155
+ // const { kinds, phone } = await window.KumikoHelpdesk.load();
156
+ // const result = await window.KumikoHelpdesk.submit({ kind, name, email, message, locale });
157
157
  // // result.kind: "sent" | "rate-limited" (retryAfterSeconds) | "failed"
158
158
  //
159
159
  // Prerequisites the app wires itself:
@@ -162,9 +162,9 @@ describe("contact sample", () => {
162
162
  // - a file provider, because the entities carry file fields
163
163
  // - `kumiko schema generate` for the new tables
164
164
 
165
- import { createContactFeature } from "@cosmicdrift/kumiko-bundled-features/contact";
165
+ import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk";
166
166
 
167
- export const contactFeature = createContactFeature({
167
+ export const helpdeskFeature = createHelpdeskFeature({
168
168
  appName: "Sample App",
169
169
  fields: { phone: "optional" },
170
170
  // Lowered only to keep the sample test fast; the default (19 bits, 3 seconds) suits production.
@@ -20,7 +20,6 @@
20
20
  | `chat-channels` | Chat channels. Delivery notifications to Slack, minus the browser tab. | `examples/chat-channels.md` |
21
21
  | `compliance-profiles-demo` | Two-tenant demo: EU + Swiss compliance profiles deliver different authority contacts, languages, and grace periods through the same App-code. | `examples/compliance-profiles-demo.md` |
22
22
  | `compose-stacks` | compose*Stack helpers for auth, security, GDPR and SaaS billing, and the runProdApp check that names a stack whose boot option is missing. | `examples/compose-stacks.md` |
23
- | `contact` | Public contact form backend: the contact bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client. | `examples/contact.md` |
24
23
  | `cross-feature-events` | Feature appends a typed domain event via ctx.events.append; a r.multiStreamProjection reacts asynchronously. | `examples/cross-feature-events.md` |
25
24
  | `crypto-shredding-hr` | Crypto-shredding: PII fields encrypted per subject key; forgetting the subject erases the key and every field it protected. | `examples/crypto-shredding-hr.md` |
26
25
  | `currencies-global` | Shared money fields across tenants. Commas still matter. | `examples/currencies-global.md` |
@@ -43,6 +42,7 @@
43
42
  | `field-access` | Field-level access control. When entity-level roles aren't granular enough. | `examples/field-access.md` |
44
43
  | `files-post-processing` | The three ways to generate an image variant: declarative field variants, imperative ctx.services.derivatives.variant() with region-blur, and the public route behind a default-deny predicate. | `examples/files-post-processing.md` |
45
44
  | `golden-path` | The smallest complete feature: entity, write handler, event, projection, screen and an integration test. | `examples/golden-path.md` |
45
+ | `helpdesk` | Public contact form backend: the helpdesk bundled feature with its required companions (delivery, user-data-rights, files) and the anonymous browser client. | `examples/helpdesk.md` |
46
46
  | `host-routing` | createHostRoutingFeature + createHostDispatch — tenant per subdomain, per-host HTML and CSP, locale redirect, shared by runProdApp and the dev server. | `examples/host-routing.md` |
47
47
  | `i18n` | Feature-scoped translations. 'Hallo' and 'Hello' in the same app. | `examples/i18n.md` |
48
48
  | `idempotency` | Same request, same result. Dedupes on request ID. | `examples/idempotency.md` |
@@ -48,8 +48,6 @@ One entry per feature a package ships: purpose, import of its factory, required
48
48
  `import { createComplianceProfilesOpsFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles-ops"`; requires `compliance-profiles`, `tenant`
49
49
  - `config`: Stores per-tenant (and optionally per-user) configuration values with a multi-layer cascade: user-row → tenant-row → system-row → app-override (deploy-time `AppConfigOverrides`) → computed → feature default.
50
50
  `import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config"`
51
- - `contact`: Contact inbox: an anonymous browser client (GET /contact/client.js) submits questions, contact requests, bug reports and wishes behind a honeypot, a minimum submit time and a single-use proof-of-work challenge; signed-in users file reports from the admin.
52
- `import { createContactFeature } from "@cosmicdrift/kumiko-bundled-features/contact"`; requires `config`, `delivery`, `user-data-rights`, `files`, `notes-history`
53
51
  - `crypto-shredding`: Operator-level crypto-shredding trigger.
54
52
  `import { createCryptoShreddingFeature } from "@cosmicdrift/kumiko-bundled-features/crypto-shredding"`
55
53
  - `custom-fields`: Tenant- and system-scoped custom field definitions with generic value storage on any host entity.
@@ -90,6 +88,8 @@ One entry per feature a package ships: purpose, import of its factory, required
90
88
  `import { createFormDraftFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft"`
91
89
  - `form-draft-user-data`: GDPR (Art.
92
90
  `import { createFormDraftUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/form-draft-user-data"`; requires `user-data-rights`
91
+ - `helpdesk`: Helpdesk inbox: an anonymous browser client (GET /helpdesk/client.js) submits questions, contact requests, bug reports and wishes behind a honeypot, a minimum submit time and a single-use proof-of-work challenge; signed-in users file reports from the admin.
92
+ `import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk"`; requires `config`, `delivery`, `user-data-rights`, `files`, `notes-history`
93
93
  - `host-routing`: Host- and path-based tenant routing: an authoritative tenant resolver from the subdomain (tenantBy host), a tenant existence check against enabled, active tenants, and the tenant-key query behind createHostDispatch, which picks the HTML file, CSP, locale redirect or 404 per host for runProdApp's hostDispatch.
94
94
  `import { createHostRoutingFeature } from "@cosmicdrift/kumiko-bundled-features/host-routing"`; requires `auth-foundation`, `tenant`
95
95
  - `inbound-mail-foundation`: Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push) and send.