@scalar/mock-server 0.9.8 → 0.9.10

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

@@ -1,110 +1,150 @@
-import { getExampleFromSchema } from "@scalar/oas-utils/spec-getters";
-import { accepts } from "hono/accepts";
-import { buildHandlerContext } from "../utils/build-handler-context.js";
-import { executeHandler } from "../utils/execute-handler.js";
+import { getExampleFromSchema } from '@scalar/oas-utils/spec-getters';
+import { accepts } from 'hono/accepts';
+import { buildHandlerContext } from '../utils/build-handler-context.js';
+import { executeHandler } from '../utils/execute-handler.js';
+/**
+ * Get example response from OpenAPI spec for a given status code.
+ * Returns the example value if found, or null if not available.
+ */
 function getExampleFromResponse(c, statusCode, responses) {
-  if (!responses) {
-    return null;
-  }
-  const statusCodeStr = statusCode.toString();
-  const response = responses[statusCodeStr] || responses.default;
-  if (!response) {
-    return null;
-  }
-  const supportedContentTypes = Object.keys(response.content ?? {});
-  if (supportedContentTypes.length === 0) {
-    return null;
-  }
-  const acceptedContentType = accepts(c, {
-    header: "Accept",
-    supports: supportedContentTypes,
-    default: supportedContentTypes.includes("application/json") ? "application/json" : supportedContentTypes[0] ?? "text/plain;charset=UTF-8"
-  });
-  const acceptedResponse = response.content?.[acceptedContentType];
-  if (!acceptedResponse) {
-    return null;
-  }
-  return acceptedResponse.example !== void 0 ? acceptedResponse.example : acceptedResponse.schema ? getExampleFromSchema(acceptedResponse.schema, {
-    emptyString: "string",
-    variables: c.req.param(),
-    mode: "read"
-  }) : null;
+    if (!responses) {
+        return null;
+    }
+    const statusCodeStr = statusCode.toString();
+    const response = responses[statusCodeStr] || responses.default;
+    if (!response) {
+        return null;
+    }
+    const supportedContentTypes = Object.keys(response.content ?? {});
+    // If no content types are defined, return null
+    if (supportedContentTypes.length === 0) {
+        return null;
+    }
+    // Content-Type negotiation
+    const acceptedContentType = accepts(c, {
+        header: 'Accept',
+        supports: supportedContentTypes,
+        default: supportedContentTypes.includes('application/json')
+            ? 'application/json'
+            : (supportedContentTypes[0] ?? 'text/plain;charset=UTF-8'),
+    });
+    const acceptedResponse = response.content?.[acceptedContentType];
+    if (!acceptedResponse) {
+        return null;
+    }
+    // Extract example from example property or generate from schema
+    return acceptedResponse.example !== undefined
+        ? acceptedResponse.example
+        : acceptedResponse.schema
+            ? getExampleFromSchema(acceptedResponse.schema, {
+                emptyString: 'string',
+                variables: c.req.param(),
+                mode: 'read',
+            })
+            : null;
 }
