@cosmicdrift/kumiko-bundled-features 0.411.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 (92) hide show
  1. package/dist/agent-tools/agent-doc-lint.d.ts +9 -0
  2. package/dist/agent-tools/agent-doc-lint.js +42 -5
  3. package/dist/agent-tools/agent-manifest.d.ts +0 -1
  4. package/dist/agent-tools/agent-manifest.js +9 -99
  5. package/dist/agent-tools/api-docs/anchors.d.ts +14 -0
  6. package/dist/agent-tools/api-docs/anchors.js +49 -0
  7. package/dist/agent-tools/api-docs/check.d.ts +7 -0
  8. package/dist/agent-tools/api-docs/check.js +15 -0
  9. package/dist/agent-tools/api-docs/collect-events.d.ts +10 -0
  10. package/dist/agent-tools/api-docs/collect-events.js +90 -0
  11. package/dist/agent-tools/api-docs/collect.d.ts +15 -0
  12. package/dist/agent-tools/api-docs/collect.js +108 -0
  13. package/dist/agent-tools/api-docs/curl.d.ts +5 -0
  14. package/dist/agent-tools/api-docs/curl.js +24 -0
  15. package/dist/agent-tools/api-docs/error-table.d.ts +9 -0
  16. package/dist/agent-tools/api-docs/error-table.js +31 -0
  17. package/dist/agent-tools/api-docs/examples.d.ts +16 -0
  18. package/dist/agent-tools/api-docs/examples.js +25 -0
  19. package/dist/agent-tools/api-docs/generate.d.ts +19 -0
  20. package/dist/agent-tools/api-docs/generate.js +104 -0
  21. package/dist/agent-tools/api-docs/index-json.d.ts +15 -0
  22. package/dist/agent-tools/api-docs/index-json.js +6 -0
  23. package/dist/agent-tools/api-docs/index.d.ts +9 -0
  24. package/dist/agent-tools/api-docs/index.js +6 -0
  25. package/dist/agent-tools/api-docs/list-parameters.d.ts +61 -0
  26. package/dist/agent-tools/api-docs/list-parameters.js +28 -0
  27. package/dist/agent-tools/api-docs/markdown.d.ts +29 -0
  28. package/dist/agent-tools/api-docs/markdown.js +48 -0
  29. package/dist/agent-tools/api-docs/menu-path.d.ts +8 -0
  30. package/dist/agent-tools/api-docs/menu-path.js +60 -0
  31. package/dist/agent-tools/api-docs/model.d.ts +76 -0
  32. package/dist/agent-tools/api-docs/model.js +1 -0
  33. package/dist/agent-tools/api-docs/problems.d.ts +32 -0
  34. package/dist/agent-tools/api-docs/problems.js +28 -0
  35. package/dist/agent-tools/api-docs/render-events.d.ts +12 -0
  36. package/dist/agent-tools/api-docs/render-events.js +55 -0
  37. package/dist/agent-tools/api-docs/render-openapi.d.ts +10 -0
  38. package/dist/agent-tools/api-docs/render-openapi.js +170 -0
  39. package/dist/agent-tools/api-docs/render-overview.d.ts +11 -0
  40. package/dist/agent-tools/api-docs/render-overview.js +60 -0
  41. package/dist/agent-tools/api-docs/render-reference.d.ts +14 -0
  42. package/dist/agent-tools/api-docs/render-reference.js +50 -0
  43. package/dist/agent-tools/api-docs/render-tokens.d.ts +12 -0
  44. package/dist/agent-tools/api-docs/render-tokens.js +101 -0
  45. package/dist/agent-tools/api-docs/schema-fields.d.ts +16 -0
  46. package/dist/agent-tools/api-docs/schema-fields.js +141 -0
  47. package/dist/agent-tools/api-docs/section-ids.d.ts +25 -0
  48. package/dist/agent-tools/api-docs/section-ids.js +26 -0
  49. package/dist/agent-tools/api-docs/system-only.d.ts +5 -0
  50. package/dist/agent-tools/api-docs/system-only.js +7 -0
  51. package/dist/agent-tools/api-docs/texts/de.d.ts +123 -0
  52. package/dist/agent-tools/api-docs/texts/de.js +123 -0
  53. package/dist/agent-tools/api-docs/texts/en.d.ts +123 -0
  54. package/dist/agent-tools/api-docs/texts/en.js +123 -0
  55. package/dist/agent-tools/api-docs/texts/es.d.ts +123 -0
  56. package/dist/agent-tools/api-docs/texts/es.js +123 -0
  57. package/dist/agent-tools/api-docs/texts/fr.d.ts +123 -0
  58. package/dist/agent-tools/api-docs/texts/fr.js +123 -0
  59. package/dist/agent-tools/api-docs/texts/index.d.ts +14 -0
  60. package/dist/agent-tools/api-docs/texts/index.js +55 -0
  61. package/dist/agent-tools/api-docs/texts/it.d.ts +123 -0
  62. package/dist/agent-tools/api-docs/texts/it.js +123 -0
  63. package/dist/agent-tools/api-docs/texts/types.d.ts +18 -0
  64. package/dist/agent-tools/api-docs/texts/types.js +104 -0
  65. package/dist/agent-tools/api-docs/ui-writes.d.ts +12 -0
  66. package/dist/agent-tools/api-docs/ui-writes.js +73 -0
  67. package/dist/agent-tools/handler-schema.d.ts +5 -0
  68. package/dist/agent-tools/handler-schema.js +37 -0
  69. package/dist/agent-tools/index.d.ts +2 -1
  70. package/dist/agent-tools/index.js +2 -1
  71. package/dist/agent-tools/labels.d.ts +26 -0
  72. package/dist/agent-tools/labels.js +131 -0
  73. package/dist/inbound-mail-foundation/entities.d.ts +84 -0
  74. package/dist/inbound-mail-foundation/entities.js +96 -71
  75. package/dist/inbound-mail-foundation/feature.js +2 -2
  76. package/dist/personal-access-tokens/feature.d.ts +1 -0
  77. package/dist/personal-access-tokens/feature.js +4 -2
  78. package/dist/personal-access-tokens/handlers/create.write.js +2 -2
  79. package/dist/personal-access-tokens/i18n.js +5 -1
  80. package/dist/personal-access-tokens/index.d.ts +4 -2
  81. package/dist/personal-access-tokens/index.js +29 -2
  82. package/dist/personal-access-tokens/scope-events-check.d.ts +3 -0
  83. package/dist/personal-access-tokens/scope-events-check.js +18 -0
  84. package/dist/personal-access-tokens/screens.js +8 -2
  85. package/dist/personal-access-tokens/web/constants.d.ts +1 -0
  86. package/dist/personal-access-tokens/web/constants.js +1 -0
  87. package/dist/personal-access-tokens/web/scopes.d.ts +2 -0
  88. package/dist/personal-access-tokens/web/scopes.js +12 -0
  89. package/package.json +11 -11
  90. package/src/agent-tools/changes.json +24 -0
  91. package/src/inbound-mail-foundation/changes.json +6 -0
  92. package/src/personal-access-tokens/changes.json +6 -0
