@eusilvio/cep-lookup 2.4.0 → 2.6.0

package/dist/src/providers/opencep.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openCepProvider = void 0;
+/**
+ * @const {Provider} openCepProvider
+ * @description Provider for the OpenCEP service.
+ * @property {string} name - "OpenCEP".
+ * @property {(cep: string) => string} buildUrl - Constructs the URL for OpenCEP API.
+ * @property {(response: any) => Address} transform - Transforms OpenCEP's response into a standardized `Address` object.
+ * @throws {Error} If OpenCEP response indicates an error.
+ */
+exports.openCepProvider = {
+    name: "OpenCEP",
+    buildUrl: (cep) => `https://opencep.com/v1/${cep}`,
+    transform: (response) => {
+        if (!response || response.error) {
+            throw new Error("CEP not found");
+        }
+        // OpenCEP returns status code 404 for not found, which fetcher catches.
+        // But sometimes APIs return 200 with error data.
+        // Assuming standard JSON return based on description.
+        return {
+            cep: (response.cep || "").replace("-", ""),
+            state: response.uf || "",
+            city: response.localidade || "",
+            neighborhood: response.bairro || "",
+            street: response.logradouro || "",
+            service: "OpenCEP",
+            ibge: response.ibge || undefined,
+        };
+    },
+};

package/dist/src/providers/viacep.js

@@ -23,6 +23,8 @@ exports.viaCepProvider = {
             neighborhood: response.bairro || "",
             street: response.logradouro || "",
             service: "ViaCEP",
+            ibge: response.ibge || undefined,
+            ddd: response.ddd || undefined,
         };
     },
 };

package/dist/src/types.d.ts

@@ -10,6 +10,8 @@ export interface Address {
     neighborhood: string;
     street: string;
     service: string;
+    ibge?: string;
+    ddd?: string;
 }
 /**
  * @interface Provider
@@ -44,14 +46,24 @@ export interface CepLookupOptions {
     cache?: Cache;
     rateLimit?: RateLimitOptions;
     staggerDelay?: number;
+    /** Number of retries after all providers fail. Default: 0 */
+    retries?: number;
+    /** Base delay in ms between retries (exponential backoff). Default: 1000 */
+    retryDelay?: number;
+    /** Optional logger for debug output */
+    logger?: {
+        debug: (msg: string, data?: Record<string, unknown>) => void;
+    };
+    /** Circuit breaker options for provider resilience */
+    circuitBreaker?: CircuitBreakerOptions;
 }
 /**
  * @interface BulkCepResult
  * @description Represents the result for a single CEP in a bulk lookup operation.
  */
-export interface BulkCepResult {
+export interface BulkCepResult<T = Address> {
     cep: string;
-    data: Address | null;
+    data: T | null;
     provider?: string;
     error?: Error;
 }
@@ -77,3 +89,30 @@ export interface EventMap {
     'cache:hit': CacheHitPayload;
 }
 export type EventListener<T extends EventName> = (payload: EventMap[T]) => void;
+export interface CircuitBreakerOptions {
+    /** Consecutive failures required to open the circuit. Default: 3 */
+    failureThreshold?: number;
+    /** Cooldown in ms before trying a provider again. Default: 30000 */
+    cooldownMs?: number;
+    /** Enable/disable circuit breaker. Default: true */
+    enabled?: boolean;
+}
+export interface ProviderHealth {
+    provider: string;
+    score: number;
+    isOpen: boolean;
+    openUntil?: number;
+    consecutiveFailures: number;
+    successCount: number;
+    failureCount: number;
+    avgLatencyMs: number;
+}
+export interface ProviderMetrics {
+    provider: string;
+    requests: number;
+    successes: number;
+    failures: number;
+    timeoutErrors: number;
+    notFoundErrors: number;
+    avgLatencyMs: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eusilvio/cep-lookup",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "A agnostic, performant and flexible CEP lookup library with race strategy and caching.",
   "license": "MIT",
   "author": "Silvio Souza",
@@ -34,7 +34,8 @@
   "scripts": {
     "clean": "rm -rf dist tsconfig.tsbuildinfo",
     "build": "npm run clean && tsc --emitDeclarationOnly --outDir dist && esbuild src/index.ts src/providers/index.ts --bundle --platform=neutral --format=cjs --outdir=dist --out-extension:.js=.cjs --minify && esbuild src/index.ts src/providers/index.ts --bundle --platform=neutral --format=esm --outdir=dist --out-extension:.js=.mjs --minify",
-    "test": "jest"
+    "test": "jest",
+    "test:html": "npx http-server . -o examples/index.html -c-1"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",