@webpieces/api-doc-model 0.4.802 → 0.4.804

package/src/model/ApiDocModel.d.ts

@@ -112,7 +112,7 @@ export declare class DocumentedType {
     /** An index signature (`[k: string]: X`) — the OPEN-MAP half of an object that also has fields. */
     indexSignatureValue: TypeRef | undefined);
 }
-/** `@Endpoint(path, kind, options?)`'s third argument, as far as a document cares. */
+/** `@Endpoint(httpMethod, path, operation, kind, options?)`'s LAST argument, as a document sees it. */
 export declare class DocumentedEndpointOptions {
     readonly formPost: boolean;
     /** `calledBy` — REQUIRED by the decorator for `external`, absent otherwise. */
@@ -122,35 +122,127 @@ export declare class DocumentedEndpointOptions {
     /** `calledBy` — REQUIRED by the decorator for `external`, absent otherwise. */
     calledBy: string | undefined, callerKind: string | undefined);
 }
-/** The `@WpMcpTool(...)` declaration, when the method carries one. */
+/**
+ * The `@WpMcpTool(...)` declaration, when the method carries one — the TWO facts the source cannot
+ * otherwise state, and nothing else.
+ *
+ * `description` is deliberately NOT read off the decorator. The method's JSDoc is the description, for
+ * the agent and for the partner alike, byte-identical: two authored copies of one paragraph is the
+ * two-spellings shim, and its failure mode is concrete — the partner reads the JSDoc in the OpenAPI
+ * document while the agent reads the decorator string in `tools/list`, and they drift the first time
+ * somebody edits one. (The field still exists on the decorator; #984 deletes it across its 29 call
+ * sites. Nothing here reads it, so nothing here depends on a field that is about to disappear.)
+ *
+ * The three side-effect hints are not read either: they are COMPUTED from the endpoint's `operation`
+ * by `mcpHintsForOperation` in `@webpieces/core-util`, which is the one place that mapping lives.
+ * `READ | WRITE_IDEMPOTENT | WRITE` already says whether repeating a call is safe, so a hand-declared
+ * hint would be a second answer to a question the contract has answered.
+ */
 export declare class DocumentedMcpTool {
+    /**
+     * The STABLE protocol name. Deliberately independent of the method name, because renaming a
+     * method must not break a saved agent workflow.
+     */
     readonly name: string;
-    /** The tool hints an agent reads — `readOnly`, `destructive`, `idempotent`, `openWorld`. */
-    readonly hints: ReadonlyMap<string, boolean>;
-    constructor(name: string, 
-    /** The tool hints an agent reads — `readOnly`, `destructive`, `idempotent`, `openWorld`. */
-    hints: ReadonlyMap<string, boolean>);
+    constructor(
+    /**
+     * The STABLE protocol name. Deliberately independent of the method name, because renaming a
+     * method must not break a saved agent workflow.
+     */
+    name: string);
+}
+/**
+ * ONE credential of an api-key regime, PARSED — `{ in: 'header', name: 'x-api-key' }` or
+ * `{ in: 'bearer' }`.
+ *
+ * Parsed rather than left as source text because it is the one auth argument a renderer must turn
+ * into a STRUCTURE: an OpenAPI `securityScheme` is `{type: apiKey, in, name}` or
+ * `{type: http, scheme: bearer}`, and those are different documents. A renderer handed the string
+ * `"{ in: 'header', name: 'x-api-key' }"` would have to parse TypeScript to emit either one, which
+ * is this package's job and not a renderer's.
+ */
+export declare class DocumentedApiKeyCredential {
+    /** `header` or `bearer`, verbatim from the declaration. */
+    readonly location: string;
+    /** The header name. Undefined for `bearer`, whose location IS `Authorization`. */
+    readonly name: string | undefined;
+    /** The prose a docs site renders on its authorization card. */
+    readonly description: string | undefined;
+    constructor(
+    /** `header` or `bearer`, verbatim from the declaration. */
+    location: string, 
+    /** The header name. Undefined for `bearer`, whose location IS `Authorization`. */
+    name: string | undefined, 
+    /** The prose a docs site renders on its authorization card. */
+    description: string | undefined);
+}
+/** `@WpAuthApiKey(regime, credentials)`, parsed. See {@link DocumentedApiKeyCredential}. */
+export declare class DocumentedApiKey {
+    readonly regime: string;
+    /**
+     * Every credential the regime requires, IN DECLARATION ORDER. They are an AND — all of them
+     * are presented together — and the order is the order a published document lists them in.
+     */
+    readonly credentials: readonly DocumentedApiKeyCredential[];
+    constructor(regime: string, 
+    /**
+     * Every credential the regime requires, IN DECLARATION ORDER. They are an AND — all of them
+     * are presented together — and the order is the order a published document lists them in.
+     */
+    credentials: readonly DocumentedApiKeyCredential[]);
 }
 /** WHICH credential an endpoint demands — `@WpAuthPublic`, `@WpAuthJwt`, … — verbatim from the source. */
 export declare class DocumentedAuth {
     /** The decorator name as written, e.g. `WpAuthJwt`. */
     readonly decorator: string;
-    /** Its argument text, verbatim, when it took one. Undefined for `@WpAuthPublic()`. */
-    readonly argumentText: string | undefined;
+    /** Every argument's text, verbatim and in order. Empty for `@WpAuthPublic()`. */
+    readonly argumentTexts: readonly string[];
+    /**
+     * The PARSED api-key declaration, set only for `@WpAuthApiKey`. Every other decorator's
+     * argument is prose or a role list that a document quotes rather than restructures, so
+     * {@link argumentTexts} is all they need — see {@link DocumentedApiKeyCredential} for why
+     * this one is different.
+     */
+    readonly apiKey: DocumentedApiKey | undefined;
     constructor(
     /** The decorator name as written, e.g. `WpAuthJwt`. */
     decorator: string, 
-    /** Its argument text, verbatim, when it took one. Undefined for `@WpAuthPublic()`. */
-    argumentText: string | undefined);
+    /** Every argument's text, verbatim and in order. Empty for `@WpAuthPublic()`. */
+    argumentTexts: readonly string[], 
+    /**
+     * The PARSED api-key declaration, set only for `@WpAuthApiKey`. Every other decorator's
+     * argument is prose or a role list that a document quotes rather than restructures, so
+     * {@link argumentTexts} is all they need — see {@link DocumentedApiKeyCredential} for why
+     * this one is different.
+     */
+    apiKey: DocumentedApiKey | undefined);
 }
 /** One `@Endpoint` method of one contract. */
 export declare class DocumentedEndpoint {
     readonly methodName: string;
+    /**
+     * `GET` or `POST`, constant-folded from `@Endpoint`'s FIRST argument. A document cannot be
+     * written without it — the verb is the key an operation hangs under in `paths`.
+     */
+    readonly httpMethod: string;
     /** The path, constant-folded. A const that cannot be folded is a HARD FAILURE, never a guess. */
     readonly path: string;
+    /**
+     * `read` | `write-idempotent` | `write`, verbatim. The SIDE-EFFECT contract, which is
+     * independent of the verb: webpieces POSTs a read. A renderer publishes it rather than
+     * inferring safety from the verb, which for this framework would be wrong.
+     */
+    readonly operation: string;
     /** `rpc` | `cloudtasks` | `cron` | `external`, verbatim — this package invents no taxonomy. */
     readonly kind: string;
+    /**
+     * `{ hidden: true }` — this method is absent from the CUSTOMER document. It stays in the
+     * private one, and in the MCP one when it is a tool. WHICH documents the CONTRACT feeds at
+     * all is a different, class-level decision; see {@link ApiDocModel.apiTypes}.
+     */
     readonly hidden: boolean;
+    /** `{ openWorld: true }` — this operation may touch systems outside this service. */
+    readonly openWorld: boolean;
     readonly options: DocumentedEndpointOptions;
     readonly auth: DocumentedAuth | undefined;
     readonly mcpTool: DocumentedMcpTool | undefined;
@@ -164,10 +256,29 @@ export declare class DocumentedEndpoint {
     readonly request: TypeRef | undefined;
     readonly response: TypeRef | undefined;
     constructor(methodName: string, 
+    /**
+     * `GET` or `POST`, constant-folded from `@Endpoint`'s FIRST argument. A document cannot be
+     * written without it — the verb is the key an operation hangs under in `paths`.
+     */
+    httpMethod: string, 
     /** The path, constant-folded. A const that cannot be folded is a HARD FAILURE, never a guess. */
     path: string, 
+    /**
+     * `read` | `write-idempotent` | `write`, verbatim. The SIDE-EFFECT contract, which is
+     * independent of the verb: webpieces POSTs a read. A renderer publishes it rather than
+     * inferring safety from the verb, which for this framework would be wrong.
+     */
+    operation: string, 
     /** `rpc` | `cloudtasks` | `cron` | `external`, verbatim — this package invents no taxonomy. */
-    kind: string, hidden: boolean, options: DocumentedEndpointOptions, auth: DocumentedAuth | undefined, mcpTool: DocumentedMcpTool | undefined, 
+    kind: string, 
+    /**
+     * `{ hidden: true }` — this method is absent from the CUSTOMER document. It stays in the
+     * private one, and in the MCP one when it is a tool. WHICH documents the CONTRACT feeds at
+     * all is a different, class-level decision; see {@link ApiDocModel.apiTypes}.
+     */
+    hidden: boolean, 
+    /** `{ openWorld: true }` — this operation may touch systems outside this service. */
+    openWorld: boolean, options: DocumentedEndpointOptions, auth: DocumentedAuth | undefined, mcpTool: DocumentedMcpTool | undefined, 
     /** `@WpMcpAuthJwt(...)`'s argument text, when present. */
     mcpAuthText: string | undefined, 
     /** `@MaskLog({...})` — field name -> mask mode. */
@@ -179,6 +290,14 @@ export declare class DocumentedEndpoint {
 export declare class ApiDocModel {
     /** The contract class name, e.g. `SaveApi`. */
     readonly contractName: string;
+    /**
+     * WHICH generated documents this contract feeds — `svc-to-svc`, `external-customer`, `mcp`,
+     * verbatim from `@ApiType(...)`, defaulting to `svc-to-svc` alone when it declares nothing.
+     *
+     * A named list rather than a falsy default, because the grant has to be the TOKEN: a default
+     * that reached customers would publish a contract whose author typed nothing about it.
+     */
+    readonly apiTypes: readonly string[];
     /** `@ApiPath(...)`, constant-folded. */
     readonly basePath: string;
     /** The JSDoc on the contract class, links flattened. */
@@ -191,6 +310,14 @@ export declare class ApiDocModel {
     constructor(
     /** The contract class name, e.g. `SaveApi`. */
     contractName: string, 
+    /**
+     * WHICH generated documents this contract feeds — `svc-to-svc`, `external-customer`, `mcp`,
+     * verbatim from `@ApiType(...)`, defaulting to `svc-to-svc` alone when it declares nothing.
+     *
+     * A named list rather than a falsy default, because the grant has to be the TOKEN: a default
+     * that reached customers would publish a contract whose author typed nothing about it.
+     */
+    apiTypes: readonly string[], 
     /** `@ApiPath(...)`, constant-folded. */
     basePath: string, 
     /** The JSDoc on the contract class, links flattened. */

package/src/model/ApiDocModel.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiDocModel = exports.DocumentedEndpoint = exports.DocumentedAuth = exports.DocumentedMcpTool = exports.DocumentedEndpointOptions = exports.DocumentedType = exports.DocumentedField = exports.UnionDiscriminator = exports.UnmappedType = void 0;
+exports.ApiDocModel = exports.DocumentedEndpoint = exports.DocumentedAuth = exports.DocumentedApiKey = exports.DocumentedApiKeyCredential = exports.DocumentedMcpTool = exports.DocumentedEndpointOptions = exports.DocumentedType = exports.DocumentedField = exports.UnionDiscriminator = exports.UnmappedType = void 0;
 /**
  * The model classes. Every one of them is a CLASS with an explicit constructor per `CLAUDE.md` §1 —
  * these are data-only structures, and a renderer (#982) builds nothing, it only reads.
@@ -118,7 +118,7 @@ class DocumentedType {
     }
 }
 exports.DocumentedType = DocumentedType;
-/** `@Endpoint(path, kind, options?)`'s third argument, as far as a document cares. */
+/** `@Endpoint(httpMethod, path, operation, kind, options?)`'s LAST argument, as a document sees it. */
 class DocumentedEndpointOptions {
     formPost;
     calledBy;
@@ -132,38 +132,108 @@ class DocumentedEndpointOptions {
     }
 }
 exports.DocumentedEndpointOptions = DocumentedEndpointOptions;
-/** The `@WpMcpTool(...)` declaration, when the method carries one. */
+/**
+ * The `@WpMcpTool(...)` declaration, when the method carries one — the TWO facts the source cannot
+ * otherwise state, and nothing else.
+ *
+ * `description` is deliberately NOT read off the decorator. The method's JSDoc is the description, for
+ * the agent and for the partner alike, byte-identical: two authored copies of one paragraph is the
+ * two-spellings shim, and its failure mode is concrete — the partner reads the JSDoc in the OpenAPI
+ * document while the agent reads the decorator string in `tools/list`, and they drift the first time
+ * somebody edits one. (The field still exists on the decorator; #984 deletes it across its 29 call
+ * sites. Nothing here reads it, so nothing here depends on a field that is about to disappear.)
+ *
+ * The three side-effect hints are not read either: they are COMPUTED from the endpoint's `operation`
+ * by `mcpHintsForOperation` in `@webpieces/core-util`, which is the one place that mapping lives.
+ * `READ | WRITE_IDEMPOTENT | WRITE` already says whether repeating a call is safe, so a hand-declared
+ * hint would be a second answer to a question the contract has answered.
+ */
 class DocumentedMcpTool {
     name;
-    hints;
-    constructor(name, 
-    /** The tool hints an agent reads — `readOnly`, `destructive`, `idempotent`, `openWorld`. */
-    hints) {
+    constructor(
+    /**
+     * The STABLE protocol name. Deliberately independent of the method name, because renaming a
+     * method must not break a saved agent workflow.
+     */
+    name) {
         this.name = name;
-        this.hints = hints;
     }
 }
 exports.DocumentedMcpTool = DocumentedMcpTool;
+/**
+ * ONE credential of an api-key regime, PARSED — `{ in: 'header', name: 'x-api-key' }` or
+ * `{ in: 'bearer' }`.
+ *
+ * Parsed rather than left as source text because it is the one auth argument a renderer must turn
+ * into a STRUCTURE: an OpenAPI `securityScheme` is `{type: apiKey, in, name}` or
+ * `{type: http, scheme: bearer}`, and those are different documents. A renderer handed the string
+ * `"{ in: 'header', name: 'x-api-key' }"` would have to parse TypeScript to emit either one, which
+ * is this package's job and not a renderer's.
+ */
+class DocumentedApiKeyCredential {
+    location;
+    name;
+    description;
+    constructor(
+    /** `header` or `bearer`, verbatim from the declaration. */
+    location, 
+    /** The header name. Undefined for `bearer`, whose location IS `Authorization`. */
+    name, 
+    /** The prose a docs site renders on its authorization card. */
+    description) {
+        this.location = location;
+        this.name = name;
+        this.description = description;
+    }
+}
+exports.DocumentedApiKeyCredential = DocumentedApiKeyCredential;
+/** `@WpAuthApiKey(regime, credentials)`, parsed. See {@link DocumentedApiKeyCredential}. */
+class DocumentedApiKey {
+    regime;
+    credentials;
+    constructor(regime, 
+    /**
+     * Every credential the regime requires, IN DECLARATION ORDER. They are an AND — all of them
+     * are presented together — and the order is the order a published document lists them in.
+     */
+    credentials) {
+        this.regime = regime;
+        this.credentials = credentials;
+    }
+}
+exports.DocumentedApiKey = DocumentedApiKey;
 /** WHICH credential an endpoint demands — `@WpAuthPublic`, `@WpAuthJwt`, … — verbatim from the source. */
 class DocumentedAuth {
     decorator;
-    argumentText;
+    argumentTexts;
+    apiKey;
     constructor(
     /** The decorator name as written, e.g. `WpAuthJwt`. */
     decorator, 
-    /** Its argument text, verbatim, when it took one. Undefined for `@WpAuthPublic()`. */
-    argumentText) {
+    /** Every argument's text, verbatim and in order. Empty for `@WpAuthPublic()`. */
+    argumentTexts, 
+    /**
+     * The PARSED api-key declaration, set only for `@WpAuthApiKey`. Every other decorator's
+     * argument is prose or a role list that a document quotes rather than restructures, so
+     * {@link argumentTexts} is all they need — see {@link DocumentedApiKeyCredential} for why
+     * this one is different.
+     */
+    apiKey) {
         this.decorator = decorator;
-        this.argumentText = argumentText;
+        this.argumentTexts = argumentTexts;
+        this.apiKey = apiKey;
     }
 }
 exports.DocumentedAuth = DocumentedAuth;
 /** One `@Endpoint` method of one contract. */
 class DocumentedEndpoint {
     methodName;
+    httpMethod;
     path;
+    operation;
     kind;
     hidden;
+    openWorld;
     options;
     auth;
     mcpTool;
@@ -174,10 +244,29 @@ class DocumentedEndpoint {
     request;
     response;
     constructor(methodName, 
+    /**
+     * `GET` or `POST`, constant-folded from `@Endpoint`'s FIRST argument. A document cannot be
+     * written without it — the verb is the key an operation hangs under in `paths`.
+     */
+    httpMethod, 
     /** The path, constant-folded. A const that cannot be folded is a HARD FAILURE, never a guess. */
     path, 
+    /**
+     * `read` | `write-idempotent` | `write`, verbatim. The SIDE-EFFECT contract, which is
+     * independent of the verb: webpieces POSTs a read. A renderer publishes it rather than
+     * inferring safety from the verb, which for this framework would be wrong.
+     */
+    operation, 
     /** `rpc` | `cloudtasks` | `cron` | `external`, verbatim — this package invents no taxonomy. */
-    kind, hidden, options, auth, mcpTool, 
+    kind, 
+    /**
+     * `{ hidden: true }` — this method is absent from the CUSTOMER document. It stays in the
+     * private one, and in the MCP one when it is a tool. WHICH documents the CONTRACT feeds at
+     * all is a different, class-level decision; see {@link ApiDocModel.apiTypes}.
+     */
+    hidden, 
+    /** `{ openWorld: true }` — this operation may touch systems outside this service. */
+    openWorld, options, auth, mcpTool, 
     /** `@WpMcpAuthJwt(...)`'s argument text, when present. */
     mcpAuthText, 
     /** `@MaskLog({...})` — field name -> mask mode. */
@@ -185,9 +274,12 @@ class DocumentedEndpoint {
     /** The `@mcp` override. See {@link DocumentedField.mcpDescription}. */
     mcpDescription, request, response) {
         this.methodName = methodName;
+        this.httpMethod = httpMethod;
         this.path = path;
+        this.operation = operation;
         this.kind = kind;
         this.hidden = hidden;
+        this.openWorld = openWorld;
         this.options = options;
         this.auth = auth;
         this.mcpTool = mcpTool;
@@ -203,6 +295,7 @@ exports.DocumentedEndpoint = DocumentedEndpoint;
 /** ONE extraction pass over ONE contract file. Both #982's renderers read exactly this. */
 class ApiDocModel {
     contractName;
+    apiTypes;
     basePath;
     description;
     endpoints;
@@ -211,6 +304,14 @@ class ApiDocModel {
     constructor(
     /** The contract class name, e.g. `SaveApi`. */
     contractName, 
+    /**
+     * WHICH generated documents this contract feeds — `svc-to-svc`, `external-customer`, `mcp`,
+     * verbatim from `@ApiType(...)`, defaulting to `svc-to-svc` alone when it declares nothing.
+     *
+     * A named list rather than a falsy default, because the grant has to be the TOKEN: a default
+     * that reached customers would publish a contract whose author typed nothing about it.
+     */
+    apiTypes, 
     /** `@ApiPath(...)`, constant-folded. */
     basePath, 
     /** The JSDoc on the contract class, links flattened. */
@@ -220,6 +321,7 @@ class ApiDocModel {
     /** Everything that could not be represented — recorded, not dropped. */
     unmapped) {
         this.contractName = contractName;
+        this.apiTypes = apiTypes;
         this.basePath = basePath;
         this.description = description;
         this.endpoints = endpoints;

package/src/model/ApiDocModel.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiDocModel.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/model/ApiDocModel.ts"],"names":[],"mappings":"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","sourcesContent":["import { TypeRef } from './TypeRef';\n\n/**\n * The model classes. Every one of them is a CLASS with an explicit constructor per `CLAUDE.md` §1 —\n * these are data-only structures, and a renderer (#982) builds nothing, it only reads.\n *\n * Nothing in this file imports anything but {@link TypeRef}: the package depends on `typescript` and\n * NOTHING else, so it can be pointed at any upstream project's contract. One app-specific import\n * here would end that, which is why `responsibilities.md` states the constraint rather than leaving\n * it to be discovered.\n */\n\n/** A type the extractor could not represent. RECORDED, never dropped — #982's guard needs a name. */\nexport class UnmappedType {\n    constructor(\n        /** The verbatim TypeScript type text, e.g. `Map<string, Widget>`. */\n        readonly typeText: string,\n        /** Pointer-style location: `path/to/File.ts:12:5`. */\n        readonly location: string,\n        /** Why it could not be mapped, in one sentence a renderer can print. */\n        readonly reason: string,\n    ) {}\n}\n\n/** The DERIVED discriminator of a union — never invented, only observed. See {@link DocumentedType}. */\nexport class UnionDiscriminator {\n    constructor(\n        /** The property every branch carries. */\n        readonly propertyName: string,\n        /** branch type name -> the single string literal that branch's property holds. */\n        readonly branchValues: ReadonlyMap<string, string>,\n    ) {}\n}\n\n/** One field of one DTO. */\nexport class DocumentedField {\n    constructor(\n        readonly name: string,\n        readonly type: TypeRef,\n        /**\n         * OPTIONAL (`name?: string`) — the property may be ABSENT. Distinguished from\n         * {@link nullable} on purpose: `{}` and `{name: null}` are different wire documents, and a\n         * renderer that conflates them emits a schema that rejects one of them.\n         */\n        readonly optional: boolean,\n        /** NULLABLE (`name: string | null`) — the property is present and may hold `null`. */\n        readonly nullable: boolean,\n        /** The JSDoc body, links flattened. Empty string when undocumented. */\n        readonly description: string,\n        /**\n         * The `@mcp` block tag — an OPTIONAL agent-facing override. Undefined means \"no override\",\n         * and a renderer falls back to {@link description}; the fallback is NOT applied here so a\n         * renderer can tell a deliberate agent-facing sentence from a reused human one.\n         */\n        readonly mcpDescription: string | undefined,\n        /** The `@format` tag, lifted onto the SCALAR (on an array, onto the ITEM). */\n        readonly format: string | undefined,\n        /** `@WpMin(n)` — numeric fields only; anything else is a build failure. */\n        readonly min: number | undefined,\n        /** `@WpMax(n)` — numeric fields only; anything else is a build failure. */\n        readonly max: number | undefined,\n    ) {}\n}\n\n/** One named type reachable from a contract: an object DTO, a string-literal enum, or a union. */\nexport class DocumentedType {\n    constructor(\n        readonly name: string,\n        readonly description: string,\n        /** Object shape. Empty for an enum or a union. */\n        readonly fields: readonly DocumentedField[],\n        /** Set for a string-literal union that has a name. */\n        readonly enumValues: readonly string[],\n        /** Set for a union of named object types. */\n        readonly unionRefNames: readonly string[],\n        /** Set only when EVERY branch carries the same property typed as one string literal. */\n        readonly discriminator: UnionDiscriminator | undefined,\n        /** An index signature (`[k: string]: X`) — the OPEN-MAP half of an object that also has fields. */\n        readonly indexSignatureValue: TypeRef | undefined,\n    ) {}\n}\n\n/** `@Endpoint(path, kind, options?)`'s third argument, as far as a document cares. */\nexport class DocumentedEndpointOptions {\n    constructor(\n        readonly formPost: boolean,\n        /** `calledBy` — REQUIRED by the decorator for `external`, absent otherwise. */\n        readonly calledBy: string | undefined,\n        readonly callerKind: string | undefined,\n    ) {}\n}\n\n/** The `@WpMcpTool(...)` declaration, when the method carries one. */\nexport class DocumentedMcpTool {\n    constructor(\n        readonly name: string,\n        /** The tool hints an agent reads — `readOnly`, `destructive`, `idempotent`, `openWorld`. */\n        readonly hints: ReadonlyMap<string, boolean>,\n    ) {}\n}\n\n/** WHICH credential an endpoint demands — `@WpAuthPublic`, `@WpAuthJwt`, … — verbatim from the source. */\nexport class DocumentedAuth {\n    constructor(\n        /** The decorator name as written, e.g. `WpAuthJwt`. */\n        readonly decorator: string,\n        /** Its argument text, verbatim, when it took one. Undefined for `@WpAuthPublic()`. */\n        readonly argumentText: string | undefined,\n    ) {}\n}\n\n/** One `@Endpoint` method of one contract. */\nexport class DocumentedEndpoint {\n    constructor(\n        readonly methodName: string,\n        /** The path, constant-folded. A const that cannot be folded is a HARD FAILURE, never a guess. */\n        readonly path: string,\n        /** `rpc` | `cloudtasks` | `cron` | `external`, verbatim — this package invents no taxonomy. */\n        readonly kind: string,\n        readonly hidden: boolean,\n        readonly options: DocumentedEndpointOptions,\n        readonly auth: DocumentedAuth | undefined,\n        readonly mcpTool: DocumentedMcpTool | undefined,\n        /** `@WpMcpAuthJwt(...)`'s argument text, when present. */\n        readonly mcpAuthText: string | undefined,\n        /** `@MaskLog({...})` — field name -> mask mode. */\n        readonly maskLog: ReadonlyMap<string, string>,\n        readonly description: string,\n        /** The `@mcp` override. See {@link DocumentedField.mcpDescription}. */\n        readonly mcpDescription: string | undefined,\n        readonly request: TypeRef | undefined,\n        readonly response: TypeRef | undefined,\n    ) {}\n}\n\n/** ONE extraction pass over ONE contract file. Both #982's renderers read exactly this. */\nexport class ApiDocModel {\n    constructor(\n        /** The contract class name, e.g. `SaveApi`. */\n        readonly contractName: string,\n        /** `@ApiPath(...)`, constant-folded. */\n        readonly basePath: string,\n        /** The JSDoc on the contract class, links flattened. */\n        readonly description: string,\n        readonly endpoints: readonly DocumentedEndpoint[],\n        /** Every named type reachable from the endpoints, by name. A `$ref` target for a renderer. */\n        readonly types: ReadonlyMap<string, DocumentedType>,\n        /** Everything that could not be represented — recorded, not dropped. */\n        readonly unmapped: readonly UnmappedType[],\n    ) {}\n}\n"]}
+{"version":3,"file":"ApiDocModel.js","sourceRoot":"","sources":["../../../../../../packages/docs/api-doc-model/src/model/ApiDocModel.ts"],"names":[],"mappings":"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","sourcesContent":["import { TypeRef } from './TypeRef';\n\n/**\n * The model classes. Every one of them is a CLASS with an explicit constructor per `CLAUDE.md` §1 —\n * these are data-only structures, and a renderer (#982) builds nothing, it only reads.\n *\n * Nothing in this file imports anything but {@link TypeRef}: the package depends on `typescript` and\n * NOTHING else, so it can be pointed at any upstream project's contract. One app-specific import\n * here would end that, which is why `responsibilities.md` states the constraint rather than leaving\n * it to be discovered.\n */\n\n/** A type the extractor could not represent. RECORDED, never dropped — #982's guard needs a name. */\nexport class UnmappedType {\n    constructor(\n        /** The verbatim TypeScript type text, e.g. `Map<string, Widget>`. */\n        readonly typeText: string,\n        /** Pointer-style location: `path/to/File.ts:12:5`. */\n        readonly location: string,\n        /** Why it could not be mapped, in one sentence a renderer can print. */\n        readonly reason: string,\n    ) {}\n}\n\n/** The DERIVED discriminator of a union — never invented, only observed. See {@link DocumentedType}. */\nexport class UnionDiscriminator {\n    constructor(\n        /** The property every branch carries. */\n        readonly propertyName: string,\n        /** branch type name -> the single string literal that branch's property holds. */\n        readonly branchValues: ReadonlyMap<string, string>,\n    ) {}\n}\n\n/** One field of one DTO. */\nexport class DocumentedField {\n    constructor(\n        readonly name: string,\n        readonly type: TypeRef,\n        /**\n         * OPTIONAL (`name?: string`) — the property may be ABSENT. Distinguished from\n         * {@link nullable} on purpose: `{}` and `{name: null}` are different wire documents, and a\n         * renderer that conflates them emits a schema that rejects one of them.\n         */\n        readonly optional: boolean,\n        /** NULLABLE (`name: string | null`) — the property is present and may hold `null`. */\n        readonly nullable: boolean,\n        /** The JSDoc body, links flattened. Empty string when undocumented. */\n        readonly description: string,\n        /**\n         * The `@mcp` block tag — an OPTIONAL agent-facing override. Undefined means \"no override\",\n         * and a renderer falls back to {@link description}; the fallback is NOT applied here so a\n         * renderer can tell a deliberate agent-facing sentence from a reused human one.\n         */\n        readonly mcpDescription: string | undefined,\n        /** The `@format` tag, lifted onto the SCALAR (on an array, onto the ITEM). */\n        readonly format: string | undefined,\n        /** `@WpMin(n)` — numeric fields only; anything else is a build failure. */\n        readonly min: number | undefined,\n        /** `@WpMax(n)` — numeric fields only; anything else is a build failure. */\n        readonly max: number | undefined,\n    ) {}\n}\n\n/** One named type reachable from a contract: an object DTO, a string-literal enum, or a union. */\nexport class DocumentedType {\n    constructor(\n        readonly name: string,\n        readonly description: string,\n        /** Object shape. Empty for an enum or a union. */\n        readonly fields: readonly DocumentedField[],\n        /** Set for a string-literal union that has a name. */\n        readonly enumValues: readonly string[],\n        /** Set for a union of named object types. */\n        readonly unionRefNames: readonly string[],\n        /** Set only when EVERY branch carries the same property typed as one string literal. */\n        readonly discriminator: UnionDiscriminator | undefined,\n        /** An index signature (`[k: string]: X`) — the OPEN-MAP half of an object that also has fields. */\n        readonly indexSignatureValue: TypeRef | undefined,\n    ) {}\n}\n\n/** `@Endpoint(httpMethod, path, operation, kind, options?)`'s LAST argument, as a document sees it. */\nexport class DocumentedEndpointOptions {\n    constructor(\n        readonly formPost: boolean,\n        /** `calledBy` — REQUIRED by the decorator for `external`, absent otherwise. */\n        readonly calledBy: string | undefined,\n        readonly callerKind: string | undefined,\n    ) {}\n}\n\n/**\n * The `@WpMcpTool(...)` declaration, when the method carries one — the TWO facts the source cannot\n * otherwise state, and nothing else.\n *\n * `description` is deliberately NOT read off the decorator. The method's JSDoc is the description, for\n * the agent and for the partner alike, byte-identical: two authored copies of one paragraph is the\n * two-spellings shim, and its failure mode is concrete — the partner reads the JSDoc in the OpenAPI\n * document while the agent reads the decorator string in `tools/list`, and they drift the first time\n * somebody edits one. (The field still exists on the decorator; #984 deletes it across its 29 call\n * sites. Nothing here reads it, so nothing here depends on a field that is about to disappear.)\n *\n * The three side-effect hints are not read either: they are COMPUTED from the endpoint's `operation`\n * by `mcpHintsForOperation` in `@webpieces/core-util`, which is the one place that mapping lives.\n * `READ | WRITE_IDEMPOTENT | WRITE` already says whether repeating a call is safe, so a hand-declared\n * hint would be a second answer to a question the contract has answered.\n */\nexport class DocumentedMcpTool {\n    constructor(\n        /**\n         * The STABLE protocol name. Deliberately independent of the method name, because renaming a\n         * method must not break a saved agent workflow.\n         */\n        readonly name: string,\n    ) {}\n}\n\n/**\n * ONE credential of an api-key regime, PARSED — `{ in: 'header', name: 'x-api-key' }` or\n * `{ in: 'bearer' }`.\n *\n * Parsed rather than left as source text because it is the one auth argument a renderer must turn\n * into a STRUCTURE: an OpenAPI `securityScheme` is `{type: apiKey, in, name}` or\n * `{type: http, scheme: bearer}`, and those are different documents. A renderer handed the string\n * `\"{ in: 'header', name: 'x-api-key' }\"` would have to parse TypeScript to emit either one, which\n * is this package's job and not a renderer's.\n */\nexport class DocumentedApiKeyCredential {\n    constructor(\n        /** `header` or `bearer`, verbatim from the declaration. */\n        readonly location: string,\n        /** The header name. Undefined for `bearer`, whose location IS `Authorization`. */\n        readonly name: string | undefined,\n        /** The prose a docs site renders on its authorization card. */\n        readonly description: string | undefined,\n    ) {}\n}\n\n/** `@WpAuthApiKey(regime, credentials)`, parsed. See {@link DocumentedApiKeyCredential}. */\nexport class DocumentedApiKey {\n    constructor(\n        readonly regime: string,\n        /**\n         * Every credential the regime requires, IN DECLARATION ORDER. They are an AND — all of them\n         * are presented together — and the order is the order a published document lists them in.\n         */\n        readonly credentials: readonly DocumentedApiKeyCredential[],\n    ) {}\n}\n\n/** WHICH credential an endpoint demands — `@WpAuthPublic`, `@WpAuthJwt`, … — verbatim from the source. */\nexport class DocumentedAuth {\n    constructor(\n        /** The decorator name as written, e.g. `WpAuthJwt`. */\n        readonly decorator: string,\n        /** Every argument's text, verbatim and in order. Empty for `@WpAuthPublic()`. */\n        readonly argumentTexts: readonly string[],\n        /**\n         * The PARSED api-key declaration, set only for `@WpAuthApiKey`. Every other decorator's\n         * argument is prose or a role list that a document quotes rather than restructures, so\n         * {@link argumentTexts} is all they need — see {@link DocumentedApiKeyCredential} for why\n         * this one is different.\n         */\n        readonly apiKey: DocumentedApiKey | undefined,\n    ) {}\n}\n\n/** One `@Endpoint` method of one contract. */\nexport class DocumentedEndpoint {\n    constructor(\n        readonly methodName: string,\n        /**\n         * `GET` or `POST`, constant-folded from `@Endpoint`'s FIRST argument. A document cannot be\n         * written without it — the verb is the key an operation hangs under in `paths`.\n         */\n        readonly httpMethod: string,\n        /** The path, constant-folded. A const that cannot be folded is a HARD FAILURE, never a guess. */\n        readonly path: string,\n        /**\n         * `read` | `write-idempotent` | `write`, verbatim. The SIDE-EFFECT contract, which is\n         * independent of the verb: webpieces POSTs a read. A renderer publishes it rather than\n         * inferring safety from the verb, which for this framework would be wrong.\n         */\n        readonly operation: string,\n        /** `rpc` | `cloudtasks` | `cron` | `external`, verbatim — this package invents no taxonomy. */\n        readonly kind: string,\n        /**\n         * `{ hidden: true }` — this method is absent from the CUSTOMER document. It stays in the\n         * private one, and in the MCP one when it is a tool. WHICH documents the CONTRACT feeds at\n         * all is a different, class-level decision; see {@link ApiDocModel.apiTypes}.\n         */\n        readonly hidden: boolean,\n        /** `{ openWorld: true }` — this operation may touch systems outside this service. */\n        readonly openWorld: boolean,\n        readonly options: DocumentedEndpointOptions,\n        readonly auth: DocumentedAuth | undefined,\n        readonly mcpTool: DocumentedMcpTool | undefined,\n        /** `@WpMcpAuthJwt(...)`'s argument text, when present. */\n        readonly mcpAuthText: string | undefined,\n        /** `@MaskLog({...})` — field name -> mask mode. */\n        readonly maskLog: ReadonlyMap<string, string>,\n        readonly description: string,\n        /** The `@mcp` override. See {@link DocumentedField.mcpDescription}. */\n        readonly mcpDescription: string | undefined,\n        readonly request: TypeRef | undefined,\n        readonly response: TypeRef | undefined,\n    ) {}\n}\n\n/** ONE extraction pass over ONE contract file. Both #982's renderers read exactly this. */\nexport class ApiDocModel {\n    constructor(\n        /** The contract class name, e.g. `SaveApi`. */\n        readonly contractName: string,\n        /**\n         * WHICH generated documents this contract feeds — `svc-to-svc`, `external-customer`, `mcp`,\n         * verbatim from `@ApiType(...)`, defaulting to `svc-to-svc` alone when it declares nothing.\n         *\n         * A named list rather than a falsy default, because the grant has to be the TOKEN: a default\n         * that reached customers would publish a contract whose author typed nothing about it.\n         */\n        readonly apiTypes: readonly string[],\n        /** `@ApiPath(...)`, constant-folded. */\n        readonly basePath: string,\n        /** The JSDoc on the contract class, links flattened. */\n        readonly description: string,\n        readonly endpoints: readonly DocumentedEndpoint[],\n        /** Every named type reachable from the endpoints, by name. A `$ref` target for a renderer. */\n        readonly types: ReadonlyMap<string, DocumentedType>,\n        /** Everything that could not be represented — recorded, not dropped. */\n        readonly unmapped: readonly UnmappedType[],\n    ) {}\n}\n"]}