@@ -0,0 +1,31 @@
1
+ import { patAuthRejectHttpStatus } from "@cosmicdrift/kumiko-framework/api";
2
+ import { frameworkErrorHttpStatus } from "@cosmicdrift/kumiko-framework/errors";
3
+ import { compareIds } from "../labels.js";
4
+ import { codeSpan, table } from "./markdown.js";
5
+ const statusTables = [
6
+ frameworkErrorHttpStatus,
7
+ patAuthRejectHttpStatus,
8
+ ];
9
+ function isDocumentedErrorCode(texts, code) {
10
+ return Object.hasOwn(texts.errorMeanings, code);
11
+ }
12
+ /** Every code the API can answer with: the framework table plus the token rejections,
13
+ * sorted by status then code. A code in both tables with the same status appears once. */
14
+ export function documentedErrorRows(texts) {
15
+ const rows = new Map();
16
+ for (const statuses of statusTables) {
17
+ for (const [code, status] of Object.entries(statuses)) {
18
+ if (isDocumentedErrorCode(texts, code))
19
+ rows.set(`${status}/${code}`, { code, status });
20
+ }
21
+ }
22
+ return [...rows.values()].sort((a, b) => a.status - b.status || compareIds(a.code, b.code));
23
+ }
24
+ export function errorMeaningTable(texts, columns) {
25
+ const [code, status, meaning] = columns.split(" | ");
26
+ return table([code ?? "", status ?? "", meaning ?? ""], documentedErrorRows(texts).map((row) => [
27
+ codeSpan(row.code),
28
+ String(row.status),
29
+ texts.errorMeanings[row.code],
30
+ ]));
31
+ }
@@ -0,0 +1,16 @@
1
+ import { type ApiExampleFile, ApiExampleFileSchema, type WebhookExampleFile, WebhookExampleFileSchema } from "@cosmicdrift/kumiko-types/api-example";
2
+ export { type ApiExampleFile, ApiExampleFileSchema, type WebhookExampleFile, WebhookExampleFileSchema, };
3
+ export type NamedWebhookExample = {
4
+ readonly fileName: string;
5
+ readonly file: WebhookExampleFile;
6
+ };
7
+ /** Same tie-break as `examplesByHandler`: the first file name in code-point order wins. */
8
+ export declare function webhookExamplesByEvent(examples: readonly NamedWebhookExample[]): ReadonlyMap<string, WebhookExampleFile>;
9
+ export type NamedApiExample = {
10
+ readonly fileName: string;
11
+ readonly file: ApiExampleFile;
12
+ };
13
+ /** A recording belongs to the handler named by `request.body.type`; when several
14
+ * recordings name the same handler the first file name in code-point order wins,
15
+ * so the choice never depends on directory listing order. */
16
+ export declare function examplesByHandler(examples: readonly NamedApiExample[]): ReadonlyMap<string, ApiExampleFile>;
@@ -0,0 +1,25 @@
1
+ import { ApiExampleFileSchema, WebhookExampleFileSchema, } from "@cosmicdrift/kumiko-types/api-example";
2
+ import { compareIds } from "../labels.js";
3
+ export { ApiExampleFileSchema, WebhookExampleFileSchema, };
4
+ /** Same tie-break as `examplesByHandler`: the first file name in code-point order wins. */
5
+ export function webhookExamplesByEvent(examples) {
6
+ const byEvent = new Map();
7
+ const sorted = [...examples].sort((a, b) => compareIds(a.fileName, b.fileName));
8
+ for (const { file } of sorted)
9
+ if (!byEvent.has(file.event))
10
+ byEvent.set(file.event, file);
11
+ return byEvent;
12
+ }
13
+ /** A recording belongs to the handler named by `request.body.type`; when several
14
+ * recordings name the same handler the first file name in code-point order wins,
15
+ * so the choice never depends on directory listing order. */
16
+ export function examplesByHandler(examples) {
17
+ const byHandler = new Map();
18
+ const sorted = [...examples].sort((a, b) => compareIds(a.fileName, b.fileName));
19
+ for (const { file } of sorted) {
20
+ const handlerQn = file.request.body.type;
21
+ if (handlerQn !== undefined && !byHandler.has(handlerQn))
22
+ byHandler.set(handlerQn, file);
23
+ }
24
+ return byHandler;
25
+ }
@@ -0,0 +1,19 @@
1
+ import type { RegistryManifestView } from "../types.ts";
2
+ import { type NamedApiExample, type NamedWebhookExample } from "./examples.ts";
3
+ import type { ApiDocsSource, ResolvedApiDocsConfig } from "./model.ts";
4
+ import { type ApiDocsProblem } from "./problems.ts";
5
+ export declare const OPENAPI_FILE = "openapi.json";
6
+ export type ApiDocsInput = {
7
+ readonly registry: RegistryManifestView;
8
+ readonly config: ResolvedApiDocsConfig;
9
+ readonly source: ApiDocsSource;
10
+ readonly examples: readonly NamedApiExample[];
11
+ readonly webhookExamples?: readonly NamedWebhookExample[];
12
+ };
13
+ export type ApiDocsResult = {
14
+ readonly files: ReadonlyMap<string, string>;
15
+ readonly problems: readonly ApiDocsProblem[];
16
+ };
17
+ /** Pure: registry in, files and problems out. No I/O, clock or environment, so the
18
+ * same input always yields byte-identical files. */
19
+ export declare function generateApiDocs(input: ApiDocsInput): ApiDocsResult;
@@ -0,0 +1,104 @@
1
+ import { findApiDocHandlerGaps, findDescriptionTranslationGaps } from "../agent-doc-lint.js";
2
+ import { anchorsForPage, slugify } from "./anchors.js";
3
+ import { collectApiDocsModel } from "./collect.js";
4
+ import { examplesByHandler, webhookExamplesByEvent, } from "./examples.js";
5
+ import { INDEX_FILE, renderIndexJson } from "./index-json.js";
6
+ import { sortApiDocsProblems } from "./problems.js";
7
+ import { renderEventsPage } from "./render-events.js";
8
+ import { renderOpenApi } from "./render-openapi.js";
9
+ import { renderOverview } from "./render-overview.js";
10
+ import { renderReferencePage } from "./render-reference.js";
11
+ import { renderTokens } from "./render-tokens.js";
12
+ import { isApiDocsLocale, resolveApiDocsTexts } from "./texts/index.js";
13
+ import { uiWriteProblems } from "./ui-writes.js";
14
+ export const OPENAPI_FILE = "openapi.json";
15
+ const OVERVIEW_ORDER = 1;
16
+ const TOKENS_ORDER = 2;
17
+ const REFERENCE_ORDER_START = 10;
18
+ /** Pure: registry in, files and problems out. No I/O, clock or environment, so the
19
+ * same input always yields byte-identical files. */
20
+ export function generateApiDocs(input) {
21
+ const { registry, config } = input;
22
+ const { locales } = config;
23
+ if (locales.length === 0)
24
+ throw new Error("apiDocs needs at least one locale.");
25
+ const unsupported = locales.filter((locale) => !isApiDocsLocale(locale));
26
+ if (unsupported.length > 0) {
27
+ throw new Error(`Unsupported apiDocs locales: ${unsupported.join(", ")}.`);
28
+ }
29
+ const collected = collectApiDocsModel(registry, {
30
+ locales,
31
+ examples: examplesByHandler(input.examples),
32
+ webhookExamples: webhookExamplesByEvent(input.webhookExamples ?? []),
33
+ });
34
+ if (collected === undefined) {
35
+ return { files: new Map(), problems: [{ kind: "patFeatureMissing" }] };
36
+ }
37
+ const { model } = collected;
38
+ const problems = [];
39
+ const files = new Map();
40
+ const pages = [];
41
+ const handlersByQn = new Map(model.handlers.map((handler) => [handler.qn, handler]));
42
+ const addPage = (path, locale, kind, order, page, scope) => {
43
+ files.set(path, page.content);
44
+ pages.push({
45
+ path,
46
+ locale,
47
+ kind,
48
+ order,
49
+ title: page.title,
50
+ description: page.description,
51
+ ...(scope !== undefined && { scope }),
52
+ anchors: page.anchors,
53
+ });
54
+ };
55
+ for (const locale of locales) {
56
+ if (!isApiDocsLocale(locale))
57
+ continue;
58
+ const resolved = resolveApiDocsTexts(locale, config.texts?.[locale]);
59
+ problems.push(...resolved.problems);
60
+ const { texts } = resolved;
61
+ addPage(`${locale}/overview.md`, locale, "overview", OVERVIEW_ORDER, renderOverview({ handlers: model.handlers, texts, baseUrl: config.baseUrl }));
62
+ addPage(`${locale}/tokens.md`, locale, "tokens", TOKENS_ORDER, renderTokens({
63
+ model,
64
+ locale,
65
+ texts,
66
+ baseUrl: config.baseUrl,
67
+ appName: config.appName,
68
+ planNote: config.planNote?.[locale],
69
+ }));
70
+ model.scopes.forEach((scope, index) => {
71
+ addPage(`${locale}/reference/${slugify(scope.domain)}.md`, locale, "reference", REFERENCE_ORDER_START + index, renderReferencePage({
72
+ scope,
73
+ handlers: handlersByQn,
74
+ anchors: anchorsForPage(scope.handlers.map((entry) => entry.qn)),
75
+ locale,
76
+ texts,
77
+ baseUrl: config.baseUrl,
78
+ }), scope.domain);
79
+ });
80
+ if (model.events.length > 0) {
81
+ const deliveryText = config.webhookDelivery?.[locale];
82
+ if (deliveryText === undefined)
83
+ problems.push({ kind: "webhookDeliveryTextMissing", locale });
84
+ addPage(`${locale}/events.md`, locale, "events", REFERENCE_ORDER_START + model.scopes.length, renderEventsPage({ events: model.events, locale, texts, deliveryText }));
85
+ }
86
+ }
87
+ files.set(OPENAPI_FILE, renderOpenApi({
88
+ model,
89
+ source: input.source,
90
+ baseUrl: config.baseUrl,
91
+ appName: config.appName,
92
+ descriptionLocale: locales.includes("en") ? "en" : (locales[0] ?? "en"),
93
+ }));
94
+ files.set(INDEX_FILE, renderIndexJson(input.source, locales, pages));
95
+ const handlerQns = model.handlers.map((handler) => handler.qn);
96
+ problems.push(...findApiDocHandlerGaps([...registry.features.values()], new Set(handlerQns)).map((gap) => ({ kind: "docGap", gap })), ...findDescriptionTranslationGaps(registry, { handlerQns, locales }).flatMap((gap) => gap.locale === undefined
97
+ ? []
98
+ : [{ kind: "descriptionTranslationMissing", qn: gap.qn, locale: gap.locale }]), ...uiWriteProblems(registry, model, config.uiOnlyWrites ?? []), ...model.events.flatMap((event) => event.untranslatedLocales.map((locale) => ({
99
+ kind: "webhookEventWithoutDescriptionTranslation",
100
+ qn: event.qn,
101
+ locale,
102
+ }))));
103
+ return { files, problems: sortApiDocsProblems(problems) };
104
+ }
@@ -0,0 +1,15 @@
1
+ import type { PageAnchor } from "./markdown.ts";
2
+ import type { ApiDocsSource } from "./model.ts";
3
+ export type ApiDocsPageKind = "overview" | "tokens" | "reference" | "events";
4
+ export type ApiDocsPageEntry = {
5
+ readonly path: string;
6
+ readonly locale: string;
7
+ readonly kind: ApiDocsPageKind;
8
+ readonly order: number;
9
+ readonly title: string;
10
+ readonly description: string;
11
+ readonly scope?: string;
12
+ readonly anchors: readonly PageAnchor[];
13
+ };
14
+ export declare const INDEX_FILE = "index.json";
15
+ export declare function renderIndexJson(source: ApiDocsSource, locales: readonly string[], pages: readonly ApiDocsPageEntry[]): string;
@@ -0,0 +1,6 @@
1
+ import { compareIds } from "../labels.js";
2
+ export const INDEX_FILE = "index.json";
3
+ export function renderIndexJson(source, locales, pages) {
4
+ const sorted = [...pages].sort((a, b) => compareIds(a.locale, b.locale) || a.order - b.order || compareIds(a.path, b.path));
5
+ return `${JSON.stringify({ source, locales, pages: sorted }, null, 2)}\n`;
6
+ }
@@ -0,0 +1,9 @@
1
+ export type { ApiDocsDiff } from "./check.ts";
2
+ export { diffApiDocsOutput } from "./check.ts";
3
+ export { type ApiExampleFile, ApiExampleFileSchema, type NamedApiExample, type NamedWebhookExample, type WebhookExampleFile, WebhookExampleFileSchema, } from "./examples.ts";
4
+ export { type ApiDocsInput, type ApiDocsResult, generateApiDocs, OPENAPI_FILE, } from "./generate.ts";
5
+ export { INDEX_FILE } from "./index-json.ts";
6
+ export type { ApiDocsSource, ResolvedApiDocsConfig } from "./model.ts";
7
+ export { type ApiDocsProblem, formatApiDocsProblem } from "./problems.ts";
8
+ export type { ApiDocsLocale, ApiDocsTexts } from "./texts/index.ts";
9
+ export { apiDocsLocales, formatApiDocsText, isApiDocsLocale } from "./texts/index.ts";
@@ -0,0 +1,6 @@
1
+ export { diffApiDocsOutput } from "./check.js";
2
+ export { ApiExampleFileSchema, WebhookExampleFileSchema, } from "./examples.js";
3
+ export { generateApiDocs, OPENAPI_FILE, } from "./generate.js";
4
+ export { INDEX_FILE } from "./index-json.js";
5
+ export { formatApiDocsProblem } from "./problems.js";
6
+ export { apiDocsLocales, formatApiDocsText, isApiDocsLocale } from "./texts/index.js";
@@ -0,0 +1,61 @@
1
+ import * as z from "zod";
2
+ import type { ApiDocsHandler } from "./model.ts";
3
+ import { type ApiDocsTexts } from "./texts/index.ts";
4
+ export declare const LIST_INPUT_JSON_SCHEMA: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
5
+ cursor: z.ZodOptional<z.ZodString>;
6
+ limit: z.ZodOptional<z.ZodNumber>;
7
+ search: z.ZodOptional<z.ZodString>;
8
+ sort: z.ZodOptional<z.ZodString>;
9
+ sortDirection: z.ZodOptional<z.ZodEnum<{
10
+ asc: "asc";
11
+ desc: "desc";
12
+ }>>;
13
+ offset: z.ZodOptional<z.ZodNumber>;
14
+ totalCount: z.ZodOptional<z.ZodBoolean>;
15
+ includeDeleted: z.ZodOptional<z.ZodBoolean>;
16
+ onlyDeleted: z.ZodOptional<z.ZodBoolean>;
17
+ filter: z.ZodOptional<z.ZodObject<{
18
+ field: z.ZodString;
19
+ op: z.ZodEnum<{
20
+ eq: "eq";
21
+ gt: "gt";
22
+ gte: "gte";
23
+ in: "in";
24
+ lt: "lt";
25
+ lte: "lte";
26
+ ne: "ne";
27
+ }>;
28
+ value: z.ZodUnknown;
29
+ }, z.core.$strip>>;
30
+ filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
31
+ field: z.ZodString;
32
+ op: z.ZodEnum<{
33
+ eq: "eq";
34
+ gt: "gt";
35
+ gte: "gte";
36
+ in: "in";
37
+ lt: "lt";
38
+ lte: "lte";
39
+ ne: "ne";
40
+ }>;
41
+ value: z.ZodUnknown;
42
+ }, z.core.$strip>>>;
43
+ namedFilter: z.ZodOptional<z.ZodString>;
44
+ aggregate: z.ZodOptional<z.ZodObject<{
45
+ groupBy: z.ZodOptional<z.ZodString>;
46
+ measures: z.ZodDefault<z.ZodArray<z.ZodObject<{
47
+ field: z.ZodString;
48
+ kind: z.ZodEnum<{
49
+ avg: "avg";
50
+ count: "count";
51
+ max: "max";
52
+ min: "min";
53
+ sum: "sum";
54
+ }>;
55
+ }, z.core.$strip>>>;
56
+ }, z.core.$strip>>;
57
+ }, z.core.$strip>>;
58
+ export declare function listParameterText(texts: ApiDocsTexts, name: string): string | undefined;
59
+ /** True when the handler takes exactly the generated entity list input, so the shared
60
+ * list parameter texts describe its fields. */
61
+ export declare function takesEntityListInput(handler: ApiDocsHandler): boolean;
@@ -0,0 +1,28 @@
1
+ import { DEFAULT_LIST_LIMIT, entityListSchema, MAX_LIST_LIMIT, } from "@cosmicdrift/kumiko-framework/engine";
2
+ import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
3
+ import * as z from "zod";
4
+ import { FILTER_OPS } from "../filter-ops.js";
5
+ import { codeSpan } from "./markdown.js";
6
+ import { formatApiDocsText } from "./texts/index.js";
7
+ export const LIST_INPUT_JSON_SCHEMA = z.toJSONSchema(entityListSchema, { io: "input" });
8
+ const LIST_PARAMETER_NAMES = Object.keys(LIST_INPUT_JSON_SCHEMA.properties ?? {}).sort();
9
+ export function listParameterText(texts, name) {
10
+ const text = Object.entries(texts.listParameters).find(([key]) => key === name)?.[1];
11
+ return text === undefined
12
+ ? undefined
13
+ : formatApiDocsText(text, {
14
+ default: DEFAULT_LIST_LIMIT,
15
+ max: MAX_LIST_LIMIT,
16
+ ops: FILTER_OPS.map(codeSpan).join(", "),
17
+ });
18
+ }
19
+ /** True when the handler takes exactly the generated entity list input, so the shared
20
+ * list parameter texts describe its fields. */
21
+ export function takesEntityListInput(handler) {
22
+ const properties = handler.inputSchema?.["properties"];
23
+ if (!isPlainObject(properties))
24
+ return false;
25
+ const names = Object.keys(properties).sort();
26
+ return (names.length === LIST_PARAMETER_NAMES.length &&
27
+ names.every((name, index) => name === LIST_PARAMETER_NAMES[index]));
28
+ }
@@ -0,0 +1,29 @@
1
+ export declare function escapeCell(text: string): string;
2
+ export declare function table(header: readonly string[], rows: readonly (readonly string[])[]): string;
3
+ /** Code span that survives backticks inside the text. */
4
+ export declare function codeSpan(text: string): string;
5
+ export declare function fenced(language: string, body: string): string;
6
+ /** Only `title` and `description`: the markdown must stay valid for any static-site tooling. */
7
+ export declare function frontmatter(title: string, description: string): string;
8
+ /** Blocks joined by blank lines; the file ends with exactly one newline. */
9
+ export declare function joinBlocks(blocks: readonly string[]): string;
10
+ export type PageAnchor = {
11
+ readonly id: string;
12
+ /** The heading text exactly as rendered. */
13
+ readonly heading: string;
14
+ readonly level: 2 | 3;
15
+ readonly qn?: string;
16
+ };
17
+ export type RenderedPage = {
18
+ readonly title: string;
19
+ readonly description: string;
20
+ readonly content: string;
21
+ readonly anchors: readonly PageAnchor[];
22
+ };
23
+ /** Collects blocks and, for every heading, an anchor entry: the ids stay in index.json
24
+ * instead of the heading so they are the same in every language. */
25
+ export declare function pageBuilder(title: string, description: string): {
26
+ add(...more: readonly string[]): void;
27
+ section(id: string, heading: string, level?: 2 | 3, qn?: string): void;
28
+ finish(): RenderedPage;
29
+ };
@@ -0,0 +1,48 @@
1
+ const TABLE_CELL_BREAKS = /\s*[\r\n]+\s*/g;
2
+ export function escapeCell(text) {
3
+ return text.replace(TABLE_CELL_BREAKS, " ").replace(/\|/g, "\\|");
4
+ }
5
+ export function table(header, rows) {
6
+ const line = (cells) => `| ${cells.map(escapeCell).join(" | ")} |`;
7
+ return [line(header), line(header.map(() => "---")), ...rows.map(line)].join("\n");
8
+ }
9
+ /** Code span that survives backticks inside the text. */
10
+ export function codeSpan(text) {
11
+ const longestRun = Math.max(0, ...[...text.matchAll(/`+/g)].map((match) => match[0].length));
12
+ const fence = "`".repeat(longestRun + 1);
13
+ return longestRun > 0 ? `${fence} ${text} ${fence}` : `${fence}${text}${fence}`;
14
+ }
15
+ export function fenced(language, body) {
16
+ return [`\`\`\`${language}`, body, "```"].join("\n");
17
+ }
18
+ /** Only `title` and `description`: the markdown must stay valid for any static-site tooling. */
19
+ export function frontmatter(title, description) {
20
+ return [
21
+ "---",
22
+ `title: ${JSON.stringify(title)}`,
23
+ `description: ${JSON.stringify(description)}`,
24
+ "---",
25
+ ].join("\n");
26
+ }
27
+ /** Blocks joined by blank lines; the file ends with exactly one newline. */
28
+ export function joinBlocks(blocks) {
29
+ return `${blocks.filter((block) => block !== "").join("\n\n")}\n`;
30
+ }
31
+ /** Collects blocks and, for every heading, an anchor entry: the ids stay in index.json
32
+ * instead of the heading so they are the same in every language. */
33
+ export function pageBuilder(title, description) {
34
+ const blocks = [frontmatter(title, description)];
35
+ const anchors = [];
36
+ return {
37
+ add(...more) {
38
+ blocks.push(...more);
39
+ },
40
+ section(id, heading, level = 2, qn) {
41
+ blocks.push(`${"#".repeat(level)} ${heading}`);
42
+ anchors.push({ id, heading, level, ...(qn !== undefined && { qn }) });
43
+ },
44
+ finish() {
45
+ return { title, description, content: joinBlocks(blocks), anchors };
46
+ },
47
+ };
48
+ }
@@ -0,0 +1,8 @@
1
+ import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
2
+ import type { RegistryManifestView } from "./../types.ts";
3
+ import type { LocalizedText } from "./model.ts";
4
+ /** The nav chain that leads to the token list ("Settings › API tokens"), or the
5
+ * screen title when the app places the screen in no nav. */
6
+ export declare function patMenuPath(registry: RegistryManifestView, feature: FeatureDefinition, locales: readonly string[]): LocalizedText;
7
+ /** Label of the list screen's first navigate toolbar action, the button that opens the mint form. */
8
+ export declare function patCreateLabel(registry: RegistryManifestView, feature: FeatureDefinition, locales: readonly string[]): LocalizedText;
@@ -0,0 +1,60 @@
1
+ import { PAT_SCREEN_ID } from "../../personal-access-tokens/index.js";
2
+ import { localizedLabels, localizedLabelsForSuffix, localizedScreenTitleLabels, pickLabel, } from "../labels.js";
3
+ const MENU_SEPARATOR = " › ";
4
+ function perLocale(locales, labels) {
5
+ const entries = locales.flatMap((locale) => {
6
+ const label = pickLabel(labels, locale);
7
+ return label === undefined ? [] : [[locale, label]];
8
+ });
9
+ return Object.fromEntries(entries);
10
+ }
11
+ function patListScreenId(registry, feature) {
12
+ const prefix = `${feature.name}:`;
13
+ for (const id of registry.getAllScreens().keys()) {
14
+ if (id.startsWith(prefix) && id.endsWith(`:${PAT_SCREEN_ID}`))
15
+ return id;
16
+ }
17
+ return undefined;
18
+ }
19
+ function navChainTo(registry, screenId) {
20
+ const navs = registry.getAllNavs();
21
+ const leaf = [...navs.values()].find((nav) => nav.screen === screenId);
22
+ if (leaf === undefined)
23
+ return undefined;
24
+ const chain = [];
25
+ const seen = new Set();
26
+ for (let nav = leaf; nav && !seen.has(nav.id);) {
27
+ seen.add(nav.id);
28
+ chain.unshift(nav);
29
+ nav = nav.parent === undefined ? undefined : navs.get(nav.parent);
30
+ }
31
+ return chain;
32
+ }
33
+ /** The nav chain that leads to the token list ("Settings › API tokens"), or the
34
+ * screen title when the app places the screen in no nav. */
35
+ export function patMenuPath(registry, feature, locales) {
36
+ const translations = registry.getAllTranslations();
37
+ const screenId = patListScreenId(registry, feature);
38
+ if (screenId === undefined)
39
+ return {};
40
+ const chain = navChainTo(registry, screenId);
41
+ if (chain === undefined)
42
+ return perLocale(locales, localizedScreenTitleLabels(translations, screenId));
43
+ return Object.fromEntries(locales.map((locale) => [
44
+ locale,
45
+ chain
46
+ .map((nav) => pickLabel(localizedLabels(translations, nav.label), locale) ?? nav.id)
47
+ .join(MENU_SEPARATOR),
48
+ ]));
49
+ }
50
+ /** Label of the list screen's first navigate toolbar action, the button that opens the mint form. */
51
+ export function patCreateLabel(registry, feature, locales) {
52
+ const screen = feature.screens?.[PAT_SCREEN_ID];
53
+ if (screen?.type !== "projectionList")
54
+ return {};
55
+ const action = screen.toolbarActions?.find((candidate) => candidate.kind === "navigate");
56
+ if (action === undefined)
57
+ return {};
58
+ const labels = localizedLabelsForSuffix(registry.getAllTranslations(), action.label);
59
+ return perLocale(locales, labels);
60
+ }
@@ -0,0 +1,76 @@
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
+ /** One string per requested locale. */
6
+ export type LocalizedText = Readonly<Record<string, string>>;
7
+ export type ApiDocsHandlerKind = "query" | "write";
8
+ export type ApiDocsHandler = {
9
+ readonly qn: string;
10
+ readonly kind: ApiDocsHandlerKind;
11
+ readonly title: LocalizedText;
12
+ readonly description: LocalizedText;
13
+ /** `undefined` when the input schema has no JSON Schema form. */
14
+ readonly inputSchema: Readonly<Record<string, unknown>> | undefined;
15
+ readonly excludedFields: readonly string[];
16
+ readonly fieldLabels: Readonly<Record<string, LocalizedText>>;
17
+ readonly example: ApiExampleFile | undefined;
18
+ };
19
+ export type ApiDocsGrantLevel = "read" | "write";
20
+ export type ApiDocsScopeHandler = {
21
+ readonly qn: string;
22
+ readonly grant: ApiDocsGrantLevel;
23
+ };
24
+ export type ApiDocsScope = {
25
+ readonly domain: string;
26
+ readonly label: string;
27
+ /** Read handlers always; write handlers only when the domain declares a write level. */
28
+ readonly handlers: readonly ApiDocsScopeHandler[];
29
+ readonly hasWriteLevel: boolean;
30
+ };
31
+ export type ApiDocsEvent = {
32
+ /** `feature:name` for a declared contract, `entity.verb` for an entity lifecycle event. */
33
+ readonly qn: string;
34
+ /** Event name as delivered; headings, anchors and OpenAPI webhook keys use it. */
35
+ readonly wireName: string;
36
+ readonly origin: "declared" | "entity";
37
+ readonly entity?: string;
38
+ readonly verb?: WebhookEntityVerb;
39
+ readonly version: number;
40
+ /** Declared events only; entity events are described from a template per verb. */
41
+ readonly description: LocalizedText;
42
+ /** Entity events only: the entity's translated label. */
43
+ readonly entityLabel: LocalizedText;
44
+ /** Declared events: requested locales other than `en` without a translated description. */
45
+ readonly untranslatedLocales: readonly string[];
46
+ /** Translated field labels per payload row name, used before the schema description. */
47
+ readonly fieldLabels: Readonly<Record<string, LocalizedText>>;
48
+ /** `undefined` when the payload has no JSON Schema form. */
49
+ readonly payloadSchema: Readonly<Record<string, unknown>> | undefined;
50
+ /** Scope domains that list the event, in code-point order; each grants it at `read` level. */
51
+ readonly domains: readonly string[];
52
+ readonly example: WebhookExampleFile | undefined;
53
+ };
54
+ export type ApiDocsModel = {
55
+ readonly scopes: readonly ApiDocsScope[];
56
+ /** Public webhook events, sorted by QN; empty when no scope lists one. */
57
+ readonly events: readonly ApiDocsEvent[];
58
+ /** Every handler any scope reaches, sorted by QN. */
59
+ readonly handlers: readonly ApiDocsHandler[];
60
+ readonly menuPath: LocalizedText;
61
+ readonly createLabel: LocalizedText;
62
+ readonly rateLimit: PatRateLimit;
63
+ readonly toggleable: boolean;
64
+ };
65
+ export type ApiDocsSource = {
66
+ readonly framework: string;
67
+ readonly app: {
68
+ readonly name: string;
69
+ readonly version: string;
70
+ };
71
+ };
72
+ export type ResolvedApiDocsConfig = AppApiDocsConfig & {
73
+ readonly locales: readonly string[];
74
+ readonly baseUrl: string;
75
+ readonly appName: string;
76
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,32 @@
1
+ import type { AgentDocGap } from "../agent-doc-lint.ts";
2
+ export type ApiDocsProblem = {
3
+ readonly kind: "patFeatureMissing";
4
+ } | {
5
+ readonly kind: "docGap";
6
+ readonly gap: AgentDocGap;
7
+ } | {
8
+ readonly kind: "descriptionTranslationMissing";
9
+ readonly qn: string;
10
+ readonly locale: string;
11
+ } | {
12
+ readonly kind: "uiWriteOutsideScopes";
13
+ readonly qn: string;
14
+ readonly screens: readonly string[];
15
+ } | {
16
+ readonly kind: "unusedUiOnlyWrite";
17
+ readonly pattern: string;
18
+ } | {
19
+ readonly kind: "webhookDeliveryTextMissing";
20
+ readonly locale: string;
21
+ } | {
22
+ readonly kind: "webhookEventWithoutDescriptionTranslation";
23
+ readonly qn: string;
24
+ readonly locale: string;
25
+ } | {
26
+ readonly kind: "invalidTextOverride";
27
+ readonly locale: string;
28
+ readonly key: string;
29
+ readonly cause: string;
30
+ };
31
+ export declare function formatApiDocsProblem(problem: ApiDocsProblem): string;
32
+ export declare function sortApiDocsProblems(problems: readonly ApiDocsProblem[]): ApiDocsProblem[];
@@ -0,0 +1,28 @@
1
+ import { webhookEventDescriptionKey } from "@cosmicdrift/kumiko-framework/engine";
2
+ import { formatAgentDocGap } from "../agent-doc-lint.js";
3
+ export function formatApiDocsProblem(problem) {
4
+ switch (problem.kind) {
5
+ case "patFeatureMissing":
6
+ return "[patFeatureMissing] The app mounts no personal-access-tokens feature with scopes, so there is nothing to document.";
7
+ case "docGap":
8
+ return `[docGap] ${formatAgentDocGap(problem.gap)}`;
9
+ case "descriptionTranslationMissing":
10
+ return `[descriptionTranslationMissing] ${problem.qn} has no \`${problem.locale}\` description translation.`;
11
+ case "uiWriteOutsideScopes":
12
+ 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.`;
13
+ case "unusedUiOnlyWrite":
14
+ return `[unusedUiOnlyWrite] apiDocs.uiOnlyWrites pattern "${problem.pattern}" matches no UI write outside the scopes.`;
15
+ case "webhookDeliveryTextMissing":
16
+ return `[webhookDeliveryTextMissing] Webhook events are public but apiDocs.webhookDelivery has no \`${problem.locale}\` text.`;
17
+ case "webhookEventWithoutDescriptionTranslation":
18
+ return `[webhookEventWithoutDescriptionTranslation] ${problem.qn} has no \`${problem.locale}\` description translation (key ${webhookEventDescriptionKey(problem.qn)}).`;
19
+ case "invalidTextOverride":
20
+ return `[invalidTextOverride] apiDocs.texts.${problem.locale}["${problem.key}"]: ${problem.cause}`;
21
+ }
22
+ }
23
+ export function sortApiDocsProblems(problems) {
24
+ const keyed = problems.map((problem) => ({ problem, key: formatApiDocsProblem(problem) }));
25
+ return keyed
26
+ .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
27
+ .map(({ problem }) => problem);
28
+ }
@@ -0,0 +1,12 @@
1
+ import { type RenderedPage } from "./markdown.ts";
2
+ import type { ApiDocsEvent } from "./model.ts";
3
+ import { type ApiDocsTexts } from "./texts/index.ts";
4
+ export type EventsInput = {
5
+ readonly events: readonly ApiDocsEvent[];
6
+ readonly locale: string;
7
+ readonly texts: ApiDocsTexts;
8
+ /** The app's delivery description; the section stays, empty, when the app wrote none. */
9
+ readonly deliveryText: string | undefined;
10
+ };
11
+ export declare function describeEvent(event: ApiDocsEvent, locale: string, texts: ApiDocsTexts): string;
12
+ export declare function renderEventsPage(input: EventsInput): RenderedPage;