@wildo-ai/saas-technical-doc 1.1.1

package/dist/esm/openapi/api-reference-targets.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Public API-reference targets and fragments.
+ *
+ * Source documentation refers to semantic API identities; the generated
+ * reference resolves those identities into these readable public fragments.
+ * Do not use OpenAPI array positions, encoded internal refs, or a hand-built
+ * URL as a cross-document target: each of those changes for reasons unrelated
+ * to the consumer contract.
+ */
+/** Stable portal roots owned by the application-consumer documentation product. */
+export declare enum ApplicationConsumerDocumentationRoute {
+    GET_STARTED = "GET_STARTED",
+    ACCESS_AND_IDENTITY = "ACCESS_AND_IDENTITY",
+    USER_ADMINISTRATION = "USER_ADMINISTRATION",
+    INTEGRATIONS = "INTEGRATIONS",
+    API_REFERENCE = "API_REFERENCE",
+    APPLICATION_ADMINISTRATION_API_REFERENCE = "APPLICATION_ADMINISTRATION_API_REFERENCE"
+}
+/** The public contract part a documentation link can target inside an API reference. */
+export declare enum ApiReferenceTargetKind {
+    CATEGORY = "CATEGORY",
+    RESOURCE = "RESOURCE",
+    OPERATION_FAMILY = "OPERATION_FAMILY",
+    OPERATION = "OPERATION",
+    REQUEST = "REQUEST",
+    RESPONSE = "RESPONSE",
+    COMPONENT_SCHEMA = "COMPONENT_SCHEMA"
+}
+/**
+ * Readable identity material used only to construct a public fragment.
+ *
+ * A later generated link index maps canonical `x-wildo` identities to this
+ * shape. Keeping the public shape separate stops an internal namespaced ref
+ * from leaking into copied URLs while retaining an exact resolver boundary.
+ */
+export type ApiReferencePublicTarget = {
+    readonly kind: ApiReferenceTargetKind.CATEGORY;
+    readonly categoryName: string;
+} | {
+    readonly kind: ApiReferenceTargetKind.RESOURCE;
+    readonly resourceName: string;
+} | {
+    readonly kind: ApiReferenceTargetKind.OPERATION_FAMILY;
+    readonly resourceName: string;
+    readonly operationName: string;
+} | {
+    readonly kind: ApiReferenceTargetKind.OPERATION;
+    readonly operationId: string;
+} | {
+    readonly kind: ApiReferenceTargetKind.REQUEST;
+    readonly operationId: string;
+} | {
+    readonly kind: ApiReferenceTargetKind.RESPONSE;
+    readonly operationId: string;
+    readonly status: string;
+} | {
+    readonly kind: ApiReferenceTargetKind.COMPONENT_SCHEMA;
+    readonly schemaName: string;
+};
+/** Resolves a stable, human-readable route path for a built-in portal root. */
+export declare function applicationConsumerDocumentationRoutePath(route: ApplicationConsumerDocumentationRoute): string;
+/**
+ * Resolves a relative documentation URL suitable for prefixing with an
+ * application-owned docs base URL. API contract targets are deliberately
+ * confined to an API-reference root: a guide cannot silently become a second
+ * endpoint-reference renderer merely by carrying an API fragment.
+ */
+export declare function applicationConsumerDocumentationTargetPath(route: ApplicationConsumerDocumentationRoute, target?: ApiReferencePublicTarget): string;
+/** Produces a readable fragment for one API-reference contract target. */
+export declare function apiReferenceTargetFragment(target: ApiReferencePublicTarget): string;
+//# sourceMappingURL=api-reference-targets.d.ts.map

package/dist/esm/openapi/api-reference-targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-reference-targets.d.ts","sourceRoot":"","sources":["../../../../src/openapi/api-reference-targets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,mFAAmF;AACnF,oBAAY,qCAAqC;IAC/C,WAAW,gBAAgB;IAC3B,mBAAmB,wBAAwB;IAC3C,mBAAmB,wBAAwB;IAC3C,YAAY,iBAAiB;IAC7B,aAAa,kBAAkB;IAC/B,wCAAwC,6CAA6C;CACtF;AAED,wFAAwF;AACxF,oBAAY,sBAAsB;IAChC,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,gBAAgB,qBAAqB;IACrC,SAAS,cAAc;IACvB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,gBAAgB,qBAAqB;CACtC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC,QAAQ,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC,QAAQ,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC,gBAAgB,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GACzH;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC,SAAS,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC,OAAO,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC,QAAQ,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzG;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC,gBAAgB,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5F,+EAA+E;AAC/E,wBAAgB,yCAAyC,CAAC,KAAK,EAAE,qCAAqC,GAAG,MAAM,CAmB9G;AAED;;;;;GAKG;AACH,wBAAgB,0CAA0C,CACxD,KAAK,EAAE,qCAAqC,EAC5C,MAAM,CAAC,EAAE,wBAAwB,GAChC,MAAM,CAQR;AAED,0EAA0E;AAC1E,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,CAqBnF"}

