@cosmicdrift/kumiko-samples 0.411.0 → 0.412.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +1 -1
  3. package/packages/bundled-features/src/agent-tools/agent-doc-lint.ts +64 -3
  4. package/packages/bundled-features/src/agent-tools/agent-manifest.ts +13 -130
  5. package/packages/bundled-features/src/agent-tools/api-docs/anchors.ts +60 -0
  6. package/packages/bundled-features/src/agent-tools/api-docs/check.ts +25 -0
  7. package/packages/bundled-features/src/agent-tools/api-docs/collect-events.ts +140 -0
  8. package/packages/bundled-features/src/agent-tools/api-docs/collect.ts +175 -0
  9. package/packages/bundled-features/src/agent-tools/api-docs/curl.ts +28 -0
  10. package/packages/bundled-features/src/agent-tools/api-docs/error-table.ts +45 -0
  11. package/packages/bundled-features/src/agent-tools/api-docs/examples.ts +43 -0
  12. package/packages/bundled-features/src/agent-tools/api-docs/generate.ts +179 -0
  13. package/packages/bundled-features/src/agent-tools/api-docs/index-json.ts +29 -0
  14. package/packages/bundled-features/src/agent-tools/api-docs/index.ts +21 -0
  15. package/packages/bundled-features/src/agent-tools/api-docs/list-parameters.ts +38 -0
  16. package/packages/bundled-features/src/agent-tools/api-docs/markdown.ts +70 -0
  17. package/packages/bundled-features/src/agent-tools/api-docs/menu-path.ts +82 -0
  18. package/packages/bundled-features/src/agent-tools/api-docs/model.ts +83 -0
  19. package/packages/bundled-features/src/agent-tools/api-docs/problems.ts +58 -0
  20. package/packages/bundled-features/src/agent-tools/api-docs/render-events.ts +76 -0
  21. package/packages/bundled-features/src/agent-tools/api-docs/render-openapi.ts +216 -0
  22. package/packages/bundled-features/src/agent-tools/api-docs/render-overview.ts +86 -0
  23. package/packages/bundled-features/src/agent-tools/api-docs/render-reference.ts +79 -0
  24. package/packages/bundled-features/src/agent-tools/api-docs/render-tokens.ts +136 -0
  25. package/packages/bundled-features/src/agent-tools/api-docs/schema-fields.ts +167 -0
  26. package/packages/bundled-features/src/agent-tools/api-docs/section-ids.ts +28 -0
  27. package/packages/bundled-features/src/agent-tools/api-docs/system-only.ts +11 -0
  28. package/packages/bundled-features/src/agent-tools/api-docs/texts/de.ts +166 -0
  29. package/packages/bundled-features/src/agent-tools/api-docs/texts/en.ts +159 -0
  30. package/packages/bundled-features/src/agent-tools/api-docs/texts/es.ts +162 -0
  31. package/packages/bundled-features/src/agent-tools/api-docs/texts/fr.ts +169 -0
  32. package/packages/bundled-features/src/agent-tools/api-docs/texts/index.ts +67 -0
  33. package/packages/bundled-features/src/agent-tools/api-docs/texts/it.ts +165 -0
  34. package/packages/bundled-features/src/agent-tools/api-docs/texts/types.ts +130 -0
  35. package/packages/bundled-features/src/agent-tools/api-docs/ui-writes.ts +81 -0
  36. package/packages/bundled-features/src/agent-tools/changes.json +24 -0
  37. package/packages/bundled-features/src/agent-tools/handler-schema.ts +45 -0
  38. package/packages/bundled-features/src/agent-tools/index.ts +24 -0
  39. package/packages/bundled-features/src/agent-tools/labels.ts +181 -0
  40. package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
  41. package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +99 -71
  42. package/packages/bundled-features/src/inbound-mail-foundation/feature.ts +2 -2
  43. package/packages/bundled-features/src/personal-access-tokens/changes.json +6 -0
  44. package/packages/bundled-features/src/personal-access-tokens/feature.ts +5 -2
  45. package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts +7 -2
  46. package/packages/bundled-features/src/personal-access-tokens/i18n.ts +6 -1
  47. package/packages/bundled-features/src/personal-access-tokens/index.ts +37 -2
  48. package/packages/bundled-features/src/personal-access-tokens/scope-events-check.ts +28 -0
  49. package/packages/bundled-features/src/personal-access-tokens/screens.ts +9 -1
  50. package/packages/bundled-features/src/personal-access-tokens/web/constants.ts +1 -0
  51. package/packages/bundled-features/src/personal-access-tokens/web/scopes.ts +14 -0
  52. package/samples/recipes/api-docs/README.md +52 -0
  53. package/samples/recipes/api-docs/api-docs/de/events.md +62 -0
  54. package/samples/recipes/api-docs/api-docs/de/overview.md +100 -0
  55. package/samples/recipes/api-docs/api-docs/de/reference/tickets.md +305 -0
  56. package/samples/recipes/api-docs/api-docs/de/tokens.md +66 -0
  57. package/samples/recipes/api-docs/api-docs/en/events.md +62 -0
  58. package/samples/recipes/api-docs/api-docs/en/overview.md +100 -0
  59. package/samples/recipes/api-docs/api-docs/en/reference/tickets.md +305 -0
  60. package/samples/recipes/api-docs/api-docs/en/tokens.md +66 -0
  61. package/samples/recipes/api-docs/api-docs/index.json +371 -0
  62. package/samples/recipes/api-docs/api-docs/openapi.json +982 -0
  63. package/samples/recipes/api-docs/api-examples/ticket-close.json +21 -0
  64. package/samples/recipes/api-docs/api-examples/ticket-create.json +42 -0
  65. package/samples/recipes/api-docs/api-examples/ticket-detail.json +28 -0
  66. package/samples/recipes/api-docs/api-examples/ticket-list.json +31 -0
  67. package/samples/recipes/api-docs/api-examples/ticket-update.json +54 -0
  68. package/samples/recipes/api-docs/api-examples/webhooks/ticket-closed.json +8 -0
  69. package/samples/recipes/api-docs/api-examples/webhooks/ticket-created.json +10 -0
  70. package/samples/recipes/api-docs/kumiko.config.ts +33 -0
  71. package/samples/recipes/api-docs/package.json +14 -0
  72. package/samples/recipes/api-docs/src/feature.ts +218 -0
  73. package/samples/recipes/api-docs/tsconfig.json +22 -0
