@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,136 @@
1
+ import { patAuthRejectHttpStatus } from "@cosmicdrift/kumiko-framework/api";
2
+ import { frameworkErrorHttpStatus } from "@cosmicdrift/kumiko-framework/errors";
3
+ import {
4
+ PAT_DEFAULT_EXPIRES_IN_DAYS,
5
+ PAT_MAX_EXPIRES_IN_DAYS,
6
+ } from "../../personal-access-tokens/index.ts";
7
+ import { curlExample } from "./curl.ts";
8
+ import { codeSpan, fenced, pageBuilder, type RenderedPage, table } from "./markdown.ts";
9
+ import type { ApiDocsModel } from "./model.ts";
10
+ import { exampleHandler } from "./render-overview.ts";
11
+ import { tokensSectionIds as ids } from "./section-ids.ts";
12
+ import { type ApiDocsTexts, formatApiDocsText } from "./texts/index.ts";
13
+
14
+ export type TokensInput = {
15
+ readonly model: ApiDocsModel;
16
+ readonly locale: string;
17
+ readonly texts: ApiDocsTexts;
18
+ readonly baseUrl: string;
19
+ readonly appName: string;
20
+ readonly planNote: string | undefined;
21
+ };
22
+
23
+ function scopeTable(input: TokensInput): string {
24
+ const [scope, grant, handlers] = input.texts.text["tokens.scopes.columns"].split(" | ");
25
+ const rows = input.model.scopes.flatMap((entry) =>
26
+ (entry.hasWriteLevel ? (["read", "write"] as const) : (["read"] as const)).map((level) => [
27
+ `${codeSpan(entry.domain)} (${entry.label})`,
28
+ codeSpan(`${entry.domain}:${level}`),
29
+ entry.handlers
30
+ .filter((handler) => handler.grant === level)
31
+ .map((handler) => codeSpan(handler.qn))
32
+ .join(", "),
33
+ ]),
34
+ );
35
+ return table([scope ?? "", grant ?? "", handlers ?? ""], rows);
36
+ }
37
+
38
+ function errorTable(input: TokensInput): string {
39
+ const text = input.texts.text;
40
+ const [status, code, cause] = text["tokens.errors.columns"].split(" | ");
41
+ const rows: { status: number; code: string; cause: string }[] = [
42
+ {
43
+ status: patAuthRejectHttpStatus.missing_token,
44
+ code: "missing_token",
45
+ cause: text["tokens.errors.missing"],
46
+ },
47
+ {
48
+ status: patAuthRejectHttpStatus.invalid_token,
49
+ code: "invalid_token",
50
+ cause: text["tokens.errors.invalid"],
51
+ },
52
+ {
53
+ status: frameworkErrorHttpStatus.access_denied,
54
+ code: "access_denied",
55
+ cause: text["tokens.errors.scope"],
56
+ },
57
+ {
58
+ status: frameworkErrorHttpStatus.access_denied,
59
+ code: "access_denied",
60
+ cause: text["tokens.errors.route"],
61
+ },
62
+ {
63
+ status: patAuthRejectHttpStatus.pat_rate_limited,
64
+ code: "pat_rate_limited",
65
+ cause: text["tokens.errors.rate"],
66
+ },
67
+ ...(input.model.toggleable
68
+ ? [
69
+ {
70
+ status: frameworkErrorHttpStatus.feature_disabled,
71
+ code: "feature_disabled",
72
+ cause: text["tokens.errors.disabled"],
73
+ },
74
+ ]
75
+ : []),
76
+ ];
77
+ return table(
78
+ [status ?? "", code ?? "", cause ?? ""],
79
+ rows.map((row) => [String(row.status), codeSpan(row.code), row.cause]),
80
+ );
81
+ }
82
+
83
+ export function renderTokens(input: TokensInput): RenderedPage {
84
+ const { model, texts, locale, appName } = input;
85
+ const text = texts.text;
86
+ const example = exampleHandler(model.handlers);
87
+ const menuPath = model.menuPath[locale] ?? "";
88
+ const page = pageBuilder(
89
+ text["tokens.title"],
90
+ formatApiDocsText(text["tokens.description"], { appName }),
91
+ );
92
+ page.add(formatApiDocsText(text["tokens.intro"], { appName }));
93
+ page.section(ids.create, text["tokens.create.heading"]);
94
+ page.add(
95
+ [
96
+ formatApiDocsText(text["tokens.create.step1"], { menuPath }),
97
+ formatApiDocsText(text["tokens.create.step2"], {
98
+ createLabel: model.createLabel[locale] ?? "",
99
+ }),
100
+ text["tokens.create.step3"],
101
+ text["tokens.create.step4"],
102
+ ]
103
+ .map((step, index) => `${index + 1}. ${step}`)
104
+ .join("\n"),
105
+ formatApiDocsText(text["tokens.expiry"], {
106
+ defaultDays: PAT_DEFAULT_EXPIRES_IN_DAYS,
107
+ maxDays: PAT_MAX_EXPIRES_IN_DAYS,
108
+ }),
109
+ );
110
+ page.section(ids.use, text["tokens.use.heading"]);
111
+ page.add(
112
+ text["tokens.use.body"],
113
+ ...(example === undefined ? [] : [fenced("bash", curlExample(example, input.baseUrl))]),
114
+ );
115
+ page.section(ids.scopes, text["tokens.scopes.heading"]);
116
+ page.add(text["tokens.scopes.intro"], scopeTable(input));
117
+ page.section(ids.rateLimit, text["tokens.rateLimit.heading"]);
118
+ page.add(
119
+ formatApiDocsText(text["tokens.rateLimit"], {
120
+ max: model.rateLimit.maxRequests,
121
+ windowSeconds: model.rateLimit.windowMs / 1000,
122
+ }),
123
+ ...(input.planNote === undefined ? [] : [input.planNote]),
124
+ );
125
+ page.section(ids.errors, text["tokens.errors.heading"]);
126
+ page.add(errorTable(input));
127
+ page.section(ids.revoke, text["tokens.revoke.heading"]);
128
+ page.add(formatApiDocsText(text["tokens.revoke.body"], { menuPath }));
129
+ page.section(ids.security, text["tokens.security.heading"]);
130
+ page.add(
131
+ [text["tokens.security.item1"], text["tokens.security.item2"], text["tokens.security.item3"]]
132
+ .map((item) => `- ${item}`)
133
+ .join("\n"),
134
+ );
135
+ return page.finish();
136
+ }
@@ -0,0 +1,167 @@
1
+ import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
2
+
3
+ type SchemaNode = Readonly<Record<string, unknown>>;
4
+
5
+ export type FieldRow = {
6
+ readonly name: string;
7
+ readonly type: string;
8
+ readonly required: boolean;
9
+ /** Raw JSON Schema `description`, used when no label exists. */
10
+ readonly schemaDescription: string | undefined;
11
+ };
12
+
13
+ // Recursive schemas would otherwise expand forever in examples and type labels.
14
+ const MAX_SCHEMA_DEPTH = 6;
15
+
16
+ const FORMAT_EXAMPLES: Readonly<Record<string, string>> = {
17
+ uuid: "00000000-0000-4000-8000-000000000001",
18
+ "date-time": "2026-01-15T09:30:00.000Z",
19
+ date: "2026-01-15",
20
+ email: "user@example.com",
21
+ uri: "https://example.com",
22
+ };
23
+
24
+ const DEFAULT_STRING_EXAMPLE = "text";
25
+
26
+ function asNode(value: unknown): SchemaNode | undefined {
27
+ return isPlainObject(value) ? value : undefined;
28
+ }
29
+
30
+ function nodeList(value: unknown): readonly SchemaNode[] {
31
+ return Array.isArray(value)
32
+ ? value.flatMap((entry) => {
33
+ const node = asNode(entry);
34
+ return node === undefined ? [] : [node];
35
+ })
36
+ : [];
37
+ }
38
+
39
+ function isNullNode(node: SchemaNode): boolean {
40
+ return node["type"] === "null";
41
+ }
42
+
43
+ function resolveRef(node: SchemaNode, root: SchemaNode): SchemaNode {
44
+ const ref = node["$ref"];
45
+ if (typeof ref !== "string" || !ref.startsWith("#/")) return node;
46
+ let target: unknown = root;
47
+ for (const part of ref.slice(2).split("/")) {
48
+ target = asNode(target)?.[part];
49
+ }
50
+ return asNode(target) ?? node;
51
+ }
52
+
53
+ function alternatives(node: SchemaNode): readonly SchemaNode[] {
54
+ return [...nodeList(node["anyOf"]), ...nodeList(node["oneOf"])];
55
+ }
56
+
57
+ export function typeLabel(rawNode: SchemaNode, root: SchemaNode = rawNode, depth = 0): string {
58
+ const node = resolveRef(rawNode, root);
59
+ if (depth > MAX_SCHEMA_DEPTH) return "object";
60
+ const options = alternatives(node);
61
+ if (options.length > 0) {
62
+ const nonNull = options.filter((option) => !isNullNode(option));
63
+ const labels = nonNull.map((option) => typeLabel(option, root, depth + 1));
64
+ return [...labels, ...(nonNull.length < options.length ? ["null"] : [])].join(" | ");
65
+ }
66
+ if (Array.isArray(node["enum"]))
67
+ return node["enum"].map((value) => JSON.stringify(value)).join(" | ");
68
+ if ("const" in node) return JSON.stringify(node["const"]);
69
+ const type = node["type"];
70
+ if (type === "array") {
71
+ const items = asNode(node["items"]);
72
+ return `array of ${items === undefined ? "any" : typeLabel(items, root, depth + 1)}`;
73
+ }
74
+ if (type === "string") {
75
+ const format = node["format"];
76
+ return typeof format === "string" ? `string (${format})` : "string";
77
+ }
78
+ if (type === "object") return "object";
79
+ return typeof type === "string" ? type : "any";
80
+ }
81
+
82
+ function rowsOf(schema: SchemaNode, root: SchemaNode, prefix: string): readonly FieldRow[] {
83
+ const properties = asNode(schema["properties"]);
84
+ if (properties === undefined) return [];
85
+ const required = new Set(
86
+ Array.isArray(schema["required"])
87
+ ? schema["required"].filter((n) => typeof n === "string")
88
+ : [],
89
+ );
90
+ return Object.entries(properties).map(([name, value]) => {
91
+ const node = asNode(value) ?? {};
92
+ const description = node["description"];
93
+ return {
94
+ name: prefix + name,
95
+ type: typeLabel(node, root),
96
+ required: required.has(name),
97
+ schemaDescription: typeof description === "string" ? description : undefined,
98
+ };
99
+ });
100
+ }
101
+
102
+ /** One row per top-level field; an object field with known properties (`changes` of a
103
+ * CRUD update) is followed by its own properties as `parent.child` rows, one level deep. */
104
+ export function fieldRows(schema: SchemaNode | undefined): readonly FieldRow[] {
105
+ if (schema === undefined) return [];
106
+ const properties = asNode(schema["properties"]) ?? {};
107
+ return rowsOf(schema, schema, "").flatMap((row) => {
108
+ const node = resolveRef(asNode(properties[row.name]) ?? {}, schema);
109
+ return [row, ...rowsOf(node, schema, `${row.name}.`)];
110
+ });
111
+ }
112
+
113
+ function stringExample(node: SchemaNode): string {
114
+ const format = node["format"];
115
+ return (
116
+ (typeof format === "string" ? FORMAT_EXAMPLES[format] : undefined) ?? DEFAULT_STRING_EXAMPLE
117
+ );
118
+ }
119
+
120
+ function objectExample(node: SchemaNode, root: SchemaNode, depth: number): Record<string, unknown> {
121
+ const properties = asNode(node["properties"]) ?? {};
122
+ return Object.fromEntries(
123
+ Object.entries(properties).map(([name, value]) => [
124
+ name,
125
+ examplePayload(asNode(value) ?? {}, root, depth + 1),
126
+ ]),
127
+ );
128
+ }
129
+
130
+ /** A request value that satisfies the schema's shape; optional fields are included
131
+ * so the example shows every field a caller may send. */
132
+ export function examplePayload(
133
+ rawNode: SchemaNode,
134
+ root: SchemaNode = rawNode,
135
+ depth = 0,
136
+ ): unknown {
137
+ const node = resolveRef(rawNode, root);
138
+ if (depth > MAX_SCHEMA_DEPTH) return null;
139
+ const options = alternatives(node);
140
+ if (options.length > 0) {
141
+ const first = options.find((option) => !isNullNode(option)) ?? options[0];
142
+ return first === undefined ? null : examplePayload(first, root, depth + 1);
143
+ }
144
+ if (Array.isArray(node["enum"])) return node["enum"][0];
145
+ if ("const" in node) return node["const"];
146
+ return typedExample(node, root, depth);
147
+ }
148
+
149
+ function typedExample(node: SchemaNode, root: SchemaNode, depth: number): unknown {
150
+ switch (node["type"]) {
151
+ case "string":
152
+ return stringExample(node);
153
+ case "number":
154
+ case "integer":
155
+ return 1;
156
+ case "boolean":
157
+ return true;
158
+ case "array": {
159
+ const items = asNode(node["items"]);
160
+ return items === undefined ? [] : [examplePayload(items, root, depth + 1)];
161
+ }
162
+ case "object":
163
+ return objectExample(node, root, depth);
164
+ default:
165
+ return null;
166
+ }
167
+ }
@@ -0,0 +1,28 @@
1
+ // Fixed per section, not derived from the translated heading, so de and en link alike.
2
+ export const overviewSectionIds = {
3
+ endpoints: "endpoints",
4
+ auth: "authentication",
5
+ body: "request-body",
6
+ responses: "responses",
7
+ errors: "error-codes",
8
+ versions: "versions",
9
+ lists: "lists",
10
+ batch: "batches",
11
+ retry: "retries",
12
+ } as const;
13
+
14
+ export const eventsSectionIds = {
15
+ delivery: "delivery",
16
+ versions: "versions",
17
+ list: "events",
18
+ } as const;
19
+
20
+ export const tokensSectionIds = {
21
+ create: "create-token",
22
+ use: "use-token",
23
+ scopes: "scopes",
24
+ rateLimit: "rate-limit",
25
+ errors: "errors",
26
+ revoke: "revoke-token",
27
+ security: "security",
28
+ } as const;
@@ -0,0 +1,11 @@
1
+ import { SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/engine";
2
+ import type { AccessRule } from "@cosmicdrift/kumiko-types/handlers";
3
+
4
+ /** A token never carries the system role, so such a handler is unreachable from the API. */
5
+ export function isSystemOnlyHandler(def: { readonly access: AccessRule }): boolean {
6
+ return (
7
+ "roles" in def.access &&
8
+ def.access.roles.length > 0 &&
9
+ def.access.roles.every((role) => role === SYSTEM_ROLE)
10
+ );
11
+ }
@@ -0,0 +1,166 @@
1
+ import type { ApiDocsTexts } from "./types.ts";
2
+
3
+ export const deApiDocsTexts = {
4
+ text: {
5
+ "overview.title": "HTTP-API",
6
+ "overview.description":
7
+ "Endpunkte, Request-Body, Antworten, Fehlercodes, Listen und Batches der HTTP-API.",
8
+ "overview.intro":
9
+ "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.",
10
+ "overview.endpoints.heading": "Endpunkte",
11
+ "overview.endpoints.query": "Liest Daten. Ändert nie etwas.",
12
+ "overview.endpoints.write":
13
+ "Ändert Daten: anlegen, ändern, löschen oder eine bestimmte Aktion.",
14
+ "overview.endpoints.batch": "Führt mehrere Schreibaufrufe in einer Transaktion aus.",
15
+ "overview.auth.heading": "Authentifizierung",
16
+ "overview.auth.body":
17
+ "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.",
18
+ "overview.body.heading": "Request-Body",
19
+ "overview.body.body":
20
+ "`type` ist der Name des Handlers, zum Beispiel `{exampleType}`. `payload` enthält die Felder aus der Referenz. `requestId` ist optional, siehe unten. Das Payload darf höchstens {maxDepth} Ebenen tief verschachtelt sein.",
21
+ "overview.responses.heading": "Antworten",
22
+ "overview.responses.success":
23
+ "Ein erfolgreiches Lesen liefert `data`. Ein erfolgreiches Schreiben liefert `isSuccess: true` und `data`.",
24
+ "overview.responses.error":
25
+ "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.",
26
+ "overview.errors.heading": "Fehlercodes",
27
+ "overview.errors.columns": "Code | HTTP-Status | Bedeutung",
28
+ "overview.versions.heading": "Versionen und Konflikte",
29
+ "overview.versions.body":
30
+ "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.",
31
+ "overview.lists.heading": "Listen",
32
+ "overview.lists.intro": "Listen-Handler enden auf `:list` und akzeptieren diese Felder:",
33
+ "overview.lists.columns": "Feld | Typ | Beschreibung",
34
+ "overview.lists.response":
35
+ "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`.",
36
+ "overview.batch.heading": "Batches",
37
+ "overview.batch.body":
38
+ "`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.",
39
+ "overview.retry.heading": "Sicher wiederholen",
40
+ "overview.retry.body":
41
+ "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.",
42
+ "tokens.title": "API-Tokens",
43
+ "tokens.description":
44
+ "Lege einen API-Token für {appName} an, wähle seine Scopes und sende ihn mit deinen Anfragen.",
45
+ "tokens.intro":
46
+ "Mit einem API-Token kann ein Skript oder ein anderer Dienst die API von {appName} in deinem Namen aufrufen. Seine Scopes bestimmen, welche Daten er lesen oder ändern darf.",
47
+ "tokens.create.heading": "Token anlegen",
48
+ "tokens.create.step1": "Öffne {menuPath}.",
49
+ "tokens.create.step2": "Wähle **{createLabel}**.",
50
+ "tokens.create.step3":
51
+ "Gib einen Namen ein, wähle die Scopes und das Ablaufdatum und bestätige mit deinem Passwort.",
52
+ "tokens.create.step4":
53
+ "Kopiere den Token. Er beginnt mit `kpat_` und wird nur einmal angezeigt.",
54
+ "tokens.expiry":
55
+ "Ein Token läuft nach {defaultDays} Tagen ab, wenn du keinen anderen Ablauf wählst. Möglich sind höchstens {maxDays} Tage.",
56
+ "tokens.use.heading": "Token verwenden",
57
+ "tokens.use.body":
58
+ "Sende den Token im Header `Authorization`. Anfragen mit Token brauchen weder Cookie noch CSRF-Token.",
59
+ "tokens.scopes.heading": "Scopes",
60
+ "tokens.scopes.intro":
61
+ "Jeder Scope hat zwei Stufen. `read` erlaubt die lesenden Handler. `write` erlaubt alles, was `read` erlaubt, und zusätzlich die schreibenden Handler.",
62
+ "tokens.scopes.columns": "Scope | Berechtigung | Handler",
63
+ "tokens.rateLimit.heading": "Ratenbegrenzung",
64
+ "tokens.rateLimit":
65
+ "Jeder Token darf {max} Anfragen pro {windowSeconds} Sekunden senden. Darüber antwortet die API mit 429 `pat_rate_limited`.",
66
+ "tokens.errors.heading": "Fehler",
67
+ "tokens.errors.columns": "HTTP-Status | Code | Ursache",
68
+ "tokens.errors.missing": "Es fehlt der Header `Authorization`.",
69
+ "tokens.errors.invalid": "Der Token ist unbekannt, widerrufen oder abgelaufen.",
70
+ "tokens.errors.scope": "Dem Token fehlt der Scope für diesen Handler.",
71
+ "tokens.errors.route":
72
+ "Der Endpunkt nimmt keine Tokens an. Tokens funktionieren nur an den API-Endpunkten.",
73
+ "tokens.errors.rate": "Zu viele Anfragen mit diesem Token.",
74
+ "tokens.errors.disabled": "API-Tokens sind nicht Teil deines Tarifs.",
75
+ "tokens.revoke.heading": "Token widerrufen",
76
+ "tokens.revoke.body":
77
+ "Widerrufe einen Token in {menuPath}, 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.",
78
+ "tokens.security.heading": "Sicherheit",
79
+ "tokens.security.item1":
80
+ "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.",
81
+ "tokens.security.item2":
82
+ "Gib jedem Skript einen eigenen Token mit nur den Scopes, die es braucht.",
83
+ "tokens.security.item3":
84
+ "Widerrufe Tokens, die du nicht mehr nutzt. Widerrufe einen Token sofort, wenn er in fremde Hände gelangt sein könnte.",
85
+ "reference.description":
86
+ "API-Referenz für {scopeLabel}: jeder Handler mit seinen Feldern und einem Beispiel.",
87
+ "reference.requiredScope": "Benötigter Scope",
88
+ "reference.endpoint": "Endpunkt",
89
+ "reference.fields.columns": "Feld | Typ | Pflicht | Beschreibung",
90
+ "reference.yes": "ja",
91
+ "reference.no": "nein",
92
+ "reference.noFields": "Dieser Handler nimmt keine Felder.",
93
+ "reference.excluded": "Über die API nicht setzbar: {fields}.",
94
+ "reference.exampleRequest": "Beispielanfrage",
95
+ "reference.exampleResponse": "Beispielantwort",
96
+ "reference.status": "Status: {status}",
97
+ "events.title": "Webhook-Ereignisse",
98
+ "events.description":
99
+ "Webhook-Ereignisse: wann sie ausgelöst werden, welchen Scope sie brauchen und was ihre Nutzlast enthält.",
100
+ "events.intro":
101
+ "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.",
102
+ "events.delivery.heading": "Zustellung",
103
+ "events.versions.heading": "Versionen",
104
+ "events.versions.body":
105
+ "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.",
106
+ "events.list.heading": "Ereignisse",
107
+ "events.version": "Version",
108
+ "events.requiredScope": "Benötigter Scope",
109
+ "events.example": "Beispiel-Nutzlast",
110
+ "events.noFields": "Dieses Ereignis enthält keine Felder.",
111
+ "events.entity.created": "Ein Datensatz vom Typ {entity} wurde angelegt.",
112
+ "events.entity.updated": "Ein Datensatz vom Typ {entity} wurde geändert.",
113
+ "events.entity.deleted": "Ein Datensatz vom Typ {entity} wurde gelöscht.",
114
+ },
115
+ errorMeanings: {
116
+ validation_error:
117
+ "Das Payload passt nicht zu den Feldern des Handlers. `details` nennt die Felder.",
118
+ unauthenticated: "Es wurden keine gültigen Zugangsdaten gesendet.",
119
+ missing_token: "Der Header `Authorization` fehlt.",
120
+ invalid_token: "Der Token ist unbekannt, widerrufen oder abgelaufen.",
121
+ ambiguous_auth: "Die Anfrage enthielt Session-Cookie und Token. Sende nur eines von beiden.",
122
+ access_denied:
123
+ "Dem Token fehlt der Scope für diesen Handler, oder der Endpunkt nimmt keine Tokens an.",
124
+ feature_disabled: "Diese Funktion ist abgeschaltet oder nicht Teil deines Tarifs.",
125
+ not_found: "Der Datensatz existiert nicht oder du darfst ihn nicht sehen.",
126
+ conflict: "Die Änderung widerspricht dem aktuellen Stand der Daten.",
127
+ version_conflict:
128
+ "Der Datensatz hat sich nach deinem Lesen geändert. Lies ihn neu und wiederhole mit der neuen `version`.",
129
+ precondition_failed:
130
+ "Ein Feld des Datensatzes hat nicht mehr den Wert, den die Änderung erwartet hat. Lies den Datensatz neu und wiederhole.",
131
+ record_locked: "Eine andere Änderung sperrt den Datensatz. Wiederhole gleich.",
132
+ idempotent_replay:
133
+ "Diese Änderung wurde unter demselben Idempotenz-Schlüssel schon ausgeführt. Der erste Versuch war erfolgreich, sende sie nicht noch einmal.",
134
+ unique_violation: "Ein Datensatz mit diesem Wert existiert bereits.",
135
+ unprocessable:
136
+ "Die Daten sind gültig, aber eine Fachregel lehnt die Änderung ab. `details.reason` nennt die Regel.",
137
+ unconfigured:
138
+ "Eine Einstellung, die diese Funktion braucht, ist noch leer. Richte sie zuerst in der App ein und wiederhole dann.",
139
+ internal_error: "Unerwarteter Serverfehler. Wiederhole später.",
140
+ member_read_timeout:
141
+ "Ein Lesevorgang auf dem Server hat zu lange gedauert und wurde abgebrochen. Wiederhole später.",
142
+ rate_limited:
143
+ "Zu viele Anfragen. Warte so viele Sekunden, wie der Header `Retry-After` angibt.",
144
+ rate_limit_unavailable:
145
+ "Die Ratenbegrenzung ist vorübergehend nicht verfügbar, die Anfrage wurde abgelehnt. Wiederhole gleich.",
146
+ pat_rate_limited:
147
+ "Dieser Token hat in kurzer Zeit zu viele Anfragen gesendet. Warte einen Moment und wiederhole.",
148
+ },
149
+ listParameters: {
150
+ cursor: "Position aus `nextCursor` der vorherigen Seite.",
151
+ limit: "Zeilen pro Seite, standardmäßig {default}, höchstens {max}.",
152
+ search: "Volltextsuche über die durchsuchbaren Felder.",
153
+ sort: "Feld, nach dem sortiert wird.",
154
+ sortDirection: "`asc` oder `desc`.",
155
+ offset: "Anzahl der zu überspringenden Zeilen. Nutze besser `cursor` zum Blättern.",
156
+ totalCount: "Mit `true` bekommst du zusätzlich `total`, die Anzahl der passenden Zeilen.",
157
+ includeDeleted:
158
+ "Mit `true` sind gelöschte Zeilen enthalten. Nur für Entitäten mit Soft Delete.",
159
+ onlyDeleted:
160
+ "Mit `true` kommen nur gelöschte Zeilen zurück. Nur für Entitäten mit Soft Delete, nicht zusammen mit `includeDeleted`.",
161
+ filter: "Ein Feldfilter mit `field`, `op` und `value`. `op` ist einer von {ops}.",
162
+ filters: "Mehrere Feldfilter, je mit `field`, `op` und `value`. `op` ist einer von {ops}.",
163
+ namedFilter: "Name eines vordefinierten Filters der Entität, zum Beispiel einer Arbeitsliste.",
164
+ aggregate: "Liefert aggregierte Werte statt Zeilen.",
165
+ },
166
+ } as const satisfies ApiDocsTexts;