package/dist/esm/openapi/api-reference-targets.js

@@ -0,0 +1,114 @@
+/**
+ * Public API-reference targets and fragments.
+ *
+ * Source documentation refers to semantic API identities; the generated
+ * reference resolves those identities into these readable public fragments.
+ * Do not use OpenAPI array positions, encoded internal refs, or a hand-built
+ * URL as a cross-document target: each of those changes for reasons unrelated
+ * to the consumer contract.
+ */
+/** Stable portal roots owned by the application-consumer documentation product. */
+export var ApplicationConsumerDocumentationRoute;
+(function (ApplicationConsumerDocumentationRoute) {
+    ApplicationConsumerDocumentationRoute["GET_STARTED"] = "GET_STARTED";
+    ApplicationConsumerDocumentationRoute["ACCESS_AND_IDENTITY"] = "ACCESS_AND_IDENTITY";
+    ApplicationConsumerDocumentationRoute["USER_ADMINISTRATION"] = "USER_ADMINISTRATION";
+    ApplicationConsumerDocumentationRoute["INTEGRATIONS"] = "INTEGRATIONS";
+    ApplicationConsumerDocumentationRoute["API_REFERENCE"] = "API_REFERENCE";
+    ApplicationConsumerDocumentationRoute["APPLICATION_ADMINISTRATION_API_REFERENCE"] = "APPLICATION_ADMINISTRATION_API_REFERENCE";
+})(ApplicationConsumerDocumentationRoute || (ApplicationConsumerDocumentationRoute = {}));
+/** The public contract part a documentation link can target inside an API reference. */
+export var ApiReferenceTargetKind;
+(function (ApiReferenceTargetKind) {
+    ApiReferenceTargetKind["CATEGORY"] = "CATEGORY";
+    ApiReferenceTargetKind["RESOURCE"] = "RESOURCE";
+    ApiReferenceTargetKind["OPERATION_FAMILY"] = "OPERATION_FAMILY";
+    ApiReferenceTargetKind["OPERATION"] = "OPERATION";
+    ApiReferenceTargetKind["REQUEST"] = "REQUEST";
+    ApiReferenceTargetKind["RESPONSE"] = "RESPONSE";
+    ApiReferenceTargetKind["COMPONENT_SCHEMA"] = "COMPONENT_SCHEMA";
+})(ApiReferenceTargetKind || (ApiReferenceTargetKind = {}));
+/** Resolves a stable, human-readable route path for a built-in portal root. */
+export function applicationConsumerDocumentationRoutePath(route) {
+    switch (route) {
+        case ApplicationConsumerDocumentationRoute.GET_STARTED:
+            return '/get-started';
+        case ApplicationConsumerDocumentationRoute.ACCESS_AND_IDENTITY:
+            return '/access-and-identity';
+        case ApplicationConsumerDocumentationRoute.USER_ADMINISTRATION:
+            return '/user-administration';
+        case ApplicationConsumerDocumentationRoute.INTEGRATIONS:
+            return '/integrations';
+        case ApplicationConsumerDocumentationRoute.API_REFERENCE:
+            return '/api';
+        case ApplicationConsumerDocumentationRoute.APPLICATION_ADMINISTRATION_API_REFERENCE:
+            return '/api/application-administration';
+        default: {
+            const exhaustiveRoute = route;
+            throw new Error(`Unsupported application-consumer documentation route: ${String(exhaustiveRoute)}`);
+        }
+    }
+}
+/**
+ * Resolves a relative documentation URL suitable for prefixing with an
+ * application-owned docs base URL. API contract targets are deliberately
+ * confined to an API-reference root: a guide cannot silently become a second
+ * endpoint-reference renderer merely by carrying an API fragment.
+ */
+export function applicationConsumerDocumentationTargetPath(route, target) {
+    const routePath = applicationConsumerDocumentationRoutePath(route);
+    if (target === undefined)
+        return routePath;
+    if (route !== ApplicationConsumerDocumentationRoute.API_REFERENCE
+        && route !== ApplicationConsumerDocumentationRoute.APPLICATION_ADMINISTRATION_API_REFERENCE) {
+        throw new Error(`Documentation route '${route}' cannot target an API-reference contract`);
+    }
+    return `${routePath}#${apiReferenceTargetFragment(target)}`;
+}
+/** Produces a readable fragment for one API-reference contract target. */
+export function apiReferenceTargetFragment(target) {
+    switch (target.kind) {
+        case ApiReferenceTargetKind.CATEGORY:
+            return `category-${readableFragmentPart(target.categoryName)}`;
+        case ApiReferenceTargetKind.RESOURCE:
+            return `resource-${readableFragmentPart(target.resourceName)}`;
+        case ApiReferenceTargetKind.OPERATION_FAMILY:
+            return `resource-${readableFragmentPart(target.resourceName)}--operation-${readableFragmentPart(target.operationName)}`;
+        case ApiReferenceTargetKind.OPERATION:
+            return `operation-${readableFragmentPart(target.operationId)}`;
+        case ApiReferenceTargetKind.REQUEST:
+            return `operation-${readableFragmentPart(target.operationId)}--request`;
+        case ApiReferenceTargetKind.RESPONSE:
+            return `operation-${readableFragmentPart(target.operationId)}--response-${readableFragmentPart(target.status)}`;
+        case ApiReferenceTargetKind.COMPONENT_SCHEMA:
+            return `schema-${readableFragmentPart(target.schemaName)}`;
+        default: {
+            const exhaustiveTarget = target;
+            throw new Error(`Unsupported API-reference target: ${JSON.stringify(exhaustiveTarget)}`);
+        }
+    }
+}
+/**
+ * Converts a declared identifier to public URL vocabulary without silently
+ * accepting arbitrary punctuation. The generated model separately rejects
+ * collisions, so this readable form never needs an opaque digest suffix.
+ */
+function readableFragmentPart(value) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(value);
+    }
+    catch {
+        throw new Error(`API-reference public fragment cannot represent identifier '${value}'`);
+    }
+    const normalized = decoded
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .replace(/[:_\s]+/g, '-')
+        .toLowerCase();
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(normalized)) {
+        throw new Error(`API-reference public fragment cannot represent identifier '${value}'`);
+    }
+    return normalized;
+}
+//# sourceMappingURL=api-reference-targets.js.map