@@ -0,0 +1,52 @@
1
+ # API docs
2
+
3
+ API documentation for personal access tokens, generated from the app itself. A helpdesk
4
+ feature exposes its ticket handlers through token scopes; `kumiko api-docs` turns the
5
+ registry, the translations and recorded requests into Markdown pages, an OpenAPI file and
6
+ an `index.json` that a website or an agent can read.
7
+
8
+ ## What it shows
9
+
10
+ - **Scopes decide the content.** Only handlers that a scope of the token feature reaches
11
+ appear. `helpdesk:write:ticket:purge` is reachable from a screen but in no scope, so it is
12
+ listed under `apiDocs.uiOnlyWrites` with a reason; without that entry the generator reports it.
13
+ - **Texts come from the feature.** Titles, descriptions and field labels per locale use the
14
+ keys `<handler qn>:title`, `:description` and `:field:<name>`; the German pages need the
15
+ German translations, the menu path to the token screen comes from the nav tree.
16
+ - **Examples are recordings.** The integration test sends real requests with a token through
17
+ `recordApiExample` from `@cosmicdrift/kumiko-testing/api-examples`. UUIDs, timestamps and
18
+ tokens are replaced by fixed values, so a recording only changes when the API changes.
19
+ - **The output is a golden.** `api-docs/` is committed and the golden test fails when the
20
+ generator would produce something else.
21
+
22
+ ## Commands
23
+
24
+ Record the examples (writes `api-examples/`, needs Postgres from `docker compose up -d`):
25
+
26
+ ```
27
+ KUMIKO_RECORD_API_EXAMPLES=1 bun test --config=bunfig.integration.toml samples/recipes/api-docs/src/__tests__/api-docs.integration.test.ts
28
+ ```
29
+
30
+ Regenerate the golden (empties and rewrites `api-docs/`):
31
+
32
+ ```
33
+ KUMIKO_UPDATE_API_DOCS_GOLDEN=1 bun test samples/recipes/api-docs/src/__tests__/api-docs.golden.test.ts
34
+ ```
35
+
36
+ Both tests run without the flags as ordinary checks.
37
+
38
+ In an app, `kumiko api-docs` writes the pages to `apiDocs.outDir` (default `api-docs`) and
39
+ `kumiko api-docs --check` compares them with the disk, so a CI step can keep them current.
40
+ The golden test pins the framework and app version in `index.json` and `openapi.json`, so
41
+ those two files differ from a real run of the command.
42
+
43
+ ## Files
44
+
45
+ ```
46
+ kumiko.config.ts features and the apiDocs block
47
+ src/feature.ts helpdesk feature and the token feature with its scopes
48
+ src/__tests__/api-docs.integration.test.ts mints a token, records the examples, checks scope limits
49
+ src/__tests__/api-docs.golden.test.ts generator output equals api-docs/
50
+ api-examples/ recorded requests and responses
51
+ api-docs/ the golden output
52
+ ```
@@ -0,0 +1,62 @@
1
+ ---
2
+ title: "Webhook-Ereignisse"
3
+ description: "Webhook-Ereignisse: wann sie ausgelöst werden, welchen Scope sie brauchen und was ihre Nutzlast enthält."
4
+ ---
5
+
6
+ Ein Webhook-Ereignis meldet deinem System, dass sich etwas geändert hat. Jedes Ereignis hat einen Namen, eine Version und eine Nutzlast. Der bei einem Ereignis genannte Scope ist der Token-Scope, der das Abonnieren erlaubt.
7
+
8
+ ## Zustellung
9
+
10
+ Zustellungen sind signiert, damit du den Absender prüfen kannst. Eine fehlgeschlagene Zustellung wird einige Male wiederholt, bevor sie verworfen wird. Antworte innerhalb weniger Sekunden und behandle wiederholte Zustellungen desselben Ereignisses als eine.
11
+
12
+ ## Versionen
13
+
14
+ Ein neues optionales Feld behält die Version. Eine inkompatible Änderung, etwa ein entferntes oder umbenanntes Feld oder ein geänderter Typ, bekommt eine neue Version.
15
+
16
+ ## Ereignisse
17
+
18
+ ### ticket.closed
19
+
20
+ Ein Ticket wurde geschlossen und seine Lösung festgehalten.
21
+
22
+ - Version: `1`
23
+ - Benötigter Scope: `tickets:read`
24
+
25
+ | Feld | Typ | Pflicht | Beschreibung |
26
+ | --- | --- | --- | --- |
27
+ | `id` | string (uuid) | ja | ID des geschlossenen Tickets |
28
+ | `resolution` | string | ja | Wie das Ticket gelöst wurde |
29
+
30
+ **Beispiel-Nutzlast**
31
+
32
+ ```json
33
+ {
34
+ "id": "00000000-0000-4000-8000-000000000001",
35
+ "resolution": "Replaced the roller"
36
+ }
37
+ ```
38
+
39
+ ### ticket.created
40
+
41
+ Ein Datensatz vom Typ Ticket wurde angelegt.
42
+
43
+ - Version: `1`
44
+ - Benötigter Scope: `tickets:read`
45
+
46
+ | Feld | Typ | Pflicht | Beschreibung |
47
+ | --- | --- | --- | --- |
48
+ | `id` | string (uuid) | ja | Ticket-ID |
49
+ | `title` | string | ja | Titel |
50
+ | `status` | "open" \| "closed" | ja | Status |
51
+ | `priority` | "low" \| "normal" \| "high" | ja | Priorität |
52
+
53
+ **Beispiel-Nutzlast**
54
+
55
+ ```json
56
+ {
57
+ "id": "00000000-0000-4000-8000-000000000001",
58
+ "title": "Scanner jams",
59
+ "status": "open",
60
+ "priority": "low"
61
+ }
62
+ ```
@@ -0,0 +1,100 @@
1
+ ---
2
+ title: "HTTP-API"
3
+ description: "Endpunkte, Request-Body, Antworten, Fehlercodes, Listen und Batches der HTTP-API."
4
+ ---
5
+
6
+ Jeder Aufruf ist ein POST mit JSON-Body. Das Feld `type` nennt den Handler, `payload` enthält dessen Felder. Die Referenzseiten listen jeden Handler mit seinen Feldern.
7
+
8
+ ## Endpunkte
9
+
10
+ | Endpoint | |
11
+ | --- | --- |
12
+ | `POST /api/query` | Liest Daten. Ändert nie etwas. |
13
+ | `POST /api/write` | Ändert Daten: anlegen, ändern, löschen oder eine bestimmte Aktion. |
14
+ | `POST /api/batch` | Führt mehrere Schreibaufrufe in einer Transaktion aus. |
15
+
16
+ ## Authentifizierung
17
+
18
+ Sende einen API-Token im Header `Authorization` als `Bearer <token>`. Anfragen mit Token brauchen weder Cookie noch CSRF-Token. Der Token legt auch das Konto fest, in dem die Anfrage läuft. Du sendest also nie eine Konto- oder Mandanten-ID.
19
+
20
+ ## Request-Body
21
+
22
+ `type` ist der Name des Handlers, zum Beispiel `helpdesk:query:ticket:detail`. `payload` enthält die Felder aus der Referenz. `requestId` ist optional, siehe unten. Das Payload darf höchstens 20 Ebenen tief verschachtelt sein.
23
+
24
+ ```bash
25
+ curl -X POST https://helpdesk.example.com/api/query \
26
+ -H "Authorization: Bearer $API_TOKEN" \
27
+ -H "Content-Type: application/json" \
28
+ -d '{
29
+ "type": "helpdesk:query:ticket:detail",
30
+ "payload": {
31
+ "id": "00000000-0000-4000-8000-000000000001"
32
+ }
33
+ }'
34
+ ```
35
+
36
+ ## Antworten
37
+
38
+ Ein erfolgreiches Lesen liefert `data`. Ein erfolgreiches Schreiben liefert `isSuccess: true` und `data`.
39
+
40
+ Bei einem Fehler ist der HTTP-Status 4xx oder 5xx und der Body enthält `error`. Schreibaufrufe liefern zusätzlich `isSuccess: false`. Werte `error.code` und den Status aus. `message` ist für Menschen gedacht und kann sich ändern.
41
+
42
+ ## Fehlercodes
43
+
44
+ | Code | HTTP-Status | Bedeutung |
45
+ | --- | --- | --- |
46
+ | `ambiguous_auth` | 400 | Die Anfrage enthielt Session-Cookie und Token. Sende nur eines von beiden. |
47
+ | `validation_error` | 400 | Das Payload passt nicht zu den Feldern des Handlers. `details` nennt die Felder. |
48
+ | `invalid_token` | 401 | Der Token ist unbekannt, widerrufen oder abgelaufen. |
49
+ | `missing_token` | 401 | Der Header `Authorization` fehlt. |
50
+ | `unauthenticated` | 401 | Es wurden keine gültigen Zugangsdaten gesendet. |
51
+ | `access_denied` | 403 | Dem Token fehlt der Scope für diesen Handler, oder der Endpunkt nimmt keine Tokens an. |
52
+ | `feature_disabled` | 403 | Diese Funktion ist abgeschaltet oder nicht Teil deines Tarifs. |
53
+ | `not_found` | 404 | Der Datensatz existiert nicht oder du darfst ihn nicht sehen. |
54
+ | `conflict` | 409 | Die Änderung widerspricht dem aktuellen Stand der Daten. |
55
+ | `idempotent_replay` | 409 | Diese Änderung wurde unter demselben Idempotenz-Schlüssel schon ausgeführt. Der erste Versuch war erfolgreich, sende sie nicht noch einmal. |
56
+ | `precondition_failed` | 409 | Ein Feld des Datensatzes hat nicht mehr den Wert, den die Änderung erwartet hat. Lies den Datensatz neu und wiederhole. |
57
+ | `record_locked` | 409 | Eine andere Änderung sperrt den Datensatz. Wiederhole gleich. |
58
+ | `unique_violation` | 409 | Ein Datensatz mit diesem Wert existiert bereits. |
59
+ | `version_conflict` | 409 | Der Datensatz hat sich nach deinem Lesen geändert. Lies ihn neu und wiederhole mit der neuen `version`. |
60
+ | `unconfigured` | 422 | Eine Einstellung, die diese Funktion braucht, ist noch leer. Richte sie zuerst in der App ein und wiederhole dann. |
61
+ | `unprocessable` | 422 | Die Daten sind gültig, aber eine Fachregel lehnt die Änderung ab. `details.reason` nennt die Regel. |
62
+ | `pat_rate_limited` | 429 | Dieser Token hat in kurzer Zeit zu viele Anfragen gesendet. Warte einen Moment und wiederhole. |
63
+ | `rate_limited` | 429 | Zu viele Anfragen. Warte so viele Sekunden, wie der Header `Retry-After` angibt. |
64
+ | `internal_error` | 500 | Unerwarteter Serverfehler. Wiederhole später. |
65
+ | `rate_limit_unavailable` | 503 | Die Ratenbegrenzung ist vorübergehend nicht verfügbar, die Anfrage wurde abgelehnt. Wiederhole gleich. |
66
+ | `member_read_timeout` | 504 | Ein Lesevorgang auf dem Server hat zu lange gedauert und wurde abgebrochen. Wiederhole später. |
67
+
68
+ ## Versionen und Konflikte
69
+
70
+ Jeder Datensatz hat eine `version`. Ein Update nimmt die `version`, die du zuletzt gelesen hast. Hat jemand den Datensatz zwischenzeitlich geändert, schlägt der Aufruf mit 409 `version_conflict` fehl. Lies den Datensatz neu, prüfe die Änderung und sende sie mit der neuen Version.
71
+
72
+ ## Listen
73
+
74
+ Listen-Handler enden auf `:list` und akzeptieren diese Felder:
75
+
76
+ | Feld | Typ | Beschreibung |
77
+ | --- | --- | --- |
78
+ | `cursor` | string | Position aus `nextCursor` der vorherigen Seite. |
79
+ | `limit` | integer | Zeilen pro Seite, standardmäßig 50, höchstens 200. |
80
+ | `search` | string | Volltextsuche über die durchsuchbaren Felder. |
81
+ | `sort` | string | Feld, nach dem sortiert wird. |
82
+ | `sortDirection` | "asc" \| "desc" | `asc` oder `desc`. |
83
+ | `offset` | integer | Anzahl der zu überspringenden Zeilen. Nutze besser `cursor` zum Blättern. |
84
+ | `totalCount` | boolean | Mit `true` bekommst du zusätzlich `total`, die Anzahl der passenden Zeilen. |
85
+ | `includeDeleted` | boolean | Mit `true` sind gelöschte Zeilen enthalten. Nur für Entitäten mit Soft Delete. |
86
+ | `onlyDeleted` | boolean | Mit `true` kommen nur gelöschte Zeilen zurück. Nur für Entitäten mit Soft Delete, nicht zusammen mit `includeDeleted`. |
87
+ | `filter` | object | Ein Feldfilter mit `field`, `op` und `value`. `op` ist einer von `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
88
+ | `filters` | array of object | Mehrere Feldfilter, je mit `field`, `op` und `value`. `op` ist einer von `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
89
+ | `namedFilter` | string | Name eines vordefinierten Filters der Entität, zum Beispiel einer Arbeitsliste. |
90
+ | `aggregate` | object | Liefert aggregierte Werte statt Zeilen. |
91
+
92
+ Die Antwort enthält `rows` und `nextCursor`. Für die nächste Seite sendest du `nextCursor` als `cursor`. Auf der letzten Seite ist `nextCursor` `null`.
93
+
94
+ ## Batches
95
+
96
+ `POST /api/batch` nimmt `commands`, eine Liste von Schreibaufrufen `{ type, payload }`. Sie laufen in einer Transaktion: Schlägt einer fehl, wirkt keiner. Die Antwort hat dann `isSuccess: false`, den `error` und `failedIndex`, die Position des fehlgeschlagenen Befehls ab 0 gezählt.
97
+
98
+ ## Sicher wiederholen
99
+
100
+ Sende bei Schreib- und Batch-Aufrufen eine `requestId` mit. Das ist ein beliebiger String, der pro Änderung eindeutig ist. Reißt die Verbindung ab und du sendest denselben Aufruf mit derselben `requestId` erneut, bekommst du das erste Ergebnis zurück und die Änderung läuft nicht doppelt.
@@ -0,0 +1,305 @@
1
+ ---
2
+ title: "Tickets"
3
+ description: "API-Referenz für Tickets: jeder Handler mit seinen Feldern und einem Beispiel."
4
+ ---
5
+
6
+ ### ticket: detail
7
+
8
+ **Ticket anzeigen**
9
+
10
+ Liefert ein Ticket.
11
+
12
+ - Benötigter Scope: `tickets:read`
13
+ - Endpunkt: `POST /api/query`
14
+
15
+ | Feld | Typ | Pflicht | Beschreibung |
16
+ | --- | --- | --- | --- |
17
+ | `id` | string (uuid) | ja | Ticket-ID |
18
+
19
+ **Beispielanfrage**
20
+
21
+ ```bash
22
+ curl -X POST https://helpdesk.example.com/api/query \
23
+ -H "Authorization: Bearer $API_TOKEN" \
24
+ -H "Content-Type: application/json" \
25
+ -d '{
26
+ "type": "helpdesk:query:ticket:detail",
27
+ "payload": {
28
+ "id": "00000000-0000-4000-8000-000000000001"
29
+ }
30
+ }'
31
+ ```
32
+
33
+ **Beispielantwort**
34
+
35
+ Status: 200
36
+
37
+ ```json
38
+ {
39
+ "data": {
40
+ "id": "00000000-0000-4000-8000-000000000001",
41
+ "tenantId": "00000000-0000-4000-8000-000000000002",
42
+ "version": 1,
43
+ "insertedAt": "2026-01-15T09:30:00.000Z",
44
+ "modifiedAt": null,
45
+ "insertedById": "00000000-0000-4000-8000-000000000003",
46
+ "modifiedById": null,
47
+ "title": "Printer is on fire",
48
+ "status": "open",
49
+ "priority": "high"
50
+ }
51
+ }
52
+ ```
53
+
54
+ ### ticket: list
55
+
56
+ **Tickets auflisten**
57
+
58
+ Listet Tickets, neueste zuerst.
59
+
60
+ - Benötigter Scope: `tickets:read`
61
+ - Endpunkt: `POST /api/query`
62
+
63
+ | Feld | Typ | Pflicht | Beschreibung |
64
+ | --- | --- | --- | --- |
65
+ | `cursor` | string | nein | Position aus `nextCursor` der vorherigen Seite. |
66
+ | `limit` | integer | nein | Zeilen pro Seite, standardmäßig 50, höchstens 200. |
67
+ | `search` | string | nein | Volltextsuche über die durchsuchbaren Felder. |
68
+ | `sort` | string | nein | Feld, nach dem sortiert wird. |
69
+ | `sortDirection` | "asc" \| "desc" | nein | `asc` oder `desc`. |
70
+ | `offset` | integer | nein | Anzahl der zu überspringenden Zeilen. Nutze besser `cursor` zum Blättern. |
71
+ | `totalCount` | boolean | nein | Mit `true` bekommst du zusätzlich `total`, die Anzahl der passenden Zeilen. |
72
+ | `includeDeleted` | boolean | nein | Mit `true` sind gelöschte Zeilen enthalten. Nur für Entitäten mit Soft Delete. |
73
+ | `onlyDeleted` | boolean | nein | Mit `true` kommen nur gelöschte Zeilen zurück. Nur für Entitäten mit Soft Delete, nicht zusammen mit `includeDeleted`. |
74
+ | `filter` | object | nein | Ein Feldfilter mit `field`, `op` und `value`. `op` ist einer von `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
75
+ | `filter.field` | string | ja | |
76
+ | `filter.op` | "eq" \| "ne" \| "lt" \| "gt" \| "lte" \| "gte" \| "in" | ja | |
77
+ | `filter.value` | any | ja | |
78
+ | `filters` | array of object | nein | Mehrere Feldfilter, je mit `field`, `op` und `value`. `op` ist einer von `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
79
+ | `namedFilter` | string | nein | Name eines vordefinierten Filters der Entität, zum Beispiel einer Arbeitsliste. |
80
+ | `aggregate` | object | nein | Liefert aggregierte Werte statt Zeilen. |
81
+ | `aggregate.groupBy` | string | nein | |
82
+ | `aggregate.measures` | array of object | nein | |
83
+
84
+ **Beispielanfrage**
85
+
86
+ ```bash
87
+ curl -X POST https://helpdesk.example.com/api/query \
88
+ -H "Authorization: Bearer $API_TOKEN" \
89
+ -H "Content-Type: application/json" \
90
+ -d '{
91
+ "type": "helpdesk:query:ticket:list",
92
+ "payload": {}
93
+ }'
94
+ ```
95
+
96
+ **Beispielantwort**
97
+
98
+ Status: 200
99
+
100
+ ```json
101
+ {
102
+ "data": {
103
+ "rows": [
104
+ {
105
+ "id": "00000000-0000-4000-8000-000000000001",
106
+ "tenantId": "00000000-0000-4000-8000-000000000002",
107
+ "version": 1,
108
+ "insertedAt": "2026-01-15T09:30:00.000Z",
109
+ "modifiedAt": null,
110
+ "insertedById": "00000000-0000-4000-8000-000000000003",
111
+ "modifiedById": null,
112
+ "title": "Printer is on fire",
113
+ "status": "open",
114
+ "priority": "high"
115
+ }
116
+ ],
117
+ "nextCursor": null
118
+ }
119
+ }
120
+ ```
121
+
122
+ ### ticket: close
123
+
124
+ **Ticket schließen**
125
+
126
+ Schließt ein Ticket und hält fest, wie es gelöst wurde.
127
+
128
+ - Benötigter Scope: `tickets:write`
129
+ - Endpunkt: `POST /api/write`
130
+
131
+ | Feld | Typ | Pflicht | Beschreibung |
132
+ | --- | --- | --- | --- |
133
+ | `id` | string (uuid) | ja | Ticket |
134
+ | `resolution` | string | ja | Lösung |
135
+
136
+ **Beispielanfrage**
137
+
138
+ ```bash
139
+ curl -X POST https://helpdesk.example.com/api/write \
140
+ -H "Authorization: Bearer $API_TOKEN" \
141
+ -H "Content-Type: application/json" \
142
+ -d '{
143
+ "type": "helpdesk:write:ticket:close",
144
+ "payload": {
145
+ "id": "00000000-0000-4000-8000-000000000001",
146
+ "resolution": "Replaced the cartridge"
147
+ }
148
+ }'
149
+ ```
150
+
151
+ **Beispielantwort**
152
+
153
+ Status: 200
154
+
155
+ ```json
156
+ {
157
+ "isSuccess": true,
158
+ "data": {
159
+ "id": "00000000-0000-4000-8000-000000000001"
160
+ }
161
+ }
162
+ ```
163
+
164
+ ### ticket: create
165
+
166
+ **Ticket anlegen**
167
+
168
+ Legt ein neues Ticket an.
169
+
170
+ - Benötigter Scope: `tickets:write`
171
+ - Endpunkt: `POST /api/write`
172
+
173
+ | Feld | Typ | Pflicht | Beschreibung |
174
+ | --- | --- | --- | --- |
175
+ | `title` | string | ja | Titel |
176
+ | `status` | "open" \| "closed" | nein | Status |
177
+ | `priority` | "low" \| "normal" \| "high" | nein | Priorität |
178
+
179
+ **Beispielanfrage**
180
+
181
+ ```bash
182
+ curl -X POST https://helpdesk.example.com/api/write \
183
+ -H "Authorization: Bearer $API_TOKEN" \
184
+ -H "Content-Type: application/json" \
185
+ -d '{
186
+ "type": "helpdesk:write:ticket:create",
187
+ "payload": {
188
+ "title": "Printer is on fire",
189
+ "priority": "high"
190
+ }
191
+ }'
192
+ ```
193
+
194
+ **Beispielantwort**
195
+
196
+ Status: 200
197
+
198
+ ```json
199
+ {
200
+ "isSuccess": true,
201
+ "data": {
202
+ "kind": "save",
203
+ "id": "00000000-0000-4000-8000-000000000001",
204
+ "data": {
205
+ "id": "00000000-0000-4000-8000-000000000001",
206
+ "tenantId": "00000000-0000-4000-8000-000000000002",
207
+ "version": 1,
208
+ "insertedAt": "2026-01-15T09:30:00.000Z",
209
+ "modifiedAt": null,
210
+ "insertedById": "00000000-0000-4000-8000-000000000003",
211
+ "modifiedById": null,
212
+ "title": "Printer is on fire",
213
+ "status": "open",
214
+ "priority": "high"
215
+ },
216
+ "changes": {
217
+ "title": "Printer is on fire",
218
+ "status": "open",
219
+ "priority": "high"
220
+ },
221
+ "previous": {},
222
+ "isNew": true,
223
+ "entityName": "ticket"
224
+ }
225
+ }
226
+ ```
227
+
228
+ ### ticket: update
229
+
230
+ **Ticket ändern**
231
+
232
+ Ändert Titel oder Priorität eines Tickets.
233
+
234
+ - Benötigter Scope: `tickets:write`
235
+ - Endpunkt: `POST /api/write`
236
+
237
+ | Feld | Typ | Pflicht | Beschreibung |
238
+ | --- | --- | --- | --- |
239
+ | `id` | string (uuid) | ja | Ticket-ID |
240
+ | `version` | number | ja | |
241
+ | `changes` | object | ja | |
242
+ | `changes.title` | string | nein | Titel |
243
+ | `changes.status` | "open" \| "closed" | nein | Status |
244
+ | `changes.priority` | "low" \| "normal" \| "high" | nein | Priorität |
245
+
246
+ **Beispielanfrage**
247
+
248
+ ```bash
249
+ curl -X POST https://helpdesk.example.com/api/write \
250
+ -H "Authorization: Bearer $API_TOKEN" \
251
+ -H "Content-Type: application/json" \
252
+ -d '{
253
+ "type": "helpdesk:write:ticket:update",
254
+ "payload": {
255
+ "id": "00000000-0000-4000-8000-000000000001",
256
+ "version": 1,
257
+ "changes": {
258
+ "priority": "normal"
259
+ }
260
+ }
261
+ }'
262
+ ```
263
+
264
+ **Beispielantwort**
265
+
266
+ Status: 200
267
+
268
+ ```json
269
+ {
270
+ "isSuccess": true,
271
+ "data": {
272
+ "kind": "save",
273
+ "id": "00000000-0000-4000-8000-000000000001",
274
+ "data": {
275
+ "id": "00000000-0000-4000-8000-000000000001",
276
+ "tenantId": "00000000-0000-4000-8000-000000000002",
277
+ "version": 2,
278
+ "insertedAt": "2026-01-15T09:30:00.000Z",
279
+ "modifiedAt": "2026-01-15T09:30:00.000Z",
280
+ "insertedById": "00000000-0000-4000-8000-000000000003",
281
+ "modifiedById": "00000000-0000-4000-8000-000000000003",
282
+ "title": "Printer is on fire",
283
+ "status": "open",
284
+ "priority": "normal"
285
+ },
286
+ "changes": {
287
+ "priority": "normal"
288
+ },
289
+ "previous": {
290
+ "id": "00000000-0000-4000-8000-000000000001",
291
+ "tenantId": "00000000-0000-4000-8000-000000000002",
292
+ "version": 1,
293
+ "insertedAt": "2026-01-15T09:30:00.000Z",
294
+ "modifiedAt": null,
295
+ "insertedById": "00000000-0000-4000-8000-000000000003",
296
+ "modifiedById": null,
297
+ "title": "Printer is on fire",
298
+ "status": "open",
299
+ "priority": "high"
300
+ },
301
+ "isNew": false,
302
+ "entityName": "ticket"
303
+ }
304
+ }
305
+ ```
@@ -0,0 +1,66 @@
1
+ ---
2
+ title: "API-Tokens"
3
+ description: "Lege einen API-Token für Helpdesk an, wähle seine Scopes und sende ihn mit deinen Anfragen."
4
+ ---
5
+
6
+ Mit einem API-Token kann ein Skript oder ein anderer Dienst die API von Helpdesk in deinem Namen aufrufen. Seine Scopes bestimmen, welche Daten er lesen oder ändern darf.
7
+
8
+ ## Token anlegen
9
+
10
+ 1. Öffne Einstellungen › API-Tokens.
11
+ 2. Wähle **Neuen Token erstellen**.
12
+ 3. Gib einen Namen ein, wähle die Scopes und das Ablaufdatum und bestätige mit deinem Passwort.
13
+ 4. Kopiere den Token. Er beginnt mit `kpat_` und wird nur einmal angezeigt.
14
+
15
+ Ein Token läuft nach 90 Tagen ab, wenn du keinen anderen Ablauf wählst. Möglich sind höchstens 3650 Tage.
16
+
17
+ ## Token verwenden
18
+
19
+ Sende den Token im Header `Authorization`. Anfragen mit Token brauchen weder Cookie noch CSRF-Token.
20
+
21
+ ```bash
22
+ curl -X POST https://helpdesk.example.com/api/query \
23
+ -H "Authorization: Bearer $API_TOKEN" \
24
+ -H "Content-Type: application/json" \
25
+ -d '{
26
+ "type": "helpdesk:query:ticket:detail",
27
+ "payload": {
28
+ "id": "00000000-0000-4000-8000-000000000001"
29
+ }
30
+ }'
31
+ ```
32
+
33
+ ## Scopes
34
+
35
+ Jeder Scope hat zwei Stufen. `read` erlaubt die lesenden Handler. `write` erlaubt alles, was `read` erlaubt, und zusätzlich die schreibenden Handler.
36
+
37
+ | Scope | Berechtigung | Handler |
38
+ | --- | --- | --- |
39
+ | `tickets` (Tickets) | `tickets:read` | `helpdesk:query:ticket:detail`, `helpdesk:query:ticket:list` |
40
+ | `tickets` (Tickets) | `tickets:write` | `helpdesk:write:ticket:close`, `helpdesk:write:ticket:create`, `helpdesk:write:ticket:update` |
41
+
42
+ ## Ratenbegrenzung
43
+
44
+ Jeder Token darf 60 Anfragen pro 60 Sekunden senden. Darüber antwortet die API mit 429 `pat_rate_limited`.
45
+
46
+ API-Tokens sind in jedem Helpdesk-Tarif enthalten.
47
+
48
+ ## Fehler
49
+
50
+ | HTTP-Status | Code | Ursache |
51
+ | --- | --- | --- |
52
+ | 401 | `missing_token` | Es fehlt der Header `Authorization`. |
53
+ | 401 | `invalid_token` | Der Token ist unbekannt, widerrufen oder abgelaufen. |
54
+ | 403 | `access_denied` | Dem Token fehlt der Scope für diesen Handler. |
55
+ | 403 | `access_denied` | Der Endpunkt nimmt keine Tokens an. Tokens funktionieren nur an den API-Endpunkten. |
56
+ | 429 | `pat_rate_limited` | Zu viele Anfragen mit diesem Token. |
57
+
58
+ ## Token widerrufen
59
+
60
+ Widerrufe einen Token in Einstellungen › API-Tokens, sobald du ihn nicht mehr brauchst. Wenn du dein Passwort änderst, werden alle deine Tokens widerrufen. Ein Token handelt immer mit deinen aktuellen Rollen. Verlässt du das Konto oder wird dein Benutzer gelöscht, funktioniert er nicht mehr.
61
+
62
+ ## Sicherheit
63
+
64
+ - Behandle einen Token wie ein Passwort. Bewahre ihn in einem Secret Store auf, nie im Code, in einem Repository, in einer App oder Webseite oder in einem Log.
65
+ - Gib jedem Skript einen eigenen Token mit nur den Scopes, die es braucht.
66
+ - Widerrufe Tokens, die du nicht mehr nutzt. Widerrufe einen Token sofort, wenn er in fremde Hände gelangt sein könnte.
@@ -0,0 +1,62 @@
1
+ ---
2
+ title: "Webhook events"
3
+ description: "Webhook events: when they fire, which scope they need and what their payload contains."
4
+ ---
5
+
6
+ A webhook event tells your system that something changed. Every event has a name, a version and a payload. The scope listed for an event is the token scope that allows subscribing to it.
7
+
8
+ ## Delivery
9
+
10
+ Deliveries are signed so that you can verify the sender. A delivery that fails is retried a few times before it is dropped. Answer within a few seconds and treat repeated deliveries of the same event as one.
11
+
12
+ ## Versions
13
+
14
+ Adding an optional field keeps the version. A breaking change, such as removing or renaming a field or changing its type, gets a new version.
15
+
16
+ ## Events
17
+
18
+ ### ticket.closed
19
+
20
+ A ticket was closed and its resolution recorded.
21
+
22
+ - Version: `1`
23
+ - Required scope: `tickets:read`
24
+
25
+ | Field | Type | Required | Description |
26
+ | --- | --- | --- | --- |
27
+ | `id` | string (uuid) | yes | ID of the closed ticket |
28
+ | `resolution` | string | yes | How the ticket was resolved |
29
+
30
+ **Example payload**
31
+
32
+ ```json
33
+ {
34
+ "id": "00000000-0000-4000-8000-000000000001",
35
+ "resolution": "Replaced the roller"
36
+ }
37
+ ```
38
+
39
+ ### ticket.created
40
+
41
+ A record of type ticket was created.
42
+
43
+ - Version: `1`
44
+ - Required scope: `tickets:read`
45
+
46
+ | Field | Type | Required | Description |
47
+ | --- | --- | --- | --- |
48
+ | `id` | string (uuid) | yes | Ticket ID |
49
+ | `title` | string | yes | Title |
50
+ | `status` | "open" \| "closed" | yes | Status |
51
+ | `priority` | "low" \| "normal" \| "high" | yes | Priority |
52
+
53
+ **Example payload**
54
+
55
+ ```json
56
+ {
57
+ "id": "00000000-0000-4000-8000-000000000001",
58
+ "title": "Scanner jams",
59
+ "status": "open",
60
+ "priority": "low"
61
+ }
62
+ ```