post-api-sync 0.1.1

package/src/log.js

@@ -0,0 +1,37 @@
+const kleur = require('kleur');
+
+const isTty = process.stdout.isTTY;
+
+function info(message) {
+  if (isTty) {
+    console.log(kleur.cyan(message));
+  } else {
+    console.log(message);
+  }
+}
+
+function warn(message) {
+  if (isTty) {
+    console.warn(kleur.yellow(message));
+  } else {
+    console.warn(message);
+  }
+}
+
+function error(message) {
+  if (isTty) {
+    console.error(kleur.red(message));
+  } else {
+    console.error(message);
+  }
+}
+
+function success(message) {
+  if (isTty) {
+    console.log(kleur.green(message));
+  } else {
+    console.log(message);
+  }
+}
+
+module.exports = { info, warn, error, success };

package/src/merge/insomnia.js

@@ -0,0 +1,77 @@
+const { buildInsomniaCollection } = require('../collection/insomnia');
+const { normalizePath } = require('../utils');
+
+function mergeInsomniaCollection(endpoints, config, existing) {
+  const generated = buildInsomniaCollection(endpoints, config);
+  if (!existing || !existing.resources) return generated;
+
+  const generatedRequests = generated.resources.filter((r) => r._type === 'request');
+  const existingRequests = existing.resources.filter((r) => r._type === 'request');
+
+  const existingMap = new Map();
+  for (const req of existingRequests) {
+    const key = keyFromRequest(req);
+    if (key) existingMap.set(key, req);
+  }
+
+  const mergedRequests = [];
+  for (const req of generatedRequests) {
+    const key = keyFromRequest(req);
+    if (key && existingMap.has(key)) {
+      mergedRequests.push(mergeRequest(req, existingMap.get(key)));
+    } else {
+      mergedRequests.push(req);
+    }
+  }
+
+  if (config.merge && config.merge.markDeprecated) {
+    for (const [key, req] of existingMap.entries()) {
+      if (!generatedRequests.find((r) => keyFromRequest(r) === key)) {
+        const deprecated = { ...req };
+        deprecated.name = deprecated.name.startsWith('[DEPRECATED]')
+          ? deprecated.name
+          : `[DEPRECATED] ${deprecated.name}`;
+        mergedRequests.push(deprecated);
+      }
+    }
+  }
+
+  const nonRequestResources = generated.resources.filter((r) => r._type !== 'request');
+
+  return {
+    ...existing,
+    resources: [...nonRequestResources, ...mergedRequests]
+  };
+}
+
+function keyFromRequest(req) {
+  if (!req || !req.method || !req.url) return null;
+  const url = req.url.replace(/\{\{\s*_.baseUrl\s*\}\}/i, '');
+  return `${req.method.toUpperCase()} ${normalizePath(url)}`;
+}
+
+function mergeRequest(newReq, existingReq) {
+  return {
+    ...existingReq,
+    name: newReq.name || existingReq.name,
+    method: newReq.method || existingReq.method,
+    url: newReq.url || existingReq.url,
+    headers: mergeHeaders(newReq.headers || [], existingReq.headers || []),
+    body: newReq.body || existingReq.body
+  };
+}
+
+function mergeHeaders(codeHeaders, existingHeaders) {
+  const map = new Map();
+  for (const h of existingHeaders) {
+    if (!h || !h.name) continue;
+    map.set(h.name.toLowerCase(), h);
+  }
+  for (const h of codeHeaders) {
+    if (!h || !h.name) continue;
+    map.set(h.name.toLowerCase(), h);
+  }
+  return Array.from(map.values());
+}
+
+module.exports = { mergeInsomniaCollection };

package/src/merge/postman.js

