@cosmicdrift/kumiko-framework 0.412.0 → 0.413.1

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 (59) hide show
  1. package/agents/api/framework-engine.md +1 -0
  2. package/agents/boot-rules.md +343 -0
  3. package/agents/examples/api-docs.md +79 -71
  4. package/agents/examples/golden-path.md +11 -11
  5. package/agents/examples/{contact.md → helpdesk.md} +41 -34
  6. package/agents/examples.md +1 -1
  7. package/agents/features-index.md +2 -2
  8. package/agents/features.md +16 -16
  9. package/dist/engine/boot-validator/boot-report.d.ts +3 -0
  10. package/dist/engine/boot-validator/boot-report.js +2 -2
  11. package/dist/engine/boot-validator/boot-rules.d.ts +570 -0
  12. package/dist/engine/boot-validator/boot-rules.js +20 -0
  13. package/dist/engine/boot-validator/definition-config-events-jobs-rules.d.ts +77 -0
  14. package/dist/engine/boot-validator/definition-config-events-jobs-rules.js +77 -0
  15. package/dist/engine/boot-validator/definition-events-rules.d.ts +42 -0
  16. package/dist/engine/boot-validator/definition-events-rules.js +42 -0
  17. package/dist/engine/boot-validator/definition-feature-rules.d.ts +42 -0
  18. package/dist/engine/boot-validator/definition-feature-rules.js +42 -0
  19. package/dist/engine/boot-validator/definition-field-factories-rules.d.ts +17 -0
  20. package/dist/engine/boot-validator/definition-field-factories-rules.js +17 -0
  21. package/dist/engine/boot-validator/definition-handlers-rules.d.ts +72 -0
  22. package/dist/engine/boot-validator/definition-handlers-rules.js +72 -0
  23. package/dist/engine/boot-validator/definition-ownership-from-rules.d.ts +27 -0
  24. package/dist/engine/boot-validator/definition-ownership-from-rules.js +27 -0
  25. package/dist/engine/boot-validator/definition-probes-rules.d.ts +47 -0
  26. package/dist/engine/boot-validator/definition-probes-rules.js +47 -0
  27. package/dist/engine/boot-validator/definition-role-assignment-rules.d.ts +27 -0
  28. package/dist/engine/boot-validator/definition-role-assignment-rules.js +27 -0
  29. package/dist/engine/boot-validator/definition-ui-extensions-rules.d.ts +197 -0
  30. package/dist/engine/boot-validator/definition-ui-extensions-rules.js +197 -0
  31. package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +32 -0
  32. package/dist/engine/boot-validator/definition-webhook-events-rules.js +32 -0
  33. package/dist/engine/define-feature.js +26 -9
  34. package/dist/engine/define-handler.js +8 -4
  35. package/dist/engine/definition-violations.d.ts +14 -0
  36. package/dist/engine/definition-violations.js +71 -0
  37. package/dist/engine/entity-handlers.js +39 -13
  38. package/dist/engine/event-def.js +32 -12
  39. package/dist/engine/factories.js +16 -5
  40. package/dist/engine/feature-config-events-jobs.js +63 -27
  41. package/dist/engine/feature-entity-handlers.js +15 -6
  42. package/dist/engine/feature-probes.js +29 -9
  43. package/dist/engine/feature-ui-extensions.js +178 -92
  44. package/dist/engine/object-form.js +8 -2
  45. package/dist/engine/ownership.js +17 -5
  46. package/dist/engine/registry-validate.d.ts +1 -0
  47. package/dist/engine/registry-validate.js +7 -0
  48. package/dist/engine/registry.js +2 -1
  49. package/dist/engine/role-assignment.js +17 -5
  50. package/dist/engine/soft-delete-cleanup.js +4 -3
  51. package/dist/engine/webhook-events.js +20 -6
  52. package/dist/files/feature.js +1 -0
  53. package/dist/files/file-routes.js +1 -1
  54. package/dist/jobs/job-runner-gates.js +5 -1
  55. package/dist/schema-cli/shared.d.ts +11 -0
  56. package/dist/schema-cli/shared.js +37 -3
  57. package/dist/schema-cli/validate-command.js +10 -3
  58. package/package.json +3 -3
  59. 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,50 @@ 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 (config, delivery, user-data-rights,
22
+ files, notes-history)
23
+ - The anonymous flow: `helpdesk:query:challenge` hands out a proof-of-work challenge,
24
+ `helpdesk:write:submit` verifies it; spam gets the same 200 body and stores nothing
25
+ - The browser client at `GET /helpdesk/client.js` (`window.KumikoHelpdesk.load()` / `submit()`)
25
26
 
26
27
  ## Layout
27
28
 
28
29
  ```
29
- samples/recipes/contact/
30
+ samples/recipes/helpdesk/
30
31
  ├── package.json
31
32
  ├── README.md
32
33
  └── src/
33
- ├── feature.ts # createContactFeature options
34
+ ├── feature.ts # createHelpdeskFeature options
34
35
  └── __tests__/
35
36
  └── feature.integration.test.ts # challenge query + client route
36
37
  ```
37
38
 
38
39
  The behavior (submit, silent drops, replies, Telegram, GDPR export and erasure, retention) is
39
40
  covered by the integration tests next to the feature in
40
- `packages/bundled-features/src/contact/__tests__/`.
41
+ `packages/bundled-features/src/helpdesk/__tests__/`.
41
42
 
42
43
  ## Run tests
