@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.
Files changed (122) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +31 -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/auth-email-password/changes.json +24 -0
  41. package/packages/bundled-features/src/auth-email-password/seeding.ts +84 -6
  42. package/packages/bundled-features/src/auth-email-password/web/i18n.ts +1 -0
  43. package/packages/bundled-features/src/auth-email-password/web/signup-screen.tsx +48 -3
  44. package/packages/bundled-features/src/auth-email-password/web/static-account.ts +190 -0
  45. package/packages/bundled-features/src/auth-email-password/web/static-client.ts +226 -0
  46. package/packages/bundled-features/src/foundation-shared/demo-admin-env.ts +11 -0
  47. package/packages/bundled-features/src/foundation-shared/index.ts +5 -1
  48. package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
  49. package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +99 -71
  50. package/packages/bundled-features/src/inbound-mail-foundation/feature.ts +2 -2
  51. package/packages/bundled-features/src/inbound-provider-imap/changes.json +6 -0
  52. package/packages/bundled-features/src/inbound-provider-imap/imap-client.ts +3 -1
  53. package/packages/bundled-features/src/personal-access-tokens/changes.json +6 -0
  54. package/packages/bundled-features/src/personal-access-tokens/feature.ts +5 -2
  55. package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts +7 -2
  56. package/packages/bundled-features/src/personal-access-tokens/i18n.ts +6 -1
  57. package/packages/bundled-features/src/personal-access-tokens/index.ts +37 -2
  58. package/packages/bundled-features/src/personal-access-tokens/scope-events-check.ts +28 -0
  59. package/packages/bundled-features/src/personal-access-tokens/screens.ts +9 -1
  60. package/packages/bundled-features/src/personal-access-tokens/web/constants.ts +1 -0
  61. package/packages/bundled-features/src/personal-access-tokens/web/scopes.ts +14 -0
  62. package/packages/bundled-features/src/presence/changes.json +8 -0
  63. package/packages/bundled-features/src/presence/feature.ts +25 -0
  64. package/packages/bundled-features/src/presence/handlers/heartbeat.write.ts +52 -0
  65. package/packages/bundled-features/src/presence/handlers/leave.write.ts +41 -0
  66. package/packages/bundled-features/src/presence/handlers/list.query.ts +39 -0
  67. package/packages/bundled-features/src/presence/index.ts +7 -0
  68. package/packages/bundled-features/src/presence/options.ts +30 -0
  69. package/packages/bundled-features/src/presence/payloads.ts +26 -0
  70. package/packages/bundled-features/src/presence/room.ts +65 -0
  71. package/packages/bundled-features/src/presence/store.ts +185 -0
  72. package/packages/bundled-features/src/sessions/feature.ts +6 -2
  73. package/packages/bundled-features/src/sessions/handlers/last-activity-probe.route.ts +19 -0
  74. package/packages/bundled-features/src/tenant-inactivity/changes.json +12 -0
  75. package/packages/bundled-features/src/tenant-inactivity/check-inactive-tenants.ts +14 -6
  76. package/packages/bundled-features/src/tenant-inactivity/constants.ts +4 -1
  77. package/packages/bundled-features/src/tenant-inactivity/handlers/inactivity-state.query.ts +2 -1
  78. package/packages/bundled-features/src/tenant-inactivity/handlers/keep-account.write.ts +2 -1
  79. package/packages/bundled-features/src/tenant-inactivity/options.ts +1 -0
  80. package/packages/bundled-features/src/tenant-inactivity/remote-activity.ts +6 -1
  81. package/packages/bundled-features/src/tenant-inactivity/static-keep-account.ts +37 -0
  82. package/packages/bundled-features/src/tenant-lifecycle/constants.ts +2 -0
  83. package/packages/bundled-features/src/tenant-lifecycle/handlers/cancel-destruction.write.ts +6 -2
  84. package/packages/bundled-features/src/tenant-lifecycle/handlers/request-destruction.write.ts +2 -1
  85. package/packages/bundled-features/src/tenant-lifecycle/index.ts +1 -0
  86. package/packages/bundled-features/src/waitlist/changes.json +6 -0
  87. package/packages/bundled-features/src/waitlist/static-submit.ts +56 -0
  88. package/samples/apps/styleguide/src/features/widgets/i18n.ts +143 -0
  89. package/samples/apps/styleguide/src/features/widgets/web/VariantsDemo.tsx +276 -0
  90. package/samples/apps/styleguide/src/features/widgets/web/Widgets.tsx +3 -0
  91. package/samples/apps/styleguide/src/features/workboard/feature.ts +1 -0
  92. package/samples/apps/use-all-bundled/feature-manifest.json +23 -1
  93. package/samples/apps/use-all-bundled/src/run-config.ts +3 -0
  94. package/samples/recipes/api-docs/README.md +52 -0
  95. package/samples/recipes/api-docs/api-docs/de/events.md +62 -0
  96. package/samples/recipes/api-docs/api-docs/de/overview.md +100 -0
  97. package/samples/recipes/api-docs/api-docs/de/reference/tickets.md +305 -0
  98. package/samples/recipes/api-docs/api-docs/de/tokens.md +66 -0
  99. package/samples/recipes/api-docs/api-docs/en/events.md +62 -0
  100. package/samples/recipes/api-docs/api-docs/en/overview.md +100 -0
  101. package/samples/recipes/api-docs/api-docs/en/reference/tickets.md +305 -0
  102. package/samples/recipes/api-docs/api-docs/en/tokens.md +66 -0
  103. package/samples/recipes/api-docs/api-docs/index.json +371 -0
  104. package/samples/recipes/api-docs/api-docs/openapi.json +982 -0
  105. package/samples/recipes/api-docs/api-examples/ticket-close.json +21 -0
  106. package/samples/recipes/api-docs/api-examples/ticket-create.json +42 -0
  107. package/samples/recipes/api-docs/api-examples/ticket-detail.json +28 -0
  108. package/samples/recipes/api-docs/api-examples/ticket-list.json +31 -0
  109. package/samples/recipes/api-docs/api-examples/ticket-update.json +54 -0
  110. package/samples/recipes/api-docs/api-examples/webhooks/ticket-closed.json +8 -0
  111. package/samples/recipes/api-docs/api-examples/webhooks/ticket-created.json +10 -0
  112. package/samples/recipes/api-docs/kumiko.config.ts +33 -0
  113. package/samples/recipes/api-docs/package.json +14 -0
  114. package/samples/recipes/api-docs/src/feature.ts +218 -0
  115. package/samples/recipes/api-docs/tsconfig.json +22 -0
  116. package/samples/recipes/realtime-sse/README.md +1 -0
  117. package/samples/recipes/realtime-sse/package.json +1 -0
  118. package/samples/recipes/realtime-sse/src/feature.ts +9 -0
  119. package/samples/recipes/record-detail-layout/README.md +1 -0
  120. package/samples/recipes/record-detail-layout/src/feature.ts +10 -0
  121. package/samples/recipes/wizard-form/README.md +9 -0
  122. package/samples/recipes/wizard-form/src/feature.ts +13 -2
