@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.
- package/agents/api/framework-engine.md +1 -0
- package/agents/boot-rules.md +343 -0
- package/agents/examples/api-docs.md +79 -71
- package/agents/examples/golden-path.md +11 -11
- package/agents/examples/{contact.md → helpdesk.md} +41 -34
- package/agents/examples.md +1 -1
- package/agents/features-index.md +2 -2
- package/agents/features.md +16 -16
- package/dist/engine/boot-validator/boot-report.d.ts +3 -0
- package/dist/engine/boot-validator/boot-report.js +2 -2
- package/dist/engine/boot-validator/boot-rules.d.ts +570 -0
- package/dist/engine/boot-validator/boot-rules.js +20 -0
- package/dist/engine/boot-validator/definition-config-events-jobs-rules.d.ts +77 -0
- package/dist/engine/boot-validator/definition-config-events-jobs-rules.js +77 -0
- package/dist/engine/boot-validator/definition-events-rules.d.ts +42 -0
- package/dist/engine/boot-validator/definition-events-rules.js +42 -0
- package/dist/engine/boot-validator/definition-feature-rules.d.ts +42 -0
- package/dist/engine/boot-validator/definition-feature-rules.js +42 -0
- package/dist/engine/boot-validator/definition-field-factories-rules.d.ts +17 -0
- package/dist/engine/boot-validator/definition-field-factories-rules.js +17 -0
- package/dist/engine/boot-validator/definition-handlers-rules.d.ts +72 -0
- package/dist/engine/boot-validator/definition-handlers-rules.js +72 -0
- package/dist/engine/boot-validator/definition-ownership-from-rules.d.ts +27 -0
- package/dist/engine/boot-validator/definition-ownership-from-rules.js +27 -0
- package/dist/engine/boot-validator/definition-probes-rules.d.ts +47 -0
- package/dist/engine/boot-validator/definition-probes-rules.js +47 -0
- package/dist/engine/boot-validator/definition-role-assignment-rules.d.ts +27 -0
- package/dist/engine/boot-validator/definition-role-assignment-rules.js +27 -0
- package/dist/engine/boot-validator/definition-ui-extensions-rules.d.ts +197 -0
- package/dist/engine/boot-validator/definition-ui-extensions-rules.js +197 -0
- package/dist/engine/boot-validator/definition-webhook-events-rules.d.ts +32 -0
- package/dist/engine/boot-validator/definition-webhook-events-rules.js +32 -0
- package/dist/engine/define-feature.js +26 -9
- package/dist/engine/define-handler.js +8 -4
- package/dist/engine/definition-violations.d.ts +14 -0
- package/dist/engine/definition-violations.js +71 -0
- package/dist/engine/entity-handlers.js +39 -13
- package/dist/engine/event-def.js +32 -12
- package/dist/engine/factories.js +16 -5
- package/dist/engine/feature-config-events-jobs.js +63 -27
- package/dist/engine/feature-entity-handlers.js +15 -6
- package/dist/engine/feature-probes.js +29 -9
- package/dist/engine/feature-ui-extensions.js +178 -92
- package/dist/engine/object-form.js +8 -2
- package/dist/engine/ownership.js +17 -5
- package/dist/engine/registry-validate.d.ts +1 -0
- package/dist/engine/registry-validate.js +7 -0
- package/dist/engine/registry.js +2 -1
- package/dist/engine/role-assignment.js +17 -5
- package/dist/engine/soft-delete-cleanup.js +4 -3
- package/dist/engine/webhook-events.js +20 -6
- package/dist/files/feature.js +1 -0
- package/dist/files/file-routes.js +1 -1
- package/dist/jobs/job-runner-gates.js +5 -1
- package/dist/schema-cli/shared.d.ts +11 -0
- package/dist/schema-cli/shared.js +37 -3
- package/dist/schema-cli/validate-command.js +10 -3
- package/package.json +3 -3
- 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
|
|
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. `
|
|
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
|
|
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 {
|
|
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(),
|
|
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://
|
|
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: "
|
|
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 {
|
|
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
|
-
|
|
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("
|
|
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", "
|
|
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", "
|
|
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", "
|
|
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", "
|
|
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", "
|
|
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("
|
|
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
|
-
"
|
|
396
|
+
"ticketing:write:ticket:create",
|
|
397
397
|
{ title: "Scanner jams", priority: "low" },
|
|
398
398
|
actor,
|
|
399
399
|
);
|
|
400
400
|
await stack.http.writeOk(
|
|
401
|
-
"
|
|
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
|
-
"
|
|
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("
|
|
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("
|
|
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(
|
|
466
|
-
|
|
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(
|
|
474
|
-
|
|
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
|
|
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
|
|
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: "
|
|
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: "
|
|
605
|
+
handler: "ticketing:write:ticket:close",
|
|
598
606
|
fields: { resolution: createTextField({ personal: false, reason: "is_business_data" }) },
|
|
599
|
-
layout: { sections: [{ title: "
|
|
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: "
|
|
612
|
+
handler: "ticketing:write:ticket:purge",
|
|
605
613
|
fields: {},
|
|
606
614
|
layout: { sections: [] },
|
|
607
615
|
});
|
|
608
616
|
|
|
609
|
-
r.nav({ id: "tickets", label: "
|
|
610
|
-
r.nav({ id: "settings", label: "
|
|
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: "
|
|
614
|
-
parent: "
|
|
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
|
-
"
|
|
621
|
-
"
|
|
622
|
-
"
|
|
623
|
-
"
|
|
624
|
-
"
|
|
625
|
-
"
|
|
626
|
-
"
|
|
627
|
-
"
|
|
628
|
-
"
|
|
629
|
-
"
|
|
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
|
-
"
|
|
634
|
-
"
|
|
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
|
-
"
|
|
639
|
-
"
|
|
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
|
-
"
|
|
644
|
-
"
|
|
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
|
-
"
|
|
649
|
-
"
|
|
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
|
-
"
|
|
654
|
-
"
|
|
655
|
-
"
|
|
656
|
-
"
|
|
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
|
-
"
|
|
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
|
-
"
|
|
665
|
-
"
|
|
666
|
-
"
|
|
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
|
-
"
|
|
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
|
-
"
|
|
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
|
-
"
|
|
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", "
|
|
691
|
-
read: ["
|
|
698
|
+
events: ["ticket.created", "ticketing:ticket-closed"],
|
|
699
|
+
read: ["ticketing:query:ticket:*"],
|
|
692
700
|
write: [
|
|
693
|
-
"
|
|
694
|
-
"
|
|
695
|
-
"
|
|
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 {
|
|
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: [
|
|
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
|
-
"
|
|
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>("
|
|
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
|
-
"
|
|
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
|
-
"
|
|
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("
|
|
113
|
+
await stack.http.writeOk("ticketing:write:ticket:close", close, admin);
|
|
114
114
|
|
|
115
|
-
const again = await stack.http.writeErr("
|
|
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
|
-
"
|
|
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
|
-
"
|
|
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
|
|
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/
|
|
1
|
+
<!-- Generated by `bun run gen:agent-docs` from samples/recipes/helpdesk. Do not edit. -->
|
|
2
2
|
|
|
3
|
-
#
|
|
3
|
+
# helpdesk
|
|
4
4
|
|
|
5
|
-
Public contact form backend: the
|
|
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:
|
|
9
|
+
# Recipe: helpdesk
|
|
10
10
|
|
|
11
|
-
Public contact form backend. The `
|
|
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 `
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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/
|
|
30
|
+
samples/recipes/helpdesk/
|
|
30
31
|
├── package.json
|
|
31
32
|
├── README.md
|
|
32
33
|
└── src/
|
|
33
|
-
├── feature.ts #
|
|
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/
|
|
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/
|
|
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 `
|
|
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 `
|
|
54
|
-
4. Embed `/
|
|
55
|
-
|
|
56
|
-
`
|
|
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 `
|
|
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 {
|
|
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
|
-
|
|
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("
|
|
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: "
|
|
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", "/
|
|
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("
|
|
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
|
-
//
|
|
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
|
-
//
|
|
155
|
-
//
|
|
156
|
-
//
|
|
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
|
-
// -
|
|
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 {
|
|
172
|
+
import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk";
|
|
166
173
|
|
|
167
|
-
export const
|
|
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.
|
package/agents/examples.md
CHANGED
|
@@ -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` |
|