capman 0.5.2 → 0.5.4

package/dist/esm/resolver.js

@@ -1,4 +1,6 @@
 import { logger } from './logger';
+// ─── Constants ────────────────────────────────────────────────────────────────
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
 function redactParams(params) {
     return Object.fromEntries(Object.entries(params).map(([k, v]) => [k, v != null ? '[REDACTED]' : 'null']));
 }
@@ -49,12 +51,8 @@ export async function resolve(matchResult, params = {}, options = {}) {
     // they must never leak into the query string as ?user_id=xyz
     const enrichedParams = { ...params };
     if (options.auth?.userId !== undefined && options.auth.userId !== '') {
-        const resolver = capability.resolver;
-        const pathTemplate = resolver.type === 'api' ? resolver.endpoints.map(e => e.path).join('') :
-            resolver.type === 'hybrid' ? resolver.api.endpoints.map(e => e.path).join('') :
-                resolver.type === 'nav' ? resolver.destination : '';
         for (const param of capability.params) {
-            if (param.source === 'session' && pathTemplate.includes(`{${param.name}}`)) {
+            if (param.source === 'session') {
                 enrichedParams[param.name] = options.auth.userId;
                 logger.debug(`Injected session param "${param.name}" (value redacted)`);
             }
@@ -65,15 +63,18 @@ export async function resolve(matchResult, params = {}, options = {}) {
     logger.debug(`Params: ${JSON.stringify(redactParams(params))}`);
     logger.debug(`Options: baseUrl=${options.baseUrl} dryRun=${options.dryRun}`);
     try {
+        const sessionParamNames = new Set(capability.params
+            .filter(p => p.source === 'session')
+            .map(p => p.name));
         switch (resolver.type) {
             case 'api':
-                return await resolveApi(resolver, enrichedParams, options);
+                return await resolveApi(resolver, enrichedParams, options, sessionParamNames);
             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),
+                    resolveApi(resolver.api, enrichedParams, options, sessionParamNames),
                     Promise.resolve(resolveNav(resolver.nav, enrichedParams)),
                 ]);
                 return {
@@ -109,15 +110,26 @@ export async function resolve(matchResult, params = {}, options = {}) {
  * For capabilities where ordering or rollback matters, define separate capabilities
  * with single endpoints and orchestrate them at the application layer.
  */
-async function resolveApi(resolver, params, options) {
+async function resolveApi(resolver, params, options, sessionParamNames = new Set()) {
     const startTime = Date.now();
     const retries = options.retries ?? 0;
     const timeoutMs = options.timeoutMs ?? 5000;
-    const apiCalls = resolver.endpoints.map(endpoint => ({
-        method: endpoint.method,
-        url: buildUrl(options.baseUrl ?? '', endpoint.path, params),
-        params: Object.fromEntries(Object.entries(params).filter(([, v]) => v !== null && v !== undefined)),
-    }));
+    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
+            }
+        }
+        return {
+            method: endpoint.method,
+            url: buildUrl(options.baseUrl ?? '', endpoint.path, endpointParams),
+            params: Object.fromEntries(Object.entries(endpointParams).filter(([, v]) => v !== null && v !== undefined)),
+        };
+    });
     if (options.dryRun) {
         return { success: true, resolverType: 'api', apiCalls, durationMs: Date.now() - startTime };
     }
@@ -130,9 +142,14 @@ async function resolveApi(resolver, params, options) {
         };
     }
     // ── Fetch with retry + timeout (iterative — no recursion) ────────────────
+    // 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;
-        for (let attempt = 0; attempt <= retries; attempt++) {
+        for (let attempt = 0; attempt <= effectiveRetries; attempt++) {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), timeoutMs);
             try {
@@ -151,8 +168,8 @@ async function resolveApi(resolver, params, options) {
                 clearTimeout(timer);
                 lastErr = err;
                 const isTimeout = err instanceof Error && err.name === 'AbortError';
-                if (attempt < retries) {
-                    logger.warn(`Request failed (attempt ${attempt + 1}/${retries + 1}) — retrying: ${isTimeout ? 'timeout' : err}`);
+                if (attempt < effectiveRetries) {
+                    logger.warn(`Request failed (attempt ${attempt + 1}/${effectiveRetries + 1}) — retrying: ${isTimeout ? 'timeout' : err}`);
                 }
                 else {
                     throw isTimeout ? new Error(`Request timed out after ${timeoutMs}ms`) : err;
@@ -209,12 +226,17 @@ function resolveNav(resolver, params) {
     }
     return { success: true, resolverType: 'nav', navTarget: destination };
 }
-// Note: buildUrl does not validate param values against an allowlist.
-// resolveNav() does validate via validateNavParam() because nav destinations
-// are used as deep links where path traversal is a real risk.
-// For API URLs, extractParams() strips most dangerous characters upstream,
-// so the practical risk is low — but any future caller bypassing extractParams
-// should add validation here too.
+function validateApiPathParam(key, value) {
+    // Prevent path traversal via unencoded slashes — encodeURIComponent does not
+    // encode '/' so a value like '../../admin' would traverse the path hierarchy.
+    // This mirrors the allowlist validation already applied in resolveNav().
+    if (!/^[a-zA-Z0-9_\-.:@]+$/.test(value)) {
+        throw new Error(`API path param "${key}" contains invalid characters: "${value}". ` +
+            `Only alphanumeric, hyphens, underscores, dots, colons, and @ are allowed.`);
+    }
+}
+// Both buildUrl (API) and resolveNav (nav) validate path param values against
+// an allowlist before substitution — prevents path traversal via unencoded slashes.
 function buildUrl(baseUrl, urlPath, params) {
     let resolved = urlPath;
     const unused = {};
@@ -222,7 +244,9 @@ function buildUrl(baseUrl, urlPath, params) {
         if (value === null || value === undefined)
             continue; // never write null into URLs
         if (resolved.includes(`{${key}}`)) {
-            resolved = resolved.replaceAll(`{${key}}`, encodeURIComponent(String(value)));
+            const str = String(value);
+            validateApiPathParam(key, str);
+            resolved = resolved.replaceAll(`{${key}}`, encodeURIComponent(str));
         }
         else {
             unused[key] = value;

package/dist/esm/schema.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-export declare const CapmanConfigSchema: z.ZodObject<{
+export declare const CapmanConfigSchema: z.ZodEffects<z.ZodObject<{
     app: z.ZodString;
     baseUrl: z.ZodOptional<z.ZodString>;
     capabilities: z.ZodEffects<z.ZodArray<z.ZodObject<{
@@ -405,6 +405,98 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         examples?: string[] | undefined;
     }[];
     baseUrl?: string | undefined;
+}>, {
+    app: string;
+    capabilities: {
+        name: string;
+        id: string;
+        params: {
+            name: string;
+            required: boolean;
+            description: string;
+            source: "user_query" | "session" | "context" | "static";
+            default?: string | number | boolean | undefined;
+        }[];
+        description: string;
+        returns: string[];
+        resolver: {
+            type: "api";
+            endpoints: {
+                method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+                path: string;
+                params?: string[] | undefined;
+            }[];
+        } | {
+            type: "nav";
+            destination: string;
+            hint?: string | undefined;
+        } | {
+            type: "hybrid";
+            api: {
+                endpoints: {
+                    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+                    path: string;
+                    params?: string[] | undefined;
+                }[];
+            };
+            nav: {
+                destination: string;
+                hint?: string | undefined;
+            };
+        };
+        privacy: {
+            level: "public" | "user_owned" | "admin";
+            note?: string | undefined;
+        };
+        examples?: string[] | undefined;
+    }[];
+    baseUrl?: string | undefined;
+}, {
+    app: string;
+    capabilities: {
+        name: string;
+        id: string;
+        params: {
+            name: string;
+            required: boolean;
+            description: string;
+            source: "user_query" | "session" | "context" | "static";
+            default?: string | number | boolean | undefined;
+        }[];
+        description: string;
+        returns: string[];
+        resolver: {
+            type: "api";
+            endpoints: {
+                method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+                path: string;
+                params?: string[] | undefined;
+            }[];
+        } | {
+            type: "nav";
+            destination: string;
+            hint?: string | undefined;
+        } | {
+            type: "hybrid";
+            api: {
+                endpoints: {
+                    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+                    path: string;
+                    params?: string[] | undefined;
+                }[];
+            };
+            nav: {
+                destination: string;
+                hint?: string | undefined;
+            };
+        };
+        privacy: {
+            level: "public" | "user_owned" | "admin";
+            note?: string | undefined;
+        };
+        examples?: string[] | undefined;
+    }[];
+    baseUrl?: string | undefined;
 }>;
 export declare const ManifestSchema: z.ZodObject<{
     version: z.ZodString;

package/dist/esm/schema.js

@@ -62,11 +62,14 @@ const CapabilitySchema = z.object({
 // ─── Config Schema ────────────────────────────────────────────────────────────
 export const CapmanConfigSchema = z.object({
     app: z.string().min(1, 'app name is required'),
-    baseUrl: z.string().url('baseUrl must be a valid URL').optional(),
+    baseUrl: z.string().url().optional(),
     capabilities: z.array(CapabilitySchema)
         .min(1, 'at least one capability is required')
         .refine(caps => new Set(caps.map(c => c.id)).size === caps.length, 'capability ids must be unique'),
-});
+}).refine(cfg => {
+    const needsBaseUrl = cfg.capabilities.some(c => c.resolver.type === 'api' || c.resolver.type === 'hybrid');
+    return !needsBaseUrl || !!cfg.baseUrl;
+}, { message: 'baseUrl is required when any capability uses an api or hybrid resolver' });
 // ─── Manifest Schema ──────────────────────────────────────────────────────────
 export const ManifestSchema = z.object({
     version: z.string(),

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.2";
+export declare const VERSION = "0.5.3";

package/dist/esm/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/version.js — do not edit manually
-export const VERSION = '0.5.2';
+export const VERSION = '0.5.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capman",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Capability Manifest Engine — let AI agents interact with your app without navigating the UI",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -29,15 +29,15 @@
     "CODEBASE.md"
   ],
   "scripts": {
-    "prebuild":   "node scripts/version.js",
-    "build:cjs":  "tsc --project tsconfig.json",
-    "build:esm":  "tsc --project tsconfig.esm.json",
-    "build":      "pnpm run build:cjs && pnpm run build:esm",
-    "dev":        "tsc --watch",
-    "example":    "tsx examples/basic.ts",
-    "validate":   "node bin/capman.js validate",
-    "inspect":    "node bin/capman.js inspect",
-    "test":       "vitest run"
+    "prebuild": "node scripts/version.js",
+    "build:cjs": "tsc --project tsconfig.json",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build": "pnpm run build:cjs && pnpm run build:esm",
+    "dev": "tsc --watch",
+    "example": "tsx examples/basic.ts",
+    "validate": "node bin/capman.js validate",
+    "inspect": "node bin/capman.js inspect",
+    "test": "vitest run"
   },
   "keywords": [
     "ai",
@@ -56,6 +56,7 @@
   },
   "dependencies": {
     "dotenv": "^17.3.1",
+    "fuse.js": "^7.3.0",
     "zod": "^3.23.0"
   }
 }