@@ -0,0 +1,141 @@
+const { buildPostmanCollection } = require('../collection/postman');
+const { toPostmanPath, normalizePath } = require('../utils');
+
+function mergePostmanCollection(endpoints, config, existing) {
+  const generated = buildPostmanCollection(endpoints, config);
+  if (!existing || !existing.item) return generated;
+
+  const newItems = flattenPostmanItems(generated.item);
+  const existingItems = flattenPostmanItems(existing.item);
+
+  const existingMap = new Map();
+  for (const item of existingItems) {
+    const key = keyFromPostmanItem(item);
+    if (key) existingMap.set(key, item);
+  }
+
+  const mergedItems = [];
+  for (const item of newItems) {
+    const key = keyFromPostmanItem(item);
+    if (key && existingMap.has(key)) {
+      mergedItems.push(mergePostmanItem(item, existingMap.get(key)));
+    } else {
+      mergedItems.push(item);
+    }
+  }
+
+  if (config.merge && config.merge.markDeprecated) {
+    for (const [key, item] of existingMap.entries()) {
+      if (!newItems.find((i) => keyFromPostmanItem(i) === key)) {
+        const deprecated = { ...item };
+        deprecated.name = deprecated.name.startsWith('[DEPRECATED]')
+          ? deprecated.name
+          : `[DEPRECATED] ${deprecated.name}`;
+        mergedItems.push(deprecated);
+      }
+    }
+  }
+
+  const rebuilt = rebuildFromFlat(generated.item, mergedItems);
+
+  return {
+    ...existing,
+    info: existing.info || generated.info,
+    variable: generated.variable,
+    item: rebuilt
+  };
+}
+
+function flattenPostmanItems(items, out = []) {
+  for (const item of items) {
+    if (item.item && Array.isArray(item.item)) {
+      flattenPostmanItems(item.item, out);
+    } else {
+      out.push(item);
+    }
+  }
+  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: [] });
+    }
+  }
+  for (const item of flatItems) {
+    const tag = inferFolderName(item.name);
+    if (folderMap.has(tag)) {
+      folderMap.get(tag).item.push(item);
+    } else {
+      if (!folderMap.has('General')) folderMap.set('General', { name: 'General', item: [] });
+      folderMap.get('General').item.push(item);
+    }
+  }
+  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;
+  const method = item.request.method || '';
+  const url = item.request.url || {};
+  let raw = '';
+  if (typeof url === 'string') raw = url;
+  if (url.raw) raw = url.raw;
+  let path = '';
+  if (raw) {
+    path = raw.replace(/\{\{\s*baseUrl\s*\}\}/i, '');
+  } else if (Array.isArray(url.path)) {
+    path = `/${url.path.join('/')}`;
+  }
+  path = toPostmanPath(path || '/');
+  return `${method.toUpperCase()} ${normalizePath(path)}`;
+}
+
+function mergePostmanItem(newItem, existingItem) {
+  const merged = { ...existingItem };
+  merged.name = newItem.name || existingItem.name;
+
+  const newRequest = newItem.request || {};
+  const existingRequest = existingItem.request || {};
+
+  const headers = mergeHeaders(newRequest.header || [], existingRequest.header || []);
+
+  merged.request = {
+    ...existingRequest,
+    method: newRequest.method || existingRequest.method,
+    url: newRequest.url || existingRequest.url,
+    header: headers,
+    body: newRequest.body || existingRequest.body
+  };
+
+  if (newItem.description && !existingItem.description) {
+    merged.description = newItem.description;
+  }
+
+  return merged;
+}
+
+function mergeHeaders(codeHeaders, existingHeaders) {
+  const map = new Map();
+  for (const h of existingHeaders) {
+    if (!h || !h.key) continue;
+    map.set(h.key.toLowerCase(), h);
+  }
+  for (const h of codeHeaders) {
+    if (!h || !h.key) continue;
+    map.set(h.key.toLowerCase(), h);
+  }
+  return Array.from(map.values());
+}
+
+module.exports = { mergePostmanCollection };

package/src/sync/postman-cloud.js

