post-api-sync 0.1.1 → 0.1.3

package/README.md

@@ -1,8 +1,8 @@
-# api-sync
+# post-api-sync
 
 Sync your API code directly to Postman and Insomnia collections. 
 
-`api-sync` extracts endpoint definitions, parameters, and validation schemas (Zod, Class Validator) from your Hono, Express, or NestJS code and generates ready-to-use collections. It can also push changes directly to Postman Cloud.
+`post-api-sync` extracts endpoint definitions, parameters, and validation schemas (Zod, Class Validator) from your Hono, Express, or NestJS code and generates ready-to-use collections. It can also push changes directly to Postman Cloud.
 
 ## Features
 
@@ -18,32 +18,32 @@ Sync your API code directly to Postman and Insomnia collections.
 ## Installation
 
 ```bash
-npm install -g api-sync
+npm install -g post-api-sync
 # or use via npx
-npx api-sync --help
+npx post-api-sync --help
 ```
 
 ## Quick Start
 
 1.  **Initialize configuration**:
     ```bash
-    npx api-sync init
+    npx post-api-sync init
     ```
-    This will create an `api-sync.config.js` file in your project root.
+    This will create an `post-api-sync.config.js` file in your project root.
 
 2.  **Run extraction**:
     ```bash
-    npx api-sync sync
+    npx post-api-sync sync
     ```
 
 3.  **Watch for changes**:
     ```bash
-    npx api-sync watch
+    npx post-api-sync watch
     ```
 
 ## Configuration
 
-The `api-sync.config.js` file allows you to customize the tool's behavior:
+The `post-api-sync.config.js` file allows you to customize the tool's behavior:
 
 ```javascript
 module.exports = {
@@ -59,6 +59,11 @@ module.exports = {
     baseUrl: 'http://localhost:3000'
   },
 
+  organization: {
+    // 'folder' (default) or 'tags'
+    groupBy: 'folder'
+  },
+
   output: {
     postman: {
       enabled: true,
@@ -67,14 +72,18 @@ module.exports = {
       apiKey: process.env.POSTMAN_API_KEY,
       collectionId: process.env.POSTMAN_COLLECTION_ID
     },
-    insomnia: {
-      enabled: true,
-      outputPath: './insomnia_collection.json'
-    }
+    // ...
   }
 };
 ```
 
+### Environment Variables
+You can use a `.env` file in your project root to store sensitive keys:
+```bash
+POSTMAN_API_KEY=your-api-key
+POSTMAN_COLLECTION_ID=your-collection-uid
+```
+
 ## Postman Cloud Sync
 
 You can push your generated collection directly to Postman without manual importing.
@@ -84,7 +93,11 @@ You can push your generated collection directly to Postman without manual import
 3.  Run the sync command:
 
 ```bash
-npx api-sync sync --postman-key <YOUR_KEY> --postman-id <COLLECTION_UID>
+# Finds keys in .env or config
+npx post-api-sync
+
+# Or specify manually
+npx post-api-sync sync --postman-key <YOUR_KEY> --postman-id <COLLECTION_UID>
 ```
 
 Or set them in your config/environment variables to use with `watch` mode.

package/bin/{api-sync.js → post-api-sync.js}

@@ -1,17 +1,22 @@
 #!/usr/bin/env node
 
+require('dotenv').config();
 const { program } = require('commander');
 const { initConfig } = require('../src/init');
 const { syncOnce } = require('../src/sync');
 const { watchMode } = require('../src/watch');
 
 program
-  .name('api-sync')
-  .description('Sync Postman and Insomnia collections from API code');
+  .name('post-api-sync')
+  .description('Sync Postman and Insomnia collections from API code')
+  .action(async () => {
+    // Default behavior: run sync
+    await syncOnce();
+  });
 
 program
   .command('init')
