@scalar/postman-to-openapi 0.5.2 → 0.5.3

package/dist/helpers/path-items.js

@@ -1,218 +1,260 @@
-import { processAuth } from "./auth.js";
-import { parseMdTable } from "./markdown.js";
-import { extractParameters } from "./parameters.js";
-import { processPostResponseScripts } from "./post-response-scripts.js";
-import { processPreRequestScripts } from "./pre-request-scripts.js";
-import { extractRequestBody } from "./request-body.js";
-import { extractResponses } from "./responses.js";
-import { extractPathFromUrl, extractPathParameterNames, extractServerFromUrl, normalizePath } from "./urls.js";
+import { processAuth } from './auth.js';
+import { parseMdTable } from './markdown.js';
+import { extractParameters } from './parameters.js';
+import { processPostResponseScripts } from './post-response-scripts.js';
+import { processPreRequestScripts } from './pre-request-scripts.js';
+import { extractRequestBody } from './request-body.js';
+import { extractResponses } from './responses.js';
+import { extractPathFromUrl, extractPathParameterNames, extractServerFromUrl, normalizePath } from './urls.js';
 function ensureRequestBodyContent(requestBody) {
-  const content = requestBody.content ?? {};
-  if (Object.keys(content).length === 0) {
-    requestBody.content = {
-      "text/plain": {}
-    };
-    return;
-  }
-  if ("text/plain" in content) {
-    const textContent = content["text/plain"];
-    if (!textContent?.schema || textContent.schema && Object.keys(textContent.schema).length === 0) {
-      content["text/plain"] = {};
-    }
-  }
+    const content = requestBody.content ?? {};
+    if (Object.keys(content).length === 0) {
+        requestBody.content = {
+            'text/plain': {},
+        };
+        return;
+    }
+    if ('text/plain' in content) {
+        const textContent = content['text/plain'];
+        if (!textContent?.schema || (textContent.schema && Object.keys(textContent.schema).length === 0)) {
+            content['text/plain'] = {};
+        }
+    }
 }
