capman 0.6.0 → 0.6.2

package/dist/esm/schema.js

@@ -5,17 +5,22 @@ const CapabilityParamSchema = z.object({
     description: z.string().min(1, 'param description is required'),
     required: z.boolean(),
     source: z.enum(['user_query', 'session']),
-    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
     pattern: z.string().optional(),
-});
+    type: z.enum(['string', 'number', 'boolean', 'date', 'email', 'url', 'enum', 'object']).optional(),
+    enum: z.array(z.string()).optional(),
+    example: z.string().optional(),
+}).refine(p => !(p.type === 'enum' && (!p.enum || p.enum.length === 0)), { message: 'enum values required when type is "enum"' });
 // ─── Resolver Schemas ─────────────────────────────────────────────────────────
+const EndpointSchema = z.object({
+    method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']),
+    path: z.string().min(1, 'endpoint path is required'),
+    params: z.array(z.string()).optional(),
+    idempotent: z.boolean().optional(),
+    idempotencyKey: z.string().optional(),
+});
 const ApiResolverSchema = z.object({
     type: z.literal('api'),
-    endpoints: z.array(z.object({
-        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
-        path: z.string().min(1, 'endpoint path is required'),
-        params: z.array(z.string()).optional(),
-    })).min(1, 'at least one endpoint is required'),
+    endpoints: z.array(EndpointSchema).min(1, 'at least one endpoint is required'),
 });
 const NavResolverSchema = z.object({
     type: z.literal('nav'),
@@ -25,11 +30,7 @@ const NavResolverSchema = z.object({
 const HybridResolverSchema = z.object({
     type: z.literal('hybrid'),
     api: z.object({
-        endpoints: z.array(z.object({
-            method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
-            path: z.string().min(1),
-            params: z.array(z.string()).optional(),
-        })).min(1),
+        endpoints: z.array(EndpointSchema).min(1),
     }),
     nav: z.object({
         destination: z.string().min(1),
@@ -46,6 +47,22 @@ const PrivacyScopeSchema = z.object({
     level: z.enum(['public', 'user_owned', 'admin']),
     note: z.string().optional(),
 });
+const LifecycleInfoSchema = z.object({
+    status: z.enum(['stable', 'beta', 'experimental', 'deprecated']),
+    deprecatedAt: z.string().datetime().optional(),
+    sunsetAt: z.string().datetime().optional(),
+    successor: z.string().optional(),
+    note: z.string().optional(),
+});
+const MatchHintSchema = z.object({
+    preferredMode: z.enum(['cheap', 'balanced', 'accurate']).optional(),
+});
+const CapabilityErrorSchema = z.object({
+    code: z.string().min(1, 'error code is required'),
+    description: z.string().min(1, 'error description is required'),
+    httpStatus: z.number().int().min(400).max(599).optional(),
+    retryable: z.boolean().optional(),
+});
 // ─── Capability Schema ────────────────────────────────────────────────────────
 const CapabilitySchema = z.object({
     id: z.string().min(1, 'capability id is required')
@@ -59,24 +76,56 @@ const CapabilitySchema = z.object({
     returns: z.array(z.string()),
     resolver: ResolverSchema,
     privacy: PrivacyScopeSchema,
+    lifecycle: LifecycleInfoSchema.optional(),
+    tags: z.array(z.string().min(1)).optional(),
+    errors: z.array(CapabilityErrorSchema).optional(),
+    matchHint: MatchHintSchema.optional(),
+});
+const ServerSchema = z.object({
+    url: z.string().url('server url must be a valid URL'),
+    description: z.string().optional(),
+    environment: z.string().optional(),
+});
+// ─── ManifestInfo Schema ──────────────────────────────────────────────────────
+const ManifestInfoSchema = z.object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+    version: z.string().optional(),
+    homepage: z.string().url().optional(),
+    contact: z.object({
+        name: z.string().optional(),
+        email: z.string().email().optional(),
+        url: z.string().url().optional(),
+    }).optional(),
+    license: z.object({
+        name: z.string().min(1, 'license name is required'),
+        url: z.string().url().optional(),
+    }).optional(),
 });
 // ─── Config Schema ────────────────────────────────────────────────────────────
 export const CapmanConfigSchema = z.object({
     app: z.string().min(1, 'app name is required'),
     baseUrl: z.string().url().optional(),
+    info: ManifestInfoSchema.optional(),
+    servers: z.array(ServerSchema).optional(),
+    tagRegistry: z.record(z.object({ description: z.string() })).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;
+    return !needsBaseUrl || !!cfg.baseUrl || (cfg.servers?.length ?? 0) > 0;
 }, { message: 'baseUrl is required when any capability uses an api or hybrid resolver' });
 // ─── Manifest Schema ──────────────────────────────────────────────────────────
 export const ManifestSchema = z.object({
+    schemaVersion: z.string().min(1, 'schemaVersion is required'),
     version: z.string(),
     app: z.string().min(1),
     generatedAt: z.string().datetime(),
     capabilities: z.array(CapabilitySchema).min(1),
+    tagRegistry: z.record(z.object({ description: z.string() })).optional(),
+    servers: z.array(ServerSchema).optional(),
+    info: ManifestInfoSchema.optional(),
 });
 export function validateConfig(config) {
     const result = CapmanConfigSchema.safeParse(config);

package/dist/esm/types.d.ts

@@ -1,5 +1,6 @@
 export type ResolverType = 'api' | 'nav' | 'hybrid';
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+export type ParamType = 'string' | 'number' | 'boolean' | 'date' | 'email' | 'url' | 'enum' | 'object';
 export interface CapabilityParam {
     name: string;
     description: string;
@@ -9,17 +10,49 @@ export interface CapabilityParam {
      * Optional extraction hint. Either a named type or an example template.
      * Named types: 'email' | 'date' | 'orderId' | 'url'
      * Example template: "order {paramName}" — extracts token after "order"
-     * When provided, pattern matching runs before keyword heuristics.
      */
     pattern?: string;
+    /**
+     * Semantic type of the parameter value.
+     * When set, implies a TYPE_PATTERNS match without requiring pattern to be set.
+     * 'email', 'date', 'url' map directly to TYPE_PATTERNS regex.
+     * 'enum' requires the enum field to be set with allowed values.
+     * 'number', 'boolean', 'object' affect coercion in LLM extraction.
+     */
+    type?: ParamType;
+    /**
+     * Allowed values when type === 'enum'.
+     * Extracted values not in this list are rejected and added to missingParams.
+     */
+    enum?: string[];
+    /**
+     * Single concrete example for LLM param prompting.
+     * Helps the LLM understand what a valid value looks like.
+     * e.g. example: "ORD-12345"
+     */
+    example?: string;
+}
+export interface Endpoint {
+    method: HttpMethod;
+    path: string;
+    params?: string[];
+    /**
+     * Whether this endpoint is idempotent — safe to retry on failure.
+     * Defaults: true for GET/HEAD/OPTIONS, false for POST/PUT/PATCH/DELETE.
+     * Set explicitly to override — e.g. `idempotent: true` on a POST
+     * with an idempotency key allows retries without `retryAllMethods: true`.
+     */
+    idempotent?: boolean;
+    /**
+     * Name of the param whose value is sent as the `Idempotency-Key` header.
+     * When set and the param is available, the header is injected automatically.
+     * e.g. idempotencyKey: 'order_id' → `Idempotency-Key: ORD-12345`
+     */
+    idempotencyKey?: string;
 }
 export interface ApiResolver {
     type: 'api';
-    endpoints: Array<{
-        method: HttpMethod;
-        path: string;
-        params?: string[];
-    }>;
+    endpoints: Endpoint[];
 }
 export interface NavResolver {
     type: 'nav';
@@ -36,6 +69,50 @@ export interface PrivacyScope {
     level: 'public' | 'user_owned' | 'admin';
     note?: string;
 }
+export type LifecycleStatus = 'stable' | 'beta' | 'experimental' | 'deprecated';
+export interface LifecycleInfo {
+    status: LifecycleStatus;
+    /** ISO 8601 — when the capability was deprecated */
+    deprecatedAt?: string;
+    /** ISO 8601 — when the capability will stop working */
+    sunsetAt?: string;
+    /** Capability id to use instead of this one */
+    successor?: string;
+    /** Human-readable note for consumers */
+    note?: string;
+}
+/**
+ * Optional embedding provider for semantic similarity matching.
+ * Zero mandatory dependency — only used when passed to EngineOptions.
+ * Implement with any model: OpenAI, local ONNX, Transformers.js, etc.
+ */
+export interface EmbeddingProvider {
+    /** Encode a batch of texts into fixed-length float vectors. */
+    encode(texts: string[]): Promise<number[][]>;
+}
+export interface MatchHint {
+    /**
+     * Advisory preferred matching mode for this capability.
+     * The engine logs when it ignores the hint (e.g. engine is in cheap mode
+     * but capability prefers accurate). Never enforced — library must not
+     * restrict what consumers can do.
+     */
+    preferredMode?: MatchMode;
+}
+export interface CapabilityError {
+    /** Machine-readable error code e.g. "ORDER_NOT_FOUND", "INSUFFICIENT_FUNDS" */
+    code: string;
+    /** Human-readable description for developers */
+    description: string;
+    /** HTTP status code this error maps to */
+    httpStatus?: number;
+    /**
+     * Whether the agent should retry after this error.
+     * true  — transient (503, timeout) — retry is safe
+     * false — permanent (422, 404) — retrying won't help, ask user
+     */
+    retryable?: boolean;
+}
 export interface Capability {
     id: string;
     name: string;
@@ -45,17 +122,82 @@ export interface Capability {
     returns: string[];
     resolver: Resolver;
     privacy: PrivacyScope;
+    /** Lifecycle status — defaults to 'stable' when absent */
+    lifecycle?: LifecycleInfo;
+    /** Tags for grouping and filtering capabilities */
+    tags?: string[];
+    errors?: CapabilityError[];
+    matchHint?: MatchHint;
+}
+export interface ManifestInfo {
+    /** Human-readable title for the app */
+    title?: string;
+    /** Brief description of what the app does */
+    description?: string;
+    /** App's own version — distinct from capman package version */
+    version?: string;
+    /** URL to the app's homepage or documentation */
+    homepage?: string;
+    contact?: {
+        name?: string;
+        email?: string;
+        url?: string;
+    };
+    license?: {
+        /** SPDX license identifier e.g. "MIT", "Apache-2.0" */
+        name: string;
+        url?: string;
+    };
+}
+export interface Server {
+    url: string;
+    description?: string;
+    /**
+     * Environment this server belongs to.
+     * Engine selects server by matching EngineOptions.environment.
+     * Fallback: first server in array when no environment matches.
+     */
+    environment?: 'production' | 'staging' | 'development' | string;
 }
 export interface Manifest {
+    /**
+     * Manifest format version — independent of the capman package version.
+     * Consumers use this to determine which parser/validator to apply.
+     * "1" = v0.6+ schema (tags, lifecycle, typed params, servers, etc.)
+     */
+    schemaVersion: string;
+    /** capman package version that generated this manifest */
     version: string;
     app: string;
     generatedAt: string;
     capabilities: Capability[];
+    /**
+     * Optional registry of known tags with descriptions.
+     * Used for documentation and validation — not required for tags to work.
+     */
+    tagRegistry?: Record<string, {
+        description: string;
+    }>;
+    /** Optional metadata block for documentation and provenance */
+    info?: ManifestInfo;
+    /**
+     * Server definitions. When present, engine selects baseUrl from this list.
+     * Falls back to EngineOptions.baseUrl if servers is absent or no match found.
+     */
+    servers?: Server[];
 }
 export interface CapmanConfig {
     app: string;
     baseUrl?: string;
     capabilities: Capability[];
+    /** Optional metadata — written to manifest.info */
+    info?: ManifestInfo;
+    /** Optional tag registry — written to manifest.tagRegistry */
+    tagRegistry?: Record<string, {
+        description: string;
+    }>;
+    /** Server definitions — written to manifest.servers */
+    servers?: Server[];
 }
 export interface MatchResult {
     capability: Capability | null;
@@ -74,15 +216,20 @@ export interface ApiCallResult {
     status?: number;
     /** Parsed JSON response body — only present when actually executed */
     data?: unknown;
+    /** Error message — only present on network-level failure (status 0) */
+    error?: string;
 }
 export interface ResolveResult {
     success: boolean;
     resolverType: ResolverType | null;
+    error?: string;
+    /** Structured error from capability.errors[] when httpStatus matches */
+    matchedError?: CapabilityError;
     apiCalls?: ApiCallResult[];
     navTarget?: string;
-    /** Execution time in milliseconds */
+    status?: number;
+    data?: unknown;
     durationMs?: number;
-    error?: string;
 }
 export interface ValidationResult {
     valid: boolean;

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.5";
+export declare const VERSION = "0.6.1";

package/dist/esm/version.js

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

package/package.json

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