-  .description('Create api-sync.config.js')
+  .description('Create post-api-sync.config.js')
   .option('--cwd <path>', 'Project root for config')
   .action(async (opts) => {
     await initConfig({ baseDir: opts.cwd });

package/package.json

@@ -1,21 +1,26 @@
 {
   "name": "post-api-sync",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Sync Postman and Insomnia collections from API code",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EzekielMisgae/post-api-sync.git"
+  },
   "type": "commonjs",
   "bin": {
-    "api-sync": "bin/api-sync.js"
+    "post-api-sync": "bin/post-api-sync.js"
   },
   "scripts": {
-    "sync": "node bin/api-sync.js sync",
-    "watch": "node bin/api-sync.js watch",
-    "init": "node bin/api-sync.js init"
+    "sync": "node bin/post-api-sync.js sync",
+    "watch": "node bin/post-api-sync.js watch",
+    "init": "node bin/post-api-sync.js init"
   },
   "dependencies": {
     "@babel/parser": "^7.24.0",
     "@babel/traverse": "^7.24.0",
     "chokidar": "^3.6.0",
     "commander": "^12.0.0",
+    "dotenv": "^17.2.4",
     "fast-glob": "^3.3.2",
     "fs-extra": "^11.2.0",
     "inquirer": "^9.2.0",

package/src/collection/insomnia.js

@@ -28,7 +28,7 @@ function buildInsomniaCollection(endpoints, config) {
     _type: 'export',
     __export_format: 4,
     __export_date: new Date().toISOString(),
-    __export_source: 'api-sync',
+    __export_source: 'post-api-sync',
     resources
   };
 }

package/src/collection/postman.js

@@ -1,12 +1,18 @@
 const { nanoid } = require('nanoid');
+const path = require('path');
 const { toPostmanPath, splitPath, extractPathParams } = require('../utils');
 
 function buildPostmanCollection(endpoints, config) {
   const name = (config.output && config.output.postman && config.output.postman.collectionName) || 'API Collection';
-  const baseUrl = config.sources.baseUrl || 'http://localhost:3000';
-  const groupBy = (config.organization && config.organization.groupBy) || 'tags';
+  const baseUrl = (config.sources && config.sources.baseUrl) || 'http://localhost:3000';
+  const groupBy = (config.organization && config.organization.groupBy) || 'folder';
 
-  const items = groupBy === 'tags' ? buildTaggedItems(endpoints) : endpoints.map(buildItem);
+  let items;
+  if (groupBy === 'folder') {
+    items = buildFolderItems(endpoints);
+  } else {
+    items = buildTaggedItems(endpoints);
+  }
 
   return {
     info: {
@@ -19,6 +25,63 @@ function buildPostmanCollection(endpoints, config) {
   };
 }
 
+function buildFolderItems(endpoints) {
+  const root = { item: [], _folders: {} };
+
+  for (const endpoint of endpoints) {
+    // Determine module name from file path
+    // e.g. /abs/path/to/src/modules/health/routes.ts -> Health
+    // e.g. /abs/path/to/src/modules/orders/routes/order.routes.ts -> Orders
+    let moduleName = 'General';
+    if (endpoint.filePath) {
+      const parts = endpoint.filePath.split(path.sep);
+      const filename = parts[parts.length - 1];
+      const parent = parts[parts.length - 2];
+      const grandparent = parts[parts.length - 3];
+
+      if (filename === 'routes.ts' || filename.endsWith('.routes.ts')) {
+        if (parent === 'routes' && grandparent) {
+          moduleName = capitalize(grandparent);
+        } else {
+          moduleName = capitalize(parent);
+        }
+      } else {
+        // Fallback: try to find a meaningful parent
+        // If parent is 'routes', go up one
+        if (parent === 'routes' && grandparent) {
+          moduleName = capitalize(grandparent);
+        } else {
+          moduleName = capitalize(parent);
+        }
+      }
+    }
+
+    if (!root._folders[moduleName]) {
+      const folder = { name: moduleName, item: [], _folders: {} };
+      root.item.push(folder);
+      root._folders[moduleName] = folder;
+    }
+
+    root._folders[moduleName].item.push(buildItem(endpoint));
+  }
+
+  return cleanFolders(root.item);
+}
+
+function capitalize(str) {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+function cleanFolders(items) {
+  // Remove temporary _folders property
+  for (const item of items) {
+    if (item._folders) delete item._folders;
+    if (item.item) cleanFolders(item.item);
+  }
+  return items;
+}
+
 function buildTaggedItems(endpoints) {
   const groups = new Map();
   for (const endpoint of endpoints) {
@@ -57,10 +120,10 @@ function buildItem(endpoint) {
       },
       body: hasBody
         ? {
-            mode: 'raw',
-            raw: JSON.stringify(example || {}, null, 2),
-            options: { raw: { language: 'json' } }
-          }
+          mode: 'raw',
+          raw: JSON.stringify(example || {}, null, 2),
+          options: { raw: { language: 'json' } }
+        }
         : undefined
     },
     response: []

package/src/config.js

@@ -6,7 +6,7 @@ const ALWAYS_EXCLUDE = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/*
 const DEFAULT_CONFIG = {
   framework: 'auto',
   sources: {
-    include: ['src/**/*.{ts,js,tsx,jsx}'],
+    include: ['src/**/routes.ts', 'src/**/*.routes.ts'],
     exclude: ['**/*.spec.ts', '**/*.test.ts', 'node_modules/**', 'dist/**', 'build/**'],
     baseUrl: 'http://localhost:3000'
   },
@@ -28,7 +28,7 @@ const DEFAULT_CONFIG = {
     markDeprecated: true
   },
   organization: {
-    groupBy: 'tags'
+    groupBy: 'folder'
   }
 };
 
@@ -41,18 +41,18 @@ async function resolveConfigPath(configPath, baseDir) {
       const stat = await fs.stat(abs);
       if (stat.isDirectory()) {
         cwd = abs;
-        return { path: path.resolve(cwd, 'api-sync.config.js'), baseDir: cwd };
+        return { path: path.resolve(cwd, 'post-api-sync.config.js'), baseDir: cwd };
       }
       return { path: abs, baseDir: path.dirname(abs) };
     }
     if (!path.extname(abs)) {
       cwd = abs;
-      return { path: path.resolve(cwd, 'api-sync.config.js'), baseDir: cwd };
+      return { path: path.resolve(cwd, 'post-api-sync.config.js'), baseDir: cwd };
     }
     return { path: abs, baseDir: cwd };
   }
 
-  return { path: path.resolve(cwd, 'api-sync.config.js'), baseDir: cwd };
+  return { path: path.resolve(cwd, 'post-api-sync.config.js'), baseDir: cwd };
 }
 
 async function loadConfig(configPath, baseDir) {

package/src/merge/postman.js

@@ -57,32 +57,64 @@ function flattenPostmanItems(items, out = []) {
   return out;
 }
 
-function rebuildFromFlat(templateItems, flatItems) {
-  // If template has folders, rebuild preserving folder names based on name prefix match.
-  if (!templateItems.some((i) => i.item)) return flatItems;
-  const folderMap = new Map();
-  for (const folder of templateItems) {
-    if (folder.item) {
-      folderMap.set(folder.name, { name: folder.name, item: [] });
-    }
+function rebuildFromFlat(templateItems, mergedItems) {
+  // Create a map of merged items for quick lookup
+  const mergedMap = new Map();
+  for (const item of mergedItems) {
+    const key = keyFromPostmanItem(item);
+    if (key) mergedMap.set(key, item);
   }
-  for (const item of flatItems) {
-    const tag = inferFolderName(item.name);
-    if (folderMap.has(tag)) {
-      folderMap.get(tag).item.push(item);
+
+  // 1. Rebuild the structure based on the template (newly generated structure)
+  const rebuilt = replaceItemsRecursive(templateItems, mergedMap);
+
+  // 2. Identify items that are in mergedItems (existing+deprecated) but NOT in template
+  // These are effectively "extra" items (old manual items, or deprecated ones)
+  // We want to keep them, usually appended to the root
+  const usedKeys = new Set();
+  traverseKeys(rebuilt, usedKeys);
+
+  const leftovers = mergedItems.filter(item => {
+    const key = keyFromPostmanItem(item);
+    return key && !usedKeys.has(key);
+  });
+
+  // Add leftovers to the root
+  return [...rebuilt, ...leftovers];
+}
+
+function replaceItemsRecursive(items, mergedMap) {
+  return items.map(item => {
+    if (item.item) {
+      // It's a folder
+      return { ...item, item: replaceItemsRecursive(item.item, mergedMap) };
+    }
+    // It's a request
+    const key = keyFromPostmanItem(item);
+    if (key && mergedMap.has(key)) {
+      // Return the merged version (which has description etc from existing)
+      // But we must preserve the new name/folder context if it changed?
+      // Actually mergedMap has the MERGED item.
+      // If the folder structure changed, 'item' here is from template, so it's in the right place.
+      // We just want the content from mergedMap.
+      return mergedMap.get(key);
+    }
+    return item;
+  });
+}
+
+function traverseKeys(items, keySet) {
+  for (const item of items) {
+    if (item.item) {
+      traverseKeys(item.item, keySet);
     } else {
-      if (!folderMap.has('General')) folderMap.set('General', { name: 'General', item: [] });
-      folderMap.get('General').item.push(item);
+      const key = keyFromPostmanItem(item);
+      if (key) keySet.add(key);
     }
   }
-  return Array.from(folderMap.values());
 }
 
-function inferFolderName(name) {
-  const match = name.match(/^[A-Z]+\s+\S+/);
-  if (match) return 'General';
-  return 'General';
-}
+
 
 function keyFromPostmanItem(item) {
   if (!item || !item.request) return null;

package/src/sync.js

@@ -13,9 +13,9 @@ async function syncOnce({ configPath, baseDir, postmanKey, postmanId } = {}) {
   try {
     const { config, baseDir: resolvedBase } = await loadConfig(configPath, baseDir);
     const cwd = resolvedBase || process.cwd();
-    // Use CLI args or config values
-    const pmKey = postmanKey || (config.output && config.output.postman && config.output.postman.apiKey);
-    const pmId = postmanId || (config.output && config.output.postman && config.output.postman.collectionId);
+    // Use CLI args, env vars, or config values
+    const pmKey = postmanKey || process.env.POSTMAN_API_KEY || (config.output && config.output.postman && config.output.postman.apiKey);
+    const pmId = postmanId || process.env.POSTMAN_COLLECTION_ID || (config.output && config.output.postman && config.output.postman.collectionId);
 
     const include = normalizeIncludePatterns(config.sources.include || [], cwd);
     const exclude = Array.from(new Set([
@@ -60,6 +60,7 @@ async function syncOnce({ configPath, baseDir, postmanKey, postmanId } = {}) {
       await fs.outputJson(outPath, merged, { spaces: 2 });
       success(`Postman collection written to ${path.relative(process.cwd(), outPath)}`);
 
+      // Auto-sync checks
       if (pmKey && pmId) {
         info(`Pushing to Postman Cloud (ID: ${pmId})...`);
         try {
@@ -68,6 +69,11 @@ async function syncOnce({ configPath, baseDir, postmanKey, postmanId } = {}) {
         } catch (err) {
           error(`Failed to sync to Postman Cloud: ${err.message}`);
         }
+      } else if (pmKey || pmId) {
+        // Partial keys present
+        warn('Skipping Postman Cloud sync: Missing API Key or Collection ID.');
+        if (!pmKey) warn('  -> POSTMAN_API_KEY is missing');
+        if (!pmId) warn('  -> POSTMAN_COLLECTION_ID is missing');
       }
     }
 

package/src/watch.js

@@ -3,7 +3,7 @@ const { loadConfig, normalizeIncludePatterns, normalizeExcludePatterns, ALWAYS_E
 const { syncOnce } = require('./sync');
 const { info } = require('./log');
 
-async function watchMode({ configPath, baseDir } = {}) {
+async function watchMode({ configPath, baseDir, postmanKey, postmanId } = {}) {
   const { config, baseDir: resolvedBase } = await loadConfig(configPath, baseDir);
   const cwd = resolvedBase || process.cwd();
   const include = normalizeIncludePatterns(config.sources.include || [], cwd);
@@ -19,7 +19,7 @@ async function watchMode({ configPath, baseDir } = {}) {
   const trigger = () => {
     if (timer) clearTimeout(timer);
     timer = setTimeout(() => {
-      syncOnce({ configPath, baseDir: cwd });
+      syncOnce({ configPath, baseDir: cwd, postmanKey, postmanId });
     }, debounceMs);
   };