@@ -0,0 +1,276 @@
1
+ // Opt-in widget variants, one block each, for screenshot review.
2
+
3
+ import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
4
+ import {
5
+ ChoiceCards,
6
+ Composer,
7
+ DetailList,
8
+ ModeSwitch,
9
+ PageSection,
10
+ SectionCard,
11
+ SectionNavLayout,
12
+ SideBySideTable,
13
+ StepBar,
14
+ TextareaField,
15
+ } from "@cosmicdrift/kumiko-renderer/web";
16
+ import { type ReactNode, useState } from "react";
17
+
18
+ type DemoMode = "auto" | "manual" | "questions" | "locked";
19
+
20
+ type DemoChoice = "empty" | "service" | "guests";
21
+
22
+ export function VariantsRoundTwoDemo(): ReactNode {
23
+ const t = useTranslation();
24
+ const { Heading, Banner, Button, Text } = usePrimitives();
25
+ const [choice, setChoice] = useState<DemoChoice | null>("service");
26
+ const [mode, setMode] = useState<DemoMode>("manual");
27
+ const [message, setMessage] = useState("");
28
+
29
+ return (
30
+ <SectionCard title={t("widgets:catalog:variants-round2-title")} testId="variants-round2-demo">
31
+ <div className="flex flex-col gap-6">
32
+ <div className="flex flex-col gap-2" data-testid="variants-choice">
33
+ <Heading variant="group">{t("widgets:catalog:variants-choice")}</Heading>
34
+ <ChoiceCards
35
+ value={choice}
36
+ onChange={setChoice}
37
+ columns={3}
38
+ variant="radio"
39
+ label={t("widgets:catalog:variants-choice-label")}
40
+ options={[
41
+ {
42
+ value: "empty",
43
+ title: t("widgets:catalog:variants-choice-empty"),
44
+ description: t("widgets:catalog:variants-choice-empty-desc"),
45
+ },
46
+ {
47
+ value: "service",
48
+ title: t("widgets:catalog:variants-choice-service"),
49
+ description: t("widgets:catalog:variants-choice-service-desc"),
50
+ },
51
+ {
52
+ value: "guests",
53
+ title: t("widgets:catalog:variants-choice-guests"),
54
+ description: t("widgets:catalog:variants-choice-guests-desc"),
55
+ },
56
+ ]}
57
+ />
58
+ </div>
59
+
60
+ <div className="flex flex-col gap-2" data-testid="variants-mode-wide">
61
+ <Heading variant="group">{t("widgets:catalog:variants-mode-wide")}</Heading>
62
+ <ModeSwitch
63
+ value={mode}
64
+ onChange={setMode}
65
+ segmentWidth="wide"
66
+ className="w-fit"
67
+ options={[
68
+ { value: "auto", label: t("widgets:catalog:variants-mode-a") },
69
+ { value: "manual", label: t("widgets:catalog:variants-mode-b") },
70
+ { value: "questions", label: t("widgets:catalog:variants-mode-c"), tone: "warning" },
71
+ ]}
72
+ />
73
+ </div>
74
+
75
+ <div className="flex flex-col gap-2" data-testid="variants-compare">
76
+ <Heading variant="group">{t("widgets:catalog:variants-compare")}</Heading>
77
+ <SideBySideTable
78
+ caption={t("widgets:catalog:variants-compare")}
79
+ rowHeaderLabel={t("widgets:catalog:variants-compare-field")}
80
+ rowHeaderTone="foreground"
81
+ columns={[
82
+ { id: "doc", label: t("widgets:catalog:variants-compare-left") },
83
+ { id: "stock", label: t("widgets:catalog:variants-compare-right") },
84
+ ]}
85
+ rows={[
86
+ {
87
+ id: "name",
88
+ header: t("widgets:catalog:variants-compare-name"),
89
+ cells: [{ content: t("widgets:catalog:variants-value-owner"), colSpan: 2 }],
90
+ },
91
+ {
92
+ id: "city",
93
+ header: t("widgets:catalog:variants-compare-city"),
94
+ cells: [{ content: "Frankfurt" }, { content: "Hamburg" }],
95
+ },
96
+ ]}
97
+ />
98
+ </div>
99
+
100
+ <div className="flex flex-col gap-2" data-testid="variants-docked">
101
+ <Heading variant="group">{t("widgets:catalog:variants-docked")}</Heading>
102
+ <div className="h-64 overflow-y-auto rounded-md border border-border">
103
+ <PageSection className="flex min-h-full flex-col">
104
+ {Array.from({ length: 12 }, (_, index) => (
105
+ <Text key={`line-${index.toString()}`} variant="muted">
106
+ {t("widgets:catalog:variants-docked-message")}
107
+ </Text>
108
+ ))}
109
+ <Composer
110
+ docked
111
+ value={message}
112
+ onChange={setMessage}
113
+ onSubmit={() => setMessage("")}
114
+ placeholder={t("widgets:catalog:variants-composer-placeholder")}
115
+ submitLabel={t("widgets:catalog:variants-composer-send")}
116
+ testId="variants-docked-composer"
117
+ />
118
+ </PageSection>
119
+ </div>
120
+ </div>
121
+
122
+ <div className="flex flex-col gap-2" data-testid="variants-banner-below">
123
+ <Heading variant="group">{t("widgets:catalog:variants-banner-below")}</Heading>
124
+ <Banner
125
+ variant="error"
126
+ icon="alert-triangle"
127
+ title={t("widgets:catalog:variants-banner-below-title")}
128
+ actionsPlacement="below"
129
+ actions={
130
+ <Button variant="secondary" size="sm">
131
+ {t("widgets:catalog:variants-banner-below-action")}
132
+ </Button>
133
+ }
134
+ >
135
+ {t("widgets:catalog:variants-banner-below-body")}
136
+ </Banner>
137
+ </div>
138
+
139
+ <div className="flex flex-col gap-2" data-testid="variants-rail">
140
+ <Heading variant="group">{t("widgets:catalog:variants-rail")}</Heading>
141
+ <div className="flex h-96 border border-border">
142
+ <StepBar
143
+ orientation="vertical"
144
+ steps={[
145
+ t("widgets:catalog:variants-rail-step-one"),
146
+ t("widgets:catalog:variants-rail-step-two"),
147
+ ]}
148
+ currentIndex={0}
149
+ compactLabel={t("widgets:catalog:variants-rail-heading")}
150
+ heading={t("widgets:catalog:variants-rail-heading")}
151
+ subtitles={[undefined, t("widgets:catalog:variants-rail-subtitle")]}
152
+ upNext={{
153
+ heading: t("widgets:catalog:variants-rail-up-next"),
154
+ title: t("widgets:catalog:variants-rail-step-two"),
155
+ subtitle: t("widgets:catalog:variants-rail-hint"),
156
+ }}
157
+ testId="variants-rail-steps"
158
+ />
159
+ </div>
160
+ </div>
161
+ </div>
162
+ </SectionCard>
163
+ );
164
+ }
165
+
166
+ export function VariantsDemo(): ReactNode {
167
+ const t = useTranslation();
168
+ const { Heading, Banner } = usePrimitives();
169
+ const [mode, setMode] = useState<DemoMode>("auto");
170
+ const [note, setNote] = useState("");
171
+ const [message, setMessage] = useState("");
172
+
173
+ const detailRows = [
174
+ {
175
+ label: t("widgets:catalog:variants-label-owner"),
176
+ value: t("widgets:catalog:variants-value-owner"),
177
+ },
178
+ {
179
+ label: t("widgets:catalog:variants-label-region"),
180
+ value: t("widgets:catalog:variants-value-region"),
181
+ },
182
+ {
183
+ label: t("widgets:catalog:variants-label-plan"),
184
+ value: t("widgets:catalog:variants-value-plan"),
185
+ },
186
+ ];
187
+
188
+ const navSections = ["profile", "billing", "security"].map((id) => ({
189
+ id: `variants-nav-${id}`,
190
+ title: t(`widgets:catalog:variants-nav-${id}`),
191
+ }));
192
+
193
+ return (
194
+ <SectionCard title={t("widgets:catalog:variants-title")} testId="variants-demo">
195
+ <div className="flex flex-col gap-6">
196
+ <div className="flex flex-col gap-2" data-testid="variants-heading">
197
+ <Heading variant="group">{t("widgets:catalog:variants-heading-group")}</Heading>
198
+ <Heading variant="section">{t("widgets:catalog:variants-heading-section")}</Heading>
199
+ </div>
200
+
201
+ <div className="grid gap-6 md:grid-cols-[1fr_280px]">
202
+ <div data-testid="variants-detail-normal">
203
+ <Heading variant="group">{t("widgets:catalog:variants-detail-normal")}</Heading>
204
+ <DetailList rows={detailRows} valueWeight="normal" />
205
+ </div>
206
+ <div data-testid="variants-detail-sidebar">
207
+ <Heading variant="group">{t("widgets:catalog:variants-detail-sidebar")}</Heading>
208
+ <DetailList rows={detailRows} valueWeight="normal" layout="sidebar" />
209
+ </div>
210
+ </div>
211
+
212
+ <div className="flex flex-col gap-2" data-testid="variants-mode-switch">
213
+ <Heading variant="group">{t("widgets:catalog:variants-mode-switch")}</Heading>
214
+ <ModeSwitch
215
+ value={mode}
216
+ onChange={setMode}
217
+ options={[
218
+ { value: "auto", label: t("widgets:catalog:variants-mode-a") },
219
+ { value: "manual", label: t("widgets:catalog:variants-mode-b") },
220
+ { value: "questions", label: t("widgets:catalog:variants-mode-c"), tone: "warning" },
221
+ { value: "locked", label: t("widgets:catalog:variants-mode-d"), disabled: true },
222
+ ]}
223
+ />
224
+ </div>
225
+
226
+ <div data-testid="variants-banner">
227
+ <Banner
228
+ variant="warning"
229
+ icon="alert-triangle"
230
+ parts={[
231
+ { text: t("widgets:catalog:variants-banner-lead") },
232
+ { text: t("widgets:catalog:variants-banner-strong"), strong: true },
233
+ { text: t("widgets:catalog:variants-banner-tail") },
234
+ ]}
235
+ />
236
+ </div>
237
+
238
+ <TextareaField
239
+ label={t("widgets:catalog:variants-textarea-placeholder")}
240
+ id="variants-textarea"
241
+ name="variants-textarea"
242
+ value={note}
243
+ onChange={setNote}
244
+ placeholder={t("widgets:catalog:variants-textarea-hint")}
245
+ testId="variants-textarea"
246
+ />
247
+
248
+ <div className="flex min-h-40 flex-col" data-testid="variants-composer-host">
249
+ <Heading variant="group">{t("widgets:catalog:variants-composer")}</Heading>
250
+ <Composer
251
+ value={message}
252
+ onChange={setMessage}
253
+ onSubmit={() => setMessage("")}
254
+ placeholder={t("widgets:catalog:variants-composer-placeholder")}
255
+ submitLabel={t("widgets:catalog:variants-composer-send")}
256
+ testId="variants-composer"
257
+ />
258
+ </div>
259
+
260
+ <div className="flex flex-col gap-2" data-testid="variants-section-nav">
261
+ <Heading variant="group">{t("widgets:catalog:variants-section-nav")}</Heading>
262
+ <SectionNavLayout items={navSections} testId="variants-section-nav-layout">
263
+ {navSections.map((section) => (
264
+ <section key={section.id} id={section.id} className="flex flex-col gap-1">
265
+ <Heading variant="group">{section.title}</Heading>
266
+ <p className="text-sm text-muted-foreground">
267
+ {t("widgets:catalog:variants-nav-body")}
268
+ </p>
269
+ </section>
270
+ ))}
271
+ </SectionNavLayout>
272
+ </div>
273
+ </div>
274
+ </SectionCard>
275
+ );
276
+ }
@@ -42,6 +42,7 @@ import { Wallet } from "lucide-react";
42
42
  import { type ReactNode, useEffect, useMemo, useState } from "react";