-function processItem(item, parentTags = [], parentPath = "") {
-  const paths = {};
-  const components = {};
-  const serverUsage = [];
-  if ("item" in item && Array.isArray(item.item)) {
-    const newParentTags = item.name ? [...parentTags, item.name] : parentTags;
-    item.item.forEach((childItem) => {
-      const childResult = processItem(childItem, newParentTags, `${parentPath}/${item.name || ""}`);
-      for (const [pathKey, pathItem2] of Object.entries(childResult.paths)) {
-        if (!paths[pathKey]) {
-          paths[pathKey] = pathItem2;
-        } else {
-          paths[pathKey] = {
-            ...paths[pathKey],
-            ...pathItem2
-          };
+/**
+ * Processes a Postman collection item or item group and returns
+ * the corresponding OpenAPI paths and components.
+ * Handles nested item groups, extracts request details, and generates corresponding
+ * OpenAPI path items and operations.
+ */
+export function processItem(item, parentTags = [], parentPath = '') {
+    const paths = {};
+    const components = {};
+    const serverUsage = [];
+    if ('item' in item && Array.isArray(item.item)) {
+        const newParentTags = item.name ? [...parentTags, item.name] : parentTags;
+        item.item.forEach((childItem) => {
+            const childResult = processItem(childItem, newParentTags, `${parentPath}/${item.name || ''}`);
+            // Merge child paths and components
+            for (const [pathKey, pathItem] of Object.entries(childResult.paths)) {
+                if (!paths[pathKey]) {
+                    paths[pathKey] = pathItem;
+                }
+                else {
+                    paths[pathKey] = {
+                        ...paths[pathKey],
+                        ...pathItem,
+                    };
+                }
+            }
+            // Merge components.securitySchemes
+            if (childResult.components.securitySchemes) {
+                components.securitySchemes = {
+                    ...components.securitySchemes,
+                    ...childResult.components.securitySchemes,
+                };
+            }
+            // Merge server usage
+            serverUsage.push(...childResult.serverUsage);
+        });
+        return { paths, components, serverUsage };
+    }
+    if (!('request' in item)) {
+        return { paths, components, serverUsage };
+    }
+    const { request, name, response } = item;
+    const method = (typeof request === 'string' ? 'get' : request.method || 'get').toLowerCase();
+    const requestUrl = typeof request === 'string' ? request : typeof request.url === 'string' ? request.url : (request.url?.raw ?? '');
+    const path = extractPathFromUrl(requestUrl);
+    // Normalize path parameters from ':param' to '{param}'
+    const normalizedPath = normalizePath(path);
+    // Extract server URL from request URL
+    const serverUrl = extractServerFromUrl(requestUrl);
+    if (serverUrl) {
+        serverUsage.push({
+            serverUrl,
+            path: normalizedPath,
+            method,
+        });
+    }
+    // Extract path parameter names
+    const pathParameterNames = extractPathParameterNames(normalizedPath);
+    // Extract operation ID if present
+    const { operationId, summary } = extractOperationInfo(name);
+    const description = typeof request === 'string'
+        ? ''
+        : typeof request.description === 'string'
+            ? request.description
+            : (request.description?.content ?? '');
+    const operationObject = {
+        tags: parentTags.length > 0 ? [parentTags.join(' > ')] : undefined,
+        summary,
+        description,
+        responses: extractResponses(response || [], item),
+        parameters: [],
+    };
+    // Add pre-request scripts if present
+    const preRequestScript = processPreRequestScripts(item.event);
+    if (preRequestScript) {
+        operationObject['x-pre-request'] = preRequestScript;
+    }
+    // Add post-response scripts if present
+    const postResponseScript = processPostResponseScripts(item.event);
+    if (postResponseScript) {
+        operationObject['x-post-response'] = postResponseScript;
+    }
+    // Only add operationId if it was explicitly provided
+    if (operationId) {
+        operationObject.operationId = operationId;
+    }
+    // Extract parameters from the request (query, path, header)
+    // This should always happen, regardless of whether a description exists
+    const extractedParameters = extractParameters(request);
+    // Merge parameters, giving priority to those from the Markdown table if description exists
+    const mergedParameters = new Map();
+    // Add extracted parameters, filtering out path parameters not in the path
+    extractedParameters.forEach((param) => {
+        if (param.name) {
+            if (param.in === 'path' && !pathParameterNames.includes(param.name)) {
+                return;
+            }
+            mergedParameters.set(param.name, param);
+        }
+    });
+    // Parse parameters from the description's Markdown table if description exists
+    if (operationObject.description) {
+        const { descriptionWithoutTable, parametersFromTable } = parseParametersFromDescription(operationObject.description);
+        operationObject.description = descriptionWithoutTable.trim();
+        // Add parameters from table, filtering out path parameters not in the path
+        // These take priority over extracted parameters
+        parametersFromTable.forEach((param) => {
+            if (param.name) {
+                if (param.in === 'path' && !pathParameterNames.includes(param.name)) {
+                    return;
+                }
+                mergedParameters.set(param.name, param);
+            }
+        });
+    }
+    // Set parameters if we have any
+    if (mergedParameters.size > 0) {
+        operationObject.parameters = Array.from(mergedParameters.values());
+    }
+    if (typeof request !== 'string' && request.auth) {
+        if (!operationObject.security) {
+            operationObject.security = [];
+        }
+        const { securitySchemes, security } = processAuth(request.auth);
+        if (!components.securitySchemes) {
+            components.securitySchemes = {};
         }
-      }
-      if (childResult.components.securitySchemes) {
         components.securitySchemes = {
-          ...components.securitySchemes,
-          ...childResult.components.securitySchemes
+            ...components.securitySchemes,
+            ...securitySchemes,
         };
-      }
-      serverUsage.push(...childResult.serverUsage);
-    });
-    return { paths, components, serverUsage };
-  }
-  if (!("request" in item)) {
-    return { paths, components, serverUsage };
-  }
-  const { request, name, response } = item;
-  const method = (typeof request === "string" ? "get" : request.method || "get").toLowerCase();
-  const requestUrl = typeof request === "string" ? request : typeof request.url === "string" ? request.url : request.url?.raw ?? "";
-  const path = extractPathFromUrl(requestUrl);
-  const normalizedPath = normalizePath(path);
-  const serverUrl = extractServerFromUrl(requestUrl);
-  if (serverUrl) {
-    serverUsage.push({
-      serverUrl,
-      path: normalizedPath,
-      method
-    });
-  }
-  const pathParameterNames = extractPathParameterNames(normalizedPath);
-  const { operationId, summary } = extractOperationInfo(name);
-  const description = typeof request === "string" ? "" : typeof request.description === "string" ? request.description : request.description?.content ?? "";
-  const operationObject = {
-    tags: parentTags.length > 0 ? [parentTags.join(" > ")] : void 0,
-    summary,
-    description,
-    responses: extractResponses(response || [], item),
-    parameters: []
-  };
-  const preRequestScript = processPreRequestScripts(item.event);
-  if (preRequestScript) {
-    operationObject["x-pre-request"] = preRequestScript;
-  }
-  const postResponseScript = processPostResponseScripts(item.event);
-  if (postResponseScript) {
-    operationObject["x-post-response"] = postResponseScript;
-  }
-  if (operationId) {
-    operationObject.operationId = operationId;
-  }
-  const extractedParameters = extractParameters(request);
-  const mergedParameters = /* @__PURE__ */ new Map();
-  extractedParameters.forEach((param) => {
-    if (param.name) {
-      if (param.in === "path" && !pathParameterNames.includes(param.name)) {
-        return;
-      }
-      mergedParameters.set(param.name, param);
-    }
-  });
-  if (operationObject.description) {
-    const { descriptionWithoutTable, parametersFromTable } = parseParametersFromDescription(operationObject.description);
-    operationObject.description = descriptionWithoutTable.trim();
-    parametersFromTable.forEach((param) => {
-      if (param.name) {
-        if (param.in === "path" && !pathParameterNames.includes(param.name)) {
-          return;
+        operationObject.security.push(...security);
+    }
+    // Allow request bodies for all methods (including GET) if body is present
+    if (typeof request !== 'string' && request.body) {
+        const requestBody = extractRequestBody(request.body);
+        ensureRequestBodyContent(requestBody);
+        // Only add requestBody if it has content
+        if (requestBody.content && Object.keys(requestBody.content).length > 0) {
+            operationObject.requestBody = requestBody;
         }
-        mergedParameters.set(param.name, param);
-      }
-    });
-  }
-  if (mergedParameters.size > 0) {
-    operationObject.parameters = Array.from(mergedParameters.values());
-  }
-  if (typeof request !== "string" && request.auth) {
-    if (!operationObject.security) {
-      operationObject.security = [];
-    }
-    const { securitySchemes, security } = processAuth(request.auth);
-    if (!components.securitySchemes) {
-      components.securitySchemes = {};
-    }
-    components.securitySchemes = {
-      ...components.securitySchemes,
-      ...securitySchemes
-    };
-    operationObject.security.push(...security);
-  }
-  if (typeof request !== "string" && request.body) {
-    const requestBody = extractRequestBody(request.body);
-    ensureRequestBodyContent(requestBody);
-    if (requestBody.content && Object.keys(requestBody.content).length > 0) {
-      operationObject.requestBody = requestBody;
-    }
-  }
-  if (!paths[path]) {
-    paths[path] = {};
-  }
-  const pathItem = paths[path];
-  pathItem[method] = operationObject;
-  return { paths, components, serverUsage };
+    }
+    if (!paths[path]) {
+        paths[path] = {};
+    }
+    const pathItem = paths[path];
+    pathItem[method] = operationObject;
+    return { paths, components, serverUsage };
 }
-const OPENAPI_PARAM_SCHEMA_TYPES = ["string", "number", "integer", "boolean", "object", "array"];
+/** OpenAPI 3.1 parameter schema types (ParameterObject uses OpenAPIV3_1). */
+const OPENAPI_PARAM_SCHEMA_TYPES = ['string', 'number', 'integer', 'boolean', 'object', 'array'];
 function toOpenApiParamSchemaType(s) {
-  const value = s ?? "string";
-  for (const t of OPENAPI_PARAM_SCHEMA_TYPES) {
-    if (t === value) return t;
-  }
-  return "string";
+    const value = s ?? 'string';
+    for (const t of OPENAPI_PARAM_SCHEMA_TYPES) {
+        if (t === value)
+            return t;
+    }
+    return 'string';
 }
 function parameterSchemaFromType(type) {
-  if (type === "array") {
-    return { type: "array" };
-  }
-  return { type };
+    if (type === 'array') {
+        return { type: 'array' };
+    }
+    return { type };
 }
 function parseParametersFromDescription(description) {
-  const lines = description.split("\n");
-  let inTable = false;
-  const tableLines = [];
-  const descriptionLines = [];
-  for (const line of lines) {
-    if (line.trim().startsWith("|")) {
-      while (descriptionLines.length > 0 && (descriptionLines[descriptionLines.length - 1]?.trim() === "" || descriptionLines[descriptionLines.length - 1]?.trim().startsWith("#"))) {
-        descriptionLines.pop();
-      }
-      inTable = true;
-    }
-    if (inTable) {
-      tableLines.push(line);
-      if (!line.trim().startsWith("|") && !line.trim().match(/^-+$/)) {
-        inTable = false;
-      }
-    } else {
-      descriptionLines.push(line);
-    }
-  }
-  const tableMarkdown = tableLines.join("\n");
-  const parsedTable = parseMdTable(tableMarkdown);
-  const parametersFromTable = Object.values(parsedTable).map((paramData) => {
-    const row = paramData;
-    if (row.object !== "query" && row.object !== "header" && row.object !== "path") {
-      return void 0;
-    }
-    if (!row.name) {
-      return void 0;
-    }
-    const param = {
-      name: row.name,
-      in: row.object,
-      description: row.description,
-      required: row.required === "true",
-      schema: parameterSchemaFromType(toOpenApiParamSchemaType(row.type))
-    };
-    if (row.example) {
-      param.example = row.example;
+    const lines = description.split('\n');
+    let inTable = false;
+    const tableLines = [];
+    const descriptionLines = [];
+    for (const line of lines) {
+        // Detect the start of the table
+        if (line.trim().startsWith('|')) {
+            // Remove any preceding headers or empty lines before the table
+            while (descriptionLines.length > 0 &&
+                (descriptionLines[descriptionLines.length - 1]?.trim() === '' ||
+                    descriptionLines[descriptionLines.length - 1]?.trim().startsWith('#'))) {
+                descriptionLines.pop();
+            }
+            // Start collecting table lines
+            inTable = true;
+        }
+        if (inTable) {
+            tableLines.push(line);
+            // Detect the end of the table (any line that doesn't start with '|', excluding the alignment line)
+            if (!line.trim().startsWith('|') && !line.trim().match(/^-+$/)) {
+                inTable = false;
+            }
+        }
+        else {
+            descriptionLines.push(line);
+        }
     }
-    return param;
-  }).filter((param) => Boolean(param));
-  const descriptionWithoutTable = descriptionLines.join("\n");
-  return { descriptionWithoutTable, parametersFromTable };
+    const tableMarkdown = tableLines.join('\n');
+    const parsedTable = parseMdTable(tableMarkdown);
+    const parametersFromTable = Object.values(parsedTable)
+        .map((paramData) => {
+        const row = paramData;
+        if (row.object !== 'query' && row.object !== 'header' && row.object !== 'path') {
+            return undefined;
+        }
+        if (!row.name) {
+            return undefined;
+        }
+        const param = {
+            name: row.name,
+            in: row.object,
+            description: row.description,
+            required: row.required === 'true',
+            schema: parameterSchemaFromType(toOpenApiParamSchemaType(row.type)),
+        };
+        if (row.example) {
+            param.example = row.example;
+        }
+        return param;
+    })
+        .filter((param) => Boolean(param));
+    const descriptionWithoutTable = descriptionLines.join('\n');
+    return { descriptionWithoutTable, parametersFromTable };
 }
+// Instead of using regex with \s*, let's split this into two steps
 function extractOperationInfo(name) {
-  if (!name) {
-    return { operationId: void 0, summary: void 0 };
-  }
-  const match = name.match(/\[([^[\]]{0,1000})\]$/);
-  if (!match) {
-    return { operationId: void 0, summary: name };
-  }
-  const operationId = match[1];
-  const lastBracketIndex = name.lastIndexOf("[");
-  const summary = name.substring(0, lastBracketIndex).trim();
-  return { operationId, summary };
+    if (!name) {
+        return { operationId: undefined, summary: undefined };
+    }
+    // First check if the string ends with something in brackets
+    const match = name.match(/\[([^[\]]{0,1000})\]$/);
+    if (!match) {
+        return { operationId: undefined, summary: name };
+    }
+    // Get the operation ID from inside brackets
+    const operationId = match[1];
+    // Trim the brackets part from the end using string operations instead of regex
+    const lastBracketIndex = name.lastIndexOf('[');
+    const summary = name.substring(0, lastBracketIndex).trim();
+    return { operationId, summary };
 }
-export {
-  processItem
-};
-//# sourceMappingURL=path-items.js.map

package/dist/helpers/post-response-scripts.js

@@ -1,13 +1,13 @@
-function processPostResponseScripts(events = []) {
-  const testEvent = events.find((event) => event.listen === "test");
-  const exec = testEvent?.script?.exec;
-  if (!exec) {
-    return void 0;
-  }
-  const content = typeof exec === "string" ? exec : exec.join("\n");
-  return content.trim() || void 0;
+/**
+ * Processes Postman test scripts and converts them to OpenAPI x-post-response extension.
+ * Extracts the test script from Postman events and returns it as a single string.
+ */
+export function processPostResponseScripts(events = []) {
+    const testEvent = events.find((event) => event.listen === 'test');
+    const exec = testEvent?.script?.exec;
+    if (!exec) {
+        return undefined;
+    }
+    const content = typeof exec === 'string' ? exec : exec.join('\n');
+    return content.trim() || undefined;
 }
-export {
-  processPostResponseScripts
-};
-//# sourceMappingURL=post-response-scripts.js.map

package/dist/helpers/pre-request-scripts.js

@@ -1,13 +1,13 @@
-function processPreRequestScripts(events = []) {
-  const preRequestEvent = events.find((event) => event.listen === "prerequest");
-  const exec = preRequestEvent?.script?.exec;
-  if (!exec) {
-    return void 0;
-  }
-  const content = typeof exec === "string" ? exec : exec.join("\n");
-  return content.trim() || void 0;
+/**
+ * Processes Postman pre-request scripts and converts them to OpenAPI x-pre-request extension.
+ * Extracts the pre-request script from Postman events and returns it as a single string.
+ */
+export function processPreRequestScripts(events = []) {
+    const preRequestEvent = events.find((event) => event.listen === 'prerequest');
+    const exec = preRequestEvent?.script?.exec;
+    if (!exec) {
+        return undefined;
+    }
+    const content = typeof exec === 'string' ? exec : exec.join('\n');
+    return content.trim() || undefined;
 }
-export {
-  processPreRequestScripts
-};
-//# sourceMappingURL=pre-request-scripts.js.map

package/dist/helpers/prune-document.js

@@ -1,39 +1,46 @@
+/**
+ * Recursively removes all undefined values from an object or array.
+ * Preserves null values as they are valid in JSON/OpenAPI.
+ * Returns a new object/array with undefined values removed.
+ */
 const removeUndefinedValues = (value) => {
-  if (value === null || value === void 0) {
-    return value === null ? null : void 0;
-  }
-  if (Array.isArray(value)) {
-    return value.map(removeUndefinedValues).filter((item) => item !== void 0);
-  }
-  if (typeof value === "object") {
-    const cleaned = {};
-    for (const [key, val] of Object.entries(value)) {
-      const cleanedValue = removeUndefinedValues(val);
-      if (cleanedValue !== void 0) {
-        cleaned[key] = cleanedValue;
-      }
+    if (value === null || value === undefined) {
+        return value === null ? null : undefined;
     }
-    return cleaned;
-  }
-  return value;
-};
-const pruneDocument = (document) => {
-  const cleaned = { ...document };
-  if (cleaned.tags?.length === 0) {
-    delete cleaned.tags;
-  }
-  if (cleaned.security?.length === 0) {
-    delete cleaned.security;
-  }
-  if (cleaned.components && Object.keys(cleaned.components).length === 0) {
-    delete cleaned.components;
-  }
-  if (cleaned.externalDocs === void 0) {
-    delete cleaned.externalDocs;
-  }
-  return removeUndefinedValues(cleaned);
+    if (Array.isArray(value)) {
+        return value.map(removeUndefinedValues).filter((item) => item !== undefined);
+    }
+    if (typeof value === 'object') {
+        const cleaned = {};
+        for (const [key, val] of Object.entries(value)) {
+            const cleanedValue = removeUndefinedValues(val);
+            if (cleanedValue !== undefined) {
+                cleaned[key] = cleanedValue;
+            }
+        }
+        return cleaned;
+    }
+    return value;
 };
-export {
-  pruneDocument
+/**
+ * Prunes an OpenAPI document by removing empty arrays/objects and undefined values.
+ * Removes empty tags, security arrays, and empty components objects.
+ * Recursively removes all undefined values throughout the document structure.
+ */
+export const pruneDocument = (document) => {
+    const cleaned = { ...document };
+    if (cleaned.tags?.length === 0) {
+        delete cleaned.tags;
+    }
+    if (cleaned.security?.length === 0) {
+        delete cleaned.security;
+    }
+    if (cleaned.components && Object.keys(cleaned.components).length === 0) {
+        delete cleaned.components;
+    }
+    if (cleaned.externalDocs === undefined) {
+        delete cleaned.externalDocs;
+    }
+    // Recursively remove all undefined values from the document
+    return removeUndefinedValues(cleaned);
 };
-//# sourceMappingURL=prune-document.js.map