@cosmicdrift/kumiko-bundled-features 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/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/model.js +1 -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/seeding.d.ts +17 -2
- package/dist/auth-email-password/seeding.js +68 -6
- package/dist/auth-email-password/web/i18n.js +1 -0
- package/dist/auth-email-password/web/signup-screen.d.ts +1 -1
- package/dist/auth-email-password/web/signup-screen.js +20 -2
- package/dist/auth-email-password/web/static-account.d.ts +40 -0
- package/dist/auth-email-password/web/static-account.js +94 -0
- package/dist/auth-email-password/web/static-client.d.ts +38 -0
- package/dist/auth-email-password/web/static-client.js +169 -0
- package/dist/foundation-shared/demo-admin-env.d.ts +4 -0
- package/dist/foundation-shared/demo-admin-env.js +7 -0
- package/dist/foundation-shared/index.d.ts +1 -1
- package/dist/foundation-shared/index.js +1 -1
- 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/inbound-provider-imap/imap-client.d.ts +1 -1
- package/dist/inbound-provider-imap/imap-client.js +3 -1
- 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 +18 -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/feature.d.ts +3 -0
- package/dist/presence/feature.js +20 -0
- package/dist/presence/handlers/heartbeat.write.d.ts +12 -0
- package/dist/presence/handlers/heartbeat.write.js +31 -0
- package/dist/presence/handlers/leave.write.d.ts +8 -0
- package/dist/presence/handlers/leave.write.js +33 -0
- package/dist/presence/handlers/list.query.d.ts +7 -0
- package/dist/presence/handlers/list.query.js +28 -0
- package/dist/presence/index.d.ts +3 -0
- package/dist/presence/index.js +2 -0
- package/dist/presence/options.d.ts +17 -0
- package/dist/presence/options.js +13 -0
- package/dist/presence/payloads.d.ts +18 -0
- package/dist/presence/payloads.js +18 -0
- package/dist/presence/room.d.ts +13 -0
- package/dist/presence/room.js +35 -0
- package/dist/presence/store.d.ts +32 -0
- package/dist/presence/store.js +140 -0
- package/dist/sessions/feature.js +2 -2
- package/dist/sessions/handlers/last-activity-probe.route.d.ts +2 -0
- package/dist/sessions/handlers/last-activity-probe.route.js +14 -0
- package/dist/tenant-inactivity/check-inactive-tenants.js +12 -6
- package/dist/tenant-inactivity/constants.d.ts +1 -1
- package/dist/tenant-inactivity/constants.js +3 -1
- package/dist/tenant-inactivity/handlers/inactivity-state.query.js +2 -1
- package/dist/tenant-inactivity/handlers/keep-account.write.js +2 -1
- package/dist/tenant-inactivity/options.d.ts +1 -0
- package/dist/tenant-inactivity/remote-activity.d.ts +3 -1
- package/dist/tenant-inactivity/remote-activity.js +4 -1
- package/dist/tenant-inactivity/static-keep-account.d.ts +6 -0
- package/dist/tenant-inactivity/static-keep-account.js +15 -0
- package/dist/tenant-lifecycle/constants.d.ts +1 -0
- package/dist/tenant-lifecycle/constants.js +1 -0
- package/dist/tenant-lifecycle/handlers/cancel-destruction.write.js +2 -2
- package/dist/tenant-lifecycle/handlers/request-destruction.write.js +2 -1
- package/dist/tenant-lifecycle/index.d.ts +1 -1
- package/dist/tenant-lifecycle/index.js +1 -1
- package/dist/waitlist/static-submit.d.ts +15 -0
- package/dist/waitlist/static-submit.js +24 -0
- package/package.json +59 -11
- package/src/agent-tools/changes.json +24 -0
- package/src/auth-email-password/changes.json +24 -0
- package/src/inbound-mail-foundation/changes.json +6 -0
- package/src/inbound-provider-imap/changes.json +6 -0
- package/src/personal-access-tokens/changes.json +6 -0
- package/src/presence/changes.json +8 -0
- package/src/tenant-inactivity/changes.json +12 -0
- package/src/waitlist/changes.json +6 -0
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
|
|
2
|
+
import type { RegistryManifestView } from "./types.ts";
|
|
2
3
|
export declare const AgentDocGapKinds: {
|
|
3
4
|
readonly handlerSchemaNotExpressible: "handler-schema-not-expressible";
|
|
4
5
|
readonly handlerWithoutDescription: "handler-without-description";
|
|
5
6
|
readonly customScreenWithoutDescription: "custom-screen-without-description";
|
|
6
7
|
readonly exposedEntityWithoutDescription: "exposed-entity-without-description";
|
|
7
8
|
readonly handlerWithoutTranslation: "handler-without-translation";
|
|
9
|
+
readonly handlerWithoutDescriptionTranslation: "handler-without-description-translation";
|
|
8
10
|
};
|
|
9
11
|
export type AgentDocGapKind = (typeof AgentDocGapKinds)[keyof typeof AgentDocGapKinds];
|
|
10
12
|
export type AgentDocGap = {
|
|
@@ -12,7 +14,14 @@ export type AgentDocGap = {
|
|
|
12
14
|
readonly feature: string;
|
|
13
15
|
readonly kind: AgentDocGapKind;
|
|
14
16
|
readonly message: string;
|
|
17
|
+
readonly locale?: string;
|
|
15
18
|
};
|
|
16
19
|
export declare function findAgentDocGaps(features: readonly FeatureDefinition[]): readonly AgentDocGap[];
|
|
20
|
+
/** Description and schema gaps of exactly the handlers the API docs list. */
|
|
21
|
+
export declare function findApiDocHandlerGaps(features: readonly FeatureDefinition[], handlerQns: ReadonlySet<string>): readonly AgentDocGap[];
|
|
17
22
|
export declare function findHandlerTranslationGaps(features: readonly FeatureDefinition[]): readonly AgentDocGap[];
|
|
23
|
+
export declare function findDescriptionTranslationGaps(registry: Pick<RegistryManifestView, "getAllTranslations">, options: {
|
|
24
|
+
readonly handlerQns: readonly string[];
|
|
25
|
+
readonly locales: readonly string[];
|
|
26
|
+
}): readonly AgentDocGap[];
|
|
18
27
|
export declare function formatAgentDocGap(gap: AgentDocGap): string;
|
|
@@ -1,18 +1,21 @@
|
|
|
1
|
-
import { handlerFieldLabelKey, handlerTitleKey, isAgentVisibleScreen, QnTypes, qn, resolveAgentExposure, toKebab, } from "@cosmicdrift/kumiko-framework/engine";
|
|
1
|
+
import { handlerDescriptionKey, handlerFieldLabelKey, handlerTitleKey, isAgentVisibleScreen, QnTypes, qn, resolveAgentExposure, toKebab, } from "@cosmicdrift/kumiko-framework/engine";
|
|
2
2
|
import * as z from "zod";
|
|
3
|
-
import { systemOnlyPropertyNames } from "./
|
|
3
|
+
import { systemOnlyPropertyNames } from "./handler-schema.js";
|
|
4
|
+
import { localizedLabels } from "./labels.js";
|
|
4
5
|
export const AgentDocGapKinds = {
|
|
5
6
|
handlerSchemaNotExpressible: "handler-schema-not-expressible",
|
|
6
7
|
handlerWithoutDescription: "handler-without-description",
|
|
7
8
|
customScreenWithoutDescription: "custom-screen-without-description",
|
|
8
9
|
exposedEntityWithoutDescription: "exposed-entity-without-description",
|
|
9
10
|
handlerWithoutTranslation: "handler-without-translation",
|
|
11
|
+
handlerWithoutDescriptionTranslation: "handler-without-description-translation",
|
|
10
12
|
};
|
|
11
13
|
// No shared screen-type union exists in the codebase to import (ScreenDefinition
|
|
12
14
|
// is a discriminated union keyed by inline string literals) — name the one
|
|
13
15
|
// value this lint cares about instead of comparing against a bare string.
|
|
14
16
|
const CUSTOM_SCREEN_TYPE = "custom";
|
|
15
17
|
const ENTITY_QN_SEGMENT = "entity";
|
|
18
|
+
const DESCRIPTION_FALLBACK_LOCALE = "en";
|
|
16
19
|
// QNs contain `:`, so localeCompare's ICU punctuation rules would make sort
|
|
17
20
|
// order depend on runtime locale — compare by code point instead (same
|
|
18
21
|
// reasoning as agent-manifest.ts's compareIds).
|
|
@@ -35,18 +38,23 @@ function schemaNotExpressibleGap(feature, handlerQn, def, handlerNoun) {
|
|
|
35
38
|
};
|
|
36
39
|
}
|
|
37
40
|
}
|
|
38
|
-
function handlerDocGaps(feature, handlers, handlerQnType, handlerNoun
|
|
41
|
+
function handlerDocGaps(feature, handlers, handlerQnType, handlerNoun,
|
|
42
|
+
// Set for the API docs: only these handlers are checked, and an agent opt-out
|
|
43
|
+
// doesn't excuse them because the docs show every handler a token reaches.
|
|
44
|
+
onlyQns) {
|
|
39
45
|
const gaps = [];
|
|
40
46
|
const handlerKind = handlerQnType === QnTypes.write ? "write" : "query";
|
|
41
47
|
for (const [name, def] of Object.entries(handlers)) {
|
|
42
48
|
const handlerQn = qn(toKebab(feature.name), handlerQnType, toKebab(name));
|
|
49
|
+
if (onlyQns !== undefined && !onlyQns.has(handlerQn))
|
|
50
|
+
continue;
|
|
43
51
|
const isExposed = resolveAgentExposure(def, handlerKind).expose;
|
|
44
|
-
if (isExposed) {
|
|
52
|
+
if (isExposed || onlyQns !== undefined) {
|
|
45
53
|
const schemaGap = schemaNotExpressibleGap(feature, handlerQn, def, handlerNoun);
|
|
46
54
|
if (schemaGap)
|
|
47
55
|
gaps.push(schemaGap);
|
|
48
56
|
}
|
|
49
|
-
if (def.agent?.expose === false)
|
|
57
|
+
if (onlyQns === undefined && def.agent?.expose === false)
|
|
50
58
|
continue;
|
|
51
59
|
if (def.description !== undefined && def.description.trim() !== "")
|
|
52
60
|
continue;
|
|
@@ -172,6 +180,14 @@ export function findAgentDocGaps(features) {
|
|
|
172
180
|
// depend on it (mirrors agent-manifest.ts's sortedByKey rationale).
|
|
173
181
|
return [...gaps].sort((a, b) => compareByCodePoint(a.qn, b.qn));
|
|
174
182
|
}
|
|
183
|
+
/** Description and schema gaps of exactly the handlers the API docs list. */
|
|
184
|
+
export function findApiDocHandlerGaps(features, handlerQns) {
|
|
185
|
+
const gaps = features.flatMap((feature) => [
|
|
186
|
+
...handlerDocGaps(feature, feature.writeHandlers ?? {}, QnTypes.write, "write handler", handlerQns),
|
|
187
|
+
...handlerDocGaps(feature, feature.queryHandlers ?? {}, QnTypes.query, "query handler", handlerQns),
|
|
188
|
+
]);
|
|
189
|
+
return [...gaps].sort((a, b) => compareByCodePoint(a.qn, b.qn));
|
|
190
|
+
}
|
|
175
191
|
// Kept out of findAgentDocGaps on purpose: the published agent-manifest guard
|
|
176
192
|
// fails on every gap that function returns, and these are advisory.
|
|
177
193
|
export function findHandlerTranslationGaps(features) {
|
|
@@ -179,6 +195,27 @@ export function findHandlerTranslationGaps(features) {
|
|
|
179
195
|
const gaps = features.flatMap((feature) => translationGapsOfFeature(feature, coveredHandlerQns));
|
|
180
196
|
return [...gaps].sort((a, b) => compareByCodePoint(a.qn, b.qn));
|
|
181
197
|
}
|
|
198
|
+
// "en" is skipped because the docs fall back to the handler's `description` for it.
|
|
199
|
+
// Advisory like findHandlerTranslationGaps: not part of findAgentDocGaps.
|
|
200
|
+
export function findDescriptionTranslationGaps(registry, options) {
|
|
201
|
+
const translations = registry.getAllTranslations();
|
|
202
|
+
const gaps = [];
|
|
203
|
+
for (const handlerQn of options.handlerQns) {
|
|
204
|
+
const labels = localizedLabels(translations, handlerDescriptionKey(handlerQn));
|
|
205
|
+
for (const locale of options.locales) {
|
|
206
|
+
if (locale === DESCRIPTION_FALLBACK_LOCALE || labels[locale] !== undefined)
|
|
207
|
+
continue;
|
|
208
|
+
gaps.push({
|
|
209
|
+
qn: handlerQn,
|
|
210
|
+
feature: handlerQn.split(":")[0] ?? handlerQn,
|
|
211
|
+
kind: AgentDocGapKinds.handlerWithoutDescriptionTranslation,
|
|
212
|
+
locale,
|
|
213
|
+
message: `No \`${locale}\` translation under ${handlerDescriptionKey(handlerQn)}.`,
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
return [...gaps].sort((a, b) => compareByCodePoint(a.qn, b.qn) || compareByCodePoint(a.locale ?? "", b.locale ?? ""));
|
|
218
|
+
}
|
|
182
219
|
export function formatAgentDocGap(gap) {
|
|
183
220
|
return `${gap.qn} — ${gap.message}`;
|
|
184
221
|
}
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import type { AgentManifest, AgentManifestOptions, RegistryManifestView } from "./types.ts";
|
|
2
|
-
export declare function systemOnlyPropertyNames(jsonSchema: Record<string, unknown>): readonly string[];
|
|
3
2
|
/** Registry snapshot → AI-agent manifest. Pure, deterministic, no I/O — mirrors
|
|
4
3
|
* `buildToolCatalog`'s contract, just describing the app's shape instead of
|
|
5
4
|
* generating callable tools from it. */
|
|
@@ -1,74 +1,18 @@
|
|
|
1
|
-
import { hasAccess, isAgentVisibleScreen, resolveAgentExposure,
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import * as z from "zod";
|
|
1
|
+
import { hasAccess, isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-framework/engine";
|
|
2
|
+
import { handlerInputJsonSchema } from "./handler-schema.js";
|
|
3
|
+
import { compareIds, entryAsLabels, labelsForSuffix, pickLabel, screenTitleLabels, } from "./labels.js";
|
|
5
4
|
import { recordManifestDenyQns } from "./manifest-deny-qns.js";
|
|
6
5
|
import { isExplicitlyAgentHidden } from "./tool-catalog.js";
|
|
7
|
-
const FALLBACK_LOCALE = "en";
|
|
8
|
-
/** Requested locale, then English, then the first remaining locale in code-point
|
|
9
|
-
* order; `undefined` when the entry has no text at all (the key is then omitted). */
|
|
10
|
-
function pickLabel(labels, locale) {
|
|
11
|
-
const nonEmpty = (value) => value !== undefined && value !== "" ? value : undefined;
|
|
12
|
-
const firstLocale = Object.keys(labels)
|
|
13
|
-
.sort(compareIds)
|
|
14
|
-
.find((key) => nonEmpty(labels[key]));
|
|
15
|
-
return (nonEmpty(labels[locale]) ??
|
|
16
|
-
nonEmpty(labels[FALLBACK_LOCALE]) ??
|
|
17
|
-
(firstLocale !== undefined ? labels[firstLocale] : undefined));
|
|
18
|
-
}
|
|
19
6
|
function labelProp(labels, locale) {
|
|
20
7
|
const label = pickLabel(labels, locale);
|
|
21
8
|
return label === undefined ? {} : { label };
|
|
22
9
|
}
|
|
23
|
-
/** The manifest surfaces one string per locale — a plural entry reads as its
|
|
24
|
-
* CLDR `other` form since the manifest has no `count` to select a category. */
|
|
25
|
-
function entryAsLabels(entry) {
|
|
26
|
-
return Object.fromEntries(Object.entries(entry).map(([locale, value]) => [locale, translationValueOtherText(value)]));
|
|
27
|
-
}
|
|
28
|
-
const labelsIndexByTranslations = new WeakMap();
|
|
29
|
-
/** Every tail starting at a key boundary (`:` or `.`, with and without the
|
|
30
|
-
* separator) maps to the labels of the first key that ends with it. */
|
|
31
|
-
function buildSuffixIndex(translations) {
|
|
32
|
-
const index = new Map();
|
|
33
|
-
for (const [key, entry] of Object.entries(translations)) {
|
|
34
|
-
const labels = entryAsLabels(entry);
|
|
35
|
-
const addTail = (start) => {
|
|
36
|
-
const tail = key.slice(start);
|
|
37
|
-
if (!index.has(tail))
|
|
38
|
-
index.set(tail, labels);
|
|
39
|
-
};
|
|
40
|
-
addTail(0);
|
|
41
|
-
for (let position = 0; position < key.length; position++) {
|
|
42
|
-
if (key[position] === ":" || key[position] === ".") {
|
|
43
|
-
addTail(position);
|
|
44
|
-
addTail(position + 1);
|
|
45
|
-
}
|
|
46
|
-
}
|
|
47
|
-
}
|
|
48
|
-
return index;
|
|
49
|
-
}
|
|
50
|
-
/** Translation keys carry a feature prefix the manifest can't reconstruct
|
|
51
|
-
* (`showcase:entity:item:field:title`), so match on the suffix instead. The
|
|
52
|
-
* suffix must start at a `:` or `.` boundary of the key. */
|
|
53
|
-
function labelsForSuffix(translations, suffix) {
|
|
54
|
-
let index = labelsIndexByTranslations.get(translations);
|
|
55
|
-
if (index === undefined) {
|
|
56
|
-
index = buildSuffixIndex(translations);
|
|
57
|
-
labelsIndexByTranslations.set(translations, index);
|
|
58
|
-
}
|
|
59
|
-
return index.get(suffix) ?? {};
|
|
60
|
-
}
|
|
61
10
|
/** Nav/screen/workspace gating is opt-in: no rule means visible to everyone
|
|
62
11
|
* (NavDefinition.access). Handlers are the opposite — `hasAccess` is
|
|
63
12
|
* default-deny there. */
|
|
64
13
|
function uiVisible(access, roles) {
|
|
65
14
|
return access === undefined || hasAccess({ roles }, access);
|
|
66
15
|
}
|
|
67
|
-
// localeCompare depends on the runtime locale and ICU punctuation rules; qualified
|
|
68
|
-
// names contain `:`, so compare by code point instead for deterministic ordering.
|
|
69
|
-
function compareIds(a, b) {
|
|
70
|
-
return a < b ? -1 : a > b ? 1 : 0;
|
|
71
|
-
}
|
|
72
16
|
function dedupeSorted(values) {
|
|
73
17
|
return [...new Set(values)].sort(compareIds);
|
|
74
18
|
}
|
|
@@ -151,30 +95,6 @@ function buildFeatures(features, visibleFeatureNames) {
|
|
|
151
95
|
}
|
|
152
96
|
return result;
|
|
153
97
|
}
|
|
154
|
-
// Agent dispatch never runs as a system identity, so properties the engine only
|
|
155
|
-
// honors for system callers would be silently dropped — hide them from the tool.
|
|
156
|
-
export function systemOnlyPropertyNames(jsonSchema) {
|
|
157
|
-
const properties = jsonSchema["properties"];
|
|
158
|
-
if (typeof properties !== "object" || properties === null)
|
|
159
|
-
return [];
|
|
160
|
-
return Object.entries(properties)
|
|
161
|
-
.filter(([, property]) => isPlainObject(property) && property[SYSTEM_ONLY_JSON_SCHEMA_KEY] === true)
|
|
162
|
-
.map(([name]) => name);
|
|
163
|
-
}
|
|
164
|
-
function withoutSystemOnlyProperties(jsonSchema) {
|
|
165
|
-
const properties = jsonSchema["properties"];
|
|
166
|
-
if (typeof properties !== "object" || properties === null)
|
|
167
|
-
return jsonSchema;
|
|
168
|
-
const hidden = systemOnlyPropertyNames(jsonSchema);
|
|
169
|
-
if (hidden.length === 0)
|
|
170
|
-
return jsonSchema;
|
|
171
|
-
const required = jsonSchema["required"];
|
|
172
|
-
return {
|
|
173
|
-
...jsonSchema,
|
|
174
|
-
properties: Object.fromEntries(Object.entries(properties).filter(([name]) => !hidden.includes(name))),
|
|
175
|
-
...(Array.isArray(required) && { required: required.filter((name) => !hidden.includes(name)) }),
|
|
176
|
-
};
|
|
177
|
-
}
|
|
178
98
|
function buildHandlerEntry(qn, kind, def, roles, getHandlerEntity, denyQns) {
|
|
179
99
|
if (denyQns.has(qn))
|
|
180
100
|
return undefined;
|
|
@@ -186,16 +106,10 @@ function buildHandlerEntry(qn, kind, def, roles, getHandlerEntity, denyQns) {
|
|
|
186
106
|
// `agent.expose: true` without a `description` still opts in — the author
|
|
187
107
|
// asked for exposure explicitly, there's just nothing to show as prose.
|
|
188
108
|
const description = def.description !== undefined && def.description !== "" ? def.description : undefined;
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
// z.instanceof, ...) is unusable for an agent tool call — leave it out
|
|
193
|
-
// rather than ship a broken tool.
|
|
194
|
-
inputSchema = withoutSystemOnlyProperties(z.toJSONSchema(def.schema, { io: "input" }));
|
|
195
|
-
}
|
|
196
|
-
catch {
|
|
109
|
+
// Left out rather than shipped as a broken tool when the schema isn't expressible.
|
|
110
|
+
const inputSchema = handlerInputJsonSchema(def);
|
|
111
|
+
if (inputSchema === undefined)
|
|
197
112
|
return undefined;
|
|
198
|
-
}
|
|
199
113
|
const entity = getHandlerEntity(qn);
|
|
200
114
|
const excludedFields = "excludedFields" in def ? def.excludedFields : undefined;
|
|
201
115
|
return {
|
|
@@ -309,22 +223,18 @@ function visibleEntityNamesOf(registry, roles, denyQns, handlers, screens) {
|
|
|
309
223
|
...[...reachable].flatMap((n) => referenceTargetsOf(entities.get(n))),
|
|
310
224
|
]);
|
|
311
225
|
}
|
|
312
|
-
function lastSegment(qualifiedId) {
|
|
313
|
-
const idx = qualifiedId.lastIndexOf(":");
|
|
314
|
-
return idx === -1 ? qualifiedId : qualifiedId.slice(idx + 1);
|
|
315
|
-
}
|
|
316
226
|
function detailIdParam(screen) {
|
|
317
227
|
return screen.type === "projectionDetail" ? (screen.idParam ?? "id") : "id";
|
|
318
228
|
}
|
|
319
|
-
function screenTitles(translations, screenId,
|
|
320
|
-
const title = pickLabel(
|
|
229
|
+
function screenTitles(translations, screenId, locale) {
|
|
230
|
+
const title = pickLabel(screenTitleLabels(translations, screenId), locale);
|
|
321
231
|
return title === undefined ? {} : { title };
|
|
322
232
|
}
|
|
323
233
|
function buildScreenEntry(screen, screenWorkspaces, translations, locale) {
|
|
324
234
|
return {
|
|
325
235
|
id: screen.id,
|
|
326
236
|
type: screen.type,
|
|
327
|
-
...screenTitles(translations, screen.id,
|
|
237
|
+
...screenTitles(translations, screen.id, locale),
|
|
328
238
|
// `screen.description` may be a raw i18n key (`registry.getAllTranslations()`
|
|
329
239
|
// double-prefixes it, see build-app-schema.ts:77-81) — match on suffix like
|
|
330
240
|
// `labelsForSuffix` does for entity/field labels, else fall back to the
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export declare function handlerHeading(qn: string): string;
|
|
2
|
+
/** GitHub-style slug: lower case, punctuation dropped, spaces to hyphens. */
|
|
3
|
+
export declare function slugify(heading: string): string;
|
|
4
|
+
export type HandlerAnchor = {
|
|
5
|
+
readonly qn: string;
|
|
6
|
+
readonly heading: string;
|
|
7
|
+
readonly anchor: string;
|
|
8
|
+
};
|
|
9
|
+
/** Events are headed by their wire name. Declared (`feature:name`) and entity (`entity.verb`) names can
|
|
10
|
+
* slug alike once punctuation is dropped, so repeats get GitHub's `-1`, `-2` suffix in QN order. */
|
|
11
|
+
export declare function eventAnchors(qns: readonly string[]): readonly HandlerAnchor[];
|
|
12
|
+
/** Short headings, except when two handlers of one page would get the same slug:
|
|
13
|
+
* both then switch to the full QN form, which is unique by construction. */
|
|
14
|
+
export declare function anchorsForPage(qns: readonly string[]): readonly HandlerAnchor[];
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
const QN_TYPE_SEGMENTS = new Set(["query", "write"]);
|
|
2
|
+
const HEADING_SEPARATOR = ": ";
|
|
3
|
+
/** `helpdesk:write:ticket:close` becomes ["ticket", "close"]: the feature prefix and
|
|
4
|
+
* the `query`/`write` kind are noise inside a page that already names both. */
|
|
5
|
+
function tailSegments(qn) {
|
|
6
|
+
const segments = qn.split(":");
|
|
7
|
+
const rest = segments.slice(1);
|
|
8
|
+
return rest[0] !== undefined && QN_TYPE_SEGMENTS.has(rest[0]) ? rest.slice(1) : rest;
|
|
9
|
+
}
|
|
10
|
+
export function handlerHeading(qn) {
|
|
11
|
+
return tailSegments(qn).join(HEADING_SEPARATOR);
|
|
12
|
+
}
|
|
13
|
+
function fullHeading(qn) {
|
|
14
|
+
return qn.split(":").join(HEADING_SEPARATOR);
|
|
15
|
+
}
|
|
16
|
+
/** GitHub-style slug: lower case, punctuation dropped, spaces to hyphens. */
|
|
17
|
+
export function slugify(heading) {
|
|
18
|
+
return heading
|
|
19
|
+
.toLowerCase()
|
|
20
|
+
.replace(/[^\p{L}\p{N}\p{M}\s_-]/gu, "")
|
|
21
|
+
.replace(/\s/g, "-");
|
|
22
|
+
}
|
|
23
|
+
/** Events are headed by their wire name. Declared (`feature:name`) and entity (`entity.verb`) names can
|
|
24
|
+
* slug alike once punctuation is dropped, so repeats get GitHub's `-1`, `-2` suffix in QN order. */
|
|
25
|
+
export function eventAnchors(qns) {
|
|
26
|
+
const used = new Set();
|
|
27
|
+
return qns.map((qn) => {
|
|
28
|
+
const base = slugify(qn);
|
|
29
|
+
let anchor = base;
|
|
30
|
+
for (let repeat = 1; used.has(anchor); repeat++)
|
|
31
|
+
anchor = `${base}-${repeat}`;
|
|
32
|
+
used.add(anchor);
|
|
33
|
+
return { qn, heading: qn, anchor };
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
/** Short headings, except when two handlers of one page would get the same slug:
|
|
37
|
+
* both then switch to the full QN form, which is unique by construction. */
|
|
38
|
+
export function anchorsForPage(qns) {
|
|
39
|
+
const shortSlugCount = new Map();
|
|
40
|
+
for (const qn of qns) {
|
|
41
|
+
const slug = slugify(handlerHeading(qn));
|
|
42
|
+
shortSlugCount.set(slug, (shortSlugCount.get(slug) ?? 0) + 1);
|
|
43
|
+
}
|
|
44
|
+
return qns.map((qn) => {
|
|
45
|
+
const isCollision = (shortSlugCount.get(slugify(handlerHeading(qn))) ?? 0) > 1;
|
|
46
|
+
const heading = isCollision ? fullHeading(qn) : handlerHeading(qn);
|
|
47
|
+
return { qn, heading, anchor: slugify(heading) };
|
|
48
|
+
});
|
|
49
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export type ApiDocsDiff = {
|
|
2
|
+
readonly missing: readonly string[];
|
|
3
|
+
readonly changed: readonly string[];
|
|
4
|
+
readonly extra: readonly string[];
|
|
5
|
+
};
|
|
6
|
+
/** `expected` is what the generator produces, `actual` what is on disk. */
|
|
7
|
+
export declare function diffApiDocsOutput(expected: ReadonlyMap<string, string>, actual: ReadonlyMap<string, string>): ApiDocsDiff;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
const byCodePoint = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
|
|
2
|
+
/** `expected` is what the generator produces, `actual` what is on disk. */
|
|
3
|
+
export function diffApiDocsOutput(expected, actual) {
|
|
4
|
+
const missing = [...expected.keys()].filter((path) => !actual.has(path));
|
|
5
|
+
const changed = [...expected].filter(([path, content]) => {
|
|
6
|
+
const onDisk = actual.get(path);
|
|
7
|
+
return onDisk !== undefined && onDisk !== content;
|
|
8
|
+
});
|
|
9
|
+
const extra = [...actual.keys()].filter((path) => !expected.has(path));
|
|
10
|
+
return {
|
|
11
|
+
missing: missing.sort(byCodePoint),
|
|
12
|
+
changed: changed.map(([path]) => path).sort(byCodePoint),
|
|
13
|
+
extra: extra.sort(byCodePoint),
|
|
14
|
+
};
|
|
15
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { PatScopeConfig } from "../../personal-access-tokens/index.ts";
|
|
2
|
+
import type { RegistryManifestView } from "../types.ts";
|
|
3
|
+
import type { WebhookExampleFile } from "./examples.ts";
|
|
4
|
+
import type { ApiDocsEvent } from "./model.ts";
|
|
5
|
+
/** Events some scope lists, deduplicated and sorted by QN. An entry without a contract is
|
|
6
|
+
* skipped: the token feature's boot check already refuses to start with one. */
|
|
7
|
+
export declare function collectApiDocsEvents(registry: RegistryManifestView, scopes: PatScopeConfig, options: {
|
|
8
|
+
locales: readonly string[];
|
|
9
|
+
examples: ReadonlyMap<string, WebhookExampleFile>;
|
|
10
|
+
}): readonly ApiDocsEvent[];
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { createWebhookContractResolver, webhookEventDescriptionKey, webhookEventFieldKey, } from "@cosmicdrift/kumiko-framework/engine";
|
|
2
|
+
import * as z from "zod";
|
|
3
|
+
import { compareIds, entityFieldLabels, localizedLabels, localizedLabelsForSuffix, pickLabel, } from "../labels.js";
|
|
4
|
+
import { fieldRows } from "./schema-fields.js";
|
|
5
|
+
const SOURCE_LOCALE = "en";
|
|
6
|
+
function nonEmpty(value) {
|
|
7
|
+
return value !== undefined && value !== "" ? value : undefined;
|
|
8
|
+
}
|
|
9
|
+
function perLocale(locales, resolve) {
|
|
10
|
+
return Object.fromEntries(locales.map((locale) => [locale, resolve(locale)]));
|
|
11
|
+
}
|
|
12
|
+
/** `undefined` when the payload cannot be expressed as JSON Schema (transforms, instanceof, ...). */
|
|
13
|
+
function payloadJsonSchema(contract) {
|
|
14
|
+
try {
|
|
15
|
+
return z.toJSONSchema(contract.payload, { io: "output" });
|
|
16
|
+
}
|
|
17
|
+
catch {
|
|
18
|
+
// skip: a payload without a JSON Schema form is documented without a field table
|
|
19
|
+
return undefined;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
/** Declared contracts read `<feature>:webhook:<name>:field:<path>`, derived ones the entity's
|
|
23
|
+
* field labels. A row without a label keeps the schema description (`.describe()`). */
|
|
24
|
+
function fieldLabelsByRow(translations, contract, payloadSchema, locales) {
|
|
25
|
+
const { entity } = contract;
|
|
26
|
+
return Object.fromEntries(fieldRows(payloadSchema).flatMap(({ name }) => {
|
|
27
|
+
const labels = entity === undefined
|
|
28
|
+
? localizedLabels(translations, webhookEventFieldKey(contract.qn, name))
|
|
29
|
+
: entityFieldLabels(translations, entity, name);
|
|
30
|
+
const resolved = Object.fromEntries(locales.flatMap((locale) => {
|
|
31
|
+
// A declared field falls back to its English `.describe()`, never to another locale.
|
|
32
|
+
const label = entity === undefined
|
|
33
|
+
? (nonEmpty(labels[locale]) ?? nonEmpty(labels[SOURCE_LOCALE]))
|
|
34
|
+
: pickLabel(labels, locale);
|
|
35
|
+
return label === undefined ? [] : [[locale, label]];
|
|
36
|
+
}));
|
|
37
|
+
return [[name, resolved]];
|
|
38
|
+
}));
|
|
39
|
+
}
|
|
40
|
+
function buildEvent(registry, contract, domains, options) {
|
|
41
|
+
const translations = registry.getAllTranslations();
|
|
42
|
+
const { locales } = options;
|
|
43
|
+
const declared = contract.origin === "declared";
|
|
44
|
+
const descriptionLabels = declared
|
|
45
|
+
? localizedLabels(translations, webhookEventDescriptionKey(contract.qn))
|
|
46
|
+
: {};
|
|
47
|
+
const entityLabels = contract.entity === undefined
|
|
48
|
+
? {}
|
|
49
|
+
: localizedLabelsForSuffix(translations, `:entity:${contract.entity}`);
|
|
50
|
+
const payloadSchema = payloadJsonSchema(contract);
|
|
51
|
+
return {
|
|
52
|
+
qn: contract.qn,
|
|
53
|
+
wireName: contract.wireName,
|
|
54
|
+
origin: contract.origin,
|
|
55
|
+
...(contract.entity !== undefined && { entity: contract.entity }),
|
|
56
|
+
...(contract.verb !== undefined && { verb: contract.verb }),
|
|
57
|
+
version: contract.version,
|
|
58
|
+
description: perLocale(locales, (locale) => nonEmpty(descriptionLabels[locale]) ??
|
|
59
|
+
nonEmpty(descriptionLabels[SOURCE_LOCALE]) ??
|
|
60
|
+
contract.description),
|
|
61
|
+
entityLabel: perLocale(locales, (locale) => pickLabel(entityLabels, locale) ?? contract.entity ?? contract.qn),
|
|
62
|
+
untranslatedLocales: declared
|
|
63
|
+
? locales.filter((locale) => locale !== SOURCE_LOCALE && nonEmpty(descriptionLabels[locale]) === undefined)
|
|
64
|
+
: [],
|
|
65
|
+
fieldLabels: fieldLabelsByRow(translations, contract, payloadSchema, locales),
|
|
66
|
+
payloadSchema,
|
|
67
|
+
domains,
|
|
68
|
+
example: options.examples.get(contract.qn),
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
/** Events some scope lists, deduplicated and sorted by QN. An entry without a contract is
|
|
72
|
+
* skipped: the token feature's boot check already refuses to start with one. */
|
|
73
|
+
export function collectApiDocsEvents(registry, scopes, options) {
|
|
74
|
+
const domainsByEvent = new Map();
|
|
75
|
+
for (const domain of Object.keys(scopes).sort(compareIds)) {
|
|
76
|
+
for (const qn of scopes[domain]?.events ?? []) {
|
|
77
|
+
const domains = domainsByEvent.get(qn) ?? [];
|
|
78
|
+
if (!domains.includes(domain))
|
|
79
|
+
domains.push(domain);
|
|
80
|
+
domainsByEvent.set(qn, domains);
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
const resolver = createWebhookContractResolver([...registry.features.values()]);
|
|
84
|
+
return [...domainsByEvent.keys()].sort(compareIds).flatMap((qn) => {
|
|
85
|
+
const contract = resolver.get(qn);
|
|
86
|
+
return contract === undefined
|
|
87
|
+
? []
|
|
88
|
+
: [buildEvent(registry, contract, domainsByEvent.get(qn) ?? [], options)];
|
|
89
|
+
});
|
|
90
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
|
|
2
|
+
import type { RegistryManifestView } from "../types.ts";
|
|
3
|
+
import type { ApiExampleFile, WebhookExampleFile } from "./examples.ts";
|
|
4
|
+
import type { ApiDocsModel } from "./model.ts";
|
|
5
|
+
export declare function findPatFeature(registry: RegistryManifestView): FeatureDefinition | undefined;
|
|
6
|
+
/** Registry and PAT scope catalog to a locale-resolved model. Only handlers that
|
|
7
|
+
* some scope reaches are collected, so nothing outside the scopes can leak into the docs. */
|
|
8
|
+
export declare function collectApiDocsModel(registry: RegistryManifestView, options: {
|
|
9
|
+
readonly locales: readonly string[];
|
|
10
|
+
readonly examples: ReadonlyMap<string, ApiExampleFile>;
|
|
11
|
+
readonly webhookExamples: ReadonlyMap<string, WebhookExampleFile>;
|
|
12
|
+
}): {
|
|
13
|
+
readonly model: ApiDocsModel;
|
|
14
|
+
readonly patFeature: FeatureDefinition;
|
|
15
|
+
} | undefined;
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
import { patAllows } from "@cosmicdrift/kumiko-framework/api";
|
|
2
|
+
import { handlerDescriptionKey, handlerFieldLabelKey, handlerTitleKey, } from "@cosmicdrift/kumiko-framework/engine";
|
|
3
|
+
import { expandScopes, patRateLimitFromFeature, patScopesFromFeature, } from "../../personal-access-tokens/index.js";
|
|
4
|
+
import { handlerInputJsonSchema } from "../handler-schema.js";
|
|
5
|
+
import { compareIds, entityFieldLabels, localizedLabels, pickLabel } from "../labels.js";
|
|
6
|
+
import { collectApiDocsEvents } from "./collect-events.js";
|
|
7
|
+
import { patCreateLabel, patMenuPath } from "./menu-path.js";
|
|
8
|
+
import { fieldRows } from "./schema-fields.js";
|
|
9
|
+
import { isSystemOnlyHandler } from "./system-only.js";
|
|
10
|
+
export function findPatFeature(registry) {
|
|
11
|
+
return [...registry.features.values()].find((feature) => patScopesFromFeature(feature) !== undefined);
|
|
12
|
+
}
|
|
13
|
+
function nonEmpty(value) {
|
|
14
|
+
return value !== undefined && value !== "" ? value : undefined;
|
|
15
|
+
}
|
|
16
|
+
function perLocale(locales, resolve) {
|
|
17
|
+
return Object.fromEntries(locales.flatMap((locale) => {
|
|
18
|
+
const text = resolve(locale);
|
|
19
|
+
return text === undefined ? [] : [[locale, text]];
|
|
20
|
+
}));
|
|
21
|
+
}
|
|
22
|
+
function buildHandler(registry, qn, def, kind, locales, examples) {
|
|
23
|
+
const translations = registry.getAllTranslations();
|
|
24
|
+
const titleLabels = localizedLabels(translations, handlerTitleKey(qn));
|
|
25
|
+
const descriptionLabels = localizedLabels(translations, handlerDescriptionKey(qn));
|
|
26
|
+
const fallbackDescription = nonEmpty(def.description);
|
|
27
|
+
const inputSchema = handlerInputJsonSchema(def);
|
|
28
|
+
const entity = registry.getHandlerEntity(qn);
|
|
29
|
+
const fieldLabels = Object.fromEntries(fieldRows(inputSchema).map(({ name: field }) => {
|
|
30
|
+
const own = localizedLabels(translations, handlerFieldLabelKey(qn, field));
|
|
31
|
+
const labels = Object.keys(own).length > 0 || entity === undefined
|
|
32
|
+
? own
|
|
33
|
+
: entityFieldLabels(translations, entity, field);
|
|
34
|
+
return [field, perLocale(locales, (locale) => pickLabel(labels, locale))];
|
|
35
|
+
}));
|
|
36
|
+
return {
|
|
37
|
+
qn,
|
|
38
|
+
kind,
|
|
39
|
+
title: perLocale(locales, (locale) => pickLabel(titleLabels, locale) ?? fallbackDescription ?? qn),
|
|
40
|
+
description: perLocale(locales, (locale) => nonEmpty(descriptionLabels[locale]) ?? fallbackDescription),
|
|
41
|
+
inputSchema,
|
|
42
|
+
excludedFields: "excludedFields" in def && def.excludedFields ? [...def.excludedFields] : [],
|
|
43
|
+
fieldLabels,
|
|
44
|
+
example: examples.get(qn),
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
function scopeHandlers(domain, scopes, qns) {
|
|
48
|
+
const readQns = expandScopes(scopes, [`${domain}:read`]);
|
|
49
|
+
const writeQns = expandScopes(scopes, [`${domain}:write`]);
|
|
50
|
+
return qns.flatMap((qn) => {
|
|
51
|
+
const grant = patAllows(readQns, qn)
|
|
52
|
+
? "read"
|
|
53
|
+
: patAllows(writeQns, qn)
|
|
54
|
+
? "write"
|
|
55
|
+
: undefined;
|
|
56
|
+
return grant === undefined ? [] : [{ qn, grant }];
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
/** Registry and PAT scope catalog to a locale-resolved model. Only handlers that
|
|
60
|
+
* some scope reaches are collected, so nothing outside the scopes can leak into the docs. */
|
|
61
|
+
export function collectApiDocsModel(registry, options) {
|
|
62
|
+
const patFeature = findPatFeature(registry);
|
|
63
|
+
const scopeConfig = patFeature === undefined ? undefined : patScopesFromFeature(patFeature);
|
|
64
|
+
if (patFeature === undefined || scopeConfig === undefined)
|
|
65
|
+
return undefined;
|
|
66
|
+
const kinds = new Map();
|
|
67
|
+
for (const [qn, def] of registry.getAllQueryHandlers()) {
|
|
68
|
+
if (!isSystemOnlyHandler(def))
|
|
69
|
+
kinds.set(qn, { kind: "query", def });
|
|
70
|
+
}
|
|
71
|
+
for (const [qn, def] of registry.getAllWriteHandlers()) {
|
|
72
|
+
if (!isSystemOnlyHandler(def))
|
|
73
|
+
kinds.set(qn, { kind: "write", def });
|
|
74
|
+
}
|
|
75
|
+
const allQns = [...kinds.keys()].sort(compareIds);
|
|
76
|
+
const scopes = Object.keys(scopeConfig)
|
|
77
|
+
.sort(compareIds)
|
|
78
|
+
.map((domain) => ({
|
|
79
|
+
domain,
|
|
80
|
+
label: scopeConfig[domain]?.label ?? domain,
|
|
81
|
+
hasWriteLevel: (scopeConfig[domain]?.write?.length ?? 0) > 0,
|
|
82
|
+
handlers: scopeHandlers(domain, scopeConfig, allQns),
|
|
83
|
+
}));
|
|
84
|
+
const reachable = new Set(scopes.flatMap((scope) => scope.handlers.map((entry) => entry.qn)));
|
|
85
|
+
const handlers = allQns
|
|
86
|
+
.filter((qn) => reachable.has(qn))
|
|
87
|
+
.flatMap((qn) => {
|
|
88
|
+
const entry = kinds.get(qn);
|
|
89
|
+
return entry === undefined
|
|
90
|
+
? []
|
|
91
|
+
: [buildHandler(registry, qn, entry.def, entry.kind, options.locales, options.examples)];
|
|
92
|
+
});
|
|
93
|
+
return {
|
|
94
|
+
patFeature,
|
|
95
|
+
model: {
|
|
96
|
+
scopes,
|
|
97
|
+
events: collectApiDocsEvents(registry, scopeConfig, {
|
|
98
|
+
locales: options.locales,
|
|
99
|
+
examples: options.webhookExamples,
|
|
100
|
+
}),
|
|
101
|
+
handlers,
|
|
102
|
+
menuPath: patMenuPath(registry, patFeature, options.locales),
|
|
103
|
+
createLabel: patCreateLabel(registry, patFeature, options.locales),
|
|
104
|
+
rateLimit: patRateLimitFromFeature(patFeature),
|
|
105
|
+
toggleable: patFeature.toggleableDefault !== undefined,
|
|
106
|
+
},
|
|
107
|
+
};
|
|
108
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { ApiDocsHandler } from "./model.ts";
|
|
2
|
+
export declare function endpointOf(handler: Pick<ApiDocsHandler, "kind">): "/api/query" | "/api/write";
|
|
3
|
+
/** Recorded payload when there is one, else a value derived from the input schema. */
|
|
4
|
+
export declare function requestPayload(handler: ApiDocsHandler): unknown;
|
|
5
|
+
export declare function curlExample(handler: ApiDocsHandler, baseUrl: string): string;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { examplePayload } from "./schema-fields.js";
|
|
2
|
+
export function endpointOf(handler) {
|
|
3
|
+
return handler.kind === "query" ? "/api/query" : "/api/write";
|
|
4
|
+
}
|
|
5
|
+
/** Recorded payload when there is one, else a value derived from the input schema. */
|
|
6
|
+
export function requestPayload(handler) {
|
|
7
|
+
const recorded = handler.example?.request.body.payload;
|
|
8
|
+
if (recorded !== undefined)
|
|
9
|
+
return recorded;
|
|
10
|
+
return handler.inputSchema === undefined ? {} : examplePayload(handler.inputSchema);
|
|
11
|
+
}
|
|
12
|
+
// Inside a single-quoted shell string the only character that needs care is the quote itself.
|
|
13
|
+
function shellSingleQuoted(text) {
|
|
14
|
+
return `'${text.replaceAll("'", "'\\''")}'`;
|
|
15
|
+
}
|
|
16
|
+
export function curlExample(handler, baseUrl) {
|
|
17
|
+
const body = JSON.stringify({ type: handler.qn, payload: requestPayload(handler) }, null, 2);
|
|
18
|
+
return [
|
|
19
|
+
`curl -X POST ${baseUrl}${endpointOf(handler)} \\`,
|
|
20
|
+
` -H "Authorization: Bearer $API_TOKEN" \\`,
|
|
21
|
+
` -H "Content-Type: application/json" \\`,
|
|
22
|
+
` -d ${shellSingleQuoted(body)}`,
|
|
23
|
+
].join("\n");
|
|
24
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { ApiDocsTexts, DocumentedErrorCode } from "./texts/index.ts";
|
|
2
|
+
export type ErrorRow = {
|
|
3
|
+
readonly code: DocumentedErrorCode;
|
|
4
|
+
readonly status: number;
|
|
5
|
+
};
|
|
6
|
+
/** Every code the API can answer with: the framework table plus the token rejections,
|
|
7
|
+
* sorted by status then code. A code in both tables with the same status appears once. */
|
|
8
|
+
export declare function documentedErrorRows(texts: Pick<ApiDocsTexts, "errorMeanings">): readonly ErrorRow[];
|
|
9
|
+
export declare function errorMeaningTable(texts: ApiDocsTexts, columns: string): string;
|