@orthacms/content-server 0.4.2 → 0.5.0

package/dist/lib/docs/describe-views-api.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The saved-views plugin's pass over the host's OpenAPI document.
+ *
+ * A second `decorate` from the same package as {@link describeContentApi},
+ * because saved views ship as a second `ServerPlugin` entry
+ * (`ContentViewsPlugin`) and a plugin describes what it registers. Keeping them
+ * apart also keeps the route tables honest: nothing here can accidentally claim
+ * a `/content/...` path, and nothing there can claim a `/views` one.
+ *
+ * Pure: takes the document and the serialized types, mutates only `/views`.
+ */
+import type { OpenApiDocument } from '@orthacms/bootstrap-server';
+import type { SerializedContentType } from '../registry/content-type-registry';
+/**
+ * Adds the saved-view schemas to `document` and points the `/views` operations
+ * at them.
+ */
+export declare function describeViewsApi(document: OpenApiDocument, types: readonly SerializedContentType[]): void;
+//# sourceMappingURL=describe-views-api.d.ts.map

package/dist/lib/docs/describe-views-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-views-api.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/describe-views-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAmC/E;;;GAGG;AACH,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,SAAS,qBAAqB,EAAE,GACxC,IAAI,CAqCN"}

package/dist/lib/docs/describe-views-api.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * The saved-views plugin's pass over the host's OpenAPI document.
+ *
+ * A second `decorate` from the same package as {@link describeContentApi},
+ * because saved views ship as a second `ServerPlugin` entry
+ * (`ContentViewsPlugin`) and a plugin describes what it registers. Keeping them
+ * apart also keeps the route tables honest: nothing here can accidentally claim
+ * a `/content/...` path, and nothing there can claim a `/views` one.
+ *
+ * Pure: takes the document and the serialized types, mutates only `/views`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeViewsApi = describeViewsApi;
+const content_schemas_1 = require("./content-schemas");
+const views_schemas_1 = require("./views-schemas");
+const openapi_writer_1 = require("./openapi-writer");
+/**
+ * Matches `<prefix>/views<rest>` — anchored at both ends.
+ *
+ * The tail is one of the three shapes the controller actually serves. The head
+ * is `^/<one segment>/`, so `/api/insights/views` — another plugin's route,
+ * ending in the same word — is not caught: a suffix match claimed it and gave
+ * it this plugin's schemas, which is the same failure that once published
+ * thirteen public content operations with the admin's shapes.
+ *
+ * It assumes the host's global prefix is a single segment, which the default
+ * (`api`) is. A longer one leaves these three operations with no response
+ * schema rather than the wrong one — the direction to fail in, and the same
+ * one an unmatched route already takes.
+ */
+const VIEWS_ROUTE_RE = /^\/[^/]+\/views((?:\/\{id\})?(?:\/default)?)$/;
+/**
+ * What each `/views` operation answers, keyed by what follows `/views`.
+ *
+ * The three `204`s (`DELETE /views/{id}`, `PUT|DELETE /views/{id}/default`) are
+ * listed as `null` rather than omitted: they are described — they simply have
+ * no body, and saying so here is what keeps a later reader from "fixing" the
+ * gap by inventing one.
+ */
+const VIEW_ROUTES = {
+    '': { get: 'list', post: 'one' },
+    '/{id}': { patch: 'one', delete: null },
+    '/{id}/default': { put: null, delete: null }
+};
+/**
+ * Adds the saved-view schemas to `document` and points the `/views` operations
+ * at them.
+ */
+function describeViewsApi(document, types) {
+    document.components ??= {};
+    document.components.schemas ??= {};
+    Object.assign(document.components.schemas, (0, views_schemas_1.buildViewsSchemas)(types));
+    for (const [route, item] of Object.entries(document.paths)) {
+        const match = VIEWS_ROUTE_RE.exec(route);
+        if (!match) {
+            continue;
+        }
+        const byMethod = VIEW_ROUTES[match[1]];
+        if (!byMethod) {
+            continue;
+        }
+        for (const [method, operation] of Object.entries(item)) {
+            const kind = byMethod[method];
+            if (kind == null || !operation || typeof operation !== 'object') {
+                continue;
+            }
+            if (kind === 'list') {
+                (0, openapi_writer_1.setSuccessResponse)(operation, { type: 'array', items: (0, content_schemas_1.ref)(views_schemas_1.SAVED_VIEW_SCHEMA) }, 'The caller’s own views for this scope at any visibility, plus every workspace-shared one, ordered for the switcher.');
+            }
+            else {
+                (0, openapi_writer_1.setSuccessResponse)(operation, (0, content_schemas_1.ref)(views_schemas_1.SAVED_VIEW_SCHEMA), 'The saved view.');
+            }
+        }
+    }
+}

package/dist/lib/docs/field-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-schema.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/field-schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAyJpD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAK5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,aAAa,CA0DjE"}
+{"version":3,"file":"field-schema.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/field-schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAyJpD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAK5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,aAAa,CAyDjE"}

