@retrivora-ai/rag-engine 2.3.0 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retrivora-ai/rag-engine",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Retrivora AI is a plug-and-play AI engine for RAG chat experiences — generic vector DB + LLM provider, embeddable or standalone.",
   "author": "Abhinav Alkuchi",
   "license": "UNLICENSED",

package/src/components/ChatWidget.tsx

@@ -1,13 +1,21 @@
-import React, { useState } from 'react';
-import { MessageSquare, X, AlertTriangle } from 'lucide-react';
+import React, { useState, useEffect, useCallback } from 'react';
+import { MessageSquare, X, AlertTriangle, Lock } from 'lucide-react';
 import { ChatWindow } from './ChatWindow';
 import { useConfig } from './ConfigProvider';
 import { ChatWidgetProps } from '../types';
 import { SDK_VERSION } from '../version';
-import { LicenseValidator } from '../core/LicenseValidator';
+import { LicenseValidator, LicenseValidationResponse } from '../core/LicenseValidator';
 
+/**
+ * Default widget dimensions (width x height) in pixels.
+ * Applied when the widget first opens and when the user resets sizing.
+ */
 const DEFAULT_DIMENSIONS = { width: 380, height: 600 };
 
+/**
+ * Keyframes and CSS custom properties for the Gemini-style
+ * shape-shifting floating button background.
+ */
 const GEMINI_STYLES = `
   @keyframes shapeshift {
     0% { clip-path: var(--circle); rotate: 0turn; }
@@ -33,11 +41,6 @@ const GEMINI_STYLES = `
     100% { translate: -75% -75%; }
   }
 
