@stackbilt/llm-providers 1.1.0 → 1.3.0

package/dist/utils/retry.d.ts

@@ -3,9 +3,11 @@
  * Exponential backoff retry logic for LLM provider requests
  */
 import type { RetryConfig } from '../types';
+import type { Logger } from './logger';
 export declare class RetryManager {
     private config;
-    constructor(config?: Partial<RetryConfig>);
+    private logger;
+    constructor(config?: Partial<RetryConfig>, logger?: Logger);
     /**
      * Execute a function with retry logic
      */
@@ -38,7 +40,7 @@ export declare const defaultRetryManager: RetryManager;
 /**
  * Retry decorator for async functions
  */
-export declare function withRetry<T extends any[], R>(retryConfig?: Partial<RetryConfig>): (target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: T) => Promise<R>>) => TypedPropertyDescriptor<(...args: T) => Promise<R>>;
+export declare function withRetry<T extends unknown[], R>(retryConfig?: Partial<RetryConfig>): (_target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: T) => Promise<R>>) => TypedPropertyDescriptor<(...args: T) => Promise<R>>;
 /**
  * Simple retry function for one-off operations
  */

package/dist/utils/retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAc;gBAEhB,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM;IAgB7C;;OAEG;IACG,OAAO,CAAC,CAAC,EACb,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,MAAoB,GAC5B,OAAO,CAAC,CAAC,CAAC;IA8Bb;;OAEG;IACH,OAAO,CAAC,WAAW;IAoBnB;;OAEG;IACH,OAAO,CAAC,cAAc;IAgBtB;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAIhD;;OAEG;IACH,SAAS,IAAI,WAAW;CAGzB;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,cAAqB,CAAC;AAEtD;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,CAAC,EAC1C,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,IAGhC,QAAQ,GAAG,EACX,aAAa,MAAM,EACnB,YAAY,uBAAuB,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,uCAAjB,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAcjE;AAED;;GAEG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAGZ"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAIvC,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAiB9D;;OAEG;IACG,OAAO,CAAC,CAAC,EACb,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,MAAoB,GAC5B,OAAO,CAAC,CAAC,CAAC;IA8Bb;;OAEG;IACH,OAAO,CAAC,WAAW;IAqBnB;;OAEG;IACH,OAAO,CAAC,cAAc;IAgBtB;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAIhD;;OAEG;IACH,SAAS,IAAI,WAAW;CAGzB;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,cAAqB,CAAC;AAEtD;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAC9C,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,IAGhC,SAAS,MAAM,EACf,aAAa,MAAM,EACnB,YAAY,uBAAuB,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,uCAAjB,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAcjE;AAED;;GAEG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAGZ"}

package/dist/utils/retry.js

@@ -2,10 +2,12 @@
  * Retry Utility
  * Exponential backoff retry logic for LLM provider requests
  */