package/dist/esm/openapi/api-reference-targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-reference-targets.js","sourceRoot":"","sources":["../../../../src/openapi/api-reference-targets.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Public API-reference targets and fragments.\n *\n * Source documentation refers to semantic API identities; the generated\n * reference resolves those identities into these readable public fragments.\n * Do not use OpenAPI array positions, encoded internal refs, or a hand-built\n * URL as a cross-document target: each of those changes for reasons unrelated\n * to the consumer contract.\n */\n\n/** Stable portal roots owned by the application-consumer documentation product. */\nexport enum ApplicationConsumerDocumentationRoute {\n  GET_STARTED = 'GET_STARTED',\n  ACCESS_AND_IDENTITY = 'ACCESS_AND_IDENTITY',\n  USER_ADMINISTRATION = 'USER_ADMINISTRATION',\n  INTEGRATIONS = 'INTEGRATIONS',\n  API_REFERENCE = 'API_REFERENCE',\n  APPLICATION_ADMINISTRATION_API_REFERENCE = 'APPLICATION_ADMINISTRATION_API_REFERENCE',\n}\n\n/** The public contract part a documentation link can target inside an API reference. */\nexport enum ApiReferenceTargetKind {\n  CATEGORY = 'CATEGORY',\n  RESOURCE = 'RESOURCE',\n  OPERATION_FAMILY = 'OPERATION_FAMILY',\n  OPERATION = 'OPERATION',\n  REQUEST = 'REQUEST',\n  RESPONSE = 'RESPONSE',\n  COMPONENT_SCHEMA = 'COMPONENT_SCHEMA',\n}\n\n/**\n * Readable identity material used only to construct a public fragment.\n *\n * A later generated link index maps canonical `x-wildo` identities to this\n * shape. Keeping the public shape separate stops an internal namespaced ref\n * from leaking into copied URLs while retaining an exact resolver boundary.\n */\nexport type ApiReferencePublicTarget =\n  | { readonly kind: ApiReferenceTargetKind.CATEGORY; readonly categoryName: string }\n  | { readonly kind: ApiReferenceTargetKind.RESOURCE; readonly resourceName: string }\n  | { readonly kind: ApiReferenceTargetKind.OPERATION_FAMILY; readonly resourceName: string; readonly operationName: string }\n  | { readonly kind: ApiReferenceTargetKind.OPERATION; readonly operationId: string }\n  | { readonly kind: ApiReferenceTargetKind.REQUEST; readonly operationId: string }\n  | { readonly kind: ApiReferenceTargetKind.RESPONSE; readonly operationId: string; readonly status: string }\n  | { readonly kind: ApiReferenceTargetKind.COMPONENT_SCHEMA; readonly schemaName: string };\n\n/** Resolves a stable, human-readable route path for a built-in portal root. */\nexport function applicationConsumerDocumentationRoutePath(route: ApplicationConsumerDocumentationRoute): string {\n  switch (route) {\n    case ApplicationConsumerDocumentationRoute.GET_STARTED:\n      return '/get-started';\n    case ApplicationConsumerDocumentationRoute.ACCESS_AND_IDENTITY:\n      return '/access-and-identity';\n    case ApplicationConsumerDocumentationRoute.USER_ADMINISTRATION:\n      return '/user-administration';\n    case ApplicationConsumerDocumentationRoute.INTEGRATIONS:\n      return '/integrations';\n    case ApplicationConsumerDocumentationRoute.API_REFERENCE:\n      return '/api';\n    case ApplicationConsumerDocumentationRoute.APPLICATION_ADMINISTRATION_API_REFERENCE:\n      return '/api/application-administration';\n    default: {\n      const exhaustiveRoute: never = route;\n      throw new Error(`Unsupported application-consumer documentation route: ${String(exhaustiveRoute)}`);\n    }\n  }\n}\n\n/**\n * Resolves a relative documentation URL suitable for prefixing with an\n * application-owned docs base URL. API contract targets are deliberately\n * confined to an API-reference root: a guide cannot silently become a second\n * endpoint-reference renderer merely by carrying an API fragment.\n */\nexport function applicationConsumerDocumentationTargetPath(\n  route: ApplicationConsumerDocumentationRoute,\n  target?: ApiReferencePublicTarget,\n): string {\n  const routePath = applicationConsumerDocumentationRoutePath(route);\n  if (target === undefined) return routePath;\n  if (route !== ApplicationConsumerDocumentationRoute.API_REFERENCE\n    && route !== ApplicationConsumerDocumentationRoute.APPLICATION_ADMINISTRATION_API_REFERENCE) {\n    throw new Error(`Documentation route '${route}' cannot target an API-reference contract`);\n  }\n  return `${routePath}#${apiReferenceTargetFragment(target)}`;\n}\n\n/** Produces a readable fragment for one API-reference contract target. */\nexport function apiReferenceTargetFragment(target: ApiReferencePublicTarget): string {\n  switch (target.kind) {\n    case ApiReferenceTargetKind.CATEGORY:\n      return `category-${readableFragmentPart(target.categoryName)}`;\n    case ApiReferenceTargetKind.RESOURCE:\n      return `resource-${readableFragmentPart(target.resourceName)}`;\n    case ApiReferenceTargetKind.OPERATION_FAMILY:\n      return `resource-${readableFragmentPart(target.resourceName)}--operation-${readableFragmentPart(target.operationName)}`;\n    case ApiReferenceTargetKind.OPERATION:\n      return `operation-${readableFragmentPart(target.operationId)}`;\n    case ApiReferenceTargetKind.REQUEST:\n      return `operation-${readableFragmentPart(target.operationId)}--request`;\n    case ApiReferenceTargetKind.RESPONSE:\n      return `operation-${readableFragmentPart(target.operationId)}--response-${readableFragmentPart(target.status)}`;\n    case ApiReferenceTargetKind.COMPONENT_SCHEMA:\n      return `schema-${readableFragmentPart(target.schemaName)}`;\n    default: {\n      const exhaustiveTarget: never = target;\n      throw new Error(`Unsupported API-reference target: ${JSON.stringify(exhaustiveTarget)}`);\n    }\n  }\n}\n\n/**\n * Converts a declared identifier to public URL vocabulary without silently\n * accepting arbitrary punctuation. The generated model separately rejects\n * collisions, so this readable form never needs an opaque digest suffix.\n */\nfunction readableFragmentPart(value: string): string {\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(value);\n  } catch {\n    throw new Error(`API-reference public fragment cannot represent identifier '${value}'`);\n  }\n  const normalized = decoded\n    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')\n    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')\n    .replace(/[:_\\s]+/g, '-')\n    .toLowerCase();\n  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(normalized)) {\n    throw new Error(`API-reference public fragment cannot represent identifier '${value}'`);\n  }\n  return normalized;\n}\n"]}