-  @keyframes gradientMove {
-    0% { translate: 0 0; }
-    100% { translate: -75% -75%; }
-  }
-
   :root {
     --flower: shape(evenodd from 17.9665% 82.0335%, curve by -12.349% -32.0335% with -13.239% -5.129% / -18.021% -15.402%, curve by -0.0275% -22.203% with -3.1825% -9.331% / -3.074% -16.6605%, curve by 12.3765% -9.8305% with 2.3835% -4.3365% / 6.565% -7.579%, curve by 32.0335% -12.349% with 5.129% -13.239% / 15.402% -18.021%, curve by 20.4535% -0.8665% with 8.3805% -2.858% / 15.1465% -3.062%, curve by 11.58% 13.2155% with 5.225% 2.161% / 9.0355% 6.6475%, curve by 12.349% 32.0335% with 13.239% 5.129% / 18.021% 15.402%, curve by 0.5715% 21.1275% with 2.9805% 8.7395% / 3.0745% 15.723%, curve by -12.9205% 10.906% with -2.26% 4.88% / -6.638% 8.472%, curve by -32.0335% 12.349% with -5.129% 13.239% / -15.402% 18.021%, curve by -21.1215% 0.5745% with -8.736% 2.9795% / -15.718% 3.0745%, curve by -10.912% -12.9235% with -4.883% -2.2595% / -8.477% -6.6385%, close);
     --hexagon: shape(evenodd from 6.47% 67.001%, curve by 0% -34.002% with -1.1735% -7.7% / -1.1735% -26.302%, curve by 7.0415% -12.1965% with 0.7075% -4.641% / 3.3765% -9.2635%, curve by 29.447% -17.001% with 6.0815% -4.8665% / 22.192% -14.1675%, curve by 14.083% 0% with 4.3725% -1.708% / 9.7105% -1.708%, curve by 29.447% 17.001% with 7.255% 2.8335% / 23.3655% 12.1345%, curve by 7.0415% 12.1965% with 3.665% 2.933% / 6.334% 7.5555%, curve by 0% 34.002% with 1.1735% 7.7% / 1.1735% 26.302%, curve by -7.0415% 12.1965% with -0.7075% 4.641% / -3.3765% 9.2635%, curve by -29.447% 17.001% with -6.0815% 4.8665% / -22.192% 14.1675%, curve by -14.083% 0% with -4.3725% 1.708% / -9.7105% 1.708%, curve by -29.447% -17.001% with -7.255% -2.8335% / -23.3655% -12.1345%, curve by -7.0415% -12.1965% with -3.665% -2.933% / -6.334% -7.5555%, close);
@@ -46,6 +49,24 @@ const GEMINI_STYLES = `
   }
 `;
 
+/**
+ * ChatWidget — Floating Action Button (FAB) that toggles the chat window.
+ *
+ * Responsibilities:
+ *   - Validates the Retrivora license key BEFORE allowing the chat to open
+ *   - Proactively validates on mount to visually lock the widget when no
+ *     valid license is present (TERMINATED / SUSPENDED / missing)
+ *   - Manages window resize, maximize, and visual positioning
+ *   - Shows an error toast when license validation fails on user attempt
+ *
+ * License key resolution order (highest to lowest priority):
+ *   1. Explicit `licenseKey` prop
+ *   2. `x-license-key` header (from `headers` prop)
+ *   3. `Authorization: Bearer <key>` header (from `headers` prop)
+ *   4. Environment variables `NEXT_PUBLIC_RETRIVORA_LICENSE_KEY` / `RETRIVORA_LICENSE_KEY`
+ *
+ * @param props  - Widget position, callbacks, API overrides, and license overrides
+ */
 export function ChatWidget({ position = 'bottom-right', onAddToCart, apiUrl, retrivoraApiBase, licenseKey: licenseKeyProp, headers }: ChatWidgetProps) {
   const { ui, projectId } = useConfig();
   const [isOpen, setIsOpen] = useState(false);
@@ -56,6 +77,7 @@ export function ChatWidget({ position = 'bottom-right', onAddToCart, apiUrl, ret
   const [prevDimensions, setPrevDimensions] = useState(DEFAULT_DIMENSIONS);
   const [widgetError, setWidgetError] = useState<string | null>(null);
   const [isValidating, setIsValidating] = useState(false);
+  const [hasMountValidationFailed, setHasMountValidationFailed] = useState(false);
 
   if (ui.showWidget === false) return null;
 
@@ -69,26 +91,75 @@ export function ChatWidget({ position = 'bottom-right', onAddToCart, apiUrl, ret
       ? 'bottom-20 left-6'
       : 'bottom-20 right-6';
 
-  const handleOpen = async () => {
+  /**
+   * Resolves the active license key from all possible sources
+   * (explicit prop → headers → environment variables).
+   */
+  const resolveLicenseKey = useCallback((): string => {
+    const getHeader = (name: string) => {
+      if (!headers) return undefined;
+      const target = name.toLowerCase();
+      for (const [k, v] of Object.entries(headers)) {
+        if (k.toLowerCase() === target) return v;
+      }
+      return undefined;
+    };
+
+    return (
+      licenseKeyProp ||
+      getHeader('x-license-key') ||
+      getHeader('authorization')?.replace(/^Bearer\s+/i, '') ||
+      (typeof process !== 'undefined'
+        ? (process.env.NEXT_PUBLIC_RETRIVORA_LICENSE_KEY || process.env.RETRIVORA_LICENSE_KEY)
+        : '') ||
+      ''
+    );
+  }, [licenseKeyProp, headers]);
+
+  /**
+   * Proactively validate the license on mount.
+   * If validation fails, mark the widget locked so the FAB button appears
+   * disabled and we don't waste a network call on every subsequent click.
+   */
+  useEffect(() => {
+    let isMounted = true;
+    async function validateOnMount() {
+      try {
+        const resolvedLicenseKey = resolveLicenseKey();
+        await LicenseValidator.getInstance().validate({
+          licenseKey: resolvedLicenseKey,
+          projectId,
+          retrivoraApiBase,
+          headers,
+        });
+        if (isMounted) {
+          setHasMountValidationFailed(false);
+          setWidgetError(null);
+        }
+      } catch (err: any) {
+        if (isMounted) {
+          setHasMountValidationFailed(true);
+          setWidgetError(err?.message || 'Access denied.');
+        }
+      }
+    }
+    validateOnMount();
+    return () => { isMounted = false; };
+  }, [resolveLicenseKey, projectId, retrivoraApiBase, headers]);
+
+  /**
+   * Validates the license key and opens the chat window.
+   * If the license was already marked invalid on mount we immediately
+   * re-display the error toast without re-validating.
+   */
+  const handleOpen = useCallback(async () => {
+    if (hasMountValidationFailed && widgetError) {
+      setWidgetError(widgetError);
+      return;
+    }
     setIsValidating(true);
     try {
-      const getHeader = (name: string) => {
-        if (!headers) return undefined;
-        const target = name.toLowerCase();
-        for (const [k, v] of Object.entries(headers)) {
-          if (k.toLowerCase() === target) return v;
-        }
-        return undefined;
-      };
-
-      const resolvedLicenseKey =
-        licenseKeyProp ||
-        getHeader('x-license-key') ||
-        getHeader('authorization')?.replace(/^Bearer\s+/i, '') ||
-        (typeof process !== 'undefined'
-          ? (process.env.NEXT_PUBLIC_RETRIVORA_LICENSE_KEY || process.env.RETRIVORA_LICENSE_KEY)
-          : '') ||
-        '';
+      const resolvedLicenseKey = resolveLicenseKey();
 
       await LicenseValidator.getInstance().validate({
         licenseKey: resolvedLicenseKey,
@@ -98,15 +169,20 @@ export function ChatWidget({ position = 'bottom-right', onAddToCart, apiUrl, ret
       });
 
       setWidgetError(null);
+      setHasMountValidationFailed(false);
       setIsOpen(true);
       setHasUnread(false);
     } catch (err: any) {
+      setHasMountValidationFailed(true);
       setWidgetError(err?.message || 'Access denied.');
-      setIsOpen(false); // DO NOT OPEN CHAT WIDGET
+      setIsOpen(false);
     } finally {
       setIsValidating(false);
     }
-  };
+  }, [hasMountValidationFailed, widgetError, resolveLicenseKey, projectId, retrivoraApiBase, headers]);
+
+  /** True when the license has been proven invalid and the widget must be locked. */
+  const isWidgetLocked = hasMountValidationFailed || isValidating;
 
   const handleResizeStart = (e: React.MouseEvent) => {
     e.preventDefault();
@@ -224,40 +300,65 @@ export function ChatWidget({ position = 'bottom-right', onAddToCart, apiUrl, ret
       {/* ── Floating Action Button ── */}
       <button
         onClick={isOpen ? () => setIsOpen(false) : handleOpen}
-        className={`group fixed z-[9999] w-14 h-14 drop-shadow-2xl flex items-center justify-center transition-all duration-300 cursor-pointer hover:scale-110 active:scale-95 ${positionClass}`}
-        aria-label="Open chat"
+        disabled={isWidgetLocked && !isOpen}
+        aria-label={isWidgetLocked ? 'Chat unavailable - invalid or missing license key' : (isOpen ? 'Close chat' : 'Open chat')}
+        aria-disabled={isWidgetLocked && !isOpen}
+        className={`group fixed z-[9999] w-14 h-14 drop-shadow-2xl flex items-center justify-center transition-all duration-300 ${positionClass} ${
+          isWidgetLocked && !isOpen
+            ? 'grayscale opacity-60 cursor-not-allowed'
+            : 'cursor-pointer hover:scale-110 active:scale-95'
+        }`}
       >
-        {/* Animated Background */}
+        {/* Animated Background (disabled when locked) */}
         <div
-          className="absolute inset-0 transition-all duration-300 overflow-hidden rounded-full group-hover:rounded-none group-hover:animate-[shapeshift_5s_ease-in-out_infinite_forwards]"
+          className={`absolute inset-0 transition-all duration-300 overflow-hidden rounded-full ${
+            !(isWidgetLocked && !isOpen) && 'group-hover:rounded-none group-hover:animate-[shapeshift_5s_ease-in-out_infinite_forwards]'
+          }`}
+          style={{
+            background: isWidgetLocked && !isOpen
+              ? 'linear-gradient(135deg, #64748b, #475569)'
+              : undefined,
+          }}
         >
-          <div
-            className="absolute top-0 left-0 w-[400%] h-[400%] transition-transform duration-300 group-hover:animate-[gradientMove_3.5s_ease-in-out_infinite_alternate]"
-            style={{
-              background: `linear-gradient(135deg, ${ui.primaryColor}, ${ui.accentColor}, ${ui.primaryColor}, ${ui.accentColor})`
-            }}
-          />
+          {!(isWidgetLocked && !isOpen) && (
+            <div
+              className="absolute top-0 left-0 w-[400%] h-[400%] transition-transform duration-300 group-hover:animate-[gradientMove_3.5s_ease-in-out_infinite_alternate]"
+              style={{
+                background: `linear-gradient(135deg, ${ui.primaryColor}, ${ui.accentColor}, ${ui.primaryColor}, ${ui.accentColor})`
+              }}
+            />
+          )}
         </div>
 
-        {/* Ripple ring */}
-        <span
-          className="absolute inset-0 rounded-full animate-ping opacity-20 pointer-events-none"
-          style={{ background: ui.primaryColor }}
-        />
+        {/* Ripple ring (hidden when locked) */}
+        {!(isWidgetLocked && !isOpen) && (
+          <span
+            className="absolute inset-0 rounded-full animate-ping opacity-20 pointer-events-none"
+            style={{ background: ui.primaryColor }}
+          />
+        )}
 
         {/* Icon Layer */}
         <span
-          className={`relative z-10 transition-transform duration-300 ${isOpen ? 'rotate-90 scale-90' : 'rotate-0 scale-100'}`}
+          className={`relative z-10 transition-transform duration-300 ${
+            isOpen
+              ? 'rotate-90 scale-90'
+              : isWidgetLocked
+                ? 'scale-90'
+                : 'rotate-0 scale-100'
+          }`}
         >
           {isOpen ? (
             <X className="w-6 h-6 text-white" />
+          ) : isWidgetLocked ? (
+            <Lock className="w-6 h-6 text-white" />
           ) : (
             <MessageSquare className="w-6 h-6 text-white" />
           )}
         </span>
 
-        {/* Unread badge */}
-        {hasUnread && !isOpen && (
+        {/* Unread badge (hidden when locked or open) */}
+        {hasUnread && !isOpen && !isWidgetLocked && (
           <span className="absolute top-0 right-0 w-4 h-4 bg-rose-500 rounded-full border-2 border-white flex items-center justify-center text-[9px] font-bold text-white">
             1
           </span>

package/src/components/ChatWindow.tsx

@@ -1,5 +1,18 @@
 'use client';
 
+/**
+ * ChatWindow — The primary chat interface container component.
+ *
+ * Renders a fully functional chat experience including:
+ *   - Header with branding, online indicator, and window controls (clear/resize/maximize/close)
+ *   - Scrollable message area with SSE-streamed assistant replies, sources, and welcome state
+ *   - Input area with textarea, voice input, document upload, auto-suggestions, and send controls
+ *   - Mandatory license validation on mount (shows a blocking error overlay if invalid / terminated)
+ *
+ * All chat-send-side inputs (textarea, voice, upload, suggestion chips, send button) are
+ * automatically disabled when the license validation fails or SDK version is unsupported.
+ */
+
 import React, { useState, useRef, useEffect, useCallback } from 'react';
 import {
   Bot,
@@ -25,6 +38,7 @@ import { ChatWindowProps } from '../types';
 import { SDK_VERSION } from '../version';
 import { LicenseValidator } from '../core/LicenseValidator';
 
+/** Browser Web Speech API extended event shape for continuous transcript delivery. */
 interface SpeechRecognitionEvent {
   resultIndex: number;
   results: {
@@ -36,10 +50,12 @@ interface SpeechRecognitionEvent {
   };
 }
 
+/** Browser Web Speech API error event shape. */
 interface SpeechRecognitionErrorEvent {
   error: string;
 }
 
+/** Browser Web Speech API controller interface. */
 interface ISpeechRecognition {
   continuous: boolean;
   interimResults: boolean;
@@ -50,11 +66,30 @@ interface ISpeechRecognition {
   stop: () => void;
 }
 
+/** Augmented Window global that surfaces both prefixed and unprefixed SpeechRecognition constructors. */
 interface WindowWithSpeech extends Window {
   SpeechRecognition?: new () => ISpeechRecognition;
   webkitSpeechRecognition?: new () => ISpeechRecognition;
 }
 
+/**
+ * ChatWindow component.
+ *
+ * @param className   - Additional CSS class for the outer wrapper.
+ * @param style       - Inline styles for the outer wrapper.
+ * @param onClose     - Callback for the close (X) button (widget mode only).
+ * @param showClose   - Whether to render the close button.
+ * @param onResizeStart - Callback fired when user begins dragging the resize handle.
+ * @param onResetResize - Callback fired when the reset-size button is clicked.
+ * @param isResized   - True if the window has been resized away from defaults.
+ * @param onMaximize  - Callback for the maximize/minimize toggle button.
+ * @param isMaximized - True if the window is currently maximized.
+ * @param onAddToCart - Callback fired when user clicks "Add to Cart" on a product card.
+ * @param apiUrl      - Override URL for the chat endpoint (bypasses retrivoraApiBase).
+ * @param retrivoraApiBase - Base URL for Retrivora catch-all endpoints (chat/suggestions/history/etc).
+ * @param licenseKey  - Override license key (highest priority; falls back to headers/env).
+ * @param headers     - Custom headers forwarded with every network request.
+ */
 export function ChatWindow({
   className = '',
   style,
@@ -95,6 +130,12 @@ export function ChatWindow({
   const [versionError, setVersionError] = useState<string | null>(null);
   const recognitionRef = useRef<ISpeechRecognition | null>(null);
 
+  /**
+   * True when all chat-send interactions must be blocked
+   * (license validation failed or SDK version is no longer supported).
+   */
+  const isDisabled = !!licenseError || !!versionError;
+
   // Validate server license and SDK version on ChatWindow session initialization
   useEffect(() => {
     let isMounted = true;
@@ -361,7 +402,8 @@ export function ChatWindow({
               <button
                 onClick={clearHistory}
                 title="Clear conversation"
-                className="w-7 h-7 rounded-md flex items-center justify-center text-slate-400 hover:text-rose-500 dark:text-white/40 dark:hover:text-rose-400 hover:bg-white dark:hover:bg-white/10 transition-all cursor-pointer"
+                disabled={isDisabled}
+                className="w-7 h-7 rounded-md flex items-center justify-center text-slate-400 hover:text-rose-500 dark:text-white/40 dark:hover:text-rose-400 hover:bg-white dark:hover:bg-white/10 transition-all cursor-pointer disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:text-slate-400 dark:disabled:hover:text-white/40"
               >
                 <Trash2 className="w-3.5 h-3.5" />
               </button>
@@ -524,18 +566,20 @@ export function ChatWindow({
       {/* ── Input ── */}
       <div className={`px-4 pb-4 pt-2 border-t border-slate-200 dark:border-white/10 ${isGlass ? 'bg-transparent' : 'bg-white dark:bg-[#0f0f1a]'}`}>
 
-        {/* Dynamic Suggestions */}
+        {/* Dynamic Suggestions — hidden/blocked when license/version error */}
         {(suggestions.length > 0 || isSuggesting) && !isLoading && (
           <div className="mb-3 flex flex-wrap gap-2 animate-in fade-in slide-in-from-bottom-2 duration-300">
             {suggestions.map((suggestion) => (
               <button
                 key={suggestion}
                 onClick={() => {
+                  if (isDisabled) return;
                   setInput(suggestion);
                   setSuggestions([]);
                   inputRef.current?.focus();
                 }}
-                className="flex items-center gap-1.5 px-3 py-1.5 rounded-xl text-[11px] font-medium bg-white dark:bg-white/5 border border-slate-200 dark:border-white/10 text-slate-600 dark:text-white/60 hover:text-slate-900 dark:hover:text-white/90 hover:border-slate-300 dark:hover:border-white/20 transition-all shadow-sm cursor-pointer group"
+                disabled={isDisabled}
+                className="flex items-center gap-1.5 px-3 py-1.5 rounded-xl text-[11px] font-medium bg-white dark:bg-white/5 border border-slate-200 dark:border-white/10 text-slate-600 dark:text-white/60 hover:text-slate-900 dark:hover:text-white/90 hover:border-slate-300 dark:hover:border-white/20 transition-all shadow-sm cursor-pointer group disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:text-slate-600 dark:disabled:hover:text-white/60"
               >
                 <Sparkles className="w-3 h-3 text-amber-400" />
                 {suggestion}
@@ -564,7 +608,7 @@ export function ChatWindow({
             onKeyDown={handleKeyDown}
             placeholder={ui.placeholder}
             rows={1}
-            disabled={isLoading || !!licenseError || !!versionError}
+            disabled={isLoading || isDisabled}
             className="flex-1 bg-transparent text-slate-900 dark:text-white/90 placeholder-slate-400 dark:placeholder-white/30 text-sm resize-none outline-none py-1.5 px-2 max-h-32 leading-relaxed disabled:opacity-50"
             style={{ scrollbarWidth: 'none' }}
           />
@@ -573,7 +617,7 @@ export function ChatWindow({
             <button
               type="button"
               onClick={toggleListening}
-              disabled={isLoading || !!licenseError || !!versionError}
+              disabled={isLoading || isDisabled}
               className={`flex-shrink-0 w-9 h-9 rounded-xl flex items-center justify-center transition-all hover:scale-105 active:scale-95 disabled:opacity-50 disabled:cursor-not-allowed disabled:hover:scale-100 disabled:active:scale-100 ${isListening
                   ? 'bg-rose-500 text-white animate-pulse shadow-md shadow-rose-500/20'
                   : 'text-slate-400 dark:text-white/40 hover:bg-slate-200 dark:hover:bg-white/10'
@@ -587,8 +631,8 @@ export function ChatWindow({
           {ui.allowUpload !== false && (
             <button
               type="button"
-              onClick={() => setIsUploadModalOpen(true)}
-              disabled={isLoading || !!licenseError || !!versionError}
+              onClick={() => { if (!isDisabled) setIsUploadModalOpen(true); }}
+              disabled={isLoading || isDisabled}
               className="flex-shrink-0 w-9 h-9 rounded-xl flex items-center justify-center transition-all hover:scale-105 active:scale-95 text-slate-400 dark:text-white/40 hover:bg-slate-200 dark:hover:bg-white/10 disabled:opacity-50 disabled:cursor-not-allowed"
               title="Upload Document"
             >
@@ -607,7 +651,7 @@ export function ChatWindow({
           ) : (
             <button
               onClick={sendMessage}
-              disabled={!input.trim() || !!licenseError || !!versionError}
+              disabled={!input.trim() || isDisabled}
               className={`flex-shrink-0 w-9 h-9 flex items-center justify-center transition-all shadow-md active:scale-95 cursor-pointer disabled:opacity-30 disabled:cursor-not-allowed disabled:active:scale-100 ${ui.borderRadius === 'full' ? 'rounded-full' : 'rounded-xl'}`}
               style={{ background: `linear-gradient(135deg, ${ui.primaryColor}, ${ui.accentColor})` }}
               title="Send message"

package/src/core/BatchProcessor.ts

@@ -5,6 +5,8 @@
  * configurable batch sizing for efficient bulk operations.
  */
 
+import { CircuitBreaker } from './CircuitBreaker';
+
 export interface BatchOptions {
   /** Maximum number of items per batch */
   batchSize?: number;
@@ -30,7 +32,7 @@ export interface BatchResult<T> {
 /**
  * Determines if an error is transient (should retry)
  */
-function isTransientError(error: unknown): boolean {
+export function isTransientError(error: unknown): boolean {
   if (!(error instanceof Error)) return false;
 
   const message = error.message.toLowerCase();
@@ -86,6 +88,42 @@ function sleep(ms: number): Promise<void> {
 }
 
 export class BatchProcessor {
+  private static readonly cb = new CircuitBreaker({
+    failureThreshold: 5,
+    resetTimeoutMs: 30_000,
+    halfOpenMaxCalls: 1,
+  });
+
+  /**
+   * Execute a processor call through the circuit breaker.
+   * Only transient failures count toward opening the circuit.
+   */
+  private static async executeWithCircuitBreaker<T>(processor: () => Promise<T>): Promise<T> {
+    if (!this.cb.canExecute()) {
+      const retryAfterSec = Math.ceil(
+        Math.max(0, 30_000 - (Date.now() - (this.cb as any).lastFailureAt || 0)) / 1000
+      );
+      throw new Error(
+        `[BatchProcessor] Circuit breaker is open. Try again in ${retryAfterSec}s.`
+      );
+    }
+
+    if ((this.cb as any).state === 'half-open') {
+      (this.cb as any).halfOpenCalls++;
+    }
+
+    try {
+      const result = await processor();
+      this.cb.record(true);
+      return result;
+    } catch (err) {
+      if (isTransientError(err)) {
+        this.cb.record(false);
+      }
+      throw err;
+    }
+  }
+
   /**
    * Processes an array of items in configurable batches with retry logic.
    *
@@ -137,7 +175,7 @@ export class BatchProcessor {
 
       for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
-          const result = await processor(batch);
+          const result = await BatchProcessor.executeWithCircuitBreaker(() => processor(batch));
           results.push(result);
           success = true;
           break;
@@ -212,7 +250,7 @@ export class BatchProcessor {
 
       for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
-          const result = await processor(item);
+          const result = await BatchProcessor.executeWithCircuitBreaker(() => processor(item));
           results.push(result);
           success = true;
           break;
@@ -311,7 +349,7 @@ export class BatchProcessor {
 
       const chunkPromises = chunk.map(async ({ item, originalIndex }) => {
         try {
-          const result = await processor(item);
+          const result = await BatchProcessor.executeWithCircuitBreaker(() => processor(item));
           return { success: true, result, index: originalIndex };
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err));

package/src/core/CircuitBreaker.ts

@@ -0,0 +1,118 @@
+type CircuitState = 'closed' | 'open' | 'half-open';
+
+export interface CircuitBreakerOptions {
+  failureThreshold?: number;
+  resetTimeoutMs?: number;
+  halfOpenMaxCalls?: number;
+}
+
+export class CircuitBreaker {
+  private state: CircuitState = 'closed';
+  private failureCount = 0;
+  private successCount = 0;
+  private lastFailureAt = 0;
+  private halfOpenCalls = 0;
+
+  private readonly failureThreshold: number;
+  private readonly resetTimeoutMs: number;
+  private readonly halfOpenMaxCalls: number;
+
+  constructor(options: CircuitBreakerOptions = {}) {
+    this.failureThreshold = options.failureThreshold ?? 5;
+    this.resetTimeoutMs = options.resetTimeoutMs ?? 30_000;
+    this.halfOpenMaxCalls = options.halfOpenMaxCalls ?? 1;
+  }
+
+  record(success: boolean): void {
+    const now = Date.now();
+
+    if (success) {
+      this.successCount++;
+      if (this.state === 'half-open') {
+        this.state = 'closed';
+        this.failureCount = 0;
+        this.halfOpenCalls = 0;
+        this.successCount = 1;
+      } else if (this.state === 'closed') {
+        if (this.successCount >= this.failureThreshold) {
+          this.failureCount = Math.max(0, this.failureCount - 1);
+          this.successCount = 0;
+        }
+      }
+    } else {
+      this.failureCount++;
+      this.lastFailureAt = now;
+      this.successCount = 0;
+      if (this.state === 'half-open') {
+        this.state = 'open';
+        this.halfOpenCalls = 0;
+      } else if (this.state === 'closed' && this.failureCount >= this.failureThreshold) {
+        this.state = 'open';
+      }
+    }
+  }
+
+  canExecute(): boolean {
+    const now = Date.now();
+
+    if (this.state === 'closed') {
+      return true;
+    }
+
+    if (this.state === 'open') {
+      if (now - this.lastFailureAt >= this.resetTimeoutMs) {
+        this.state = 'half-open';
+        this.halfOpenCalls = 0;
+        return true;
+      }
+      return false;
+    }
+
+    if (this.state === 'half-open') {
+      return this.halfOpenCalls < this.halfOpenMaxCalls;
+    }
+
+    return true;
+  }
+
+  async wrap<T>(fn: () => Promise<T>): Promise<T> {
+    if (!this.canExecute()) {
+      const retryAfterSec = Math.ceil(
+        Math.max(0, this.resetTimeoutMs - (Date.now() - this.lastFailureAt)) / 1000
+      );
+      throw new Error(
+        `Circuit breaker is open. Try again in ${retryAfterSec}s. ` +
+        `Failed ${this.failureCount}/${this.failureThreshold} consecutive calls.`
+      );
+    }
+
+    if (this.state === 'half-open') {
+      this.halfOpenCalls++;
+    }
+
+    try {
+      const result = await fn();
+      this.record(true);
+      return result;
+    } catch (err) {
+      this.record(false);
+      throw err;
+    }
+  }
+
+  getState(): CircuitState {
+    return this.state;
+  }
+
+  getFailureCount(): number {
+    return this.failureCount;
+  }
+
+  reset(): void {
+    this.state = 'closed';
+    this.failureCount = 0;
+    this.successCount = 0;
+    this.lastFailureAt = 0;
+    this.halfOpenCalls = 0;
+  }
+}