@eusilvio/zip-lookup 2.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Silvio Campos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# @eusilvio/zip-lookup
+
+[![NPM Version](https://img.shields.io/npm/v/@eusilvio/zip-lookup.svg)](https://www.npmjs.com/package/@eusilvio/zip-lookup)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/eusilvio/cep-lookup/ci.yml)](https://github.com/eusilvio/cep-lookup/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+US ZIP code lookup engine with multi-provider race, resilience controls, and metrics.
+
+## Installation
+
+```bash
+npm install @eusilvio/zip-lookup
+```
+
+## Features
+
+- Multi-provider race strategy.
+- Cache and rate limiting.
+- Retry with exponential backoff.
+- Standardized errors with error codes.
+- Circuit breaker per provider.
+- Provider health score and runtime metrics.
+- Event-based observability.
+
+## Basic Usage
+
+```ts
+import { ZipLookup } from "@eusilvio/zip-lookup";
+import { zippopotamProvider } from "@eusilvio/zip-lookup/providers";
+
+const lookup = new ZipLookup({
+  providers: [zippopotamProvider],
+});
+
+const address = await lookup.lookup("90210");
+console.log(address);
+// {
+//   zip: "90210",
+//   city: "Beverly Hills",
+//   state: "California",
+//   stateAbbr: "CA",
+//   country: "United States",
+//   latitude: "34.0901",
+//   longitude: "-118.4065",
+//   service: "Zippopotam"
+// }
+```
+
+## Providers
+
+### Free (no API key)
+
+```ts
+import { zippopotamProvider } from "@eusilvio/zip-lookup/providers";
+```
+
+### ZipCodeStack (free tier, API key required)
+
+Sign up at [zipcodestack.com](https://zipcodestack.com). Returns county and timezone in addition to city/state.
+
+```ts
+import { createZipcodestackProvider } from "@eusilvio/zip-lookup/providers";
+
+const provider = createZipcodestackProvider("YOUR_API_KEY");
+```
+
+### USPS Web Tools (free, API key required)
+
+Register at [usps.com/business/web-tools-apis](https://www.usps.com/business/web-tools-apis/). Returns city and state only.
+
+```ts
+import { createUspsProvider } from "@eusilvio/zip-lookup/providers";
+
+const provider = createUspsProvider("YOUR_USPS_USERID");
+```
+
+## Multiple Providers (race strategy)
+
+```ts
+import { ZipLookup } from "@eusilvio/zip-lookup";
+import {
+  zippopotamProvider,
+  createZipcodestackProvider,
+  createUspsProvider,
+} from "@eusilvio/zip-lookup/providers";
+
+const lookup = new ZipLookup({
+  providers: [
+    zippopotamProvider,
+    createZipcodestackProvider("YOUR_API_KEY"),
+    createUspsProvider("YOUR_USPS_USERID"),
+  ],
+  staggerDelay: 100, // ms before backup providers are triggered
+});
+```
+
+## ZIP Code Formats
+
+All of the following are accepted and normalized to 5 digits internally:
+
+```ts
+await lookup.lookup("10001");         // 5-digit
+await lookup.lookup("10001-1234");    // ZIP+4 with hyphen
+await lookup.lookup("100011234");     // ZIP+4 without hyphen
+```
+
+## Error Handling
+
+```ts
+import {
+  ZipLookup,
+  ZipValidationError,
+  ZipNotFoundError,
+  ProviderTimeoutError,
+  RateLimitError,
+  AllProvidersFailedError,
+} from "@eusilvio/zip-lookup";
+
+try {
+  await lookup.lookup("99999");
+} catch (error) {
+  if (error instanceof ZipValidationError) {
+    console.log(error.code); // INVALID_ZIP
+  } else if (error instanceof ZipNotFoundError) {
+    console.log(error.code); // NOT_FOUND
+  } else if (error instanceof ProviderTimeoutError) {
+    console.log(error.code); // TIMEOUT
+  } else if (error instanceof RateLimitError) {
+    console.log(error.code); // RATE_LIMITED
+  } else if (error instanceof AllProvidersFailedError) {
+    console.log(error.code); // ALL_PROVIDERS_FAILED
+  }
+}
+```
+
+## Cache
+
+```ts
+import { ZipLookup, InMemoryCache } from "@eusilvio/zip-lookup";
+
+const lookup = new ZipLookup({
+  providers: [zippopotamProvider],
+  cache: new InMemoryCache({ ttl: 60_000, maxSize: 500 }),
+});
+```
+
+## Rate Limiting
+
+```ts
+const lookup = new ZipLookup({
+  providers: [zippopotamProvider],
+  rateLimit: { requests: 10, per: 1000 }, // 10 req/s
+});
+```
+
+## Circuit Breaker
+
+```ts
+const lookup = new ZipLookup({
+  providers: [zippopotamProvider],
+  circuitBreaker: {
+    enabled: true,
+    failureThreshold: 3,
+    cooldownMs: 30_000,
+  },
+});
+```
+
+## Warmup
+
+Pings all providers and sorts them by latency. Useful to call on input focus.
+
+```ts
+await lookup.warmup();
+```
+
+## Health and Metrics
+
+```ts
+const health = lookup.getProviderHealth();
+// [{ provider: "Zippopotam", score: 0.96, isOpen: false, avgLatencyMs: 48.2, ... }]
+
+const metrics = lookup.getProviderMetrics();
+// [{ provider: "Zippopotam", requests: 5, successes: 5, failures: 0, ... }]
+```
+
+## Bulk Lookup
+
+```ts
+const results = await lookup.lookupZips(["10001", "90210", "60601"], 3);
+// [{ zip, data, provider }, { zip, data: null, error }, ...]
+```
+
+## Custom Mapper
+
+```ts
+const city = await lookup.lookup("10001", (addr) => addr.city);
+// "New York City"
+```
+
+## Events
+
+```ts
+lookup.on("success", ({ provider, zip, duration, address }) => { ... });
+lookup.on("failure", ({ provider, zip, duration, error }) => { ... });
+lookup.on("cache:hit", ({ zip }) => { ... });
+
+lookup.off("success", listener);
+```
+
+## API Summary
+
+### `new ZipLookup(options)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `providers` | `ZipProvider[]` | required | Provider list |
+| `fetcher` | `Fetcher` | `fetch` | Custom HTTP function |
+| `cache` | `ZipCache` | — | Cache implementation |
+| `rateLimit` | `{ requests, per }` | — | Rate limit window |
+| `staggerDelay` | `number` | `100` | ms before backup providers fire |
+| `retries` | `number` | `0` | Retry count after all fail |
+| `retryDelay` | `number` | `1000` | Base retry delay (exponential) |
+| `circuitBreaker` | `CircuitBreakerOptions` | enabled | Resilience per provider |
+| `logger` | `{ debug }` | — | Debug logger |
+
+### Methods
+
+- `lookup(zip, mapper?): Promise<ZipAddress>`
+- `lookupZips(zips, concurrency?, mapper?): Promise<BulkZipResult[]>`
+- `warmup(): Promise<ZipProvider[]>`
+- `getProviderHealth(): ProviderHealth[]`
+- `getProviderMetrics(): ProviderMetrics[]`
+- `on(event, listener)` / `off(event, listener)`
+
+## Custom Provider
+
+```ts
+import type { ZipProvider } from "@eusilvio/zip-lookup";
+
+const myProvider: ZipProvider = {
+  name: "MyProvider",
+  timeout: 3000,
+  buildUrl: (zip) => `https://my-api.example.com/zip/${zip}`,
+  transform: (response) => ({
+    zip: response.postal_code,
+    city: response.city,
+    state: response.state_name,
+    stateAbbr: response.state_code,
+    country: "United States",
+    service: "MyProvider",
+  }),
+};
+```
+
+## Compatibility
+
+- Node.js: `20.x`, `22.x`, `24.x`
+- Works in browser environments that support `fetch`
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var Z=Object.defineProperty;var z=Object.getOwnPropertyDescriptor;var U=Object.getOwnPropertyNames;var B=Object.prototype.hasOwnProperty;var q=(s,e)=>{for(var t in e)Z(s,t,{get:e[t],enumerable:!0})},_=(s,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of U(e))!B.call(s,i)&&i!==t&&Z(s,i,{get:()=>e[i],enumerable:!(r=z(e,i))||r.enumerable});return s};var V=s=>_(Z({},"__esModule",{value:!0}),s);var K={};q(K,{AllProvidersFailedError:()=>v,InMemoryCache:()=>C,ProviderTimeoutError:()=>p,ProviderUnavailableError:()=>P,RateLimitError:()=>E,ZipLookup:()=>F,ZipNotFoundError:()=>y,ZipValidationError:()=>g});module.exports=V(K);var C=class{constructor(e){this.cache=new Map;this.ttl=e?.ttl??1/0,this.maxSize=e?.maxSize??1/0}get(e){let t=this.cache.get(e);if(t){if(this.ttl!==1/0&&Date.now()-t.timestamp>this.ttl){this.cache.delete(e);return}return t.value}}set(e,t){if(this.cache.has(e)&&this.cache.delete(e),this.cache.size>=this.maxSize){let r=this.cache.keys().next().value;r!==void 0&&this.cache.delete(r)}this.cache.set(e,{value:t,timestamp:Date.now()})}delete(e){this.cache.delete(e)}has(e){if(!this.cache.has(e))return!1;let t=this.cache.get(e);return this.ttl!==1/0&&Date.now()-t.timestamp>this.ttl?(this.cache.delete(e),!1):!0}clear(){this.cache.clear()}};var g=class extends Error{constructor(t){super("Invalid ZIP code format. Use NNNNN or NNNNN-NNNN.");this.code="INVALID_ZIP";this.name="ZipValidationError",this.zip=t}},E=class extends Error{constructor(t,r){super(`Rate limit exceeded: ${t} requests per ${r}ms.`);this.code="RATE_LIMITED";this.name="RateLimitError",this.limit=t,this.window=r}},p=class extends Error{constructor(t,r){super(`Timeout from ${t}`);this.code="TIMEOUT";this.name="ProviderTimeoutError",this.provider=t,this.timeout=r}},y=class extends Error{constructor(t,r){super("ZIP code not found");this.code="NOT_FOUND";this.name="ZipNotFoundError",this.zip=t,this.provider=r}},v=class extends Error{constructor(t){super("All providers failed to resolve the ZIP code.");this.code="ALL_PROVIDERS_FAILED";this.name="AllProvidersFailedError",this.errors=t}},P=class extends Error{constructor(t){super(`Provider ${t} is temporarily unavailable (circuit open).`);this.code="PROVIDER_UNAVAILABLE";this.name="ProviderUnavailableError",this.provider=t}};function M(s,e,t){if(s instanceof Error){if(s instanceof g||s instanceof E||s instanceof p||s instanceof y||s instanceof P||s instanceof v)return s;let r=s.message?.toLowerCase?.()||"";return r.includes("zip not found")||r.includes("not found")||r.includes("status: 404")?new y(e,t):(s.name==="AbortError",s)}return new Error(String(s))}var x=class{constructor(){this.listeners={}}on(e,t){this.listeners[e]||(this.listeners[e]=[]),this.listeners[e].push(t)}off(e,t){let r=this.listeners[e];r&&(this.listeners[e]=r.filter(i=>i!==t))}emit(e,t){let r=this.listeners[e];r&&r.forEach(i=>i(t))}};function H(s){if(!/^(\d{5}-\d{4}|\d{9}|\d{5})$/.test(s))throw new g(s);return s.replace("-","").slice(0,5)}function $(s){let e={...s};return Object.keys(e).forEach(t=>{let r=e[t];typeof r=="string"&&(e[t]=r.trim())}),e}var F=class{constructor(e){this.requestTimestamps=[];this.providerState=new Map;this.providers=e.providers,this.sortedProviders=[...e.providers],this.emitter=new x,this.fetcher=e.fetcher||(async(t,r)=>{let i=await fetch(t,{signal:r});if(!i.ok)throw new Error(`HTTP error! status: ${i.status}`);return i.json()}),this.cache=e.cache,this.rateLimit=e.rateLimit,this.staggerDelay=e.staggerDelay??100,this.retries=e.retries??0,this.retryDelay=e.retryDelay??1e3,this.logger=e.logger,this.circuitBreakerEnabled=e.circuitBreaker?.enabled??!0,this.circuitFailureThreshold=e.circuitBreaker?.failureThreshold??3,this.circuitCooldownMs=e.circuitBreaker?.cooldownMs??3e4,this.providers.forEach(t=>{this.providerState.set(t.name,{consecutiveFailures:0,successCount:0,failureCount:0,avgLatencyMs:0,requests:0,timeoutErrors:0,notFoundErrors:0})})}log(e,t){this.logger?.debug(e,t)}on(e,t){this.emitter.on(e,t)}off(e,t){this.emitter.off(e,t)}async warmup(){let e="10001",t=new AbortController,r=this.providers.map(async o=>{let a=Date.now();try{let d=o.buildUrl(e);return await(o.fetcher||this.fetcher)(d,t.signal),{provider:o,duration:Date.now()-a,error:!1}}catch{return{provider:o,duration:1/0,error:!0}}}),c=(await Promise.all(r)).sort((o,a)=>o.duration-a.duration);return this.sortedProviders=c.map(o=>o.provider).filter(o=>!!o),t.abort(),this.sortedProviders}getOrCreateProviderState(e){let t=this.providerState.get(e);if(t)return t;let r={consecutiveFailures:0,successCount:0,failureCount:0,avgLatencyMs:0,requests:0,timeoutErrors:0,notFoundErrors:0};return this.providerState.set(e,r),r}recordProviderSuccess(e,t){let r=this.getOrCreateProviderState(e);r.requests+=1,r.successCount+=1,r.consecutiveFailures=0;let i=r.successCount+r.failureCount;r.avgLatencyMs=i===1?t:(r.avgLatencyMs*(i-1)+t)/i,r.openUntil=void 0}recordProviderFailure(e,t,r){let i=this.getOrCreateProviderState(e);i.requests+=1,i.failureCount+=1,i.consecutiveFailures+=1;let c=i.successCount+i.failureCount;i.avgLatencyMs=c===1?t:(i.avgLatencyMs*(c-1)+t)/c,r instanceof p&&(i.timeoutErrors+=1),r instanceof y&&(i.notFoundErrors+=1),this.circuitBreakerEnabled&&i.consecutiveFailures>=this.circuitFailureThreshold&&(i.openUntil=Date.now()+this.circuitCooldownMs)}isProviderOpen(e){if(!this.circuitBreakerEnabled)return!1;let t=this.getOrCreateProviderState(e);return t.openUntil?Date.now()>=t.openUntil?(t.openUntil=void 0,t.consecutiveFailures=0,!1):!0:!1}scoreProvider(e){let t=this.getOrCreateProviderState(e.name),r=t.successCount+t.failureCount,i=r===0?1:t.successCount/r,c=t.avgLatencyMs>0?Math.min(t.avgLatencyMs/1e3,1):0,o=this.isProviderOpen(e.name)?1:0;return i*.8+(1-c)*.2-o}getProviderHealth(){return this.providers.map(e=>{let t=this.getOrCreateProviderState(e.name);return{provider:e.name,score:Number(this.scoreProvider(e).toFixed(4)),isOpen:this.isProviderOpen(e.name),openUntil:t.openUntil,consecutiveFailures:t.consecutiveFailures,successCount:t.successCount,failureCount:t.failureCount,avgLatencyMs:Number(t.avgLatencyMs.toFixed(2))}}).sort((e,t)=>t.score-e.score)}getProviderMetrics(){return this.providers.map(e=>{let t=this.getOrCreateProviderState(e.name);return{provider:e.name,requests:t.requests,successes:t.successCount,failures:t.failureCount,timeoutErrors:t.timeoutErrors,notFoundErrors:t.notFoundErrors,avgLatencyMs:Number(t.avgLatencyMs.toFixed(2))}})}checkRateLimit(){if(!this.rateLimit)return;let e=Date.now(),t=e-this.rateLimit.per;if(this.requestTimestamps=this.requestTimestamps.filter(r=>r>t),this.requestTimestamps.length>=this.rateLimit.requests)throw new E(this.rateLimit.requests,this.rateLimit.per);this.requestTimestamps.push(e)}async lookup(e,t){this.checkRateLimit();let r=H(e);if(this.log("lookup:start",{zip:r}),this.cache){let o=this.cache.get(r);if(o)return this.log("cache:hit",{zip:r}),this.emitter.emit("cache:hit",{zip:r}),t?t(o):o}let i,c=1+this.retries;for(let o=0;o<c;o++){if(o>0){let a=this.retryDelay*Math.pow(2,o-1);this.log("retry:attempt",{attempt:o,zip:r,delay:a}),await new Promise(d=>setTimeout(d,a))}try{return await this._lookupFromProviders(r,t)}catch(a){if(a instanceof g||a instanceof E)throw a;i=a}}throw i}async _lookupFromProviders(e,t){let r=new AbortController,{signal:i}=r,c=this.sortedProviders.filter(n=>!this.isProviderOpen(n.name)),o=[...c].sort((n,l)=>this.scoreProvider(l)-this.scoreProvider(n)),a=o.length>0?o:[...this.sortedProviders].sort((n,l)=>this.scoreProvider(l)-this.scoreProvider(n));if(a.length===0)throw new v([new P("all")]);if(c.length===0&&this.circuitBreakerEnabled)throw new v(a.map(n=>new P(n.name)));let d=n=>{let l=Date.now(),A=n.buildUrl(e),D=n.fetcher||this.fetcher;this.log("provider:start",{provider:n.name,zip:e});let R=new Promise((b,m)=>{if(!n.timeout)return;let u=setTimeout(()=>{i.removeEventListener("abort",O);let I=Date.now()-l,L=new p(n.name,n.timeout);this.recordProviderFailure(n.name,I,L),this.log("provider:failure",{provider:n.name,zip:e,error:L.message}),this.emitter.emit("failure",{provider:n.name,zip:e,duration:I,error:L}),m(L)},n.timeout),O=()=>clearTimeout(u);i.addEventListener("abort",O,{once:!0})}),S=D(A,i).then(b=>n.transform(b)).then(b=>{let m=Date.now()-l,u=$(b);return this.recordProviderSuccess(n.name,m),this.log("provider:success",{provider:n.name,zip:e,duration:m}),this.emitter.emit("success",{provider:n.name,zip:e,duration:m,address:u}),this.cache&&this.cache.set(e,u),t?t(u):u}).catch(b=>{let m=Date.now()-l,u=M(b,e,n.name);throw u.name!=="AbortError"&&!(u instanceof p)&&(this.recordProviderFailure(n.name,m,u),this.log("provider:failure",{provider:n.name,zip:e,error:u.message}),this.emitter.emit("failure",{provider:n.name,zip:e,duration:m,error:u})),u});return Promise.race([S,R])},f=a[0],h=a.slice(1);if(h.length===0)try{return await d(f)}finally{r.abort()}let w=null,T=null,N=new Promise((n,l)=>{T=()=>{if(w&&clearTimeout(w),i.aborted)return;let A=h.map(d);Promise.any(A).then(n).catch(l)},w=setTimeout(T,this.staggerDelay)}),k=d(f).catch(n=>{throw T&&T(),n});try{return await Promise.any([k,N])}catch(n){let l=n.errors||[n];throw new v(l)}finally{w&&clearTimeout(w),r.abort()}}async lookupZips(e,t=5,r){if(!e||e.length===0)return[];let i=new Array(e.length),c=0,o=async()=>{for(;c<e.length;){let d=c++;if(d>=e.length)break;let f=e[d];try{let h=await this.lookup(f);if(h)i[d]={zip:f,data:r?r(h):h,provider:h.service};else throw new Error("No address found")}catch(h){i[d]={zip:f,data:null,error:h}}}},a=Array.from({length:Math.min(t,e.length)},()=>o());return await Promise.all(a),i.filter(Boolean)}};

package/dist/index.mjs

@@ -0,0 +1 @@
+var A=class{constructor(e){this.cache=new Map;this.ttl=e?.ttl??1/0,this.maxSize=e?.maxSize??1/0}get(e){let t=this.cache.get(e);if(t){if(this.ttl!==1/0&&Date.now()-t.timestamp>this.ttl){this.cache.delete(e);return}return t.value}}set(e,t){if(this.cache.has(e)&&this.cache.delete(e),this.cache.size>=this.maxSize){let r=this.cache.keys().next().value;r!==void 0&&this.cache.delete(r)}this.cache.set(e,{value:t,timestamp:Date.now()})}delete(e){this.cache.delete(e)}has(e){if(!this.cache.has(e))return!1;let t=this.cache.get(e);return this.ttl!==1/0&&Date.now()-t.timestamp>this.ttl?(this.cache.delete(e),!1):!0}clear(){this.cache.clear()}};var E=class extends Error{constructor(t){super("Invalid ZIP code format. Use NNNNN or NNNNN-NNNN.");this.code="INVALID_ZIP";this.name="ZipValidationError",this.zip=t}},y=class extends Error{constructor(t,r){super(`Rate limit exceeded: ${t} requests per ${r}ms.`);this.code="RATE_LIMITED";this.name="RateLimitError",this.limit=t,this.window=r}},v=class extends Error{constructor(t,r){super(`Timeout from ${t}`);this.code="TIMEOUT";this.name="ProviderTimeoutError",this.provider=t,this.timeout=r}},P=class extends Error{constructor(t,r){super("ZIP code not found");this.code="NOT_FOUND";this.name="ZipNotFoundError",this.zip=t,this.provider=r}},f=class extends Error{constructor(t){super("All providers failed to resolve the ZIP code.");this.code="ALL_PROVIDERS_FAILED";this.name="AllProvidersFailedError",this.errors=t}},b=class extends Error{constructor(t){super(`Provider ${t} is temporarily unavailable (circuit open).`);this.code="PROVIDER_UNAVAILABLE";this.name="ProviderUnavailableError",this.provider=t}};function O(n,e,t){if(n instanceof Error){if(n instanceof E||n instanceof y||n instanceof v||n instanceof P||n instanceof b||n instanceof f)return n;let r=n.message?.toLowerCase?.()||"";return r.includes("zip not found")||r.includes("not found")||r.includes("status: 404")?new P(e,t):(n.name==="AbortError",n)}return new Error(String(n))}var Z=class{constructor(){this.listeners={}}on(e,t){this.listeners[e]||(this.listeners[e]=[]),this.listeners[e].push(t)}off(e,t){let r=this.listeners[e];r&&(this.listeners[e]=r.filter(i=>i!==t))}emit(e,t){let r=this.listeners[e];r&&r.forEach(i=>i(t))}};function S(n){if(!/^(\d{5}-\d{4}|\d{9}|\d{5})$/.test(n))throw new E(n);return n.replace("-","").slice(0,5)}function z(n){let e={...n};return Object.keys(e).forEach(t=>{let r=e[t];typeof r=="string"&&(e[t]=r.trim())}),e}var I=class{constructor(e){this.requestTimestamps=[];this.providerState=new Map;this.providers=e.providers,this.sortedProviders=[...e.providers],this.emitter=new Z,this.fetcher=e.fetcher||(async(t,r)=>{let i=await fetch(t,{signal:r});if(!i.ok)throw new Error(`HTTP error! status: ${i.status}`);return i.json()}),this.cache=e.cache,this.rateLimit=e.rateLimit,this.staggerDelay=e.staggerDelay??100,this.retries=e.retries??0,this.retryDelay=e.retryDelay??1e3,this.logger=e.logger,this.circuitBreakerEnabled=e.circuitBreaker?.enabled??!0,this.circuitFailureThreshold=e.circuitBreaker?.failureThreshold??3,this.circuitCooldownMs=e.circuitBreaker?.cooldownMs??3e4,this.providers.forEach(t=>{this.providerState.set(t.name,{consecutiveFailures:0,successCount:0,failureCount:0,avgLatencyMs:0,requests:0,timeoutErrors:0,notFoundErrors:0})})}log(e,t){this.logger?.debug(e,t)}on(e,t){this.emitter.on(e,t)}off(e,t){this.emitter.off(e,t)}async warmup(){let e="10001",t=new AbortController,r=this.providers.map(async o=>{let a=Date.now();try{let d=o.buildUrl(e);return await(o.fetcher||this.fetcher)(d,t.signal),{provider:o,duration:Date.now()-a,error:!1}}catch{return{provider:o,duration:1/0,error:!0}}}),c=(await Promise.all(r)).sort((o,a)=>o.duration-a.duration);return this.sortedProviders=c.map(o=>o.provider).filter(o=>!!o),t.abort(),this.sortedProviders}getOrCreateProviderState(e){let t=this.providerState.get(e);if(t)return t;let r={consecutiveFailures:0,successCount:0,failureCount:0,avgLatencyMs:0,requests:0,timeoutErrors:0,notFoundErrors:0};return this.providerState.set(e,r),r}recordProviderSuccess(e,t){let r=this.getOrCreateProviderState(e);r.requests+=1,r.successCount+=1,r.consecutiveFailures=0;let i=r.successCount+r.failureCount;r.avgLatencyMs=i===1?t:(r.avgLatencyMs*(i-1)+t)/i,r.openUntil=void 0}recordProviderFailure(e,t,r){let i=this.getOrCreateProviderState(e);i.requests+=1,i.failureCount+=1,i.consecutiveFailures+=1;let c=i.successCount+i.failureCount;i.avgLatencyMs=c===1?t:(i.avgLatencyMs*(c-1)+t)/c,r instanceof v&&(i.timeoutErrors+=1),r instanceof P&&(i.notFoundErrors+=1),this.circuitBreakerEnabled&&i.consecutiveFailures>=this.circuitFailureThreshold&&(i.openUntil=Date.now()+this.circuitCooldownMs)}isProviderOpen(e){if(!this.circuitBreakerEnabled)return!1;let t=this.getOrCreateProviderState(e);return t.openUntil?Date.now()>=t.openUntil?(t.openUntil=void 0,t.consecutiveFailures=0,!1):!0:!1}scoreProvider(e){let t=this.getOrCreateProviderState(e.name),r=t.successCount+t.failureCount,i=r===0?1:t.successCount/r,c=t.avgLatencyMs>0?Math.min(t.avgLatencyMs/1e3,1):0,o=this.isProviderOpen(e.name)?1:0;return i*.8+(1-c)*.2-o}getProviderHealth(){return this.providers.map(e=>{let t=this.getOrCreateProviderState(e.name);return{provider:e.name,score:Number(this.scoreProvider(e).toFixed(4)),isOpen:this.isProviderOpen(e.name),openUntil:t.openUntil,consecutiveFailures:t.consecutiveFailures,successCount:t.successCount,failureCount:t.failureCount,avgLatencyMs:Number(t.avgLatencyMs.toFixed(2))}}).sort((e,t)=>t.score-e.score)}getProviderMetrics(){return this.providers.map(e=>{let t=this.getOrCreateProviderState(e.name);return{provider:e.name,requests:t.requests,successes:t.successCount,failures:t.failureCount,timeoutErrors:t.timeoutErrors,notFoundErrors:t.notFoundErrors,avgLatencyMs:Number(t.avgLatencyMs.toFixed(2))}})}checkRateLimit(){if(!this.rateLimit)return;let e=Date.now(),t=e-this.rateLimit.per;if(this.requestTimestamps=this.requestTimestamps.filter(r=>r>t),this.requestTimestamps.length>=this.rateLimit.requests)throw new y(this.rateLimit.requests,this.rateLimit.per);this.requestTimestamps.push(e)}async lookup(e,t){this.checkRateLimit();let r=S(e);if(this.log("lookup:start",{zip:r}),this.cache){let o=this.cache.get(r);if(o)return this.log("cache:hit",{zip:r}),this.emitter.emit("cache:hit",{zip:r}),t?t(o):o}let i,c=1+this.retries;for(let o=0;o<c;o++){if(o>0){let a=this.retryDelay*Math.pow(2,o-1);this.log("retry:attempt",{attempt:o,zip:r,delay:a}),await new Promise(d=>setTimeout(d,a))}try{return await this._lookupFromProviders(r,t)}catch(a){if(a instanceof E||a instanceof y)throw a;i=a}}throw i}async _lookupFromProviders(e,t){let r=new AbortController,{signal:i}=r,c=this.sortedProviders.filter(s=>!this.isProviderOpen(s.name)),o=[...c].sort((s,l)=>this.scoreProvider(l)-this.scoreProvider(s)),a=o.length>0?o:[...this.sortedProviders].sort((s,l)=>this.scoreProvider(l)-this.scoreProvider(s));if(a.length===0)throw new f([new b("all")]);if(c.length===0&&this.circuitBreakerEnabled)throw new f(a.map(s=>new b(s.name)));let d=s=>{let l=Date.now(),C=s.buildUrl(e),k=s.fetcher||this.fetcher;this.log("provider:start",{provider:s.name,zip:e});let D=new Promise((g,m)=>{if(!s.timeout)return;let u=setTimeout(()=>{i.removeEventListener("abort",x);let F=Date.now()-l,L=new v(s.name,s.timeout);this.recordProviderFailure(s.name,F,L),this.log("provider:failure",{provider:s.name,zip:e,error:L.message}),this.emitter.emit("failure",{provider:s.name,zip:e,duration:F,error:L}),m(L)},s.timeout),x=()=>clearTimeout(u);i.addEventListener("abort",x,{once:!0})}),R=k(C,i).then(g=>s.transform(g)).then(g=>{let m=Date.now()-l,u=z(g);return this.recordProviderSuccess(s.name,m),this.log("provider:success",{provider:s.name,zip:e,duration:m}),this.emitter.emit("success",{provider:s.name,zip:e,duration:m,address:u}),this.cache&&this.cache.set(e,u),t?t(u):u}).catch(g=>{let m=Date.now()-l,u=O(g,e,s.name);throw u.name!=="AbortError"&&!(u instanceof v)&&(this.recordProviderFailure(s.name,m,u),this.log("provider:failure",{provider:s.name,zip:e,error:u.message}),this.emitter.emit("failure",{provider:s.name,zip:e,duration:m,error:u})),u});return Promise.race([R,D])},p=a[0],h=a.slice(1);if(h.length===0)try{return await d(p)}finally{r.abort()}let w=null,T=null,M=new Promise((s,l)=>{T=()=>{if(w&&clearTimeout(w),i.aborted)return;let C=h.map(d);Promise.any(C).then(s).catch(l)},w=setTimeout(T,this.staggerDelay)}),N=d(p).catch(s=>{throw T&&T(),s});try{return await Promise.any([N,M])}catch(s){let l=s.errors||[s];throw new f(l)}finally{w&&clearTimeout(w),r.abort()}}async lookupZips(e,t=5,r){if(!e||e.length===0)return[];let i=new Array(e.length),c=0,o=async()=>{for(;c<e.length;){let d=c++;if(d>=e.length)break;let p=e[d];try{let h=await this.lookup(p);if(h)i[d]={zip:p,data:r?r(h):h,provider:h.service};else throw new Error("No address found")}catch(h){i[d]={zip:p,data:null,error:h}}}},a=Array.from({length:Math.min(t,e.length)},()=>o());return await Promise.all(a),i.filter(Boolean)}};export{f as AllProvidersFailedError,A as InMemoryCache,v as ProviderTimeoutError,b as ProviderUnavailableError,y as RateLimitError,I as ZipLookup,P as ZipNotFoundError,E as ZipValidationError};

package/dist/providers/index.cjs

@@ -0,0 +1 @@
+"use strict";var s=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var l=(e,t)=>{for(var r in t)s(e,r,{get:t[r],enumerable:!0})},h=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of p(t))!u.call(e,i)&&i!==r&&s(e,i,{get:()=>t[i],enumerable:!(o=c(t,i))||o.enumerable});return e};var m=e=>h(s({},"__esModule",{value:!0}),e);var P={};l(P,{createUspsProvider:()=>y,createZipcodestackProvider:()=>A,zippopotamPlusProvider:()=>g,zippopotamProvider:()=>f});module.exports=m(P);var f={name:"Zippopotam",buildUrl:e=>`https://api.zippopotam.us/us/${e}`,transform:e=>{if(!e||!e.places||e.places.length===0)throw new Error("ZIP not found");let t=e.places[0];return{zip:e["post code"]||"",city:t["place name"]||"",state:t.state||"",stateAbbr:t["state abbreviation"]||"",country:e.country||"United States",latitude:t.latitude||void 0,longitude:t.longitude||void 0,service:"Zippopotam"}}},g={name:"ZippopotamPlus",buildUrl:e=>`https://api.zippopotam.us/us/${e}`,transform:e=>{if(!e||!e.places||e.places.length===0)throw new Error("ZIP not found");let t=e.places[0];return{zip:e["post code"]||"",city:t["place name"]||"",state:t.state||"",stateAbbr:t["state abbreviation"]||"",country:e.country||"United States",latitude:t.latitude||void 0,longitude:t.longitude||void 0,service:"ZippopotamPlus"}}};function A(e){return{name:"ZipCodeStack",buildUrl:t=>`https://api.zipcodestack.com/v1/search?codes=${t}&country=us&apikey=${e}`,transform:t=>{if(!t||!t.results)throw new Error("ZIP not found");let r=Object.keys(t.results);if(r.length===0)throw new Error("ZIP not found");let o=t.results[r[0]];if(!o||o.length===0)throw new Error("ZIP not found");let i=o[0];return{zip:i.postal_code||r[0],city:i.city||"",state:i.state||"",stateAbbr:i.state_code||"",county:i.county||void 0,country:"United States",latitude:i.latitude!=null?String(i.latitude):void 0,longitude:i.longitude!=null?String(i.longitude):void 0,timezone:i.timezone||void 0,service:"ZipCodeStack"}}}}var Z={AL:"Alabama",AK:"Alaska",AZ:"Arizona",AR:"Arkansas",CA:"California",CO:"Colorado",CT:"Connecticut",DE:"Delaware",FL:"Florida",GA:"Georgia",HI:"Hawaii",ID:"Idaho",IL:"Illinois",IN:"Indiana",IA:"Iowa",KS:"Kansas",KY:"Kentucky",LA:"Louisiana",ME:"Maine",MD:"Maryland",MA:"Massachusetts",MI:"Michigan",MN:"Minnesota",MS:"Mississippi",MO:"Missouri",MT:"Montana",NE:"Nebraska",NV:"Nevada",NH:"New Hampshire",NJ:"New Jersey",NM:"New Mexico",NY:"New York",NC:"North Carolina",ND:"North Dakota",OH:"Ohio",OK:"Oklahoma",OR:"Oregon",PA:"Pennsylvania",RI:"Rhode Island",SC:"South Carolina",SD:"South Dakota",TN:"Tennessee",TX:"Texas",UT:"Utah",VT:"Vermont",VA:"Virginia",WA:"Washington",WV:"West Virginia",WI:"Wisconsin",WY:"Wyoming",DC:"District of Columbia",PR:"Puerto Rico",VI:"Virgin Islands",GU:"Guam",AS:"American Samoa",MP:"Northern Mariana Islands"};function a(e,t){let r=e.match(new RegExp(`<${t}[^>]*>([^<]*)<\\/${t}>`));return r?r[1].trim():void 0}function y(e){return{name:"USPS",fetcher:async(r,o)=>{let i=await fetch(r,{signal:o});if(!i.ok)throw new Error(`HTTP error! status: ${i.status}`);return i.text()},buildUrl:r=>{let o=`<CityStateLookupRequest USERID="${e}"><ZipCode ID="0"><Zip5>${r}</Zip5></ZipCode></CityStateLookupRequest>`;return`https://secure.shippingapis.com/ShippingAPI.dll?API=CityStateLookup&XML=${encodeURIComponent(o)}`},transform:r=>{let o=a(r,"Description");if(r.includes("<Error>")&&o)throw new Error(o);let i=a(r,"City"),n=a(r,"State"),d=a(r,"Zip5");if(!i||!n||!d)throw new Error("ZIP not found");return{zip:d,city:i.charAt(0)+i.slice(1).toLowerCase(),state:Z[n]||n,stateAbbr:n,country:"United States",service:"USPS"}}}}

package/dist/providers/index.mjs

@@ -0,0 +1 @@
+var c={name:"Zippopotam",buildUrl:t=>`https://api.zippopotam.us/us/${t}`,transform:t=>{if(!t||!t.places||t.places.length===0)throw new Error("ZIP not found");let e=t.places[0];return{zip:t["post code"]||"",city:e["place name"]||"",state:e.state||"",stateAbbr:e["state abbreviation"]||"",country:t.country||"United States",latitude:e.latitude||void 0,longitude:e.longitude||void 0,service:"Zippopotam"}}},p={name:"ZippopotamPlus",buildUrl:t=>`https://api.zippopotam.us/us/${t}`,transform:t=>{if(!t||!t.places||t.places.length===0)throw new Error("ZIP not found");let e=t.places[0];return{zip:t["post code"]||"",city:e["place name"]||"",state:e.state||"",stateAbbr:e["state abbreviation"]||"",country:t.country||"United States",latitude:e.latitude||void 0,longitude:e.longitude||void 0,service:"ZippopotamPlus"}}};function l(t){return{name:"ZipCodeStack",buildUrl:e=>`https://api.zipcodestack.com/v1/search?codes=${e}&country=us&apikey=${t}`,transform:e=>{if(!e||!e.results)throw new Error("ZIP not found");let r=Object.keys(e.results);if(r.length===0)throw new Error("ZIP not found");let o=e.results[r[0]];if(!o||o.length===0)throw new Error("ZIP not found");let i=o[0];return{zip:i.postal_code||r[0],city:i.city||"",state:i.state||"",stateAbbr:i.state_code||"",county:i.county||void 0,country:"United States",latitude:i.latitude!=null?String(i.latitude):void 0,longitude:i.longitude!=null?String(i.longitude):void 0,timezone:i.timezone||void 0,service:"ZipCodeStack"}}}}var d={AL:"Alabama",AK:"Alaska",AZ:"Arizona",AR:"Arkansas",CA:"California",CO:"Colorado",CT:"Connecticut",DE:"Delaware",FL:"Florida",GA:"Georgia",HI:"Hawaii",ID:"Idaho",IL:"Illinois",IN:"Indiana",IA:"Iowa",KS:"Kansas",KY:"Kentucky",LA:"Louisiana",ME:"Maine",MD:"Maryland",MA:"Massachusetts",MI:"Michigan",MN:"Minnesota",MS:"Mississippi",MO:"Missouri",MT:"Montana",NE:"Nebraska",NV:"Nevada",NH:"New Hampshire",NJ:"New Jersey",NM:"New Mexico",NY:"New York",NC:"North Carolina",ND:"North Dakota",OH:"Ohio",OK:"Oklahoma",OR:"Oregon",PA:"Pennsylvania",RI:"Rhode Island",SC:"South Carolina",SD:"South Dakota",TN:"Tennessee",TX:"Texas",UT:"Utah",VT:"Vermont",VA:"Virginia",WA:"Washington",WV:"West Virginia",WI:"Wisconsin",WY:"Wyoming",DC:"District of Columbia",PR:"Puerto Rico",VI:"Virgin Islands",GU:"Guam",AS:"American Samoa",MP:"Northern Mariana Islands"};function a(t,e){let r=t.match(new RegExp(`<${e}[^>]*>([^<]*)<\\/${e}>`));return r?r[1].trim():void 0}function m(t){return{name:"USPS",fetcher:async(r,o)=>{let i=await fetch(r,{signal:o});if(!i.ok)throw new Error(`HTTP error! status: ${i.status}`);return i.text()},buildUrl:r=>{let o=`<CityStateLookupRequest USERID="${t}"><ZipCode ID="0"><Zip5>${r}</Zip5></ZipCode></CityStateLookupRequest>`;return`https://secure.shippingapis.com/ShippingAPI.dll?API=CityStateLookup&XML=${encodeURIComponent(o)}`},transform:r=>{let o=a(r,"Description");if(r.includes("<Error>")&&o)throw new Error(o);let i=a(r,"City"),n=a(r,"State"),s=a(r,"Zip5");if(!i||!n||!s)throw new Error("ZIP not found");return{zip:s,city:i.charAt(0)+i.slice(1).toLowerCase(),state:d[n]||n,stateAbbr:n,country:"United States",service:"USPS"}}}}export{m as createUspsProvider,l as createZipcodestackProvider,p as zippopotamPlusProvider,c as zippopotamProvider};

package/dist/src/cache/index.d.ts

@@ -0,0 +1,25 @@
+import { ZipAddress } from '../types';
+export interface ZipCache {
+    get(key: string): ZipAddress | undefined;
+    set(key: string, value: ZipAddress): void;
+    clear(): void;
+    delete?(key: string): void;
+    has?(key: string): boolean;
+}
+export interface InMemoryCacheOptions {
+    /** Time-to-live in milliseconds. Default: Infinity (no expiry) */
+    ttl?: number;
+    /** Maximum number of entries. Default: Infinity (no limit) */
+    maxSize?: number;
+}
+export declare class InMemoryCache implements ZipCache {
+    private cache;
+    private ttl;
+    private maxSize;
+    constructor(options?: InMemoryCacheOptions);
+    get(key: string): ZipAddress | undefined;
+    set(key: string, value: ZipAddress): void;
+    delete(key: string): void;
+    has(key: string): boolean;
+    clear(): void;
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,35 @@
+export type ZipErrorCode = "INVALID_ZIP" | "RATE_LIMITED" | "TIMEOUT" | "NOT_FOUND" | "PROVIDER_UNAVAILABLE" | "ALL_PROVIDERS_FAILED" | "UNKNOWN";
+export declare class ZipValidationError extends Error {
+    readonly zip: string;
+    readonly code: ZipErrorCode;
+    constructor(zip: string);
+}
+export declare class RateLimitError extends Error {
+    readonly limit: number;
+    readonly window: number;
+    readonly code: ZipErrorCode;
+    constructor(limit: number, window: number);
+}
+export declare class ProviderTimeoutError extends Error {
+    readonly provider: string;
+    readonly timeout: number;
+    readonly code: ZipErrorCode;
+    constructor(provider: string, timeout: number);
+}
+export declare class ZipNotFoundError extends Error {
+    readonly zip: string;
+    readonly provider?: string;
+    readonly code: ZipErrorCode;
+    constructor(zip: string, provider?: string);
+}
+export declare class AllProvidersFailedError extends Error {
+    readonly errors: Error[];
+    readonly code: ZipErrorCode;
+    constructor(errors: Error[]);
+}
+export declare class ProviderUnavailableError extends Error {
+    readonly provider: string;
+    readonly code: ZipErrorCode;
+    constructor(provider: string);
+}
+export declare function normalizeProviderError(error: unknown, zip: string, provider: string): Error;

package/dist/src/index.d.ts

@@ -0,0 +1,43 @@
+import { ZipAddress, Fetcher, ZipProvider, ZipLookupOptions, BulkZipResult, RateLimitOptions, EventName, EventListener, EventMap, ProviderHealth, ProviderMetrics, CircuitBreakerOptions } from "./types";
+import { ZipCache, InMemoryCache, InMemoryCacheOptions } from "./cache";
+import { ZipValidationError, RateLimitError, ProviderTimeoutError, ZipNotFoundError, AllProvidersFailedError, ProviderUnavailableError } from "./errors";
+export type { ZipAddress, Fetcher, ZipProvider, ZipLookupOptions, BulkZipResult, RateLimitOptions, EventName, EventListener, EventMap, ZipCache, InMemoryCacheOptions, ProviderHealth, ProviderMetrics, CircuitBreakerOptions, };
+export { InMemoryCache };
+export { ZipValidationError, RateLimitError, ProviderTimeoutError, ZipNotFoundError, AllProvidersFailedError, ProviderUnavailableError, };
+export declare class ZipLookup {
+    private providers;
+    private sortedProviders;
+    private fetcher;
+    private cache?;
+    private rateLimit?;
+    private staggerDelay;
+    private retries;
+    private retryDelay;
+    private logger?;
+    private requestTimestamps;
+    private emitter;
+    private circuitBreakerEnabled;
+    private circuitFailureThreshold;
+    private circuitCooldownMs;
+    private providerState;
+    constructor(options: ZipLookupOptions);
+    private log;
+    on<T extends EventName>(eventName: T, listener: EventListener<T>): void;
+    off<T extends EventName>(eventName: T, listener: EventListener<T>): void;
+    /**
+     * Pings providers to determine the fastest one and updates internal priority order.
+     * Useful to call on UI events like 'focus' on the ZIP input.
+     */
+    warmup(): Promise<ZipProvider[]>;
+    private getOrCreateProviderState;
+    private recordProviderSuccess;
+    private recordProviderFailure;
+    private isProviderOpen;
+    private scoreProvider;
+    getProviderHealth(): ProviderHealth[];
+    getProviderMetrics(): ProviderMetrics[];
+    private checkRateLimit;
+    lookup<T = ZipAddress>(zip: string, mapper?: (address: ZipAddress) => T): Promise<T>;
+    private _lookupFromProviders;
+    lookupZips<T = ZipAddress>(zips: string[], concurrency?: number, mapper?: (address: ZipAddress) => T): Promise<BulkZipResult<T>[]>;
+}

package/dist/src/providers/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./zippopotam";
+export * from "./zipcodestack";
+export * from "./usps";

package/dist/src/providers/usps.d.ts

@@ -0,0 +1,9 @@
+import { ZipProvider } from "../types";
+/**
+ * Creates a USPS CityStateLookup provider.
+ * Requires a free USPS Web Tools API key: https://www.usps.com/business/web-tools-apis/
+ *
+ * Note: USPS only returns city and state — no lat/lng or county.
+ * The provider uses a text/xml fetcher internally so no custom global fetcher is needed.
+ */
+export declare function createUspsProvider(apiKey: string): ZipProvider;

package/dist/src/providers/zipcodestack.d.ts

@@ -0,0 +1,7 @@
+import { ZipProvider } from "../types";
+/**
+ * Creates a ZipCodeStack provider.
+ * Requires a free API key from https://zipcodestack.com
+ * Returns city, state, county, timezone, latitude, longitude.
+ */
+export declare function createZipcodestackProvider(apiKey: string): ZipProvider;

package/dist/src/providers/zippopotam.d.ts

@@ -0,0 +1,12 @@
+import { ZipProvider } from "../types";
+/**
+ * Free provider with no API key required.
+ * Returns city, state, county, latitude and longitude.
+ * Docs: https://www.zippopotam.us/
+ */
+export declare const zippopotamProvider: ZipProvider;
+/**
+ * Same as zippopotamProvider but requests the extended endpoint with
+ * additional place data (multiple cities per ZIP when available).
+ */
+export declare const zippopotamPlusProvider: ZipProvider;

package/dist/src/types.d.ts

@@ -0,0 +1,98 @@
+import { ZipCache } from "./cache";
+export interface ZipAddress {
+    zip: string;
+    city: string;
+    state: string;
+    stateAbbr: string;
+    county?: string;
+    country: string;
+    latitude?: string;
+    longitude?: string;
+    timezone?: string;
+    service: string;
+}
+export type Fetcher = (url: string, signal?: AbortSignal) => Promise<any>;
+export interface ZipProvider {
+    name: string;
+    timeout?: number;
+    buildUrl: (zip: string) => string;
+    transform: (response: any) => ZipAddress;
+    /** Override the global fetcher for this provider (e.g. for XML-based APIs). */
+    fetcher?: Fetcher;
+}
+export interface RateLimitOptions {
+    requests: number;
+    per: number;
+}
+export interface ZipLookupOptions {
+    providers: ZipProvider[];
+    fetcher?: Fetcher;
+    cache?: ZipCache;
+    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;
+}
+export interface BulkZipResult<T = ZipAddress> {
+    zip: string;
+    data: T | null;
+    provider?: string;
+    error?: Error;
+}
+export type EventName = 'success' | 'failure' | 'cache:hit';
+export interface SuccessPayload {
+    provider: string;
+    zip: string;
+    duration: number;
+    address: ZipAddress;
+}
+export interface FailurePayload {
+    provider: string;
+    zip: string;
+    duration: number;
+    error: Error;
+}
+export interface CacheHitPayload {
+    zip: string;
+}
+export interface EventMap {
+    success: SuccessPayload;
+    failure: FailurePayload;
+    '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

@@ -0,0 +1,48 @@
+{
+  "name": "@eusilvio/zip-lookup",
+  "version": "2.6.0",
+  "description": "Agnostic, performant and flexible US ZIP code lookup library with race strategy and caching.",
+  "license": "MIT",
+  "author": "Silvio Souza",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eusilvio/cep-lookup.git",
+    "directory": "packages/zip-lookup"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./providers": {
+      "types": "./dist/src/providers/index.d.ts",
+      "import": "./dist/providers/index.mjs",
+      "require": "./dist/providers/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "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"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "esbuild": "^0.27.2",
+    "jest": "^30.1.3",
+    "ts-jest": "^29.4.4",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.9.2"
+  }
+}