@skmtc/core 0.30.1 → 0.31.0

package/script/oas/webhook/Webhook.d.ts

@@ -113,10 +113,10 @@ export declare class OasWebhook extends OasBase {
      */
     toPayload(): OasRequestBody | undefined;
     /**
-     * The schema of the received payload for `mediaType` (default
-     * `application/json`) — the inbound body shape a handler generator emits a
-     * type for. `undefined` when there is no body or no schema for that media
-     * type.
+     * The schema of the received payload for `mediaType`, an exact lookup —
+     * the inbound body shape a handler generator writes a type for. Without
+     * `mediaType`, the media type `OasRequestBody.toJsonContent` picks.
+     * `undefined` when there is no body or no schema for that media type.
      */
     toPayloadSchema(mediaType?: string): OasSchema | OasRef<'schema'> | undefined;
     /**

package/script/oas/webhook/Webhook.js

@@ -160,13 +160,13 @@ class OasWebhook extends OasBase_js_1.OasBase {
         return this.requestBody?.resolve();
     }
     /**
-     * The schema of the received payload for `mediaType` (default
-     * `application/json`) — the inbound body shape a handler generator emits a
-     * type for. `undefined` when there is no body or no schema for that media
-     * type.
+     * The schema of the received payload for `mediaType`, an exact lookup —
+     * the inbound body shape a handler generator writes a type for. Without
+     * `mediaType`, the media type `OasRequestBody.toJsonContent` picks.
+     * `undefined` when there is no body or no schema for that media type.
      */
-    toPayloadSchema(mediaType = 'application/json') {
-        return this.toPayload()?.content[mediaType]?.schema;
+    toPayloadSchema(mediaType) {
+        return this.toPayload()?.toSchema(mediaType);
     }
     /**
      * Resolve the inbound parameters (e.g. the signature/headers a handler

package/script/parse/logBodyMediaTypes.d.ts

@@ -0,0 +1,27 @@
+import type { ParseContextType } from '../context/parseTypes.js';
+import type { StackTrail } from '../context/StackTrail.js';
+import type { OasMediaType } from '../oas/mediaType/MediaType.js';
+export type LogBodyMediaTypesArgs = {
+    /** The parsed `content` map of a response or request body. */
+    content: Record<string, OasMediaType> | undefined;
+    /** Trail of the response or request body; the issue is logged at its `content` key. */
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+/**
+ * Log at most one issue for a parsed response or request body, from the same
+ * choice the lookups make (`toJsonContent`), so the issue and the lookup
+ * cannot disagree. Called after the body is built, so a body that fails to
+ * parse logs nothing.
+ *
+ * - `WILDCARD_MEDIA_TYPE` (`warning`): the body is read from `*\/*` as JSON,
+ *   though the document does not say its format.
+ * - `NO_JSON_MEDIA_TYPE` (`debug`): no lookup reads the body, and its keys
+ *   include a range (`*\/*` with a scalar schema, `application/*`), so its
+ *   format is unknown.
+ *
+ * A body with only specific non-JSON types (`multipart/form-data`,
+ * `application/octet-stream`, `text/plain`) logs nothing: that is a normal
+ * text, form or binary body.
+ */
+export declare const logBodyMediaTypes: ({ content, stackTrail, context }: LogBodyMediaTypesArgs) => void;

package/script/parse/logBodyMediaTypes.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logBodyMediaTypes = void 0;
+const jsonMediaType_js_1 = require("../oas/mediaType/jsonMediaType.js");
+/**
+ * Log at most one issue for a parsed response or request body, from the same
+ * choice the lookups make (`toJsonContent`), so the issue and the lookup
+ * cannot disagree. Called after the body is built, so a body that fails to
+ * parse logs nothing.
+ *
+ * - `WILDCARD_MEDIA_TYPE` (`warning`): the body is read from `*\/*` as JSON,
+ *   though the document does not say its format.
+ * - `NO_JSON_MEDIA_TYPE` (`debug`): no lookup reads the body, and its keys
+ *   include a range (`*\/*` with a scalar schema, `application/*`), so its
+ *   format is unknown.
+ *
+ * A body with only specific non-JSON types (`multipart/form-data`,
+ * `application/octet-stream`, `text/plain`) logs nothing: that is a normal
+ * text, form or binary body.
+ */
+const logBodyMediaTypes = ({ content, stackTrail, context }) => {
+    const mediaTypes = Object.keys(content ?? {});
+    if (mediaTypes.length === 0) {
+        return;
+    }
+    const listed = mediaTypes.map(mediaType => `"${mediaType}"`).join(', ');
+    // `parent` is only the keys: the issue log serializes it on every issue.
+    const parent = { mediaTypes };
+    const chosen = (0, jsonMediaType_js_1.toJsonContent)(content);
+    if (chosen !== undefined) {
+        if ((0, jsonMediaType_js_1.isAnyMediaType)(chosen.mediaType)) {
+            context.logIssue({
+                key: 'content',
+                level: 'warning',
+                type: 'WILDCARD_MEDIA_TYPE',
+                message: `Content has no JSON media type (${listed}), so the body is read from "*/*" as JSON although the document does not say its format`,
+                parent,
+                stackTrail
+            });
+        }
+        return;
+    }
+    if (mediaTypes.some(mediaType => (0, jsonMediaType_js_1.toMediaTypeEssence)(mediaType).includes('*'))) {
+        context.logIssue({
+            key: 'content',
+            level: 'debug',
+            type: 'NO_JSON_MEDIA_TYPE',
+            message: `Content names only a media type range or non-JSON types (${listed}), so no lookup without a media type reads its schema`,
+            parent,
+            stackTrail
+        });
+    }
+};
+exports.logBodyMediaTypes = logBodyMediaTypes;

package/script/parse/v3-0/requestBody/toRequestBodiesV3.js

@@ -6,6 +6,7 @@ const toRefV31_js_1 = require("../ref/toRefV31.js");
 const toMediaTypeItemV3_js_1 = require("../mediaType/toMediaTypeItemV3.js");
 const RequestBody_js_1 = require("../../../oas/requestBody/RequestBody.js");
 const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const logBodyMediaTypes_js_1 = require("../../logBodyMediaTypes.js");
 const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
     if (!requestBody) {
         return undefined;
@@ -29,7 +30,9 @@ const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
         required,
         extensionFields
     };
-    return context.withStackTrail(stackTrail, () => new RequestBody_js_1.OasRequestBody(fields, context));
+    const parsed = context.withStackTrail(stackTrail, () => new RequestBody_js_1.OasRequestBody(fields, context));
+    (0, logBodyMediaTypes_js_1.logBodyMediaTypes)({ content: fields.content, stackTrail, context });
+    return parsed;
 };
 exports.toRequestBodyV3 = toRequestBodyV3;
 const toRequestBodiesV3 = ({ requestBodies, stackTrail, context }) => {

package/script/parse/v3-0/response/toResponseV3.js

@@ -9,6 +9,7 @@ const toMediaTypeItemV3_js_1 = require("../mediaType/toMediaTypeItemV3.js");
 const Response_js_1 = require("../../../oas/response/Response.js");
 const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
 const tryParseAt_js_1 = require("../../../context/tryParseAt.js");
+const logBodyMediaTypes_js_1 = require("../../logBodyMediaTypes.js");
 const toResponsesV3 = ({ responses, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(responses);
@@ -50,12 +51,14 @@ const toResponseV3 = ({ response, stackTrail, context }) => {
     const parsedHeaders = stackTrail.trace('headers', st => (0, toHeadersV3_js_1.toHeadersV3)({ headers, stackTrail: st, context }));
     const parsedLinks = stackTrail.trace('links', st => (0, toLinksV3_js_1.toLinksV3)({ links, stackTrail: st, context }));
     const parsedContent = stackTrail.trace('content', st => (0, toMediaTypeItemV3_js_1.toOptionalMediaTypeItemsV3)({ content, stackTrail: st, context }));
-    return context.withStackTrail(stackTrail, () => new Response_js_1.OasResponse({
+    const parsed = context.withStackTrail(stackTrail, () => new Response_js_1.OasResponse({
         description,
         headers: parsedHeaders,
         links: parsedLinks,
         content: parsedContent,
         extensionFields
     }, context));
+    (0, logBodyMediaTypes_js_1.logBodyMediaTypes)({ content: parsedContent, stackTrail, context });
+    return parsed;
 };
 exports.toResponseV3 = toResponseV3;

package/script/parse/v3-1/requestBody/toRequestBodiesV3.js

@@ -6,6 +6,7 @@ const toRefV31_js_1 = require("../ref/toRefV31.js");
 const toMediaTypeItemV3_js_1 = require("../mediaType/toMediaTypeItemV3.js");
 const RequestBody_js_1 = require("../../../oas/requestBody/RequestBody.js");
 const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const logBodyMediaTypes_js_1 = require("../../logBodyMediaTypes.js");
 const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
     if (!requestBody) {
         return undefined;
@@ -29,7 +30,9 @@ const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
         required,
         extensionFields
     };
-    return context.withStackTrail(stackTrail, () => new RequestBody_js_1.OasRequestBody(fields, context));
+    const parsed = context.withStackTrail(stackTrail, () => new RequestBody_js_1.OasRequestBody(fields, context));
+    (0, logBodyMediaTypes_js_1.logBodyMediaTypes)({ content: fields.content, stackTrail, context });
+    return parsed;
 };
 exports.toRequestBodyV3 = toRequestBodyV3;
 const toRequestBodiesV3 = ({ requestBodies, stackTrail, context }) => {

package/script/parse/v3-1/response/toResponseV3.js

@@ -9,6 +9,7 @@ const toMediaTypeItemV3_js_1 = require("../mediaType/toMediaTypeItemV3.js");
 const Response_js_1 = require("../../../oas/response/Response.js");
 const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
 const tryParseAt_js_1 = require("../../../context/tryParseAt.js");
+const logBodyMediaTypes_js_1 = require("../../logBodyMediaTypes.js");
 const toResponsesV3 = ({ responses, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(responses);
@@ -50,12 +51,14 @@ const toResponseV3 = ({ response, stackTrail, context }) => {
     const parsedHeaders = stackTrail.trace('headers', st => (0, toHeadersV3_js_1.toHeadersV3)({ headers, stackTrail: st, context }));
     const parsedLinks = stackTrail.trace('links', st => (0, toLinksV3_js_1.toLinksV3)({ links, stackTrail: st, context }));
     const parsedContent = stackTrail.trace('content', st => (0, toMediaTypeItemV3_js_1.toOptionalMediaTypeItemsV3)({ content, stackTrail: st, context }));
-    return context.withStackTrail(stackTrail, () => new Response_js_1.OasResponse({
+    const parsed = context.withStackTrail(stackTrail, () => new Response_js_1.OasResponse({
         description,
         headers: parsedHeaders,
         links: parsedLinks,
         content: parsedContent,
         extensionFields
     }, context));
+    (0, logBodyMediaTypes_js_1.logBodyMediaTypes)({ content: parsedContent, stackTrail, context });
+    return parsed;
 };
 exports.toResponseV3 = toResponseV3;

package/script/parse/v3-2/requestBody/toRequestBodiesV3.js

@@ -6,6 +6,7 @@ const toRefV31_js_1 = require("../ref/toRefV31.js");
 const toMediaTypeItemV3_js_1 = require("../mediaType/toMediaTypeItemV3.js");
 const RequestBody_js_1 = require("../../../oas/requestBody/RequestBody.js");
 const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
+const logBodyMediaTypes_js_1 = require("../../logBodyMediaTypes.js");
 const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
     if (!requestBody) {
         return undefined;
@@ -29,7 +30,9 @@ const toRequestBodyV3 = ({ requestBody, stackTrail, context }) => {
         required,
         extensionFields
     };
-    return context.withStackTrail(stackTrail, () => new RequestBody_js_1.OasRequestBody(fields, context));
+    const parsed = context.withStackTrail(stackTrail, () => new RequestBody_js_1.OasRequestBody(fields, context));
+    (0, logBodyMediaTypes_js_1.logBodyMediaTypes)({ content: fields.content, stackTrail, context });
+    return parsed;
 };
 exports.toRequestBodyV3 = toRequestBodyV3;
 const toRequestBodiesV3 = ({ requestBodies, stackTrail, context }) => {

package/script/parse/v3-2/response/toResponseV3.js

@@ -9,6 +9,7 @@ const toMediaTypeItemV3_js_1 = require("../mediaType/toMediaTypeItemV3.js");
 const Response_js_1 = require("../../../oas/response/Response.js");
 const toSpecificationExtensionsV3_js_1 = require("../specificationExtensions/toSpecificationExtensionsV3.js");
 const tryParseAt_js_1 = require("../../../context/tryParseAt.js");
+const logBodyMediaTypes_js_1 = require("../../logBodyMediaTypes.js");
 const toResponsesV3 = ({ responses, stackTrail, context }) => {
     const output = {};
     const entries = Object.entries(responses);
@@ -50,7 +51,7 @@ const toResponseV3 = ({ response, stackTrail, context }) => {
     const parsedHeaders = stackTrail.trace('headers', st => (0, toHeadersV3_js_1.toHeadersV3)({ headers, stackTrail: st, context }));
     const parsedLinks = stackTrail.trace('links', st => (0, toLinksV3_js_1.toLinksV3)({ links, stackTrail: st, context }));
     const parsedContent = stackTrail.trace('content', st => (0, toMediaTypeItemV3_js_1.toOptionalMediaTypeItemsV3)({ content, stackTrail: st, context }));
-    return context.withStackTrail(stackTrail, () => new Response_js_1.OasResponse({
+    const parsed = context.withStackTrail(stackTrail, () => new Response_js_1.OasResponse({
         summary,
         description,
         headers: parsedHeaders,
@@ -58,5 +59,7 @@ const toResponseV3 = ({ response, stackTrail, context }) => {
         content: parsedContent,
         extensionFields
     }, context));
+    (0, logBodyMediaTypes_js_1.logBodyMediaTypes)({ content: parsedContent, stackTrail, context });
+    return parsed;
 };
 exports.toResponseV3 = toResponseV3;