+/**
+ * Determine HTTP status code based on store operation tracking.
+ * Prioritizes operations based on semantic meaning:
+ * - get > update > delete > create > list
+ * This ensures that if a handler performs multiple operations (e.g., get followed by create for logging),
+ * the status code reflects the most semantically meaningful operation.
+ */
 function determineStatusCode(tracking) {
-  const { operations } = tracking;
-  if (operations.length === 0) {
-    return 200;
-  }
-  const getOperation = operations.find((op) => op.operation === "get");
-  if (getOperation) {
-    if (getOperation.result === void 0 || getOperation.result === null) {
-      return 404;
+    const { operations } = tracking;
+    // If no operations were performed, default to 200
+    if (operations.length === 0) {
+        return 200;
     }
-    return 200;
-  }
-  const updateOperation = operations.find((op) => op.operation === "update");
-  if (updateOperation) {
-    if (updateOperation.result === null || updateOperation.result === void 0) {
-      return 404;
+    // Priority order: get > update > delete > create > list
+    // Check for get operations first (highest priority)
+    const getOperation = operations.find((op) => op.operation === 'get');
+    if (getOperation) {
+        // Return 404 if get() returned undefined or null
+        if (getOperation.result === undefined || getOperation.result === null) {
+            return 404;
+        }
+        return 200;
     }
-    return 200;
-  }
-  const deleteOperation = operations.find((op) => op.operation === "delete");
-  if (deleteOperation) {
-    if (deleteOperation.result === null || deleteOperation.result === void 0) {
-      return 404;
+    // Check for update operations
+    const updateOperation = operations.find((op) => op.operation === 'update');
+    if (updateOperation) {
+        // Return 404 if update() returned null (item not found)
+        if (updateOperation.result === null || updateOperation.result === undefined) {
+            return 404;
+        }
+        return 200;
     }
-    return 204;
-  }
-  const createOperation = operations.find((op) => op.operation === "create");
-  if (createOperation) {
-    return 201;
-  }
-  return 200;
+    // Check for delete operations
+    const deleteOperation = operations.find((op) => op.operation === 'delete');
+    if (deleteOperation) {
+        // Return 404 if delete() returned null (item not found)
+        if (deleteOperation.result === null || deleteOperation.result === undefined) {
+            return 404;
+        }
+        return 204;
+    }
+    // Check for create operations
+    const createOperation = operations.find((op) => op.operation === 'create');
+    if (createOperation) {
+        return 201;
+    }
+    // Default to 200 for list or any other operation
+    return 200;
 }
-async function mockHandlerResponse(c, operation, options) {
-  if (options?.onRequest) {
-    options.onRequest({
-      context: c,
-      operation
-    });
-  }
-  const handlerCode = operation?.["x-handler"];
-  if (!handlerCode) {
-    c.status(500);
-    return c.json({ error: "x-handler code not found in operation" });
-  }
-  try {
-    const { context, tracking } = await buildHandlerContext(c, operation);
-    const { result } = await executeHandler(handlerCode, context);
-    const statusCode = determineStatusCode(tracking);
-    c.status(statusCode);
-    if (statusCode === 204) {
-      return c.body(null);
+/**
+ * Mock response using x-handler code.
+ * Executes the handler and returns its result as the response.
+ */
+export async function mockHandlerResponse(c, operation, options) {
+    // Call onRequest callback
+    if (options?.onRequest) {
+        options.onRequest({
+            context: c,
+            operation,
+        });
     }
-    c.header("Content-Type", "application/json");
-    if (result === void 0 || result === null) {
-      const exampleResponse = getExampleFromResponse(
-        c,
-        statusCode,
-        operation.responses
-      );
-      if (exampleResponse !== null) {
-        return c.json(exampleResponse);
-      }
-      return c.json(null);
+    // Get x-handler code from operation
+    const handlerCode = operation?.['x-handler'];
+    if (!handlerCode) {
+        c.status(500);
+        return c.json({ error: 'x-handler code not found in operation' });
+    }
+    try {
+        // Build handler context with tracking
+        const { context, tracking } = await buildHandlerContext(c, operation);
+        // Execute handler
+        const { result } = await executeHandler(handlerCode, context);
+        // Determine status code based on all store operations, prioritizing semantically meaningful ones
+        const statusCode = determineStatusCode(tracking);
+        // Set status code
+        c.status(statusCode);
+        // For 204 No Content, return null body without Content-Type header
+        if (statusCode === 204) {
+            return c.body(null);
+        }
+        // Set Content-Type header for other responses
+        c.header('Content-Type', 'application/json');
+        // Return the handler result as JSON
+        // Handle undefined/null results gracefully
+        if (result === undefined || result === null) {
+            // Try to pick up example response from OpenAPI spec if available
+            const exampleResponse = getExampleFromResponse(c, statusCode, operation.responses);
+            if (exampleResponse !== null) {
+                return c.json(exampleResponse);
+            }
+            return c.json(null);
+        }
+        return c.json(result);
+    }
+    catch (error) {
+        // Log error to console
+        console.error('x-handler execution error:', error);
+        // Return 500 error
+        c.status(500);
+        return c.json({
+            error: 'Handler execution failed',
+            message: error instanceof Error ? error.message : String(error),
+        });
     }
-    return c.json(result);
-  } catch (error) {
-    console.error("x-handler execution error:", error);
-    c.status(500);
-    return c.json({
-      error: "Handler execution failed",
-      message: error instanceof Error ? error.message : String(error)
-    });
-  }
 }
-export {
-  mockHandlerResponse
-};
-//# sourceMappingURL=mock-handler-response.js.map

package/dist/routes/respond-with-authorize-page.js

@@ -1,92 +1,105 @@
-const EXAMPLE_AUTHORIZATION_CODE = "super-secret-token";
-const EXAMPLE_ACCESS_TOKEN = "super-secret-access-token";
+/** Always responds with this code */
+const EXAMPLE_AUTHORIZATION_CODE = 'super-secret-token';
+/** Always responds with this token for implicit flow */
+const EXAMPLE_ACCESS_TOKEN = 'super-secret-access-token';
+/**
+ * Escapes HTML special characters to prevent XSS when rendering user-controlled scope values.
+ */
 function escapeHtml(s) {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
 }
+/**
+ * Parses the OAuth 2.0 scope query parameter (space- or +-separated) into an array of scope strings.
+ */
 function parseScopeParam(scopeQuery) {
-  if (!scopeQuery || scopeQuery.trim() === "") {
-    return [];
-  }
-  return scopeQuery.split(/[\s+]+/).map((s) => s.trim()).filter(Boolean);
+    if (!scopeQuery || scopeQuery.trim() === '') {
+        return [];
+    }
+    return scopeQuery
+        .split(/[\s+]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
 }
-function respondWithAuthorizePage(c, title = "") {
-  const redirectUri = c.req.query("redirect_uri");
-  const responseType = c.req.query("response_type");
-  const scope = c.req.query("scope");
-  const state = c.req.query("state");
-  if (!redirectUri) {
-    return c.html(
-      generateErrorHtml(
-        "Missing redirect_uri parameter",
-        "This parameter is required for the OAuth 2.0 authorization flow to function correctly. Please provide a valid redirect URI in your request."
-      ),
-      400
-    );
-  }
-  try {
-    const redirectUrl = new URL(redirectUri);
-    const isImplicitFlow = responseType === "token";
-    if (isImplicitFlow) {
-      const fragmentParams = new URLSearchParams();
-      fragmentParams.set("access_token", EXAMPLE_ACCESS_TOKEN);
-      fragmentParams.set("token_type", "Bearer");
-      fragmentParams.set("expires_in", "3600");
-      if (scope) {
-        fragmentParams.set("scope", scope);
-      }
-      if (state) {
-        fragmentParams.set("state", state);
-      }
-      redirectUrl.hash = fragmentParams.toString();
-    } else {
-      redirectUrl.searchParams.set("code", EXAMPLE_AUTHORIZATION_CODE);
-      if (state) {
-        redirectUrl.searchParams.set("state", state);
-      }
+/**
+ * Responds with an HTML page that simulates an OAuth 2.0 authorization page.
+ */
+export function respondWithAuthorizePage(c, title = '') {
+    const redirectUri = c.req.query('redirect_uri');
+    const responseType = c.req.query('response_type');
+    const scope = c.req.query('scope');
+    const state = c.req.query('state');
+    if (!redirectUri) {
+        return c.html(generateErrorHtml('Missing redirect_uri parameter', 'This parameter is required for the OAuth 2.0 authorization flow to function correctly. Please provide a valid redirect URI in your request.'), 400);
+    }
+    try {
+        // Validate redirect URI against allowed domains
+        const redirectUrl = new URL(redirectUri);
+        const isImplicitFlow = responseType === 'token';
+        if (isImplicitFlow) {
+            const fragmentParams = new URLSearchParams();
+            fragmentParams.set('access_token', EXAMPLE_ACCESS_TOKEN);
+            fragmentParams.set('token_type', 'Bearer');
+            fragmentParams.set('expires_in', '3600');
+            if (scope) {
+                fragmentParams.set('scope', scope);
+            }
+            if (state) {
+                fragmentParams.set('state', state);
+            }
+            redirectUrl.hash = fragmentParams.toString();
+        }
+        else {
+            redirectUrl.searchParams.set('code', EXAMPLE_AUTHORIZATION_CODE);
+            if (state) {
+                redirectUrl.searchParams.set('state', state);
+            }
+        }
+        const deniedUrl = new URL(redirectUri);
+        if (isImplicitFlow) {
+            const deniedFragmentParams = new URLSearchParams();
+            deniedFragmentParams.set('error', 'access_denied');
+            deniedFragmentParams.set('error_description', 'User has denied the authorization request');
+            if (state) {
+                deniedFragmentParams.set('state', state);
+            }
+            deniedUrl.hash = deniedFragmentParams.toString();
+        }
+        else {
+            if (state) {
+                deniedUrl.searchParams.set('state', state);
+            }
+            deniedUrl.searchParams.set('error', 'access_denied');
+            deniedUrl.searchParams.set('error_description', 'User has denied the authorization request');
+        }
+        const scopes = parseScopeParam(c.req.query('scope'));
+        const htmlContent = generateAuthorizationHtml(redirectUrl.toString(), deniedUrl.toString(), title, scopes);
+        return c.html(htmlContent);
     }
-    const deniedUrl = new URL(redirectUri);
-    if (isImplicitFlow) {
-      const deniedFragmentParams = new URLSearchParams();
-      deniedFragmentParams.set("error", "access_denied");
-      deniedFragmentParams.set("error_description", "User has denied the authorization request");
-      if (state) {
-        deniedFragmentParams.set("state", state);
-      }
-      deniedUrl.hash = deniedFragmentParams.toString();
-    } else {
-      if (state) {
-        deniedUrl.searchParams.set("state", state);
-      }
-      deniedUrl.searchParams.set("error", "access_denied");
-      deniedUrl.searchParams.set("error_description", "User has denied the authorization request");
+    catch {
+        return c.html(generateErrorHtml('Invalid redirect_uri format', 'Please provide a valid URL. The redirect_uri parameter must be a properly formatted URL that includes the protocol (e.g., https://) and a valid domain. This is essential for the OAuth 2.0 flow to securely redirect after authorization.'), 400);
     }
-    const scopes = parseScopeParam(c.req.query("scope"));
-    const htmlContent = generateAuthorizationHtml(redirectUrl.toString(), deniedUrl.toString(), title, scopes);
-    return c.html(htmlContent);
-  } catch {
-    return c.html(
-      generateErrorHtml(
-        "Invalid redirect_uri format",
-        "Please provide a valid URL. The redirect_uri parameter must be a properly formatted URL that includes the protocol (e.g., https://) and a valid domain. This is essential for the OAuth 2.0 flow to securely redirect after authorization."
-      ),
-      400
-    );
-  }
 }
-function generateAuthorizationHtml(redirectUrl, deniedUrl, title = "", scopes = []) {
-  const scopesSection = scopes.length > 0 ? `
+function generateAuthorizationHtml(redirectUrl, deniedUrl, title = '', scopes = []) {
+    const scopesSection = scopes.length > 0
+        ? `
               <p class="font-medium text-gray-700">Requested Scopes</p>
               <ul class="list-disc list-inside space-y-1">
-                ${scopes.map((scope) => `<li><code class="bg-gray-100 py-1 px-2 rounded text-sm">${escapeHtml(scope)}</code></li>`).join("\n                ")}
-              </ul>` : "";
-  return `
+                ${scopes.map((scope) => `<li><code class="bg-gray-100 py-1 px-2 rounded text-sm">${escapeHtml(scope)}</code></li>`).join('\n                ')}
+              </ul>`
+        : '';
+    return `
 <!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>OAuth 2.0 Authorization</title>
-    <script src="https://cdn.tailwindcss.com"><\/script>
+    <script src="https://cdn.tailwindcss.com"></script>
   </head>
   <body class="flex justify-center items-center h-screen bg-gray-100">
 
@@ -134,13 +147,13 @@ function generateAuthorizationHtml(redirectUrl, deniedUrl, title = "", scopes =
   `;
 }
 function generateErrorHtml(title, message) {
-  return `<html>
+    return `<html>
   <html lang="en">
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>OAuth 2.0 Authorization</title>
-    <script src="https://cdn.tailwindcss.com"><\/script>
+    <script src="https://cdn.tailwindcss.com"></script>
   </head>
   <body>
     <div class="p-4 m-8 flex flex-col gap-4 text-lg">
@@ -157,7 +170,3 @@ function generateErrorHtml(title, message) {
   </body>
 </html>`;
 }
-export {
-  respondWithAuthorizePage
-};
-//# sourceMappingURL=respond-with-authorize-page.js.map

package/dist/routes/respond-with-openapi-document.js

@@ -1,39 +1,36 @@
-import { normalize, toYaml } from "@scalar/openapi-parser";
-function respondWithOpenApiDocument(c, input, format = "json") {
-  if (!input) {
-    return c.text("Not found", 404);
-  }
-  try {
-    const document = normalize(input);
-    if (format === "json") {
-      return c.json(document);
+import { normalize, toYaml } from '@scalar/openapi-parser';
+/**
+ * OpenAPI endpoints
+ */
+export function respondWithOpenApiDocument(c, input, format = 'json') {
+    if (!input) {
+        return c.text('Not found', 404);
     }
     try {
-      const yamlDocument = toYaml(normalize(document));
-      c.header("Content-Type", "text/yaml");
-      return c.text(yamlDocument, 200, {
-        "Content-Type": "application/yaml; charset=UTF-8"
-      });
-    } catch (error) {
-      return c.json(
-        {
-          error: "Failed to convert document to YAML",
-          message: error instanceof Error ? error.message : "Unknown error occurred"
-        },
-        500
-      );
+        const document = normalize(input);
+        // JSON
+        if (format === 'json') {
+            return c.json(document);
+        }
+        // YAML
+        try {
+            const yamlDocument = toYaml(normalize(document));
+            c.header('Content-Type', 'text/yaml');
+            return c.text(yamlDocument, 200, {
+                'Content-Type': 'application/yaml; charset=UTF-8',
+            });
+        }
+        catch (error) {
+            return c.json({
+                error: 'Failed to convert document to YAML',
+                message: error instanceof Error ? error.message : 'Unknown error occurred',
+            }, 500);
+        }
+    }
+    catch (error) {
+        return c.json({
+            error: 'Failed to parse OpenAPI document',
+            message: error instanceof Error ? error.message : 'Unknown error occurred',
+        }, 400);
     }
-  } catch (error) {
-    return c.json(
-      {
-        error: "Failed to parse OpenAPI document",
-        message: error instanceof Error ? error.message : "Unknown error occurred"
-      },
-      400
-    );
-  }
 }
-export {
-  respondWithOpenApiDocument
-};
-//# sourceMappingURL=respond-with-openapi-document.js.map

package/dist/routes/respond-with-token.js

@@ -1,46 +1,41 @@
-const EXAMPLE_ACCESS_TOKEN = "super-secret-access-token";
-function respondWithToken(c) {
-  const grantType = c.req.query("grant_type");
-  if (!grantType) {
-    return c.json(
-      {
-        error: "invalid_request",
-        error_description: "Missing grant_type parameter"
-      },
-      400
-    );
-  }
-  const supportedGrantTypes = ["authorization_code", "client_credentials", "refresh_token"];
-  if (!supportedGrantTypes.includes(grantType)) {
-    return c.json(
-      {
-        error: "unsupported_grant_type",
-        error_description: `Grant type must be one of: ${supportedGrantTypes.join(", ")}`
-      },
-      400
-    );
-  }
-  if (grantType === "authorization_code" && !c.req.query("code")) {
-    return c.json(
-      {
-        error: "invalid_request",
-        error_description: "Missing code parameter"
-      },
-      400
-    );
-  }
-  const tokenResponse = {
-    access_token: EXAMPLE_ACCESS_TOKEN,
-    token_type: "Bearer",
-    expires_in: 3600,
-    refresh_token: "example-refresh-token",
-    scope: c.req.query("scope") ?? "read write"
-  };
-  c.header("Cache-Control", "no-store");
-  c.header("Pragma", "no-cache");
-  return c.json(tokenResponse);
+/** Always responds with this token */
+const EXAMPLE_ACCESS_TOKEN = 'super-secret-access-token';
+/**
+ * Responds with a JSON object simulating an OAuth 2.0 token response.
+ */
+export function respondWithToken(c) {
+    const grantType = c.req.query('grant_type');
+    if (!grantType) {
+        return c.json({
+            error: 'invalid_request',
+            error_description: 'Missing grant_type parameter',
+        }, 400);
+    }
+    // Validate supported grant types
+    const supportedGrantTypes = ['authorization_code', 'client_credentials', 'refresh_token'];
+    if (!supportedGrantTypes.includes(grantType)) {
+        return c.json({
+            error: 'unsupported_grant_type',
+            error_description: `Grant type must be one of: ${supportedGrantTypes.join(', ')}`,
+        }, 400);
+    }
+    // Validate required parameters for each grant type
+    if (grantType === 'authorization_code' && !c.req.query('code')) {
+        return c.json({
+            error: 'invalid_request',
+            error_description: 'Missing code parameter',
+        }, 400);
+    }
+    // Simulate token generation
+    const tokenResponse = {
+        access_token: EXAMPLE_ACCESS_TOKEN,
+        token_type: 'Bearer',
+        expires_in: 3600,
+        refresh_token: 'example-refresh-token',
+        scope: c.req.query('scope') ?? 'read write',
+    };
+    // Security headers
+    c.header('Cache-Control', 'no-store');
+    c.header('Pragma', 'no-cache');
+    return c.json(tokenResponse);
 }
-export {
-  respondWithToken
-};
-//# sourceMappingURL=respond-with-token.js.map

package/dist/types.js

@@ -1,5 +1,2 @@
-const httpMethods = ["get", "put", "post", "delete", "options", "patch"];
-export {
-  httpMethods
-};
-//# sourceMappingURL=types.js.map
+/** Available HTTP methods for Hono routes */
+export const httpMethods = ['get', 'put', 'post', 'delete', 'options', 'patch'];