@cosmicdrift/kumiko-samples 0.410.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.
- package/package.json +1 -1
- package/packages/bundled-features/package.json +31 -1
- package/packages/bundled-features/src/agent-tools/agent-doc-lint.ts +64 -3
- package/packages/bundled-features/src/agent-tools/agent-manifest.ts +13 -130
- package/packages/bundled-features/src/agent-tools/api-docs/anchors.ts +60 -0
- package/packages/bundled-features/src/agent-tools/api-docs/check.ts +25 -0
- package/packages/bundled-features/src/agent-tools/api-docs/collect-events.ts +140 -0
- package/packages/bundled-features/src/agent-tools/api-docs/collect.ts +175 -0
- package/packages/bundled-features/src/agent-tools/api-docs/curl.ts +28 -0
- package/packages/bundled-features/src/agent-tools/api-docs/error-table.ts +45 -0
- package/packages/bundled-features/src/agent-tools/api-docs/examples.ts +43 -0
- package/packages/bundled-features/src/agent-tools/api-docs/generate.ts +179 -0
- package/packages/bundled-features/src/agent-tools/api-docs/index-json.ts +29 -0
- package/packages/bundled-features/src/agent-tools/api-docs/index.ts +21 -0
- package/packages/bundled-features/src/agent-tools/api-docs/list-parameters.ts +38 -0
- package/packages/bundled-features/src/agent-tools/api-docs/markdown.ts +70 -0
- package/packages/bundled-features/src/agent-tools/api-docs/menu-path.ts +82 -0
- package/packages/bundled-features/src/agent-tools/api-docs/model.ts +83 -0
- package/packages/bundled-features/src/agent-tools/api-docs/problems.ts +58 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-events.ts +76 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-openapi.ts +216 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-overview.ts +86 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-reference.ts +79 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-tokens.ts +136 -0
- package/packages/bundled-features/src/agent-tools/api-docs/schema-fields.ts +167 -0
- package/packages/bundled-features/src/agent-tools/api-docs/section-ids.ts +28 -0
- package/packages/bundled-features/src/agent-tools/api-docs/system-only.ts +11 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/de.ts +166 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/en.ts +159 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/es.ts +162 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/fr.ts +169 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/index.ts +67 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/it.ts +165 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/types.ts +130 -0
- package/packages/bundled-features/src/agent-tools/api-docs/ui-writes.ts +81 -0
- package/packages/bundled-features/src/agent-tools/changes.json +24 -0
- package/packages/bundled-features/src/agent-tools/handler-schema.ts +45 -0
- package/packages/bundled-features/src/agent-tools/index.ts +24 -0
- package/packages/bundled-features/src/agent-tools/labels.ts +181 -0
- package/packages/bundled-features/src/auth-email-password/changes.json +24 -0
- package/packages/bundled-features/src/auth-email-password/seeding.ts +84 -6
- package/packages/bundled-features/src/auth-email-password/web/i18n.ts +1 -0
- package/packages/bundled-features/src/auth-email-password/web/signup-screen.tsx +48 -3
- package/packages/bundled-features/src/auth-email-password/web/static-account.ts +190 -0
- package/packages/bundled-features/src/auth-email-password/web/static-client.ts +226 -0
- package/packages/bundled-features/src/foundation-shared/demo-admin-env.ts +11 -0
- package/packages/bundled-features/src/foundation-shared/index.ts +5 -1
- package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
- package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +99 -71
- package/packages/bundled-features/src/inbound-mail-foundation/feature.ts +2 -2
- package/packages/bundled-features/src/inbound-provider-imap/changes.json +6 -0
- package/packages/bundled-features/src/inbound-provider-imap/imap-client.ts +3 -1
- package/packages/bundled-features/src/personal-access-tokens/changes.json +6 -0
- package/packages/bundled-features/src/personal-access-tokens/feature.ts +5 -2
- package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts +7 -2
- package/packages/bundled-features/src/personal-access-tokens/i18n.ts +6 -1
- package/packages/bundled-features/src/personal-access-tokens/index.ts +37 -2
- package/packages/bundled-features/src/personal-access-tokens/scope-events-check.ts +28 -0
- package/packages/bundled-features/src/personal-access-tokens/screens.ts +9 -1
- package/packages/bundled-features/src/personal-access-tokens/web/constants.ts +1 -0
- package/packages/bundled-features/src/personal-access-tokens/web/scopes.ts +14 -0
- package/packages/bundled-features/src/presence/changes.json +8 -0
- package/packages/bundled-features/src/presence/feature.ts +25 -0
- package/packages/bundled-features/src/presence/handlers/heartbeat.write.ts +52 -0
- package/packages/bundled-features/src/presence/handlers/leave.write.ts +41 -0
- package/packages/bundled-features/src/presence/handlers/list.query.ts +39 -0
- package/packages/bundled-features/src/presence/index.ts +7 -0
- package/packages/bundled-features/src/presence/options.ts +30 -0
- package/packages/bundled-features/src/presence/payloads.ts +26 -0
- package/packages/bundled-features/src/presence/room.ts +65 -0
- package/packages/bundled-features/src/presence/store.ts +185 -0
- package/packages/bundled-features/src/sessions/feature.ts +6 -2
- package/packages/bundled-features/src/sessions/handlers/last-activity-probe.route.ts +19 -0
- package/packages/bundled-features/src/tenant-inactivity/changes.json +12 -0
- package/packages/bundled-features/src/tenant-inactivity/check-inactive-tenants.ts +14 -6
- package/packages/bundled-features/src/tenant-inactivity/constants.ts +4 -1
- package/packages/bundled-features/src/tenant-inactivity/handlers/inactivity-state.query.ts +2 -1
- package/packages/bundled-features/src/tenant-inactivity/handlers/keep-account.write.ts +2 -1
- package/packages/bundled-features/src/tenant-inactivity/options.ts +1 -0
- package/packages/bundled-features/src/tenant-inactivity/remote-activity.ts +6 -1
- package/packages/bundled-features/src/tenant-inactivity/static-keep-account.ts +37 -0
- package/packages/bundled-features/src/tenant-lifecycle/constants.ts +2 -0
- package/packages/bundled-features/src/tenant-lifecycle/handlers/cancel-destruction.write.ts +6 -2
- package/packages/bundled-features/src/tenant-lifecycle/handlers/request-destruction.write.ts +2 -1
- package/packages/bundled-features/src/tenant-lifecycle/index.ts +1 -0
- package/packages/bundled-features/src/waitlist/changes.json +6 -0
- package/packages/bundled-features/src/waitlist/static-submit.ts +56 -0
- package/samples/apps/styleguide/src/features/widgets/i18n.ts +143 -0
- package/samples/apps/styleguide/src/features/widgets/web/VariantsDemo.tsx +276 -0
- package/samples/apps/styleguide/src/features/widgets/web/Widgets.tsx +3 -0
- package/samples/apps/styleguide/src/features/workboard/feature.ts +1 -0
- package/samples/apps/use-all-bundled/feature-manifest.json +23 -1
- package/samples/apps/use-all-bundled/src/run-config.ts +3 -0
- package/samples/recipes/api-docs/README.md +52 -0
- package/samples/recipes/api-docs/api-docs/de/events.md +62 -0
- package/samples/recipes/api-docs/api-docs/de/overview.md +100 -0
- package/samples/recipes/api-docs/api-docs/de/reference/tickets.md +305 -0
- package/samples/recipes/api-docs/api-docs/de/tokens.md +66 -0
- package/samples/recipes/api-docs/api-docs/en/events.md +62 -0
- package/samples/recipes/api-docs/api-docs/en/overview.md +100 -0
- package/samples/recipes/api-docs/api-docs/en/reference/tickets.md +305 -0
- package/samples/recipes/api-docs/api-docs/en/tokens.md +66 -0
- package/samples/recipes/api-docs/api-docs/index.json +371 -0
- package/samples/recipes/api-docs/api-docs/openapi.json +982 -0
- package/samples/recipes/api-docs/api-examples/ticket-close.json +21 -0
- package/samples/recipes/api-docs/api-examples/ticket-create.json +42 -0
- package/samples/recipes/api-docs/api-examples/ticket-detail.json +28 -0
- package/samples/recipes/api-docs/api-examples/ticket-list.json +31 -0
- package/samples/recipes/api-docs/api-examples/ticket-update.json +54 -0
- package/samples/recipes/api-docs/api-examples/webhooks/ticket-closed.json +8 -0
- package/samples/recipes/api-docs/api-examples/webhooks/ticket-created.json +10 -0
- package/samples/recipes/api-docs/kumiko.config.ts +33 -0
- package/samples/recipes/api-docs/package.json +14 -0
- package/samples/recipes/api-docs/src/feature.ts +218 -0
- package/samples/recipes/api-docs/tsconfig.json +22 -0
- package/samples/recipes/realtime-sse/README.md +1 -0
- package/samples/recipes/realtime-sse/package.json +1 -0
- package/samples/recipes/realtime-sse/src/feature.ts +9 -0
- package/samples/recipes/record-detail-layout/README.md +1 -0
- package/samples/recipes/record-detail-layout/src/feature.ts +10 -0
- package/samples/recipes/wizard-form/README.md +9 -0
- package/samples/recipes/wizard-form/src/feature.ts +13 -2
|
@@ -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
|
+
```
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "HTTP API"
|
|
3
|
+
description: "Endpoints, request body, responses, error codes, lists and batches of the HTTP API."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Every call is a POST with a JSON body. The `type` field names the handler, `payload` carries its fields. The reference pages list every handler with its fields.
|
|
7
|
+
|
|
8
|
+
## Endpoints
|
|
9
|
+
|
|
10
|
+
| Endpoint | |
|
|
11
|
+
| --- | --- |
|
|
12
|
+
| `POST /api/query` | Reads data. Never changes anything. |
|
|
13
|
+
| `POST /api/write` | Changes data: create, update, delete or a specific action. |
|
|
14
|
+
| `POST /api/batch` | Runs several write calls in one transaction. |
|
|
15
|
+
|
|
16
|
+
## Authentication
|
|
17
|
+
|
|
18
|
+
Send an API token in the `Authorization` header as `Bearer <token>`. Requests with a token need no cookie and no CSRF token. The token also fixes the account the request runs in, so you never send an account or tenant ID.
|
|
19
|
+
|
|
20
|
+
## Request body
|
|
21
|
+
|
|
22
|
+
`type` is the handler name, for example `helpdesk:query:ticket:detail`. `payload` holds the fields from the reference. `requestId` is optional, see below. The payload may be nested at most 20 levels deep.
|
|
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
|
+
## Responses
|
|
37
|
+
|
|
38
|
+
A successful read returns `data`. A successful write returns `isSuccess: true` and `data`.
|
|
39
|
+
|
|
40
|
+
On failure the HTTP status is 4xx or 5xx and the body contains `error`. Write calls also return `isSuccess: false`. Branch on `error.code` and the status. `message` is meant for people and may change.
|
|
41
|
+
|
|
42
|
+
## Error codes
|
|
43
|
+
|
|
44
|
+
| Code | HTTP status | Meaning |
|
|
45
|
+
| --- | --- | --- |
|
|
46
|
+
| `ambiguous_auth` | 400 | The request carried both a session cookie and a token. Send only one. |
|
|
47
|
+
| `validation_error` | 400 | The payload does not match the handler's fields. `details` names the fields. |
|
|
48
|
+
| `invalid_token` | 401 | The token is unknown, revoked or expired. |
|
|
49
|
+
| `missing_token` | 401 | The `Authorization` header is missing. |
|
|
50
|
+
| `unauthenticated` | 401 | No valid credentials were sent. |
|
|
51
|
+
| `access_denied` | 403 | The token lacks the scope for this handler, or the endpoint does not accept tokens. |
|
|
52
|
+
| `feature_disabled` | 403 | This function is switched off or not part of your plan. |
|
|
53
|
+
| `not_found` | 404 | The record does not exist or you cannot see it. |
|
|
54
|
+
| `conflict` | 409 | The change conflicts with the current state of the data. |
|
|
55
|
+
| `idempotent_replay` | 409 | This change was already applied under the same idempotency key. The first attempt succeeded, so do not send it again. |
|
|
56
|
+
| `precondition_failed` | 409 | A field of the record no longer has the value the change expected. Read the record again and retry. |
|
|
57
|
+
| `record_locked` | 409 | Another change holds a lock on the record. Retry shortly. |
|
|
58
|
+
| `unique_violation` | 409 | A record with this value already exists. |
|
|
59
|
+
| `version_conflict` | 409 | The record changed after you read it. Read it again and retry with the new `version`. |
|
|
60
|
+
| `unconfigured` | 422 | A setting this function needs is still empty. Set it up in the app first, then retry. |
|
|
61
|
+
| `unprocessable` | 422 | The data is valid, but a business rule rejects the change. `details.reason` names the rule. |
|
|
62
|
+
| `pat_rate_limited` | 429 | This token sent too many requests in a short time. Wait a moment and retry. |
|
|
63
|
+
| `rate_limited` | 429 | Too many requests. Wait as many seconds as the `Retry-After` header says. |
|
|
64
|
+
| `internal_error` | 500 | Unexpected server error. Retry later. |
|
|
65
|
+
| `rate_limit_unavailable` | 503 | The rate limiter is temporarily unavailable, so the request was refused. Retry shortly. |
|
|
66
|
+
| `member_read_timeout` | 504 | A read on the server took too long and was stopped. Retry later. |
|
|
67
|
+
|
|
68
|
+
## Versions and conflicts
|
|
69
|
+
|
|
70
|
+
Every record has a `version`. An update takes the `version` you read last. If someone changed the record in between, the call fails with 409 `version_conflict`. Read the record again, check the change and send it with the new version.
|
|
71
|
+
|
|
72
|
+
## Lists
|
|
73
|
+
|
|
74
|
+
List handlers end in `:list` and accept these fields:
|
|
75
|
+
|
|
76
|
+
| Field | Type | Description |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| `cursor` | string | Position from `nextCursor` of the previous page. |
|
|
79
|
+
| `limit` | integer | Rows per page, 50 by default, at most 200. |
|
|
80
|
+
| `search` | string | Full-text search across the searchable fields. |
|
|
81
|
+
| `sort` | string | Field to sort by. |
|
|
82
|
+
| `sortDirection` | "asc" \| "desc" | `asc` or `desc`. |
|
|
83
|
+
| `offset` | integer | Number of rows to skip. Prefer `cursor` for paging. |
|
|
84
|
+
| `totalCount` | boolean | Set `true` to also get `total`, the number of matching rows. |
|
|
85
|
+
| `includeDeleted` | boolean | Set `true` to include deleted rows. Only for entities with soft delete. |
|
|
86
|
+
| `onlyDeleted` | boolean | Set `true` to return only deleted rows. Only for entities with soft delete, not together with `includeDeleted`. |
|
|
87
|
+
| `filter` | object | One field filter with `field`, `op` and `value`. `op` is one of `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
|
|
88
|
+
| `filters` | array of object | Several field filters, each with `field`, `op` and `value`. `op` is one of `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`. |
|
|
89
|
+
| `namedFilter` | string | Name of a predefined filter of the entity, for example a work queue. |
|
|
90
|
+
| `aggregate` | object | Returns aggregated values instead of rows. |
|
|
91
|
+
|
|
92
|
+
The response contains `rows` and `nextCursor`. For the next page send `nextCursor` as `cursor`. On the last page `nextCursor` is `null`.
|
|
93
|
+
|
|
94
|
+
## Batches
|
|
95
|
+
|
|
96
|
+
`POST /api/batch` takes `commands`, a list of `{ type, payload }` write calls. They run in one transaction: if one fails, none takes effect. The response then has `isSuccess: false`, the `error` and `failedIndex`, the position of the failed command counted from 0.
|
|
97
|
+
|
|
98
|
+
## Safe retries
|
|
99
|
+
|
|
100
|
+
Send a `requestId` with write and batch calls, any string that is unique per change. If the connection drops and you send the same call again with the same `requestId`, you get the first result back and the change does not run twice.
|