@@ -0,0 +1,46 @@
+const https = require('https');
+
+function pushToPostman(collectionJson, apiKey, collectionUid) {
+    return new Promise((resolve, reject) => {
+        const data = JSON.stringify({
+            collection: collectionJson
+        });
+
+        const options = {
+            hostname: 'api.getpostman.com',
+            port: 443,
+            path: `/collections/${collectionUid}`,
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Api-Key': apiKey,
+                'Content-Length': Buffer.byteLength(data)
+            }
+        };
+
+        const req = https.request(options, (res) => {
+            let responseBody = '';
+
+            res.on('data', (chunk) => {
+                responseBody += chunk;
+            });
+
+            res.on('end', () => {
+                if (res.statusCode >= 200 && res.statusCode < 300) {
+                    resolve(JSON.parse(responseBody));
+                } else {
+                    reject(new Error(`Postman API Error: ${res.statusCode} - ${responseBody}`));
+                }
+            });
+        });
+
+        req.on('error', (e) => {
+            reject(e);
+        });
+
+        req.write(data);
+        req.end();
+    });
+}
+
+module.exports = { pushToPostman };

package/src/sync.js

@@ -0,0 +1,99 @@
+const fs = require('fs-extra');
+const fg = require('fast-glob');
+const path = require('path');
+const { loadConfig, ensureAbsolute, normalizeIncludePatterns, normalizeExcludePatterns, ALWAYS_EXCLUDE } = require('./config');
+const { extractAllEndpoints } = require('./extract');
+const { mergePostmanCollection } = require('./merge/postman');
+const { mergeInsomniaCollection } = require('./merge/insomnia');
+const postmanCloud = require('./sync/postman-cloud');
+const { info, warn, success, error } = require('./log');
+const { isJsOrTs } = require('./utils');
+
+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);
+
+    const include = normalizeIncludePatterns(config.sources.include || [], cwd);
+    const exclude = Array.from(new Set([
+      ...normalizeExcludePatterns(config.sources.exclude || [], cwd),
+      ...ALWAYS_EXCLUDE
+    ]));
+
+    const files = await fg(include, { ignore: exclude, dot: false, cwd, absolute: true });
+    const jsTsFiles = files.filter(isJsOrTs);
+
+    info(`Scanning ${jsTsFiles.length} file(s)...`);
+    if (jsTsFiles.length === 0) {
+      warn(`No files matched. cwd=${cwd}`);
+      warn(`include=${include.join(', ')}`);
+      warn(`exclude=${exclude.join(', ')}`);
+    }
+
+    let extracted = [];
+    try {
+      extracted = await extractAllEndpoints(jsTsFiles, config.framework);
+      if (extracted.length === 0 && config.framework && config.framework !== 'auto') {
+        const fallback = await extractAllEndpoints(jsTsFiles, 'auto');
+        if (fallback.length) {
+          warn(`No endpoints found for framework=${config.framework}. Falling back to auto-detect.`);
+          extracted = fallback;
+        }
+      }
+    } catch (err) {
+      warn(`Extraction failed: ${err.message || err}`);
+    }
+
+    const unique = new Map();
+    for (const e of extracted) unique.set(e.key, e);
+
+    const finalEndpoints = Array.from(unique.values());
+    info(`Found ${finalEndpoints.length} endpoint(s)`);
+
+    if (config.output && config.output.postman && config.output.postman.enabled) {
+      const outPath = ensureAbsolute(config.output.postman.outputPath, cwd);
+      const existing = await readJsonIfExists(outPath);
+      const merged = mergePostmanCollection(finalEndpoints, config, existing);
+      await fs.outputJson(outPath, merged, { spaces: 2 });
+      success(`Postman collection written to ${path.relative(process.cwd(), outPath)}`);
+
+      if (pmKey && pmId) {
+        info(`Pushing to Postman Cloud (ID: ${pmId})...`);
+        try {
+          await postmanCloud.pushToPostman(merged, pmKey, pmId);
+          success('Successfully synced to Postman Cloud!');
+        } catch (err) {
+          error(`Failed to sync to Postman Cloud: ${err.message}`);
+        }
+      }
+    }
+
+    if (config.output && config.output.insomnia && config.output.insomnia.enabled) {
+      const outPath = ensureAbsolute(config.output.insomnia.outputPath, cwd);
+      const existing = await readJsonIfExists(outPath);
+      const merged = mergeInsomniaCollection(finalEndpoints, config, existing);
+      await fs.outputJson(outPath, merged, { spaces: 2 });
+      success(`Insomnia collection written to ${path.relative(process.cwd(), outPath)}`);
+    }
+  } catch (err) {
+    error(err.stack || err.message || String(err));
+    process.exitCode = 1;
+  }
+}
+
+async function readJsonIfExists(filePath) {
+  if (await fs.pathExists(filePath)) {
+    try {
+      return await fs.readJson(filePath);
+    } catch (err) {
+      warn(`Failed to read existing collection at ${filePath}: ${err.message || err}`);
+      return null;
+    }
+  }
+  return null;
+}
+
+module.exports = { syncOnce };