43
44
 
44
45
  ```bash
45
- bun test --config=bunfig.integration.toml samples/recipes/contact
46
+ bun test --config=bunfig.integration.toml samples/recipes/helpdesk
46
47
  ```
47
48
 
48
49
  ## Integration into a real app
49
50
 
50
- 1. Mount `createContactFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
51
- `files` with a file provider and `config`.
51
+ 1. Mount `createHelpdeskFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
52
+ `files` with a file provider, `notes-history` and `config`.
52
53
  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`.
54
+ 3. SystemAdmins set `helpdesk:config:reply-to` in the admin.
55
+ 4. Embed `/helpdesk/client.js` on the website; the form is yours. The client posts to the
56
+ relative paths `/api/query` and `/api/write` without cookies, so the page has to share the
57
+ app's origin. A website served by another server forwards `/api` to the app on its own
58
+ origin; it can then serve the same script from `HELPDESK_CLIENT_SOURCE` and type its calls
59
+ with `HelpdeskWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/helpdesk/client`.
60
+ `samples/apps/use-all-bundled/public/helpdesk-contact.html` (with `helpdesk-contact.js`) is a complete same-origin page.
57
61
 
58
62
  Telegram is optional and off by default: notifications go by mail to SystemAdmins only. An app
59
63
  that turns it on (`telegram: true`) also mounts `channel-telegram` and `secrets` for the bot
60
- token, and SystemAdmins set `contact:config:telegram-chat`.
64
+ token, and SystemAdmins set `helpdesk:config:telegram-chat`.
61
65
 
62
66
  ## Source files
63
67
 
@@ -84,7 +88,7 @@ import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
84
88
  import { createUserDataRightsFeature } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
85
89
  import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
86
90
  import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
87
- import { contactFeature } from "../feature";
91
+ import { helpdeskFeature } from "../feature";
88
92
 
89
93
  let stack: TestStack;
90
94
 
@@ -108,7 +112,7 @@ beforeAll(async () => {
108
112
  createSessionsFeature(),
109
113
  createUserDataRightsFeature(),
110
114
  createNotesHistoryFeature(),
111
- contactFeature,
115
+ helpdeskFeature,
112
116
  ],
113
117
  anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
114
118
  });
@@ -118,10 +122,10 @@ afterAll(async () => {
118
122
  await stack.cleanup();
119
123
  });
120
124
 
121
- describe("contact sample", () => {
125
+ describe("helpdesk sample", () => {
122
126
  test("an anonymous visitor gets a proof-of-work challenge and the form options", async () => {
123
127
  const res = await stack.http.raw("POST", "/api/query", {
124
- type: "contact:query:challenge",
128
+ type: "helpdesk:query:challenge",
125
129
  payload: {},
126
130
  });
127
131
  expect(res.status).toBe(200);
@@ -132,10 +136,10 @@ describe("contact sample", () => {
132
136
  });
133
137
 
134
138
  test("the browser client is served as JavaScript", async () => {
135
- const res = await stack.http.raw("GET", "/contact/client.js");
139
+ const res = await stack.http.raw("GET", "/helpdesk/client.js");
136
140
  expect(res.status).toBe(200);
137
141
  expect(res.headers.get("content-type")).toContain("application/javascript");
138
- expect(await res.text()).toContain("KumikoContact");
142
+ expect(await res.text()).toContain("KumikoHelpdesk");
139
143
  });
140
144
  });
141
145
  ```
@@ -143,28 +147,31 @@ describe("contact sample", () => {
143
147
  ### src/feature.ts
144
148
 
145
149
  ```ts
146
- // Contact sample
150
+ // Helpdesk sample
147
151
  //
148
152
  // A public website form (question, contact request, problem report) that lands with the
149
153
  // SystemAdmins: mail, optional Telegram, a copy to the sender. Spam is handled without a
150
154
  // captcha: honeypot field, single-use proof-of-work challenge, minimum submit time, per-IP
151
155
  // and per-email rate limits. Rejected submits answer 200 with the normal body.
152
156
  //
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 });
157
+ // The website embeds the anonymous client the feature serves itself. The client posts to the
158
+ // relative paths /api/query and /api/write, so the page must share its origin with the app
159
+ // (or forward /api to it on its own origin):
160
+ // <script src="/helpdesk/client.js"></script>
161
+ // const { kinds, phone } = await window.KumikoHelpdesk.load();
162
+ // const result = await window.KumikoHelpdesk.submit({ kind, name, email, message, locale });
157
163
  // // result.kind: "sent" | "rate-limited" (retryAfterSeconds) | "failed"
158
164
  //
159
165
  // Prerequisites the app wires itself:
160
166
  // - `anonymousAccess` (defaultTenantId = SYSTEM_TENANT_ID) so the form needs no login
161
167
  // - delivery with a mail channel (channel-telegram only with `telegram: true`, off by default)
162
- // - a file provider, because the entities carry file fields
168
+ // - config, user-data-rights and notes-history (required features)
169
+ // - files with a file provider, because the entities carry file fields
163
170
  // - `kumiko schema generate` for the new tables
164
171
 
165
- import { createContactFeature } from "@cosmicdrift/kumiko-bundled-features/contact";
172
+ import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk";
166
173
 
167
- export const contactFeature = createContactFeature({
174
+ export const helpdeskFeature = createHelpdeskFeature({
168
175
  appName: "Sample App",
169
176
  fields: { phone: "optional" },
170
177
  // 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` |