@salimassili/ai-costguard 1.2.0 → 2.0.1

package/dist/core/GuardCore.d.ts

@@ -1,22 +1,102 @@
+import type { GuardConfig, GuardErrorCode, GuardEventHandler, GuardEventName, GuardState, RequestContext } from './types.js';
 /**
- * GuardCore.ts - FREE CORE (VIRAL ENGINE)
- *
- * Maximum simplicity. Maximum virality. Zero complexity.
- * Instant safety layer every AI developer installs by default.
+ * Result returned by the guard evaluator.
  */
-import { GuardConfig, RequestContext, GuardState } from './types.js';
+export interface GuardCheckResult {
+    /** Final guard decision. */
+    decision: 'allow' | 'block';
+    /** Request context that was evaluated. */
+    context: RequestContext;
+    /** Human-readable block reason, present when decision is "block". */
+    reason?: string;
+    /** Highest prompt similarity seen during loop detection. */
+    similarity?: number;
+}
 /**
- * Guard your AI client from wasting money
- * FREE CORE: Local protection + viral logs + real-time risk warnings
+ * Extra structured metadata attached to GuardError.
  */
-export declare function guard(client: any, config: GuardConfig, sharedState?: GuardState): any;
+export interface GuardErrorMetadata {
+    /** Stable machine-readable block reason. */
+    code: GuardErrorCode;
+    /** Human-readable block reason. */
+    reason: string;
+    /** Evaluated request context. */
+    context: RequestContext;
+    /** Current scope key for budget/history isolation. */
+    scopeKey: string;
+    /** Highest prompt similarity involved in a loop/retry decision. */
+    similarity?: number;
+}
 /**
- * Express middleware (FREE CORE - LOCAL ONLY)
+ * Error thrown when a guarded request is blocked before reaching the AI provider.
  */
-export declare function middleware(config: GuardConfig): (req: any, res: any, next: any) => void;
 export declare class GuardError extends Error {
-    context: RequestContext;
-    constructor(message: string, context: RequestContext);
+    /** Stable machine-readable block reason. */
+    readonly code: GuardErrorCode;
+    /** Request context that caused the block. */
+    readonly context: RequestContext;
+    /** Structured error metadata for API responses and logging. */
+    readonly metadata: GuardErrorMetadata;
+    /**
+     * Creates a GuardError for a blocked request.
+     */
+    constructor(message: string, context?: RequestContext, code?: GuardErrorCode, metadata?: Partial<GuardErrorMetadata>);
+    toJSON(): GuardErrorMetadata;
 }
-export { getPricing } from '../pricing/index.js';
+/**
+ * Shared synchronous evaluator used by the free proxy guard and middleware.
+ */
+export declare class GuardCore {
+    private readonly config;
+    private readonly state;
+    private readonly emitter;
+    /**
+     * Creates a process-local guard evaluator.
+     */
+    constructor(config?: GuardConfig, sharedState?: GuardState);
+    /**
+     * Subscribes to guard events.
+     */
+    on(eventName: GuardEventName, handler: GuardEventHandler): () => void;
+    /**
+     * Removes a guard event handler.
+     */
+    off(eventName: GuardEventName, handler: GuardEventHandler): void;
+    /**
+     * Returns the mutable process-local state used by this evaluator.
+     */
+    getState(): GuardState;
+    /**
+     * Returns true when a proxied method path should be evaluated.
+     */
+    shouldGuardMethod(methodPath: string): boolean;
+    /**
+     * Extracts a normalized request context from OpenAI-like method arguments.
+     */
+    extractContext(args: readonly unknown[], method?: string): RequestContext;
+    /**
+     * Checks a request context, records allowed calls, emits events, and throws GuardError on block.
+     */
+    check(context: RequestContext): GuardCheckResult;
+    /**
+     * Reconciles actual provider usage from OpenAI/Anthropic-like response objects when available.
+     */
+    recordActualUsage(context: RequestContext, response: unknown): void;
+    private checkBudget;
+    private checkMaxSteps;
+    private findLoopSimilarity;
+    private checkRetryStorm;
+    private recordAttempt;
+    private recordAllowed;
+    private pushHistory;
+    private block;
+    private emit;
+    private getScopeState;
+    private pruneScope;
+    private extractScope;
+}
+/**
+ * Creates an empty process-local guard state.
+ */
+export declare function createGuardState(): GuardState;
 //# sourceMappingURL=GuardCore.d.ts.map

package/dist/core/GuardCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GuardCore.d.ts","sourceRoot":"","sources":["../../src/core/GuardCore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAErE;;;GAGG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,UAAU,OAgF/E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,IAGpC,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG,UAiCtC;AAiED,qBAAa,UAAW,SAAQ,KAAK;IACnC,OAAO,EAAE,cAAc,CAAC;gBACZ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;CAKrD;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"GuardCore.d.ts","sourceRoot":"","sources":["../../src/core/GuardCore.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,cAAc,EAGd,UAAU,EACV,cAAc,EACf,MAAM,YAAY,CAAC;AAmBpB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC;IAC5B,0CAA0C;IAC1C,OAAO,EAAE,cAAc,CAAC;IACxB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,IAAI,EAAE,cAAc,CAAC;IACrB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,OAAO,EAAE,cAAc,CAAC;IACxB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IAEtC;;OAEG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,cAAqC,EAC9C,IAAI,GAAE,cAAkC,EACxC,QAAQ,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAe5C,MAAM,IAAI,kBAAkB;CAG7B;AAED;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAyBnB;IACJ,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IAEnD;;OAEG;gBACS,MAAM,GAAE,WAAgB,EAAE,WAAW,GAAE,UAA+B;IA8BlF;;OAEG;IACH,EAAE,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAIrE;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAIhE;;OAEG;IACH,QAAQ,IAAI,UAAU;IAItB;;OAEG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI9C;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc;IA+BzE;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,gBAAgB;IAqChD;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAoBnE,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,eAAe;IAoBvB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,KAAK;IAkBb,OAAO,CAAC,IAAI;IAaZ,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,YAAY;CAOrB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAK7C"}