@scalar/postman-to-openapi 0.5.2 → 0.6.0

package/dist/helpers/auth.js

@@ -1,113 +1,137 @@
+// Constants for security scheme names and URLs
 const AUTH_SCHEMES = {
-  API_KEY: "apikeyAuth",
-  BASIC: "basicAuth",
-  BEARER: "bearerAuth",
-  OAUTH2: "oauth2Auth"
+    API_KEY: 'apikeyAuth',
+    BASIC: 'basicAuth',
+    BEARER: 'bearerAuth',
+    OAUTH2: 'oauth2Auth',
 };
 const OAUTH2_DEFAULTS = {
-  AUTHORIZE_URL: "/oauth/authorize",
-  TOKEN_URL: "/oauth/token"
+    AUTHORIZE_URL: '/oauth/authorize',
+    TOKEN_URL: '/oauth/token',
 };
+/**
+ * Creates security configuration for API key authentication
+ */
 function createApiKeyConfig() {
-  return {
-    scheme: {
-      type: "apiKey",
-      name: "api_key",
-      in: "header"
-    },
-    requirement: { [AUTH_SCHEMES.API_KEY]: [] }
-  };
+    return {
+        scheme: {
+            type: 'apiKey',
+            name: 'api_key',
+            in: 'header',
+        },
+        requirement: { [AUTH_SCHEMES.API_KEY]: [] },
+    };
 }
+/**
+ * Creates security configuration for Basic authentication
+ */
 function createBasicConfig() {
-  return {
-    scheme: {
-      type: "http",
-      scheme: "basic"
-    },
-    requirement: { [AUTH_SCHEMES.BASIC]: [] }
-  };
+    return {
+        scheme: {
+            type: 'http',
+            scheme: 'basic',
+        },
+        requirement: { [AUTH_SCHEMES.BASIC]: [] },
+    };
 }
