@cosmicdrift/kumiko-samples 0.410.0 → 0.412.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/packages/bundled-features/package.json +31 -1
- package/packages/bundled-features/src/agent-tools/agent-doc-lint.ts +64 -3
- package/packages/bundled-features/src/agent-tools/agent-manifest.ts +13 -130
- package/packages/bundled-features/src/agent-tools/api-docs/anchors.ts +60 -0
- package/packages/bundled-features/src/agent-tools/api-docs/check.ts +25 -0
- package/packages/bundled-features/src/agent-tools/api-docs/collect-events.ts +140 -0
- package/packages/bundled-features/src/agent-tools/api-docs/collect.ts +175 -0
- package/packages/bundled-features/src/agent-tools/api-docs/curl.ts +28 -0
- package/packages/bundled-features/src/agent-tools/api-docs/error-table.ts +45 -0
- package/packages/bundled-features/src/agent-tools/api-docs/examples.ts +43 -0
- package/packages/bundled-features/src/agent-tools/api-docs/generate.ts +179 -0
- package/packages/bundled-features/src/agent-tools/api-docs/index-json.ts +29 -0
- package/packages/bundled-features/src/agent-tools/api-docs/index.ts +21 -0
- package/packages/bundled-features/src/agent-tools/api-docs/list-parameters.ts +38 -0
- package/packages/bundled-features/src/agent-tools/api-docs/markdown.ts +70 -0
- package/packages/bundled-features/src/agent-tools/api-docs/menu-path.ts +82 -0
- package/packages/bundled-features/src/agent-tools/api-docs/model.ts +83 -0
- package/packages/bundled-features/src/agent-tools/api-docs/problems.ts +58 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-events.ts +76 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-openapi.ts +216 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-overview.ts +86 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-reference.ts +79 -0
- package/packages/bundled-features/src/agent-tools/api-docs/render-tokens.ts +136 -0
- package/packages/bundled-features/src/agent-tools/api-docs/schema-fields.ts +167 -0
- package/packages/bundled-features/src/agent-tools/api-docs/section-ids.ts +28 -0
- package/packages/bundled-features/src/agent-tools/api-docs/system-only.ts +11 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/de.ts +166 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/en.ts +159 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/es.ts +162 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/fr.ts +169 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/index.ts +67 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/it.ts +165 -0
- package/packages/bundled-features/src/agent-tools/api-docs/texts/types.ts +130 -0
- package/packages/bundled-features/src/agent-tools/api-docs/ui-writes.ts +81 -0
- package/packages/bundled-features/src/agent-tools/changes.json +24 -0
- package/packages/bundled-features/src/agent-tools/handler-schema.ts +45 -0
- package/packages/bundled-features/src/agent-tools/index.ts +24 -0
- package/packages/bundled-features/src/agent-tools/labels.ts +181 -0
- package/packages/bundled-features/src/auth-email-password/changes.json +24 -0
- package/packages/bundled-features/src/auth-email-password/seeding.ts +84 -6
- package/packages/bundled-features/src/auth-email-password/web/i18n.ts +1 -0
- package/packages/bundled-features/src/auth-email-password/web/signup-screen.tsx +48 -3
- package/packages/bundled-features/src/auth-email-password/web/static-account.ts +190 -0
- package/packages/bundled-features/src/auth-email-password/web/static-client.ts +226 -0
- package/packages/bundled-features/src/foundation-shared/demo-admin-env.ts +11 -0
- package/packages/bundled-features/src/foundation-shared/index.ts +5 -1
- package/packages/bundled-features/src/inbound-mail-foundation/changes.json +6 -0
- package/packages/bundled-features/src/inbound-mail-foundation/entities.ts +99 -71
- package/packages/bundled-features/src/inbound-mail-foundation/feature.ts +2 -2
- package/packages/bundled-features/src/inbound-provider-imap/changes.json +6 -0
- package/packages/bundled-features/src/inbound-provider-imap/imap-client.ts +3 -1
- package/packages/bundled-features/src/personal-access-tokens/changes.json +6 -0
- package/packages/bundled-features/src/personal-access-tokens/feature.ts +5 -2
- package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts +7 -2
- package/packages/bundled-features/src/personal-access-tokens/i18n.ts +6 -1
- package/packages/bundled-features/src/personal-access-tokens/index.ts +37 -2
- package/packages/bundled-features/src/personal-access-tokens/scope-events-check.ts +28 -0
- package/packages/bundled-features/src/personal-access-tokens/screens.ts +9 -1
- package/packages/bundled-features/src/personal-access-tokens/web/constants.ts +1 -0
- package/packages/bundled-features/src/personal-access-tokens/web/scopes.ts +14 -0
- package/packages/bundled-features/src/presence/changes.json +8 -0
- package/packages/bundled-features/src/presence/feature.ts +25 -0
- package/packages/bundled-features/src/presence/handlers/heartbeat.write.ts +52 -0
- package/packages/bundled-features/src/presence/handlers/leave.write.ts +41 -0
- package/packages/bundled-features/src/presence/handlers/list.query.ts +39 -0
- package/packages/bundled-features/src/presence/index.ts +7 -0
- package/packages/bundled-features/src/presence/options.ts +30 -0
- package/packages/bundled-features/src/presence/payloads.ts +26 -0
- package/packages/bundled-features/src/presence/room.ts +65 -0
- package/packages/bundled-features/src/presence/store.ts +185 -0
- package/packages/bundled-features/src/sessions/feature.ts +6 -2
- package/packages/bundled-features/src/sessions/handlers/last-activity-probe.route.ts +19 -0
- package/packages/bundled-features/src/tenant-inactivity/changes.json +12 -0
- package/packages/bundled-features/src/tenant-inactivity/check-inactive-tenants.ts +14 -6
- package/packages/bundled-features/src/tenant-inactivity/constants.ts +4 -1
- package/packages/bundled-features/src/tenant-inactivity/handlers/inactivity-state.query.ts +2 -1
- package/packages/bundled-features/src/tenant-inactivity/handlers/keep-account.write.ts +2 -1
- package/packages/bundled-features/src/tenant-inactivity/options.ts +1 -0
- package/packages/bundled-features/src/tenant-inactivity/remote-activity.ts +6 -1
- package/packages/bundled-features/src/tenant-inactivity/static-keep-account.ts +37 -0
- package/packages/bundled-features/src/tenant-lifecycle/constants.ts +2 -0
- package/packages/bundled-features/src/tenant-lifecycle/handlers/cancel-destruction.write.ts +6 -2
- package/packages/bundled-features/src/tenant-lifecycle/handlers/request-destruction.write.ts +2 -1
- package/packages/bundled-features/src/tenant-lifecycle/index.ts +1 -0
- package/packages/bundled-features/src/waitlist/changes.json +6 -0
- package/packages/bundled-features/src/waitlist/static-submit.ts +56 -0
- package/samples/apps/styleguide/src/features/widgets/i18n.ts +143 -0
- package/samples/apps/styleguide/src/features/widgets/web/VariantsDemo.tsx +276 -0
- package/samples/apps/styleguide/src/features/widgets/web/Widgets.tsx +3 -0
- package/samples/apps/styleguide/src/features/workboard/feature.ts +1 -0
- package/samples/apps/use-all-bundled/feature-manifest.json +23 -1
- package/samples/apps/use-all-bundled/src/run-config.ts +3 -0
- package/samples/recipes/api-docs/README.md +52 -0
- package/samples/recipes/api-docs/api-docs/de/events.md +62 -0
- package/samples/recipes/api-docs/api-docs/de/overview.md +100 -0
- package/samples/recipes/api-docs/api-docs/de/reference/tickets.md +305 -0
- package/samples/recipes/api-docs/api-docs/de/tokens.md +66 -0
- package/samples/recipes/api-docs/api-docs/en/events.md +62 -0
- package/samples/recipes/api-docs/api-docs/en/overview.md +100 -0
- package/samples/recipes/api-docs/api-docs/en/reference/tickets.md +305 -0
- package/samples/recipes/api-docs/api-docs/en/tokens.md +66 -0
- package/samples/recipes/api-docs/api-docs/index.json +371 -0
- package/samples/recipes/api-docs/api-docs/openapi.json +982 -0
- package/samples/recipes/api-docs/api-examples/ticket-close.json +21 -0
- package/samples/recipes/api-docs/api-examples/ticket-create.json +42 -0
- package/samples/recipes/api-docs/api-examples/ticket-detail.json +28 -0
- package/samples/recipes/api-docs/api-examples/ticket-list.json +31 -0
- package/samples/recipes/api-docs/api-examples/ticket-update.json +54 -0
- package/samples/recipes/api-docs/api-examples/webhooks/ticket-closed.json +8 -0
- package/samples/recipes/api-docs/api-examples/webhooks/ticket-created.json +10 -0
- package/samples/recipes/api-docs/kumiko.config.ts +33 -0
- package/samples/recipes/api-docs/package.json +14 -0
- package/samples/recipes/api-docs/src/feature.ts +218 -0
- package/samples/recipes/api-docs/tsconfig.json +22 -0
- package/samples/recipes/realtime-sse/README.md +1 -0
- package/samples/recipes/realtime-sse/package.json +1 -0
- package/samples/recipes/realtime-sse/src/feature.ts +9 -0
- package/samples/recipes/record-detail-layout/README.md +1 -0
- package/samples/recipes/record-detail-layout/src/feature.ts +10 -0
- package/samples/recipes/wizard-form/README.md +9 -0
- package/samples/recipes/wizard-form/src/feature.ts +13 -2
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import type { FeatureDefinition, NavDefinition } from "@cosmicdrift/kumiko-framework/engine";
|
|
2
|
+
import { PAT_SCREEN_ID } from "../../personal-access-tokens/index.ts";
|
|
3
|
+
import {
|
|
4
|
+
localizedLabels,
|
|
5
|
+
localizedLabelsForSuffix,
|
|
6
|
+
localizedScreenTitleLabels,
|
|
7
|
+
pickLabel,
|
|
8
|
+
} from "../labels.ts";
|
|
9
|
+
import type { RegistryManifestView } from "./../types.ts";
|
|
10
|
+
import type { LocalizedText } from "./model.ts";
|
|
11
|
+
|
|
12
|
+
const MENU_SEPARATOR = " › ";
|
|
13
|
+
|
|
14
|
+
function perLocale(locales: readonly string[], labels: Readonly<Record<string, string>>) {
|
|
15
|
+
const entries = locales.flatMap((locale) => {
|
|
16
|
+
const label = pickLabel(labels, locale);
|
|
17
|
+
return label === undefined ? [] : [[locale, label] as const];
|
|
18
|
+
});
|
|
19
|
+
return Object.fromEntries(entries);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function patListScreenId(registry: RegistryManifestView, feature: FeatureDefinition) {
|
|
23
|
+
const prefix = `${feature.name}:`;
|
|
24
|
+
for (const id of registry.getAllScreens().keys()) {
|
|
25
|
+
if (id.startsWith(prefix) && id.endsWith(`:${PAT_SCREEN_ID}`)) return id;
|
|
26
|
+
}
|
|
27
|
+
return undefined;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function navChainTo(
|
|
31
|
+
registry: RegistryManifestView,
|
|
32
|
+
screenId: string,
|
|
33
|
+
): readonly NavDefinition[] | undefined {
|
|
34
|
+
const navs = registry.getAllNavs();
|
|
35
|
+
const leaf = [...navs.values()].find((nav) => nav.screen === screenId);
|
|
36
|
+
if (leaf === undefined) return undefined;
|
|
37
|
+
const chain: NavDefinition[] = [];
|
|
38
|
+
const seen = new Set<string>();
|
|
39
|
+
for (let nav: NavDefinition | undefined = leaf; nav && !seen.has(nav.id); ) {
|
|
40
|
+
seen.add(nav.id);
|
|
41
|
+
chain.unshift(nav);
|
|
42
|
+
nav = nav.parent === undefined ? undefined : navs.get(nav.parent);
|
|
43
|
+
}
|
|
44
|
+
return chain;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The nav chain that leads to the token list ("Settings › API tokens"), or the
|
|
48
|
+
* screen title when the app places the screen in no nav. */
|
|
49
|
+
export function patMenuPath(
|
|
50
|
+
registry: RegistryManifestView,
|
|
51
|
+
feature: FeatureDefinition,
|
|
52
|
+
locales: readonly string[],
|
|
53
|
+
): LocalizedText {
|
|
54
|
+
const translations = registry.getAllTranslations();
|
|
55
|
+
const screenId = patListScreenId(registry, feature);
|
|
56
|
+
if (screenId === undefined) return {};
|
|
57
|
+
const chain = navChainTo(registry, screenId);
|
|
58
|
+
if (chain === undefined)
|
|
59
|
+
return perLocale(locales, localizedScreenTitleLabels(translations, screenId));
|
|
60
|
+
return Object.fromEntries(
|
|
61
|
+
locales.map((locale) => [
|
|
62
|
+
locale,
|
|
63
|
+
chain
|
|
64
|
+
.map((nav) => pickLabel(localizedLabels(translations, nav.label), locale) ?? nav.id)
|
|
65
|
+
.join(MENU_SEPARATOR),
|
|
66
|
+
]),
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** Label of the list screen's first navigate toolbar action, the button that opens the mint form. */
|
|
71
|
+
export function patCreateLabel(
|
|
72
|
+
registry: RegistryManifestView,
|
|
73
|
+
feature: FeatureDefinition,
|
|
74
|
+
locales: readonly string[],
|
|
75
|
+
): LocalizedText {
|
|
76
|
+
const screen = feature.screens?.[PAT_SCREEN_ID];
|
|
77
|
+
if (screen?.type !== "projectionList") return {};
|
|
78
|
+
const action = screen.toolbarActions?.find((candidate) => candidate.kind === "navigate");
|
|
79
|
+
if (action === undefined) return {};
|
|
80
|
+
const labels = localizedLabelsForSuffix(registry.getAllTranslations(), action.label);
|
|
81
|
+
return perLocale(locales, labels);
|
|
82
|
+
}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import type { AppApiDocsConfig } from "@cosmicdrift/kumiko-framework/config";
|
|
2
|
+
import type { WebhookEntityVerb } from "@cosmicdrift/kumiko-framework/engine";
|
|
3
|
+
import type { PatRateLimit } from "../../personal-access-tokens/index.ts";
|
|
4
|
+
import type { ApiExampleFile, WebhookExampleFile } from "./examples.ts";
|
|
5
|
+
|
|
6
|
+
/** One string per requested locale. */
|
|
7
|
+
export type LocalizedText = Readonly<Record<string, string>>;
|
|
8
|
+
|
|
9
|
+
export type ApiDocsHandlerKind = "query" | "write";
|
|
10
|
+
|
|
11
|
+
export type ApiDocsHandler = {
|
|
12
|
+
readonly qn: string;
|
|
13
|
+
readonly kind: ApiDocsHandlerKind;
|
|
14
|
+
readonly title: LocalizedText;
|
|
15
|
+
readonly description: LocalizedText;
|
|
16
|
+
/** `undefined` when the input schema has no JSON Schema form. */
|
|
17
|
+
readonly inputSchema: Readonly<Record<string, unknown>> | undefined;
|
|
18
|
+
readonly excludedFields: readonly string[];
|
|
19
|
+
readonly fieldLabels: Readonly<Record<string, LocalizedText>>;
|
|
20
|
+
readonly example: ApiExampleFile | undefined;
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
export type ApiDocsGrantLevel = "read" | "write";
|
|
24
|
+
|
|
25
|
+
export type ApiDocsScopeHandler = {
|
|
26
|
+
readonly qn: string;
|
|
27
|
+
readonly grant: ApiDocsGrantLevel;
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
export type ApiDocsScope = {
|
|
31
|
+
readonly domain: string;
|
|
32
|
+
readonly label: string;
|
|
33
|
+
/** Read handlers always; write handlers only when the domain declares a write level. */
|
|
34
|
+
readonly handlers: readonly ApiDocsScopeHandler[];
|
|
35
|
+
readonly hasWriteLevel: boolean;
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
export type ApiDocsEvent = {
|
|
39
|
+
/** `feature:name` for a declared contract, `entity.verb` for an entity lifecycle event. */
|
|
40
|
+
readonly qn: string;
|
|
41
|
+
/** Event name as delivered; headings, anchors and OpenAPI webhook keys use it. */
|
|
42
|
+
readonly wireName: string;
|
|
43
|
+
readonly origin: "declared" | "entity";
|
|
44
|
+
readonly entity?: string;
|
|
45
|
+
readonly verb?: WebhookEntityVerb;
|
|
46
|
+
readonly version: number;
|
|
47
|
+
/** Declared events only; entity events are described from a template per verb. */
|
|
48
|
+
readonly description: LocalizedText;
|
|
49
|
+
/** Entity events only: the entity's translated label. */
|
|
50
|
+
readonly entityLabel: LocalizedText;
|
|
51
|
+
/** Declared events: requested locales other than `en` without a translated description. */
|
|
52
|
+
readonly untranslatedLocales: readonly string[];
|
|
53
|
+
/** Translated field labels per payload row name, used before the schema description. */
|
|
54
|
+
readonly fieldLabels: Readonly<Record<string, LocalizedText>>;
|
|
55
|
+
/** `undefined` when the payload has no JSON Schema form. */
|
|
56
|
+
readonly payloadSchema: Readonly<Record<string, unknown>> | undefined;
|
|
57
|
+
/** Scope domains that list the event, in code-point order; each grants it at `read` level. */
|
|
58
|
+
readonly domains: readonly string[];
|
|
59
|
+
readonly example: WebhookExampleFile | undefined;
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
export type ApiDocsModel = {
|
|
63
|
+
readonly scopes: readonly ApiDocsScope[];
|
|
64
|
+
/** Public webhook events, sorted by QN; empty when no scope lists one. */
|
|
65
|
+
readonly events: readonly ApiDocsEvent[];
|
|
66
|
+
/** Every handler any scope reaches, sorted by QN. */
|
|
67
|
+
readonly handlers: readonly ApiDocsHandler[];
|
|
68
|
+
readonly menuPath: LocalizedText;
|
|
69
|
+
readonly createLabel: LocalizedText;
|
|
70
|
+
readonly rateLimit: PatRateLimit;
|
|
71
|
+
readonly toggleable: boolean;
|
|
72
|
+
};
|
|
73
|
+
|
|
74
|
+
export type ApiDocsSource = {
|
|
75
|
+
readonly framework: string;
|
|
76
|
+
readonly app: { readonly name: string; readonly version: string };
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
export type ResolvedApiDocsConfig = AppApiDocsConfig & {
|
|
80
|
+
readonly locales: readonly string[];
|
|
81
|
+
readonly baseUrl: string;
|
|
82
|
+
readonly appName: string;
|
|
83
|
+
};
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { webhookEventDescriptionKey } from "@cosmicdrift/kumiko-framework/engine";
|
|
2
|
+
import type { AgentDocGap } from "../agent-doc-lint.ts";
|
|
3
|
+
import { formatAgentDocGap } from "../agent-doc-lint.ts";
|
|
4
|
+
|
|
5
|
+
export type ApiDocsProblem =
|
|
6
|
+
| { readonly kind: "patFeatureMissing" }
|
|
7
|
+
| { readonly kind: "docGap"; readonly gap: AgentDocGap }
|
|
8
|
+
| {
|
|
9
|
+
readonly kind: "descriptionTranslationMissing";
|
|
10
|
+
readonly qn: string;
|
|
11
|
+
readonly locale: string;
|
|
12
|
+
}
|
|
13
|
+
| {
|
|
14
|
+
readonly kind: "uiWriteOutsideScopes";
|
|
15
|
+
readonly qn: string;
|
|
16
|
+
readonly screens: readonly string[];
|
|
17
|
+
}
|
|
18
|
+
| { readonly kind: "unusedUiOnlyWrite"; readonly pattern: string }
|
|
19
|
+
| { readonly kind: "webhookDeliveryTextMissing"; readonly locale: string }
|
|
20
|
+
| {
|
|
21
|
+
readonly kind: "webhookEventWithoutDescriptionTranslation";
|
|
22
|
+
readonly qn: string;
|
|
23
|
+
readonly locale: string;
|
|
24
|
+
}
|
|
25
|
+
| {
|
|
26
|
+
readonly kind: "invalidTextOverride";
|
|
27
|
+
readonly locale: string;
|
|
28
|
+
readonly key: string;
|
|
29
|
+
readonly cause: string;
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
export function formatApiDocsProblem(problem: ApiDocsProblem): string {
|
|
33
|
+
switch (problem.kind) {
|
|
34
|
+
case "patFeatureMissing":
|
|
35
|
+
return "[patFeatureMissing] The app mounts no personal-access-tokens feature with scopes, so there is nothing to document.";
|
|
36
|
+
case "docGap":
|
|
37
|
+
return `[docGap] ${formatAgentDocGap(problem.gap)}`;
|
|
38
|
+
case "descriptionTranslationMissing":
|
|
39
|
+
return `[descriptionTranslationMissing] ${problem.qn} has no \`${problem.locale}\` description translation.`;
|
|
40
|
+
case "uiWriteOutsideScopes":
|
|
41
|
+
return `[uiWriteOutsideScopes] ${problem.qn} is used by ${problem.screens.join(", ")} but no token scope grants it. Add it to a scope or list it under apiDocs.uiOnlyWrites.`;
|
|
42
|
+
case "unusedUiOnlyWrite":
|
|
43
|
+
return `[unusedUiOnlyWrite] apiDocs.uiOnlyWrites pattern "${problem.pattern}" matches no UI write outside the scopes.`;
|
|
44
|
+
case "webhookDeliveryTextMissing":
|
|
45
|
+
return `[webhookDeliveryTextMissing] Webhook events are public but apiDocs.webhookDelivery has no \`${problem.locale}\` text.`;
|
|
46
|
+
case "webhookEventWithoutDescriptionTranslation":
|
|
47
|
+
return `[webhookEventWithoutDescriptionTranslation] ${problem.qn} has no \`${problem.locale}\` description translation (key ${webhookEventDescriptionKey(problem.qn)}).`;
|
|
48
|
+
case "invalidTextOverride":
|
|
49
|
+
return `[invalidTextOverride] apiDocs.texts.${problem.locale}["${problem.key}"]: ${problem.cause}`;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export function sortApiDocsProblems(problems: readonly ApiDocsProblem[]): ApiDocsProblem[] {
|
|
54
|
+
const keyed = problems.map((problem) => ({ problem, key: formatApiDocsProblem(problem) }));
|
|
55
|
+
return keyed
|
|
56
|
+
.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
|
|
57
|
+
.map(({ problem }) => problem);
|
|
58
|
+
}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import type { WebhookEntityVerb } from "@cosmicdrift/kumiko-framework/engine";
|
|
2
|
+
import { eventAnchors } from "./anchors.ts";
|
|
3
|
+
import { codeSpan, fenced, pageBuilder, type RenderedPage, table } from "./markdown.ts";
|
|
4
|
+
import type { ApiDocsEvent } from "./model.ts";
|
|
5
|
+
import { fieldRows } from "./schema-fields.ts";
|
|
6
|
+
import { eventsSectionIds as ids } from "./section-ids.ts";
|
|
7
|
+
import { type ApiDocsTextKey, type ApiDocsTexts, formatApiDocsText } from "./texts/index.ts";
|
|
8
|
+
|
|
9
|
+
export type EventsInput = {
|
|
10
|
+
readonly events: readonly ApiDocsEvent[];
|
|
11
|
+
readonly locale: string;
|
|
12
|
+
readonly texts: ApiDocsTexts;
|
|
13
|
+
/** The app's delivery description; the section stays, empty, when the app wrote none. */
|
|
14
|
+
readonly deliveryText: string | undefined;
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
const entityDescriptionKeys = {
|
|
18
|
+
created: "events.entity.created",
|
|
19
|
+
updated: "events.entity.updated",
|
|
20
|
+
deleted: "events.entity.deleted",
|
|
21
|
+
} as const satisfies Record<WebhookEntityVerb, ApiDocsTextKey>;
|
|
22
|
+
|
|
23
|
+
export function describeEvent(event: ApiDocsEvent, locale: string, texts: ApiDocsTexts): string {
|
|
24
|
+
if (event.origin === "declared" || event.verb === undefined) {
|
|
25
|
+
return event.description[locale] ?? "";
|
|
26
|
+
}
|
|
27
|
+
return formatApiDocsText(texts.text[entityDescriptionKeys[event.verb]], {
|
|
28
|
+
entity: event.entityLabel[locale] ?? event.entity ?? "",
|
|
29
|
+
});
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
function payloadTable(event: ApiDocsEvent, locale: string, texts: ApiDocsTexts): string {
|
|
33
|
+
const rows = fieldRows(event.payloadSchema);
|
|
34
|
+
if (rows.length === 0) return texts.text["events.noFields"];
|
|
35
|
+
const [name, type, required, description] = texts.text["reference.fields.columns"].split(" | ");
|
|
36
|
+
return table(
|
|
37
|
+
[name ?? "", type ?? "", required ?? "", description ?? ""],
|
|
38
|
+
rows.map((row) => [
|
|
39
|
+
codeSpan(row.name),
|
|
40
|
+
row.type,
|
|
41
|
+
row.required ? texts.text["reference.yes"] : texts.text["reference.no"],
|
|
42
|
+
event.fieldLabels[row.name]?.[locale] ?? row.schemaDescription ?? "",
|
|
43
|
+
]),
|
|
44
|
+
);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export function renderEventsPage(input: EventsInput): RenderedPage {
|
|
48
|
+
const { texts } = input;
|
|
49
|
+
const text = texts.text;
|
|
50
|
+
const page = pageBuilder(text["events.title"], text["events.description"]);
|
|
51
|
+
page.add(text["events.intro"]);
|
|
52
|
+
page.section(ids.delivery, text["events.delivery.heading"]);
|
|
53
|
+
if (input.deliveryText !== undefined) page.add(input.deliveryText);
|
|
54
|
+
page.section(ids.versions, text["events.versions.heading"]);
|
|
55
|
+
page.add(text["events.versions.body"]);
|
|
56
|
+
page.section(ids.list, text["events.list.heading"]);
|
|
57
|
+
const anchors = eventAnchors(input.events.map((event) => event.wireName));
|
|
58
|
+
input.events.forEach((event, index) => {
|
|
59
|
+
const anchor = anchors[index];
|
|
60
|
+
// skip: eventAnchors returns one entry per event, so a gap only means an empty list
|
|
61
|
+
if (anchor === undefined) return;
|
|
62
|
+
page.section(anchor.anchor, anchor.heading, 3, event.qn);
|
|
63
|
+
page.add(
|
|
64
|
+
describeEvent(event, input.locale, texts),
|
|
65
|
+
`- ${text["events.version"]}: ${codeSpan(String(event.version))}\n- ${text["events.requiredScope"]}: ${event.domains.map((domain) => codeSpan(`${domain}:read`)).join(", ")}`,
|
|
66
|
+
payloadTable(event, input.locale, texts),
|
|
67
|
+
);
|
|
68
|
+
if (event.example !== undefined) {
|
|
69
|
+
page.add(
|
|
70
|
+
`**${text["events.example"]}**`,
|
|
71
|
+
fenced("json", JSON.stringify(event.example.payload, null, 2)),
|
|
72
|
+
);
|
|
73
|
+
}
|
|
74
|
+
});
|
|
75
|
+
return page.finish();
|
|
76
|
+
}
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
|
|
2
|
+
import { compareIds } from "../labels.ts";
|
|
3
|
+
import { documentedErrorRows } from "./error-table.ts";
|
|
4
|
+
import type { ApiDocsEvent, ApiDocsHandler, ApiDocsModel, ApiDocsSource } from "./model.ts";
|
|
5
|
+
import { describeEvent } from "./render-events.ts";
|
|
6
|
+
import { apiDocsTextsFor, isApiDocsLocale } from "./texts/index.ts";
|
|
7
|
+
|
|
8
|
+
type Json = Readonly<Record<string, unknown>>;
|
|
9
|
+
|
|
10
|
+
const SCHEMAS = "#/components/schemas";
|
|
11
|
+
const JSON_CONTENT = "application/json";
|
|
12
|
+
|
|
13
|
+
const schemaName = (qn: string): string => qn.replaceAll(":", ".");
|
|
14
|
+
|
|
15
|
+
const ref = (name: string): Json => ({ $ref: `${SCHEMAS}/${name}` });
|
|
16
|
+
|
|
17
|
+
// Entity events are `entity.verb`: a different suffix keeps them apart from a declared
|
|
18
|
+
// `feature:name` event that would map to the same dotted name.
|
|
19
|
+
const eventSchemaName = (event: ApiDocsEvent): string =>
|
|
20
|
+
event.origin === "entity" ? `${event.qn}.entity-event` : `${schemaName(event.qn)}.event`;
|
|
21
|
+
|
|
22
|
+
/** Embedded input schemas are standalone documents: drop `$schema` (OpenAPI 3.1 sets
|
|
23
|
+
* the dialect once) and hoist their `$defs` into components so local refs keep resolving. */
|
|
24
|
+
function embedSchema(schema: Json, name: string, hoisted: Record<string, unknown>): unknown {
|
|
25
|
+
const defs = isPlainObject(schema["$defs"]) ? schema["$defs"] : {};
|
|
26
|
+
const rewrite = (node: unknown): unknown => {
|
|
27
|
+
if (Array.isArray(node)) return node.map(rewrite);
|
|
28
|
+
if (!isPlainObject(node)) return node;
|
|
29
|
+
return Object.fromEntries(
|
|
30
|
+
Object.entries(node)
|
|
31
|
+
.filter(([key]) => key !== "$schema" && key !== "$defs")
|
|
32
|
+
.map(([key, value]) => {
|
|
33
|
+
if (key === "$ref" && typeof value === "string" && value.startsWith("#/$defs/")) {
|
|
34
|
+
return [key, `${SCHEMAS}/${name}.${value.slice("#/$defs/".length)}`];
|
|
35
|
+
}
|
|
36
|
+
return [key, rewrite(value)];
|
|
37
|
+
}),
|
|
38
|
+
);
|
|
39
|
+
};
|
|
40
|
+
for (const [defName, def] of Object.entries(defs)) hoisted[`${name}.${defName}`] = rewrite(def);
|
|
41
|
+
return rewrite(schema);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function requestWrapper(handler: ApiDocsHandler, description: string | undefined): Json {
|
|
45
|
+
return {
|
|
46
|
+
type: "object",
|
|
47
|
+
...(description !== undefined && { description }),
|
|
48
|
+
required: ["type", "payload"],
|
|
49
|
+
properties: {
|
|
50
|
+
type: { const: handler.qn },
|
|
51
|
+
payload: ref(`${schemaName(handler.qn)}.payload`),
|
|
52
|
+
requestId: { type: "string" },
|
|
53
|
+
},
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function oneOfRequests(handlers: readonly ApiDocsHandler[]): Json {
|
|
58
|
+
return {
|
|
59
|
+
oneOf: handlers.map((handler) => ref(`${schemaName(handler.qn)}.request`)),
|
|
60
|
+
discriminator: {
|
|
61
|
+
propertyName: "type",
|
|
62
|
+
mapping: Object.fromEntries(
|
|
63
|
+
handlers.map((handler) => [handler.qn, `${SCHEMAS}/${schemaName(handler.qn)}.request`]),
|
|
64
|
+
),
|
|
65
|
+
},
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function errorResponses(): Json {
|
|
70
|
+
const statuses = [
|
|
71
|
+
...new Set(documentedErrorRows(apiDocsTextsFor("en")).map((row) => row.status)),
|
|
72
|
+
];
|
|
73
|
+
return Object.fromEntries(
|
|
74
|
+
statuses
|
|
75
|
+
.sort((a, b) => a - b)
|
|
76
|
+
.map((status) => [
|
|
77
|
+
String(status),
|
|
78
|
+
{ description: "Error", content: { [JSON_CONTENT]: { schema: ref("ErrorEnvelope") } } },
|
|
79
|
+
]),
|
|
80
|
+
);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
function operation(summary: string, requestBody: Json, dataSchema: Json): Json {
|
|
84
|
+
return {
|
|
85
|
+
post: {
|
|
86
|
+
summary,
|
|
87
|
+
requestBody: { required: true, content: { [JSON_CONTENT]: { schema: requestBody } } },
|
|
88
|
+
responses: {
|
|
89
|
+
"200": {
|
|
90
|
+
description: "Success",
|
|
91
|
+
content: {
|
|
92
|
+
[JSON_CONTENT]: {
|
|
93
|
+
schema: {
|
|
94
|
+
type: "object",
|
|
95
|
+
properties: { isSuccess: { type: "boolean" }, data: dataSchema },
|
|
96
|
+
},
|
|
97
|
+
},
|
|
98
|
+
},
|
|
99
|
+
},
|
|
100
|
+
...errorResponses(),
|
|
101
|
+
},
|
|
102
|
+
},
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function webhooks(events: readonly ApiDocsEvent[], locale: string): Json {
|
|
107
|
+
const texts = apiDocsTextsFor(isApiDocsLocale(locale) ? locale : "en");
|
|
108
|
+
return Object.fromEntries(
|
|
109
|
+
events.map((event) => [
|
|
110
|
+
event.wireName,
|
|
111
|
+
{
|
|
112
|
+
post: {
|
|
113
|
+
summary: event.wireName,
|
|
114
|
+
"x-kumiko-qn": event.qn,
|
|
115
|
+
description: describeEvent(event, locale, texts),
|
|
116
|
+
requestBody: {
|
|
117
|
+
required: true,
|
|
118
|
+
content: { [JSON_CONTENT]: { schema: ref(eventSchemaName(event)) } },
|
|
119
|
+
},
|
|
120
|
+
"x-kumiko-version": event.version,
|
|
121
|
+
"x-kumiko-scope": event.domains.map((domain) => `${domain}:read`),
|
|
122
|
+
},
|
|
123
|
+
},
|
|
124
|
+
]),
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
export type OpenApiInput = {
|
|
129
|
+
readonly model: ApiDocsModel;
|
|
130
|
+
readonly source: ApiDocsSource;
|
|
131
|
+
readonly baseUrl: string;
|
|
132
|
+
readonly appName: string;
|
|
133
|
+
/** Locale the operation descriptions are taken from. */
|
|
134
|
+
readonly descriptionLocale: string;
|
|
135
|
+
};
|
|
136
|
+
|
|
137
|
+
export function renderOpenApi(input: OpenApiInput): string {
|
|
138
|
+
const { model } = input;
|
|
139
|
+
const schemas: Record<string, unknown> = {};
|
|
140
|
+
for (const handler of model.handlers) {
|
|
141
|
+
const name = schemaName(handler.qn);
|
|
142
|
+
schemas[`${name}.request`] = requestWrapper(
|
|
143
|
+
handler,
|
|
144
|
+
handler.description[input.descriptionLocale],
|
|
145
|
+
);
|
|
146
|
+
schemas[`${name}.payload`] = embedSchema(
|
|
147
|
+
handler.inputSchema ?? { type: "object" },
|
|
148
|
+
`${name}.payload`,
|
|
149
|
+
schemas,
|
|
150
|
+
);
|
|
151
|
+
}
|
|
152
|
+
for (const event of model.events) {
|
|
153
|
+
const name = eventSchemaName(event);
|
|
154
|
+
schemas[name] = embedSchema(event.payloadSchema ?? { type: "object" }, name, schemas);
|
|
155
|
+
}
|
|
156
|
+
const errorCodes = [
|
|
157
|
+
...new Set(documentedErrorRows(apiDocsTextsFor("en")).map((r) => r.code)),
|
|
158
|
+
].sort(compareIds);
|
|
159
|
+
schemas["ErrorEnvelope"] = {
|
|
160
|
+
type: "object",
|
|
161
|
+
required: ["error"],
|
|
162
|
+
properties: {
|
|
163
|
+
isSuccess: { type: "boolean" },
|
|
164
|
+
error: {
|
|
165
|
+
type: "object",
|
|
166
|
+
required: ["code", "message"],
|
|
167
|
+
properties: {
|
|
168
|
+
code: { type: "string", enum: errorCodes },
|
|
169
|
+
httpStatus: { type: "integer" },
|
|
170
|
+
message: { type: "string" },
|
|
171
|
+
details: { type: "object" },
|
|
172
|
+
},
|
|
173
|
+
},
|
|
174
|
+
},
|
|
175
|
+
};
|
|
176
|
+
|
|
177
|
+
const queries = model.handlers.filter((handler) => handler.kind === "query");
|
|
178
|
+
const writes = model.handlers.filter((handler) => handler.kind === "write");
|
|
179
|
+
const paths: Record<string, unknown> = {
|
|
180
|
+
...(queries.length > 0 && { "/api/query": operation("Query", oneOfRequests(queries), {}) }),
|
|
181
|
+
...(writes.length > 0 && {
|
|
182
|
+
"/api/write": operation("Write", oneOfRequests(writes), {}),
|
|
183
|
+
"/api/batch": operation(
|
|
184
|
+
"Batch",
|
|
185
|
+
{
|
|
186
|
+
type: "object",
|
|
187
|
+
required: ["commands"],
|
|
188
|
+
properties: {
|
|
189
|
+
commands: { type: "array", items: oneOfRequests(writes) },
|
|
190
|
+
requestId: { type: "string" },
|
|
191
|
+
},
|
|
192
|
+
},
|
|
193
|
+
{ type: "array" },
|
|
194
|
+
),
|
|
195
|
+
}),
|
|
196
|
+
};
|
|
197
|
+
|
|
198
|
+
return `${JSON.stringify(
|
|
199
|
+
{
|
|
200
|
+
openapi: "3.1.0",
|
|
201
|
+
info: { title: `${input.appName} API`, version: input.source.app.version },
|
|
202
|
+
servers: [{ url: input.baseUrl }],
|
|
203
|
+
security: [{ bearerAuth: [] }],
|
|
204
|
+
paths,
|
|
205
|
+
...(model.events.length > 0 && {
|
|
206
|
+
webhooks: webhooks(model.events, input.descriptionLocale),
|
|
207
|
+
}),
|
|
208
|
+
components: {
|
|
209
|
+
securitySchemes: { bearerAuth: { type: "http", scheme: "bearer" } },
|
|
210
|
+
schemas,
|
|
211
|
+
},
|
|
212
|
+
},
|
|
213
|
+
null,
|
|
214
|
+
2,
|
|
215
|
+
)}\n`;
|
|
216
|
+
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { MAX_PAYLOAD_DEPTH } from "@cosmicdrift/kumiko-framework/api";
|
|
2
|
+
import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
|
|
3
|
+
import { curlExample } from "./curl.ts";
|
|
4
|
+
import { errorMeaningTable } from "./error-table.ts";
|
|
5
|
+
import { LIST_INPUT_JSON_SCHEMA, listParameterText } from "./list-parameters.ts";
|
|
6
|
+
import { codeSpan, fenced, pageBuilder, type RenderedPage, table } from "./markdown.ts";
|
|
7
|
+
import type { ApiDocsHandler } from "./model.ts";
|
|
8
|
+
import { typeLabel } from "./schema-fields.ts";
|
|
9
|
+
import { overviewSectionIds as ids } from "./section-ids.ts";
|
|
10
|
+
import { type ApiDocsTexts, formatApiDocsText } from "./texts/index.ts";
|
|
11
|
+
|
|
12
|
+
export type OverviewInput = {
|
|
13
|
+
readonly handlers: readonly ApiDocsHandler[];
|
|
14
|
+
readonly texts: ApiDocsTexts;
|
|
15
|
+
readonly baseUrl: string;
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
function listParameterTable(texts: ApiDocsTexts): string {
|
|
19
|
+
const jsonSchema = LIST_INPUT_JSON_SCHEMA;
|
|
20
|
+
const properties = jsonSchema.properties ?? {};
|
|
21
|
+
const [field, type, description] = texts.text["overview.lists.columns"].split(" | ");
|
|
22
|
+
return table(
|
|
23
|
+
[field ?? "", type ?? "", description ?? ""],
|
|
24
|
+
Object.keys(texts.listParameters).map((name) => [
|
|
25
|
+
codeSpan(name),
|
|
26
|
+
typeLabel(propertyNode(properties[name]), jsonSchema),
|
|
27
|
+
listParameterText(texts, name) ?? "",
|
|
28
|
+
]),
|
|
29
|
+
);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** A read handler is the safest example: pasting it changes nothing. */
|
|
33
|
+
export function exampleHandler(handlers: readonly ApiDocsHandler[]): ApiDocsHandler | undefined {
|
|
34
|
+
return handlers.find((handler) => handler.kind === "query") ?? handlers[0];
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export function renderOverview(input: OverviewInput): RenderedPage {
|
|
38
|
+
const { texts, baseUrl } = input;
|
|
39
|
+
const text = texts.text;
|
|
40
|
+
const example = exampleHandler(input.handlers);
|
|
41
|
+
const page = pageBuilder(text["overview.title"], text["overview.description"]);
|
|
42
|
+
page.add(text["overview.intro"]);
|
|
43
|
+
page.section(ids.endpoints, text["overview.endpoints.heading"]);
|
|
44
|
+
page.add(
|
|
45
|
+
table(
|
|
46
|
+
["Endpoint", ""],
|
|
47
|
+
[
|
|
48
|
+
[codeSpan("POST /api/query"), text["overview.endpoints.query"]],
|
|
49
|
+
[codeSpan("POST /api/write"), text["overview.endpoints.write"]],
|
|
50
|
+
[codeSpan("POST /api/batch"), text["overview.endpoints.batch"]],
|
|
51
|
+
],
|
|
52
|
+
),
|
|
53
|
+
);
|
|
54
|
+
page.section(ids.auth, text["overview.auth.heading"]);
|
|
55
|
+
page.add(text["overview.auth.body"]);
|
|
56
|
+
page.section(ids.body, text["overview.body.heading"]);
|
|
57
|
+
page.add(
|
|
58
|
+
formatApiDocsText(text["overview.body.body"], {
|
|
59
|
+
exampleType: example?.qn ?? "feature:query:entity:list",
|
|
60
|
+
maxDepth: MAX_PAYLOAD_DEPTH,
|
|
61
|
+
}),
|
|
62
|
+
...(example === undefined ? [] : [fenced("bash", curlExample(example, baseUrl))]),
|
|
63
|
+
);
|
|
64
|
+
page.section(ids.responses, text["overview.responses.heading"]);
|
|
65
|
+
page.add(text["overview.responses.success"], text["overview.responses.error"]);
|
|
66
|
+
page.section(ids.errors, text["overview.errors.heading"]);
|
|
67
|
+
page.add(errorMeaningTable(texts, text["overview.errors.columns"]));
|
|
68
|
+
page.section(ids.versions, text["overview.versions.heading"]);
|
|
69
|
+
page.add(text["overview.versions.body"]);
|
|
70
|
+
page.section(ids.lists, text["overview.lists.heading"]);
|
|
71
|
+
page.add(
|
|
72
|
+
text["overview.lists.intro"],
|
|
73
|
+
listParameterTable(texts),
|
|
74
|
+
text["overview.lists.response"],
|
|
75
|
+
);
|
|
76
|
+
page.section(ids.batch, text["overview.batch.heading"]);
|
|
77
|
+
page.add(text["overview.batch.body"]);
|
|
78
|
+
page.section(ids.retry, text["overview.retry.heading"]);
|
|
79
|
+
page.add(text["overview.retry.body"]);
|
|
80
|
+
return page.finish();
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// JSON Schema allows a bare boolean as a property schema; the list schema has none.
|
|
84
|
+
function propertyNode(property: unknown): Readonly<Record<string, unknown>> {
|
|
85
|
+
return isPlainObject(property) ? property : {};
|
|
86
|
+
}
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import type { HandlerAnchor } from "./anchors.ts";
|
|
2
|
+
import { curlExample, endpointOf } from "./curl.ts";
|
|
3
|
+
import { listParameterText, takesEntityListInput } from "./list-parameters.ts";
|
|
4
|
+
import { codeSpan, fenced, pageBuilder, type RenderedPage, table } from "./markdown.ts";
|
|
5
|
+
import type { ApiDocsHandler, ApiDocsScope } from "./model.ts";
|
|
6
|
+
import { fieldRows } from "./schema-fields.ts";
|
|
7
|
+
import { type ApiDocsTexts, formatApiDocsText } from "./texts/index.ts";
|
|
8
|
+
|
|
9
|
+
export type ReferenceInput = {
|
|
10
|
+
readonly scope: ApiDocsScope;
|
|
11
|
+
readonly handlers: ReadonlyMap<string, ApiDocsHandler>;
|
|
12
|
+
/** One per `scope.handlers` entry, same order. */
|
|
13
|
+
readonly anchors: readonly HandlerAnchor[];
|
|
14
|
+
readonly locale: string;
|
|
15
|
+
readonly texts: ApiDocsTexts;
|
|
16
|
+
readonly baseUrl: string;
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
function fieldTable(handler: ApiDocsHandler, locale: string, texts: ApiDocsTexts): string {
|
|
20
|
+
const rows = fieldRows(handler.inputSchema);
|
|
21
|
+
if (rows.length === 0) return texts.text["reference.noFields"];
|
|
22
|
+
const listInput = takesEntityListInput(handler);
|
|
23
|
+
const [name, type, required, description] = texts.text["reference.fields.columns"].split(" | ");
|
|
24
|
+
return table(
|
|
25
|
+
[name ?? "", type ?? "", required ?? "", description ?? ""],
|
|
26
|
+
rows.map((row) => [
|
|
27
|
+
codeSpan(row.name),
|
|
28
|
+
row.type,
|
|
29
|
+
row.required ? texts.text["reference.yes"] : texts.text["reference.no"],
|
|
30
|
+
handler.fieldLabels[row.name]?.[locale] ??
|
|
31
|
+
row.schemaDescription ??
|
|
32
|
+
(listInput ? listParameterText(texts, row.name) : undefined) ??
|
|
33
|
+
"",
|
|
34
|
+
]),
|
|
35
|
+
);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export function renderReferencePage(input: ReferenceInput): RenderedPage {
|
|
39
|
+
const { scope, texts, locale } = input;
|
|
40
|
+
const text = texts.text;
|
|
41
|
+
const page = pageBuilder(
|
|
42
|
+
scope.label,
|
|
43
|
+
formatApiDocsText(text["reference.description"], { scopeLabel: scope.label }),
|
|
44
|
+
);
|
|
45
|
+
scope.handlers.forEach((entry, index) => {
|
|
46
|
+
const handler = input.handlers.get(entry.qn);
|
|
47
|
+
const anchor = input.anchors[index];
|
|
48
|
+
// skip: scope entries without a collected handler or anchor have nothing to render
|
|
49
|
+
if (handler === undefined || anchor === undefined) return;
|
|
50
|
+
page.section(anchor.anchor, anchor.heading, 3, handler.qn);
|
|
51
|
+
page.add(`**${handler.title[locale] ?? handler.qn}**`);
|
|
52
|
+
const description = handler.description[locale];
|
|
53
|
+
if (description !== undefined) page.add(description);
|
|
54
|
+
page.add(
|
|
55
|
+
`- ${text["reference.requiredScope"]}: ${codeSpan(`${scope.domain}:${entry.grant}`)}\n- ${text["reference.endpoint"]}: ${codeSpan(`POST ${endpointOf(handler)}`)}`,
|
|
56
|
+
fieldTable(handler, locale, texts),
|
|
57
|
+
);
|
|
58
|
+
if (handler.excludedFields.length > 0) {
|
|
59
|
+
page.add(
|
|
60
|
+
formatApiDocsText(text["reference.excluded"], {
|
|
61
|
+
fields: handler.excludedFields.map(codeSpan).join(", "),
|
|
62
|
+
}),
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
page.add(
|
|
66
|
+
`**${text["reference.exampleRequest"]}**`,
|
|
67
|
+
fenced("bash", curlExample(handler, input.baseUrl)),
|
|
68
|
+
);
|
|
69
|
+
const response = handler.example?.response;
|
|
70
|
+
if (response !== undefined) {
|
|
71
|
+
page.add(
|
|
72
|
+
`**${text["reference.exampleResponse"]}**`,
|
|
73
|
+
formatApiDocsText(text["reference.status"], { status: response.status }),
|
|
74
|
+
fenced("json", JSON.stringify(response.body, null, 2)),
|
|
75
|
+
);
|
|
76
|
+
}
|
|
77
|
+
});
|
|
78
|
+
return page.finish();
|
|
79
|
+
}
|