capman 0.5.1 → 0.5.3

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 {
@@ -95,15 +96,40 @@ export async function resolve(matchResult, params = {}, options = {}) {
         };
     }
 }
-async function resolveApi(resolver, params, options) {
+/**
+ * Resolves an API capability by executing all configured endpoints.
+ *
+ * ⚠️  PARALLEL EXECUTION: All endpoints are fired simultaneously via Promise.all().
+ * If any endpoint fails, the entire result is marked as failed and partial results
+ * are discarded — but side effects from successful endpoints cannot be rolled back.
+ *
+ * Example: a capability with two endpoints [POST /reserve, POST /confirm] will
+ * fire both in parallel. If /confirm fails after /reserve succeeded, the reservation
+ * exists but the caller receives success: false with no indication that /reserve ran.
+ *
+ * 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, 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,
-    }));
+    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 };
     }
@@ -116,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 {
@@ -127,7 +158,7 @@ async function resolveApi(resolver, params, options) {
                     headers: options.headers ?? {},
                     signal: controller.signal,
                     body: ['POST', 'PUT', 'PATCH'].includes(call.method)
-                        ? JSON.stringify(call.params)
+                        ? JSON.stringify(Object.fromEntries(Object.entries(call.params).filter(([, v]) => v !== null && v !== undefined)))
                         : undefined,
                 });
                 clearTimeout(timer);
@@ -137,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;
@@ -191,10 +222,21 @@ function resolveNav(resolver, params) {
             continue;
         const str = String(value);
         validateNavParam(key, str);
-        destination = destination.replace(`{${key}}`, encodeURIComponent(str));
+        destination = destination.replaceAll(`{${key}}`, encodeURIComponent(str));
     }
     return { success: true, resolverType: 'nav', navTarget: destination };
 }
+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 = {};
@@ -202,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.replace(`{${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<{
@@ -108,6 +108,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 hint?: string | undefined;
             }>;
         }, "strip", z.ZodTypeAny, {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -119,8 +120,8 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         }, {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -132,7 +133,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         }>]>;
         privacy: z.ZodObject<{
             level: z.ZodEnum<["public", "user_owned", "admin"]>;
@@ -168,6 +168,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -179,7 +180,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -210,6 +210,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -221,7 +222,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -252,6 +252,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -263,7 +264,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -294,6 +294,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -305,7 +306,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -339,6 +339,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -350,7 +351,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -385,6 +385,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -396,7 +397,98 @@ export declare const CapmanConfigSchema: z.ZodObject<{
                 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;
+}, {
+    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";
@@ -516,6 +608,7 @@ export declare const ManifestSchema: z.ZodObject<{
                 hint?: string | undefined;
             }>;
         }, "strip", z.ZodTypeAny, {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -527,8 +620,8 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         }, {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -540,7 +633,6 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         }>]>;
         privacy: z.ZodObject<{
             level: z.ZodEnum<["public", "user_owned", "admin"]>;
@@ -576,6 +668,7 @@ export declare const ManifestSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -587,7 +680,6 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -618,6 +710,7 @@ export declare const ManifestSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -629,7 +722,6 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -664,6 +756,7 @@ export declare const ManifestSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -675,7 +768,6 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";
@@ -711,6 +803,7 @@ export declare const ManifestSchema: z.ZodObject<{
             destination: string;
             hint?: string | undefined;
         } | {
+            type: "hybrid";
             api: {
                 endpoints: {
                     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -722,7 +815,6 @@ export declare const ManifestSchema: z.ZodObject<{
                 destination: string;
                 hint?: string | undefined;
             };
-            type: "hybrid";
         };
         privacy: {
             level: "public" | "user_owned" | "admin";

package/dist/esm/schema.js

@@ -50,8 +50,10 @@ const CapabilitySchema = z.object({
     id: z.string().min(1, 'capability id is required')
         .regex(/^[a-z0-9_]+$/, 'id must be snake_case (lowercase, numbers, underscores only)'),
     name: z.string().min(1, 'capability name is required'),
-    description: z.string().min(10, 'description must be at least 10 characters for accurate matching'),
-    examples: z.array(z.string()).optional(),
+    description: z.string()
+        .min(10, 'description must be at least 10 characters for accurate matching')
+        .max(500, 'description must be 500 characters or fewer'),
+    examples: z.array(z.string().max(200, 'each example must be 200 characters or fewer')).optional(),
     params: z.array(CapabilityParamSchema),
     returns: z.array(z.string()),
     resolver: ResolverSchema,
@@ -60,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/types.d.ts

@@ -134,3 +134,4 @@ export interface ExplainResult {
     resolvedVia: 'keyword' | 'llm';
     durationMs: number;
 }
+export type MatchMode = 'cheap' | 'balanced' | 'accurate';

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.1";
+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.1';
+export const VERSION = '0.5.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capman",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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",