43
43
  import { euro, percent } from "../lib/format";
44
44
  import { InboxReaderExamples } from "./InboxReaderExamples";
45
+ import { VariantsDemo, VariantsRoundTwoDemo } from "./VariantsDemo";
45
46
 
46
47
  const RESPONSE_TIMES = Array.from({ length: 48 }, (_, i) => ({
47
48
  atMs: i * 30 * 60 * 1000,
@@ -329,6 +330,8 @@ export function Widgets(): ReactNode {
329
330
  <ComparisonDemo />
330
331
  <AiTextDemo />
331
332
  <PlanCatalogDemo />
333
+ <VariantsDemo />
334
+ <VariantsRoundTwoDemo />
332
335
  </div>
333
336
  );
334
337
  }
@@ -133,6 +133,7 @@ export const workboardFeature = defineFeature("workboard", (r) => {
133
133
  searchable: true,
134
134
  facets: { estimateHours: { display: "range" } },
135
135
  table: {
136
+ compactHeader: true,
136
137
  grouping: { field: "status", collapsedWhen: "done", userChoice: true, fields: ["priority"] },
137
138
  totals: [{ field: "estimateHours", kind: "sum" }],
138
139
  },
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
3
- "featureCount": 92,
3
+ "featureCount": 93,
4
4
  "features": [
5
5
  {
6
6
  "name": "account-security",
@@ -2249,6 +2249,28 @@
2249
2249
  "recommended": false
2250
2250
  }
2251
2251
  },
2252
+ {
2253
+ "name": "presence",
2254
+ "description": "Who else is on this record right now: a browser sends a heartbeat every 15 seconds for one row of an allow-listed entity and gets the other viewers and editors back, with a live signal to them on a change. State is ephemeral (Redis hash per tenant, entity and row, in-memory without Redis), keyed by the session tenant, expires after ttlSeconds without a heartbeat and holds user ids only; display names are looked up per response. A caller sees presence only for rows visible to them. Mount with createPresenceFeature({ entities: [\"task\"] }).",
2255
+ "toggleableDefault": null,
2256
+ "requires": [],
2257
+ "optionalRequires": [],
2258
+ "configReads": [],
2259
+ "exposesApis": [],
2260
+ "usesApis": [],
2261
+ "extensionsUsed": [],
2262
+ "configKeys": [],
2263
+ "secrets": [],
2264
+ "writeHandlers": [
2265
+ "presence:write:heartbeat",
2266
+ "presence:write:leave"
2267
+ ],
2268
+ "uiHints": {
2269
+ "displayLabel": "Presence",
2270
+ "category": "communication",
2271
+ "recommended": false
2272
+ }
2273
+ },
2252
2274
  {
2253
2275
  "name": "rate-limiting",
2254
2276
  "description": "Adds an ops-side `rate-limiting:query:status` query handler for inspecting current bucket state; the actual request throttling is wired automatically by the dispatcher when any handler declares a `rateLimit` option (e.g. `{ per: 'user', limit: 3, windowSeconds: 60 }`) or when you pass `context.rateLimit` to `buildServer`. Loading this feature is optional if you only need L3 per-handler rate limits and have no need for ops introspection.",
@@ -74,6 +74,7 @@ import {
74
74
  import { createNotesHistoryFeature } from "@cosmicdrift/kumiko-bundled-features/notes-history";
75
75
  import { createNotesHistoryUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/notes-history-user-data";
76
76
  import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
77
+ import { createPresenceFeature } from "@cosmicdrift/kumiko-bundled-features/presence";
77
78
  import { createReadinessFeature } from "@cosmicdrift/kumiko-bundled-features/readiness";
78
79
  import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
79
80
  import { createRendererPdfFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
@@ -421,6 +422,8 @@ export const APP_FEATURES = [
421
422
  // notes-history: default roles are TenantAdmin/TenantMember; same
422
423
  // SystemAdmin-operator reasoning as tags above.
423
424
  createNotesHistoryFeature({ roles: ["TenantAdmin", "TenantMember", "SystemAdmin"] }),
425
+ // presence: no host entity in this sample opts in, so it only mounts the handlers.
426
+ createPresenceFeature(),
424
427
  // notes-history-user-data: GDPR export/erase coverage for note-entry.
425
428
  // Depends (optionally) on notes-history + (hard) on user-data-rights —
426
429
  // both mounted here.
@@ -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.