package/dist/lib/docs/field-schema.js

@@ -206,9 +206,43 @@ function fieldSchema(field) {
         ? field.admin['label']
         : undefined;
     return {
-        ...valueSchema(field),
-        nullable: true,
+        ...nullable(valueSchema(field)),
         ...(label ? { title: label } : {}),
         ...(notes.length ? { description: notes.join(' ') } : {})
     };
 }
+/**
+ * Marks a value schema nullable — and does the two things `nullable: true`
+ * alone does **not** do.
+ *
+ * OpenAPI 3.0's `nullable` is a modifier on the schema's `type`, so it is inert
+ * wherever there is no single type to modify, and it does not widen an
+ * enumeration. Both cases occur here and both produced a document that rejected
+ * responses the API really returns:
+ *
+ * - a `select` read back as `{ type: 'string', enum: [...], nullable: true }`,
+ *   which every validator refuses `null` against, because OAS 3.0 requires a
+ *   nullable enum to list `null` among its values;
+ * - a `richtext` read back as a bare `oneOf` (document or legacy HTML string)
+ *   with `nullable` attached to nothing at all.
+ *
+ * Measured against a live server: an `article` with an unset `layout` did not
+ * validate against its own `ArticleValues` schema until this existed.
+ */
+function nullable(schema) {
+    if (Array.isArray(schema['oneOf'])) {
+        return {
+            ...schema,
+            oneOf: [...schema['oneOf'], { type: 'null' }],
+            nullable: true
+        };
+    }
+    if (Array.isArray(schema['enum'])) {
+        return {
+            ...schema,
+            enum: [...schema['enum'], null],
+            nullable: true
+        };
+    }
+    return { ...schema, nullable: true };
+}

package/dist/lib/docs/openapi-writer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The two writes every `decorate` pass in this package makes on the generated
+ * document, and the one rule they both follow: **never invent a status code.**
+ *
+ * The scanner has already emitted whichever 2xx key the handler actually
+ * answers with — 201 for a bare `@Post`, 200 elsewhere, and whatever a
+ * `@HttpCode` moved it to — so a schema is written *onto that key* rather than
+ * onto a guessed one. A document that describes a `200` for a route answering
+ * `201` is worse than a document that describes nothing, because a consumer
+ * cannot tell it is wrong without curling the API, which is the whole thing
+ * these passes exist to make unnecessary.
+ */
+import type { OpenApiSchema } from './field-schema';
+/** An operation object, as far as these passes need to see one. */
+export interface Operation {
+    parameters?: {
+        name: string;
+        in: string;
+        schema?: OpenApiSchema;
+        description?: string;
+    }[];
+    responses?: Record<string, {
+        description?: string;
+        content?: unknown;
+    }>;
+}
+/**
+ * Writes a success response's schema onto whichever 2xx key the scanner already
+ * emitted.
+ *
+ * `204` is left alone deliberately: a no-content response has no body, and
+ * attaching one would describe a payload the server never sends.
+ */
+export declare function setSuccessResponse(operation: Operation, schema: OpenApiSchema, description: string, 
+/**
+ * Media type. `application/json` for all but the two transfer downloads,
+ * which stream a file.
+ */
+mediaType?: string, 
+/** Response headers worth documenting, keyed by header name. */
+headers?: Record<string, unknown>): void;
+/**
+ * Writes a success response carrying several media types — one download route
+ * whose content type depends on what the caller asked for.
+ */
+export declare function setSuccessResponseVariants(operation: Operation, byMediaType: Record<string, OpenApiSchema>, description: string, headers?: Record<string, unknown>): void;
+/** Adds a documented failure response, leaving any existing one alone. */
+export declare function addErrorResponse(operation: Operation, code: string, description: string, schema?: OpenApiSchema): void;
+//# sourceMappingURL=openapi-writer.d.ts.map

package/dist/lib/docs/openapi-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-writer.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/openapi-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACtB,UAAU,CAAC,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,CAAC,EAAE,aAAa,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACxB,EAAE,CAAC;IACJ,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAC9B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM;AACnB;;;GAGG;AACH,SAAS,SAAqB;AAC9B,gEAAgE;AAChE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,IAAI,CAYN;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACtC,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAC1C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,IAAI,CAiBN;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAC5B,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,aAAa,GACvB,IAAI,CAUN"}

