@gravito/echo 3.1.2 → 4.0.0

package/dist/errors/EchoError.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Echo error types
+ *
+ * @module @gravito/echo/errors
+ */
+import { InfrastructureException, type InfrastructureExceptionOptions } from '@gravito/core';
+import type { EchoErrorCode } from './codes';
+/**
+ * Base error class for Echo module.
+ *
+ * Provides structured error handling with error codes and messages.
+ * Extends InfrastructureException for unified error handling across Gravito.
+ *
+ * @example
+ * ```typescript
+ * throw new EchoError('echo.unknown_provider', 'Unknown provider type: stripe')
+ * ```
+ * @public
+ */
+export declare class EchoError extends InfrastructureException {
+    /**
+     * Creates a new EchoError instance.
+     *
+     * @param code - The error code.
+     * @param message - The error message.
+     * @param options - Optional infrastructure exception options.
+     */
+    constructor(code: EchoErrorCode, message: string, options?: InfrastructureExceptionOptions);
+}

package/dist/errors/codes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Echo error codes
+ *
+ * Namespaced error codes for the Echo webhook module.
+ *
+ * @module @gravito/echo/errors
+ */
+/**
+ * Error codes for Echo module operations.
+ * Follows dot-separated namespace convention.
+ */
+export declare const EchoErrorCodes: {
+    readonly UNKNOWN_PROVIDER: "echo.unknown_provider";
+    readonly KEY_ROTATION_NOT_SET: "echo.key_rotation_not_set";
+    readonly NO_PRIMARY_KEY: "echo.no_primary_key";
+    readonly KEY_ROTATION_NOT_ENABLED: "echo.key_rotation_not_enabled";
+    readonly NO_DELIVERY_ATTEMPTS: "echo.no_delivery_attempts";
+    readonly INVALID_CONFIG: "echo.invalid_config";
+};
+export type EchoErrorCode = (typeof EchoErrorCodes)[keyof typeof EchoErrorCodes];

package/dist/index.d.ts

@@ -38,6 +38,9 @@
  * @module @gravito/echo
  */
 export type { DeadLetterEvent, DeadLetterQueue } from './dlq/DeadLetterQueue';
+export { EchoError } from './errors/EchoError';
+export { EchoErrorCodes } from './errors/codes';
+export type { EchoErrorCode } from './errors/codes';
 export { MemoryDeadLetterQueue } from './dlq/MemoryDeadLetterQueue';
 export { createRequestBufferMiddleware, RequestBufferMiddleware } from './middleware';
 export { OrbitEcho } from './OrbitEcho';

package/dist/index.js

@@ -26,9 +26,11 @@ export {
   GitHubProvider,
   GenericProvider,
   EchoMetrics,
+  EchoErrorCodes,
+  EchoError,
   ConsoleEchoLogger,
   CircuitBreaker,
   BaseProvider
 };
 
-//# debugId=AEF7E6966FAD4D5C64756E2164756E21
+//# debugId=FCA02EA2A4A7000964756E2164756E21

package/dist/index.js.map

@@ -4,6 +4,6 @@
   "sourcesContent": [
   ],
   "mappings": "",
-  "debugId": "AEF7E6966FAD4D5C64756E2164756E21",
+  "debugId": "FCA02EA2A4A7000964756E2164756E21",
   "names": []
 }

package/dist/resilience/CircuitBreaker.d.ts

@@ -1,117 +1,6 @@
 /**
- * Implementation of the Circuit Breaker pattern.
- *
- * Protects downstream services from cascading failures by monitoring error rates
- * and temporarily "tripping" the circuit when thresholds are exceeded. This
- * prevents unnecessary load on struggling services and allows them time to recover.
- *
+ * Circuit Breaker — re-exported from @gravito/resilience (canonical implementation).
+ * Per D-01: echo's duplicate CB is replaced with re-exports from @gravito/resilience.
  * @module @gravito/echo/resilience
- * @since 1.1.0
  */
