@scalar/postman-to-openapi 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @scalar/postman-to-openapi
 
+## 0.7.0
+
+### Minor Changes
+
+- [#8904](https://github.com/scalar/scalar/pull/8904): feat: don't keep all headers
+
+### Patch Changes
+
+- [#8901](https://github.com/scalar/scalar/pull/8901): fix fixture generation formatting by writing output textures with 2-space indented JSON so regeneration does not produce noisy diffs when data is unchanged
+- [#8901](https://github.com/scalar/scalar/pull/8901): Move Postman conversion fixtures into the repository and update tests to read local fixture files instead of downloading from cloud storage.
+- [#8899](https://github.com/scalar/scalar/pull/8899): resolve Postman `{{variables}}` in server URLs by substituting collection variable values and emitting OpenAPI server variables when values are unresolved or recursive
+- [#8900](https://github.com/scalar/scalar/pull/8900): fix(postman-to-openapi): preserve tag context when folder description is an empty string
+- [#8900](https://github.com/scalar/scalar/pull/8900): feat(postman-to-openapi): default to leaf-based tag naming with chain fallback option
+- [#8895](https://github.com/scalar/scalar/pull/8895): fix: omit response content for no-body status codes by default
+
 ## 0.6.3
 
 ### Patch Changes

package/dist/convert.d.ts

@@ -5,6 +5,7 @@ import type { PostmanCollection } from './types.js';
  * Example: `[0, 2, 1]` → `collection.item[0].item[2].item[1]`.
  */
 export type PostmanRequestIndexPath = readonly number[];
+export type TagNamingStrategy = 'leaf' | 'chain';
 export type ConvertOptions = {
     /**
      * Whether to merge operations with the same path and method.
@@ -21,12 +22,25 @@ export type ConvertOptions = {
      * When omitted, the whole collection is converted (existing behavior).
      */
     requestIndexPaths?: readonly PostmanRequestIndexPath[];
+    /**
+     * Strategy for generating OpenAPI tag names from nested Postman folders.
+     * - `leaf` (default): use the folder name only; duplicate leaves fallback to `parent / leaf`.
+     * - `chain`: keep the legacy full folder chain joined by ` > `.
+     */
+    tagNamingStrategy?: TagNamingStrategy;
     /**
      * Existing OpenAPI document to merge into. The input is is updated with Postman paths,
      * tags (union by name), security schemes, and servers.
      * Root `info` and existing paths are preserved unless Postman adds or merges operations.
      */
     document?: OpenAPIV3_1.Document;
+    /**
+     * Header keys (case-insensitive) to preserve as `parameters[in=header]` even
+     * if they match the built-in block-list of transport, content-negotiation, or
+     * auth headers (Accept, Content-Type, Authorization, Host, ...). Rarely needed —
+     * useful when an API intentionally documents a non-standard use of these names.
+     */
+    keepHeaders?: readonly string[];
 };
 /**
  * Converts a Postman Collection to an OpenAPI 3.1.0 document.

package/dist/convert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAkBxD,OAAO,KAAK,EAAgC,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAE9E;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,MAAM,EAAE,CAAA;AA8iBvD,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAA;CAChC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,iBAAiB,EAAE,iBAAiB,GAAG,MAAM,EAC7C,OAAO,GAAE,cAA0C,GAClD,WAAW,CAAC,QAAQ,CA4MtB"}
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAoBxD,OAAO,KAAK,EAAgC,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAE9E;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,MAAM,EAAE,CAAA;AA6DvD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAA;AA6rBhD,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;IACrC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAA;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,iBAAiB,EAAE,iBAAiB,GAAG,MAAM,EAC7C,OAAO,GAAE,cAA0C,GAClD,WAAW,CAAC,QAAQ,CAkOtB"}

package/dist/convert.js

@@ -4,10 +4,10 @@ import { processExternalDocs } from './helpers/external-docs.js';
 import { processLicense } from './helpers/license.js';
 import { processLogo } from './helpers/logo.js';
 import { DEFAULT_EXAMPLE_NAME, OPERATION_KEYS, mergePathItem } from './helpers/merge-path-item.js';
-import { POSTMAN_EXAMPLE_NAME_EXTENSION, POSTMAN_POST_RESPONSE_SCRIPTS_EXTENSION, POSTMAN_PRE_REQUEST_SCRIPTS_EXTENSION, processItem, } from './helpers/path-items.js';
+import { POSTMAN_EXAMPLE_NAME_EXTENSION, POSTMAN_FOLDER_SEGMENTS_EXTENSION, POSTMAN_POST_RESPONSE_SCRIPTS_EXTENSION, POSTMAN_PRE_REQUEST_SCRIPTS_EXTENSION, processItem, } from './helpers/path-items.js';
 import { pruneDocument } from './helpers/prune-document.js';
 import { analyzeServerDistribution } from './helpers/servers.js';
-import { getPathStructuralSignature, normalizePath } from './helpers/urls.js';
+import { createCollectionVariableLookup, getPathStructuralSignature, normalizePath } from './helpers/urls.js';
 const normalizeDescription = (description) => {
     if (typeof description === 'string') {
         return description;
@@ -53,35 +53,173 @@ const validateCollectionShape = (collection) => {
     }
     return candidate;
 };
-/**
- * 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 TAG_CHAIN_SEPARATOR = ' > ';
+const TAG_DUPLICATE_SEPARATOR = ' / ';
+const getTagContextKey = (segments) => JSON.stringify(segments);
+const getChainTagName = (segments) => segments.join(TAG_CHAIN_SEPARATOR);
+const isPathParameterSegment = (segment) => (segment.startsWith('{') && segment.endsWith('}')) || segment.startsWith(':');
+const normalizeLeafTagSegment = (segment) => {
+    const trimmed = segment.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    // Postman folders are sometimes literal URL templates (`/languages/{languageCode}`).
+    // Keep tag names short by turning those into a readable leaf identifier.
+    const looksLikePathTemplate = trimmed.startsWith('/') || (trimmed.includes('/') && !trimmed.includes(' '));
+    if (!looksLikePathTemplate) {
+        return trimmed;
+    }
+    const segments = trimmed
+        .split('/')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (segments.length === 0) {
+        return trimmed;
+    }
+    const preferredSegment = [...segments].reverse().find((part) => !isPathParameterSegment(part));
+    const fallbackSegment = preferredSegment ?? segments[segments.length - 1] ?? trimmed;
+    if (fallbackSegment.startsWith('{') && fallbackSegment.endsWith('}')) {
+        return fallbackSegment.slice(1, -1);
+    }
+    if (fallbackSegment.startsWith(':')) {
+        return fallbackSegment.slice(1);
+    }
+    return fallbackSegment;
+};
+const getLeafTagName = (segments) => normalizeLeafTagSegment(segments[segments.length - 1] ?? '');
+const getLeafDuplicateFallback = (segments, leafTagName) => {
+    const parentSegment = segments[segments.length - 2];
+    if (!parentSegment) {
+        return getChainTagName(segments);
+    }
+    const normalizedParent = normalizeLeafTagSegment(parentSegment);
+    if (!normalizedParent) {
+        return getChainTagName(segments);
+    }
+    return `${normalizedParent}${TAG_DUPLICATE_SEPARATOR}${leafTagName}`;
+};
+const buildLeafTagContextDescription = (segments) => {
+    if (segments.length <= 1) {
+        return undefined;
+    }
+    return `Part of ${segments.slice(0, -1).join(' -> ')}`;
+};
+const mergeTagDescriptions = (description, contextDescription) => {
+    if (description && contextDescription) {
+        return `${description}\n\n${contextDescription}`;
+    }
+    return description || contextDescription;
+};
+const dedupeTagContexts = (contexts) => {
+    const contextMap = new Map();
+    contexts.forEach((context) => {
+        const key = getTagContextKey(context.segments);
+        const existing = contextMap.get(key);
+        if (!existing) {
+            contextMap.set(key, context);
+            return;
+        }
+        if (!existing.description && context.description) {
+            contextMap.set(key, context);
+        }
+    });
+    return [...contextMap.values()];
+};
+const resolveTagNameMap = (contexts, strategy) => {
+    const nameMap = new Map();
+    contexts.forEach((context) => {
+        const key = getTagContextKey(context.segments);
+        const initialName = strategy === 'chain' ? getChainTagName(context.segments) : getLeafTagName(context.segments);
+        nameMap.set(key, initialName || getChainTagName(context.segments));
+    });
+    if (strategy === 'chain') {
+        return nameMap;
+    }
+    const initialCounts = new Map();
+    nameMap.forEach((name) => {
+        initialCounts.set(name, (initialCounts.get(name) ?? 0) + 1);
+    });
+    contexts.forEach((context) => {
+        const key = getTagContextKey(context.segments);
+        const currentName = nameMap.get(key);
+        if (!currentName) {
+            return;
+        }
+        if ((initialCounts.get(currentName) ?? 0) > 1) {
+            nameMap.set(key, getLeafDuplicateFallback(context.segments, currentName));
+        }
+    });
+    const fallbackCounts = new Map();
+    nameMap.forEach((name) => {
+        fallbackCounts.set(name, (fallbackCounts.get(name) ?? 0) + 1);
+    });
+    contexts.forEach((context) => {
+        const key = getTagContextKey(context.segments);
+        const currentName = nameMap.get(key);
+        if (!currentName) {
+            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))];
+        if ((fallbackCounts.get(currentName) ?? 0) > 1) {
+            nameMap.set(key, getChainTagName(context.segments));
+        }
+    });
+    return nameMap;
+};
+const buildTagMetadata = (contexts, strategy) => {
+    const uniqueContexts = dedupeTagContexts(contexts);
+    const resolvedNameMap = resolveTagNameMap(uniqueContexts, strategy);
+    const tags = [];
+    const seenNames = new Set();
+    uniqueContexts.forEach((context) => {
+        const key = getTagContextKey(context.segments);
+        const name = resolvedNameMap.get(key);
+        if (!name || seenNames.has(name)) {
+            return;
+        }
+        seenNames.add(name);
+        const contextDescription = strategy === 'leaf' ? buildLeafTagContextDescription(context.segments) : undefined;
+        const description = mergeTagDescriptions(context.description, contextDescription);
+        tags.push({
+            name,
+            ...(description && { description }),
+        });
+    });
+    const resolveTagName = (segments) => {
+        if (segments.length === 0) {
+            return undefined;
+        }
+        const fromMap = resolvedNameMap.get(getTagContextKey(segments));
+        if (fromMap) {
+            return fromMap;
+        }
+        if (strategy === 'chain') {
+            return getChainTagName(segments);
+        }
+        return getLeafTagName(segments) || getChainTagName(segments);
     };
-    return items.flatMap((item) => collectTags(item));
+    return { tags, resolveTagName };
 };
+const collectTagContexts = (items, parentSegments = []) => items.flatMap((item) => {
+    if (!isItemGroup(item)) {
+        return [];
+    }
+    const nextSegments = item.name ? [...parentSegments, item.name] : parentSegments;
+    const currentContext = item.name?.length
+        ? [
+            {
+                segments: nextSegments,
+                description: normalizeDescription(item.description),
+            },
+        ]
+        : [];
+    return [...currentContext, ...collectTagContexts(item.item, nextSegments)];
+});
+const extractTags = (items, strategy) => buildTagMetadata(collectTagContexts(items), strategy);
 /**
- * Folder tags for ancestors of each selected path only (same shape as {@link extractTags}).
+ * Folder tags for ancestors of each selected path only (same shape as full extraction).
  */
-const extractTagsForSelectedPaths = (items, paths) => {
+const extractTagContextsForSelectedPaths = (items, paths) => {
     const seen = new Set();
     const result = [];
     for (const path of paths) {
@@ -89,7 +227,7 @@ const extractTagsForSelectedPaths = (items, paths) => {
             continue;
         }
         let list = items;
-        let parentPath = '';
+        const segments = [];
         for (let i = 0; i < path.length - 1; i++) {
             const idx = path[i];
             if (idx === undefined || idx < 0 || idx >= list.length) {
@@ -99,21 +237,23 @@ const extractTagsForSelectedPaths = (items, paths) => {
             if (node === undefined || !isItemGroup(node)) {
                 break;
             }
-            const nextPath = node.name ? (parentPath ? `${parentPath} > ${node.name}` : node.name) : parentPath;
-            const description = normalizeDescription(node.description);
-            if (node.name?.length && !seen.has(nextPath)) {
-                seen.add(nextPath);
-                result.push({
-                    name: nextPath,
-                    ...(description && { description }),
-                });
+            if (node.name?.length) {
+                segments.push(node.name);
+                const key = getTagContextKey(segments);
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    result.push({
+                        segments: [...segments],
+                        description: normalizeDescription(node.description),
+                    });
+                }
             }
-            parentPath = nextPath;
             list = node.item;
         }
     }
     return result;
 };
+const extractTagsForSelectedPaths = (items, paths, strategy) => buildTagMetadata(extractTagContextsForSelectedPaths(items, paths), strategy);
 const getNodeAtPath = (items, path) => {
     if (path.length === 0) {
         return undefined;
@@ -178,11 +318,13 @@ const mergeSecuritySchemes = (openapi, securitySchemes) => {
     };
 };
 const mergeServerLists = (existing, incoming) => {
-    const seen = new Set((existing ?? []).map((s) => s.url));
+    const createServerKey = (server) => JSON.stringify(server);
+    const seen = new Set((existing ?? []).map(createServerKey));
     const out = [...(existing ?? [])];
     for (const server of incoming) {
-        if (!seen.has(server.url)) {
-            seen.add(server.url);
+        const serverKey = createServerKey(server);
+        if (!seen.has(serverKey)) {
+            seen.add(serverKey);
             out.push(server);
         }
     }
@@ -241,6 +383,7 @@ const cleanupOperations = (paths) => {
             delete operation[POSTMAN_EXAMPLE_NAME_EXTENSION];
             delete operation[POSTMAN_PRE_REQUEST_SCRIPTS_EXTENSION];
             delete operation[POSTMAN_POST_RESPONSE_SCRIPTS_EXTENSION];
+            delete operation[POSTMAN_FOLDER_SEGMENTS_EXTENSION];
         });
     });
 };
@@ -351,20 +494,24 @@ const findFolderTemplateHint = (pathItemGroup, signature) => {
             if (!operation) {
                 continue;
             }
+            // Use the raw Postman folder chain if available; otherwise fall back to
+            // splitting tag strings (supports the legacy chain tag naming strategy).
+            const rawSegments = operation[POSTMAN_FOLDER_SEGMENTS_EXTENSION];
+            const folderNameCandidates = rawSegments ? [...rawSegments] : [];
             for (const tag of operation.tags ?? []) {
-                const folderNames = tag.split(' > ').map((segment) => segment.trim());
-                for (const folderName of folderNames) {
-                    if (!folderName.startsWith('/')) {
-                        continue;
-                    }
-                    const normalizedFolderName = normalizePath(folderName);
-                    if (getPathStructuralSignature(normalizedFolderName) !== signature) {
-                        continue;
-                    }
-                    const folderParameterNames = getOrderedPathParameterNames(normalizedFolderName);
-                    if (folderParameterNames.length === parameterNames.length) {
-                        return folderParameterNames;
-                    }
+                folderNameCandidates.push(...tag.split(' > ').map((segment) => segment.trim()));
+            }
+            for (const folderName of folderNameCandidates) {
+                if (!folderName.startsWith('/')) {
+                    continue;
+                }
+                const normalizedFolderName = normalizePath(folderName);
+                if (getPathStructuralSignature(normalizedFolderName) !== signature) {
+                    continue;
+                }
+                const folderParameterNames = getOrderedPathParameterNames(normalizedFolderName);
+                if (folderParameterNames.length === parameterNames.length) {
+                    return folderParameterNames;
                 }
             }
         }
@@ -432,7 +579,7 @@ const unifyEquivalentPathParameters = (paths) => {
  * and items to create a corresponding OpenAPI structure.
  */
 export function convert(postmanCollection, options = { mergeOperation: false }) {
-    const { requestIndexPaths, mergeOperation = false, document: baseDocument } = options;
+    const { requestIndexPaths, mergeOperation = false, tagNamingStrategy = 'leaf', document: baseDocument, keepHeaders, } = options;
     const isMergingIntoBase = baseDocument !== undefined;
     const collection = validateCollectionShape(parseCollectionInput(postmanCollection));
     // Extract title from collection info, fallback to 'API' if not provided
@@ -480,11 +627,12 @@ export function convert(postmanCollection, options = { mergeOperation: false })
     }
     // Process each item in the collection and merge into OpenAPI spec
     const allServerUsage = [];
+    const collectionVariableLookup = createCollectionVariableLookup(collection.variable);
     if (collection.item) {
         const usePathFilter = requestIndexPaths !== undefined;
         if (usePathFilter) {
             const uniquePaths = dedupeIndexPaths(requestIndexPaths);
-            const tags = extractTagsForSelectedPaths(collection.item, uniquePaths);
+            const { tags, resolveTagName } = extractTagsForSelectedPaths(collection.item, uniquePaths, tagNamingStrategy);
             assignTagsFromPostman(openapi, tags, isMergingIntoBase);
             for (const path of uniquePaths) {
                 const node = getNodeAtPath(collection.item, path);
@@ -492,7 +640,7 @@ export function convert(postmanCollection, options = { mergeOperation: false })
                     continue;
                 }
                 const parentTags = collectParentTagSegments(collection.item, path);
-                const { paths: itemPaths, components: itemComponents, serverUsage, } = processItem(node, DEFAULT_EXAMPLE_NAME, parentTags, '', mergeOperation);
+                const { paths: itemPaths, components: itemComponents, serverUsage, } = processItem(node, DEFAULT_EXAMPLE_NAME, parentTags, '', mergeOperation, resolveTagName, collectionVariableLookup, keepHeaders);
                 allServerUsage.push(...serverUsage);
                 for (const [pathKey, pathItem] of Object.entries(itemPaths)) {
                     const normalizedPathKey = normalizePath(pathKey);
@@ -507,10 +655,10 @@ export function convert(postmanCollection, options = { mergeOperation: false })
             }
         }
         else {
-            const tags = extractTags(collection.item);
+            const { tags, resolveTagName } = extractTags(collection.item, tagNamingStrategy);
             assignTagsFromPostman(openapi, tags, isMergingIntoBase);
             collection.item.forEach((item) => {
-                const { paths: itemPaths, components: itemComponents, serverUsage, } = processItem(item, DEFAULT_EXAMPLE_NAME, [], '', mergeOperation);
+                const { paths: itemPaths, components: itemComponents, serverUsage, } = processItem(item, DEFAULT_EXAMPLE_NAME, [], '', mergeOperation, resolveTagName, collectionVariableLookup, keepHeaders);
                 allServerUsage.push(...serverUsage);
                 openapi.paths = openapi.paths || {};
                 for (const [pathKey, pathItem] of Object.entries(itemPaths)) {

package/dist/helpers/header-utils.d.ts

@@ -0,0 +1,21 @@
+import type { HeaderList } from '../types.js';
+type RequestHeaders = HeaderList | string | null | undefined;
+/**
+ * Looks up a header value case-insensitively. Returns the value of the first
+ * non-disabled match, or undefined. Silently ignores string-typed headers
+ * (Postman occasionally stores them that way).
+ */
+export declare function readHeader(headers: RequestHeaders, name: string): string | undefined;
+/**
+ * Normalises a raw Content-Type header value (`application/json; charset=utf-8`)
+ * to just the media type (`application/json`). Returns undefined for empty input.
+ */
+export declare function parseMediaType(value: string | undefined): string | undefined;
+/**
+ * Picks a single media type from an Accept header value, preferring
+ * `application/json` if present, else the first non-wildcard type. Returns
+ * undefined for `*​/*` alone, empty input, or only wildcard types.
+ */
+export declare function pickAcceptMediaType(value: string | undefined): string | undefined;
+export {};
+//# sourceMappingURL=header-utils.d.ts.map

package/dist/helpers/header-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header-utils.d.ts","sourceRoot":"","sources":["../../src/helpers/header-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,UAAU,EAAE,MAAM,SAAS,CAAA;AAEjD,KAAK,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;AAE5D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOpF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAM5E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAYjF"}

package/dist/helpers/header-utils.js

@@ -0,0 +1,42 @@
+/**
+ * Looks up a header value case-insensitively. Returns the value of the first
+ * non-disabled match, or undefined. Silently ignores string-typed headers
+ * (Postman occasionally stores them that way).
+ */
+export function readHeader(headers, name) {
+    if (!headers || typeof headers === 'string' || !Array.isArray(headers)) {
+        return undefined;
+    }
+    const target = name.toLowerCase();
+    const match = headers.find((h) => h.key?.toLowerCase() === target && !h.disabled);
+    return match?.value;
+}
+/**
+ * Normalises a raw Content-Type header value (`application/json; charset=utf-8`)
+ * to just the media type (`application/json`). Returns undefined for empty input.
+ */
+export function parseMediaType(value) {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.split(';')[0]?.trim().toLowerCase();
+    return trimmed || undefined;
+}
+/**
+ * Picks a single media type from an Accept header value, preferring
+ * `application/json` if present, else the first non-wildcard type. Returns
+ * undefined for `*​/*` alone, empty input, or only wildcard types.
+ */
+export function pickAcceptMediaType(value) {
+    if (!value) {
+        return undefined;
+    }
+    const types = value
+        .split(',')
+        .map((t) => parseMediaType(t))
+        .filter((t) => !!t && t !== '*/*');
+    if (types.length === 0) {
+        return undefined;
+    }
+    return types.find((t) => t === 'application/json') ?? types[0];
+}

package/dist/helpers/parameters.d.ts

@@ -3,8 +3,11 @@ import type { Request } from '../types.js';
 /**
  * Extracts parameters from a Postman request and converts them to OpenAPI parameter objects.
  * Processes query, path, and header parameters from the request URL and headers.
+ *
+ * Headers on the built-in block-list (content negotiation, transport, auth) are
+ * dropped unless the caller passes them via `keepHeaders` (case-insensitive).
  */
-export declare function extractParameters(request: Request, exampleName: string): OpenAPIV3_1.ParameterObject[];
+export declare function extractParameters(request: Request, exampleName: string, keepHeaders?: readonly string[]): OpenAPIV3_1.ParameterObject[];
 /**
  * Creates an OpenAPI parameter object from a Postman parameter.
  */

package/dist/helpers/parameters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../src/helpers/parameters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAU,OAAO,EAAE,MAAM,SAAS,CAAA;AAI9C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW,CAAC,eAAe,EAAE,CA2DtG;AAoBD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,EACpC,WAAW,EAAE,MAAM,GAClB,WAAW,CAAC,eAAe,CAwD7B"}
+{"version":3,"file":"parameters.d.ts","sourceRoot":"","sources":["../../src/helpers/parameters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAU,OAAO,EAAE,MAAM,SAAS,CAAA;AAuC9C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,WAAW,CAAC,eAAe,EAAE,CA8D/B;AAoBD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,EACpC,WAAW,EAAE,MAAM,GAClB,WAAW,CAAC,eAAe,CAwD7B"}

package/dist/helpers/parameters.js

@@ -1,9 +1,45 @@
 import { inferSchemaType } from './schemas.js';
+/**
+ * Header keys (lower-case) that never become `parameters[in=header]` on an
+ * OpenAPI operation. They either describe the transport (Host, Connection),
+ * overlap with `requestBody.content` / `responses.content` (Accept,
+ * Content-Type), or belong in `components.securitySchemes` (Authorization,
+ * Cookie). Callers can opt a specific name back in via `ConvertOptions.keepHeaders`.
+ */
+const BLOCKED_HEADERS = new Set([
+    // Content negotiation
+    'accept',
+    'accept-encoding',
+    'accept-language',
+    'content-type',
+    // Transport / hop-by-hop
+    'connection',
+    'content-length',
+    'host',
+    'transfer-encoding',
+    // Auth — belong in components.securitySchemes
+    'authorization',
+    'cookie',
+    'proxy-authorization',
+]);
+function isBlockedHeader(name, keepHeaders) {
+    if (!name) {
+        return false;
+    }
+    const lower = name.toLowerCase();
+    if (keepHeaders?.some((kept) => kept.toLowerCase() === lower)) {
+        return false;
+    }
+    return BLOCKED_HEADERS.has(lower);
+}
 /**
  * Extracts parameters from a Postman request and converts them to OpenAPI parameter objects.
  * Processes query, path, and header parameters from the request URL and headers.
+ *
+ * Headers on the built-in block-list (content negotiation, transport, auth) are
+ * dropped unless the caller passes them via `keepHeaders` (case-insensitive).
  */
-export function extractParameters(request, exampleName) {
+export function extractParameters(request, exampleName, keepHeaders) {
     const parameters = [];
     const parameterMap = new Map();
     if (typeof request === 'string' || !request.url) {
@@ -48,6 +84,9 @@ export function extractParameters(request, exampleName) {
     // Process header parameters
     if (request.header && Array.isArray(request.header)) {
         request.header.forEach((header) => {
+            if (isBlockedHeader(header.key, keepHeaders)) {
+                return;
+            }
             const paramObj = createParameterObject(header, 'header', exampleName);
             if (paramObj.name) {
                 parameterMap.set(paramObj.name, paramObj);

package/dist/helpers/path-items.d.ts

@@ -4,21 +4,24 @@ type HttpMethods = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'pat
 export declare const POSTMAN_EXAMPLE_NAME_EXTENSION = "x-postman-example-name";
 export declare const POSTMAN_PRE_REQUEST_SCRIPTS_EXTENSION = "x-postman-pre-request-scripts";
 export declare const POSTMAN_POST_RESPONSE_SCRIPTS_EXTENSION = "x-postman-post-response-scripts";
+export declare const POSTMAN_FOLDER_SEGMENTS_EXTENSION = "x-postman-folder-segments";
 /**
  * Information about server usage for an operation.
  */
 export type ServerUsage = {
     serverUrl: string;
+    server?: OpenAPIV3_1.ServerObject;
     path: string;
     method: HttpMethods;
 };
+type CollectionVariableLookup = ReadonlyMap<string, string>;
 /**
  * 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 declare function processItem(item: Item | ItemGroup, exampleName?: string, parentTags?: string[], parentPath?: string, preserveCollapsedVariants?: boolean): {
+export declare function processItem(item: Item | ItemGroup, exampleName?: string, parentTags?: string[], parentPath?: string, preserveCollapsedVariants?: boolean, resolveTagName?: (segments: string[]) => string | undefined, collectionVariableLookup?: CollectionVariableLookup, keepHeaders?: readonly string[]): {
     paths: OpenAPIV3_1.PathsObject;
     components: OpenAPIV3_1.ComponentsObject;
     serverUsage: ServerUsage[];

package/dist/helpers/path-items.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-items.d.ts","sourceRoot":"","sources":["../../src/helpers/path-items.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAW9C,KAAK,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAE7F,eAAO,MAAM,8BAA8B,2BAA2B,CAAA;AACtE,eAAO,MAAM,qCAAqC,kCAAkC,CAAA;AACpF,eAAO,MAAM,uCAAuC,oCAAoC,CAAA;AAExF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,WAAW,CAAA;CACpB,CAAA;AAoBD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,IAAI,GAAG,SAAS,EACtB,WAAW,GAAE,MAAkB,EAC/B,UAAU,GAAE,MAAM,EAAO,EACzB,UAAU,GAAE,MAAW,EACvB,yBAAyB,GAAE,OAAe,GACzC;IACD,KAAK,EAAE,WAAW,CAAC,WAAW,CAAA;IAC9B,UAAU,EAAE,WAAW,CAAC,gBAAgB,CAAA;IACxC,WAAW,EAAE,WAAW,EAAE,CAAA;CAC3B,CAoMA;AAED,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAkCpD"}
+{"version":3,"file":"path-items.d.ts","sourceRoot":"","sources":["../../src/helpers/path-items.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAY9C,KAAK,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAE7F,eAAO,MAAM,8BAA8B,2BAA2B,CAAA;AACtE,eAAO,MAAM,qCAAqC,kCAAkC,CAAA;AACpF,eAAO,MAAM,uCAAuC,oCAAoC,CAAA;AAIxF,eAAO,MAAM,iCAAiC,8BAA8B,CAAA;AAE5E;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC,YAAY,CAAA;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,WAAW,CAAA;CACpB,CAAA;AAED,KAAK,wBAAwB,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAoB3D;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,IAAI,GAAG,SAAS,EACtB,WAAW,GAAE,MAAkB,EAC/B,UAAU,GAAE,MAAM,EAAO,EACzB,UAAU,GAAE,MAAW,EACvB,yBAAyB,GAAE,OAAe,EAC1C,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,MAAM,GAAG,SAAS,EAC3D,wBAAwB,GAAE,wBAAoC,EAC9D,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B;IACD,KAAK,EAAE,WAAW,CAAC,WAAW,CAAA;IAC9B,UAAU,EAAE,WAAW,CAAC,gBAAgB,CAAA;IACxC,WAAW,EAAE,WAAW,EAAE,CAAA;CAC3B,CAoNA;AAED,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAkCpD"}

package/dist/helpers/path-items.js

@@ -1,14 +1,19 @@
 import { processAuth } from './auth.js';
+import { parseMediaType, pickAcceptMediaType, readHeader } from './header-utils.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 { DEFAULT_RESPONSE_DESCRIPTIONS, extractResponses } from './responses.js';
-import { extractPathFromUrl, extractPathParameterNames, extractServerFromUrl, normalizePath } from './urls.js';
+import { extractPathFromUrl, extractPathParameterNames, extractServerObjectFromUrl, normalizePath } from './urls.js';
 export const POSTMAN_EXAMPLE_NAME_EXTENSION = 'x-postman-example-name';
 export const POSTMAN_PRE_REQUEST_SCRIPTS_EXTENSION = 'x-postman-pre-request-scripts';
 export const POSTMAN_POST_RESPONSE_SCRIPTS_EXTENSION = 'x-postman-post-response-scripts';
+// Raw Postman folder-name chain for the operation. Used internally to preserve
+// template hints (for example `/applications/{id}`) even when tag names are
+// simplified. Stripped before emitting the final OpenAPI document.
+export const POSTMAN_FOLDER_SEGMENTS_EXTENSION = 'x-postman-folder-segments';
 function ensureRequestBodyContent(requestBody) {
     const content = requestBody.content ?? {};
     if (Object.keys(content).length === 0) {
@@ -30,14 +35,14 @@ function ensureRequestBodyContent(requestBody) {
  * Handles nested item groups, extracts request details, and generates corresponding
  * OpenAPI path items and operations.
  */
-export function processItem(item, exampleName = 'default', parentTags = [], parentPath = '', preserveCollapsedVariants = false) {
+export function processItem(item, exampleName = 'default', parentTags = [], parentPath = '', preserveCollapsedVariants = false, resolveTagName, collectionVariableLookup = new Map(), keepHeaders) {
     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, exampleName, newParentTags, `${parentPath}/${item.name || ''}`, preserveCollapsedVariants);
+            const childResult = processItem(childItem, exampleName, newParentTags, `${parentPath}/${item.name || ''}`, preserveCollapsedVariants, resolveTagName, collectionVariableLookup, keepHeaders);
             // Merge child paths and components
             for (const [pathKey, pathItem] of Object.entries(childResult.paths)) {
                 if (!paths[pathKey]) {
@@ -74,10 +79,11 @@ export function processItem(item, exampleName = 'default', parentTags = [], pare
     // Normalize path parameters from ':param' to '{param}'
     const normalizedPath = normalizePath(path);
     // Extract server URL from request URL
-    const serverUrl = extractServerFromUrl(requestUrl);
-    if (serverUrl) {
+    const server = extractServerObjectFromUrl(requestUrl, collectionVariableLookup);
+    if (server?.url) {
         serverUsage.push({
-            serverUrl,
+            serverUrl: server.url,
+            server,
             path: normalizedPath,
             method,
         });
@@ -91,13 +97,23 @@ export function processItem(item, exampleName = 'default', parentTags = [], pare
         : typeof request.description === 'string'
             ? request.description
             : (request.description?.content ?? '');
+    const tagName = parentTags.length > 0 ? (resolveTagName ? resolveTagName(parentTags) : parentTags.join(' > ')) : undefined;
+    // Derive media-type signals from request headers before they are filtered out
+    // of `parameters[in=header]`. Content-Type drives the request body media type;
+    // Accept drives responses when no saved-response Content-Type is available.
+    const requestHeaders = typeof request === 'string' ? undefined : request.header;
+    const contentType = parseMediaType(readHeader(requestHeaders, 'Content-Type'));
+    const acceptMediaType = pickAcceptMediaType(readHeader(requestHeaders, 'Accept'));
     const operationObject = {
-        tags: parentTags.length > 0 ? [parentTags.join(' > ')] : undefined,
+        tags: tagName ? [tagName] : undefined,
         summary,
         description,
-        responses: extractResponses(response || [], item),
+        responses: extractResponses(response || [], item, acceptMediaType),
         parameters: [],
     };
+    if (parentTags.length > 0) {
+        operationObject[POSTMAN_FOLDER_SEGMENTS_EXTENSION] = [...parentTags];
+    }
     if (preserveCollapsedVariants) {
         operationObject[POSTMAN_EXAMPLE_NAME_EXTENSION] = sourceRequestName;
     }
@@ -127,7 +143,7 @@ export function processItem(item, exampleName = 'default', parentTags = [], pare
     }
     // Extract parameters from the request (query, path, header)
     // This should always happen, regardless of whether a description exists
-    const extractedParameters = extractParameters(request, operationExampleName);
+    const extractedParameters = extractParameters(request, operationExampleName, keepHeaders);
     // 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
@@ -174,7 +190,7 @@ export function processItem(item, exampleName = 'default', parentTags = [], pare
     }
     // Allow request bodies for all methods (including GET) if body is present
     if (typeof request !== 'string' && request.body) {
-        const requestBody = extractRequestBody(request.body, operationExampleName);
+        const requestBody = extractRequestBody(request.body, operationExampleName, contentType);
         ensureRequestBodyContent(requestBody);
         // Only add requestBody if it has content
         if (requestBody.content && Object.keys(requestBody.content).length > 0) {

package/dist/helpers/request-body.d.ts

@@ -3,6 +3,10 @@ import type { RequestBody } from '../types.js';
 /**
  * Extracts and converts the request body from a Postman request to an OpenAPI RequestBodyObject.
  * Handles raw JSON, form-data, and URL-encoded body types, creating appropriate schemas and content types.
+ *
+ * When `contentType` is provided (already normalised via `parseMediaType`), it
+ * wins over the Postman `options.raw.language` hint for `raw` bodies.
+ * `formdata` and `urlencoded` modes keep their natural media types.
  */
-export declare function extractRequestBody(body: RequestBody, exampleName: string): OpenAPIV3_1.RequestBodyObject;
+export declare function extractRequestBody(body: RequestBody, exampleName: string, contentType?: string): OpenAPIV3_1.RequestBodyObject;
 //# sourceMappingURL=request-body.d.ts.map

package/dist/helpers/request-body.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-body.d.ts","sourceRoot":"","sources":["../../src/helpers/request-body.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAiB,WAAW,EAAuB,MAAM,SAAS,CAAA;AAK9E;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW,CAAC,iBAAiB,CAqBxG"}
+{"version":3,"file":"request-body.d.ts","sourceRoot":"","sources":["../../src/helpers/request-body.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAiB,WAAW,EAAuB,MAAM,SAAS,CAAA;AAK9E;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,GACnB,WAAW,CAAC,iBAAiB,CAqB/B"}

package/dist/helpers/request-body.js

@@ -3,13 +3,17 @@ import { createParameterObject } from './parameters.js';
 /**
  * Extracts and converts the request body from a Postman request to an OpenAPI RequestBodyObject.
  * Handles raw JSON, form-data, and URL-encoded body types, creating appropriate schemas and content types.
+ *
+ * When `contentType` is provided (already normalised via `parseMediaType`), it
+ * wins over the Postman `options.raw.language` hint for `raw` bodies.
+ * `formdata` and `urlencoded` modes keep their natural media types.
  */
-export function extractRequestBody(body, exampleName) {
+export function extractRequestBody(body, exampleName, contentType) {
     const requestBody = {
         content: {},
     };
     if (body.mode === 'raw') {
-        handleRawBody(body, requestBody, exampleName);
+        handleRawBody(body, requestBody, exampleName, contentType);
         return requestBody;
     }
     if (body.mode === 'formdata' && body.formdata) {
@@ -22,11 +26,11 @@ export function extractRequestBody(body, exampleName) {
     }
     return requestBody;
 }
-function handleRawBody(body, requestBody, exampleName) {
+function handleRawBody(body, requestBody, exampleName, contentType) {
     const rawBody = body.raw || '';
     const isJsonLanguage = body.options?.raw?.language === 'json';
-    // If we have valid JSON, use it
-    if (isJsonLanguage) {
+    const mediaType = contentType ?? (isJsonLanguage ? 'application/json' : 'text/plain');
+    if (mediaType === 'application/json') {
         requestBody.content = {
             'application/json': {
                 schema: {
@@ -41,12 +45,27 @@ function handleRawBody(body, requestBody, exampleName) {
         };
         return;
     }
-    // Fallback to text/plain
+    if (mediaType === 'text/plain') {
+        requestBody.content = {
+            'text/plain': {
+                schema: {
+                    type: 'string',
+                    examples: rawBody ? [rawBody] : undefined,
+                },
+            },
+        };
+        return;
+    }
+    // Any other caller-declared media type (application/xml, text/csv, application/octet-stream, ...)
     requestBody.content = {
-        'text/plain': {
+        [mediaType]: {
             schema: {
                 type: 'string',
-                examples: rawBody ? [rawBody] : undefined,
+            },
+            examples: {
+                [exampleName]: {
+                    value: rawBody,
+                },
             },
         },
     };

package/dist/helpers/responses.d.ts

@@ -5,6 +5,12 @@ export declare const DEFAULT_RESPONSE_DESCRIPTIONS: Record<string, string>;
  * Extracts and converts Postman response objects to OpenAPI response objects.
  * Processes response status codes, descriptions, headers, and body content,
  * inferring schemas from example responses when possible.
+ *
+ * Media-type selection precedence for each response:
+ *   1. The saved response's own `Content-Type` header.
+ *   2. The request's `Accept` header (passed as `acceptMediaType`, already
+ *      narrowed via `pickAcceptMediaType`).
+ *   3. `application/json` fallback.
  */
-export declare function extractResponses(responses: Response[], item?: Item): OpenAPIV3_1.ResponsesObject | undefined;
+export declare function extractResponses(responses: Response[], item?: Item, acceptMediaType?: string): OpenAPIV3_1.ResponsesObject | undefined;
 //# sourceMappingURL=responses.d.ts.map

package/dist/helpers/responses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/helpers/responses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAc,IAAI,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAKzD,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAchE,CAAA;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,WAAW,CAAC,eAAe,GAAG,SAAS,CAwC5G"}
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/helpers/responses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAc,IAAI,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAMzD,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAchE,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,QAAQ,EAAE,EACrB,IAAI,CAAC,EAAE,IAAI,EACX,eAAe,CAAC,EAAE,MAAM,GACvB,WAAW,CAAC,eAAe,GAAG,SAAS,CA+DzC"}

package/dist/helpers/responses.js

@@ -1,3 +1,4 @@
+import { parseMediaType, readHeader } from './header-utils.js';
 import { inferSchemaFromExample } from './schemas.js';
 import { extractStatusCodesFromTests } from './status-codes.js';
 export const DEFAULT_RESPONSE_DESCRIPTIONS = {
@@ -19,36 +20,58 @@ export const DEFAULT_RESPONSE_DESCRIPTIONS = {
  * Extracts and converts Postman response objects to OpenAPI response objects.
  * Processes response status codes, descriptions, headers, and body content,
  * inferring schemas from example responses when possible.
+ *
+ * Media-type selection precedence for each response:
+ *   1. The saved response's own `Content-Type` header.
+ *   2. The request's `Accept` header (passed as `acceptMediaType`, already
+ *      narrowed via `pickAcceptMediaType`).
+ *   3. `application/json` fallback.
  */
-export function extractResponses(responses, item) {
+export function extractResponses(responses, item, acceptMediaType) {
     // Extract status codes from tests
     const statusCodes = item ? extractStatusCodesFromTests(item) : [];
     // Create a map of status codes to descriptions from responses
     const responseMap = responses.reduce((acc, response) => {
         const statusCode = response.code?.toString() || 'default';
-        acc[statusCode] = {
-            description: getResponseDescription(response, statusCode),
-            headers: extractHeaders(response.header),
-            content: {
-                'application/json': {
+        const hasNoContentStatusCode = hasNoResponseBodyStatusCode(statusCode);
+        const hasExplicitBodyExample = response.body !== undefined && response.body !== null && response.body !== '';
+        if (hasNoContentStatusCode && hasExplicitBodyExample) {
+            console.warn(`[postman-to-openapi] Response ${statusCode} usually has no body, but Postman includes a body example. Keeping OpenAPI content.`);
+        }
+        const savedContentType = parseMediaType(readHeader(response.header, 'Content-Type'));
+        const mediaType = savedContentType ?? acceptMediaType ?? 'application/json';
+        const content = hasNoContentStatusCode && !hasExplicitBodyExample
+            ? undefined
+            : {
+                [mediaType]: {
                     schema: inferSchemaFromExample(response.body || ''),
                     examples: {
                         default: tryParseJson(response.body || ''),
                     },
                 },
-            },
+            };
+        acc[statusCode] = {
+            description: getResponseDescription(response, statusCode),
+            headers: extractHeaders(response.header),
+            ...(content ? { content } : {}),
         };
         return acc;
     }, {});
     // Add status codes from tests if not already present
+    const fallbackMediaType = acceptMediaType ?? 'application/json';
     statusCodes.forEach((code) => {
         const codeStr = code.toString();
         if (!responseMap[codeStr]) {
+            const hasNoContentStatusCode = hasNoResponseBodyStatusCode(codeStr);
             responseMap[codeStr] = {
                 description: getDefaultResponseDescription(codeStr),
-                content: {
-                    'application/json': {},
-                },
+                ...(!hasNoContentStatusCode
+                    ? {
+                        content: {
+                            [fallbackMediaType]: {},
+                        },
+                    }
+                    : {}),
             };
         }
     });
@@ -100,6 +123,13 @@ function isThreeDigitStatusCode(value) {
     }
     return true;
 }
+const hasNoResponseBodyStatusCode = (statusCode) => {
+    const numericCode = Number(statusCode);
+    if (!Number.isInteger(numericCode)) {
+        return false;
+    }
+    return (numericCode >= 100 && numericCode <= 199) || numericCode === 204 || numericCode === 205 || numericCode === 304;
+};
 function extractHeaders(headers) {
     if (!headers || typeof headers === 'string') {
         return undefined;

package/dist/helpers/servers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"servers.d.ts","sourceRoot":"","sources":["../../src/helpers/servers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB,QAAQ,EAAE,WAAW,CAAC,YAAY,EAAE,CAAA;IACpC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,CAAA;IAClD,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAAA;CACjE,CAAA;AAsBD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,WAAW,EAAE,EAAE,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,eAAe,CAuElH"}
+{"version":3,"file":"servers.d.ts","sourceRoot":"","sources":["../../src/helpers/servers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB,QAAQ,EAAE,WAAW,CAAC,YAAY,EAAE,CAAA;IACpC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,CAAA;IAClD,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAAA;CACjE,CAAA;AAsBD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,WAAW,EAAE,EAAE,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,eAAe,CA0ElH"}

package/dist/helpers/servers.js

@@ -33,18 +33,22 @@ export function analyzeServerDistribution(serverUsage, allUniquePaths) {
     if (serverUsage.length === 0) {
         return placement;
     }
-    // Build a map: serverUrl -> Set<operationKey>
+    // Build a map: serverKey -> { server, operations }
     // Using string keys instead of objects because JavaScript Sets compare by reference
     const serverMap = new Map();
     for (const usage of serverUsage) {
-        if (!serverMap.has(usage.serverUrl)) {
-            serverMap.set(usage.serverUrl, new Set());
+        const serverObject = usage.server ?? { url: usage.serverUrl };
+        const serverKey = JSON.stringify(serverObject);
+        if (!serverMap.has(serverKey)) {
+            serverMap.set(serverKey, {
+                server: serverObject,
+                operations: new Set(),
+            });
         }
-        serverMap.get(usage.serverUrl).add(createOperationKey(usage.path, usage.method));
+        serverMap.get(serverKey).operations.add(createOperationKey(usage.path, usage.method));
     }
     // For each server, determine its placement
-    for (const [serverUrl, operationKeys] of serverMap.entries()) {
-        const serverObject = { url: serverUrl };
+    for (const { server: serverObject, operations: operationKeys } of serverMap.values()) {
         // Parse operation keys back to path/method pairs
         const operations = Array.from(operationKeys).map(parseOperationKey);
         // Count unique paths this server appears in

package/dist/helpers/urls.d.ts

@@ -1,3 +1,4 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
 /**
  * Extracts the domain (including protocol and port if present) from a given URL.
  */
@@ -11,6 +12,15 @@ export declare function extractPathFromUrl(url: string | undefined): string;
  * e.g., '/users/:id' becomes '/users/{id}'
  */
 export declare const normalizePath: (path: string) => string;
+type CollectionVariableLookup = ReadonlyMap<string, string>;
+/**
+ * Extracts Postman collection variables into a lookup table.
+ */
+export declare function createCollectionVariableLookup(variables: ReadonlyArray<{
+    key?: string;
+    value?: string | number | boolean;
+    disabled?: boolean;
+}> | undefined): ReadonlyMap<string, string>;
 /**
  * Generates a structural path signature by replacing parameter segments with `{*}`.
  * Paths with the same signature are equivalent except for parameter names.
@@ -27,4 +37,9 @@ export declare function extractPathParameterNames(path: string): string[];
  * Returns undefined if no valid server URL can be extracted.
  */
 export declare function extractServerFromUrl(url: string | undefined): string | undefined;
+/**
+ * Extracts the server object from a request URL and resolves Postman templates.
+ */
+export declare function extractServerObjectFromUrl(url: string | undefined, collectionVariableLookup?: CollectionVariableLookup): OpenAPIV3_1.ServerObject | undefined;
+export {};
 //# sourceMappingURL=urls.d.ts.map

package/dist/helpers/urls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../src/helpers/urls.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAYlE;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MAAyC,CAAA;AAEtF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,MAAM,KAAG,MAWzD,CAAA;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAahE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAyBhF"}
+{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../src/helpers/urls.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAoBxD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAYlE;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MAAyC,CAAA;AAEtF,KAAK,wBAAwB,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AA8B3D;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,aAAa,CAAC;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,SAAS,GAC5G,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7B;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,MAAM,KAAG,MAWzD,CAAA;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAahE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEhF;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,wBAAwB,GAAE,wBAAoC,GAC7D,WAAW,CAAC,YAAY,GAAG,SAAS,CAsEtC"}

package/dist/helpers/urls.js

@@ -1,4 +1,7 @@
 import { REGEX } from '@scalar/helpers/regex/regex-helpers';
+const POSTMAN_TEMPLATE_REGEX = /\{\{([^{}]{0,1000})\}\}/g;
+const DEFAULT_SERVER_VARIABLE_VALUE = 'example.com';
+const SERVER_VARIABLE_DESCRIPTION = 'Declared in Postman collection variables.';
 /**
  * Parses a URL string into its component parts.
  */
@@ -27,7 +30,7 @@ export function extractPathFromUrl(url) {
     // Remove scheme, domain, query parameters, and hash fragments
     const path = url.replace(/^(?:https?:\/\/)?[^/]+(\/|$)/, '/').split(/[?#]/)[0] ?? '';
     // Replace Postman variables and ensure single leading slash
-    const finalPath = ('/' + path.replace(/\{\{([^{}]{0,1000})\}\}/g, '{$1}').replace(/^\/+/, '')).replace(/\/\/+/g, '/');
+    const finalPath = ('/' + path.replace(POSTMAN_TEMPLATE_REGEX, '{$1}').replace(/^\/+/, '')).replace(/\/\/+/g, '/');
     return finalPath;
 }
 /**
@@ -35,6 +38,41 @@ export function extractPathFromUrl(url) {
  * e.g., '/users/:id' becomes '/users/{id}'
  */
 export const normalizePath = (path) => path.replace(/:(\w+)/g, '{$1}');
+const isCompleteUrl = (value) => /^(https?:\/\/)/i.test(value);
+const hasPostmanTemplateSyntax = (value) => /\{\{([^{}]{0,1000})\}\}/.test(value);
+const createServerVariableDefinition = () => ({
+    default: DEFAULT_SERVER_VARIABLE_VALUE,
+    description: SERVER_VARIABLE_DESCRIPTION,
+});
+const extractFullHostTemplateVariableName = (rawServerUrl) => {
+    const protocolSeparatorIndex = rawServerUrl.indexOf('://');
+    if (protocolSeparatorIndex === -1) {
+        return undefined;
+    }
+    const hostCandidate = rawServerUrl.slice(protocolSeparatorIndex + 3);
+    if (!hostCandidate.startsWith('{{') || !hostCandidate.endsWith('}}')) {
+        return undefined;
+    }
+    const variableName = hostCandidate.slice(2, -2).trim();
+    if (!variableName || variableName.includes('{') || variableName.includes('}')) {
+        return undefined;
+    }
+    return variableName;
+};
+/**
+ * Extracts Postman collection variables into a lookup table.
+ */
+export function createCollectionVariableLookup(variables) {
+    const variableLookup = new Map();
+    for (const variable of variables ?? []) {
+        const key = variable.key?.trim();
+        if (!key || variable.disabled || variable.value === undefined) {
+            continue;
+        }
+        variableLookup.set(key, String(variable.value));
+    }
+    return variableLookup;
+}
 /**
  * Generates a structural path signature by replacing parameter segments with `{*}`.
  * Paths with the same signature are equivalent except for parameter names.
@@ -70,6 +108,12 @@ export function extractPathParameterNames(path) {
  * Returns undefined if no valid server URL can be extracted.
  */
 export function extractServerFromUrl(url) {
+    return extractServerObjectFromUrl(url)?.url;
+}
+/**
+ * Extracts the server object from a request URL and resolves Postman templates.
+ */
+export function extractServerObjectFromUrl(url, collectionVariableLookup = new Map()) {
     if (!url) {
         return undefined;
     }
@@ -84,8 +128,49 @@ export function extractServerFromUrl(url) {
         }
         const hostPart = urlMatch[1];
         // Preserve the original protocol if present, otherwise default to https
-        const serverUrl = protocol ? `${protocol}${hostPart}`.replace(/\/$/, '') : `https://${hostPart}`.replace(/\/$/, '');
-        return serverUrl;
+        const rawServerUrl = protocol
+            ? `${protocol}${hostPart}`.replace(/\/$/, '')
+            : `https://${hostPart}`.replace(/\/$/, '');
+        const templateMatches = Array.from(rawServerUrl.matchAll(POSTMAN_TEMPLATE_REGEX));
+        if (templateMatches.length === 0) {
+            return { url: rawServerUrl };
+        }
+        const unresolvedVariables = new Set();
+        const fullHostTemplateVariableName = extractFullHostTemplateVariableName(rawServerUrl);
+        if (fullHostTemplateVariableName) {
+            const variableName = fullHostTemplateVariableName;
+            const variableValue = collectionVariableLookup.get(variableName);
+            if (!variableValue || hasPostmanTemplateSyntax(variableValue)) {
+                unresolvedVariables.add(variableName);
+            }
+            else if (isCompleteUrl(variableValue)) {
+                return { url: variableValue.replace(/\/$/, '') };
+            }
+        }
+        const resolvedUrl = rawServerUrl.replace(POSTMAN_TEMPLATE_REGEX, (_, rawName) => {
+            const variableName = rawName.trim();
+            const variableValue = collectionVariableLookup.get(variableName);
+            if (!variableValue || hasPostmanTemplateSyntax(variableValue)) {
+                unresolvedVariables.add(variableName);
+                return `{${variableName}}`;
+            }
+            if (isCompleteUrl(variableValue)) {
+                unresolvedVariables.add(variableName);
+                return `{${variableName}}`;
+            }
+            return variableValue;
+        });
+        if (unresolvedVariables.size > 0) {
+            const variables = {};
+            for (const variableName of unresolvedVariables) {
+                variables[variableName] = createServerVariableDefinition();
+            }
+            return {
+                url: resolvedUrl,
+                variables,
+            };
+        }
+        return { url: resolvedUrl.replace(/\/$/, '') };
     }
     catch (error) {
         console.error(`Error extracting server from URL "${url}":`, error);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type ConvertOptions, type PostmanRequestIndexPath, convert } from './convert.js';
+export { type ConvertOptions, convert, type PostmanRequestIndexPath, type TagNamingStrategy } from './convert.js';
 export { isPostmanCollection } from './is-postman-collection.js';
 export { extractPathFromUrl, normalizePath } from './helpers/urls.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,uBAAuB,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACtF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,KAAK,uBAAuB,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC9G,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA"}

package/package.json

@@ -19,7 +19,7 @@
     "export",
     "scalar"
   ],
-  "version": "0.6.3",
+  "version": "0.7.0",
   "engines": {
     "node": ">=22"
   },
@@ -39,17 +39,16 @@
   ],
   "dependencies": {
     "@scalar/helpers": "0.5.1",
-    "@scalar/openapi-types": "0.7.0"
+    "@scalar/openapi-types": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",
     "vite": "8.0.0",
-    "@scalar/openapi-parser": "0.25.10"
+    "@scalar/openapi-parser": "0.25.11"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "evaluate": "tsx ./scripts/evaluate/run.ts",
-    "generate:textures": "tsx ./scripts/generate-textures.ts",
     "test": "vitest --run",
     "types:check": "tsc --noEmit"
   }