@wildo-ai/saas-models 1.1.2 → 1.1.4

package/dist/esm/requests/manual-controllers-routes-documentation.d.ts

@@ -0,0 +1,137 @@
+/**
+ * What each manually mounted controller route IS, for consumer documentation.
+ *
+ * ## Why this file exists
+ *
+ * A Wildo application serves two disjoint families of HTTP routes. The RESOURCE REGISTRY builds one
+ * family from the resource configurations, and every mechanism downstream — the OpenAPI generator,
+ * the API-reference renderer, the link index — projects that family and only that family. The other
+ * family is mounted by hand, controller by controller, from
+ * {@link MANUAL_CONTROLLER_ROUTES_URLS}: sign-in, token refresh, MFA, passkeys, SAML, the OAuth 2.0
+ * authorization-server endpoints, the MCP and A2A doors, file transfer, i18n labels, charts.
+ *
+ * Nothing projected the second family, so it appeared in NO generated API reference. Measured
+ * 2026-09-09 on the four committed documents of the two dogfood applications — 439, 576, 146 and 160
+ * paths — every one of which contained **zero** paths under `/auth`. The reference told an integrator
+ * that operations accept a bearer token and never told them which endpoint issues one; worse, four
+ * operation-header descriptions in the same document say a step-up token is "obtained from
+ * `POST /api/v1/auth/reauth`", a path that document does not publish.
+ *
+ * ## Why the facts live HERE and not at the mount site
+ *
+ * The route's VERB and its one-line purpose are already written at each `logRouteRegistration(...)`
+ * call — 203 of them — inside `@wildo-ai/saas-backend-lib`. That package is the backend runtime, and
+ * the documentation projector runs inside the companion's introspection subprocess, which loads the
+ * application's SHARED library and never the backend. So the mount site cannot be the source: it is
+ * not reachable from where the answer is needed.
+ *
+ * This catalog is therefore the shared, statically-loadable source, and it is **total over
+ * {@link ManualControllerRouteKey}** by construction. A route key added tomorrow does not compile
+ * until somebody says what it is and whether it may be published — which is the whole point: an
+ * undocumented route should be a build failure, not a silent hole in a customer-facing reference.
+ *
+ * ## What is deliberately NOT here
+ *
+ * No request or response JSON Schema. The request bodies are Zod schemas declared inside the backend
+ * controllers, unreachable from this package; hand-copying them here would create a second copy of a
+ * contract with nothing checking the two agree — the exact drift this repository refuses elsewhere.
+ * Each entry therefore names its payload in PROSE and authors its success status, which is honest
+ * about what is known. Wiring the real schemas is a later, larger change that has to move them into a
+ * shared module first.
+ */
+import { HttpMethod } from './http-requests.shared';
+import { ManualControllerRouteKey } from './manual-controllers-routes-urls';
+/**
+ * The API-reference grouping a manual route belongs to — the OpenAPI `tag` it is published under.
+ *
+ * Deliberately NOT one group per controller. A reader groups by what they are trying to DO, and the
+ * controller split is an implementation fact: sign-in lives in one controller and password change in
+ * another, and both are "authentication" to the person reading.
+ *
+ * The values must not collide with any resource identifier, because the generator turns a tag name
+ * into `technical-documentation:resource/<name>` and two tags claiming one ref would make the
+ * renderer's conservation check refuse the document. Resource identifiers are the resource TYPES
+ * (`users`, `organizations`, `oauthConsentGrants`, …); none of these names is one.
+ */
+export declare enum ManualControllerRouteGroup {
+    /** Signing in, staying signed in, signing out, and everything that proves who the caller is. */
+    AUTHENTICATION = "authentication",
+    /** This application acting as an OAuth 2.0 / OpenID Connect authorization server for other software. */
+    IDENTITY_PROVIDER = "identityProvider",
+    /** Connecting a third-party account so this application can act as it. The opposite arrow from sign-in. */
+    CONNECTED_ACCOUNTS = "connectedAccounts",
+    /** The doors an autonomous agent knocks on: Model Context Protocol and Agent2Agent. */
+    AGENT_INTERFACES = "agentInterfaces",
+    /** Transferring a stored file by its own id, wherever it is attached. */
+    FILE_TRANSFER = "fileTransfer",
+    /** Reads a client makes to work out what this application currently offers it. */
+    APPLICATION_RUNTIME = "applicationRuntime"
+}
+/**
+ * What a caller must present. Mirrors the documentation vocabulary the resource projector already
+ * resolves from role bindings, so both families of routes describe access the same way.
+ */
+export declare enum ManualControllerRouteAuthentication {
+    /** No credential. The request itself carries whatever authorization it needs (a single-use token, say). */
+    PUBLIC = "public",
+    /** An anonymous-session token in the anonymous-session header. */
+    ANONYMOUS_SESSION = "anonymous_session",
+    /** A bearer access token, or an API key where the surface accepts one. */
+    AUTHENTICATED = "authenticated",
+    /** Either an anonymous session or a full credential; the endpoint serves both. */
+    ANONYMOUS_OR_AUTHENTICATED = "anonymous_or_authenticated"
+}
+/** Whether a route reaches the generated consumer API reference. */
+export declare enum ManualControllerRoutePublication {
+    PUBLISHED = "published",
+    WITHHELD = "withheld"
+}
+/** A route that is published: everything the projector needs to emit an OpenAPI operation. */
+export interface PublishedManualControllerRouteDocumentation {
+    readonly publication: ManualControllerRoutePublication.PUBLISHED;
+    readonly group: ManualControllerRouteGroup;
+    /**
+     * The methods actually mounted for this path, measured from the controllers rather than assumed.
+     * One key can carry several (`/oauth/register/{clientId}` is GET, PUT and DELETE; RFC 7592 defines
+     * ONE endpoint whose method selects the operation), and each becomes its own OpenAPI operation.
+     */
+    readonly methods: readonly HttpMethod[];
+    /** Short action label. Becomes the OpenAPI `summary`; the generator caps it at 200 characters. */
+    readonly summary: string;
+    /** What the endpoint does, what it expects, and what a caller does with the answer. Capped at 2000. */
+    readonly description: string;
+    readonly authentication: ManualControllerRouteAuthentication;
+    /** One sentence naming the credential. Capped at 500. */
+    readonly authenticationSummary: string;
+    /**
+     * The success status and what it means. Authored because no response schema is projected: without
+     * it the generator would emit a bare `204 No Content`, which is wrong for almost every route here.
+     */
+    readonly successStatus: {
+        readonly code: string;
+        readonly meaning: string;
+    };
+}
+/**
+ * A route that is NOT published, and why.
+ *
+ * The reason is a required field rather than a comment on purpose. Withholding a route from a
+ * customer-facing reference is a decision, and a decision with no recorded reason is indistinguishable
+ * from an oversight — which is how this whole family came to be missing in the first place.
+ */
+export interface WithheldManualControllerRouteDocumentation {
+    readonly publication: ManualControllerRoutePublication.WITHHELD;
+    readonly withheldReason: string;
+}
+export type ManualControllerRouteDocumentation = PublishedManualControllerRouteDocumentation | WithheldManualControllerRouteDocumentation;
+/** Prose group descriptions, emitted as each published group's OpenAPI `tags[].description`. */
+export declare const MANUAL_CONTROLLER_ROUTE_GROUP_DESCRIPTIONS: Record<ManualControllerRouteGroup, string>;
+/**
+ * Every manually mounted route, keyed by the route it is mounted at.
+ *
+ * TOTAL over {@link ManualControllerRouteKey}: the `Record` type makes a new route key a compile
+ * error until it is described here. That is the mechanism that keeps this catalog honest — a
+ * hand-kept list of "the ones we remembered" is precisely what rots.
+ */
+export declare const MANUAL_CONTROLLER_ROUTE_DOCUMENTATION: Record<ManualControllerRouteKey, ManualControllerRouteDocumentation>;
+//# sourceMappingURL=manual-controllers-routes-documentation.d.ts.map