package/src/utils.js

@@ -0,0 +1,58 @@
+const path = require('path');
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head'];
+
+function normalizePath(p) {
+  if (!p) return '/';
+  let out = p.trim();
+  if (!out.startsWith('/')) out = `/${out}`;
+  out = out.replace(/\/+/g, '/');
+  if (out.length > 1 && out.endsWith('/')) out = out.slice(0, -1);
+  return out;
+}
+
+function joinPaths(base, child) {
+  const a = normalizePath(base || '/');
+  const b = normalizePath(child || '/');
+  if (a === '/') return b;
+  if (b === '/') return a;
+  return normalizePath(`${a}/${b}`);
+}
+
+function extractPathParams(p) {
+  const params = new Set();
+  const colonMatches = p.match(/:([A-Za-z0-9_]+)/g) || [];
+  for (const m of colonMatches) params.add(m.slice(1));
+  const braceMatches = p.match(/{([A-Za-z0-9_]+)}/g) || [];
+  for (const m of braceMatches) params.add(m.slice(1, -1));
+  return Array.from(params);
+}
+
+function toPostmanPath(p) {
+  return p.replace(/{(\w+)}/g, ':$1');
+}
+
+function splitPath(p) {
+  return normalizePath(p).split('/').filter(Boolean);
+}
+
+function toKey(method, pathStr) {
+  return `${method.toUpperCase()} ${normalizePath(pathStr)}`;
+}
+
+function isJsOrTs(filePath) {
+  if (filePath.endsWith('.d.ts') || filePath.endsWith('.d.tsx')) return false;
+  const ext = path.extname(filePath).toLowerCase();
+  return ext === '.js' || ext === '.ts' || ext === '.jsx' || ext === '.tsx';
+}
+
+module.exports = {
+  HTTP_METHODS,
+  normalizePath,
+  joinPaths,
+  extractPathParams,
+  toPostmanPath,
+  splitPath,
+  toKey,
+  isJsOrTs
+};

package/src/watch.js

@@ -0,0 +1,37 @@
+const chokidar = require('chokidar');
+const { loadConfig, normalizeIncludePatterns, normalizeExcludePatterns, ALWAYS_EXCLUDE } = require('./config');
+const { syncOnce } = require('./sync');
+const { info } = require('./log');
+
+async function watchMode({ configPath, baseDir } = {}) {
+  const { config, baseDir: resolvedBase } = await loadConfig(configPath, baseDir);
+  const cwd = resolvedBase || process.cwd();
+  const include = normalizeIncludePatterns(config.sources.include || [], cwd);
+  const exclude = Array.from(new Set([
+    ...normalizeExcludePatterns(config.sources.exclude || [], cwd),
+    ...ALWAYS_EXCLUDE
+  ]));
+  const debounceMs = (config.watch && config.watch.debounce) || 300;
+
+  info(`Watching for changes...`);
+
+  let timer = null;
+  const trigger = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      syncOnce({ configPath, baseDir: cwd });
+    }, debounceMs);
+  };
+
+  const watcher = chokidar.watch(include, {
+    ignored: exclude,
+    ignoreInitial: true,
+    cwd
+  });
+
+  watcher.on('add', trigger);
+  watcher.on('change', trigger);
+  watcher.on('unlink', trigger);
+}
+
+module.exports = { watchMode };