@postman-enricher/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Caio Pizzol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/enrichers/descriptions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Descriptions enricher - Adds rich markdown descriptions to collection, folders, and requests
+ */
+import type { PostmanCollection, DescriptionConfig } from '@postman-enricher/shared';
+/**
+ * Add descriptions to collection, folders, and requests
+ * @param collection - Postman collection
+ * @param config - Descriptions configuration
+ * @returns Collection with descriptions
+ */
+export declare function addDescriptions(collection: PostmanCollection, config: DescriptionConfig | undefined): PostmanCollection;

package/dist/enrichers/descriptions.js

@@ -0,0 +1,88 @@
+/**
+ * Descriptions enricher - Adds rich markdown descriptions to collection, folders, and requests
+ */
+import { walkCollection, isFolder, isRequest, getRequestMethod, } from '@postman-enricher/shared';
+/**
+ * Add descriptions to collection, folders, and requests
+ * @param collection - Postman collection
+ * @param config - Descriptions configuration
+ * @returns Collection with descriptions
+ */
+export function addDescriptions(collection, config) {
+    if (!config)
+        return collection;
+    // 1. Update collection-level info
+    if (config.collection) {
+        const collectionKey = Object.keys(config.collection).find((key) => collection.info.name.includes(key));
+        if (collectionKey) {
+            const collectionConfig = config.collection[collectionKey];
+            if (collectionConfig.name) {
+                collection.info.name = collectionConfig.name;
+            }
+            if (collectionConfig.description) {
+                collection.info.description = collectionConfig.description;
+            }
+        }
+    }
+    // 2. Add folder descriptions
+    if (config.folders) {
+        walkCollection(collection.item, (item) => {
+            if (isFolder(item)) {
+                const folderKey = item.name?.toLowerCase();
+                // Try exact match first
+                if (config.folders && config.folders[folderKey]) {
+                    item.description = config.folders[folderKey];
+                }
+                // Try without special characters
+                else {
+                    const cleanKey = folderKey?.replace(/[{}:]/g, '');
+                    if (config.folders && cleanKey && config.folders[cleanKey]) {
+                        item.description = config.folders[cleanKey];
+                    }
+                }
+            }
+        });
+    }
+    // 3. Add request descriptions
+    if (config.requests) {
+        walkCollection(collection.item, (item) => {
+            if (isRequest(item) && item.request) {
+                const requestName = item.name;
+                if (config.requests && config.requests[requestName]) {
+                    item.request.description = config.requests[requestName];
+                }
+                else {
+                    // Generate generic description if not specified
+                    item.request.description = generateGenericDescription(getRequestMethod(item), requestName);
+                }
+            }
+        });
+    }
+    return collection;
+}
+/**
+ * Generate a description based on HTTP method and name
+ * @param method - HTTP method
+ * @param name - Request name
+ * @returns Generated description
+ */
+function generateGenericDescription(method, name) {
+    const descriptions = {
+        GET: `Retrieve ${name
+            .toLowerCase()
+            .replace(/^get\s+/, '')
+            .replace(/^list\s+/, '')}`,
+        POST: `Create new ${name
+            .toLowerCase()
+            .replace(/^create\s+/, '')
+            .replace(/^add\s+/, '')}`,
+        PUT: `Update ${name.toLowerCase().replace(/^update\s+/, '')}`,
+        PATCH: `Partially update ${name.toLowerCase().replace(/^update\s+/, '')}`,
+        DELETE: `Delete ${name
+            .toLowerCase()
+            .replace(/^delete\s+/, '')
+            .replace(/^remove\s+/, '')}`,
+    };
+    return (descriptions[method] ||
+        `Perform ${method} operation on ${name.toLowerCase()}`);
+}

package/dist/enrichers/examples.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Examples enricher - Adds request body examples and response examples
+ */
+import type { PostmanCollection, ExampleConfig } from '@postman-enricher/shared';
+/**
+ * Add examples to requests and responses
+ * @param collection - Postman collection
+ * @param config - Examples configuration
+ * @returns Collection with examples
+ */
+export declare function addExamples(collection: PostmanCollection, config: ExampleConfig | undefined): PostmanCollection;

package/dist/enrichers/examples.js