package/dist/esm/openapi/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@wildo-ai/saas-technical-doc` — OpenAPI generation surface.
+ *
+ * Schemas describing the output of the companion's OpenAPI generation route
+ * (saas-technical-doc.md Steps 3 & 4). The generator IMPLEMENTATION lives
+ * under `../companion/` and is re-exported via the package's `./companion`
+ * subpath export. This sub-tree only ships the type-level contract so it is
+ * safely consumable from:
+ *   - the companion (Node) — to populate the response shape;
+ *   - the docs site (browser, build-time) — to import the canonical output
+ *     filenames so the Docusaurus plugin config stays in lockstep;
+ *   - any CI tooling that needs to inspect a generated artefact.
+ *
+ * @wildo-boundary
+ *   No React, no `react-dom`, no Node `fs`/`path` imports. Pure schemas.
+ */
+export * from './openapi-generation-output.schemas';
+export * from './api-reference-targets';
+export * from './api-reference-link-index';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/openapi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/openapi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,cAAc,qCAAqC,CAAC;AACpD,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC"}

package/dist/esm/openapi/index.js

@@ -0,0 +1,20 @@
+/**
+ * `@wildo-ai/saas-technical-doc` — OpenAPI generation surface.
+ *
+ * Schemas describing the output of the companion's OpenAPI generation route
+ * (saas-technical-doc.md Steps 3 & 4). The generator IMPLEMENTATION lives
+ * under `../companion/` and is re-exported via the package's `./companion`
+ * subpath export. This sub-tree only ships the type-level contract so it is
+ * safely consumable from:
+ *   - the companion (Node) — to populate the response shape;
+ *   - the docs site (browser, build-time) — to import the canonical output
+ *     filenames so the Docusaurus plugin config stays in lockstep;
+ *   - any CI tooling that needs to inspect a generated artefact.
+ *
+ * @wildo-boundary
+ *   No React, no `react-dom`, no Node `fs`/`path` imports. Pure schemas.
+ */
+export * from './openapi-generation-output.schemas.js';
+export * from './api-reference-targets.js';
+export * from './api-reference-link-index.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/openapi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/openapi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,cAAc,qCAAqC,CAAC;AACpD,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC","sourcesContent":["/**\n * `@wildo-ai/saas-technical-doc` — OpenAPI generation surface.\n *\n * Schemas describing the output of the companion's OpenAPI generation route\n * (saas-technical-doc.md Steps 3 & 4). The generator IMPLEMENTATION lives\n * under `../companion/` and is re-exported via the package's `./companion`\n * subpath export. This sub-tree only ships the type-level contract so it is\n * safely consumable from:\n *   - the companion (Node) — to populate the response shape;\n *   - the docs site (browser, build-time) — to import the canonical output\n *     filenames so the Docusaurus plugin config stays in lockstep;\n *   - any CI tooling that needs to inspect a generated artefact.\n *\n * @wildo-boundary\n *   No React, no `react-dom`, no Node `fs`/`path` imports. Pure schemas.\n */\n\nexport * from './openapi-generation-output.schemas';\nexport * from './api-reference-targets';\nexport * from './api-reference-link-index';\n"]}

package/dist/esm/openapi/openapi-generation-output.schemas.d.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+/**
+ * Consumer-facing API-reference section.
+ *
+ * This is intentionally not named after the framework's internal resource
+ * scopes. Organization-scoped, user-self, anonymous and ordinary
+ * authenticated operations all belong to the normal API reference. Only an
+ * operation whose accepted authorities are exclusively application
+ * administration roles belongs to the administration reference.
+ */
+export declare enum OpenApiSection {
+    /** The API consumed by customers, employees and external integrations. */
+    API_REFERENCE = "api_reference",
+    /** Privileged API for administrators of the generated application itself. */
+    APPLICATION_ADMINISTRATION_API_REFERENCE = "application_administration_api_reference"
+}
+/**
+ * Filename emitted into `<app>/technical-doc/openapi/` for each section.
+ *
+ * Locked stable names:
+ *   - normal API reference → `api.{yaml,json}`
+ *   - application administration →
+ *     `application-administration-api.{yaml,json}`
+ *
+ * Pinned here (rather than at a consumer call site) so every generated-output
+ * adapter stays in lockstep with the generator without re-declaring filenames.
+ */
+export declare const OPENAPI_OUTPUT_FILENAMES: Readonly<Record<OpenApiSection, Readonly<{
+    yaml: string;
+    json: string;
+}>>>;
+/**
+ * Per-section summary of what the generator produced.
+ *
+ * `operationCount` and `resourceCount` are diagnostic metadata returned
+ * over the wire by the companion route (Step 3) so the caller can render
+ * a "Generated 47 operations across 12 resources" confirmation in the
+ * companion UI without re-parsing the YAML.
+ */
+export declare const OpenApiSectionOutputSchema: z.ZodObject<{
+    section: z.ZodEnum<typeof OpenApiSection>;
+    operationCount: z.ZodNumber;
+    resourceCount: z.ZodNumber;
+    /**
+     * The sole semantic OpenAPI document. Format serialization belongs to the
+     * OpenAPI renderer so a caller cannot provide divergent YAML and JSON bytes.
+     */
+    document: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export type OpenApiSectionOutput = z.infer<typeof OpenApiSectionOutputSchema>;
+/**
+ * Top-level contract returned by the companion's
+ * `POST /companion/api/technical-doc/generate-openapi` route (Step 3).
+ *
+ * One entry per emitted section. A section is omitted entirely if it
+ * contains zero operations after source sectioning (for example, an app with
+ * no application-administration-only operations has no administration entry).
+ *
+ * The renderer consumes this same shape and writes both serializations to its
+ * stable generated OpenAPI directory. YAML remains human-reviewable; JSON is
+ * the browser renderer's contract. Neither serialization is independently
+ * authored.
+ */
+export declare const OpenApiGenerationOutputSchema: z.ZodObject<{
+    /** ISO-8601 timestamp of when the generation completed. */
+    generatedAt: z.ZodISODateTime;
+    /** The sections actually produced (zero-operation sections are omitted). */
+    sections: z.ZodArray<z.ZodObject<{
+        section: z.ZodEnum<typeof OpenApiSection>;
+        operationCount: z.ZodNumber;
+        resourceCount: z.ZodNumber;
+        /**
+         * The sole semantic OpenAPI document. Format serialization belongs to the
+         * OpenAPI renderer so a caller cannot provide divergent YAML and JSON bytes.
+         */
+        document: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type OpenApiGenerationOutput = z.infer<typeof OpenApiGenerationOutputSchema>;
+//# sourceMappingURL=openapi-generation-output.schemas.d.ts.map

package/dist/esm/openapi/openapi-generation-output.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-generation-output.schemas.d.ts","sourceRoot":"","sources":["../../../../src/openapi/openapi-generation-output.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,oBAAY,cAAc;IACxB,0EAA0E;IAC1E,aAAa,kBAAkB;IAC/B,6EAA6E;IAC7E,wCAAwC,6CAA6C;CACtF;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAS/G,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;;IAIrC;;;OAGG;;kBAEH,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B;IACxC,2DAA2D;;IAE3D,4EAA4E;;;;;QAxB5E;;;WAGG;;;kBAuBH,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC"}

package/dist/esm/openapi/openapi-generation-output.schemas.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+/**
+ * Consumer-facing API-reference section.
+ *
+ * This is intentionally not named after the framework's internal resource
+ * scopes. Organization-scoped, user-self, anonymous and ordinary
+ * authenticated operations all belong to the normal API reference. Only an
+ * operation whose accepted authorities are exclusively application
+ * administration roles belongs to the administration reference.
+ */
+export var OpenApiSection;
+(function (OpenApiSection) {
+    /** The API consumed by customers, employees and external integrations. */
+    OpenApiSection["API_REFERENCE"] = "api_reference";
+    /** Privileged API for administrators of the generated application itself. */
+    OpenApiSection["APPLICATION_ADMINISTRATION_API_REFERENCE"] = "application_administration_api_reference";
+})(OpenApiSection || (OpenApiSection = {}));
+/**
+ * Filename emitted into `<app>/technical-doc/openapi/` for each section.
+ *
+ * Locked stable names:
+ *   - normal API reference → `api.{yaml,json}`
+ *   - application administration →
+ *     `application-administration-api.{yaml,json}`
+ *
+ * Pinned here (rather than at a consumer call site) so every generated-output
+ * adapter stays in lockstep with the generator without re-declaring filenames.
+ */
+export const OPENAPI_OUTPUT_FILENAMES = {
+    [OpenApiSection.API_REFERENCE]: {
+        yaml: 'api.yaml',
+        json: 'api.json',
+    },
+    [OpenApiSection.APPLICATION_ADMINISTRATION_API_REFERENCE]: {
+        yaml: 'application-administration-api.yaml',
+        json: 'application-administration-api.json',
+    },
+};
+/**
+ * Per-section summary of what the generator produced.
+ *
+ * `operationCount` and `resourceCount` are diagnostic metadata returned
+ * over the wire by the companion route (Step 3) so the caller can render
+ * a "Generated 47 operations across 12 resources" confirmation in the
+ * companion UI without re-parsing the YAML.
+ */
+export const OpenApiSectionOutputSchema = z.strictObject({
+    section: z.enum(OpenApiSection),
+    operationCount: z.number().int().nonnegative(),
+    resourceCount: z.number().int().nonnegative(),
+    /**
+     * The sole semantic OpenAPI document. Format serialization belongs to the
+     * OpenAPI renderer so a caller cannot provide divergent YAML and JSON bytes.
+     */
+    document: z.record(z.string(), z.unknown()),
+});
+/**
+ * Top-level contract returned by the companion's
+ * `POST /companion/api/technical-doc/generate-openapi` route (Step 3).
+ *
+ * One entry per emitted section. A section is omitted entirely if it
+ * contains zero operations after source sectioning (for example, an app with
+ * no application-administration-only operations has no administration entry).
+ *
+ * The renderer consumes this same shape and writes both serializations to its
+ * stable generated OpenAPI directory. YAML remains human-reviewable; JSON is
+ * the browser renderer's contract. Neither serialization is independently
+ * authored.
+ */
+export const OpenApiGenerationOutputSchema = z.strictObject({
+    /** ISO-8601 timestamp of when the generation completed. */
+    generatedAt: z.iso.datetime(),
+    /** The sections actually produced (zero-operation sections are omitted). */
+    sections: z.array(OpenApiSectionOutputSchema).max(2),
+});
+//# sourceMappingURL=openapi-generation-output.schemas.js.map

package/dist/esm/openapi/openapi-generation-output.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-generation-output.schemas.js","sourceRoot":"","sources":["../../../../src/openapi/openapi-generation-output.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,cAKX;AALD,WAAY,cAAc;IACxB,0EAA0E;IAC1E,iDAA+B,CAAA;IAC/B,6EAA6E;IAC7E,uGAAqF,CAAA;AACvF,CAAC,EALW,cAAc,KAAd,cAAc,QAKzB;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA+E;IAClH,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE;QAC9B,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,UAAU;KACjB;IACD,CAAC,cAAc,CAAC,wCAAwC,CAAC,EAAE;QACzD,IAAI,EAAE,qCAAqC;QAC3C,IAAI,EAAE,qCAAqC;KAC5C;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,YAAY,CAAC;IACvD,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC;IAC/B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC9C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC7C;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;CAC5C,CAAC,CAAC;AAGH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,YAAY,CAAC;IAC1D,2DAA2D;IAC3D,WAAW,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;IAC7B,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACrD,CAAC,CAAC","sourcesContent":["import { z } from 'zod';\n\n/**\n * Consumer-facing API-reference section.\n *\n * This is intentionally not named after the framework's internal resource\n * scopes. Organization-scoped, user-self, anonymous and ordinary\n * authenticated operations all belong to the normal API reference. Only an\n * operation whose accepted authorities are exclusively application\n * administration roles belongs to the administration reference.\n */\nexport enum OpenApiSection {\n  /** The API consumed by customers, employees and external integrations. */\n  API_REFERENCE = 'api_reference',\n  /** Privileged API for administrators of the generated application itself. */\n  APPLICATION_ADMINISTRATION_API_REFERENCE = 'application_administration_api_reference',\n}\n\n/**\n * Filename emitted into `<app>/technical-doc/openapi/` for each section.\n *\n * Locked stable names:\n *   - normal API reference → `api.{yaml,json}`\n *   - application administration →\n *     `application-administration-api.{yaml,json}`\n *\n * Pinned here (rather than at a consumer call site) so every generated-output\n * adapter stays in lockstep with the generator without re-declaring filenames.\n */\nexport const OPENAPI_OUTPUT_FILENAMES: Readonly<Record<OpenApiSection, Readonly<{ yaml: string; json: string }>>> = {\n  [OpenApiSection.API_REFERENCE]: {\n    yaml: 'api.yaml',\n    json: 'api.json',\n  },\n  [OpenApiSection.APPLICATION_ADMINISTRATION_API_REFERENCE]: {\n    yaml: 'application-administration-api.yaml',\n    json: 'application-administration-api.json',\n  },\n};\n\n/**\n * Per-section summary of what the generator produced.\n *\n * `operationCount` and `resourceCount` are diagnostic metadata returned\n * over the wire by the companion route (Step 3) so the caller can render\n * a \"Generated 47 operations across 12 resources\" confirmation in the\n * companion UI without re-parsing the YAML.\n */\nexport const OpenApiSectionOutputSchema = z.strictObject({\n  section: z.enum(OpenApiSection),\n  operationCount: z.number().int().nonnegative(),\n  resourceCount: z.number().int().nonnegative(),\n  /**\n   * The sole semantic OpenAPI document. Format serialization belongs to the\n   * OpenAPI renderer so a caller cannot provide divergent YAML and JSON bytes.\n   */\n  document: z.record(z.string(), z.unknown()),\n});\nexport type OpenApiSectionOutput = z.infer<typeof OpenApiSectionOutputSchema>;\n\n/**\n * Top-level contract returned by the companion's\n * `POST /companion/api/technical-doc/generate-openapi` route (Step 3).\n *\n * One entry per emitted section. A section is omitted entirely if it\n * contains zero operations after source sectioning (for example, an app with\n * no application-administration-only operations has no administration entry).\n *\n * The renderer consumes this same shape and writes both serializations to its\n * stable generated OpenAPI directory. YAML remains human-reviewable; JSON is\n * the browser renderer's contract. Neither serialization is independently\n * authored.\n */\nexport const OpenApiGenerationOutputSchema = z.strictObject({\n  /** ISO-8601 timestamp of when the generation completed. */\n  generatedAt: z.iso.datetime(),\n  /** The sections actually produced (zero-operation sections are omitted). */\n  sections: z.array(OpenApiSectionOutputSchema).max(2),\n});\nexport type OpenApiGenerationOutput = z.infer<typeof OpenApiGenerationOutputSchema>;\n"]}

package/dist/esm/openapi-reference-model.exports.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Browser-safe and Node-safe OpenAPI reference-model entrypoint.
+ *
+ * Managed publication uses this narrow subpath to verify that the native
+ * renderer conserves the generated OpenAPI inventory without importing the
+ * React/auth runtime barrel. Docusaurus may consume the same projection.
+ */
+export * from './runtime/openapi-reference-model';
+export * from './runtime/openapi-reference-conservation';
+//# sourceMappingURL=openapi-reference-model.exports.d.ts.map

package/dist/esm/openapi-reference-model.exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-reference-model.exports.d.ts","sourceRoot":"","sources":["../../../src/openapi-reference-model.exports.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,mCAAmC,CAAC;AAClD,cAAc,0CAA0C,CAAC"}

package/dist/esm/openapi-reference-model.exports.js

@@ -0,0 +1,10 @@
+/**
+ * Browser-safe and Node-safe OpenAPI reference-model entrypoint.
+ *
+ * Managed publication uses this narrow subpath to verify that the native
+ * renderer conserves the generated OpenAPI inventory without importing the
+ * React/auth runtime barrel. Docusaurus may consume the same projection.
+ */
+export * from './runtime/openapi-reference-model.js';
+export * from './runtime/openapi-reference-conservation.js';
+//# sourceMappingURL=openapi-reference-model.exports.js.map

package/dist/esm/openapi-reference-model.exports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-reference-model.exports.js","sourceRoot":"","sources":["../../../src/openapi-reference-model.exports.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,mCAAmC,CAAC;AAClD,cAAc,0CAA0C,CAAC","sourcesContent":["/**\n * Browser-safe and Node-safe OpenAPI reference-model entrypoint.\n *\n * Managed publication uses this narrow subpath to verify that the native\n * renderer conserves the generated OpenAPI inventory without importing the\n * React/auth runtime barrel. Docusaurus may consume the same projection.\n */\n\nexport * from './runtime/openapi-reference-model';\nexport * from './runtime/openapi-reference-conservation';\n"]}

package/dist/esm/runtime/AuthExchangePage.d.ts

@@ -0,0 +1,84 @@
+import { type FC, type ReactNode } from 'react';
+/**
+ * Status of the auth-code exchange the page is performing.
+ *
+ *   - `pending`   — initial mount; effect has not yet run.
+ *   - `exchanging`— the `/auth/token/exchange` POST is in flight.
+ *   - `success`   — tokens received; about to navigate to `returnPath`.
+ *   - `error`     — exchange failed; the page renders a fallback message
+ *                   and a manual link back to the docs root.
+ *   - `missingCode`— landed on `/auth/exchange` without `?code=…` (someone
+ *                    bookmarked the page or arrived via a stale link).
+ */
+export type AuthExchangeStatus = 'pending' | 'exchanging' | 'success' | 'error' | 'missingCode';
+/**
+ * Page component mounted at `/auth/exchange` on the docs site
+ * (saas-technical-doc.md Step 5).
+ *
+ * Lifecycle on mount:
+ *
+ *   1. Read `?code=` and `?return=` from `window.location.search`.
+ *   2. If `code` is missing → render the missingCode UI (no network call).
+ *   3. Else call `useDocsAuthSession().beginExchange(code)`, which POSTs
+ *      `/auth/token/exchange` and updates the in-memory context.
+ *   4. On success, navigate to `returnPath` (defaults to `/`) using the
+ *      consumer-supplied `onSuccessNavigate` (Docusaurus / react-router
+ *      hosts MUST pass a client-side `history.push` — see the prop
+ *      docstring below for why a full reload is incorrect here).
+ *   5. On failure, render the error UI with a link back to `/`.
+ *
+ * Why a single component (rather than splitting effect + render):
+ *
+ *   - Keeps the exchange contract trivially auditable from one file.
+ *   - The effect intentionally runs ONCE per mount (`hasRunRef` guard) —
+ *     `code` values are single-use AUTH_CODE_EXCHANGE consumable tokens
+ *     and a stray re-mount in React 18 strict-mode dev would burn the
+ *     code with the second call returning `invalid_or_expired_code`.
+ *
+ * Visual layer: this component renders a minimal centered "Signing you
+ * in…" / error block. Apps that want to brand it can either pass a
+ * `render` prop (consumer-controlled UI for each status) or skip this
+ * component entirely and call `useDocsAuthSession().beginExchange(code)`
+ * from their own page. The default rendering deliberately uses inline
+ * styles (no Tailwind / no CSS imports) so the component can be mounted
+ * by any Docusaurus theme without dragging in extra build pipeline.
+ */
+export declare const AuthExchangePage: FC<{
+    /**
+     * Override the default rendering. Receives the current status and (when
+     * the page reaches a terminal state) a recovery URL the consumer can
+     * link back to.
+     */
+    render?: (props: {
+        status: AuthExchangeStatus;
+        returnPath: string;
+        error: string | null;
+    }) => ReactNode;
+    /**
+     * Post-success navigation. **SPA hosts (Docusaurus, react-router,
+     * Vite/React-Router apps) MUST pass a client-side router push** — the
+     * default `window.location.assign` triggers a full browser navigation
+     * which destroys the in-memory `DocsAuthProvider` state we just
+     * populated (the entire JS bundle re-executes from scratch on the
+     * destination page, the React tree re-mounts, and `session` resets to
+     * `'anonymous'`). For a Docusaurus consumer that looks like:
+     *
+     * ```tsx
+     * import { useHistory } from '@docusaurus/router';
+     *
+     * function AuthExchangeRoute() {
+     *   const history = useHistory();
+     *   return <AuthExchangePage onSuccessNavigate={(p) => history.push(p)} />;
+     * }
+     * ```
+     *
+     * The default `window.location.assign` only works for plain-HTML hosts
+     * that have no in-memory client state to preserve across the redirect.
+     * It is kept as the default so the runtime stays usable in those hosts
+     * with zero ceremony, but for SPAs failing to override it would
+     * silently break the entire handoff (the user lands on the destination
+     * page anonymous and any role-gated content rejects them).
+     */
+    onSuccessNavigate?: (returnPath: string) => void;
+}>;
+//# sourceMappingURL=AuthExchangePage.d.ts.map

package/dist/esm/runtime/AuthExchangePage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthExchangePage.d.ts","sourceRoot":"","sources":["../../../../src/runtime/AuthExchangePage.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAmD,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAIjG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,YAAY,GACZ,SAAS,GACT,OAAO,GACP,aAAa,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,kBAAkB,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,SAAS,CAAC;IACxG;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CAClD,CA8FA,CAAC"}