@onlineapps/conn-infra-error-handler 1.0.0

package/API.md

@@ -0,0 +1,637 @@
+<a name="module_@onlineapps/conn-infra-error-handler"></a>
+
+## @onlineapps/conn-infra-error-handler
+Unified error handling connector providing retry strategies, circuit breaker pattern,
+and compensation mechanisms for OA Drive microservices.
+
+**See**: [GitHub Repository](https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-infra-error-handler)  
+**Since**: 1.0.0  
+**Author**: OA Drive Team  
+**License**: MIT  
+
+* [@onlineapps/conn-infra-error-handler](#module_@onlineapps/conn-infra-error-handler)
+    * _static_
+        * [.ErrorTypes](#module_@onlineapps/conn-infra-error-handler.ErrorTypes) : <code>enum</code>
+        * [.ErrorCodes](#module_@onlineapps/conn-infra-error-handler.ErrorCodes) : <code>enum</code>
+        * [.VERSION](#module_@onlineapps/conn-infra-error-handler.VERSION) : <code>string</code>
+    * _inner_
+        * [~ErrorHandlerConnector](#module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector)
+            * [new ErrorHandlerConnector()](#new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new)
+            * [new ErrorHandlerConnector([config])](#new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new)
+            * [.getCircuitBreaker(name, fn, options)](#module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector+getCircuitBreaker) ⇒ <code>CircuitBreaker</code>
+        * [~ErrorHandlerConnector](#module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector)
+            * [new ErrorHandlerConnector()](#new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new)
+            * [new ErrorHandlerConnector([config])](#new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new)
+            * [.getCircuitBreaker(name, fn, options)](#module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector+getCircuitBreaker) ⇒ <code>CircuitBreaker</code>
+        * [~classifyError(error)](#module_@onlineapps/conn-infra-error-handler..classifyError) ⇒ <code>string</code>
+        * [~shouldRetry(error, [attempts])](#module_@onlineapps/conn-infra-error-handler..shouldRetry) ⇒ <code>boolean</code>
+        * [~calculateBackoff(attempts)](#module_@onlineapps/conn-infra-error-handler..calculateBackoff) ⇒ <code>number</code>
+        * [~executeWithRetry(fn, [options])](#module_@onlineapps/conn-infra-error-handler..executeWithRetry) ⇒ <code>Promise.&lt;\*&gt;</code>
+        * [~executeWithCircuitBreaker(name, fn, [options])](#module_@onlineapps/conn-infra-error-handler..executeWithCircuitBreaker) ⇒ <code>Promise.&lt;\*&gt;</code>
+        * [~registerCompensation(operation, handler)](#module_@onlineapps/conn-infra-error-handler..registerCompensation) ⇒ <code>void</code>
+        * [~executeCompensation(operation, context)](#module_@onlineapps/conn-infra-error-handler..executeCompensation) ⇒ <code>Promise.&lt;\*&gt;</code>
+        * [~routeToDLQ(mqClient, message, error)](#module_@onlineapps/conn-infra-error-handler..routeToDLQ) ⇒ <code>Promise.&lt;void&gt;</code>
+        * [~createErrorResponse(error, [context])](#module_@onlineapps/conn-infra-error-handler..createErrorResponse) ⇒ <code>ErrorResponse</code>
+        * [~wrap(fn, [options])](#module_@onlineapps/conn-infra-error-handler..wrap) ⇒ <code>function</code>
+        * [~handleWorkflowError(workflow, error, failedStep)](#module_@onlineapps/conn-infra-error-handler..handleWorkflowError) ⇒ <code>Promise.&lt;WorkflowErrorResult&gt;</code>
+        * [~getStats()](#module_@onlineapps/conn-infra-error-handler..getStats) ⇒ <code>ErrorStats</code>
+        * [~resetStats()](#module_@onlineapps/conn-infra-error-handler..resetStats) ⇒ <code>void</code>
+        * [~create(config)](#module_@onlineapps/conn-infra-error-handler..create) ⇒ <code>ErrorHandlerConnector</code>
+        * [~ErrorResponse](#module_@onlineapps/conn-infra-error-handler..ErrorResponse) : <code>Object</code>
+        * [~WorkflowErrorResult](#module_@onlineapps/conn-infra-error-handler..WorkflowErrorResult) : <code>Object</code>
+        * [~ErrorStats](#module_@onlineapps/conn-infra-error-handler..ErrorStats) : <code>Object</code>
+
+<a name="module_@onlineapps/conn-infra-error-handler.ErrorTypes"></a>
+
+### @onlineapps/conn-infra-error-handler.ErrorTypes : <code>enum</code>
+Error type enumeration
+
+**Kind**: static enum of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+<a name="module_@onlineapps/conn-infra-error-handler.ErrorCodes"></a>
+
+### @onlineapps/conn-infra-error-handler.ErrorCodes : <code>enum</code>
+Standard error code mappings
+
+**Kind**: static enum of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+<a name="module_@onlineapps/conn-infra-error-handler.VERSION"></a>
+
+### @onlineapps/conn-infra-error-handler.VERSION : <code>string</code>
+Current version
+
+**Kind**: static constant of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+<a name="module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector"></a>
+
+### @onlineapps/conn-infra-error-handler~ErrorHandlerConnector
+**Kind**: inner class of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+
+* [~ErrorHandlerConnector](#module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector)
+    * [new ErrorHandlerConnector()](#new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new)
+    * [new ErrorHandlerConnector([config])](#new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new)
+    * [.getCircuitBreaker(name, fn, options)](#module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector+getCircuitBreaker) ⇒ <code>CircuitBreaker</code>
+
+<a name="new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new"></a>
+
+#### new ErrorHandlerConnector()
+Error handling connector with retry, circuit breaker, and compensation
+
+**Example** *(Basic Usage)*  
+```js
+const errorHandler = new ErrorHandlerConnector({
+  maxRetries: 3,
+  retryDelay: 1000
+});
+
+const result = await errorHandler.executeWithRetry(async () => {
+  return await riskyOperation();
+});
+```
+**Example** *(With Circuit Breaker)*  
+```js
+const errorHandler = new ErrorHandlerConnector({
+  circuitBreakerEnabled: true,
+  errorThreshold: 50
+});
+
+await errorHandler.executeWithCircuitBreaker('api-call', async () => {
+  return await apiClient.call();
+});
+```
+<a name="new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new"></a>
+
+#### new ErrorHandlerConnector([config])
+Creates a new ErrorHandlerConnector instance
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [config] | <code>Object</code> | <code>{}</code> | Configuration options |
+| [config.maxRetries] | <code>number</code> | <code>3</code> | Maximum retry attempts |
+| [config.retryDelay] | <code>number</code> | <code>1000</code> | Initial retry delay in ms |
+| [config.retryMultiplier] | <code>number</code> | <code>2</code> | Backoff multiplier |
+| [config.maxRetryDelay] | <code>number</code> | <code>30000</code> | Maximum retry delay |
+| [config.circuitBreakerEnabled] | <code>boolean</code> | <code>true</code> | Enable circuit breaker |
+| [config.circuitTimeout] | <code>number</code> | <code>10000</code> | Circuit breaker timeout |
+| [config.errorThreshold] | <code>number</code> | <code>50</code> | Error threshold percentage |
+| [config.resetTimeout] | <code>number</code> | <code>30000</code> | Circuit reset timeout |
+| [config.compensationEnabled] | <code>boolean</code> | <code>true</code> | Enable compensation |
+| [config.circuitBreakerOptions] | <code>Object</code> |  | Additional circuit breaker options |
+
+**Example** *(Full Configuration)*  
+```js
+const errorHandler = new ErrorHandlerConnector({
+  maxRetries: 5,
+  retryDelay: 500,
+  retryMultiplier: 1.5,
+  maxRetryDelay: 20000,
+  circuitBreakerEnabled: true,
+  errorThreshold: 60,
+  compensationEnabled: true
+});
+```
+<a name="module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector+getCircuitBreaker"></a>
+
+#### errorHandlerConnector.getCircuitBreaker(name, fn, options) ⇒ <code>CircuitBreaker</code>
+Get or create circuit breaker for operation
+
+**Kind**: instance method of [<code>ErrorHandlerConnector</code>](#module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector)  
+**Returns**: <code>CircuitBreaker</code> - Circuit breaker instance  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| name | <code>string</code> | Operation name |
+| fn | <code>function</code> | Function to protect |
+| options | <code>object</code> | Circuit breaker options |
+
+<a name="module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector"></a>
+
+### @onlineapps/conn-infra-error-handler~ErrorHandlerConnector
+**Kind**: inner class of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+
+* [~ErrorHandlerConnector](#module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector)
+    * [new ErrorHandlerConnector()](#new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new)
+    * [new ErrorHandlerConnector([config])](#new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new)
+    * [.getCircuitBreaker(name, fn, options)](#module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector+getCircuitBreaker) ⇒ <code>CircuitBreaker</code>
+
+<a name="new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new"></a>
+
+#### new ErrorHandlerConnector()
+Error handling connector with retry, circuit breaker, and compensation
+
+**Example** *(Basic Usage)*  
+```js
+const errorHandler = new ErrorHandlerConnector({
+  maxRetries: 3,
+  retryDelay: 1000
+});
+
+const result = await errorHandler.executeWithRetry(async () => {
+  return await riskyOperation();
+});
+```
+**Example** *(With Circuit Breaker)*  
+```js
+const errorHandler = new ErrorHandlerConnector({
+  circuitBreakerEnabled: true,
+  errorThreshold: 50
+});
+
+await errorHandler.executeWithCircuitBreaker('api-call', async () => {
+  return await apiClient.call();
+});
+```
+<a name="new_module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector_new"></a>
+
+#### new ErrorHandlerConnector([config])
+Creates a new ErrorHandlerConnector instance
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [config] | <code>Object</code> | <code>{}</code> | Configuration options |
+| [config.maxRetries] | <code>number</code> | <code>3</code> | Maximum retry attempts |
+| [config.retryDelay] | <code>number</code> | <code>1000</code> | Initial retry delay in ms |
+| [config.retryMultiplier] | <code>number</code> | <code>2</code> | Backoff multiplier |
+| [config.maxRetryDelay] | <code>number</code> | <code>30000</code> | Maximum retry delay |
+| [config.circuitBreakerEnabled] | <code>boolean</code> | <code>true</code> | Enable circuit breaker |
+| [config.circuitTimeout] | <code>number</code> | <code>10000</code> | Circuit breaker timeout |
+| [config.errorThreshold] | <code>number</code> | <code>50</code> | Error threshold percentage |
+| [config.resetTimeout] | <code>number</code> | <code>30000</code> | Circuit reset timeout |
+| [config.compensationEnabled] | <code>boolean</code> | <code>true</code> | Enable compensation |
+| [config.circuitBreakerOptions] | <code>Object</code> |  | Additional circuit breaker options |
+
+**Example** *(Full Configuration)*  
+```js
+const errorHandler = new ErrorHandlerConnector({
+  maxRetries: 5,
+  retryDelay: 500,
+  retryMultiplier: 1.5,
+  maxRetryDelay: 20000,
+  circuitBreakerEnabled: true,
+  errorThreshold: 60,
+  compensationEnabled: true
+});
+```
+<a name="module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector+getCircuitBreaker"></a>
+
+#### errorHandlerConnector.getCircuitBreaker(name, fn, options) ⇒ <code>CircuitBreaker</code>
+Get or create circuit breaker for operation
+
+**Kind**: instance method of [<code>ErrorHandlerConnector</code>](#module_@onlineapps/conn-infra-error-handler..ErrorHandlerConnector)  
+**Returns**: <code>CircuitBreaker</code> - Circuit breaker instance  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| name | <code>string</code> | Operation name |
+| fn | <code>function</code> | Function to protect |
+| options | <code>object</code> | Circuit breaker options |
+
+<a name="module_@onlineapps/conn-infra-error-handler..classifyError"></a>
+
+### @onlineapps/conn-infra-error-handler~classifyError(error) ⇒ <code>string</code>
+Classify error into type for appropriate handling
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>string</code> - Error type from ErrorTypes enum  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| error | <code>Error</code> | Error to classify |
+| [error.code] | <code>string</code> | Error code (e.g., ECONNREFUSED) |
+| [error.statusCode] | <code>number</code> | HTTP status code |
+| [error.type] | <code>string</code> | Explicit error type |
+
+**Example** *(Network Error)*  
+```js
+const type = errorHandler.classifyError(new Error('ECONNREFUSED'));
+// Returns: 'TRANSIENT'
+```
+**Example** *(HTTP Error)*  
+```js
+const error = new Error('Not Found');
+error.statusCode = 404;
+const type = errorHandler.classifyError(error);
+// Returns: 'BUSINESS'
+```
+**Example** *(Timeout Error)*  
+```js
+const type = errorHandler.classifyError(new Error('Operation timeout'));
+// Returns: 'TIMEOUT'
+```
+<a name="module_@onlineapps/conn-infra-error-handler..shouldRetry"></a>
+
+### @onlineapps/conn-infra-error-handler~shouldRetry(error, [attempts]) ⇒ <code>boolean</code>
+Determine if error should be retried
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>boolean</code> - True if should retry  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| error | <code>Error</code> |  | Error to check |
+| [attempts] | <code>number</code> | <code>0</code> | Current attempt count |
+
+**Example**  
+```js
+const error = new Error('Connection refused');
+if (errorHandler.shouldRetry(error, 1)) {
+  // Retry the operation
+}
+```
+<a name="module_@onlineapps/conn-infra-error-handler..calculateBackoff"></a>
+
+### @onlineapps/conn-infra-error-handler~calculateBackoff(attempts) ⇒ <code>number</code>
+Calculate exponential backoff delay
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>number</code> - Delay in milliseconds  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| attempts | <code>number</code> | Current attempt number (1-based) |
+
+**Example**  
+```js
+const delay = errorHandler.calculateBackoff(3);
+// With default config: 1000 * 2^2 = 4000ms
+```
+<a name="module_@onlineapps/conn-infra-error-handler..executeWithRetry"></a>
+
+### @onlineapps/conn-infra-error-handler~executeWithRetry(fn, [options]) ⇒ <code>Promise.&lt;\*&gt;</code>
+Execute function with automatic retry on failure
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>Promise.&lt;\*&gt;</code> - Function result  
+**Throws**:
+
+- <code>Error</code> Last error if all retries fail
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| fn | <code>function</code> |  | Async function to execute |
+| [options] | <code>Object</code> | <code>{}</code> | Retry options |
+| [options.maxRetries] | <code>number</code> |  | Override max retries |
+| [options.retryOn] | <code>Array.&lt;string&gt;</code> | <code>[]</code> | Additional error codes to retry |
+| [options.onRetry] | <code>function</code> |  | Callback on retry (error, attempt, delay) |
+
+**Example** *(Simple Retry)*  
+```js
+const result = await errorHandler.executeWithRetry(async () => {
+  return await apiClient.fetchData();
+});
+```
+**Example** *(With Options)*  
+```js
+const result = await errorHandler.executeWithRetry(
+  async () => await riskyOperation(),
+  {
+    maxRetries: 5,
+    retryOn: ['CUSTOM_ERROR'],
+    onRetry: (error, attempt, delay) => {
+      console.log(`Retry ${attempt} after ${delay}ms`);
+    }
+  }
+);
+```
+**Example** *(Database Operation)*  
+```js
+const data = await errorHandler.executeWithRetry(async () => {
+  const conn = await db.connect();
+  try {
+    return await conn.query('SELECT * FROM users');
+  } finally {
+    conn.close();
+  }
+});
+```
+<a name="module_@onlineapps/conn-infra-error-handler..executeWithCircuitBreaker"></a>
+
+### @onlineapps/conn-infra-error-handler~executeWithCircuitBreaker(name, fn, [options]) ⇒ <code>Promise.&lt;\*&gt;</code>
+Execute function with circuit breaker protection
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>Promise.&lt;\*&gt;</code> - Function result  
+**Throws**:
+
+- <code>Error</code> If circuit is open or operation fails
+
+**Emits**: <code>CircuitBreaker#event:open - When circuit opens</code>, <code>CircuitBreaker#event:halfOpen - When circuit enters half-open state</code>  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| name | <code>string</code> |  | Operation name for circuit breaker |
+| fn | <code>function</code> |  | Async function to execute |
+| [options] | <code>Object</code> | <code>{}</code> | Circuit breaker options |
+| [options.timeout] | <code>number</code> |  | Operation timeout |
+| [options.errorThresholdPercentage] | <code>number</code> |  | Error threshold |
+
+**Example** *(API Call Protection)*  
+```js
+try {
+  const data = await errorHandler.executeWithCircuitBreaker(
+    'user-api',
+    async () => await userAPI.getUser(id)
+  );
+} catch (error) {
+  if (error.message.includes('circuit is open')) {
+    // Service is down, use fallback
+  }
+}
+```
+**Example** *(With Custom Options)*  
+```js
+const result = await errorHandler.executeWithCircuitBreaker(
+  'payment-gateway',
+  async () => await processPayment(order),
+  {
+    timeout: 5000,
+    errorThresholdPercentage: 30
+  }
+);
+```
+<a name="module_@onlineapps/conn-infra-error-handler..registerCompensation"></a>
+
+### @onlineapps/conn-infra-error-handler~registerCompensation(operation, handler) ⇒ <code>void</code>
+Register compensation handler for an operation
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| operation | <code>string</code> | Operation name |
+| handler | <code>function</code> | Compensation handler function |
+
+**Example**  
+```js
+errorHandler.registerCompensation('create-order', async (context) => {
+  // Rollback order creation
+  await orderService.cancel(context.orderId);
+});
+
+errorHandler.registerCompensation('charge-payment', async (context) => {
+  // Refund payment
+  await paymentService.refund(context.chargeId);
+});
+```
+<a name="module_@onlineapps/conn-infra-error-handler..executeCompensation"></a>
+
+### @onlineapps/conn-infra-error-handler~executeCompensation(operation, context) ⇒ <code>Promise.&lt;\*&gt;</code>
+Execute compensation for failed operation
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>Promise.&lt;\*&gt;</code> - Compensation result or null if no handler  
+**Throws**:
+
+- <code>Error</code> If compensation fails
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| operation | <code>string</code> | Operation that failed |
+| context | <code>Object</code> | Operation context for compensation |
+
+**Example**  
+```js
+try {
+  await createOrder(data);
+} catch (error) {
+  await errorHandler.executeCompensation('create-order', {
+    orderId: data.orderId,
+    userId: data.userId
+  });
+}
+```
+<a name="module_@onlineapps/conn-infra-error-handler..routeToDLQ"></a>
+
+### @onlineapps/conn-infra-error-handler~routeToDLQ(mqClient, message, error) ⇒ <code>Promise.&lt;void&gt;</code>
+Route failed message to dead letter queue
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| mqClient | <code>Object</code> | Message queue client |
+| message | <code>Object</code> | Original message that failed |
+| error | <code>Error</code> | Error that occurred |
+
+**Example**  
+```js
+try {
+  await processMessage(message);
+} catch (error) {
+  if (!errorHandler.shouldRetry(error)) {
+    await errorHandler.routeToDLQ(mqClient, message, error);
+  }
+}
+```
+<a name="module_@onlineapps/conn-infra-error-handler..createErrorResponse"></a>
+
+### @onlineapps/conn-infra-error-handler~createErrorResponse(error, [context]) ⇒ <code>ErrorResponse</code>
+Create standardized error response
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>ErrorResponse</code> - Formatted error response  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| error | <code>Error</code> |  | Original error |
+| [context] | <code>Object</code> | <code>{}</code> | Additional context |
+
+**Example**  
+```js
+const response = errorHandler.createErrorResponse(
+  new Error('Database connection failed'),
+  { operation: 'user-fetch', userId: 123 }
+);
+// Returns standardized error object
+```
+<a name="module_@onlineapps/conn-infra-error-handler..wrap"></a>
+
+### @onlineapps/conn-infra-error-handler~wrap(fn, [options]) ⇒ <code>function</code>
+Wrap function with error handling capabilities
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>function</code> - Wrapped function  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| fn | <code>function</code> |  | Function to wrap |
+| [options] | <code>Object</code> | <code>{}</code> | Wrapping options |
+| [options.name] | <code>string</code> |  | Operation name |
+| [options.circuitBreaker] | <code>boolean</code> | <code>true</code> | Use circuit breaker |
+| [options.retry] | <code>boolean</code> | <code>true</code> | Use retry logic |
+| [options.maxRetries] | <code>number</code> |  | Max retry attempts |
+
+**Example** *(Wrap API Function)*  
+```js
+const safeApiCall = errorHandler.wrap(
+  async (id) => await api.getUser(id),
+  { name: 'get-user', maxRetries: 3 }
+);
+
+const user = await safeApiCall(123);
+```
+**Example** *(Wrap Database Function)*  
+```js
+const safeQuery = errorHandler.wrap(
+  async (sql, params) => await db.query(sql, params),
+  { circuitBreaker: false, retry: true }
+);
+```
+<a name="module_@onlineapps/conn-infra-error-handler..handleWorkflowError"></a>
+
+### @onlineapps/conn-infra-error-handler~handleWorkflowError(workflow, error, failedStep) ⇒ <code>Promise.&lt;WorkflowErrorResult&gt;</code>
+Handle workflow error with compensation support
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>Promise.&lt;WorkflowErrorResult&gt;</code> - Error handling result  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| workflow | <code>Object</code> | Workflow context |
+| error | <code>Error</code> | Error that occurred |
+| failedStep | <code>string</code> | Step that failed |
+
+**Example**  
+```js
+const result = await errorHandler.handleWorkflowError(
+  workflowContext,
+  error,
+  'payment-processing'
+);
+
+if (result.shouldRetry) {
+  // Retry the step
+} else if (result.compensated) {
+  // Compensation was executed
+}
+```
+<a name="module_@onlineapps/conn-infra-error-handler..getStats"></a>
+
+### @onlineapps/conn-infra-error-handler~getStats() ⇒ <code>ErrorStats</code>
+Get error handler statistics
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>ErrorStats</code> - Current statistics  
+**Example**  
+```js
+const stats = errorHandler.getStats();
+console.log(`Total errors: ${stats.errors}`);
+console.log(`Retry success rate: ${stats.retries / stats.errors * 100}%`);
+console.log(`Circuit breakers:`, stats.circuitBreakers);
+```
+<a name="module_@onlineapps/conn-infra-error-handler..resetStats"></a>
+
+### @onlineapps/conn-infra-error-handler~resetStats() ⇒ <code>void</code>
+Reset all statistics
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Example**  
+```js
+errorHandler.resetStats();
+// All counters reset to 0
+```
+<a name="module_@onlineapps/conn-infra-error-handler..create"></a>
+
+### @onlineapps/conn-infra-error-handler~create(config) ⇒ <code>ErrorHandlerConnector</code>
+Factory function to create error handler instance
+
+**Kind**: inner method of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Returns**: <code>ErrorHandlerConnector</code> - New error handler instance  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| config | <code>Object</code> | Configuration object |
+
+**Example**  
+```js
+const errorHandler = ErrorHandlerConnector.create({
+  maxRetries: 5,
+  circuitBreakerEnabled: true
+});
+```
+<a name="module_@onlineapps/conn-infra-error-handler..ErrorResponse"></a>
+
+### @onlineapps/conn-infra-error-handler~ErrorResponse : <code>Object</code>
+**Kind**: inner typedef of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| success | <code>boolean</code> | Always false for errors |
+| error | <code>Object</code> | Error details |
+| error.message | <code>string</code> | Error message |
+| error.code | <code>string</code> | Error code |
+| error.type | <code>string</code> | Error type from ErrorTypes |
+| error.retryable | <code>boolean</code> | Whether error is retryable |
+| error.timestamp | <code>string</code> | ISO timestamp |
+
+<a name="module_@onlineapps/conn-infra-error-handler..WorkflowErrorResult"></a>
+
+### @onlineapps/conn-infra-error-handler~WorkflowErrorResult : <code>Object</code>
+**Kind**: inner typedef of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| handled | <code>boolean</code> | Whether error was handled |
+| compensated | <code>boolean</code> | Whether compensation was executed |
+| shouldContinue | <code>boolean</code> | Whether workflow should continue |
+| shouldRetry | <code>boolean</code> | Whether step should be retried |
+| error | <code>ErrorResponse</code> | Error response |
+
+<a name="module_@onlineapps/conn-infra-error-handler..ErrorStats"></a>
+
+### @onlineapps/conn-infra-error-handler~ErrorStats : <code>Object</code>
+**Kind**: inner typedef of [<code>@onlineapps/conn-infra-error-handler</code>](#module_@onlineapps/conn-infra-error-handler)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| errors | <code>number</code> | Total errors |
+| retries | <code>number</code> | Total retries |
+| compensations | <code>number</code> | Total compensations |
+| circuitBreaks | <code>number</code> | Circuit breaker trips |
+| byType | <code>Object</code> | Errors by type |
+| circuitBreakers | <code>Object</code> | Circuit breaker states |
+

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@onlineapps/conn-infra-error-handler",
+  "version": "1.0.0",
+  "description": "Unified error handling with retry strategies, circuit breaker, and compensation patterns",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest",
+    "test:unit": "jest test/unit",
+    "test:integration": "jest test/integration",
+    "docs": "jsdoc2md --files src/**/*.js > API.md"
+  },
+  "keywords": [
+    "error-handling",
+    "retry",
+    "circuit-breaker",
+    "compensation",
+    "resilience"
+  ],
+  "author": "OA Drive Team",
+  "license": "MIT",
+  "dependencies": {
+    "opossum": "^7.1.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}