@@ -0,0 +1,122 @@
+/**
+ * Examples enricher - Adds request body examples and response examples
+ */
+import { walkCollection, isRequest, getRequestMethod, } from '@postman-enricher/shared';
+/**
+ * Add examples to requests and responses
+ * @param collection - Postman collection
+ * @param config - Examples configuration
+ * @returns Collection with examples
+ */
+export function addExamples(collection, config) {
+    if (!config)
+        return collection;
+    walkCollection(collection.item, (item) => {
+        if (!isRequest(item) || !item.request)
+            return;
+        const requestName = item.name;
+        const method = getRequestMethod(item);
+        // Add request body examples
+        if (item.request?.body?.raw && config.requests?.[requestName]?.body) {
+            try {
+                const body = JSON.parse(item.request.body.raw);
+                const exampleBody = { ...body, ...config.requests[requestName].body };
+                item.request.body.raw = JSON.stringify(exampleBody, null, 2);
+            }
+            catch {
+                // Not JSON, skip
+            }
+        }
+        // Add response examples
+        if (config.responses?.[requestName]) {
+            const responseExample = config.responses[requestName];
+            item.response = [
+                {
+                    name: responseExample.name || 'Success',
+                    status: responseExample.status || getDefaultStatus(method),
+                    code: responseExample.code || getDefaultStatusCode(method),
+                    _postman_previewlanguage: 'json',
+                    header: [{ key: 'Content-Type', value: 'application/json' }],
+                    body: JSON.stringify(responseExample.body, null, 2),
+                },
+            ];
+        }
+        else if (!item.response || item.response.length === 0) {
+            // Add default response example if none exists
+            item.response = [getDefaultResponseExample(method)];
+        }
+    });
+    return collection;
+}
+/**
+ * Get default status text for HTTP method
+ * @param method - HTTP method
+ * @returns Status text
+ */
+function getDefaultStatus(method) {
+    const statuses = {
+        GET: 'OK',
+        POST: 'Created',
+        PUT: 'OK',
+        PATCH: 'OK',
+        DELETE: 'No Content',
+    };
+    return statuses[method] || 'OK';
+}
+/**
+ * Get default status code for HTTP method
+ * @param method - HTTP method
+ * @returns Status code
+ */
+function getDefaultStatusCode(method) {
+    const codes = {
+        GET: 200,
+        POST: 201,
+        PUT: 200,
+        PATCH: 200,
+        DELETE: 204,
+    };
+    return codes[method] || 200;
+}
+/**
+ * Get default response example for HTTP method
+ * @param method - HTTP method
+ * @returns Response example
+ */
+function getDefaultResponseExample(method) {
+    if (method === 'DELETE') {
+        return {
+            name: 'No Content',
+            status: 'No Content',
+            code: 204,
+            header: [],
+            body: '',
+        };
+    }
+    if (method === 'POST') {
+        return {
+            name: 'Created',
+            status: 'Created',
+            code: 201,
+            _postman_previewlanguage: 'json',
+            header: [{ key: 'Content-Type', value: 'application/json' }],
+            body: JSON.stringify({
+                id: '123e4567-e89b-12d3-a456-426614174000',
+                message: 'Resource created successfully',
+            }, null, 2),
+        };
+    }
+    return {
+        name: 'Success',
+        status: 'OK',
+        code: 200,
+        _postman_previewlanguage: 'json',
+        header: [{ key: 'Content-Type', value: 'application/json' }],
+        body: JSON.stringify({
+            id: '123e4567-e89b-12d3-a456-426614174000',
+            name: 'Example Resource',
+            createdAt: '2024-01-01T00:00:00Z',
+            updatedAt: '2024-01-01T00:00:00Z',
+        }, null, 2),
+    };
+}

package/dist/enrichers/filter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Filter enricher - Removes non-essential endpoints from collection
+ */
+import type { PostmanCollection, FilterConfig } from '@postman-enricher/shared';
+/**
+ * Filter collection to only include specified endpoints
+ * @param collection - Postman collection
+ * @param config - Filter configuration with include/exclude endpoints
+ * @returns Filtered collection
+ */
+export declare function filterEndpoints(collection: PostmanCollection, config: FilterConfig): PostmanCollection;

package/dist/enrichers/filter.js