package/dist/esm/requests/manual-controllers-routes-documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-controllers-routes-documentation.d.ts","sourceRoot":"","sources":["../../../src/requests/manual-controllers-routes-documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,oBAAY,0BAA0B;IACpC,gGAAgG;IAChG,cAAc,mBAAmB;IACjC,wGAAwG;IACxG,iBAAiB,qBAAqB;IACtC,2GAA2G;IAC3G,kBAAkB,sBAAsB;IACxC,uFAAuF;IACvF,gBAAgB,oBAAoB;IACpC,yEAAyE;IACzE,aAAa,iBAAiB;IAC9B,kFAAkF;IAClF,mBAAmB,uBAAuB;CAC3C;AAED;;;GAGG;AACH,oBAAY,mCAAmC;IAC7C,2GAA2G;IAC3G,MAAM,WAAW;IACjB,kEAAkE;IAClE,iBAAiB,sBAAsB;IACvC,0EAA0E;IAC1E,aAAa,kBAAkB;IAC/B,kFAAkF;IAClF,0BAA0B,+BAA+B;CAC1D;AAED,oEAAoE;AACpE,oBAAY,gCAAgC;IAC1C,SAAS,cAAc;IACvB,QAAQ,aAAa;CACtB;AAED,8FAA8F;AAC9F,MAAM,WAAW,2CAA2C;IAC1D,QAAQ,CAAC,WAAW,EAAE,gCAAgC,CAAC,SAAS,CAAC;IACjE,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,mCAAmC,CAAC;IAC7D,yDAAyD;IACzD,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,WAAW,EAAE,gCAAgC,CAAC,QAAQ,CAAC;IAChE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,kCAAkC,GAC1C,2CAA2C,GAC3C,0CAA0C,CAAC;AAoB/C,gGAAgG;AAChG,eAAO,MAAM,0CAA0C,EAAE,MAAM,CAAC,0BAA0B,EAAE,MAAM,CAuBjG,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC,EAAE,MAAM,CAAC,wBAAwB,EAAE,kCAAkC,CAssCtH,CAAC"}