@scalar/mock-server 0.14.4 → 0.16.0

package/dist/utils/get-open-auth-token-urls.js

@@ -1,7 +1,7 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 /**
- * Extract path from URL. Metadata is fetched at its exact declared URL, so its routes
- * preserve trailing slashes instead of using the token-route normalization.
+ * Extract path from URL. Metadata routes preserve trailing slashes because discovery
+ * fetches the exact declared URL, unlike normalized token routes.
  */
 export function getPathFromUrl(url, { preserveTrailingSlash = false } = {}) {
     try {
@@ -41,13 +41,15 @@ export function getOpenAuthTokenUrls(schema) {
         if (!scheme || !isOAuth2Scheme(scheme)) {
             continue;
         }
-        const flows = scheme.flows; // Type assertion no longer needed
+        const flows = scheme.flows;
         // Helper to safely add valid OAuth URLs
         const addOAuthUrl = (url) => {
             if (url && isValidOAuthUrl(url)) {
                 oauthUrls.add(getPathFromUrl(url));
             }
         };
+        addOAuthUrl(flows?.deviceAuthorization?.tokenUrl);
+        addOAuthUrl(flows?.deviceAuthorization?.refreshUrl);
         addOAuthUrl(flows?.password?.tokenUrl);
         addOAuthUrl(flows?.password?.refreshUrl);
         addOAuthUrl(flows?.clientCredentials?.tokenUrl);

package/dist/utils/get-operation.d.ts

@@ -1,8 +1,10 @@
 import type { OpenAPIV3_1 } from '@scalar/openapi-types';
-import { type HttpMethod } from '../types.js';
 /**
  * Takes a dereferenced OpenAPI document and returns all operations.
+ * Keys use their wire capitalization: fixed methods are uppercase, additional methods retain their case.
  * Ignores other attributes, like summary, parameters, etc.
  */
-export declare function getOperations(path?: OpenAPIV3_1.PathItemObject): Record<HttpMethod, OpenAPIV3_1.OperationObject>;
+export declare const getOperations: (path?: OpenAPIV3_1.PathItemObject & {
+    additionalOperations?: Record<string, OpenAPIV3_1.OperationObject>;
+}) => Record<string, OpenAPIV3_1.OperationObject>;
 //# sourceMappingURL=get-operation.d.ts.map

package/dist/utils/get-operation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-operation.d.ts","sourceRoot":"","sources":["../../src/utils/get-operation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,EAAE,KAAK,UAAU,EAAe,MAAM,SAAS,CAAA;AAEtD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,cAAc,GAAG,MAAM,CAAC,UAAU,EAAE,WAAW,CAAC,eAAe,CAAC,CAUhH"}
+{"version":3,"file":"get-operation.d.ts","sourceRoot":"","sources":["../../src/utils/get-operation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,WAAW,CAAC,cAAc,GAAG;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,eAAe,CAAC,CAAA;CACnE,KACA,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,eAAe,CAc5C,CAAA"}

package/dist/utils/get-operation.js

@@ -1,14 +1,18 @@
 import { httpMethods } from '../types.js';
 /**
  * Takes a dereferenced OpenAPI document and returns all operations.
+ * Keys use their wire capitalization: fixed methods are uppercase, additional methods retain their case.
  * Ignores other attributes, like summary, parameters, etc.
  */
-export function getOperations(path) {
-    const operations = {};
+export const getOperations = (path) => {
+    const operations = new Map();
     for (const method of httpMethods) {
         if (path?.[method]) {
-            operations[method] = path?.[method];
+            operations.set(method.toUpperCase(), path[method]);
         }
     }
-    return operations;
-}
+    for (const [method, operation] of Object.entries(path?.additionalOperations ?? {})) {
+        operations.set(method, operation);
+    }
+    return Object.fromEntries(operations);
+};

package/dist/utils/handle-authentication.d.ts

@@ -1,4 +1,4 @@
-import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { OpenAPIV3_1, OpenAPIV3_2 } from '@scalar/openapi-types';
 import type { Context } from 'hono';
 /**
  * Handles authentication for incoming requests based on the OpenAPI document.
@@ -8,5 +8,5 @@ import type { Context } from 'hono';
  * only when *every* scheme it lists is satisfied. An empty requirement object (`{}`)
  * means authentication is optional and always passes.
  */
-export declare function handleAuthentication(schema?: OpenAPIV3_1.Document, operation?: OpenAPIV3_1.OperationObject): (c: Context, next: () => Promise<void>) => Promise<Response | void>;
+export declare function handleAuthentication(schema?: OpenAPIV3_1.Document | OpenAPIV3_2.Document, operation?: OpenAPIV3_2.OperationObject): (c: Context, next: () => Promise<void>) => Promise<Response | void>;
 //# sourceMappingURL=handle-authentication.d.ts.map

package/dist/utils/handle-authentication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle-authentication.d.ts","sourceRoot":"","sources":["../../src/utils/handle-authentication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAEnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAiInC;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,IAC3F,GAAG,OAAO,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA4D/E"}
+{"version":3,"file":"handle-authentication.d.ts","sourceRoot":"","sources":["../../src/utils/handle-authentication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,WAAW,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAEhF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAiInC;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,EACpD,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,IAEzB,GAAG,OAAO,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA4D/E"}

package/dist/utils/log-authentication-instructions.d.ts

@@ -1,4 +1,4 @@
-import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { OpenAPIV3_2 } from '@scalar/openapi-types';
 import type { MockServerLogger } from '../types.js';
 /**
  * Log authentication instructions for different security schemes.
@@ -7,5 +7,5 @@ import type { MockServerLogger } from '../types.js';
  * security schemes the mock server cannot handle are printed unconditionally, so a silenced startup
  * still surfaces schemes that will not work.
  */
-export declare function logAuthenticationInstructions(securitySchemes: Record<string, OpenAPIV3_1.SecuritySchemeObject>, log?: MockServerLogger): void;
+export declare function logAuthenticationInstructions(securitySchemes: Record<string, OpenAPIV3_2.SecuritySchemeObject>, log?: MockServerLogger): void;
 //# sourceMappingURL=log-authentication-instructions.d.ts.map

package/dist/utils/log-authentication-instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-authentication-instructions.d.ts","sourceRoot":"","sources":["../../src/utils/log-authentication-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI/C;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,EACjE,GAAG,GAAE,gBAA8C,QAiIpD"}
+{"version":3,"file":"log-authentication-instructions.d.ts","sourceRoot":"","sources":["../../src/utils/log-authentication-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI/C;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,EACjE,GAAG,GAAE,gBAA8C,QA4IpD"}

package/dist/utils/log-authentication-instructions.js

@@ -76,6 +76,13 @@ export function logAuthenticationInstructions(securitySchemes, log = (line) => c
                 if (scheme.flows) {
                     Object.keys(scheme.flows).forEach((flow) => {
                         switch (flow) {
+                            case 'deviceAuthorization':
+                                log('✅ OAuth 2.0 Device Authorization Flow');
+                                log(`   POST ${getPathFromUrl(scheme.flows?.deviceAuthorization?.deviceAuthorizationUrl || '/oauth/device')}`);
+                                log('   Send client_id and scope as form data, open verification_uri, and enter user_code.');
+                                log(`   Poll ${getPathFromUrl(scheme.flows?.deviceAuthorization?.tokenUrl || '/oauth/token')} with grant_type=urn:ietf:params:oauth:grant-type:device_code and device_code.`);
+                                log('');
+                                break;
                             case 'implicit':
                                 log('✅ OAuth 2.0 Implicit Flow');
                                 log('   Use the following URL to initiate the OAuth 2.0 Implicit Flow:');

package/dist/utils/negotiate-content-type.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from 'hono';
+/** Use the same response media-type preference for generated and custom-handler responses. */
+export declare const negotiateContentType: (c: Context, content: Record<string, unknown> | undefined) => string;
+//# sourceMappingURL=negotiate-content-type.d.ts.map

package/dist/utils/negotiate-content-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiate-content-type.d.ts","sourceRoot":"","sources":["../../src/utils/negotiate-content-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAGnC,8FAA8F;AAC9F,eAAO,MAAM,oBAAoB,GAAI,GAAG,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAG,MAS/F,CAAA"}

package/dist/utils/negotiate-content-type.js

@@ -0,0 +1,12 @@
+import { accepts } from 'hono/accepts';
+/** Use the same response media-type preference for generated and custom-handler responses. */
+export const negotiateContentType = (c, content) => {
+    const supportedContentTypes = Object.keys(content ?? {});
+    return accepts(c, {
+        header: 'Accept',
+        supports: supportedContentTypes,
+        default: supportedContentTypes.includes('application/json')
+            ? 'application/json'
+            : (supportedContentTypes[0] ?? 'text/plain;charset=UTF-8'),
+    });
+};

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

@@ -1,6 +1,6 @@
-import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { OpenAPIV3_1, OpenAPIV3_2 } from '@scalar/openapi-types';
 /**
- * Processes an OpenAPI document by bundling external references, upgrading to OpenAPI 3.1,
+ * Processes an OpenAPI document by bundling external references, upgrading compatible input to OpenAPI 3.2,
  * and wrapping it so internal references stay intact but resolve lazily.
  *
  * Unlike a full dereference, the returned document keeps `$ref` nodes in place. Consumers
@@ -8,9 +8,12 @@ import type { OpenAPIV3_1 } from '@scalar/openapi-types';
  * `$ref-value` exposed by the magic proxy. This avoids eagerly flattening (and duplicating)
  * the whole document up front.
  *
+ * Compatibility failures retain the OpenAPI 3.1 document and its version, without applying partial migrations.
+ *
  * @param document - The OpenAPI document to process. Can be a string (URL/path) or an object.
- * @returns A promise that resolves to the OpenAPI 3.1 document with lazily resolvable references.
+ * @param origin - Source file path or URL for resolving references in an already loaded document.
+ * @returns A promise that resolves to the document with lazily resolvable references.
  * @throws Error if the document cannot be processed or is invalid.
  */
-export declare function processOpenApiDocument(document: string | Record<string, any> | undefined): Promise<OpenAPIV3_1.Document>;
+export declare function processOpenApiDocument(document: string | Record<string, any> | undefined, origin?: string): Promise<OpenAPIV3_1.Document | OpenAPIV3_2.Document>;
 //# sourceMappingURL=process-openapi-document.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"process-openapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-openapi-document.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GACjD,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAsD/B"}
+{"version":3,"file":"process-openapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-openapi-document.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIrE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAClD,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAkEtD"}

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

@@ -3,10 +3,12 @@ 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 { isHttpUrl } from '@scalar/json-magic/helpers/is-http-url';
 import { createMagicProxy } from '@scalar/json-magic/magic-proxy';
 import { upgrade } from '@scalar/openapi-upgrader';
+import { openApiDocument, resolveOpenApiDocument } from '@scalar/workspace-store/plugins/bundler';
 /**
- * Processes an OpenAPI document by bundling external references, upgrading to OpenAPI 3.1,
+ * Processes an OpenAPI document by bundling external references, upgrading compatible input to OpenAPI 3.2,
  * and wrapping it so internal references stay intact but resolve lazily.
  *
  * Unlike a full dereference, the returned document keeps `$ref` nodes in place. Consumers
@@ -14,16 +16,19 @@ import { upgrade } from '@scalar/openapi-upgrader';
  * `$ref-value` exposed by the magic proxy. This avoids eagerly flattening (and duplicating)
  * the whole document up front.
  *
+ * Compatibility failures retain the OpenAPI 3.1 document and its version, without applying partial migrations.
+ *
  * @param document - The OpenAPI document to process. Can be a string (URL/path) or an object.
- * @returns A promise that resolves to the OpenAPI 3.1 document with lazily resolvable references.
+ * @param origin - Source file path or URL for resolving references in an already loaded document.
+ * @returns A promise that resolves to the document with lazily resolvable references.
  * @throws Error if the document cannot be processed or is invalid.
  */
-export async function processOpenApiDocument(document) {
+export async function processOpenApiDocument(document, origin) {
     // Handle empty/undefined input gracefully
     if (!document || (typeof document === 'object' && Object.keys(document).length === 0)) {
-        // Return a minimal valid OpenAPI 3.1 document
+        // Return a minimal valid OpenAPI 3.2 document
         return {
-            openapi: '3.1.0',
+            openapi: '3.2.0',
             info: {
                 title: 'Mock API',
                 version: '1.0.0',
@@ -35,12 +40,20 @@ export async function processOpenApiDocument(document) {
     // Confine local file `$ref`s to the document's own directory (or the working directory when the
     // document is an object or inline string), and refuse to fetch private or internal addresses.
     // Without these guards a `$ref` could read arbitrary local files or reach internal services.
-    const basePath = typeof document === 'string' && isFilePath(document) ? path.dirname(path.resolve(document)) : cwd();
+    const source = origin ?? document;
+    const basePath = typeof source === 'string' && isFilePath(source) ? path.dirname(path.resolve(source)) : cwd();
     try {
         // Bundle external references with Node.js plugins
         // Include parseJson and parseYaml to handle string inputs
         bundled = await bundle(document, {
-            plugins: [parseJson(), parseYaml(), readFiles({ basePath }), fetchUrls({ blockPrivateNetworks: true })],
+            origin,
+            plugins: [
+                openApiDocument(),
+                parseJson(),
+                parseYaml(),
+                readFiles({ basePath }),
+                fetchUrls({ blockPrivateNetworks: true }),
+            ],
             treeShake: false,
         });
     }
@@ -50,18 +63,20 @@ export async function processOpenApiDocument(document) {
     if (!bundled || typeof bundled !== 'object') {
         throw new Error('Bundled document is invalid: expected an object');
     }
+    // Upgrading must not activate a $self field authored in an older OpenAPI version.
+    const retrievalUri = origin ?? (typeof document === 'string' && (isFilePath(document) || isHttpUrl(document)) ? document : '/');
+    const documentUri = resolveOpenApiDocument(bundled, retrievalUri)?.baseUri;
     let upgraded;
     try {
-        // Upgrade to OpenAPI 3.1
-        upgraded = upgrade(bundled, '3.1');
+        upgraded = upgrade(bundled, '3.2', { onIncompatible: 'collect' }).document;
     }
     catch (error) {
-        throw new Error(`Failed to upgrade OpenAPI document to 3.1: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Failed to upgrade OpenAPI document to 3.2: ${error instanceof Error ? error.message : String(error)}`);
     }
     if (!upgraded) {
         throw new Error('Upgraded document is invalid: upgrade returned null or undefined');
     }
     // Wrap the document in a magic proxy so internal references resolve lazily via `$ref-value`.
     // External references were already pulled inline by `bundle` above, so only local `$ref`s remain.
-    return createMagicProxy(upgraded);
+    return createMagicProxy(upgraded, { documentUri });
 }

package/dist/utils/querystring-parameter.d.ts

@@ -0,0 +1,11 @@
+import type { OpenAPIV3_2 } from '@scalar/openapi-types';
+/**
+ * Find the whole-query parameter, giving operation declarations precedence over path declarations.
+ * This module decodes incoming queries; workspace-store/src/helpers/querystring-parameter.ts serializes outgoing ones.
+ */
+export declare const findQuerystringParameter: (operation?: OpenAPIV3_2.OperationObject, pathParameters?: OpenAPIV3_2.PathItemObject["parameters"]) => OpenAPIV3_2.ParameterObject | undefined;
+/** Validate JSON-encoded form properties before the coercing form validator can alter their native types. */
+export declare const getQuerystringJsonSchema: (parameter: OpenAPIV3_2.ParameterObject | undefined) => Record<string, unknown> | null;
+/** Decode the complete query without introducing the parameter's documentary name. Throws on malformed JSON or URI escaping. */
+export declare const parseQuerystringParameter: (url: string, parameter: OpenAPIV3_2.ParameterObject) => unknown;
+//# sourceMappingURL=querystring-parameter.d.ts.map

package/dist/utils/querystring-parameter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"querystring-parameter.d.ts","sourceRoot":"","sources":["../../src/utils/querystring-parameter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAaxD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GACnC,YAAY,WAAW,CAAC,eAAe,EACvC,iBAAiB,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,KACxD,WAAW,CAAC,eAAe,GAAG,SAMwB,CAAA;AAkBzD,6GAA6G;AAC7G,eAAO,MAAM,wBAAwB,GACnC,WAAW,WAAW,CAAC,eAAe,GAAG,SAAS,KACjD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAkC5B,CAAA;AAED,gIAAgI;AAChI,eAAO,MAAM,yBAAyB,GAAI,KAAK,MAAM,EAAE,WAAW,WAAW,CAAC,eAAe,KAAG,OA0E/F,CAAA"}

package/dist/utils/querystring-parameter.js

@@ -0,0 +1,135 @@
+import { getFirstMediaType } from '@scalar/helpers/http/get-first-media-type';
+import { isJsonMediaType } from '@scalar/helpers/http/is-json-media-type';
+import { parseMimeType } from '@scalar/helpers/http/mime-type';
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
+import { deserializeArrayParameter, deserializeObjectParameter, getObjectPropertyNames, isArraySchema, isObjectSchema, resolveSerialization, } from './deserialize-parameter.js';
+/**
+ * Find the whole-query parameter, giving operation declarations precedence over path declarations.
+ * This module decodes incoming queries; workspace-store/src/helpers/querystring-parameter.ts serializes outgoing ones.
+ */
+export const findQuerystringParameter = (operation, pathParameters) => [
+    ...(Array.isArray(operation?.parameters) ? operation.parameters : []),
+    ...(Array.isArray(pathParameters) ? pathParameters : []),
+]
+    .map((parameter) => getResolvedRef(parameter))
+    .find((parameter) => parameter?.in === 'querystring');
+/** Collect form properties through compositions so nullable and composed objects retain their encoding. */
+const getPropertySchemas = (schema) => {
+    const properties = {};
+    for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+        const branches = schema?.[keyword];
+        if (Array.isArray(branches)) {
+            for (const branch of branches) {
+                if (branch && typeof branch === 'object') {
+                    Object.assign(properties, getPropertySchemas(branch));
+                }
+            }
+        }
+    }
+    return { ...properties, ...schema?.properties };
+};
+/** Validate JSON-encoded form properties before the coercing form validator can alter their native types. */
+export const getQuerystringJsonSchema = (parameter) => {
+    const [contentType, media] = getFirstMediaType(parameter?.content) ?? [];
+    if (parseMimeType(contentType).essence !== 'application/x-www-form-urlencoded') {
+        return null;
+    }
+    const selectJsonProperties = (schema) => {
+        const properties = (schema?.properties ?? {});
+        const jsonProperties = Object.fromEntries(Object.entries(properties).filter(([name, property]) => {
+            const encoding = media?.encoding?.[name];
+            if (encoding?.style !== undefined || encoding?.explode !== undefined || encoding?.allowReserved !== undefined) {
+                return false;
+            }
+            const item = isArraySchema(property) ? property.items : property;
+            return isJsonMediaType(encoding?.contentType) || isObjectSchema(item) || isArraySchema(item);
+        }));
+        const result = { properties: jsonProperties };
+        for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+            const branches = schema?.[keyword];
+            if (Array.isArray(branches)) {
+                // Non-JSON fields may distinguish oneOf branches. The complete validator enforces exclusivity.
+                const target = keyword === 'oneOf' ? 'anyOf' : keyword;
+                const selected = branches.map((branch) => selectJsonProperties(branch));
+                if (target in result) {
+                    result.allOf = [...(Array.isArray(result.allOf) ? result.allOf : []), { [target]: selected }];
+                }
+                else {
+                    result[target] = selected;
+                }
+            }
+        }
+        return result;
+    };
+    return selectJsonProperties(getResolvedRefDeep(media?.schema));
+};
+/** Decode the complete query without introducing the parameter's documentary name. Throws on malformed JSON or URI escaping. */
+export const parseQuerystringParameter = (url, parameter) => {
+    const query = new URL(url).search.slice(1);
+    if (!query) {
+        return undefined;
+    }
+    const [contentType, media] = getFirstMediaType(parameter.content) ?? [];
+    const mediaType = parseMimeType(contentType).essence;
+    if (mediaType !== 'application/x-www-form-urlencoded') {
+        const decoded = decodeURIComponent(query);
+        return isJsonMediaType(mediaType) ? JSON.parse(decoded) : decoded;
+    }
+    const params = new URLSearchParams(query);
+    const map = Object.fromEntries([...new Set(params.keys())].map((key) => {
+        const values = params.getAll(key);
+        return [key, values.length === 1 ? (values[0] ?? '') : values];
+    }));
+    const result = { ...map };
+    const schema = getResolvedRefDeep(media?.schema);
+    const properties = getPropertySchemas(schema);
+    for (const name of getObjectPropertyNames(schema)) {
+        const property = properties?.[name];
+        const encoding = media?.encoding?.[name];
+        const single = params.get(name) ?? undefined;
+        const styleBased = encoding?.style !== undefined || encoding?.explode !== undefined || encoding?.allowReserved !== undefined;
+        if (styleBased) {
+            const { style, explode } = resolveSerialization('query', encoding?.style, encoding?.explode);
+            const value = isObjectSchema(property)
+                ? deserializeObjectParameter({
+                    style,
+                    explode,
+                    single,
+                    map,
+                    name,
+                    propertyNames: getObjectPropertyNames(property),
+                    reservedKeys: new Set(Object.keys(properties)),
+                })
+                : isArraySchema(property)
+                    ? deserializeArrayParameter({
+                        style,
+                        explode,
+                        single,
+                        multi: params.has(name) ? params.getAll(name) : undefined,
+                    })
+                    : single;
+            if (value !== undefined) {
+                if (isObjectSchema(property) &&
+                    (style === 'deepObject' || (style === 'form' && explode)) &&
+                    typeof value === 'object' &&
+                    value !== null) {
+                    for (const key of Object.keys(value)) {
+                        delete result[style === 'deepObject' ? `${name}[${key}]` : key];
+                    }
+                }
+                result[name] = value;
+            }
+            continue;
+        }
+        if (single === undefined) {
+            continue;
+        }
+        const json = isJsonMediaType(encoding?.contentType);
+        const decode = (value, itemSchema) => json || isObjectSchema(itemSchema) || isArraySchema(itemSchema) ? JSON.parse(value) : value;
+        result[name] = isArraySchema(property)
+            ? params.getAll(name).map((value) => decode(value, property?.items))
+            : decode(single, property);
+    }
+    return result;
+};

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

@@ -16,7 +16,9 @@ import type { OpenAPIV3_1 } from '@scalar/openapi-types';
  * caller still gets a schema-generated body. An unknown `exampleName` simply
  * falls through to the later steps.
  */
-export declare const selectResponseExample: (mediaType: OpenAPIV3_1.MediaTypeObject | undefined, exampleName?: string) => {
+export declare const selectResponseExample: <T extends Pick<OpenAPIV3_1.MediaTypeObject, "example" | "examples"> & {
+    schema?: unknown;
+}>(mediaType: T | undefined, exampleName?: string) => {
     value: unknown;
 } | undefined;
 //# 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,WAAW,WAAW,CAAC,eAAe,GAAG,SAAS,EAClD,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;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"}

package/dist/utils/set-up-authentication-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set-up-authentication-routes.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-authentication-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAE5E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAQhC;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,QA+G7E"}
+{"version":3,"file":"set-up-authentication-routes.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-authentication-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAE5E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAShC;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,QAiH7E"}

package/dist/utils/set-up-authentication-routes.js

@@ -3,11 +3,13 @@ import { respondWithAuthorizePage } from '../routes/respond-with-authorize-page.
 import { respondWithToken } from '../routes/respond-with-token.js';
 import { getOAuth2Metadata } from './get-oauth2-metadata.js';
 import { getOpenAuthTokenUrls, getPathFromUrl } from './get-open-auth-token-urls.js';
+import { setUpDeviceAuthorization } from './set-up-device-authorization.js';
 /**
  * Helper function to set up authentication routes for OAuth 2.0 flows
  */
 export function setUpAuthenticationRoutes(app, schema) {
     const securitySchemes = schema?.components?.securitySchemes || {};
+    setUpDeviceAuthorization(app, schema);
     // Set up authentication routes for OAuth 2.0 flows
     getOpenAuthTokenUrls(schema).forEach((tokenUrl) => {
         app.post(tokenUrl, (c) => {

package/dist/utils/set-up-device-authorization.d.ts

@@ -0,0 +1,5 @@
+import type { OpenAPI } from '@scalar/openapi-types';
+import type { Hono } from 'hono';
+/** Registers a local RFC8628 approval flow before the permissive mock token handlers. */
+export declare const setUpDeviceAuthorization: (app: Hono, document?: OpenAPI.Document) => void;
+//# sourceMappingURL=set-up-device-authorization.d.ts.map

package/dist/utils/set-up-device-authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-up-device-authorization.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-device-authorization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,uBAAuB,CAAA;AAEjE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AA0FhC,yFAAyF;AACzF,eAAO,MAAM,wBAAwB,GAAI,KAAK,IAAI,EAAE,WAAW,OAAO,CAAC,QAAQ,KAAG,IAsJjF,CAAA"}