package/dist/lib/docs/openapi-writer.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * The two writes every `decorate` pass in this package makes on the generated
+ * document, and the one rule they both follow: **never invent a status code.**
+ *
+ * The scanner has already emitted whichever 2xx key the handler actually
+ * answers with — 201 for a bare `@Post`, 200 elsewhere, and whatever a
+ * `@HttpCode` moved it to — so a schema is written *onto that key* rather than
+ * onto a guessed one. A document that describes a `200` for a route answering
+ * `201` is worse than a document that describes nothing, because a consumer
+ * cannot tell it is wrong without curling the API, which is the whole thing
+ * these passes exist to make unnecessary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setSuccessResponse = setSuccessResponse;
+exports.setSuccessResponseVariants = setSuccessResponseVariants;
+exports.addErrorResponse = addErrorResponse;
+/**
+ * Writes a success response's schema onto whichever 2xx key the scanner already
+ * emitted.
+ *
+ * `204` is left alone deliberately: a no-content response has no body, and
+ * attaching one would describe a payload the server never sends.
+ */
+function setSuccessResponse(operation, schema, description, 
+/**
+ * Media type. `application/json` for all but the two transfer downloads,
+ * which stream a file.
+ */
+mediaType = 'application/json', 
+/** Response headers worth documenting, keyed by header name. */
+headers) {
+    const responses = operation.responses ?? {};
+    const key = Object.keys(responses).find((code) => /^2\d\d$/.test(code));
+    if (!key || key === '204') {
+        return;
+    }
+    responses[key] = {
+        description,
+        ...(headers ? { headers } : {}),
+        content: { [mediaType]: { schema } }
+    };
+    operation.responses = responses;
+}
+/**
+ * Writes a success response carrying several media types — one download route
+ * whose content type depends on what the caller asked for.
+ */
+function setSuccessResponseVariants(operation, byMediaType, description, headers) {
+    const responses = operation.responses ?? {};
+    const key = Object.keys(responses).find((code) => /^2\d\d$/.test(code));
+    if (!key || key === '204') {
+        return;
+    }
+    responses[key] = {
+        description,
+        ...(headers ? { headers } : {}),
+        content: Object.fromEntries(Object.entries(byMediaType).map(([type, schema]) => [
+            type,
+            { schema }
+        ]))
+    };
+    operation.responses = responses;
+}
+/** Adds a documented failure response, leaving any existing one alone. */
+function addErrorResponse(operation, code, description, schema) {
+    const responses = operation.responses ?? {};
+    if (responses[code]) {
+        return;
+    }
+    responses[code] = {
+        description,
+        ...(schema ? { content: { 'application/json': { schema } } } : {})
+    };
+    operation.responses = responses;
+}

package/dist/lib/docs/public-api-schemas.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The OpenAPI schemas of the **public** content API (`/api/v1/...`), kept apart
+ * from the admin's for the same reason `types/public-entry.ts` is kept apart
+ * from `EntryRecord`: this is a published contract an external site builds
+ * against, and it must be free to stay still while the admin's shape moves.
+ *
+ * Splitting them is not tidiness. Until this module existed the document
+ * described `/api/v1/content/{typeName}/{id}` with the **admin** entry schema,
+ * because the route pattern in `describe-content-api.ts` matched both spellings
+ * — so a consumer reading the reference was told a relation preview carries
+ * `RelationRef`s (id + title) when the public API returns whole entries, and
+ * that a media read is `Record<string, MediaRef[]>` when it is
+ * `Record<string, { items, total }>`. A wrong schema is worse than an absent
+ * one: the absent one sends you to curl, the wrong one does not.
+ */
+import type { SerializedContentType } from '../registry/content-type-registry';
+import { type OpenApiSchema } from './field-schema';
+/** Schema names of one content type's public trio. */
+export interface PublicTypeSchemaNames {
+    /** The `values` bag — the entry's own data, references omitted. */
+    values: string;
+    /** One entry as the public API serves it. */
+    entry: string;
+    /** One page of them. */
+    listPage: string;
+}
+/** The three schema names a content type contributes to the public document. */
+export declare function publicSchemaNamesOf(type: SerializedContentType): PublicTypeSchemaNames;
+/**
+ * The public per-type entry schemas as alternatives — the response shape
+ * depends on `typeName`, which OpenAPI cannot express as a dependency. One
+ * registered type needs no union; none at all leaves an open object, since
+ * every one of these routes 404s anyway.
+ *
+ * `anyOf` rather than `oneOf`, for the reason `unionOf` in
+ * `describe-content-api.ts` spells out: the alternatives overlap, and *exactly
+ * one* is a promise the API does not keep.
+ */
+export declare function publicUnionOf(names: string[]): OpenApiSchema;
+/**
+ * Every schema the public API contributes: its fixed shapes plus, per
+ * registered content type, the `Values` / `Entry` / `ListPage` trio.
+ */
+export declare function buildPublicApiSchemas(types: readonly SerializedContentType[]): Record<string, OpenApiSchema>;
+//# sourceMappingURL=public-api-schemas.d.ts.map

package/dist/lib/docs/public-api-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api-schemas.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/public-api-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAG/E,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMjE,sDAAsD;AACtD,MAAM,WAAW,qBAAqB;IAClC,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAC/B,IAAI,EAAE,qBAAqB,GAC5B,qBAAqB,CAOvB;AA+JD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,aAAa,CAK5D;AAuMD;;;GAGG;AACH,wBAAgB,qBAAqB,CACjC,KAAK,EAAE,SAAS,qBAAqB,EAAE,GACxC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAY/B"}