@@ -0,0 +1,54 @@
+/**
+ * Filter enricher - Removes non-essential endpoints from collection
+ */
+import { isRequest, getRequestMethod, getUrlPath, shouldIncludeEndpoint, } from '@postman-enricher/shared';
+/**
+ * Filter collection to only include specified endpoints
+ * @param collection - Postman collection
+ * @param config - Filter configuration with include/exclude endpoints
+ * @returns Filtered collection
+ */
+export function filterEndpoints(collection, config) {
+    if (!config?.include) {
+        return collection; // No filtering configured
+    }
+    function filterItems(items) {
+        if (!items)
+            return [];
+        return items
+            .map((item) => {
+            if (isRequest(item)) {
+                // This is a request item
+                const method = getRequestMethod(item);
+                const path = getUrlPath(item.request.url);
+                if (shouldIncludeEndpoint(method, path, config.include, config.normalizationRules || {})) {
+                    return item;
+                }
+                return null; // Filter out this endpoint
+            }
+            else if (item.item) {
+                // This is a folder
+                const filteredSubItems = filterItems(item.item).filter(Boolean);
+                if (filteredSubItems.length > 0) {
+                    return {
+                        ...item,
+                        item: filteredSubItems,
+                    };
+                }
+                return null; // Remove empty folders
+            }
+            return item;
+        })
+            .filter((item) => item !== null);
+    }
+    const filtered = {
+        ...collection,
+        item: filterItems(collection.item),
+    };
+    // Add note about filtering in description (if provided in config)
+    if (filtered.info && config.note) {
+        filtered.info.description =
+            (filtered.info.description || '') + '\n\n' + config.note;
+    }
+    return filtered;
+}

package/dist/enrichers/tests.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tests enricher - Adds basic test scripts to requests
+ */
+import type { PostmanCollection, TestConfig } from '@postman-enricher/shared';
+/**
+ * Add test scripts to requests
+ * @param collection - Postman collection
+ * @param config - Tests configuration
+ * @returns Collection with test scripts
+ */
+export declare function addTests(collection: PostmanCollection, config: TestConfig | undefined): PostmanCollection;

package/dist/enrichers/tests.js

@@ -0,0 +1,82 @@
+/**
+ * Tests enricher - Adds basic test scripts to requests
+ */
+import { walkCollection, isRequest, getRequestMethod, } from '@postman-enricher/shared';
+/**
+ * Add test scripts to requests
+ * @param collection - Postman collection
+ * @param config - Tests configuration
+ * @returns Collection with test scripts
+ */
+export function addTests(collection, config) {
+    if (!config?.auto)
+        return collection;
+    walkCollection(collection.item, (item) => {
+        if (!isRequest(item))
+            return;
+        const method = getRequestMethod(item);
+        const testScript = getTestTemplate(method);
+        if (testScript) {
+            item.event = item.event || [];
+            item.event.push({
+                listen: 'test',
+                script: {
+                    type: 'text/javascript',
+                    exec: testScript,
+                },
+            });
+        }
+    });
+    return collection;
+}
+/**
+ * Get test template for HTTP method
+ * @param method - HTTP method
+ * @returns Test script lines or null
+ */
+function getTestTemplate(method) {
+    const templates = {
+        GET: [
+            'pm.test("Status code is 200", () => {',
+            '    pm.response.to.have.status(200);',
+            '});',
+            '',
+            'pm.test("Response time is less than 1000ms", () => {',
+            '    pm.expect(pm.response.responseTime).to.be.below(1000);',
+            '});',
+        ],
+        POST: [
+            'pm.test("Successful creation", () => {',
+            '    pm.expect(pm.response.code).to.be.oneOf([200, 201]);',
+            '});',
+            '',
+            'pm.test("Response has data", () => {',
+            '    const jsonData = pm.response.json();',
+            '    pm.expect(jsonData).to.be.an("object");',
+            '});',
+        ],
+        PUT: [
+            'pm.test("Successful update", () => {',
+            '    pm.expect(pm.response.code).to.be.oneOf([200, 204]);',
+            '});',
+        ],
+        PATCH: [
+            'pm.test("Successful partial update", () => {',
+            '    pm.expect(pm.response.code).to.be.oneOf([200, 204]);',
+            '});',
+            '',
+            'pm.test("Response has updated data", () => {',
+            '    if (pm.response.code === 200) {',
+            '        const jsonData = pm.response.json();',
+            '        pm.expect(jsonData).to.be.an("object");',
+            '    }',
+            '});',
+        ],
+        DELETE: [
+            'pm.test("Successful deletion", () => {',
+            '    pm.response.to.have.status(204);',
+            '});',
+        ],
+    };
+    return templates[method] || null;
+}

