@cosmicdrift/kumiko-bundled-features 0.411.0 → 0.413.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/dist/admin-shell/feature.d.ts +1 -1
- package/dist/agent-tools/agent-doc-lint.d.ts +9 -0
- package/dist/agent-tools/agent-doc-lint.js +42 -5
- package/dist/agent-tools/agent-manifest.d.ts +0 -1
- package/dist/agent-tools/agent-manifest.js +9 -99
- package/dist/agent-tools/api-docs/anchors.d.ts +14 -0
- package/dist/agent-tools/api-docs/anchors.js +49 -0
- package/dist/agent-tools/api-docs/check.d.ts +7 -0
- package/dist/agent-tools/api-docs/check.js +15 -0
- package/dist/agent-tools/api-docs/collect-events.d.ts +10 -0
- package/dist/agent-tools/api-docs/collect-events.js +90 -0
- package/dist/agent-tools/api-docs/collect.d.ts +15 -0
- package/dist/agent-tools/api-docs/collect.js +108 -0
- package/dist/agent-tools/api-docs/curl.d.ts +5 -0
- package/dist/agent-tools/api-docs/curl.js +24 -0
- package/dist/agent-tools/api-docs/error-table.d.ts +9 -0
- package/dist/agent-tools/api-docs/error-table.js +31 -0
- package/dist/agent-tools/api-docs/examples.d.ts +16 -0
- package/dist/agent-tools/api-docs/examples.js +25 -0
- package/dist/agent-tools/api-docs/generate.d.ts +19 -0
- package/dist/agent-tools/api-docs/generate.js +104 -0
- package/dist/agent-tools/api-docs/index-json.d.ts +15 -0
- package/dist/agent-tools/api-docs/index-json.js +6 -0
- package/dist/agent-tools/api-docs/index.d.ts +9 -0
- package/dist/agent-tools/api-docs/index.js +6 -0
- package/dist/agent-tools/api-docs/list-parameters.d.ts +61 -0
- package/dist/agent-tools/api-docs/list-parameters.js +28 -0
- package/dist/agent-tools/api-docs/markdown.d.ts +29 -0
- package/dist/agent-tools/api-docs/markdown.js +48 -0
- package/dist/agent-tools/api-docs/menu-path.d.ts +8 -0
- package/dist/agent-tools/api-docs/menu-path.js +60 -0
- package/dist/agent-tools/api-docs/model.d.ts +76 -0
- package/dist/agent-tools/api-docs/problems.d.ts +32 -0
- package/dist/agent-tools/api-docs/problems.js +28 -0
- package/dist/agent-tools/api-docs/render-events.d.ts +12 -0
- package/dist/agent-tools/api-docs/render-events.js +55 -0
- package/dist/agent-tools/api-docs/render-openapi.d.ts +10 -0
- package/dist/agent-tools/api-docs/render-openapi.js +170 -0
- package/dist/agent-tools/api-docs/render-overview.d.ts +11 -0
- package/dist/agent-tools/api-docs/render-overview.js +60 -0
- package/dist/agent-tools/api-docs/render-reference.d.ts +14 -0
- package/dist/agent-tools/api-docs/render-reference.js +50 -0
- package/dist/agent-tools/api-docs/render-tokens.d.ts +12 -0
- package/dist/agent-tools/api-docs/render-tokens.js +101 -0
- package/dist/agent-tools/api-docs/schema-fields.d.ts +16 -0
- package/dist/agent-tools/api-docs/schema-fields.js +141 -0
- package/dist/agent-tools/api-docs/section-ids.d.ts +25 -0
- package/dist/agent-tools/api-docs/section-ids.js +26 -0
- package/dist/agent-tools/api-docs/system-only.d.ts +5 -0
- package/dist/agent-tools/api-docs/system-only.js +7 -0
- package/dist/agent-tools/api-docs/texts/de.d.ts +123 -0
- package/dist/agent-tools/api-docs/texts/de.js +123 -0
- package/dist/agent-tools/api-docs/texts/en.d.ts +123 -0
- package/dist/agent-tools/api-docs/texts/en.js +123 -0
- package/dist/agent-tools/api-docs/texts/es.d.ts +123 -0
- package/dist/agent-tools/api-docs/texts/es.js +123 -0
- package/dist/agent-tools/api-docs/texts/fr.d.ts +123 -0
- package/dist/agent-tools/api-docs/texts/fr.js +123 -0
- package/dist/agent-tools/api-docs/texts/index.d.ts +14 -0
- package/dist/agent-tools/api-docs/texts/index.js +55 -0
- package/dist/agent-tools/api-docs/texts/it.d.ts +123 -0
- package/dist/agent-tools/api-docs/texts/it.js +123 -0
- package/dist/agent-tools/api-docs/texts/types.d.ts +18 -0
- package/dist/agent-tools/api-docs/texts/types.js +104 -0
- package/dist/agent-tools/api-docs/ui-writes.d.ts +12 -0
- package/dist/agent-tools/api-docs/ui-writes.js +73 -0
- package/dist/agent-tools/handler-schema.d.ts +5 -0
- package/dist/agent-tools/handler-schema.js +37 -0
- package/dist/agent-tools/index.d.ts +2 -1
- package/dist/agent-tools/index.js +2 -1
- package/dist/agent-tools/labels.d.ts +26 -0
- package/dist/agent-tools/labels.js +131 -0
- package/dist/auth-email-password/boot-rules.d.ts +7 -0
- package/dist/auth-email-password/boot-rules.js +7 -0
- package/dist/auth-email-password/feature.js +6 -13
- package/dist/auth-email-password/validate-options.d.ts +5 -0
- package/dist/auth-email-password/validate-options.js +15 -0
- package/dist/billing-foundation/boot-rules.d.ts +22 -0
- package/dist/billing-foundation/boot-rules.js +22 -0
- package/dist/billing-foundation/validate-options.js +56 -18
- package/dist/cap-overview/boot-rules.d.ts +12 -0
- package/dist/cap-overview/boot-rules.js +12 -0
- package/dist/cap-overview/feature.js +8 -3
- package/dist/documents/boot-rules.d.ts +12 -0
- package/dist/documents/boot-rules.js +12 -0
- package/dist/documents/feature.js +8 -3
- package/dist/file-derivatives/boot-rules.d.ts +7 -0
- package/dist/file-derivatives/boot-rules.js +7 -0
- package/dist/file-derivatives/feature.js +5 -2
- package/dist/folders/boot-rules.d.ts +7 -0
- package/dist/folders/boot-rules.js +7 -0
- package/dist/folders/feature.js +8 -5
- package/dist/helpdesk/boot-rules.d.ts +7 -0
- package/dist/helpdesk/boot-rules.js +7 -0
- package/dist/{contact → helpdesk}/challenge.js +2 -2
- package/dist/helpdesk/client/helpdesk-client-source.d.ts +1 -0
- package/dist/{contact/client/contact-client-source.js → helpdesk/client/helpdesk-client-source.js} +4 -4
- package/dist/helpdesk/client/helpdesk-website-client.d.ts +26 -0
- package/dist/helpdesk/client/helpdesk-website-client.js +1 -0
- package/dist/helpdesk/client/index.d.ts +2 -0
- package/dist/helpdesk/client/index.js +1 -0
- package/dist/{contact → helpdesk}/entity.d.ts +6 -6
- package/dist/{contact → helpdesk}/entity.js +31 -27
- package/dist/helpdesk/feature.d.ts +3 -0
- package/dist/{contact → helpdesk}/feature.js +43 -39
- package/dist/{contact → helpdesk}/handlers/attempts.d.ts +2 -2
- package/dist/helpdesk/handlers/challenge.query.d.ts +9 -0
- package/dist/{contact → helpdesk}/handlers/challenge.query.js +5 -5
- package/dist/helpdesk/handlers/forward-request.write.d.ts +9 -0
- package/dist/{contact → helpdesk}/handlers/forward-request.write.js +17 -15
- package/dist/{contact → helpdesk}/handlers/mark-done.write.d.ts +2 -2
- package/dist/{contact → helpdesk}/handlers/mark-done.write.js +8 -8
- package/dist/{contact → helpdesk}/handlers/notify-reporter-in-app.write.d.ts +2 -2
- package/dist/{contact → helpdesk}/handlers/notify-reporter-in-app.write.js +11 -11
- package/dist/{contact → helpdesk}/handlers/open-count.js +2 -2
- package/dist/{contact → helpdesk}/handlers/open-count.query.js +4 -4
- package/dist/{contact → helpdesk}/handlers/replies.query.js +6 -6
- package/dist/{contact → helpdesk}/handlers/reply.write.d.ts +4 -4
- package/dist/{contact → helpdesk}/handlers/reply.write.js +16 -16
- package/dist/helpdesk/handlers/report.write.d.ts +16 -0
- package/dist/{contact → helpdesk}/handlers/report.write.js +17 -17
- package/dist/helpdesk/handlers/request-delivery.query.d.ts +16 -0
- package/dist/{contact → helpdesk}/handlers/request-delivery.query.js +24 -24
- package/dist/{contact → helpdesk}/handlers/request-detail.query.d.ts +3 -3
- package/dist/{contact → helpdesk}/handlers/request-detail.query.js +10 -10
- package/dist/{contact → helpdesk}/handlers/request-list.query.js +2 -2
- package/dist/helpdesk/handlers/send-reply-mail.write.d.ts +8 -0
- package/dist/{contact → helpdesk}/handlers/send-reply-mail.write.js +15 -15
- package/dist/helpdesk/handlers/send-test.write.d.ts +5 -0
- package/dist/{contact → helpdesk}/handlers/send-test.write.js +10 -10
- package/dist/{contact → helpdesk}/handlers/submit.write.d.ts +4 -4
- package/dist/{contact → helpdesk}/handlers/submit.write.js +17 -17
- package/dist/{contact → helpdesk}/handlers/take-over-uploads.js +5 -5
- package/dist/{contact → helpdesk}/i18n.d.ts +1 -1
- package/dist/{contact → helpdesk}/i18n.js +78 -75
- package/dist/helpdesk/index.d.ts +5 -0
- package/dist/helpdesk/index.js +4 -0
- package/dist/{contact → helpdesk}/lib.d.ts +5 -5
- package/dist/{contact → helpdesk}/lib.js +16 -16
- package/dist/{contact → helpdesk}/mail.d.ts +20 -20
- package/dist/{contact → helpdesk}/mail.js +47 -47
- package/dist/{contact → helpdesk}/options.d.ts +6 -6
- package/dist/helpdesk/options.js +36 -0
- package/dist/helpdesk/panels.d.ts +2 -0
- package/dist/helpdesk/panels.js +21 -0
- package/dist/{contact → helpdesk}/payloads.d.ts +11 -11
- package/dist/{contact → helpdesk}/payloads.js +28 -28
- package/dist/helpdesk/screens.d.ts +5 -0
- package/dist/{contact → helpdesk}/screens.js +87 -87
- package/dist/{contact → helpdesk}/subject.js +3 -3
- package/dist/helpdesk/user-data-hooks.d.ts +3 -0
- package/dist/{contact → helpdesk}/user-data-hooks.js +15 -15
- package/dist/helpdesk/web/constants.d.ts +127 -0
- package/dist/helpdesk/web/constants.js +126 -0
- package/dist/helpdesk/web/index.d.ts +1 -0
- package/dist/helpdesk/web/index.js +1 -0
- package/dist/host-routing/boot-rules.d.ts +22 -0
- package/dist/host-routing/boot-rules.js +22 -0
- package/dist/host-routing/validate-options.js +35 -11
- package/dist/inbound-mail-foundation/entities.d.ts +84 -0
- package/dist/inbound-mail-foundation/entities.js +96 -71
- package/dist/inbound-mail-foundation/feature.js +2 -2
- package/dist/jobs/boot-rules.d.ts +7 -0
- package/dist/jobs/boot-rules.js +7 -0
- package/dist/jobs/feature.js +5 -2
- package/dist/legal-pages/boot-rules.d.ts +17 -0
- package/dist/legal-pages/boot-rules.js +17 -0
- package/dist/legal-pages/feature.js +5 -2
- package/dist/legal-pages/lib/validate-routes.js +11 -3
- package/dist/metrics/boot-rules.d.ts +12 -0
- package/dist/metrics/boot-rules.js +12 -0
- package/dist/metrics/validate.js +8 -2
- package/dist/notes-history/boot-rules.d.ts +7 -0
- package/dist/notes-history/boot-rules.js +7 -0
- package/dist/notes-history/feature.js +7 -4
- package/dist/personal-access-tokens/boot-rules.d.ts +7 -0
- package/dist/personal-access-tokens/boot-rules.js +7 -0
- package/dist/personal-access-tokens/feature.d.ts +1 -0
- package/dist/personal-access-tokens/feature.js +4 -2
- package/dist/personal-access-tokens/handlers/create.write.js +2 -2
- package/dist/personal-access-tokens/i18n.js +5 -1
- package/dist/personal-access-tokens/index.d.ts +4 -2
- package/dist/personal-access-tokens/index.js +29 -2
- package/dist/personal-access-tokens/scope-events-check.d.ts +3 -0
- package/dist/personal-access-tokens/scope-events-check.js +21 -0
- package/dist/personal-access-tokens/screens.js +8 -2
- package/dist/personal-access-tokens/web/constants.d.ts +1 -0
- package/dist/personal-access-tokens/web/constants.js +1 -0
- package/dist/personal-access-tokens/web/scopes.d.ts +2 -0
- package/dist/personal-access-tokens/web/scopes.js +12 -0
- package/dist/presence/boot-rules.d.ts +7 -0
- package/dist/presence/boot-rules.js +7 -0
- package/dist/presence/options.js +5 -1
- package/dist/readiness/boot-rules.d.ts +12 -0
- package/dist/readiness/boot-rules.js +12 -0
- package/dist/readiness/probe-boot-check.js +8 -3
- package/dist/shared/assert-no-where-rule-in-ownership-write.d.ts +1 -1
- package/dist/shared/assert-no-where-rule-in-ownership-write.js +11 -7
- package/dist/shared/boot-rules.d.ts +7 -0
- package/dist/shared/boot-rules.js +7 -0
- package/dist/subscription-mollie/boot-rules.d.ts +17 -0
- package/dist/subscription-mollie/boot-rules.js +17 -0
- package/dist/subscription-mollie/feature.js +13 -6
- package/dist/tags/boot-rules.d.ts +7 -0
- package/dist/tags/boot-rules.js +7 -0
- package/dist/tags/feature.js +8 -5
- package/dist/template-resolver/boot-rules.d.ts +17 -0
- package/dist/template-resolver/boot-rules.js +17 -0
- package/dist/template-resolver/feature.js +14 -5
- package/dist/tenant/boot-rules.d.ts +7 -0
- package/dist/tenant/boot-rules.js +7 -0
- package/dist/tenant/feature.js +5 -2
- package/kumiko-es-tables.json +4 -4
- package/package.json +29 -29
- package/src/agent-tools/changes.json +24 -0
- package/src/{contact → helpdesk}/changes.json +6 -0
- package/src/inbound-mail-foundation/changes.json +6 -0
- package/src/personal-access-tokens/changes.json +6 -0
- package/dist/contact/client/contact-client-source.d.ts +0 -1
- package/dist/contact/client/contact-website-client.d.ts +0 -26
- package/dist/contact/client/index.d.ts +0 -2
- package/dist/contact/client/index.js +0 -1
- package/dist/contact/feature.d.ts +0 -3
- package/dist/contact/handlers/challenge.query.d.ts +0 -9
- package/dist/contact/handlers/forward-request.write.d.ts +0 -9
- package/dist/contact/handlers/report.write.d.ts +0 -16
- package/dist/contact/handlers/request-delivery.query.d.ts +0 -16
- package/dist/contact/handlers/send-reply-mail.write.d.ts +0 -8
- package/dist/contact/handlers/send-test.write.d.ts +0 -5
- package/dist/contact/index.d.ts +0 -5
- package/dist/contact/index.js +0 -4
- package/dist/contact/options.js +0 -32
- package/dist/contact/panels.d.ts +0 -2
- package/dist/contact/panels.js +0 -21
- package/dist/contact/screens.d.ts +0 -5
- package/dist/contact/user-data-hooks.d.ts +0 -3
- package/dist/contact/web/constants.d.ts +0 -127
- package/dist/contact/web/constants.js +0 -126
- package/dist/contact/web/index.d.ts +0 -1
- package/dist/contact/web/index.js +0 -1
- /package/dist/{contact/client/contact-website-client.js → agent-tools/api-docs/model.js} +0 -0
- /package/dist/{contact → helpdesk}/challenge.d.ts +0 -0
- /package/dist/{contact → helpdesk}/handlers/access.d.ts +0 -0
- /package/dist/{contact → helpdesk}/handlers/access.js +0 -0
- /package/dist/{contact → helpdesk}/handlers/attempts.js +0 -0
- /package/dist/{contact → helpdesk}/handlers/open-count.d.ts +0 -0
- /package/dist/{contact → helpdesk}/handlers/open-count.query.d.ts +0 -0
- /package/dist/{contact → helpdesk}/handlers/replies.query.d.ts +0 -0
- /package/dist/{contact → helpdesk}/handlers/request-list.query.d.ts +0 -0
- /package/dist/{contact → helpdesk}/handlers/take-over-uploads.d.ts +0 -0
- /package/dist/{contact → helpdesk}/pow.d.ts +0 -0
- /package/dist/{contact → helpdesk}/pow.js +0 -0
- /package/dist/{contact → helpdesk}/subject.d.ts +0 -0
- /package/dist/{contact → helpdesk}/user-agent.d.ts +0 -0
- /package/dist/{contact → helpdesk}/user-agent.js +0 -0
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { eventAnchors } from "./anchors.js";
|
|
2
|
+
import { codeSpan, fenced, pageBuilder, table } from "./markdown.js";
|
|
3
|
+
import { fieldRows } from "./schema-fields.js";
|
|
4
|
+
import { eventsSectionIds as ids } from "./section-ids.js";
|
|
5
|
+
import { formatApiDocsText } from "./texts/index.js";
|
|
6
|
+
const entityDescriptionKeys = {
|
|
7
|
+
created: "events.entity.created",
|
|
8
|
+
updated: "events.entity.updated",
|
|
9
|
+
deleted: "events.entity.deleted",
|
|
10
|
+
};
|
|
11
|
+
export function describeEvent(event, locale, texts) {
|
|
12
|
+
if (event.origin === "declared" || event.verb === undefined) {
|
|
13
|
+
return event.description[locale] ?? "";
|
|
14
|
+
}
|
|
15
|
+
return formatApiDocsText(texts.text[entityDescriptionKeys[event.verb]], {
|
|
16
|
+
entity: event.entityLabel[locale] ?? event.entity ?? "",
|
|
17
|
+
});
|
|
18
|
+
}
|
|
19
|
+
function payloadTable(event, locale, texts) {
|
|
20
|
+
const rows = fieldRows(event.payloadSchema);
|
|
21
|
+
if (rows.length === 0)
|
|
22
|
+
return texts.text["events.noFields"];
|
|
23
|
+
const [name, type, required, description] = texts.text["reference.fields.columns"].split(" | ");
|
|
24
|
+
return table([name ?? "", type ?? "", required ?? "", description ?? ""], rows.map((row) => [
|
|
25
|
+
codeSpan(row.name),
|
|
26
|
+
row.type,
|
|
27
|
+
row.required ? texts.text["reference.yes"] : texts.text["reference.no"],
|
|
28
|
+
event.fieldLabels[row.name]?.[locale] ?? row.schemaDescription ?? "",
|
|
29
|
+
]));
|
|
30
|
+
}
|
|
31
|
+
export function renderEventsPage(input) {
|
|
32
|
+
const { texts } = input;
|
|
33
|
+
const text = texts.text;
|
|
34
|
+
const page = pageBuilder(text["events.title"], text["events.description"]);
|
|
35
|
+
page.add(text["events.intro"]);
|
|
36
|
+
page.section(ids.delivery, text["events.delivery.heading"]);
|
|
37
|
+
if (input.deliveryText !== undefined)
|
|
38
|
+
page.add(input.deliveryText);
|
|
39
|
+
page.section(ids.versions, text["events.versions.heading"]);
|
|
40
|
+
page.add(text["events.versions.body"]);
|
|
41
|
+
page.section(ids.list, text["events.list.heading"]);
|
|
42
|
+
const anchors = eventAnchors(input.events.map((event) => event.wireName));
|
|
43
|
+
input.events.forEach((event, index) => {
|
|
44
|
+
const anchor = anchors[index];
|
|
45
|
+
// skip: eventAnchors returns one entry per event, so a gap only means an empty list
|
|
46
|
+
if (anchor === undefined)
|
|
47
|
+
return;
|
|
48
|
+
page.section(anchor.anchor, anchor.heading, 3, event.qn);
|
|
49
|
+
page.add(describeEvent(event, input.locale, texts), `- ${text["events.version"]}: ${codeSpan(String(event.version))}\n- ${text["events.requiredScope"]}: ${event.domains.map((domain) => codeSpan(`${domain}:read`)).join(", ")}`, payloadTable(event, input.locale, texts));
|
|
50
|
+
if (event.example !== undefined) {
|
|
51
|
+
page.add(`**${text["events.example"]}**`, fenced("json", JSON.stringify(event.example.payload, null, 2)));
|
|
52
|
+
}
|
|
53
|
+
});
|
|
54
|
+
return page.finish();
|
|
55
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { ApiDocsModel, ApiDocsSource } from "./model.ts";
|
|
2
|
+
export type OpenApiInput = {
|
|
3
|
+
readonly model: ApiDocsModel;
|
|
4
|
+
readonly source: ApiDocsSource;
|
|
5
|
+
readonly baseUrl: string;
|
|
6
|
+
readonly appName: string;
|
|
7
|
+
/** Locale the operation descriptions are taken from. */
|
|
8
|
+
readonly descriptionLocale: string;
|
|
9
|
+
};
|
|
10
|
+
export declare function renderOpenApi(input: OpenApiInput): string;
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
|
|
2
|
+
import { compareIds } from "../labels.js";
|
|
3
|
+
import { documentedErrorRows } from "./error-table.js";
|
|
4
|
+
import { describeEvent } from "./render-events.js";
|
|
5
|
+
import { apiDocsTextsFor, isApiDocsLocale } from "./texts/index.js";
|
|
6
|
+
const SCHEMAS = "#/components/schemas";
|
|
7
|
+
const JSON_CONTENT = "application/json";
|
|
8
|
+
const schemaName = (qn) => qn.replaceAll(":", ".");
|
|
9
|
+
const ref = (name) => ({ $ref: `${SCHEMAS}/${name}` });
|
|
10
|
+
// Entity events are `entity.verb`: a different suffix keeps them apart from a declared
|
|
11
|
+
// `feature:name` event that would map to the same dotted name.
|
|
12
|
+
const eventSchemaName = (event) => event.origin === "entity" ? `${event.qn}.entity-event` : `${schemaName(event.qn)}.event`;
|
|
13
|
+
/** Embedded input schemas are standalone documents: drop `$schema` (OpenAPI 3.1 sets
|
|
14
|
+
* the dialect once) and hoist their `$defs` into components so local refs keep resolving. */
|
|
15
|
+
function embedSchema(schema, name, hoisted) {
|
|
16
|
+
const defs = isPlainObject(schema["$defs"]) ? schema["$defs"] : {};
|
|
17
|
+
const rewrite = (node) => {
|
|
18
|
+
if (Array.isArray(node))
|
|
19
|
+
return node.map(rewrite);
|
|
20
|
+
if (!isPlainObject(node))
|
|
21
|
+
return node;
|
|
22
|
+
return Object.fromEntries(Object.entries(node)
|
|
23
|
+
.filter(([key]) => key !== "$schema" && key !== "$defs")
|
|
24
|
+
.map(([key, value]) => {
|
|
25
|
+
if (key === "$ref" && typeof value === "string" && value.startsWith("#/$defs/")) {
|
|
26
|
+
return [key, `${SCHEMAS}/${name}.${value.slice("#/$defs/".length)}`];
|
|
27
|
+
}
|
|
28
|
+
return [key, rewrite(value)];
|
|
29
|
+
}));
|
|
30
|
+
};
|
|
31
|
+
for (const [defName, def] of Object.entries(defs))
|
|
32
|
+
hoisted[`${name}.${defName}`] = rewrite(def);
|
|
33
|
+
return rewrite(schema);
|
|
34
|
+
}
|
|
35
|
+
function requestWrapper(handler, description) {
|
|
36
|
+
return {
|
|
37
|
+
type: "object",
|
|
38
|
+
...(description !== undefined && { description }),
|
|
39
|
+
required: ["type", "payload"],
|
|
40
|
+
properties: {
|
|
41
|
+
type: { const: handler.qn },
|
|
42
|
+
payload: ref(`${schemaName(handler.qn)}.payload`),
|
|
43
|
+
requestId: { type: "string" },
|
|
44
|
+
},
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
function oneOfRequests(handlers) {
|
|
48
|
+
return {
|
|
49
|
+
oneOf: handlers.map((handler) => ref(`${schemaName(handler.qn)}.request`)),
|
|
50
|
+
discriminator: {
|
|
51
|
+
propertyName: "type",
|
|
52
|
+
mapping: Object.fromEntries(handlers.map((handler) => [handler.qn, `${SCHEMAS}/${schemaName(handler.qn)}.request`])),
|
|
53
|
+
},
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
function errorResponses() {
|
|
57
|
+
const statuses = [
|
|
58
|
+
...new Set(documentedErrorRows(apiDocsTextsFor("en")).map((row) => row.status)),
|
|
59
|
+
];
|
|
60
|
+
return Object.fromEntries(statuses
|
|
61
|
+
.sort((a, b) => a - b)
|
|
62
|
+
.map((status) => [
|
|
63
|
+
String(status),
|
|
64
|
+
{ description: "Error", content: { [JSON_CONTENT]: { schema: ref("ErrorEnvelope") } } },
|
|
65
|
+
]));
|
|
66
|
+
}
|
|
67
|
+
function operation(summary, requestBody, dataSchema) {
|
|
68
|
+
return {
|
|
69
|
+
post: {
|
|
70
|
+
summary,
|
|
71
|
+
requestBody: { required: true, content: { [JSON_CONTENT]: { schema: requestBody } } },
|
|
72
|
+
responses: {
|
|
73
|
+
"200": {
|
|
74
|
+
description: "Success",
|
|
75
|
+
content: {
|
|
76
|
+
[JSON_CONTENT]: {
|
|
77
|
+
schema: {
|
|
78
|
+
type: "object",
|
|
79
|
+
properties: { isSuccess: { type: "boolean" }, data: dataSchema },
|
|
80
|
+
},
|
|
81
|
+
},
|
|
82
|
+
},
|
|
83
|
+
},
|
|
84
|
+
...errorResponses(),
|
|
85
|
+
},
|
|
86
|
+
},
|
|
87
|
+
};
|
|
88
|
+
}
|
|
89
|
+
function webhooks(events, locale) {
|
|
90
|
+
const texts = apiDocsTextsFor(isApiDocsLocale(locale) ? locale : "en");
|
|
91
|
+
return Object.fromEntries(events.map((event) => [
|
|
92
|
+
event.wireName,
|
|
93
|
+
{
|
|
94
|
+
post: {
|
|
95
|
+
summary: event.wireName,
|
|
96
|
+
"x-kumiko-qn": event.qn,
|
|
97
|
+
description: describeEvent(event, locale, texts),
|
|
98
|
+
requestBody: {
|
|
99
|
+
required: true,
|
|
100
|
+
content: { [JSON_CONTENT]: { schema: ref(eventSchemaName(event)) } },
|
|
101
|
+
},
|
|
102
|
+
"x-kumiko-version": event.version,
|
|
103
|
+
"x-kumiko-scope": event.domains.map((domain) => `${domain}:read`),
|
|
104
|
+
},
|
|
105
|
+
},
|
|
106
|
+
]));
|
|
107
|
+
}
|
|
108
|
+
export function renderOpenApi(input) {
|
|
109
|
+
const { model } = input;
|
|
110
|
+
const schemas = {};
|
|
111
|
+
for (const handler of model.handlers) {
|
|
112
|
+
const name = schemaName(handler.qn);
|
|
113
|
+
schemas[`${name}.request`] = requestWrapper(handler, handler.description[input.descriptionLocale]);
|
|
114
|
+
schemas[`${name}.payload`] = embedSchema(handler.inputSchema ?? { type: "object" }, `${name}.payload`, schemas);
|
|
115
|
+
}
|
|
116
|
+
for (const event of model.events) {
|
|
117
|
+
const name = eventSchemaName(event);
|
|
118
|
+
schemas[name] = embedSchema(event.payloadSchema ?? { type: "object" }, name, schemas);
|
|
119
|
+
}
|
|
120
|
+
const errorCodes = [
|
|
121
|
+
...new Set(documentedErrorRows(apiDocsTextsFor("en")).map((r) => r.code)),
|
|
122
|
+
].sort(compareIds);
|
|
123
|
+
schemas["ErrorEnvelope"] = {
|
|
124
|
+
type: "object",
|
|
125
|
+
required: ["error"],
|
|
126
|
+
properties: {
|
|
127
|
+
isSuccess: { type: "boolean" },
|
|
128
|
+
error: {
|
|
129
|
+
type: "object",
|
|
130
|
+
required: ["code", "message"],
|
|
131
|
+
properties: {
|
|
132
|
+
code: { type: "string", enum: errorCodes },
|
|
133
|
+
httpStatus: { type: "integer" },
|
|
134
|
+
message: { type: "string" },
|
|
135
|
+
details: { type: "object" },
|
|
136
|
+
},
|
|
137
|
+
},
|
|
138
|
+
},
|
|
139
|
+
};
|
|
140
|
+
const queries = model.handlers.filter((handler) => handler.kind === "query");
|
|
141
|
+
const writes = model.handlers.filter((handler) => handler.kind === "write");
|
|
142
|
+
const paths = {
|
|
143
|
+
...(queries.length > 0 && { "/api/query": operation("Query", oneOfRequests(queries), {}) }),
|
|
144
|
+
...(writes.length > 0 && {
|
|
145
|
+
"/api/write": operation("Write", oneOfRequests(writes), {}),
|
|
146
|
+
"/api/batch": operation("Batch", {
|
|
147
|
+
type: "object",
|
|
148
|
+
required: ["commands"],
|
|
149
|
+
properties: {
|
|
150
|
+
commands: { type: "array", items: oneOfRequests(writes) },
|
|
151
|
+
requestId: { type: "string" },
|
|
152
|
+
},
|
|
153
|
+
}, { type: "array" }),
|
|
154
|
+
}),
|
|
155
|
+
};
|
|
156
|
+
return `${JSON.stringify({
|
|
157
|
+
openapi: "3.1.0",
|
|
158
|
+
info: { title: `${input.appName} API`, version: input.source.app.version },
|
|
159
|
+
servers: [{ url: input.baseUrl }],
|
|
160
|
+
security: [{ bearerAuth: [] }],
|
|
161
|
+
paths,
|
|
162
|
+
...(model.events.length > 0 && {
|
|
163
|
+
webhooks: webhooks(model.events, input.descriptionLocale),
|
|
164
|
+
}),
|
|
165
|
+
components: {
|
|
166
|
+
securitySchemes: { bearerAuth: { type: "http", scheme: "bearer" } },
|
|
167
|
+
schemas,
|
|
168
|
+
},
|
|
169
|
+
}, null, 2)}\n`;
|
|
170
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { type RenderedPage } from "./markdown.ts";
|
|
2
|
+
import type { ApiDocsHandler } from "./model.ts";
|
|
3
|
+
import { type ApiDocsTexts } from "./texts/index.ts";
|
|
4
|
+
export type OverviewInput = {
|
|
5
|
+
readonly handlers: readonly ApiDocsHandler[];
|
|
6
|
+
readonly texts: ApiDocsTexts;
|
|
7
|
+
readonly baseUrl: string;
|
|
8
|
+
};
|
|
9
|
+
/** A read handler is the safest example: pasting it changes nothing. */
|
|
10
|
+
export declare function exampleHandler(handlers: readonly ApiDocsHandler[]): ApiDocsHandler | undefined;
|
|
11
|
+
export declare function renderOverview(input: OverviewInput): RenderedPage;
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { MAX_PAYLOAD_DEPTH } from "@cosmicdrift/kumiko-framework/api";
|
|
2
|
+
import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
|
|
3
|
+
import { curlExample } from "./curl.js";
|
|
4
|
+
import { errorMeaningTable } from "./error-table.js";
|
|
5
|
+
import { LIST_INPUT_JSON_SCHEMA, listParameterText } from "./list-parameters.js";
|
|
6
|
+
import { codeSpan, fenced, pageBuilder, table } from "./markdown.js";
|
|
7
|
+
import { typeLabel } from "./schema-fields.js";
|
|
8
|
+
import { overviewSectionIds as ids } from "./section-ids.js";
|
|
9
|
+
import { formatApiDocsText } from "./texts/index.js";
|
|
10
|
+
function listParameterTable(texts) {
|
|
11
|
+
const jsonSchema = LIST_INPUT_JSON_SCHEMA;
|
|
12
|
+
const properties = jsonSchema.properties ?? {};
|
|
13
|
+
const [field, type, description] = texts.text["overview.lists.columns"].split(" | ");
|
|
14
|
+
return table([field ?? "", type ?? "", description ?? ""], Object.keys(texts.listParameters).map((name) => [
|
|
15
|
+
codeSpan(name),
|
|
16
|
+
typeLabel(propertyNode(properties[name]), jsonSchema),
|
|
17
|
+
listParameterText(texts, name) ?? "",
|
|
18
|
+
]));
|
|
19
|
+
}
|
|
20
|
+
/** A read handler is the safest example: pasting it changes nothing. */
|
|
21
|
+
export function exampleHandler(handlers) {
|
|
22
|
+
return handlers.find((handler) => handler.kind === "query") ?? handlers[0];
|
|
23
|
+
}
|
|
24
|
+
export function renderOverview(input) {
|
|
25
|
+
const { texts, baseUrl } = input;
|
|
26
|
+
const text = texts.text;
|
|
27
|
+
const example = exampleHandler(input.handlers);
|
|
28
|
+
const page = pageBuilder(text["overview.title"], text["overview.description"]);
|
|
29
|
+
page.add(text["overview.intro"]);
|
|
30
|
+
page.section(ids.endpoints, text["overview.endpoints.heading"]);
|
|
31
|
+
page.add(table(["Endpoint", ""], [
|
|
32
|
+
[codeSpan("POST /api/query"), text["overview.endpoints.query"]],
|
|
33
|
+
[codeSpan("POST /api/write"), text["overview.endpoints.write"]],
|
|
34
|
+
[codeSpan("POST /api/batch"), text["overview.endpoints.batch"]],
|
|
35
|
+
]));
|
|
36
|
+
page.section(ids.auth, text["overview.auth.heading"]);
|
|
37
|
+
page.add(text["overview.auth.body"]);
|
|
38
|
+
page.section(ids.body, text["overview.body.heading"]);
|
|
39
|
+
page.add(formatApiDocsText(text["overview.body.body"], {
|
|
40
|
+
exampleType: example?.qn ?? "feature:query:entity:list",
|
|
41
|
+
maxDepth: MAX_PAYLOAD_DEPTH,
|
|
42
|
+
}), ...(example === undefined ? [] : [fenced("bash", curlExample(example, baseUrl))]));
|
|
43
|
+
page.section(ids.responses, text["overview.responses.heading"]);
|
|
44
|
+
page.add(text["overview.responses.success"], text["overview.responses.error"]);
|
|
45
|
+
page.section(ids.errors, text["overview.errors.heading"]);
|
|
46
|
+
page.add(errorMeaningTable(texts, text["overview.errors.columns"]));
|
|
47
|
+
page.section(ids.versions, text["overview.versions.heading"]);
|
|
48
|
+
page.add(text["overview.versions.body"]);
|
|
49
|
+
page.section(ids.lists, text["overview.lists.heading"]);
|
|
50
|
+
page.add(text["overview.lists.intro"], listParameterTable(texts), text["overview.lists.response"]);
|
|
51
|
+
page.section(ids.batch, text["overview.batch.heading"]);
|
|
52
|
+
page.add(text["overview.batch.body"]);
|
|
53
|
+
page.section(ids.retry, text["overview.retry.heading"]);
|
|
54
|
+
page.add(text["overview.retry.body"]);
|
|
55
|
+
return page.finish();
|
|
56
|
+
}
|
|
57
|
+
// JSON Schema allows a bare boolean as a property schema; the list schema has none.
|
|
58
|
+
function propertyNode(property) {
|
|
59
|
+
return isPlainObject(property) ? property : {};
|
|
60
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { HandlerAnchor } from "./anchors.ts";
|
|
2
|
+
import { type RenderedPage } from "./markdown.ts";
|
|
3
|
+
import type { ApiDocsHandler, ApiDocsScope } from "./model.ts";
|
|
4
|
+
import { type ApiDocsTexts } from "./texts/index.ts";
|
|
5
|
+
export type ReferenceInput = {
|
|
6
|
+
readonly scope: ApiDocsScope;
|
|
7
|
+
readonly handlers: ReadonlyMap<string, ApiDocsHandler>;
|
|
8
|
+
/** One per `scope.handlers` entry, same order. */
|
|
9
|
+
readonly anchors: readonly HandlerAnchor[];
|
|
10
|
+
readonly locale: string;
|
|
11
|
+
readonly texts: ApiDocsTexts;
|
|
12
|
+
readonly baseUrl: string;
|
|
13
|
+
};
|
|
14
|
+
export declare function renderReferencePage(input: ReferenceInput): RenderedPage;
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { curlExample, endpointOf } from "./curl.js";
|
|
2
|
+
import { listParameterText, takesEntityListInput } from "./list-parameters.js";
|
|
3
|
+
import { codeSpan, fenced, pageBuilder, table } from "./markdown.js";
|
|
4
|
+
import { fieldRows } from "./schema-fields.js";
|
|
5
|
+
import { formatApiDocsText } from "./texts/index.js";
|
|
6
|
+
function fieldTable(handler, locale, texts) {
|
|
7
|
+
const rows = fieldRows(handler.inputSchema);
|
|
8
|
+
if (rows.length === 0)
|
|
9
|
+
return texts.text["reference.noFields"];
|
|
10
|
+
const listInput = takesEntityListInput(handler);
|
|
11
|
+
const [name, type, required, description] = texts.text["reference.fields.columns"].split(" | ");
|
|
12
|
+
return table([name ?? "", type ?? "", required ?? "", description ?? ""], rows.map((row) => [
|
|
13
|
+
codeSpan(row.name),
|
|
14
|
+
row.type,
|
|
15
|
+
row.required ? texts.text["reference.yes"] : texts.text["reference.no"],
|
|
16
|
+
handler.fieldLabels[row.name]?.[locale] ??
|
|
17
|
+
row.schemaDescription ??
|
|
18
|
+
(listInput ? listParameterText(texts, row.name) : undefined) ??
|
|
19
|
+
"",
|
|
20
|
+
]));
|
|
21
|
+
}
|
|
22
|
+
export function renderReferencePage(input) {
|
|
23
|
+
const { scope, texts, locale } = input;
|
|
24
|
+
const text = texts.text;
|
|
25
|
+
const page = pageBuilder(scope.label, formatApiDocsText(text["reference.description"], { scopeLabel: scope.label }));
|
|
26
|
+
scope.handlers.forEach((entry, index) => {
|
|
27
|
+
const handler = input.handlers.get(entry.qn);
|
|
28
|
+
const anchor = input.anchors[index];
|
|
29
|
+
// skip: scope entries without a collected handler or anchor have nothing to render
|
|
30
|
+
if (handler === undefined || anchor === undefined)
|
|
31
|
+
return;
|
|
32
|
+
page.section(anchor.anchor, anchor.heading, 3, handler.qn);
|
|
33
|
+
page.add(`**${handler.title[locale] ?? handler.qn}**`);
|
|
34
|
+
const description = handler.description[locale];
|
|
35
|
+
if (description !== undefined)
|
|
36
|
+
page.add(description);
|
|
37
|
+
page.add(`- ${text["reference.requiredScope"]}: ${codeSpan(`${scope.domain}:${entry.grant}`)}\n- ${text["reference.endpoint"]}: ${codeSpan(`POST ${endpointOf(handler)}`)}`, fieldTable(handler, locale, texts));
|
|
38
|
+
if (handler.excludedFields.length > 0) {
|
|
39
|
+
page.add(formatApiDocsText(text["reference.excluded"], {
|
|
40
|
+
fields: handler.excludedFields.map(codeSpan).join(", "),
|
|
41
|
+
}));
|
|
42
|
+
}
|
|
43
|
+
page.add(`**${text["reference.exampleRequest"]}**`, fenced("bash", curlExample(handler, input.baseUrl)));
|
|
44
|
+
const response = handler.example?.response;
|
|
45
|
+
if (response !== undefined) {
|
|
46
|
+
page.add(`**${text["reference.exampleResponse"]}**`, formatApiDocsText(text["reference.status"], { status: response.status }), fenced("json", JSON.stringify(response.body, null, 2)));
|
|
47
|
+
}
|
|
48
|
+
});
|
|
49
|
+
return page.finish();
|
|
50
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { type RenderedPage } from "./markdown.ts";
|
|
2
|
+
import type { ApiDocsModel } from "./model.ts";
|
|
3
|
+
import { type ApiDocsTexts } from "./texts/index.ts";
|
|
4
|
+
export type TokensInput = {
|
|
5
|
+
readonly model: ApiDocsModel;
|
|
6
|
+
readonly locale: string;
|
|
7
|
+
readonly texts: ApiDocsTexts;
|
|
8
|
+
readonly baseUrl: string;
|
|
9
|
+
readonly appName: string;
|
|
10
|
+
readonly planNote: string | undefined;
|
|
11
|
+
};
|
|
12
|
+
export declare function renderTokens(input: TokensInput): RenderedPage;
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import { patAuthRejectHttpStatus } from "@cosmicdrift/kumiko-framework/api";
|
|
2
|
+
import { frameworkErrorHttpStatus } from "@cosmicdrift/kumiko-framework/errors";
|
|
3
|
+
import { PAT_DEFAULT_EXPIRES_IN_DAYS, PAT_MAX_EXPIRES_IN_DAYS, } from "../../personal-access-tokens/index.js";
|
|
4
|
+
import { curlExample } from "./curl.js";
|
|
5
|
+
import { codeSpan, fenced, pageBuilder, table } from "./markdown.js";
|
|
6
|
+
import { exampleHandler } from "./render-overview.js";
|
|
7
|
+
import { tokensSectionIds as ids } from "./section-ids.js";
|
|
8
|
+
import { formatApiDocsText } from "./texts/index.js";
|
|
9
|
+
function scopeTable(input) {
|
|
10
|
+
const [scope, grant, handlers] = input.texts.text["tokens.scopes.columns"].split(" | ");
|
|
11
|
+
const rows = input.model.scopes.flatMap((entry) => (entry.hasWriteLevel ? ["read", "write"] : ["read"]).map((level) => [
|
|
12
|
+
`${codeSpan(entry.domain)} (${entry.label})`,
|
|
13
|
+
codeSpan(`${entry.domain}:${level}`),
|
|
14
|
+
entry.handlers
|
|
15
|
+
.filter((handler) => handler.grant === level)
|
|
16
|
+
.map((handler) => codeSpan(handler.qn))
|
|
17
|
+
.join(", "),
|
|
18
|
+
]));
|
|
19
|
+
return table([scope ?? "", grant ?? "", handlers ?? ""], rows);
|
|
20
|
+
}
|
|
21
|
+
function errorTable(input) {
|
|
22
|
+
const text = input.texts.text;
|
|
23
|
+
const [status, code, cause] = text["tokens.errors.columns"].split(" | ");
|
|
24
|
+
const rows = [
|
|
25
|
+
{
|
|
26
|
+
status: patAuthRejectHttpStatus.missing_token,
|
|
27
|
+
code: "missing_token",
|
|
28
|
+
cause: text["tokens.errors.missing"],
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
status: patAuthRejectHttpStatus.invalid_token,
|
|
32
|
+
code: "invalid_token",
|
|
33
|
+
cause: text["tokens.errors.invalid"],
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
status: frameworkErrorHttpStatus.access_denied,
|
|
37
|
+
code: "access_denied",
|
|
38
|
+
cause: text["tokens.errors.scope"],
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
status: frameworkErrorHttpStatus.access_denied,
|
|
42
|
+
code: "access_denied",
|
|
43
|
+
cause: text["tokens.errors.route"],
|
|
44
|
+
},
|
|
45
|
+
{
|
|
46
|
+
status: patAuthRejectHttpStatus.pat_rate_limited,
|
|
47
|
+
code: "pat_rate_limited",
|
|
48
|
+
cause: text["tokens.errors.rate"],
|
|
49
|
+
},
|
|
50
|
+
...(input.model.toggleable
|
|
51
|
+
? [
|
|
52
|
+
{
|
|
53
|
+
status: frameworkErrorHttpStatus.feature_disabled,
|
|
54
|
+
code: "feature_disabled",
|
|
55
|
+
cause: text["tokens.errors.disabled"],
|
|
56
|
+
},
|
|
57
|
+
]
|
|
58
|
+
: []),
|
|
59
|
+
];
|
|
60
|
+
return table([status ?? "", code ?? "", cause ?? ""], rows.map((row) => [String(row.status), codeSpan(row.code), row.cause]));
|
|
61
|
+
}
|
|
62
|
+
export function renderTokens(input) {
|
|
63
|
+
const { model, texts, locale, appName } = input;
|
|
64
|
+
const text = texts.text;
|
|
65
|
+
const example = exampleHandler(model.handlers);
|
|
66
|
+
const menuPath = model.menuPath[locale] ?? "";
|
|
67
|
+
const page = pageBuilder(text["tokens.title"], formatApiDocsText(text["tokens.description"], { appName }));
|
|
68
|
+
page.add(formatApiDocsText(text["tokens.intro"], { appName }));
|
|
69
|
+
page.section(ids.create, text["tokens.create.heading"]);
|
|
70
|
+
page.add([
|
|
71
|
+
formatApiDocsText(text["tokens.create.step1"], { menuPath }),
|
|
72
|
+
formatApiDocsText(text["tokens.create.step2"], {
|
|
73
|
+
createLabel: model.createLabel[locale] ?? "",
|
|
74
|
+
}),
|
|
75
|
+
text["tokens.create.step3"],
|
|
76
|
+
text["tokens.create.step4"],
|
|
77
|
+
]
|
|
78
|
+
.map((step, index) => `${index + 1}. ${step}`)
|
|
79
|
+
.join("\n"), formatApiDocsText(text["tokens.expiry"], {
|
|
80
|
+
defaultDays: PAT_DEFAULT_EXPIRES_IN_DAYS,
|
|
81
|
+
maxDays: PAT_MAX_EXPIRES_IN_DAYS,
|
|
82
|
+
}));
|
|
83
|
+
page.section(ids.use, text["tokens.use.heading"]);
|
|
84
|
+
page.add(text["tokens.use.body"], ...(example === undefined ? [] : [fenced("bash", curlExample(example, input.baseUrl))]));
|
|
85
|
+
page.section(ids.scopes, text["tokens.scopes.heading"]);
|
|
86
|
+
page.add(text["tokens.scopes.intro"], scopeTable(input));
|
|
87
|
+
page.section(ids.rateLimit, text["tokens.rateLimit.heading"]);
|
|
88
|
+
page.add(formatApiDocsText(text["tokens.rateLimit"], {
|
|
89
|
+
max: model.rateLimit.maxRequests,
|
|
90
|
+
windowSeconds: model.rateLimit.windowMs / 1000,
|
|
91
|
+
}), ...(input.planNote === undefined ? [] : [input.planNote]));
|
|
92
|
+
page.section(ids.errors, text["tokens.errors.heading"]);
|
|
93
|
+
page.add(errorTable(input));
|
|
94
|
+
page.section(ids.revoke, text["tokens.revoke.heading"]);
|
|
95
|
+
page.add(formatApiDocsText(text["tokens.revoke.body"], { menuPath }));
|
|
96
|
+
page.section(ids.security, text["tokens.security.heading"]);
|
|
97
|
+
page.add([text["tokens.security.item1"], text["tokens.security.item2"], text["tokens.security.item3"]]
|
|
98
|
+
.map((item) => `- ${item}`)
|
|
99
|
+
.join("\n"));
|
|
100
|
+
return page.finish();
|
|
101
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
type SchemaNode = Readonly<Record<string, unknown>>;
|
|
2
|
+
export type FieldRow = {
|
|
3
|
+
readonly name: string;
|
|
4
|
+
readonly type: string;
|
|
5
|
+
readonly required: boolean;
|
|
6
|
+
/** Raw JSON Schema `description`, used when no label exists. */
|
|
7
|
+
readonly schemaDescription: string | undefined;
|
|
8
|
+
};
|
|
9
|
+
export declare function typeLabel(rawNode: SchemaNode, root?: SchemaNode, depth?: number): string;
|
|
10
|
+
/** One row per top-level field; an object field with known properties (`changes` of a
|
|
11
|
+
* CRUD update) is followed by its own properties as `parent.child` rows, one level deep. */
|
|
12
|
+
export declare function fieldRows(schema: SchemaNode | undefined): readonly FieldRow[];
|
|
13
|
+
/** A request value that satisfies the schema's shape; optional fields are included
|
|
14
|
+
* so the example shows every field a caller may send. */
|
|
15
|
+
export declare function examplePayload(rawNode: SchemaNode, root?: SchemaNode, depth?: number): unknown;
|
|
16
|
+
export {};
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
|
|
2
|
+
// Recursive schemas would otherwise expand forever in examples and type labels.
|
|
3
|
+
const MAX_SCHEMA_DEPTH = 6;
|
|
4
|
+
const FORMAT_EXAMPLES = {
|
|
5
|
+
uuid: "00000000-0000-4000-8000-000000000001",
|
|
6
|
+
"date-time": "2026-01-15T09:30:00.000Z",
|
|
7
|
+
date: "2026-01-15",
|
|
8
|
+
email: "user@example.com",
|
|
9
|
+
uri: "https://example.com",
|
|
10
|
+
};
|
|
11
|
+
const DEFAULT_STRING_EXAMPLE = "text";
|
|
12
|
+
function asNode(value) {
|
|
13
|
+
return isPlainObject(value) ? value : undefined;
|
|
14
|
+
}
|
|
15
|
+
function nodeList(value) {
|
|
16
|
+
return Array.isArray(value)
|
|
17
|
+
? value.flatMap((entry) => {
|
|
18
|
+
const node = asNode(entry);
|
|
19
|
+
return node === undefined ? [] : [node];
|
|
20
|
+
})
|
|
21
|
+
: [];
|
|
22
|
+
}
|
|
23
|
+
function isNullNode(node) {
|
|
24
|
+
return node["type"] === "null";
|
|
25
|
+
}
|
|
26
|
+
function resolveRef(node, root) {
|
|
27
|
+
const ref = node["$ref"];
|
|
28
|
+
if (typeof ref !== "string" || !ref.startsWith("#/"))
|
|
29
|
+
return node;
|
|
30
|
+
let target = root;
|
|
31
|
+
for (const part of ref.slice(2).split("/")) {
|
|
32
|
+
target = asNode(target)?.[part];
|
|
33
|
+
}
|
|
34
|
+
return asNode(target) ?? node;
|
|
35
|
+
}
|
|
36
|
+
function alternatives(node) {
|
|
37
|
+
return [...nodeList(node["anyOf"]), ...nodeList(node["oneOf"])];
|
|
38
|
+
}
|
|
39
|
+
export function typeLabel(rawNode, root = rawNode, depth = 0) {
|
|
40
|
+
const node = resolveRef(rawNode, root);
|
|
41
|
+
if (depth > MAX_SCHEMA_DEPTH)
|
|
42
|
+
return "object";
|
|
43
|
+
const options = alternatives(node);
|
|
44
|
+
if (options.length > 0) {
|
|
45
|
+
const nonNull = options.filter((option) => !isNullNode(option));
|
|
46
|
+
const labels = nonNull.map((option) => typeLabel(option, root, depth + 1));
|
|
47
|
+
return [...labels, ...(nonNull.length < options.length ? ["null"] : [])].join(" | ");
|
|
48
|
+
}
|
|
49
|
+
if (Array.isArray(node["enum"]))
|
|
50
|
+
return node["enum"].map((value) => JSON.stringify(value)).join(" | ");
|
|
51
|
+
if ("const" in node)
|
|
52
|
+
return JSON.stringify(node["const"]);
|
|
53
|
+
const type = node["type"];
|
|
54
|
+
if (type === "array") {
|
|
55
|
+
const items = asNode(node["items"]);
|
|
56
|
+
return `array of ${items === undefined ? "any" : typeLabel(items, root, depth + 1)}`;
|
|
57
|
+
}
|
|
58
|
+
if (type === "string") {
|
|
59
|
+
const format = node["format"];
|
|
60
|
+
return typeof format === "string" ? `string (${format})` : "string";
|
|
61
|
+
}
|
|
62
|
+
if (type === "object")
|
|
63
|
+
return "object";
|
|
64
|
+
return typeof type === "string" ? type : "any";
|
|
65
|
+
}
|
|
66
|
+
function rowsOf(schema, root, prefix) {
|
|
67
|
+
const properties = asNode(schema["properties"]);
|
|
68
|
+
if (properties === undefined)
|
|
69
|
+
return [];
|
|
70
|
+
const required = new Set(Array.isArray(schema["required"])
|
|
71
|
+
? schema["required"].filter((n) => typeof n === "string")
|
|
72
|
+
: []);
|
|
73
|
+
return Object.entries(properties).map(([name, value]) => {
|
|
74
|
+
const node = asNode(value) ?? {};
|
|
75
|
+
const description = node["description"];
|
|
76
|
+
return {
|
|
77
|
+
name: prefix + name,
|
|
78
|
+
type: typeLabel(node, root),
|
|
79
|
+
required: required.has(name),
|
|
80
|
+
schemaDescription: typeof description === "string" ? description : undefined,
|
|
81
|
+
};
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
/** One row per top-level field; an object field with known properties (`changes` of a
|
|
85
|
+
* CRUD update) is followed by its own properties as `parent.child` rows, one level deep. */
|
|
86
|
+
export function fieldRows(schema) {
|
|
87
|
+
if (schema === undefined)
|
|
88
|
+
return [];
|
|
89
|
+
const properties = asNode(schema["properties"]) ?? {};
|
|
90
|
+
return rowsOf(schema, schema, "").flatMap((row) => {
|
|
91
|
+
const node = resolveRef(asNode(properties[row.name]) ?? {}, schema);
|
|
92
|
+
return [row, ...rowsOf(node, schema, `${row.name}.`)];
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
function stringExample(node) {
|
|
96
|
+
const format = node["format"];
|
|
97
|
+
return ((typeof format === "string" ? FORMAT_EXAMPLES[format] : undefined) ?? DEFAULT_STRING_EXAMPLE);
|
|
98
|
+
}
|
|
99
|
+
function objectExample(node, root, depth) {
|
|
100
|
+
const properties = asNode(node["properties"]) ?? {};
|
|
101
|
+
return Object.fromEntries(Object.entries(properties).map(([name, value]) => [
|
|
102
|
+
name,
|
|
103
|
+
examplePayload(asNode(value) ?? {}, root, depth + 1),
|
|
104
|
+
]));
|
|
105
|
+
}
|
|
106
|
+
/** A request value that satisfies the schema's shape; optional fields are included
|
|
107
|
+
* so the example shows every field a caller may send. */
|
|
108
|
+
export function examplePayload(rawNode, root = rawNode, depth = 0) {
|
|
109
|
+
const node = resolveRef(rawNode, root);
|
|
110
|
+
if (depth > MAX_SCHEMA_DEPTH)
|
|
111
|
+
return null;
|
|
112
|
+
const options = alternatives(node);
|
|
113
|
+
if (options.length > 0) {
|
|
114
|
+
const first = options.find((option) => !isNullNode(option)) ?? options[0];
|
|
115
|
+
return first === undefined ? null : examplePayload(first, root, depth + 1);
|
|
116
|
+
}
|
|
117
|
+
if (Array.isArray(node["enum"]))
|
|
118
|
+
return node["enum"][0];
|
|
119
|
+
if ("const" in node)
|
|
120
|
+
return node["const"];
|
|
121
|
+
return typedExample(node, root, depth);
|
|
122
|
+
}
|
|
123
|
+
function typedExample(node, root, depth) {
|
|
124
|
+
switch (node["type"]) {
|
|
125
|
+
case "string":
|
|
126
|
+
return stringExample(node);
|
|
127
|
+
case "number":
|
|
128
|
+
case "integer":
|
|
129
|
+
return 1;
|
|
130
|
+
case "boolean":
|
|
131
|
+
return true;
|
|
132
|
+
case "array": {
|
|
133
|
+
const items = asNode(node["items"]);
|
|
134
|
+
return items === undefined ? [] : [examplePayload(items, root, depth + 1)];
|
|
135
|
+
}
|
|
136
|
+
case "object":
|
|
137
|
+
return objectExample(node, root, depth);
|
|
138
|
+
default:
|
|
139
|
+
return null;
|
|
140
|
+
}
|
|
141
|
+
}
|