-import { LLMErrorFactory } from '../errors';
+import { noopLogger } from './logger';
+import { LLMErrorFactory, LLMProviderError } from '../errors';
 export class RetryManager {
     config;
-    constructor(config = {}) {
+    logger;
+    constructor(config = {}, logger) {
         this.config = {
             maxRetries: config.maxRetries ?? 3,
             initialDelay: config.initialDelay ?? 1000,
@@ -19,6 +21,7 @@ export class RetryManager {
                 'CIRCUIT_BREAKER_OPEN'
             ]
         };
+        this.logger = logger ?? noopLogger;
     }
     /**
      * Execute a function with retry logic
@@ -39,7 +42,7 @@ export class RetryManager {
                 }
                 // Calculate delay for next attempt
                 const delay = this.calculateDelay(attempt, error);
-                console.warn(`[RetryManager] ${context} failed (attempt ${attempt}/${this.config.maxRetries + 1}): ${lastError.message}. Retrying in ${delay}ms...`);
+                this.logger.warn(`[RetryManager] ${context} failed (attempt ${attempt}/${this.config.maxRetries + 1}): ${lastError.message}. Retrying in ${delay}ms...`);
                 await this.delay(delay);
             }
         }
@@ -58,9 +61,10 @@ export class RetryManager {
             return false;
         }
         // Check if error code is in retryable list
-        const errorCode = error.code;
-        if (errorCode && !this.config.retryableErrors.includes(errorCode)) {
-            return false;
+        if (error instanceof LLMProviderError) {
+            if (!this.config.retryableErrors.includes(error.code)) {
+                return false;
+            }
         }
         return true;
     }
@@ -106,11 +110,11 @@ export const defaultRetryManager = new RetryManager();
  * Retry decorator for async functions
  */
 export function withRetry(retryConfig) {
-    return function (target, propertyKey, descriptor) {
+    return function (_target, propertyKey, descriptor) {
         const originalMethod = descriptor.value;
         const retryManager = new RetryManager(retryConfig);
         descriptor.value = async function (...args) {
-            return retryManager.execute(() => originalMethod.apply(this, args), `${target.constructor.name}.${propertyKey}`);
+            return retryManager.execute(() => originalMethod.apply(this, args), `${this.constructor.name}.${propertyKey}`);
         };
         return descriptor;
     };

package/dist/utils/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,OAAO,YAAY;IACf,MAAM,CAAc;IAE5B,YAAY,SAA+B,EAAE;QAC3C,IAAI,CAAC,MAAM,GAAG;YACZ,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,CAAC;YAClC,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;YACzC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,KAAK;YAClC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,IAAI,CAAC;YAChD,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI;gBACzC,eAAe;gBACf,SAAS;gBACT,cAAc;gBACd,YAAY;gBACZ,sBAAsB;aACvB;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CACX,EAAoB,EACpB,UAAkB,WAAW;QAE7B,IAAI,SAAgB,CAAC;QACrB,IAAI,OAAO,GAAG,CAAC,CAAC;QAEhB,OAAO,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YACzC,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,SAAS,GAAG,KAAc,CAAC;gBAC3B,OAAO,EAAE,CAAC;gBAEV,sCAAsC;gBACtC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,KAAc,EAAE,OAAO,CAAC,EAAE,CAAC;oBAC/C,MAAM,KAAK,CAAC;gBACd,CAAC;gBAED,mCAAmC;gBACnC,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,KAAc,CAAC,CAAC;gBAE3D,OAAO,CAAC,IAAI,CACV,kBAAkB,OAAO,oBAAoB,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,CAAC,MAAM,SAAS,CAAC,OAAO,iBAAiB,KAAK,OAAO,CACvI,CAAC;gBAEF,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,MAAM,SAAU,CAAC;IACnB,CAAC;IAED;;OAEG;IACK,WAAW,CAAC,KAAY,EAAE,OAAe;QAC/C,6CAA6C;QAC7C,IAAI,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YACrC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,8BAA8B;QAC9B,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YACxC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,2CAA2C;QAC3C,MAAM,SAAS,GAAI,KAAa,CAAC,IAAI,CAAC;QACtC,IAAI,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAClE,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,OAAe,EAAE,KAAY;QAClD,wCAAwC;QACxC,MAAM,UAAU,GAAG,eAAe,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACxD,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,GAAG,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9D,CAAC;QAED,+BAA+B;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;QAE9F,wCAAwC;QACxC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,KAAK,CAAC;QAE3C,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,EAAU;QACtB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAA4B;QACvC,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,YAAY,EAAE,CAAC;AAEtD;;GAEG;AACH,MAAM,UAAU,SAAS,CACvB,WAAkC;IAElC,OAAO,UACL,MAAW,EACX,WAAmB,EACnB,UAA+D;QAE/D,MAAM,cAAc,GAAG,UAAU,CAAC,KAAM,CAAC;QACzC,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC,WAAW,CAAC,CAAC;QAEnD,UAAU,CAAC,KAAK,GAAG,KAAK,WAAW,GAAG,IAAO;YAC3C,OAAO,YAAY,CAAC,OAAO,CACzB,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EACtC,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,IAAI,WAAW,EAAE,CAC5C,CAAC;QACJ,CAAC,CAAC;QAEF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,EAAoB,EACpB,MAA6B;IAE7B,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"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"}

package/dist/utils/schema-validator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Response Envelope Schema Validator
+ *
+ * Zero-dependency runtime validator for provider response shapes. Used at the
+ * provider boundary to detect when an upstream API silently changes its
+ * response envelope — the classic "field renamed at 2am, parser throws at
+ * 3am" failure mode.
+ *
+ * Philosophy: validate the *minimum* fields each provider's parser actually
+ * reads. Don't re-type the full upstream schema — that creates brittle
+ * over-specification that churns every time the provider adds an optional
+ * field. Only the fields we touch matter.
+ *
+ * Usage:
+ *   validateSchema('anthropic', data, [
+ *     { path: 'content', type: 'array' },
+ *     { path: 'usage.input_tokens', type: 'number' },
+ *     { path: 'usage.output_tokens', type: 'number' },
+ *     { path: 'model', type: 'string' },
+ *   ]);
+ *
+ * On first failure, throws SchemaDriftError. The caller (typically the
+ * factory) catches it, fires the onSchemaDrift hook, and falls over to
+ * another provider.
+ */
+export type SchemaFieldType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'string-or-null';
+export interface SchemaField {
+    /**
+     * Dot-separated path into the response object. Array indices not supported
+     * in the path itself — use `items` to validate array element shapes.
+     */
+    path: string;
+    type: SchemaFieldType;
+    /**
+     * If true, missing paths are allowed and skipped. Useful for fields that
+     * are genuinely optional (e.g. stop_sequence on Anthropic).
+     */
+    optional?: boolean;
+    /**
+     * For type: 'array' — validate each element against a nested schema.
+     *
+     * - `shape`: a flat SchemaField[] applied to every element (all elements
+     *   the same shape).
+     * - `variants` + `discriminator`: discriminated union. Each element is
+     *   routed by the value of `discriminator` (a field name on the element)
+     *   to the matching variant schema. **Unknown discriminator values are
+     *   allowed and skipped** — we want forward-compat for additive API
+     *   changes (e.g. Anthropic adds a new content block type). Only *missing*
+     *   discriminators or *wrong-typed* known variants trigger drift.
+     */
+    items?: {
+        shape?: SchemaField[];
+        discriminator?: string;
+        variants?: Record<string, SchemaField[]>;
+    };
+}
+/**
+ * Validate a response envelope against a minimal field schema.
+ * Throws SchemaDriftError on the first mismatch, with provider + path +
+ * expected/actual types surfaced for observability.
+ *
+ * We fail fast rather than collecting all errors: the first drift is enough
+ * to trigger fallback, and walking the whole schema when we're already
+ * broken wastes budget.
+ */
+export declare function validateSchema(provider: string, data: unknown, fields: SchemaField[]): void;
+//# sourceMappingURL=schema-validator.d.ts.map

package/dist/utils/schema-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-validator.d.ts","sourceRoot":"","sources":["../../src/utils/schema-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,OAAO,GACP,QAAQ,GACR,gBAAgB,CAAC;AAErB,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,eAAe,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE;QACN,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;KAC1C,CAAC;CACH;AAoID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,WAAW,EAAE,GACpB,IAAI,CAEN"}

package/dist/utils/schema-validator.js

@@ -0,0 +1,140 @@
+/**
+ * Response Envelope Schema Validator
+ *
+ * Zero-dependency runtime validator for provider response shapes. Used at the
+ * provider boundary to detect when an upstream API silently changes its
+ * response envelope — the classic "field renamed at 2am, parser throws at
+ * 3am" failure mode.
+ *
+ * Philosophy: validate the *minimum* fields each provider's parser actually
+ * reads. Don't re-type the full upstream schema — that creates brittle
+ * over-specification that churns every time the provider adds an optional
+ * field. Only the fields we touch matter.
+ *
+ * Usage:
+ *   validateSchema('anthropic', data, [
+ *     { path: 'content', type: 'array' },
+ *     { path: 'usage.input_tokens', type: 'number' },
+ *     { path: 'usage.output_tokens', type: 'number' },
+ *     { path: 'model', type: 'string' },
+ *   ]);
+ *
+ * On first failure, throws SchemaDriftError. The caller (typically the
+ * factory) catches it, fires the onSchemaDrift hook, and falls over to
+ * another provider.
+ */
+import { SchemaDriftError } from '../errors';
+/**
+ * Walk a dot-path into an object. Returns undefined if any segment is missing.
+ * Does NOT distinguish "path missing" from "path present but undefined" —
+ * callers should treat both as missing.
+ */
+function getPath(obj, path) {
+    const segments = path.split('.');
+    let current = obj;
+    for (const segment of segments) {
+        if (current == null || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Describe the actual runtime type of a value for error messages.
+ * Separates null / undefined / array from generic object.
+ */
+function describeType(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function matchesType(value, type) {
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'array':
+            return Array.isArray(value);
+        case 'object':
+            return value !== null && typeof value === 'object' && !Array.isArray(value);
+        case 'string-or-null':
+            return value === null || typeof value === 'string';
+    }
+}
+/**
+ * Validate a single object against a flat SchemaField list, prefixing any
+ * error path with `pathPrefix` so nested element errors read like
+ * `content[2].id` instead of bare `id`.
+ */
+function validateFields(provider, data, fields, pathPrefix) {
+    if (data == null || typeof data !== 'object') {
+        throw new SchemaDriftError(provider, pathPrefix || '$root', 'object', describeType(data));
+    }
+    for (const field of fields) {
+        const fullPath = pathPrefix ? `${pathPrefix}.${field.path}` : field.path;
+        const value = getPath(data, field.path);
+        if (value === undefined) {
+            if (field.optional)
+                continue;
+            throw new SchemaDriftError(provider, fullPath, field.type, 'undefined');
+        }
+        if (!matchesType(value, field.type)) {
+            throw new SchemaDriftError(provider, fullPath, field.type, describeType(value));
+        }
+        if (field.type === 'array' && field.items) {
+            validateArrayItems(provider, value, field.items, fullPath);
+        }
+    }
+}
+/**
+ * Validate the elements of an array against either a flat `shape` or a
+ * discriminated `variants` map. Unknown discriminator values are
+ * forward-compatible and skipped.
+ */
+function validateArrayItems(provider, items, spec, arrayPath) {
+    for (let i = 0; i < items.length; i++) {
+        const element = items[i];
+        const elementPath = `${arrayPath}[${i}]`;
+        if (element == null || typeof element !== 'object') {
+            throw new SchemaDriftError(provider, elementPath, 'object', describeType(element));
+        }
+        if (spec.discriminator && spec.variants) {
+            const disc = element[spec.discriminator];
+            if (typeof disc !== 'string') {
+                throw new SchemaDriftError(provider, `${elementPath}.${spec.discriminator}`, 'string', describeType(disc));
+            }
+            const variantFields = spec.variants[disc];
+            // Unknown discriminator value — forward-compat. Skip validation
+            // rather than reject, so adding a new block type upstream doesn't
+            // break every consumer on the next deploy.
+            if (!variantFields)
+                continue;
+            validateFields(provider, element, variantFields, elementPath);
+            continue;
+        }
+        if (spec.shape) {
+            validateFields(provider, element, spec.shape, elementPath);
+        }
+    }
+}
+/**
+ * Validate a response envelope against a minimal field schema.
+ * Throws SchemaDriftError on the first mismatch, with provider + path +
+ * expected/actual types surfaced for observability.
+ *
+ * We fail fast rather than collecting all errors: the first drift is enough
+ * to trigger fallback, and walking the whole schema when we're already
+ * broken wastes budget.
+ */
+export function validateSchema(provider, data, fields) {
+    validateFields(provider, data, fields, '');
+}
+//# sourceMappingURL=schema-validator.js.map

package/dist/utils/schema-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-validator.js","sourceRoot":"","sources":["../../src/utils/schema-validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbilt/llm-providers",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Multi-LLM failover with circuit breakers, cost tracking, and intelligent retry. Cloudflare Workers native.",
   "author": "Stackbilt <admin@stackbilt.dev>",
   "license": "Apache-2.0",