package/dist/enrichers/variables.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Variables enricher - Sets up path variables and environment variables
+ */
+import type { PostmanCollection, VariableConfig } from '@postman-enricher/shared';
+/**
+ * Setup variables in the collection
+ * @param collection - Postman collection
+ * @param config - Variables configuration
+ * @returns Collection with variables configured
+ */
+export declare function setupVariables(collection: PostmanCollection, config: VariableConfig | undefined): PostmanCollection;

package/dist/enrichers/variables.js

@@ -0,0 +1,101 @@
+/**
+ * Variables enricher - Sets up path variables and environment variables
+ */
+import { walkCollection, isRequest } from '@postman-enricher/shared';
+/**
+ * Setup variables in the collection
+ * @param collection - Postman collection
+ * @param config - Variables configuration
+ * @returns Collection with variables configured
+ */
+export function setupVariables(collection, config) {
+    if (!config)
+        return collection;
+    // 1. Clear collection variables (use environment variables instead)
+    collection.variable = [];
+    // 2. Setup path variables
+    if (config.path) {
+        walkCollection(collection.item, (item) => {
+            if (!isRequest(item) || !item.request?.url)
+                return;
+            const url = item.request.url;
+            if (!url.path || !Array.isArray(url.path))
+                return;
+            // Initialize variable array if needed
+            if (!url.variable) {
+                url.variable = [];
+            }
+            // Check which path variables are needed
+            Object.entries(config.path).forEach(([varName, varValue]) => {
+                if (url.path &&
+                    Array.isArray(url.path) &&
+                    url.path.includes(`:${varName}`)) {
+                    // Find existing variable or add new one
+                    const existingIndex = url.variable.findIndex((v) => v.key === varName);
+                    const variable = {
+                        key: varName,
+                        value: varValue,
+                        description: config.descriptions?.[varName] || '',
+                    };
+                    if (existingIndex >= 0) {
+                        url.variable[existingIndex] = variable;
+                    }
+                    else {
+                        url.variable.push(variable);
+                    }
+                }
+            });
+        });
+    }
+    // 3. Update host URLs to use environment variables
+    const baseUrlVar = config.baseUrlVar || 'baseUrl';
+    walkCollection(collection.item, (item) => {
+        if (isRequest(item) && item.request?.url) {
+            item.request.url.host = [`{{${baseUrlVar}}}`];
+        }
+    });
+    // 4. Process query parameters
+    if (config.query) {
+        walkCollection(collection.item, (item) => {
+            if (!isRequest(item) || !item.request?.url?.query)
+                return;
+            Object.entries(config.query).forEach(([key, value]) => {
+                const query = item.request.url.query;
+                const paramIndex = query.findIndex((q) => q.key === key);
+                if (paramIndex >= 0) {
+                    const existingParam = query[paramIndex];
+                    query[paramIndex] = {
+                        key,
+                        value,
+                        disabled: false,
+                        ...(existingParam.description && {
+                            description: existingParam.description,
+                        }),
+                    };
+                }
+            });
+        });
+    }
+    // 5. Add collection-level pre-request script for environment validation
+    const envVars = config.environment ? Object.keys(config.environment) : [];
+    if (envVars.length > 0) {
+        const script = [
+            '// Validate required environment variables',
+            ...envVars.map((varName) => `if (!pm.environment.get("${varName}")) {
+    console.warn("Please set your ${varName} in the environment");
+}`),
+            '',
+            '// Save timestamp for chaining requests',
+            'pm.globals.set("timestamp", new Date().toISOString());',
+        ];
+        collection.event = collection.event || [];
+        collection.event.push({
+            listen: 'prerequest',
+            script: {
+                type: 'text/javascript',
+                exec: script,
+            },
+        });
+    }
+    return collection;
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * OpenAPI to Postman Complete - Core
+ * Main API for enriching Postman collections with descriptions, examples, variables, and tests
+ */
+import type { PostmanCollection, EnrichmentConfig } from '@postman-enricher/shared';
+import { filterEndpoints } from './enrichers/filter.js';
+import { addDescriptions } from './enrichers/descriptions.js';
+import { addExamples } from './enrichers/examples.js';
+import { setupVariables } from './enrichers/variables.js';
+import { addTests } from './enrichers/tests.js';
+/**
+ * Enrich a Postman collection with additional metadata and functionality
+ * @param collection - Postman collection to enrich
+ * @param config - Enrichment configuration (object or path to YAML file)
+ * @returns Enriched Postman collection
+ */
+export declare function enrichCollection(collection: PostmanCollection, config?: EnrichmentConfig | string): PostmanCollection;
+/**
+ * Load enrichment configuration from a YAML file
+ * @param filePath - Path to YAML configuration file
+ * @returns Parsed enrichment configuration
+ */
+export declare function loadConfigFromYaml(filePath: string): EnrichmentConfig;
+/**
+ * Export individual enrichers for advanced usage
+ */
+export { filterEndpoints, addDescriptions, addExamples, setupVariables, addTests, };

package/dist/index.js

@@ -0,0 +1,62 @@
+/**
+ * OpenAPI to Postman Complete - Core
+ * Main API for enriching Postman collections with descriptions, examples, variables, and tests
+ */
+import { readFileSync } from 'fs';
+import { parse as parseYaml } from 'yaml';
+import { filterEndpoints } from './enrichers/filter.js';
+import { addDescriptions } from './enrichers/descriptions.js';
+import { addExamples } from './enrichers/examples.js';
+import { setupVariables } from './enrichers/variables.js';
+import { addTests } from './enrichers/tests.js';
+/**
+ * Enrich a Postman collection with additional metadata and functionality
+ * @param collection - Postman collection to enrich
+ * @param config - Enrichment configuration (object or path to YAML file)
+ * @returns Enriched Postman collection
+ */
+export function enrichCollection(collection, config = {}) {
+    // Load config from YAML file if string path provided
+    const enrichmentConfig = typeof config === 'string' ? loadConfigFromYaml(config) : config;
+    let enriched = { ...collection };
+    // Apply enrichments in order
+    // 1. Filter endpoints first (reduce what we're working with)
+    if (enrichmentConfig.filter) {
+        enriched = filterEndpoints(enriched, enrichmentConfig.filter);
+    }
+    // 2. Add descriptions (collection, folders, requests)
+    if (enrichmentConfig.descriptions) {
+        enriched = addDescriptions(enriched, enrichmentConfig.descriptions);
+    }
+    // 3. Add examples (request bodies and responses)
+    if (enrichmentConfig.examples) {
+        enriched = addExamples(enriched, enrichmentConfig.examples);
+    }
+    // 4. Setup variables (path variables, environment variables)
+    if (enrichmentConfig.variables) {
+        enriched = setupVariables(enriched, enrichmentConfig.variables);
+    }
+    // 5. Add test scripts
+    if (enrichmentConfig.tests) {
+        enriched = addTests(enriched, enrichmentConfig.tests);
+    }
+    return enriched;
+}
+/**
+ * Load enrichment configuration from a YAML file
+ * @param filePath - Path to YAML configuration file
+ * @returns Parsed enrichment configuration
+ */
+export function loadConfigFromYaml(filePath) {
+    try {
+        const yaml = readFileSync(filePath, 'utf8');
+        return parseYaml(yaml);
+    }
+    catch (error) {
+        throw new Error(`Failed to load config from ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Export individual enrichers for advanced usage
+ */
+export { filterEndpoints, addDescriptions, addExamples, setupVariables, addTests, };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@postman-enricher/core",
+  "version": "1.0.0",
+  "description": "Core enrichment logic for Postman Enricher",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "yaml": "^2.8.1",
+    "@postman-enricher/shared": "1.0.0"
+  },
+  "devDependencies": {
+    "@anolilab/semantic-release-pnpm": "^3.0.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/node": "^24.10.1",
+    "semantic-release": "^25.0.2",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/caiopizzol/openapi-to-postman-complete.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/caiopizzol/openapi-to-postman-complete/issues"
+  },
+  "homepage": "https://github.com/caiopizzol/openapi-to-postman-complete#readme",
+  "author": "Caio Pizzol",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}