capman 0.5.5 → 0.6.1

package/dist/esm/parser.js

@@ -31,7 +31,16 @@ async function loadSpec(source) {
         return parseSpecText(text, source);
     }
     // Local file
-    const resolved = path.resolve(process.cwd(), source);
+    const cwd = process.cwd();
+    const resolved = path.resolve(cwd, source);
+    // Guard against path traversal — same check used by FileCache and FileLearningStore.
+    // Prevents parseOpenAPI('../../etc/passwd') from reading arbitrary files when
+    // the source argument comes from user input (CLI args, UI, CI scripts).
+    const allowedPrefix = cwd === '/' ? '/' : cwd + path.sep;
+    if (!resolved.startsWith(allowedPrefix)) {
+        throw new Error(`Spec path "${source}" resolves outside the working directory.\n` +
+            `Resolved: ${resolved}\nAllowed:  ${cwd}`);
+    }
     if (!fs.existsSync(resolved)) {
         throw new Error(`Spec file not found: ${resolved}`);
     }
@@ -101,11 +110,20 @@ function convertSpec(spec) {
                 warnings.push(`Skipped ${method} ${urlPath} — no useful info to generate capability`);
                 continue;
             }
-            // Check for duplicate IDs
-            const existing = capabilities.find(c => c.id === result.id);
-            if (existing) {
-                result.id = `${result.id}_${method.toLowerCase()}`;
-                warnings.push(`Duplicate ID resolved: ${result.id}`);
+            // De-conflict duplicate IDs — loop until the candidate ID is unique.
+            // A single find() check is insufficient: if two operations both produce
+            // `get_user`, the second becomes `get_user_get`. A third `get_user` would
+            // then collide with `get_user_get` only when it also uses GET — the general
+            // multi-collision case is only caught by looping.
+            let candidateId = result.id;
+            let dedupeCount = 0;
+            while (capabilities.find(c => c.id === candidateId)) {
+                dedupeCount++;
+                candidateId = `${result.id}_${method.toLowerCase()}${dedupeCount > 1 ? `_${dedupeCount}` : ''}`;
+            }
+            if (candidateId !== result.id) {
+                warnings.push(`Duplicate ID resolved: ${result.id} → ${candidateId}`);
+                result.id = candidateId;
             }
             capabilities.push(result);
         }
@@ -259,9 +277,9 @@ function extractBaseUrl(spec) {
         const base = spec.basePath ?? '';
         return `${scheme}://${spec.host}${base}`.replace(/\/$/, '');
     }
