capman 0.4.2 → 0.4.3

package/dist/esm/engine.js

@@ -6,6 +6,12 @@ import { MemoryCache, normalizeQuery } from './cache';
 // ─── CapmanEngine ─────────────────────────────────────────────────────────────
 export class CapmanEngine {
     constructor(options) {
+        // ── LLM rate limiting state ────────────────────────────────────────────────
+        this.llmCallsThisMinute = 0;
+        this.llmWindowStart = Date.now();
+        this.llmLastCallAt = 0;
+        this.llmConsecutiveFails = 0;
+        this.llmCircuitOpenAt = 0;
         this.manifest = options.manifest;
         this.mode = options.mode ?? 'balanced';
         this.llm = options.llm;
@@ -13,6 +19,10 @@ export class CapmanEngine {
         this.auth = options.auth;
         this.headers = options.headers;
         this.threshold = options.threshold ?? 50;
+        this.maxLLMCallsPerMinute = options.maxLLMCallsPerMinute ?? 60;
+        this.llmCooldownMs = options.llmCooldownMs ?? 0;
+        this.llmCircuitBreakerThreshold = options.llmCircuitBreakerThreshold ?? 3;
+        this.llmCircuitBreakerResetMs = options.llmCircuitBreakerResetMs ?? 60000;
         // Cache — default MemoryCache (no filesystem writes), or disabled with false
         // Use FileCache or ComboCache explicitly for persistence across restarts
         this.cache = options.cache === false
@@ -51,7 +61,7 @@ export class CapmanEngine {
                 const resolution = await _resolve(cached.result, cached.result.extractedParams, this.resolveOptions(overrides));
                 const trace = {
                     query,
-                    candidates: cached.result.candidates ?? [],
+                    candidates: cached.result.candidates,
                     reasoning: [`Served from cache (original: ${cached.result.reasoning})`],
                     steps,
                     resolvedVia: 'cache',
@@ -83,10 +93,30 @@ export class CapmanEngine {
             }
             case 'accurate': {
                 if (this.llm) {
-                    const t = Date.now();
-                    matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
-                    resolvedVia = 'llm';
-                    steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
+                    const skipReason = this.checkLLMAllowed();
+                    if (skipReason) {
+                        logger.warn(`LLM skipped — ${skipReason} — falling back to keyword`);
+                        const t = Date.now();
+                        matchResult = _match(query, this.manifest);
+                        steps.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t, detail: `llm skipped: ${skipReason}` });
+                    }
+                    else {
+                        const t = Date.now();
+                        try {
+                            matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                            this.recordLLMSuccess();
+                            resolvedVia = 'llm';
+                            steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
+                        }
+                        catch (err) {
+                            this.recordLLMFailure();
+                            logger.warn(`LLM call failed — falling back to keyword: ${err}`);
+                            const t2 = Date.now();
+                            matchResult = _match(query, this.manifest);
+                            steps.push({ type: 'llm_match', status: 'fail', durationMs: Date.now() - t, detail: String(err) });
+                            steps.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t2, detail: 'fallback after llm failure' });
+                        }
+                    }
                 }
                 else {
                     logger.warn('accurate mode requires llm — falling back to keyword');
@@ -105,11 +135,28 @@ export class CapmanEngine {
                     matchResult = keywordResult;
                 }
                 else {
-                    logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
-                    const t2 = Date.now();
-                    matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
-                    resolvedVia = 'llm';
-                    steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
+                    const skipReason = this.checkLLMAllowed();
+                    if (skipReason) {
+                        logger.warn(`LLM skipped — ${skipReason}`);
+                        steps.push({ type: 'llm_match', status: 'skip', durationMs: 0, detail: skipReason });
+                        matchResult = keywordResult;
+                    }
+                    else {
+                        logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
+                        const t2 = Date.now();
+                        try {
+                            matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                            this.recordLLMSuccess();
+                            resolvedVia = 'llm';
+                            steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
+                        }
+                        catch (err) {
+                            this.recordLLMFailure();
+                            logger.warn(`LLM call failed — falling back to keyword: ${err}`);
+                            steps.push({ type: 'llm_match', status: 'fail', durationMs: Date.now() - t2, detail: String(err) });
+                            matchResult = keywordResult;
+                        }
+                    }
                 }
                 break;
             }
@@ -140,7 +187,7 @@ export class CapmanEngine {
         });
         // ── Step 6: Build reasoning array ────────────────────────────────────────
         const reasoning = [];
-        if (matchResult.candidates?.length) {
+        if (matchResult.candidates.length) {
             const winner = matchResult.candidates.find(c => c.matched);
             const rejected = matchResult.candidates
                 .filter(c => !c.matched && c.score > 0)
@@ -167,7 +214,7 @@ export class CapmanEngine {
         await this.recordLearning(query, matchResult, resolvedVia);
         const trace = {
             query,
-            candidates: matchResult.candidates ?? [],
+            candidates: matchResult.candidates,
             reasoning,
             steps,
             resolvedVia,
@@ -205,6 +252,254 @@ export class CapmanEngine {
         if (this.cache)
             await this.cache.clear();
     }
+    /**
+     * Explain what would happen for a query — without executing it.
+     * Shows matched capability, all candidate scores with reasoning,
+     * and what action would be taken.
+     *
+     * @example
+     * const explanation = await engine.explain('track order 1234')
+     * console.log(explanation.matched.reasoning)
+     * console.log(explanation.wouldExecute.action)
+     * console.log(explanation.candidates)
+     */
+    async explain(query) {
+        const start = Date.now();
+        // ── Match — mirrors ask() logic including rate limiting ───────────────────
+        let matchResult;
+        let resolvedVia = 'keyword';
+        if (this.mode === 'accurate') {
+            if (this.llm) {
+                const skipReason = this.checkLLMAllowed();
+                if (skipReason) {
+                    logger.warn(`explain(): LLM skipped — ${skipReason} — falling back to keyword`);
+                    matchResult = _match(query, this.manifest);
+                }
+                else {
+                    try {
+                        matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                        this.recordLLMSuccess();
+                        resolvedVia = 'llm';
+                    }
+                    catch (err) {
+                        this.recordLLMFailure();
+                        logger.warn(`explain(): LLM call failed — falling back to keyword: ${err}`);
+                        matchResult = _match(query, this.manifest);
+                    }
+                }
+            }
+            else {
+                matchResult = _match(query, this.manifest);
+            }
+        }
+        else if (this.mode === 'balanced' && this.llm) {
+            // Keyword first — escalate to LLM if low confidence (same as ask())
+            const keywordResult = _match(query, this.manifest);
+            if (keywordResult.confidence >= this.threshold) {
+                matchResult = keywordResult;
+            }
+            else {
+                const skipReason = this.checkLLMAllowed();
+                if (skipReason) {
+                    logger.warn(`explain(): LLM skipped — ${skipReason}`);
+                    matchResult = keywordResult;
+                }
+                else {
+                    try {
+                        matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                        this.recordLLMSuccess();
+                        resolvedVia = 'llm';
+                    }
+                    catch (err) {
+                        this.recordLLMFailure();
+                        logger.warn(`explain(): LLM call failed — falling back to keyword: ${err}`);
+                        matchResult = keywordResult;
+                    }
+                }
+            }
+        }
+        else {
+            // cheap mode or no llm — keyword only
+            matchResult = _match(query, this.manifest);
+        }
+        // ── Build candidate explanations ─────────────────────────────────────────
+        const candidates = matchResult.candidates
+            .sort((a, b) => b.score - a.score)
+            .map(c => {
+            const cap = this.manifest.capabilities.find(mc => mc.id === c.capabilityId);
+            let explanation = '';
+            if (c.score === 0) {
+                explanation = 'No keyword overlap with examples or description';
+            }
+            else if (c.score >= 90) {
+                explanation = `Strong match (${c.score}%) — query closely matches examples`;
+            }
+            else if (c.score >= 50) {
+                const qWords = query.toLowerCase().split(/\W+/).filter(Boolean);
+                const matchedWords = (cap?.examples ?? [])
+                    .flatMap(e => e.toLowerCase().split(/\s+/))
+                    .filter(w => qWords.includes(w) && w.length > 2);
+                const unique = [...new Set(matchedWords)].slice(0, 3);
+                explanation = unique.length
+                    ? `Matched keywords: ${unique.join(', ')} (${c.score}%)`
+                    : `Partial match (${c.score}%) — some keyword overlap`;
+            }
+            else {
+                explanation = `Weak match (${c.score}%) — below 50% confidence threshold, rejected`;
+            }
+            return { capabilityId: c.capabilityId, score: c.score, matched: c.matched, explanation };
+        });
+        // ── Build reasoning array ────────────────────────────────────────────────
+        const reasoning = [];
+        const winner = candidates.find(c => c.matched);
+        const rejected = candidates.filter(c => !c.matched && c.score > 0).slice(0, 3);
+        if (winner) {
+            reasoning.push(`Matched "${winner.capabilityId}" with ${winner.score}% confidence`);
+        }
+        else {
+            reasoning.push('No capability matched above the 50% confidence threshold');
+        }
+        if (rejected.length) {
+            reasoning.push(`Rejected: ${rejected.map(r => `${r.capabilityId} (${r.score}%)`).join(', ')}`);
+        }
+        reasoning.push(`Resolved via: ${resolvedVia}`);
+        if (matchResult.extractedParams && Object.keys(matchResult.extractedParams).length) {
+            const params = Object.entries(matchResult.extractedParams)
+                .filter(([, v]) => v !== null)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(', ');
+            if (params)
+                reasoning.push(`Would extract params: ${params}`);
+        }
+        // ── Build wouldExecute ───────────────────────────────────────────────────
+        const cap = matchResult.capability;
+        let action = null;
+        let blocked = null;
+        let privacy = null;
+        let resolverType = null;
+        if (cap) {
+            privacy = cap.privacy.level;
+            resolverType = cap.resolver.type;
+            // Check if privacy would block
+            if (cap.privacy.level === 'user_owned' && !this.auth?.isAuthenticated) {
+                blocked = `Requires authentication (privacy: user_owned)`;
+            }
+            else if (cap.privacy.level === 'admin' && this.auth?.role !== 'admin') {
+                blocked = `Requires admin role (current: ${this.auth?.role ?? 'none'})`;
+            }
+            if (!blocked) {
+                // Build action string
+                const params = matchResult.extractedParams;
+                if (cap.resolver.type === 'api') {
+                    const endpoint = cap.resolver.endpoints[0];
+                    let path = endpoint.path;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            path = path.replace(`{${k}}`, v);
+                    }
+                    const base = this.baseUrl ?? '';
+                    action = `${endpoint.method} ${base}${path}`;
+                }
+                else if (cap.resolver.type === 'nav') {
+                    let dest = cap.resolver.destination;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            dest = dest.replace(`{${k}}`, v);
+                    }
+                    action = `navigate → ${dest}`;
+                }
+                else if (cap.resolver.type === 'hybrid') {
+                    const hybrid = cap.resolver;
+                    const endpoint = hybrid.api.endpoints[0];
+                    let path = endpoint.path;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            path = path.replace(`{${k}}`, v);
+                    }
+                    let dest = hybrid.nav.destination;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            dest = dest.replace(`{${k}}`, v);
+                    }
+                    const base = this.baseUrl ?? '';
+                    action = `${endpoint.method} ${base}${path} + navigate → ${dest}`;
+                }
+            }
+        }
+        return {
+            query,
+            matched: {
+                capability: matchResult.capability,
+                confidence: matchResult.confidence,
+                intent: matchResult.intent,
+                reasoning,
+            },
+            candidates,
+            wouldExecute: { resolverType, action, privacy, blocked },
+            resolvedVia,
+            durationMs: Date.now() - start,
+        };
+    }
+    /**
+     * Checks all rate limiting and circuit breaker conditions.
+     * Returns null if LLM call is allowed, or a skip reason string if it should be skipped.
+     */
+    checkLLMAllowed() {
+        const now = Date.now();
+        // ── Circuit breaker ──────────────────────────────────────────────────────
+        if (this.llmCircuitOpenAt > 0) {
+            const elapsed = now - this.llmCircuitOpenAt;
+            if (elapsed < this.llmCircuitBreakerResetMs) {
+                const remainingSec = Math.ceil((this.llmCircuitBreakerResetMs - elapsed) / 1000);
+                return `circuit breaker open — ${remainingSec}s remaining`;
+            }
+            // Reset circuit breaker — try again
+            logger.info('LLM circuit breaker reset — trying again');
+            this.llmCircuitOpenAt = 0;
+            this.llmConsecutiveFails = 0;
+        }
+        // ── Cooldown between calls ───────────────────────────────────────────────
+        if (this.llmCooldownMs > 0 && this.llmLastCallAt > 0) {
+            const elapsed = now - this.llmLastCallAt;
+            if (elapsed < this.llmCooldownMs) {
+                const remainingMs = this.llmCooldownMs - elapsed;
+                return `cooldown active — ${remainingMs}ms remaining`;
+            }
+        }
+        // ── Per-minute rate limit ────────────────────────────────────────────────
+        const windowElapsed = now - this.llmWindowStart;
+        if (windowElapsed >= 60000) {
+            // Reset window
+            this.llmCallsThisMinute = 0;
+            this.llmWindowStart = now;
+        }
+        if (this.llmCallsThisMinute >= this.maxLLMCallsPerMinute) {
+            const windowResetIn = Math.ceil((60000 - windowElapsed) / 1000);
+            return `rate limit reached (${this.maxLLMCallsPerMinute}/min) — resets in ${windowResetIn}s`;
+        }
+        // Reserve the slot atomically before the call happens
+        this.llmCallsThisMinute++;
+        this.llmLastCallAt = Date.now();
+        return null;
+    }
+    /**
+     * Records a successful LLM call — updates rate limit counters.
+     */
+    recordLLMSuccess() {
+        this.llmConsecutiveFails = 0;
+    }
+    /**
+     * Records a failed LLM call — may open the circuit breaker.
+     */
+    recordLLMFailure() {
+        this.llmCallsThisMinute++;
+        this.llmConsecutiveFails++;
+        this.llmLastCallAt = Date.now();
+        if (this.llmConsecutiveFails >= this.llmCircuitBreakerThreshold) {
+            this.llmCircuitOpenAt = Date.now();
+            logger.warn(`LLM circuit breaker opened after ${this.llmConsecutiveFails} consecutive failures — pausing for ${this.llmCircuitBreakerResetMs / 1000}s`);
+        }
+    }
     // ── Private helpers ────────────────────────────────────────────────────────
     resolveOptions(overrides = {}) {
         return {

package/dist/esm/generator.d.ts

@@ -0,0 +1,7 @@
+import type { CapmanConfig, Manifest, ValidationResult } from './types';
+export declare function generate(config: CapmanConfig): Manifest;
+export declare function loadConfig(configPath?: string): CapmanConfig;
+export declare function writeManifest(manifest: Manifest, outputPath?: string): string;
+export declare function readManifest(manifestPath?: string): Manifest;
+export declare function validate(manifest: Manifest): ValidationResult;
+export declare function generateStarterConfig(): string;

package/dist/esm/generator.js

@@ -28,6 +28,10 @@ export function loadConfig(configPath) {
         if (fs.existsSync(resolved)) {
             let raw;
             // Catch syntax errors in config file
+            // Note: require() only works with CJS config files (.js, .json)
+            // ESM config files (.mjs or "type": "module") are not supported.
+            // Use a CJS config file or convert with: module.exports = { ... }
+            // Full ESM config support is planned for v0.5.
             try {
                 const mod = require(resolved);
                 raw = mod.default ?? mod;

package/dist/esm/index.d.ts

@@ -0,0 +1,47 @@
+export { setLogLevel } from './logger';
+export type { LogLevel } from './logger';
+export type { Capability, CapabilityParam, CapmanConfig, Manifest, MatchResult, ExecutionTrace, TraceStep, MatchCandidate, ResolveResult, ApiCallResult, ValidationResult, Resolver, ApiResolver, NavResolver, HybridResolver, PrivacyScope, ResolverType, HttpMethod, ExplainResult, ExplainCandidate, } from './types';
+export { generate, loadConfig, writeManifest, readManifest, validate, generateStarterConfig, } from './generator';
+export { match, matchWithLLM, } from './matcher';
+export type { LLMMatcherOptions } from './matcher';
+export { resolve } from './resolver';
+export type { ResolveOptions, AuthContext } from './resolver';
+export { CapmanEngine } from './engine';
+export type { EngineOptions, EngineResult } from './engine';
+export { MemoryCache, FileCache, ComboCache, buildCacheKey, normalizeQuery } from './cache';
+export type { CacheStore, CacheEntry } from './cache';
+export { FileLearningStore, MemoryLearningStore } from './learning';
+export type { LearningStore, LearningEntry, KeywordStats } from './learning';
+export { parseOpenAPI } from './parser';
+export type { ParseResult } from './parser';
+import type { Manifest, MatchResult, ResolveResult } from './types';
+import type { LLMMatcherOptions } from './matcher';
+import type { ResolveOptions } from './resolver';
+export type MatchMode = 'cheap' | 'balanced' | 'accurate';
+export interface AskOptions extends ResolveOptions {
+    llm?: LLMMatcherOptions['llm'];
+    /**
+     * Controls how intent matching is performed.
+     * - 'cheap'    — keyword only, no LLM calls
+     * - 'balanced' — keyword first, LLM fallback if confidence < 50% (default)
+     * - 'accurate' — LLM first, keyword fallback
+     * @default 'balanced'
+     */
+    mode?: MatchMode;
+}
+export interface AskResult {
+    match: MatchResult;
+    resolution: ResolveResult;
+}
+/**
+ * One-shot convenience: match + resolve in a single call.
+ * Delegates to CapmanEngine internally.
+ *
+ * @deprecated For full features including trace and caching, use CapmanEngine directly.
+ *
+ * @example
+ * const result = await ask("show me the dashboard", manifest, {
+ *   baseUrl: 'https://api.your-app.com',
+ * })
+ */
+export declare function ask(query: string, manifest: Manifest, options?: AskOptions): Promise<AskResult>;

package/dist/esm/learning.d.ts

@@ -0,0 +1,55 @@
+export interface LearningEntry {
+    query: string;
+    capabilityId: string | null;
+    confidence: number;
+    intent: string;
+    extractedParams: Record<string, string | null>;
+    resolvedVia: 'keyword' | 'llm' | 'cache';
+    timestamp: string;
+}
+export interface KeywordStats {
+    /** keyword → Map of capabilityId → hit count */
+    index: Record<string, Record<string, number>>;
+    /** Total queries processed */
+    totalQueries: number;
+    /** Queries that went to LLM */
+    llmQueries: number;
+    /** Queries served from cache */
+    cacheHits: number;
+    /** Out of scope queries */
+    outOfScope: number;
+}
+export interface LearningStore {
+    record(entry: LearningEntry): Promise<void>;
+    getStats(): Promise<KeywordStats>;
+    getTopCapabilities(limit?: number): Promise<Array<{
+        id: string;
+        hits: number;
+    }>>;
+    clear(): Promise<void>;
+}
+export declare class FileLearningStore implements LearningStore {
+    private filePath;
+    private entries;
+    private loaded;
+    constructor(filePath?: string);
+    private load;
+    private save;
+    record(entry: LearningEntry): Promise<void>;
+    getStats(): Promise<KeywordStats>;
+    getTopCapabilities(limit?: number): Promise<Array<{
+        id: string;
+        hits: number;
+    }>>;
+    clear(): Promise<void>;
+}
+export declare class MemoryLearningStore implements LearningStore {
+    private entries;
+    record(entry: LearningEntry): Promise<void>;
+    getStats(): Promise<KeywordStats>;
+    getTopCapabilities(limit?: number): Promise<Array<{
+        id: string;
+        hits: number;
+    }>>;
+    clear(): Promise<void>;
+}

package/dist/esm/logger.d.ts

@@ -0,0 +1,21 @@
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+export declare class Logger {
+    private level;
+    constructor(level?: LogLevel);
+    setLevel(level: LogLevel): void;
+    error(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+}
+export declare const logger: Logger;
+/**
+ * Set the global log level for capman.
+ *
+ * @example
+ * import { setLogLevel } from 'capman'
+ * setLogLevel('debug') // see everything
+ * setLogLevel('info')  // see key steps
+ * setLogLevel('silent') // no output (default)
+ */
+export declare function setLogLevel(level: LogLevel): void;

package/dist/esm/matcher.d.ts

@@ -0,0 +1,6 @@
+import type { Manifest, MatchResult } from './types';
+export declare function match(query: string, manifest: Manifest): MatchResult;
+export interface LLMMatcherOptions {
+    llm: (prompt: string) => Promise<string>;
+}
+export declare function matchWithLLM(query: string, manifest: Manifest, options: LLMMatcherOptions): Promise<MatchResult>;

package/dist/esm/matcher.js

@@ -203,29 +203,23 @@ export async function matchWithLLM(query, manifest, options) {
   "reasoning": "<one sentence>",
   "extracted_params": { "<param_name>": "<value or null>" }
   }`;
-    try {
-        const raw = await options.llm(prompt);
-        const clean = raw.replace(/```json|```/g, '').trim();
-        const parsed = JSON.parse(clean);
-        const isOOS = parsed.matched_capability === 'OUT_OF_SCOPE';
-        const capability = isOOS
-            ? null
-            : manifest.capabilities.find(c => c.id === parsed.matched_capability) ?? null;
-        return {
-            capability,
-            confidence: parsed.confidence,
-            intent: isOOS ? 'out_of_scope' : parsed.intent,
-            extractedParams: parsed.extracted_params ?? {},
-            reasoning: parsed.reasoning,
-            candidates: capability ? [{
-                    capabilityId: capability.id,
-                    score: parsed.confidence,
-                    matched: true,
-                }] : [],
-        };
-    }
-    catch (err) {
-        logger.warn(`LLM match failed, falling back to keyword matcher: ${err}`);
-        return match(query, manifest);
-    }
+    const raw = await options.llm(prompt);
+    const clean = raw.replace(/```json|```/g, '').trim();
+    const parsed = JSON.parse(clean);
+    const isOOS = parsed.matched_capability === 'OUT_OF_SCOPE';
+    const capability = isOOS
+        ? null
+        : manifest.capabilities.find(c => c.id === parsed.matched_capability) ?? null;
+    return {
+        capability,
+        confidence: parsed.confidence,
+        intent: isOOS ? 'out_of_scope' : parsed.intent,
+        extractedParams: parsed.extracted_params ?? {},
+        reasoning: parsed.reasoning,
+        candidates: capability ? [{
+                capabilityId: capability.id,
+                score: parsed.confidence,
+                matched: true,
+            }] : [],
+    };
 }

package/dist/esm/parser.d.ts

@@ -0,0 +1,10 @@
+import type { CapmanConfig } from './types';
+export interface ParseResult {
+    config: CapmanConfig;
+    stats: {
+        total: number;
+        skipped: number;
+        warnings: string[];
+    };
+}
+export declare function parseOpenAPI(specPathOrUrl: string): Promise<ParseResult>;

package/dist/esm/resolver.d.ts

@@ -0,0 +1,21 @@
+import type { MatchResult, ResolveResult } from './types';
+export interface AuthContext {
+    /** Whether the current request is authenticated */
+    isAuthenticated: boolean;
+    /** Current user's role */
+    role?: 'user' | 'admin';
+    /** Current user's ID — injected into session params */
+    userId?: string;
+}
+export interface ResolveOptions {
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    dryRun?: boolean;
+    headers?: Record<string, string>;
+    auth?: AuthContext;
+    /** Number of retries on failure (default: 0) */
+    retries?: number;
+    /** Timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+}
+export declare function resolve(matchResult: MatchResult, params?: Record<string, unknown>, options?: ResolveOptions): Promise<ResolveResult>;