+/**
+ * Creates security configuration for Bearer token authentication
+ */
 function createBearerConfig() {
-  return {
-    scheme: {
-      type: "http",
-      scheme: "bearer"
-    },
-    requirement: { [AUTH_SCHEMES.BEARER]: [] }
-  };
-}
-function createOAuth2Config(auth) {
-  if (!auth) {
     return {
-      scheme: {},
-      requirement: {}
+        scheme: {
+            type: 'http',
+            scheme: 'bearer',
+        },
+        requirement: { [AUTH_SCHEMES.BEARER]: [] },
     };
-  }
-  const oauth2Attrs = auth.oauth2 || [];
-  const attrMap = /* @__PURE__ */ new Map();
-  oauth2Attrs.forEach((attr) => {
-    if (attr.key && attr.value !== void 0) {
-      attrMap.set(attr.key, String(attr.value));
+}
+/**
+ * Creates security configuration for OAuth2 authentication
+ * Extracts actual OAuth2 URLs and scopes from the Postman auth object
+ */
+function createOAuth2Config(auth) {
+    if (!auth) {
+        return {
+            scheme: {},
+            requirement: {},
+        };
     }
-  });
-  const authUrl = attrMap.get("authUrl") || attrMap.get("authorizationUrl") || OAUTH2_DEFAULTS.AUTHORIZE_URL;
-  const tokenUrl = attrMap.get("accessTokenUrl") || attrMap.get("tokenUrl") || OAUTH2_DEFAULTS.TOKEN_URL;
-  const scopeValue = attrMap.get("scope") || "";
-  const scopes = {};
-  if (scopeValue) {
-    const scopeList = scopeValue.split(/[,\s]+/).filter(Boolean);
-    scopeList.forEach((scope) => {
-      scopes[scope] = scope;
-    });
-  }
-  return {
-    scheme: {
-      type: "oauth2",
-      flows: {
-        authorizationCode: {
-          authorizationUrl: authUrl,
-          tokenUrl,
-          scopes
+    const oauth2Attrs = auth.oauth2 || [];
+    const attrMap = new Map();
+    oauth2Attrs.forEach((attr) => {
+        if (attr.key && attr.value !== undefined) {
+            attrMap.set(attr.key, String(attr.value));
         }
-      }
-    },
-    requirement: { [AUTH_SCHEMES.OAUTH2]: Object.keys(scopes) }
-  };
+    });
+    const authUrl = attrMap.get('authUrl') || attrMap.get('authorizationUrl') || OAUTH2_DEFAULTS.AUTHORIZE_URL;
+    const tokenUrl = attrMap.get('accessTokenUrl') || attrMap.get('tokenUrl') || OAUTH2_DEFAULTS.TOKEN_URL;
+    const scopeValue = attrMap.get('scope') || '';
+    // Parse scopes from the scope value (can be space or comma separated)
+    const scopes = {};
+    if (scopeValue) {
+        const scopeList = scopeValue.split(/[,\s]+/).filter(Boolean);
+        scopeList.forEach((scope) => {
+            scopes[scope] = scope;
+        });
+    }
+    return {
+        scheme: {
+            type: 'oauth2',
+            flows: {
+                authorizationCode: {
+                    authorizationUrl: authUrl,
+                    tokenUrl,
+                    scopes,
+                },
+            },
+        },
+        requirement: { [AUTH_SCHEMES.OAUTH2]: Object.keys(scopes) },
+    };
 }
+/**
+ * Creates security configuration for no authentication
+ */
 function createNoAuthConfig() {
-  return {
-    scheme: {},
-    requirement: {}
-  };
+    return {
+        scheme: {},
+        requirement: {},
+    };
 }
+/**
+ * Maps authentication types to their configuration creators
+ */
 const AUTH_TYPE_HANDLERS = {
-  apikey: createApiKeyConfig,
-  basic: createBasicConfig,
-  bearer: createBearerConfig,
-  oauth2: createOAuth2Config,
-  noauth: createNoAuthConfig
+    apikey: createApiKeyConfig,
+    basic: createBasicConfig,
+    bearer: createBearerConfig,
+    oauth2: createOAuth2Config,
+    noauth: createNoAuthConfig,
 };
-function processAuth(auth) {
-  const securitySchemes = {};
-  const security = [];
-  try {
-    const handler = AUTH_TYPE_HANDLERS[auth.type];
-    if (!handler) {
-      throw new Error(`Unsupported authentication type: ${auth.type}`);
+/**
+ * Processes authentication information from a Postman collection and updates
+ * the OpenAPI document with the corresponding security schemes and requirements.
+ * Supports API key, basic auth, bearer token, OAuth2, and no authentication types.
+ */
+export function processAuth(auth) {
+    const securitySchemes = {};
+    const security = [];
+    try {
+        const handler = AUTH_TYPE_HANDLERS[auth.type];
+        if (!handler) {
+            throw new Error(`Unsupported authentication type: ${auth.type}`);
+        }
+        const { scheme, requirement } = handler(auth);
+        // Only add security schemes and requirements if they're not empty
+        if (Object.keys(scheme).length > 0) {
+            const schemeKey = `${auth.type}Auth`;
+            securitySchemes[schemeKey] = scheme;
+            security.push(requirement);
+        }
     }
-    const { scheme, requirement } = handler(auth);
-    if (Object.keys(scheme).length > 0) {
-      const schemeKey = `${auth.type}Auth`;
-      securitySchemes[schemeKey] = scheme;
-      security.push(requirement);
+    catch (error) {
+        console.error('Error processing authentication:', error);
+        throw error;
     }
-  } catch (error) {
-    console.error("Error processing authentication:", error);
-    throw error;
-  }
-  return { securitySchemes, security };
+    return { securitySchemes, security };
 }
-export {
-  processAuth
-};
-//# sourceMappingURL=auth.js.map

package/dist/helpers/contact.js

@@ -1,25 +1,29 @@
+// Constants for contact variable keys
 const VARIABLE_KEYS = {
-  NAME: "contact.name",
-  URL: "contact.url",
-  EMAIL: "contact.email"
+    NAME: 'contact.name',
+    URL: 'contact.url',
+    EMAIL: 'contact.email',
 };
+/**
+ * Finds a specific variable in the collection by its key
+ */
 function findVariable(collection, key) {
-  return collection.variable?.find((v) => v.key === key);
+    return collection.variable?.find((v) => v.key === key);
 }
-function processContact(collection) {
-  const nameVar = findVariable(collection, VARIABLE_KEYS.NAME);
-  const urlVar = findVariable(collection, VARIABLE_KEYS.URL);
-  const emailVar = findVariable(collection, VARIABLE_KEYS.EMAIL);
-  if (!nameVar?.value && !urlVar?.value && !emailVar?.value) {
-    return void 0;
-  }
-  return {
-    ...nameVar?.value && typeof nameVar.value === "string" && { name: nameVar.value },
-    ...urlVar?.value && typeof urlVar.value === "string" && { url: urlVar.value },
-    ...emailVar?.value && typeof emailVar.value === "string" && { email: emailVar.value }
-  };
+/**
+ * Processes contact information from collection variables.
+ * Returns an OpenAPI Contact Object if at least one contact field is present.
+ */
+export function processContact(collection) {
+    const nameVar = findVariable(collection, VARIABLE_KEYS.NAME);
+    const urlVar = findVariable(collection, VARIABLE_KEYS.URL);
+    const emailVar = findVariable(collection, VARIABLE_KEYS.EMAIL);
+    if (!nameVar?.value && !urlVar?.value && !emailVar?.value) {
+        return undefined;
+    }
+    return {
+        ...(nameVar?.value && typeof nameVar.value === 'string' && { name: nameVar.value }),
+        ...(urlVar?.value && typeof urlVar.value === 'string' && { url: urlVar.value }),
+        ...(emailVar?.value && typeof emailVar.value === 'string' && { email: emailVar.value }),
+    };
 }
-export {
-  processContact
-};
-//# sourceMappingURL=contact.js.map

package/dist/helpers/external-docs.js

@@ -1,32 +1,40 @@
+// Constants for variable keys
 const VARIABLE_KEYS = {
-  URL: "externalDocs.url",
-  DESCRIPTION: "externalDocs.description"
+    URL: 'externalDocs.url',
+    DESCRIPTION: 'externalDocs.description',
 };
+/**
+ * Finds a specific variable in the collection by its key
+ */
 function findVariable(collection, key) {
-  return collection.variable?.find((v) => v.key === key);
+    return collection.variable?.find((v) => v.key === key);
 }
-function processExternalDocs(collection) {
-  try {
-    const urlVariable = findVariable(collection, VARIABLE_KEYS.URL);
-    const descriptionVariable = findVariable(collection, VARIABLE_KEYS.DESCRIPTION);
-    if (!urlVariable?.value) {
-      return void 0;
+/**
+ * Processes the external documentation information from a Postman Collection.
+ * This function checks for 'externalDocs.url' and 'externalDocs.description'
+ * in the collection variables and creates an OpenAPI External Documentation Object
+ * if the URL is present.
+ */
+export function processExternalDocs(collection) {
+    try {
+        const urlVariable = findVariable(collection, VARIABLE_KEYS.URL);
+        const descriptionVariable = findVariable(collection, VARIABLE_KEYS.DESCRIPTION);
+        if (!urlVariable?.value) {
+            return undefined;
+        }
+        if (typeof urlVariable.value !== 'string') {
+            throw new Error('External docs URL must be a string');
+        }
+        return {
+            url: urlVariable.value,
+            ...(descriptionVariable?.value &&
+                typeof descriptionVariable.value === 'string' && {
+                description: descriptionVariable.value,
+            }),
+        };
     }
-    if (typeof urlVariable.value !== "string") {
-      throw new Error("External docs URL must be a string");
+    catch (error) {
+        console.error('Error processing external docs:', error);
+        throw error;
     }
-    return {
-      url: urlVariable.value,
-      ...descriptionVariable?.value && typeof descriptionVariable.value === "string" && {
-        description: descriptionVariable.value
-      }
-    };
-  } catch (error) {
-    console.error("Error processing external docs:", error);
-    throw error;
-  }
 }
-export {
-  processExternalDocs
-};
-//# sourceMappingURL=external-docs.js.map

package/dist/helpers/form-data.js

@@ -1,39 +1,45 @@
-function processFormDataSchema(formdata) {
-  const schema = {
-    type: "object",
-    properties: {},
-    required: []
-  };
-  formdata.forEach((item) => {
-    if (!schema.properties) {
-      return;
-    }
-    const property = {
-      type: "string"
+/**
+ * Processes form data parameters from a Postman request and converts them into an OpenAPI schema.
+ * Handles file uploads, required fields, and descriptions.
+ */
+export function processFormDataSchema(formdata) {
+    const schema = {
+        type: 'object',
+        properties: {},
+        required: [],
     };
-    if (item.description) {
-      const descriptionText = typeof item.description === "string" ? item.description : item.description.content || "";
-      property.description = descriptionText.replace(" [required]", "");
-      if (descriptionText.includes("[required]")) {
-        schema.required?.push(item.key);
-      }
-    }
-    if (item.type === "file") {
-      property.format = "binary";
-    } else {
-      property.example = item.value;
-    }
-    if (item.disabled === true) {
-      property["x-scalar-disabled"] = true;
+    formdata.forEach((item) => {
+        if (!schema.properties) {
+            return;
+        }
+        const property = {
+            type: 'string',
+        };
+        // Add description if present, handling both string and object descriptions
+        if (item.description) {
+            const descriptionText = typeof item.description === 'string' ? item.description : item.description.content || '';
+            property.description = descriptionText.replace(' [required]', '');
+            // If [required] was present, add to required array
+            if (descriptionText.includes('[required]')) {
+                schema.required?.push(item.key);
+            }
+        }
+        // Handle file type fields
+        if (item.type === 'file') {
+            property.format = 'binary';
+        }
+        else {
+            property.example = item.value;
+        }
+        // Add x-scalar-disabled extension if parameter is disabled
+        if (item.disabled === true) {
+            property['x-scalar-disabled'] = true;
+        }
+        schema.properties[item.key] = property;
+    });
+    // Only keep required array if it has items
+    if (schema.required?.length === 0) {
+        delete schema.required;
     }
-    schema.properties[item.key] = property;
-  });
-  if (schema.required?.length === 0) {
-    delete schema.required;
-  }
-  return schema;
+    return schema;
 }
-export {
-  processFormDataSchema
-};
-//# sourceMappingURL=form-data.js.map

package/dist/helpers/generate-unique-value.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generates a unique string value based on a default value and a validation function.
+ * The function tries the default value first. If validation fails, it appends
+ * an incrementing suffix (optionally with a prefix) until the validation passes.
+ *
+ * @param defaultValue - The initial base string value to try.
+ * @param validation - A function that receives a candidate value and returns true if it is valid.
+ * @param prefix - Optional prefix to add before the incrementing number (default is '').
+ * @returns The first value that passes the validation.
+ *
+ * @example
+ * // Case 1: Simple unused value
+ * generateUniqueValue('example', v => v !== 'example') // → "example 2"
+ *
+ * // Case 2: Avoids taken values in a set
+ * const taken = new Set(['foo', 'foo 1', 'foo 2']);
+ * generateUniqueValue('foo', v => !taken.has(v)) // → "foo 3"
+ *
+ * // Case 3: Using a prefix
+ * generateUniqueValue('base', v => v === 'base__3', '__') // → "base__3"
+ */
+export declare const generateUniqueValue: (defaultValue: string, validation: (value: string) => boolean, prefix?: string) => string;
+//# sourceMappingURL=generate-unique-value.d.ts.map

package/dist/helpers/generate-unique-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-unique-value.d.ts","sourceRoot":"","sources":["../../src/helpers/generate-unique-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,GAC9B,cAAc,MAAM,EACpB,YAAY,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,EACtC,eAAW,KACV,MAOF,CAAA"}

package/dist/helpers/generate-unique-value.js

@@ -0,0 +1,29 @@
+/**
+ * Generates a unique string value based on a default value and a validation function.
+ * The function tries the default value first. If validation fails, it appends
+ * an incrementing suffix (optionally with a prefix) until the validation passes.
+ *
+ * @param defaultValue - The initial base string value to try.
+ * @param validation - A function that receives a candidate value and returns true if it is valid.
+ * @param prefix - Optional prefix to add before the incrementing number (default is '').
+ * @returns The first value that passes the validation.
+ *
+ * @example
+ * // Case 1: Simple unused value
+ * generateUniqueValue('example', v => v !== 'example') // → "example 2"
+ *
+ * // Case 2: Avoids taken values in a set
+ * const taken = new Set(['foo', 'foo 1', 'foo 2']);
+ * generateUniqueValue('foo', v => !taken.has(v)) // → "foo 3"
+ *
+ * // Case 3: Using a prefix
+ * generateUniqueValue('base', v => v === 'base__3', '__') // → "base__3"
+ */
+export const generateUniqueValue = (defaultValue, validation, prefix = '') => {
+    let i = 1;
+    let value = defaultValue;
+    while (!validation(value)) {
+        value = `${defaultValue} ${prefix}${i++}`;
+    }
+    return value;
+};

package/dist/helpers/get-operation-examples.d.ts

@@ -0,0 +1,40 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+/**
+ * Collects all example names used on parameters and requestBodies
+ * within all operations of a PathItemObject.
+ *
+ * This is useful for checking which example names are already present
+ * so you can avoid clashes (e.g., generating unique example names
+ * when merging path items).
+ *
+ * @param path - The OpenAPI PathItemObject to scan
+ * @returns Set of all unique example names found across parameters and requestBodies
+ *
+ * @example
+ * const operation: OpenAPIV3_1.OperationObject = {
+ *   parameters: [
+ *     {
+ *       name: 'id',
+ *       in: 'query',
+ *       examples: {
+ *         foo: { value: 'bar' },
+ *         bar: { value: 'baz' }
+ *       }
+ *     }
+ *   ],
+ *   requestBody: {
+ *     content: {
+ *       'application/json': {
+ *         examples: {
+ *           default: { value: 1 },
+ *           extra: { value: 2 }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * const path = { get: operation }
+ * // getOperationExamples(path) => Set { 'foo', 'bar', 'default', 'extra' }
+ */
+export declare const getOperationExamples: (path: OpenAPIV3_1.PathItemObject) => Set<string>;
+//# sourceMappingURL=get-operation-examples.d.ts.map

package/dist/helpers/get-operation-examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-operation-examples.d.ts","sourceRoot":"","sources":["../../src/helpers/get-operation-examples.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,WAAW,CAAC,cAAc,gBA2CpE,CAAA"}

package/dist/helpers/get-operation-examples.js

@@ -0,0 +1,76 @@
+import { HTTP_METHODS } from '@scalar/helpers/http/http-methods';
+/**
+ * Collects all example names used on parameters and requestBodies
+ * within all operations of a PathItemObject.
+ *
+ * This is useful for checking which example names are already present
+ * so you can avoid clashes (e.g., generating unique example names
+ * when merging path items).
+ *
+ * @param path - The OpenAPI PathItemObject to scan
+ * @returns Set of all unique example names found across parameters and requestBodies
+ *
+ * @example
+ * const operation: OpenAPIV3_1.OperationObject = {
+ *   parameters: [
+ *     {
+ *       name: 'id',
+ *       in: 'query',
+ *       examples: {
+ *         foo: { value: 'bar' },
+ *         bar: { value: 'baz' }
+ *       }
+ *     }
+ *   ],
+ *   requestBody: {
+ *     content: {
+ *       'application/json': {
+ *         examples: {
+ *           default: { value: 1 },
+ *           extra: { value: 2 }
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ * const path = { get: operation }
+ * // getOperationExamples(path) => Set { 'foo', 'bar', 'default', 'extra' }
+ */
+export const getOperationExamples = (path) => {
+    const exampleNames = new Set();
+    for (const key of HTTP_METHODS) {
+        const operation = path[key];
+        if (operation === undefined || typeof operation !== 'object') {
+            continue;
+        }
+        const op = operation;
+        if ('parameters' in op) {
+            op.parameters?.forEach((parameter) => {
+                if (parameter.examples) {
+                    for (const exampleName of Object.keys(parameter.examples)) {
+                        exampleNames.add(exampleName);
+                    }
+                }
+            });
+        }
+        if ('requestBody' in op) {
+            const requestBody = op.requestBody;
+            if (requestBody?.content) {
+                for (const mediaTypeObject of Object.values(requestBody.content)) {
+                    const examples = mediaTypeObject &&
+                        typeof mediaTypeObject === 'object' &&
+                        'examples' in mediaTypeObject &&
+                        typeof mediaTypeObject.examples === 'object'
+                        ? mediaTypeObject.examples
+                        : undefined;
+                    if (examples) {
+                        for (const exampleName of Object.keys(examples)) {
+                            exampleNames.add(exampleName);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return exampleNames;
+};

package/dist/helpers/license.js

@@ -1,22 +1,26 @@
+// Constants for license variable keys
 const VARIABLE_KEYS = {
-  NAME: "license.name",
-  URL: "license.url"
+    NAME: 'license.name',
+    URL: 'license.url',
 };
+/**
+ * Finds a specific variable in the collection by its key
+ */
 function findVariable(collection, key) {
-  return collection.variable?.find((v) => v.key === key);
+    return collection.variable?.find((v) => v.key === key);
 }
-function processLicense(collection) {
-  const nameVar = findVariable(collection, VARIABLE_KEYS.NAME);
-  if (!nameVar?.value || typeof nameVar.value !== "string") {
-    return void 0;
-  }
-  const urlVar = findVariable(collection, VARIABLE_KEYS.URL);
-  return {
-    name: nameVar.value,
-    ...urlVar?.value && typeof urlVar.value === "string" && { url: urlVar.value }
-  };
+/**
+ * Processes license information from collection variables.
+ * Returns an OpenAPI License Object if the license name is present.
+ */
+export function processLicense(collection) {
+    const nameVar = findVariable(collection, VARIABLE_KEYS.NAME);
+    if (!nameVar?.value || typeof nameVar.value !== 'string') {
+        return undefined;
+    }
+    const urlVar = findVariable(collection, VARIABLE_KEYS.URL);
+    return {
+        name: nameVar.value,
+        ...(urlVar?.value && typeof urlVar.value === 'string' && { url: urlVar.value }),
+    };
 }
-export {
-  processLicense
-};
-//# sourceMappingURL=license.js.map