@scalar/workspace-store 0.40.2 → 0.40.4

package/dist/mutators/operation/helpers/fetch-response-to-har.js

@@ -1,104 +1,152 @@
-const fetchResponseToHar = async ({
-  response,
-  includeBody = true,
-  httpVersion = "HTTP/1.1",
-  bodySizeLimit = 1048576
-}) => {
-  const { headers, headersSize, cookies } = processResponseHeaders(response);
-  const redirectURL = response.headers.get("location") || "";
-  const contentType = response.headers.get("content-type") ?? "text/plain";
-  const bodyDetails = await (async () => {
-    if (includeBody && response.body) {
-      const details = await processResponseBody(response.clone());
-      if (details.size <= bodySizeLimit) {
-        return details;
-      }
-    }
-    return { text: "", size: -1, encoding: void 0 };
-  })();
-  const harResponse = {
-    status: response.status,
-    statusText: response.statusText,
-    httpVersion,
-    headers,
-    cookies,
-    content: {
-      size: bodyDetails.size,
-      mimeType: contentType,
-      text: bodyDetails.text,
-      encoding: bodyDetails.encoding
-    },
-    redirectURL,
-    headersSize,
-    bodySize: bodyDetails.size
-  };
-  return harResponse;
+/**
+ * Converts a Fetch API Response object to HAR (HTTP Archive) Response format.
+ *
+ * This function transforms a standard JavaScript Fetch API Response into the
+ * HAR format, which is useful for:
+ * - Recording HTTP responses for replay or analysis
+ * - Creating test fixtures from real API responses
+ * - Debugging and monitoring HTTP traffic
+ * - Generating API documentation from real responses
+ *
+ * The conversion handles:
+ * - Response status and status text
+ * - Headers extraction (including Set-Cookie headers converted to cookies)
+ * - Response body reading (with automatic cloning to preserve the original)
+ * - Content-Type detection and MIME type extraction
+ * - Size calculations for headers and body
+ * - Redirect URL extraction from Location header
+ *
+ * Note: The Fetch API does not expose the HTTP version, so it defaults to HTTP/1.1
+ * unless specified otherwise.
+ *
+ * @see https://w3c.github.io/web-performance/specs/HAR/Overview.html
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Response
+ *
+ * @example
+ * const response = await fetch('https://api.example.com/users')
+ * const harResponse = await fetchResponseToHar({ response })
+ * console.log(harResponse.status) // 200
+ */
+export const fetchResponseToHar = async ({ response, includeBody = true, httpVersion = 'HTTP/1.1', bodySizeLimit = 1048576, }) => {
+    // Extract the headers from the response
+    const { headers, headersSize, cookies } = processResponseHeaders(response);
+    // Extract redirect URL from Location header
+    const redirectURL = response.headers.get('location') || '';
+    // Get content type
+    const contentType = response.headers.get('content-type') ?? 'text/plain';
+    // Read the response body if requested
+    const bodyDetails = await (async () => {
+        if (includeBody && response.body) {
+            const details = await processResponseBody(response.clone());
+            if (details.size <= bodySizeLimit) {
+                return details;
+            }
+        }
+        return { text: '', size: -1, encoding: undefined };
+    })();
+    // Create the HAR response object
+    const harResponse = {
+        status: response.status,
+        statusText: response.statusText,
+        httpVersion,
+        headers,
+        cookies,
+        content: {
+            size: bodyDetails.size,
+            mimeType: contentType,
+            text: bodyDetails.text,
+            encoding: bodyDetails.encoding,
+        },
+        redirectURL,
+        headersSize,
+        bodySize: bodyDetails.size,
+    };
+    return harResponse;
 };
 const processResponseHeaders = (response) => {
-  return Array.from(response.headers.entries()).reduce(
-    (acc, [name, value]) => {
-      acc.headers.push({ name, value });
-      acc.headersSize += name.length + 2 + value.length + 2;
-      if (name.toLowerCase() === "set-cookie") {
-        const cookie = parseSetCookieHeader(value);
-        if (cookie) {
-          acc.cookies.push(cookie);
+    return Array.from(response.headers.entries()).reduce((acc, [name, value]) => {
+        acc.headers.push({ name, value });
+        acc.headersSize += name.length + 2 + value.length + 2;
+        // Parse Set-Cookie headers into cookies array
+        if (name.toLowerCase() === 'set-cookie') {
+            const cookie = parseSetCookieHeader(value);
+            if (cookie) {
+                acc.cookies.push(cookie);
+            }
         }
-      }
-      return acc;
-    },
-    { headers: [], headersSize: 0, cookies: [] }
-  );
+        return acc;
+    }, { headers: [], headersSize: 0, cookies: [] });
 };
 const processResponseBody = async (response) => {
-  const contentType = response.headers.get("content-type");
-  if (!contentType || !isTextBasedContent(contentType)) {
-    return { text: "", size: -1, encoding: void 0 };
-  }
-  try {
-    const arrayBuffer = await response.arrayBuffer();
-    const bodySize = arrayBuffer.byteLength;
-    const text = new TextDecoder("utf-8").decode(arrayBuffer);
-    return { text, size: bodySize, encoding: void 0 };
-  } catch {
-    return { text: "", size: -1, encoding: void 0 };
-  }
+    const contentType = response.headers.get('content-type');
+    if (!contentType || !isTextBasedContent(contentType)) {
+        return { text: '', size: -1, encoding: undefined };
+    }
+    try {
+        // Read as ArrayBuffer to get the size
+        const arrayBuffer = await response.arrayBuffer();
+        const bodySize = arrayBuffer.byteLength;
+        const text = new TextDecoder('utf-8').decode(arrayBuffer);
+        return { text, size: bodySize, encoding: undefined };
+    }
+    catch {
+        // If body cannot be read, leave it empty
+        return { text: '', size: -1, encoding: undefined };
+    }
 };
-const isTextBasedContent = (contentType) => {
-  const lowerContentType = contentType.toLowerCase();
-  if (lowerContentType.startsWith("text/")) {
-    return true;
-  }
-  if (lowerContentType.includes("application/json") || lowerContentType.includes("+json")) {
-    return true;
-  }
-  if (lowerContentType.includes("application/xml") || lowerContentType.includes("text/xml") || lowerContentType.includes("+xml")) {
-    return true;
-  }
-  if (lowerContentType.includes("application/javascript") || lowerContentType.includes("application/x-javascript")) {
-    return true;
-  }
-  if (lowerContentType.includes("application/x-www-form-urlencoded") || lowerContentType.includes("application/graphql")) {
-    return true;
-  }
-  return false;
+/**
+ * Checks if the content type is text-based and should be included in HAR.
+ * Text-based content types include:
+ * - text/* (text/plain, text/html, text/css, etc.)
+ * - application/json
+ * - application/xml and text/xml
+ * - application/javascript
+ * - application/*+json and application/*+xml variants
+ */
+export const isTextBasedContent = (contentType) => {
+    const lowerContentType = contentType.toLowerCase();
+    // Check for text/* types
+    if (lowerContentType.startsWith('text/')) {
+        return true;
+    }
+    // Check for JSON types
+    if (lowerContentType.includes('application/json') || lowerContentType.includes('+json')) {
+        return true;
+    }
+    // Check for XML types
+    if (lowerContentType.includes('application/xml') ||
+        lowerContentType.includes('text/xml') ||
+        lowerContentType.includes('+xml')) {
+        return true;
+    }
+    // Check for JavaScript
+    if (lowerContentType.includes('application/javascript') || lowerContentType.includes('application/x-javascript')) {
+        return true;
+    }
+    // Check for common text-based formats
+    if (lowerContentType.includes('application/x-www-form-urlencoded') ||
+        lowerContentType.includes('application/graphql')) {
+        return true;
+    }
+    return false;
 };
+/**
+ * Parses a Set-Cookie header value into a cookie object.
+ * This is a simplified parser that extracts the name and value.
+ * For full cookie parsing with attributes, a more robust parser would be needed.
+ */
 const parseSetCookieHeader = (setCookieValue) => {
-  const parts = setCookieValue.split(";");
-  if (parts.length === 0 || !parts[0]) {
-    return null;
-  }
-  const cookiePart = parts[0].trim();
-  const equalIndex = cookiePart.indexOf("=");
-  if (equalIndex === -1) {
-    return null;
-  }
-  const name = cookiePart.substring(0, equalIndex).trim();
-  const value = cookiePart.substring(equalIndex + 1).trim();
-  return { name, value };
-};
-export {
-  fetchResponseToHar,
-  isTextBasedContent
+    // Set-Cookie format: name=value; attribute1=value1; attribute2=value2
+    const parts = setCookieValue.split(';');
+    if (parts.length === 0 || !parts[0]) {
+        return null;
+    }
+    const cookiePart = parts[0].trim();
+    const equalIndex = cookiePart.indexOf('=');
+    if (equalIndex === -1) {
+        return null;
+    }
+    const name = cookiePart.substring(0, equalIndex).trim();
+    const value = cookiePart.substring(equalIndex + 1).trim();
+    return { name, value };
 };
-//# sourceMappingURL=fetch-response-to-har.js.map

package/dist/mutators/operation/helpers/get-parameter-position.js

@@ -1,14 +1,14 @@
-const getParameterPositions = (path, parameters) => {
-  const positions = {};
-  for (const paramName of parameters) {
-    const position = path.indexOf(`{${paramName}}`);
-    if (position !== -1) {
-      positions[paramName] = position;
+/**
+ * Creates a map of parameter names to their character positions in a path.
+ * Used to detect renamed path parameters by position matching.
+ */
+export const getParameterPositions = (path, parameters) => {
+    const positions = {};
+    for (const paramName of parameters) {
+        const position = path.indexOf(`{${paramName}}`);
+        if (position !== -1) {
+            positions[paramName] = position;
+        }
     }
-  }
-  return positions;
+    return positions;
 };
-export {
-  getParameterPositions
-};
-//# sourceMappingURL=get-parameter-position.js.map

package/dist/mutators/operation/helpers/har-to-operation.js

@@ -1,146 +1,183 @@
-import { getResolvedRef } from "@scalar/workspace-store/helpers/get-resolved-ref";
-import { isContentTypeParameterObject } from "../../../schemas/v3.1/strict/type-guards.js";
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { isContentTypeParameterObject } from '../../../schemas/v3.1/strict/type-guards.js';
 const preprocessParameters = (parameters, pathVariables, exampleKey) => {
-  parameters.forEach((param) => {
-    const resolvedParam = getResolvedRef(param);
-    if (isContentTypeParameterObject(resolvedParam)) {
-      return;
-    }
-    setParameterDisabled(getResolvedRef(param), exampleKey, true);
-    if (resolvedParam.in === "path") {
-      resolvedParam.examples ||= {};
-      resolvedParam.examples[exampleKey] = {
-        value: pathVariables[resolvedParam.name] ?? "",
-        "x-disabled": false
-      };
-    }
-  });
+    parameters.forEach((param) => {
+        const resolvedParam = getResolvedRef(param);
+        if (isContentTypeParameterObject(resolvedParam)) {
+            return;
+        }
+        setParameterDisabled(getResolvedRef(param), exampleKey, true);
+        if (resolvedParam.in === 'path') {
+            resolvedParam.examples ||= {};
+            resolvedParam.examples[exampleKey] = {
+                value: pathVariables[resolvedParam.name] ?? '',
+                'x-disabled': false,
+            };
+        }
+    });
 };
-const harToOperation = ({
-  harRequest,
-  exampleKey,
-  baseOperation = {},
-  pathVariables = {}
-}) => {
-  if (!baseOperation.parameters) {
-    baseOperation.parameters = [];
-  }
-  preprocessParameters(baseOperation.parameters, pathVariables, exampleKey);
-  if (harRequest.queryString && harRequest.queryString.length > 0) {
-    for (const queryParam of harRequest.queryString) {
-      const param = findOrCreateParameter(baseOperation.parameters, queryParam.name, "query");
-      if (!param || isContentTypeParameterObject(param)) {
-        continue;
-      }
-      param.examples ||= {};
-      param.examples[exampleKey] = {
-        value: queryParam.value,
-        "x-disabled": false
-      };
+/**
+ * Converts a HAR request back to an OpenAPI Operation object with populated examples.
+ *
+ * This function is the reverse of operationToHar - it takes a HAR request and
+ * converts it back into an OpenAPI operation structure, populating the example
+ * values based on the HAR request data.
+ *
+ * The conversion handles:
+ * - URL parsing to extract path and query parameters
+ * - Header extraction and mapping to operation parameters
+ * - Query string parsing and mapping to parameters
+ * - Cookie extraction and mapping to cookie parameters
+ * - Request body extraction and mapping to requestBody with examples
+ * - Content-Type detection and media type assignment
+ *
+ * Note: This function focuses on populating examples and does not reconstruct
+ * schema definitions. If you need full schema generation, consider combining
+ * this with a schema inference tool.
+ *
+ * @see https://w3c.github.io/web-performance/specs/HAR/Overview.html
+ * @see https://spec.openapis.org/oas/v3.1.0#operation-object
+ */
+export const harToOperation = ({ harRequest, exampleKey, baseOperation = {}, pathVariables = {}, }) => {
+    // Ensure parameters array exists on the base operation
+    if (!baseOperation.parameters) {
+        baseOperation.parameters = [];
     }
-  }
-  if (harRequest.headers && harRequest.headers.length > 0) {
-    for (const header of harRequest.headers) {
-      const param = findOrCreateParameter(baseOperation.parameters, header.name, "header");
-      if (!param || isContentTypeParameterObject(param)) {
-        continue;
-      }
-      param.examples ||= {};
-      param.examples[exampleKey] = {
-        value: header.value,
-        "x-disabled": false
-      };
-    }
-  }
-  if (harRequest.cookies && harRequest.cookies.length > 0) {
-    for (const cookie of harRequest.cookies) {
-      const param = findOrCreateParameter(baseOperation.parameters, cookie.name, "cookie");
-      if (!param || isContentTypeParameterObject(param)) {
-        continue;
-      }
-      param.examples ||= {};
-      param.examples[exampleKey] = {
-        value: cookie.value,
-        "x-disabled": false
-      };
-    }
-  }
-  if (harRequest.postData) {
-    const { mimeType, text, params } = harRequest.postData;
-    if (!baseOperation.requestBody) {
-      baseOperation.requestBody = {
-        content: {}
-      };
+    // Set any other parameters as disabled and set the path variables
+    preprocessParameters(baseOperation.parameters, pathVariables, exampleKey);
+    // Process query string parameters from the HAR request
+    if (harRequest.queryString && harRequest.queryString.length > 0) {
+        for (const queryParam of harRequest.queryString) {
+            const param = findOrCreateParameter(baseOperation.parameters, queryParam.name, 'query');
+            if (!param || isContentTypeParameterObject(param)) {
+                continue;
+            }
+            param.examples ||= {};
+            param.examples[exampleKey] = {
+                value: queryParam.value,
+                'x-disabled': false,
+            };
+        }
     }
-    const requestBody = getResolvedRef(baseOperation.requestBody);
-    if (!requestBody.content[mimeType]) {
-      requestBody.content[mimeType] = {
-        schema: {
-          type: "object"
+    // Process headers from the HAR request
+    if (harRequest.headers && harRequest.headers.length > 0) {
+        for (const header of harRequest.headers) {
+            const param = findOrCreateParameter(baseOperation.parameters, header.name, 'header');
+            if (!param || isContentTypeParameterObject(param)) {
+                continue;
+            }
+            param.examples ||= {};
+            param.examples[exampleKey] = {
+                value: header.value,
+                'x-disabled': false,
+            };
         }
-      };
     }
-    const mediaType = requestBody.content[mimeType];
-    if (!mediaType) {
-      return baseOperation;
+    // Process cookies from the HAR request
+    if (harRequest.cookies && harRequest.cookies.length > 0) {
+        for (const cookie of harRequest.cookies) {
+            const param = findOrCreateParameter(baseOperation.parameters, cookie.name, 'cookie');
+            if (!param || isContentTypeParameterObject(param)) {
+                continue;
+            }
+            param.examples ||= {};
+            param.examples[exampleKey] = {
+                value: cookie.value,
+                'x-disabled': false,
+            };
+        }
     }
-    mediaType.examples ||= {};
-    let exampleValue;
-    if (params && params.length > 0) {
-      exampleValue = [];
-      for (const param of params) {
-        exampleValue.push({
-          name: param.name,
-          value: param.value,
-          "x-disabled": false
-        });
-      }
-    } else {
-      exampleValue = text;
+    // Process request body from the HAR request
+    if (harRequest.postData) {
+        const { mimeType, text, params } = harRequest.postData;
+        // Ensure requestBody exists on the base operation
+        if (!baseOperation.requestBody) {
+            baseOperation.requestBody = {
+                content: {},
+            };
+        }
+        // Resolve the request body in case it is a reference
+        const requestBody = getResolvedRef(baseOperation.requestBody);
+        // Ensure the content type exists in the requestBody
+        if (!requestBody.content[mimeType]) {
+            requestBody.content[mimeType] = {
+                schema: {
+                    type: 'object',
+                },
+            };
+        }
+        // Get the media type object
+        const mediaType = requestBody.content[mimeType];
+        if (!mediaType) {
+            return baseOperation;
+        }
+        // Ensure examples object exists
+        mediaType.examples ||= {};
+        // Convert the HAR postData to an example value
+        let exampleValue;
+        // If params exist (form data), convert to array
+        if (params && params.length > 0) {
+            exampleValue = [];
+            for (const param of params) {
+                exampleValue.push({
+                    name: param.name,
+                    value: param.value,
+                    'x-disabled': false,
+                });
+            }
+        }
+        else {
+            exampleValue = text;
+        }
+        // Add the example to the media type
+        mediaType.examples[exampleKey] = {
+            value: exampleValue,
+            'x-disabled': false,
+        };
+        // Update the selected media type
+        requestBody['x-scalar-selected-content-type'] ||= {};
+        requestBody['x-scalar-selected-content-type'][exampleKey] = mimeType;
     }
-    mediaType.examples[exampleKey] = {
-      value: exampleValue,
-      "x-disabled": false
-    };
-    requestBody["x-scalar-selected-content-type"] ||= {};
-    requestBody["x-scalar-selected-content-type"][exampleKey] = mimeType;
-  }
-  return baseOperation;
+    return baseOperation;
 };
 const setParameterDisabled = (param, exampleKey, disabled) => {
-  if (isContentTypeParameterObject(param)) {
-    return;
-  }
-  if (!param.examples?.[exampleKey]) {
-    return;
-  }
-  getResolvedRef(param.examples[exampleKey])["x-disabled"] = disabled;
-};
-const findOrCreateParameter = (parameters, name, inValue) => {
-  for (const param of parameters) {
-    const resolved = getResolvedRef(param);
-    if (isContentTypeParameterObject(resolved)) {
-      continue;
+    if (isContentTypeParameterObject(param)) {
+        return;
     }
-    if (resolved.in !== inValue) {
-      continue;
+    if (!param.examples?.[exampleKey]) {
+        return;
     }
-    const namesMatch = inValue === "header" ? resolved.name.toLowerCase() === name.toLowerCase() : resolved.name === name;
-    if (namesMatch) {
-      return resolved;
-    }
-  }
-  const newParam = {
-    name,
-    in: inValue,
-    schema: {
-      type: "string"
-    }
-  };
-  parameters.push(newParam);
-  return newParam;
+    getResolvedRef(param.examples[exampleKey])['x-disabled'] = disabled;
 };
-export {
-  harToOperation
+/**
+ * Finds an existing parameter in the parameters array or creates a new one.
+ * This ensures we do not create duplicate parameters.
+ */
+const findOrCreateParameter = (parameters, name, inValue) => {
+    // Try to find existing parameter using getResolvedRef to handle references
+    for (const param of parameters) {
+        const resolved = getResolvedRef(param);
+        if (isContentTypeParameterObject(resolved)) {
+            continue;
+        }
+        // Check if parameter location matches
+        if (resolved.in !== inValue) {
+            continue;
+        }
+        // For headers, use case-insensitive comparison; otherwise use exact match
+        const namesMatch = inValue === 'header' ? resolved.name.toLowerCase() === name.toLowerCase() : resolved.name === name;
+        if (namesMatch) {
+            return resolved;
+        }
+    }
+    // Create new parameter with schema
+    const newParam = {
+        name,
+        in: inValue,
+        schema: {
+            type: 'string',
+        },
+    };
+    parameters.push(newParam);
+    return newParam;
 };
-//# sourceMappingURL=har-to-operation.js.map