@stackbilt/llm-providers 1.2.0 → 1.5.0

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.2.0",
+  "version": "1.5.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",