@scalar/postman-to-openapi 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @scalar/postman-to-openapi
 
+## 0.5.3
+
+### Patch Changes
+
+- [#8466](https://github.com/scalar/scalar/pull/8466): chore: new build pipeline
+
+## 0.5.2
+
+### Patch Changes
+
+#### Updated Dependencies
+
+- **@scalar/helpers@0.4.1**
+  - [#8420](https://github.com/scalar/scalar/pull/8420): fix TypeScript access to navigator.userAgentData in isMacOS without ts-expect-error
+
 ## 0.5.1
 
 ### Patch Changes

package/dist/convert.js

@@ -1,233 +1,261 @@
-import { processAuth } from "./helpers/auth.js";
-import { processContact } from "./helpers/contact.js";
-import { processExternalDocs } from "./helpers/external-docs.js";
-import { processLicense } from "./helpers/license.js";
-import { processLogo } from "./helpers/logo.js";
-import { processItem } from "./helpers/path-items.js";
-import { pruneDocument } from "./helpers/prune-document.js";
-import { analyzeServerDistribution } from "./helpers/servers.js";
-import { normalizePath } from "./helpers/urls.js";
+import { processAuth } from './helpers/auth.js';
+import { processContact } from './helpers/contact.js';
+import { processExternalDocs } from './helpers/external-docs.js';
+import { processLicense } from './helpers/license.js';
+import { processLogo } from './helpers/logo.js';
+import { processItem } from './helpers/path-items.js';
+import { pruneDocument } from './helpers/prune-document.js';
+import { analyzeServerDistribution } from './helpers/servers.js';
+import { normalizePath } from './helpers/urls.js';
 const OPERATION_KEYS = [
-  "get",
-  "put",
-  "post",
-  "delete",
-  "options",
-  "head",
-  "patch",
-  "trace"
+    'get',
+    'put',
+    'post',
+    'delete',
+    'options',
+    'head',
+    'patch',
+    'trace',
 ];
 const normalizeDescription = (description) => {
-  if (typeof description === "string") {
-    return description;
-  }
-  return description?.content;
+    if (typeof description === 'string') {
+        return description;
+    }
+    return description?.content;
 };
 const parseCollectionInput = (postmanCollection) => {
-  if (typeof postmanCollection !== "string") {
-    return postmanCollection;
-  }
-  try {
-    return JSON.parse(postmanCollection);
-  } catch (error) {
-    const details = error instanceof Error ? error.message : "Unknown parse error";
-    const parseError = new Error(`Invalid Postman collection JSON: ${details}`);
-    parseError.name = "PostmanCollectionParseError";
-    throw parseError;
-  }
+    if (typeof postmanCollection !== 'string') {
+        return postmanCollection;
+    }
+    try {
+        return JSON.parse(postmanCollection);
+    }
+    catch (error) {
+        const details = error instanceof Error ? error.message : 'Unknown parse error';
+        const parseError = new Error(`Invalid Postman collection JSON: ${details}`);
+        parseError.name = 'PostmanCollectionParseError';
+        throw parseError;
+    }
 };
 const validateCollectionShape = (collection) => {
-  if (!collection || typeof collection !== "object") {
-    throw new Error("Invalid Postman collection: expected an object");
-  }
-  const candidate = collection;
-  if (!candidate.info) {
-    throw new Error("Missing required info on Postman collection");
-  }
-  if (!candidate.item || !Array.isArray(candidate.item)) {
-    throw new Error("Invalid Postman collection: item must be an array");
-  }
-  if (typeof candidate.info !== "object") {
-    throw new Error("Invalid Postman collection: info must be an object");
-  }
-  if (!candidate.info.name) {
-    throw new Error("Missing required info.name on Postman collection");
-  }
-  if (!candidate.info.schema) {
-    throw new Error("Invalid Postman collection: missing info.schema");
-  }
-  if (candidate.variable && !Array.isArray(candidate.variable)) {
-    throw new Error("Invalid Postman collection: variable must be an array when provided");
-  }
-  return candidate;
+    if (!collection || typeof collection !== 'object') {
+        throw new Error('Invalid Postman collection: expected an object');
+    }
+    const candidate = collection;
+    if (!candidate.info) {
+        throw new Error('Missing required info on Postman collection');
+    }
+    if (!candidate.item || !Array.isArray(candidate.item)) {
+        throw new Error('Invalid Postman collection: item must be an array');
+    }
+    if (typeof candidate.info !== 'object') {
+        throw new Error('Invalid Postman collection: info must be an object');
+    }
+    if (!candidate.info.name) {
+        throw new Error('Missing required info.name on Postman collection');
+    }
+    if (!candidate.info.schema) {
+        throw new Error('Invalid Postman collection: missing info.schema');
+    }
+    if (candidate.variable && !Array.isArray(candidate.variable)) {
+        throw new Error('Invalid Postman collection: variable must be an array when provided');
+    }
+    return candidate;
 };
-const isItemGroup = (item) => "item" in item && Array.isArray(item.item);
+/**
+ * Extracts tags from Postman collection folders.
+ * We keep folder nesting using " > " so tag names stay readable while preserving hierarchy.
+ * Requests do not produce tags; only folders are reflected as tags.
+ */
+const isItemGroup = (item) => 'item' in item && Array.isArray(item.item);
 const extractTags = (items) => {
-  const collectTags = (item, parentPath = "") => {
-    if (!isItemGroup(item)) {
-      return [];
-    }
-    const nextPath = item.name ? parentPath ? `${parentPath} > ${item.name}` : item.name : parentPath;
-    const description = normalizeDescription(item.description);
-    const currentTag = item.name?.length ? [
-      {
-        name: nextPath,
-        ...description && { description }
-      }
-    ] : [];
-    return [...currentTag, ...item.item.flatMap((subItem) => collectTags(subItem, nextPath))];
-  };
-  return items.flatMap((item) => collectTags(item));
+    const collectTags = (item, parentPath = '') => {
+        if (!isItemGroup(item)) {
+            return [];
+        }
+        const nextPath = item.name ? (parentPath ? `${parentPath} > ${item.name}` : item.name) : parentPath;
+        const description = normalizeDescription(item.description);
+        const currentTag = item.name?.length
+            ? [
+                {
+                    name: nextPath,
+                    ...(description && { description }),
+                },
+            ]
+            : [];
+        return [...currentTag, ...item.item.flatMap((subItem) => collectTags(subItem, nextPath))];
+    };
+    return items.flatMap((item) => collectTags(item));
 };
 const mergeSecuritySchemes = (openapi, securitySchemes) => {
-  if (!securitySchemes || Object.keys(securitySchemes).length === 0) {
-    return;
-  }
-  openapi.components = openapi.components || {};
-  openapi.components.securitySchemes = {
-    ...openapi.components.securitySchemes ?? {},
-    ...securitySchemes
-  };
+    if (!securitySchemes || Object.keys(securitySchemes).length === 0) {
+        return;
+    }
+    openapi.components = openapi.components || {};
+    openapi.components.securitySchemes = {
+        ...(openapi.components.securitySchemes ?? {}),
+        ...securitySchemes,
+    };
 };
 const mergePathItem = (paths, normalizedPathKey, pathItem) => {
-  const targetPath = paths[normalizedPathKey] ?? {};
-  for (const [key, value] of Object.entries(pathItem)) {
-    if (value === void 0) {
-      continue;
-    }
-    const isOperationKey = OPERATION_KEYS.includes(key);
-    if (isOperationKey && targetPath[key]) {
-      const operationName = typeof key === "string" ? key.toUpperCase() : String(key);
-      console.warn(
-        `Duplicate operation detected for ${operationName} ${normalizedPathKey}. Last operation will overwrite previous.`
-      );
-    }
-    targetPath[key] = value;
-  }
-  paths[normalizedPathKey] = targetPath;
+    const targetPath = (paths[normalizedPathKey] ?? {});
+    for (const [key, value] of Object.entries(pathItem)) {
+        if (value === undefined) {
+            continue;
+        }
+        const isOperationKey = OPERATION_KEYS.includes(key);
+        if (isOperationKey && targetPath[key]) {
+            const operationName = typeof key === 'string' ? key.toUpperCase() : String(key);
+            console.warn(`Duplicate operation detected for ${operationName} ${normalizedPathKey}. Last operation will overwrite previous.`);
+        }
+        targetPath[key] = value;
+    }
+    paths[normalizedPathKey] = targetPath;
 };
 const cleanupOperations = (paths) => {
-  Object.values(paths).forEach((pathItem) => {
-    if (!pathItem) {
-      return;
-    }
-    OPERATION_KEYS.forEach((operationKey) => {
-      const operation = pathItem[operationKey];
-      if (!operation) {
-        return;
-      }
-      if ("parameters" in operation && operation.parameters?.length === 0) {
-        delete operation.parameters;
-      }
-      if ("requestBody" in operation && operation.requestBody && "content" in operation.requestBody) {
-        const content = operation.requestBody.content;
-        if (content && "text/plain" in content) {
-          const text = content["text/plain"];
-          if (!text?.schema || text.schema && Object.keys(text.schema).length === 0) {
-            content["text/plain"] = {};
-          }
+    Object.values(paths).forEach((pathItem) => {
+        if (!pathItem) {
+            return;
         }
-      }
-      if (!operation.description) {
-        delete operation.description;
-      }
+        OPERATION_KEYS.forEach((operationKey) => {
+            const operation = pathItem[operationKey];
+            if (!operation) {
+                return;
+            }
+            if ('parameters' in operation && operation.parameters?.length === 0) {
+                delete operation.parameters;
+            }
+            if ('requestBody' in operation && operation.requestBody && 'content' in operation.requestBody) {
+                const content = operation.requestBody.content;
+                if (content && 'text/plain' in content) {
+                    const text = content['text/plain'];
+                    if (!text?.schema || (text.schema && Object.keys(text.schema).length === 0)) {
+                        content['text/plain'] = {};
+                    }
+                }
+            }
+            if (!operation.description) {
+                delete operation.description;
+            }
+        });
     });
-  });
 };
-function convert(postmanCollection) {
-  const collection = validateCollectionShape(parseCollectionInput(postmanCollection));
-  const title = collection.info.name || "API";
-  const version = collection.variable?.find((v) => v.key === "version")?.value || "1.0.0";
-  const description = normalizeDescription(collection.info.description) || "";
-  const license = processLicense(collection);
-  const contact = processContact(collection);
-  const logo = processLogo(collection);
-  const openapi = {
-    openapi: "3.1.0",
-    info: {
-      title,
-      version,
-      ...description && { description },
-      ...license && { license },
-      ...contact && { contact },
-      ...logo && { "x-logo": logo }
-    },
-    paths: {}
-  };
-  const externalDocs = processExternalDocs(collection);
-  if (externalDocs) {
-    openapi.externalDocs = externalDocs;
-  }
-  if (collection.auth) {
-    const { securitySchemes, security } = processAuth(collection.auth);
-    mergeSecuritySchemes(openapi, securitySchemes);
-    openapi.security = security;
-  }
-  const allServerUsage = [];
-  if (collection.item) {
-    const tags = extractTags(collection.item);
-    if (tags.length > 0) {
-      openapi.tags = tags;
-    }
-    collection.item.forEach((item) => {
-      const { paths: itemPaths, components: itemComponents, serverUsage } = processItem(item);
-      allServerUsage.push(...serverUsage);
-      openapi.paths = openapi.paths || {};
-      for (const [pathKey, pathItem] of Object.entries(itemPaths)) {
-        const normalizedPathKey = normalizePath(pathKey);
-        if (!pathItem) {
-          continue;
+/**
+ * Converts a Postman Collection to an OpenAPI 3.1.0 document.
+ * This function processes the collection's information, servers, authentication,
+ * and items to create a corresponding OpenAPI structure.
+ */
+export function convert(postmanCollection) {
+    const collection = validateCollectionShape(parseCollectionInput(postmanCollection));
+    // Extract title from collection info, fallback to 'API' if not provided
+    const title = collection.info.name || 'API';
+    // Look for version in collection variables, default to '1.0.0'
+    const version = collection.variable?.find((v) => v.key === 'version')?.value || '1.0.0';
+    // Handle different description formats in Postman
+    const description = normalizeDescription(collection.info.description) || '';
+    // Process license and contact information
+    const license = processLicense(collection);
+    const contact = processContact(collection);
+    // Process logo information
+    const logo = processLogo(collection);
+    // Initialize the OpenAPI document with required fields
+    const openapi = {
+        openapi: '3.1.0',
+        info: {
+            title,
+            version,
+            ...(description && { description }),
+            ...(license && { license }),
+            ...(contact && { contact }),
+            ...(logo && { 'x-logo': logo }),
+        },
+        paths: {},
+    };
+    // Process external docs
+    const externalDocs = processExternalDocs(collection);
+    if (externalDocs) {
+        openapi.externalDocs = externalDocs;
+    }
+    // Process authentication if present in the collection
+    if (collection.auth) {
+        const { securitySchemes, security } = processAuth(collection.auth);
+        mergeSecuritySchemes(openapi, securitySchemes);
+        openapi.security = security;
+    }
+    // Process each item in the collection and merge into OpenAPI spec
+    const allServerUsage = [];
+    if (collection.item) {
+        // Extract tags from folders
+        const tags = extractTags(collection.item);
+        if (tags.length > 0) {
+            openapi.tags = tags;
         }
-        mergePathItem(openapi.paths, normalizedPathKey, pathItem);
-      }
-      if (itemComponents?.securitySchemes) {
-        mergeSecuritySchemes(openapi, itemComponents.securitySchemes);
-      }
-    });
-  }
-  const allUniquePaths = /* @__PURE__ */ new Set();
-  if (openapi.paths) {
-    for (const pathKey of Object.keys(openapi.paths)) {
-      allUniquePaths.add(pathKey);
-    }
-  }
-  const serverPlacement = analyzeServerDistribution(allServerUsage, allUniquePaths);
-  if (serverPlacement.document.length > 0) {
-    openapi.servers = serverPlacement.document;
-  }
-  if (openapi.paths) {
-    for (const [path, servers] of serverPlacement.pathItems.entries()) {
-      const normalizedPathKey = normalizePath(path);
-      const pathItem = openapi.paths[normalizedPathKey];
-      if (pathItem) {
-        pathItem.servers = servers;
-      }
-    }
-    for (const [path, methods] of serverPlacement.operations.entries()) {
-      const normalizedPathKey = normalizePath(path);
-      const pathItem = openapi.paths[normalizedPathKey];
-      if (!pathItem) {
-        continue;
-      }
-      for (const [method, servers] of methods.entries()) {
-        if (method in pathItem) {
-          const operation = pathItem[method];
-          if (operation && typeof operation === "object" && "responses" in operation) {
-            operation.servers = servers;
-          }
+        collection.item.forEach((item) => {
+            const { paths: itemPaths, components: itemComponents, serverUsage } = processItem(item);
+            // Collect server usage information
+            allServerUsage.push(...serverUsage);
+            // Merge paths from the current item
+            openapi.paths = openapi.paths || {};
+            for (const [pathKey, pathItem] of Object.entries(itemPaths)) {
+                // Convert colon-style params to curly brace style
+                const normalizedPathKey = normalizePath(pathKey);
+                if (!pathItem) {
+                    continue;
+                }
+                mergePathItem(openapi.paths, normalizedPathKey, pathItem);
+            }
+            // Merge security schemes from the current item
+            if (itemComponents?.securitySchemes) {
+                mergeSecuritySchemes(openapi, itemComponents.securitySchemes);
+            }
+        });
+    }
+    // Extract all unique paths from the document
+    const allUniquePaths = new Set();
+    if (openapi.paths) {
+        for (const pathKey of Object.keys(openapi.paths)) {
+            allUniquePaths.add(pathKey);
         }
-      }
-    }
-  }
-  if (openapi.paths) {
-    cleanupOperations(openapi.paths);
-  }
-  if (Object.keys(openapi.components || {}).length === 0) {
-    delete openapi.components;
-  }
-  return pruneDocument(openapi);
+    }
+    // Analyze server distribution and place servers at appropriate levels
+    const serverPlacement = analyzeServerDistribution(allServerUsage, allUniquePaths);
+    // Add servers to document level
+    if (serverPlacement.document.length > 0) {
+        openapi.servers = serverPlacement.document;
+    }
+    // Add servers to path items
+    if (openapi.paths) {
+        for (const [path, servers] of serverPlacement.pathItems.entries()) {
+            const normalizedPathKey = normalizePath(path);
+            const pathItem = openapi.paths[normalizedPathKey];
+            if (pathItem) {
+                pathItem.servers = servers;
+            }
+        }
+        // Add servers to operations
+        for (const [path, methods] of serverPlacement.operations.entries()) {
+            const normalizedPathKey = normalizePath(path);
+            const pathItem = openapi.paths[normalizedPathKey];
+            if (!pathItem) {
+                continue;
+            }
+            for (const [method, servers] of methods.entries()) {
+                if (method in pathItem) {
+                    const operation = pathItem[method];
+                    if (operation && typeof operation === 'object' && 'responses' in operation) {
+                        operation.servers = servers;
+                    }
+                }
+            }
+        }
+    }
+    // Clean up the generated paths
+    if (openapi.paths) {
+        cleanupOperations(openapi.paths);
+    }
+    // Remove empty components object
+    if (Object.keys(openapi.components || {}).length === 0) {
+        delete openapi.components;
+    }
+    return pruneDocument(openapi);
 }
-export {
-  convert
-};
-//# sourceMappingURL=convert.js.map