-    logger.warn(`No server URL found in spec — using placeholder "https://api.your-app.com". ` +
-        `Set baseUrl manually in the generated config before use.`);
-    return 'https://api.your-app.com';
+    throw new Error(`No server URL found in OpenAPI spec — cannot determine base URL.\n` +
+        `Add a "servers" entry (OpenAPI 3.x) or "host" + "basePath" (Swagger 2.x), ` +
+        `or set baseUrl manually in capman.config.js after generating.`);
 }
 function sanitizeAppName(title) {
     return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');

package/dist/esm/resolver.d.ts

@@ -1,4 +1,4 @@
-import type { MatchResult, ResolveResult } from './types';
+import type { MatchResult, ResolveResult, Capability } from './types';
 export interface AuthContext {
     /** Whether the current request is authenticated */
     isAuthenticated: boolean;
@@ -25,5 +25,5 @@ export interface ResolveOptions {
      */
     retryAllMethods?: boolean;
 }
-export declare function checkPrivacy(capability: import('./types').Capability, auth?: AuthContext): string | null;
+export declare function checkPrivacy(capability: Capability, auth?: AuthContext): string | null;
 export declare function resolve(matchResult: MatchResult, params?: Record<string, unknown>, options?: ResolveOptions): Promise<ResolveResult>;

package/dist/esm/resolver.js

@@ -68,13 +68,13 @@ export async function resolve(matchResult, params = {}, options = {}) {
             .map(p => p.name));
         switch (resolver.type) {
             case 'api':
-                return await resolveApi(resolver, enrichedParams, options, sessionParamNames);
+                return await resolveApi(resolver, enrichedParams, options, sessionParamNames, capability.errors ?? []);
             case 'nav':
                 return resolveNav(resolver, enrichedParams);
             case 'hybrid': {
                 logger.debug('Hybrid resolver — running API and nav in parallel');
                 const [apiResult, navResult] = await Promise.all([
-                    resolveApi(resolver.api, enrichedParams, options, sessionParamNames),
+                    resolveApi(resolver.api, enrichedParams, options, sessionParamNames, capability.errors ?? []),
                     Promise.resolve(resolveNav(resolver.nav, enrichedParams)),
                 ]);
                 return {
@@ -116,23 +116,27 @@ export async function resolve(matchResult, params = {}, options = {}) {
  * Full partial success reporting (partialSuccess, completedCalls, failedCalls)
  * is planned for a future version.
  */
-async function resolveApi(resolver, params, options, sessionParamNames = new Set()) {
+async function resolveApi(resolver, params, options, sessionParamNames = new Set(), capabilityErrors = []) {
     const startTime = Date.now();
     const retries = options.retries ?? 0;
     const timeoutMs = options.timeoutMs ?? 5000;
+    // Map url → endpoint metadata for idempotency and Idempotency-Key injection
+    const endpointMeta = new Map();
     const apiCalls = resolver.endpoints.map(endpoint => {
-        // Build per-endpoint params — only inject session params if this
-        // specific endpoint has the placeholder. Prevents userId leaking
-        // as ?user_id=xyz on endpoints that don't use it in their path.
         const endpointParams = { ...params };
         for (const name of sessionParamNames) {
             if (!endpoint.path.includes(`{${name}}`)) {
-                delete endpointParams[name]; // strip session param — not in this endpoint's path
+                delete endpointParams[name];
             }
         }
+        const url = buildUrl(options.baseUrl ?? '', endpoint.path, endpointParams, sessionParamNames);
+        endpointMeta.set(url, {
+            idempotent: endpoint.idempotent,
+            idempotencyKey: endpoint.idempotencyKey,
+        });
         return {
             method: endpoint.method,
-            url: buildUrl(options.baseUrl ?? '', endpoint.path, endpointParams, sessionParamNames),
+            url,
             params: Object.fromEntries(Object.entries(endpointParams).filter(([, v]) => v !== null && v !== undefined)),
         };
     });
@@ -151,23 +155,42 @@ async function resolveApi(resolver, params, options, sessionParamNames = new Set
     // Only retry safe/idempotent methods — retrying POST/PUT/PATCH/DELETE
     // can cause duplicate side effects (e.g. duplicate orders, double charges).
     async function fetchWithRetry(call) {
-        const effectiveRetries = (options.retryAllMethods || SAFE_METHODS.has(call.method))
-            ? retries
-            : 0;
-        let lastErr;
+        const meta = endpointMeta.get(call.url);
+        // Explicit idempotent flag overrides method-based default
+        const isIdempotent = meta?.idempotent !== undefined
+            ? meta.idempotent
+            : SAFE_METHODS.has(call.method);
+        const effectiveRetries = (options.retryAllMethods || isIdempotent) ? retries : 0;
+        let lastErr = new Error('fetchWithRetry: exhausted all attempts without result');
         for (let attempt = 0; attempt <= effectiveRetries; attempt++) {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), timeoutMs);
             try {
+                // Inject Idempotency-Key header when configured
+                const idempotencyHeaders = {};
+                if (meta?.idempotencyKey) {
+                    const keyValue = call.params[meta.idempotencyKey];
+                    if (keyValue !== null && keyValue !== undefined) {
+                        idempotencyHeaders['Idempotency-Key'] = String(keyValue);
+                    }
+                }
                 const res = await fetchFn(call.url, {
                     method: call.method,
-                    headers: options.headers ?? {},
+                    headers: { ...options.headers ?? {}, ...idempotencyHeaders },
                     signal: controller.signal,
                     body: ['POST', 'PUT', 'PATCH'].includes(call.method)
                         ? JSON.stringify(Object.fromEntries(Object.entries(call.params).filter(([, v]) => v !== null && v !== undefined)))
                         : undefined,
                 });
                 clearTimeout(timer);
+                // Throw on retryable 5xx — fetch() resolves (doesn't throw) on HTTP errors,
+                // so without this check a 503 is returned immediately with no retry.
+                // 4xx errors are not retried — they are client errors that won't change.
+                if (res.status >= 500 && attempt < effectiveRetries) {
+                    lastErr = new Error(`HTTP ${res.status}`);
+                    logger.warn(`Server error ${res.status} (attempt ${attempt + 1}/${effectiveRetries + 1}) — retrying`);
+                    continue;
+                }
                 return res;
             }
             catch (err) {
@@ -184,32 +207,49 @@ async function resolveApi(resolver, params, options, sessionParamNames = new Set
         }
         throw lastErr;
     }
+    let enrichedCalls = apiCalls.map(c => ({ ...c }));
     try {
-        const responses = await Promise.all(apiCalls.map(c => fetchWithRetry(c)));
-        const failedIdx = responses.findIndex(r => !r.ok);
-        if (failedIdx !== -1) {
-            const failed = responses[failedIdx];
-            return {
-                success: false, resolverType: 'api', apiCalls,
-                durationMs: Date.now() - startTime,
-                error: `API request failed: ${failed.status} ${failed.statusText}`,
-            };
-        }
-        const enrichedCalls = await Promise.all(responses.map(async (res, i) => {
+        const settled = await Promise.allSettled(apiCalls.map(c => fetchWithRetry(c)));
+        enrichedCalls = await Promise.all(settled.map(async (result, i) => {
+            if (result.status === 'rejected') {
+                const reason = result.reason;
+                logger.warn(`Endpoint ${apiCalls[i].method} ${apiCalls[i].url} failed: ${reason}`);
+                return {
+                    ...apiCalls[i],
+                    status: 0,
+                    error: reason instanceof Error ? reason.message : String(reason),
+                };
+            }
+            const res = result.value;
             let data = undefined;
             try {
                 const text = await res.text();
                 data = text ? JSON.parse(text) : undefined;
             }
-            catch { /* non-JSON response */ }
+            catch { /* non-JSON response body */ }
             return { ...apiCalls[i], status: res.status, data };
         }));
+        const failedCall = enrichedCalls.find(c => typeof c.status === 'number' && (c.status === 0 || c.status >= 400));
+        if (failedCall) {
+            const matchedError = capabilityErrors.find(e => e.httpStatus === failedCall.status);
+            const statusLabel = failedCall.status === 0 ? 'network failure' : String(failedCall.status);
+            return {
+                success: false,
+                resolverType: 'api',
+                apiCalls: enrichedCalls,
+                durationMs: Date.now() - startTime,
+                error: matchedError
+                    ? `${matchedError.code}: ${matchedError.description}`
+                    : `API request failed: ${statusLabel} on ${failedCall.method} ${failedCall.url}`,
+                matchedError,
+            };
+        }
         logger.debug(`API calls completed in ${Date.now() - startTime}ms`);
         return { success: true, resolverType: 'api', apiCalls: enrichedCalls, durationMs: Date.now() - startTime };
     }
     catch (err) {
         return {
-            success: false, resolverType: 'api', apiCalls,
+            success: false, resolverType: 'api', apiCalls: enrichedCalls,
             durationMs: Date.now() - startTime,
             error: err instanceof Error ? err.message : String(err),
         };