-import type { CircuitBreakerConfig, CircuitBreakerMetrics, CircuitBreakerState } from '../types';
-/**
- * State machine for managing downstream service availability via the Circuit Breaker pattern.
- *
- * This implementation tracks failures and successes to determine one of three states:
- * - `CLOSED`: Healthy state. All requests are executed normally.
- * - `OPEN`: Failing state. Trip thresholds exceeded; requests are rejected immediately to
- *   prevent cascading failure and give the target system time to recover.
- * - `HALF_OPEN`: Recovery phase. Allows a limited number of test requests to determine
- *   if the downstream service has restored functionality.
- *
- * @example Protecting a fragile API call
- * ```typescript
- * const breaker = new CircuitBreaker('inventory-service', {
- *   failureThreshold: 5,
- *   openTimeout: 60000 // Stay open for 1 minute before testing recovery
- * });
- *
- * try {
- *   const stock = await breaker.execute(async () => {
- *     return await apiClient.getInventory();
- *   });
- * } catch (error) {
- *   if (error.message.includes('Circuit breaker is OPEN')) {
- *     // Redirect to fallback or return cached data
- *   }
- * }
- * ```
- *
- * @public
- */
-export declare class CircuitBreaker {
-    private readonly name;
-    private state;
-    private failures;
-    private successes;
-    private lastFailureAt?;
-    private lastSuccessAt?;
-    private openedAt?;
-    private halfOpenAttempts;
-    private config;
-    /**
-     * Constructs a new CircuitBreaker for a specific resource, host, or service.
-     *
-     * @param name - A semantic identifier for the target being protected.
-     * @param config - Policy settings for failure thresholds, recovery timeouts, and callbacks.
-     */
-    constructor(name: string, config?: CircuitBreakerConfig);
-    /**
-     * Executes an asynchronous operation within the safety window of the circuit breaker.
-     *
-     * This method will proactively check the circuit state. If the state is `OPEN`, it will
-     * throw an error immediately without invoking the provided function.
-     *
-     * @param fn - The asynchronous operation to be protected.
-     * @returns A promise resolving to the result of the protected operation.
-     * @throws {Error} If the circuit is currently `OPEN` or if the underlying operation fails.
-     */
-    execute<T>(fn: () => Promise<T>): Promise<T>;
-    /**
-     * Records a successful operation and updates the state machine.
-     * In `HALF_OPEN` state, this contributes to the success threshold for closing the circuit.
-     */
-    private onSuccess;
-    /**
-     * Records a failed operation and determines if the circuit should trip to `OPEN`.
-     * Any failure in `HALF_OPEN` state immediately trips the circuit back to `OPEN`.
-     */
-    private onFailure;
-    /**
-     * Evaluates and performs automatic state transitions based on elapsed time and thresholds.
-     */
-    private checkStateTransition;
-    /**
-     * Transitions the circuit to a new state and executes configured lifecycle callbacks.
-     *
-     * @param newState - The target state to transition into.
-     */
-    private transitionTo;
-    /**
-     * Resets all internal counters and timers to their initial baseline state.
-     */
-    private reset;
-    /**
-     * Retrieves a snapshot of the current health and performance metrics of the circuit.
-     *
-     * @returns An object containing state, failure counts, and activity timestamps.
-     */
-    getMetrics(): CircuitBreakerMetrics;
-    /**
-     * Forcefully resets the circuit breaker to the `CLOSED` state.
-     * Useful for manual recovery scenarios after a service has been verified healthy.
-     */
-    manualReset(): void;
-    /**
-     * Returns the current operational state of the circuit breaker.
-     *
-     * @returns The current state identifier.
-     */
-    getState(): CircuitBreakerState;
-    /**
-     * Returns the semantic name assigned to this circuit breaker instance.
-     *
-     * @returns The name identifier.
-     */
-    getName(): string;
-}
+export { CircuitBreaker, CircuitBreakerState, type CircuitBreakerOptions, type CircuitBreakerMetrics, type CircuitBreakerMetricsRecorder, } from '@gravito/resilience';

package/dist/resilience/index.d.ts

@@ -6,5 +6,6 @@
  * @module @gravito/echo/resilience
  * @since v1.1
  */
-export type { CircuitBreakerConfig, CircuitBreakerMetrics, CircuitBreakerState } from '../types';
+export type { CircuitBreakerConfig, CircuitBreakerMetrics } from '../types';
+export { CircuitBreakerState } from '../types';
 export { CircuitBreaker } from './CircuitBreaker';

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { CircuitBreakerState } from '@gravito/resilience';
 import type { DeadLetterQueue } from './dlq/DeadLetterQueue';
 import type { EchoLogger } from './observability/logging';
 import type { MetricsProvider } from './observability/metrics';
@@ -235,6 +236,7 @@ export interface RequestBufferConfig {
 }
 /**
  * The current operational state of a circuit breaker.
+ * Re-exported from @gravito/resilience (canonical source per D-01).
  *
  * - `CLOSED`: Healthy state, allowing all requests through.
  * - `OPEN`: Failing state, blocking all requests to prevent cascading failure.
@@ -242,7 +244,7 @@ export interface RequestBufferConfig {
  *
  * @public
  */
-export type CircuitBreakerState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+export { CircuitBreakerState } from '@gravito/resilience';
 /**
  * Resilience configuration for outgoing webhook delivery.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gravito/echo",
   "sideEffects": false,
-  "version": "3.1.2",
+  "version": "4.0.0",
   "description": "Enterprise-grade webhook handling for Gravito. Secure receiving and reliable sending.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,7 +26,8 @@
     "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
     "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
-    "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts"
+    "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "publint": "publint"
   },
   "keywords": [
     "gravito",
@@ -45,10 +46,12 @@
   },
   "homepage": "https://github.com/gravito-framework/gravito#readme",
   "peerDependencies": {
-    "@gravito/core": "^2.0.0"
+    "@gravito/core": "^3.0.0",
+    "@gravito/resilience": "workspace:*"
   },
   "devDependencies": {
     "@gravito/core": "workspace:*",
+    "@gravito/resilience": "workspace:*",
     "bun-types": "latest",
     "typescript": "^5.9.3"
   },