@scalar/mock-server 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @scalar/mock-server
 
+## 0.17.1
+
+## 0.17.0
+
+### Minor Changes
+
+- [#10192](https://github.com/scalar/scalar/pull/10192): Mock-server XML response bytes now use the shared schema-aware serializer instead of `json2xml`, including attributes, namespaces, and root naming. Existing XML response snapshots may need updating. Supplied serialized XML remains unchanged.
+
+  Generate XML examples from schema metadata, preserving attributes, namespaces, array wrappers, repeated elements, and OpenAPI 3.2 text and CDATA nodes. Use the same XML serialization for request bodies, code snippets, response examples, mock responses, and Markdown documentation. Preserve serialized media examples and escape schema string examples as element text.
+
+  Explain XML generation failures in response example panels, including the serialized-example escape hatch for large payloads. Expose XML generation failures in mock response headers with `X-Scalar-XML-Error`, containing the first error diagnostic code. Report diagnostics to other consumers through a callback or the developer console, and format element-only descendants within mixed content without changing text values.
+
+### Patch Changes
+
+- [#10343](https://github.com/scalar/scalar/pull/10343): Restrict AsyncAPI external references to the source directory and public network addresses, and preserve the source location for preloaded documents.
+
+  URL inputs to `createAsyncApiMockServer` also reject private network addresses, including localhost. Load local files or pass preloaded document content for local development. Docker documents supplied through `OPENAPI_DOCUMENT` resolve relative references from their temporary `/tmp/openapi.json` or `/tmp/openapi.yaml` file, confined to `/tmp`. Both OpenAPI and AsyncAPI Docker documents preserve the selected source origin.
+
+- [#10192](https://github.com/scalar/scalar/pull/10192): Apply edited XML bodies instead of their original serialized or data examples, render schema-free XML examples in Markdown, and share reference decoding and response provenance selection.
+
 ## 0.16.0
 
 ### Minor Changes

package/dist/create-asyncapi-mock-server.d.ts

@@ -9,6 +9,8 @@ export type AsyncApiMockServerOptions = {
      * string, or an already-parsed object.
      */
     document?: string | Record<string, any>;
+    /** Source file path or URL for resolving references in an already loaded document. */
+    origin?: string;
     /**
      * Additional transports appended after the built-in WebSocket and SSE transports. Use this to
      * support extra protocols (for example SignalR) without changing the core. The first transport

package/dist/create-asyncapi-mock-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-asyncapi-mock-server.d.ts","sourceRoot":"","sources":["../src/create-asyncapi-mock-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAoB,MAAM,mBAAmB,CAAA;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAK3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAoB,MAAM,oBAAoB,CAAA;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAM/C,oDAAoD;AACpD,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;IAE5B,yFAAyF;IACzF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAE/F;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAA;CACpC,CAAA;AAED,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sEAAsE;IACtE,GAAG,EAAE,IAAI,CAAA;IACT,wFAAwF;IACxF,SAAS,EAAE;QAAE,MAAM,EAAE,mBAAmB,CAAA;KAAE,CAAA;CAC3C,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqC9G"}
+{"version":3,"file":"create-asyncapi-mock-server.d.ts","sourceRoot":"","sources":["../src/create-asyncapi-mock-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAoB,MAAM,mBAAmB,CAAA;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAK3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAoB,MAAM,oBAAoB,CAAA;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAM/C,oDAAoD;AACpD,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;IAE5B,yFAAyF;IACzF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAE/F;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAA;CACpC,CAAA;AAED,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sEAAsE;IACtE,GAAG,EAAE,IAAI,CAAA;IACT,wFAAwF;IACxF,SAAS,EAAE;QAAE,MAAM,EAAE,mBAAmB,CAAA;KAAE,CAAA;CAC3C,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqC9G"}

package/dist/create-asyncapi-mock-server.js

@@ -22,7 +22,7 @@ import { resolveLogger } from './utils/resolve-logger.js';
  */
 export async function createAsyncApiMockServer(options) {
     const app = new Hono();
-    const document = await processAsyncApiDocument(options.document);
+    const document = await processAsyncApiDocument(options.document, options.origin);
     const channels = resolveChannels(document);
     const transports = [...defaultTransports, ...(options.transports ?? [])];
     const log = resolveLogger(options.logger, false);

package/dist/create-mock-server.js

@@ -109,7 +109,7 @@ export async function createMockServer(configuration) {
             allowedMethods.add(method);
         }
     }
-    app.use(cors({ origin: '*', allowMethods: [...allowedMethods] }));
+    app.use(cors({ origin: '*', allowMethods: [...allowedMethods], exposeHeaders: ['X-Scalar-XML-Error'] }));
     /** Authentication methods defined in the OpenAPI document */
     setUpAuthenticationRoutes(app, schema);
     // Only the instructions honor `logger` (on by default); the util still prints warnings and errors
@@ -192,10 +192,10 @@ export async function createMockServer(configuration) {
             const hasHandler = handlerCode && typeof handlerCode === 'string' && handlerCode.trim().length > 0;
             // Route to appropriate handler
             if (hasHandler) {
-                handlers.push(async (c) => await mockHandlerResponse(c, operation, pathItem?.parameters));
+                handlers.push(async (c) => await mockHandlerResponse(c, operation, pathItem?.parameters, schema.openapi));
             }
             else {
-                handlers.push(async (c) => await mockAnyResponse(c, operation));
+                handlers.push(async (c) => await mockAnyResponse(c, operation, schema.openapi));
             }
             // The pinned query parameters are not part of the route, so they are checked here. A request
             // that does not carry them is handed on to the next matching route — usually the sibling path

package/dist/routes/mock-any-response.d.ts

@@ -3,5 +3,5 @@ import type { Context } from 'hono';
 /**
  * Mock any response
  */
-export declare function mockAnyResponse(c: Context, operation: OpenAPIV3_1.OperationObject): Response;
+export declare function mockAnyResponse(c: Context, operation: OpenAPIV3_1.OperationObject, openapiVersion?: string): Response;
 //# sourceMappingURL=mock-any-response.d.ts.map

package/dist/routes/mock-any-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-any-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-any-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAenC;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,YA6IjF"}
+{"version":3,"file":"mock-any-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-any-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAKxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAenC;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,EAAE,cAAc,CAAC,EAAE,MAAM,YA4J1G"}

package/dist/routes/mock-any-response.js

@@ -1,6 +1,7 @@
+import { isXmlMediaType } from '@scalar/helpers/http/is-xml-media-type';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
-import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
+import { getExampleFromSchema, getXmlBodyExample } from '@scalar/workspace-store/request-example';
 import { streamSSE } from 'hono/streaming';
 import { collectSseEvents, isEventStreamContentType } from '../utils/collect-sse-events.js';
 import { findPreferredResponseKey } from '../utils/find-preferred-response-key.js';
@@ -15,7 +16,7 @@ import { getStreamingResponse, sendStreamingResponse } from '../utils/streaming-
 /**
  * Mock any response
  */
-export function mockAnyResponse(c, operation) {
+export function mockAnyResponse(c, operation, openapiVersion) {
     // Note: the `onRequest` callback runs as middleware (see `create-mock-server`) so it also fires
     // for requests rejected before reaching this handler.
     // Parse the Prefer header (RFC 7240) so clients can request a specific
@@ -102,9 +103,24 @@ export function mockAnyResponse(c, operation) {
     // Body: a named/singular/first example if one is defined, otherwise generate
     // a value from the schema. `Prefer: example=<name>` picks a named example.
     const selectedExample = selectResponseExample(acceptedResponse, prefer.example);
+    c.status(statusCode);
+    if (isXmlMediaType(acceptedContentType)) {
+        const result = getXmlBodyExample(acceptedResponse?.schema, selectedExample, {
+            openapiVersion,
+            emptyString: 'string',
+            variables: pathParameters(c),
+            mode: 'read',
+        });
+        const error = result.diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+        if (error) {
+            c.header('X-Scalar-XML-Error', error.code);
+        }
+        return result.xml === undefined ? c.body(null) : c.body(result.xml);
+    }
+    const provenance = selectedExample?.provenance;
     const body = (() => {
         if (selectedExample) {
-            return normalizeResponseBody(selectedExample.value, responseSchema);
+            return provenance ? selectedExample.value : normalizeResponseBody(selectedExample.value, responseSchema);
         }
         if (!responseSchema) {
             return null;
@@ -119,8 +135,7 @@ export function mockAnyResponse(c, operation) {
         // Re-inferring it from sibling items would wrap a selected primitive in an array.
         return generated;
     })();
-    c.status(statusCode);
-    const serializedBody = serializeResponseBody(body, acceptedContentType, responseSchema);
+    const serializedBody = serializeResponseBody(body, acceptedContentType, responseSchema, provenance);
     // `JSON.stringify` returns `undefined` for an `undefined` body, which is an empty response.
     if (serializedBody === undefined) {
         return c.body(null);

package/dist/routes/mock-handler-response.d.ts

@@ -4,5 +4,5 @@ import type { Context } from 'hono';
  * Mock response using x-handler code.
  * Executes the handler and returns its result as the response.
  */
-export declare function mockHandlerResponse(c: Context, operation: OpenAPIV3_1.OperationObject, pathItemParameters?: OpenAPIV3_1.PathItemObject['parameters']): Promise<Response>;
+export declare function mockHandlerResponse(c: Context, operation: OpenAPIV3_1.OperationObject, pathItemParameters?: OpenAPIV3_1.PathItemObject['parameters'], openapiVersion?: string): Promise<Response>;
 //# sourceMappingURL=mock-handler-response.d.ts.map

package/dist/routes/mock-handler-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-handler-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-handler-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AA4HnC;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,EAAE,WAAW,CAAC,eAAe,EACtC,kBAAkB,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,qBAqE9D"}
+{"version":3,"file":"mock-handler-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-handler-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAoJnC;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,EAAE,WAAW,CAAC,eAAe,EACtC,kBAAkB,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,EAC7D,cAAc,CAAC,EAAE,MAAM,qBA8ExB"}

package/dist/routes/mock-handler-response.js

@@ -1,4 +1,6 @@
+import { isXmlMediaType } from '@scalar/helpers/http/is-xml-media-type';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { getXmlBodyExample } from '@scalar/workspace-store/request-example';
 import { buildHandlerContext } from '../utils/build-handler-context.js';
 import { executeHandler } from '../utils/execute-handler.js';
 import { generateResponseExample } from '../utils/generate-response-example.js';
@@ -7,16 +9,17 @@ import { normalizeResponseBody } from '../utils/normalize-response-body.js';
 import { parsePreferHeader } from '../utils/parse-prefer-header.js';
 import { pathParameters } from '../utils/path-parameters.js';
 import { selectResponseExample } from '../utils/select-response-example.js';
+import { serializeResponseBody } from '../utils/serialize-response-body.js';
 import { getStreamingResponse, sendStreamingResponse } from '../utils/streaming-response.js';
 /**
  * Get example response from OpenAPI spec for a given status code.
- * Returns the example value if found, or null if not available.
+ * Returns a serialized payload if found, or null if not available.
  *
  * Honors `Prefer: example=<name>` to pick a named example from the
  * `examples` map; otherwise it falls back to the singular `example`, the
  * first entry of the map, or a value generated from the schema.
  */
-function getExampleFromResponse(c, statusCode, responses, exampleName) {
+function getExampleFromResponse(c, statusCode, responses, exampleName, openapiVersion) {
     if (!responses) {
         return null;
     }
@@ -39,11 +42,32 @@ function getExampleFromResponse(c, statusCode, responses, exampleName) {
     const responseSchema = acceptedResponse.schema ? getResolvedRef(acceptedResponse.schema) : undefined;
     // Extract example (named, singular, or first) or generate from schema
     const selectedExample = selectResponseExample(acceptedResponse, exampleName);
-    return selectedExample
+    if (isXmlMediaType(acceptedContentType)) {
+        c.header('Content-Type', acceptedContentType);
+        const result = getXmlBodyExample(acceptedResponse.schema, selectedExample, {
+            openapiVersion,
+            emptyString: 'string',
+            variables: pathParameters(c),
+            mode: 'read',
+        });
+        const error = result.diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+        if (error) {
+            c.header('X-Scalar-XML-Error', error.code);
+        }
+        return result.xml ?? null;
+    }
+    const provenance = selectedExample?.provenance;
+    if (selectedExample && provenance) {
+        c.header('Content-Type', acceptedContentType);
+        return serializeResponseBody(selectedExample.value, acceptedContentType, responseSchema, provenance) ?? null;
+    }
+    const value = selectedExample
         ? normalizeResponseBody(selectedExample.value, responseSchema)
         : responseSchema
             ? normalizeResponseBody(generateResponseExample(responseSchema, pathParameters(c)), responseSchema)
             : null;
+    // Legacy examples retain the handler fallback's JSON encoding policy.
+    return JSON.stringify(value) ?? null;
 }
 /**
  * Determine HTTP status code based on store operation tracking.
@@ -98,7 +122,7 @@ function determineStatusCode(tracking) {
  * Mock response using x-handler code.
  * Executes the handler and returns its result as the response.
  */
-export async function mockHandlerResponse(c, operation, pathItemParameters) {
+export async function mockHandlerResponse(c, operation, pathItemParameters, openapiVersion) {
     // Note: the `onRequest` callback runs as middleware (see `create-mock-server`) so it also fires
     // for requests rejected before reaching this handler.
     // Get x-handler code from operation
@@ -137,9 +161,12 @@ export async function mockHandlerResponse(c, operation, pathItemParameters) {
         if (result === undefined || result === null) {
             // Try to pick up example response from OpenAPI spec if available
             const prefer = parsePreferHeader(c.req.header('Prefer'));
-            const exampleResponse = getExampleFromResponse(c, statusCode, operation.responses, prefer.example);
+            const exampleResponse = getExampleFromResponse(c, statusCode, operation.responses, prefer.example, openapiVersion);
             if (exampleResponse !== null) {
-                return c.json(exampleResponse);
+                return c.body(exampleResponse);
+            }
+            if (isXmlMediaType(c.res.headers.get('Content-Type') ?? undefined)) {
+                return c.body(null);
             }
             return c.json(null);
         }

package/dist/utils/process-asyncapi-document.d.ts

@@ -11,10 +11,11 @@ import type { AsyncApiDocument } from '@scalar/types/asyncapi/3.1';
  * Only AsyncAPI 3.1 is supported; 2.x documents should be upgraded before being passed in.
  *
  * @param document - The AsyncAPI document to process. Can be a string (URL/path) or an object.
+ * @param origin - Source file path or URL for resolving references in an already loaded document.
  * @returns A promise that resolves to the AsyncAPI document with lazily resolvable references.
  * @throws Error if the document cannot be processed or is invalid.
  */
-export declare function processAsyncApiDocument(document: string | Record<string, any> | undefined): Promise<AsyncApiDocument>;
+export declare function processAsyncApiDocument(document: string | Record<string, any> | undefined, origin?: string): Promise<AsyncApiDocument>;
 /**
  * Detects whether a loaded document describes an AsyncAPI API (rather than OpenAPI/Swagger).
  * Used to route an incoming document to the right mock engine.

package/dist/utils/process-asyncapi-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-asyncapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-asyncapi-document.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAElE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GACjD,OAAO,CAAC,gBAAgB,CAAC,CAiC3B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAE7D"}
+{"version":3,"file":"process-asyncapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-asyncapi-document.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAElE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAClD,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC,CAsC3B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAE7D"}

package/dist/utils/process-asyncapi-document.js

@@ -1,5 +1,8 @@
+import path from 'node:path';
+import { cwd } from 'node:process';
 import { bundle } from '@scalar/json-magic/bundle';
 import { fetchUrls, parseJson, parseYaml, readFiles } from '@scalar/json-magic/bundle/plugins/node';
+import { isFilePath } from '@scalar/json-magic/helpers/is-file-path';
 import { createMagicProxy } from '@scalar/json-magic/magic-proxy';
 /**
  * Processes an AsyncAPI document by bundling external references and wrapping it so internal
@@ -13,10 +16,11 @@ import { createMagicProxy } from '@scalar/json-magic/magic-proxy';
  * Only AsyncAPI 3.1 is supported; 2.x documents should be upgraded before being passed in.
  *
  * @param document - The AsyncAPI document to process. Can be a string (URL/path) or an object.
+ * @param origin - Source file path or URL for resolving references in an already loaded document.
  * @returns A promise that resolves to the AsyncAPI document with lazily resolvable references.
  * @throws Error if the document cannot be processed or is invalid.
  */
-export async function processAsyncApiDocument(document) {
+export async function processAsyncApiDocument(document, origin) {
     // Handle empty/undefined input gracefully with a minimal valid document.
     if (!document || (typeof document === 'object' && Object.keys(document).length === 0)) {
         return {
@@ -30,10 +34,14 @@ export async function processAsyncApiDocument(document) {
         };
     }
     let bundled;
+    // Keep references inside the source directory and prevent access to internal services.
+    const source = origin ?? document;
+    const basePath = typeof source === 'string' && isFilePath(source) ? path.dirname(path.resolve(source)) : cwd();
     try {
         // Bundle external references; parse string inputs (JSON or YAML) along the way.
         bundled = await bundle(document, {
-            plugins: [parseJson(), parseYaml(), readFiles(), fetchUrls()],
+            origin,
+            plugins: [parseJson(), parseYaml(), readFiles({ basePath }), fetchUrls({ blockPrivateNetworks: true })],
             treeShake: false,
         });
     }

package/dist/utils/select-response-example.d.ts

@@ -1,4 +1,9 @@
 import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { ExampleObject } from '@scalar/workspace-store/schemas/v3.2/strict/example';
+type SelectedResponseExample = ExampleObject & {
+    value: unknown;
+    provenance?: 'serialized' | 'data';
+};
 /**
  * Pick the example body for a response media type.
  *
@@ -18,7 +23,6 @@ import type { OpenAPIV3_1 } from '@scalar/openapi-types';
  */
 export declare const selectResponseExample: <T extends Pick<OpenAPIV3_1.MediaTypeObject, "example" | "examples"> & {
     schema?: unknown;
-}>(mediaType: T | undefined, exampleName?: string) => {
-    value: unknown;
-} | undefined;
+}>(mediaType: T | undefined, exampleName?: string) => SelectedResponseExample | undefined;
+export {};
 //# sourceMappingURL=select-response-example.d.ts.map

package/dist/utils/select-response-example.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select-response-example.d.ts","sourceRoot":"","sources":["../../src/utils/select-response-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAChC,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,SAAS,GAAG,UAAU,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAE1F,WAAW,CAAC,GAAG,SAAS,EACxB,cAAc,MAAM,KACnB;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAoCvB,CAAA"}
+{"version":3,"file":"select-response-example.d.ts","sourceRoot":"","sources":["../../src/utils/select-response-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AAExF,KAAK,uBAAuB,GAAG,aAAa,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,YAAY,GAAG,MAAM,CAAA;CAAE,CAAA;AAarG;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAChC,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,SAAS,GAAG,UAAU,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAE1F,WAAW,CAAC,GAAG,SAAS,EACxB,cAAc,MAAM,KACnB,uBAAuB,GAAG,SAkC5B,CAAA"}

package/dist/utils/select-response-example.js

@@ -1,4 +1,14 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+/** Keep serialized/data examples distinguishable until the media serializer runs. */
+const exampleValue = (example) => {
+    if (example?.serializedValue !== undefined) {
+        return { serializedValue: example.serializedValue, value: example.serializedValue, provenance: 'serialized' };
+    }
+    if (example?.dataValue !== undefined) {
+        return { dataValue: example.dataValue, value: example.dataValue, provenance: 'data' };
+    }
+    return example?.value !== undefined ? { value: example.value } : undefined;
+};
 /**
  * Pick the example body for a response media type.
  *
@@ -23,9 +33,9 @@ export const selectResponseExample = (mediaType, exampleName) => {
     const { example, examples } = mediaType;
     // 1. A named example requested via `Prefer: example=<name>`
     if (exampleName && examples && exampleName in examples) {
-        const value = getResolvedRef(examples[exampleName])?.value;
-        if (value !== undefined) {
-            return { value };
+        const selected = exampleValue(getResolvedRef(examples[exampleName]));
+        if (selected) {
+            return selected;
         }
     }
     // 2. The singular `example` keyword
@@ -36,9 +46,9 @@ export const selectResponseExample = (mediaType, exampleName) => {
     if (examples) {
         const firstKey = Object.keys(examples)[0];
         if (firstKey !== undefined) {
-            const value = getResolvedRef(examples[firstKey])?.value;
-            if (value !== undefined) {
-                return { value };
+            const selected = exampleValue(getResolvedRef(examples[firstKey]));
+            if (selected) {
+                return selected;
             }
         }
     }

package/dist/utils/serialize-response-body.d.ts

@@ -6,6 +6,6 @@ type Schema = NonNullable<OpenAPIV3_1.ComponentsObject['schemas']>[string];
  * Returns `undefined` for an `undefined` body, mirroring `JSON.stringify`, so the caller can send an
  * empty body rather than the characters `undefined`.
  */
-export declare const serializeResponseBody: (body: unknown, contentType: string | undefined, schema?: Schema) => string | undefined;
+export declare const serializeResponseBody: (body: unknown, contentType: string | undefined, schema?: Schema, provenance?: "data" | "serialized") => string | undefined;
 export {};
 //# sourceMappingURL=serialize-response-body.d.ts.map

package/dist/utils/serialize-response-body.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize-response-body.d.ts","sourceRoot":"","sources":["../../src/utils/serialize-response-body.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,KAAK,MAAM,GAAG,WAAW,CAAC,WAAW,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AAkE1E;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,OAAO,EACb,aAAa,MAAM,GAAG,SAAS,EAC/B,SAAS,MAAM,KACd,MAAM,GAAG,SAgCX,CAAA"}
+{"version":3,"file":"serialize-response-body.d.ts","sourceRoot":"","sources":["../../src/utils/serialize-response-body.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAKxD,KAAK,MAAM,GAAG,WAAW,CAAC,WAAW,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AA2D1E;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,OAAO,EACb,aAAa,MAAM,GAAG,SAAS,EAC/B,SAAS,MAAM,EACf,aAAa,MAAM,GAAG,YAAY,KACjC,MAAM,GAAG,SAsCX,CAAA"}

package/dist/utils/serialize-response-body.js

@@ -1,5 +1,8 @@
-import { json2xml } from '@scalar/helpers/file/json2xml';
+import { isXmlMediaType } from '@scalar/helpers/http/is-xml-media-type';
 import { parseMimeType } from '@scalar/helpers/http/mime-type';
+import { serializeXmlExample } from '@scalar/workspace-store/request-example';
+import { coerceValue } from '@scalar/workspace-store/schemas/typebox-coerce';
+import { SchemaObjectSchema } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
 /**
  * Whether a media type carries a single JSON document.
  *
@@ -13,11 +16,6 @@ const isJsonDocumentContentType = (contentType) => {
     const { subtype } = parseMimeType(contentType);
     return subtype === 'json' || subtype.endsWith('+json');
 };
-/** Whether a media type carries XML, including suffixed types such as `application/xhtml+xml`. */
-const isXmlContentType = (contentType) => {
-    const { subtype } = parseMimeType(contentType);
-    return subtype === 'xml' || subtype.endsWith('+xml');
-};
 /**
  * How the resolved response schema describes the body: as a string, as something else, or not at all.
  *
@@ -58,11 +56,17 @@ const isSerializedJsonDocument = (value) => {
  * Returns `undefined` for an `undefined` body, mirroring `JSON.stringify`, so the caller can send an
  * empty body rather than the characters `undefined`.
  */
-export const serializeResponseBody = (body, contentType, schema) => {
-    // XML: only an object tree can be turned into a document. `null` is `typeof 'object'` too, but it is
-    // not a valid XML root, so it falls through to `JSON.stringify` below rather than into `json2xml`.
-    if (body !== null && typeof body === 'object' && isXmlContentType(contentType)) {
-        return json2xml(body);
+export const serializeResponseBody = (body, contentType, schema, provenance) => {
+    if (provenance === 'serialized' && typeof body === 'string') {
+        return body;
+    }
+    if (provenance === 'data' && isJsonDocumentContentType(contentType)) {
+        return JSON.stringify(body);
+    }
+    if (isXmlMediaType(contentType)) {
+        return typeof body === 'string'
+            ? body
+            : serializeXmlExample(body, coerceValue(SchemaObjectSchema, schema ?? {}), { mode: 'read' }).xml;
     }
     if (typeof body === 'string') {
         // Anywhere but a single JSON document, the characters are the payload: `text/plain`, `text/html`,

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.16.0",
+  "version": "0.17.1",
   "engines": {
     "node": ">=22"
   },
@@ -53,12 +53,12 @@
   "dependencies": {
     "@faker-js/faker": "10.6.0",
     "@hono/node-server": "^2.1.1",
-    "@scalar/helpers": "0.14.0",
-    "@scalar/json-magic": "0.15.1",
+    "@scalar/helpers": "0.16.0",
+    "@scalar/json-magic": "0.15.3",
     "@scalar/openapi-types": "0.9.7",
-    "@scalar/openapi-upgrader": "0.3.1",
-    "@scalar/types": "0.22.0",
-    "@scalar/workspace-store": "0.66.0",
+    "@scalar/openapi-upgrader": "0.4.1",
+    "@scalar/types": "0.22.2",
+    "@scalar/workspace-store": "0.67.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "hono": "^4.13.8",
@@ -69,7 +69,7 @@
   "devDependencies": {
     "@types/node": "^24.1.0",
     "@types/ws": "8.18.1",
-    "undici": "7.24.4",
+    "undici": "7.29.0",
     "vite": "8.1.5"
   },
   "scripts": {