{"_id":"@br-geo-kit/cep","name":"@br-geo-kit/cep","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@br-geo-kit/cep","version":"1.0.0","description":"Resolve Brazilian CEPs through a chain of providers, with caching, fallback and offline enrichment","license":"MIT","engines":{"node":">=20"},"type":"module","sideEffects":false,"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"dependencies":{"@br-geo-kit/core":"1.0.0"},"publishConfig":{"access":"public"},"keywords":["cep","endereco","correios","viacep","brasil","br-geo-kit"],"repository":{"type":"git","url":"git+https://github.com/arielff3/br-geo-kit.git","directory":"packages/cep"},"homepage":"https://github.com/arielff3/br-geo-kit/tree/main/packages/cep#readme","bugs":{"url":"https://github.com/arielff3/br-geo-kit/issues"},"devDependencies":{"@br-geo-kit/ibge":"1.0.0"},"scripts":{"build":"tsup","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""},"_id":"@br-geo-kit/cep@1.0.0","_integrity":"sha512-Qse7l09MwUVc4euxAGsN1/vA32A2PFuChzenavJSYwtV+Zkrx80ACg1mQXlZPC/fdweFMCwsqZnh2tErt7VTPg==","_resolved":"C:\\Users\\ariel\\AppData\\Local\\Temp\\1875dcbff69085c34cf50131802d4655\\br-geo-kit-cep-1.0.0.tgz","_from":"file:br-geo-kit-cep-1.0.0.tgz","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-Qse7l09MwUVc4euxAGsN1/vA32A2PFuChzenavJSYwtV+Zkrx80ACg1mQXlZPC/fdweFMCwsqZnh2tErt7VTPg==","shasum":"b5f99df1df120125e6a3c3a1ac200cab8dc9e05e","tarball":"https://registry.npmjs.org/@br-geo-kit/cep/-/cep-1.0.0.tgz","fileCount":10,"unpackedSize":122280,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCA1rI1X7ZqB3H5RqbV0oAbWL3PCKzjhnCHJY7PTvBxHAIgLiBbN+q/6G5A2lXkVFPhVmUr5mGULy0AQjGmcpRbAy8="}]},"_npmUser":{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"},"directories":{},"maintainers":[{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cep_1.0.0_1789134629767_0.27438771386883176"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-11T13:50:29.604Z","1.0.0":"2026-09-11T13:50:29.906Z","modified":"2026-09-11T13:50:30.142Z"},"maintainers":[{"name":"arielff03","email":"arielfrancoferreira5@gmail.com"}],"description":"Resolve Brazilian CEPs through a chain of providers, with caching, fallback and offline enrichment","homepage":"https://github.com/arielff3/br-geo-kit/tree/main/packages/cep#readme","keywords":["cep","endereco","correios","viacep","brasil","br-geo-kit"],"repository":{"type":"git","url":"git+https://github.com/arielff3/br-geo-kit.git","directory":"packages/cep"},"bugs":{"url":"https://github.com/arielff3/br-geo-kit/issues"},"license":"MIT","readme":"# @br-geo-kit/cep\n\n> Resolve a Brazilian CEP through a chain of providers that survives any\n> one of them going down.\n\n```bash\npnpm add @br-geo-kit/cep @br-geo-kit/provider-brasilapi @br-geo-kit/provider-viacep\n```\n\n```ts\nimport { createCep, memoryCache } from '@br-geo-kit/cep'\nimport { brasilapi } from '@br-geo-kit/provider-brasilapi'\nimport { viacep } from '@br-geo-kit/provider-viacep'\nimport { ibge } from '@br-geo-kit/ibge'\n\nconst cep = createCep({\n  providers: [brasilapi(), viacep()],\n  cache: memoryCache(),\n  territory: ibge,\n})\n\nawait cep.lookup('01310-100')\n```\n\n---\n\n## The one distinction everything rests on\n\n| Result | Meaning |\n| --- | --- |\n| an `Address` | the CEP exists |\n| `null` | every provider was asked, and none of them has it |\n| throws `AllProvidersFailedError` | nobody could be reached |\n\nMost hand-rolled integrations collapse the last two, and the bug that\nfollows is always the same: a rate limit or an outage reaches the user as\n\"this address does not exist\", so somebody with a perfectly valid\naddress retypes it until they give up.\n\n```ts\ntry {\n  const address = await cep.lookup(input)\n  if (address === null) {\n    // no such CEP — ask the user to check it\n  }\n} catch (error) {\n  // nobody answered — ask them to try again, do not blame the address\n}\n```\n\n---\n\n## The canonical address\n\nEvery provider is normalized into one shape. ViaCEP says\n`logradouro/localidade/uf`, BrasilAPI says `street/city/state`,\nAwesomeAPI says something else again.\n\n```ts\n{\n  cep: '01310100',          // always eight digits, no mask\n  street: 'Avenida Paulista',\n  complement: 'de 612 a 1510 - lado par',\n  neighborhood: 'Bela Vista',\n  city: 'São Paulo',\n  state: 'SP',\n  ibge: { city: '3550308', state: '35' },\n  ddd: '11',\n  timezone: 'America/Sao_Paulo',\n  coordinates: { latitude: -23.5617698, longitude: -46.6553299 },\n  source: 'brasilapi',\n  cached: false\n}\n```\n\nA field is `null` when the source did not provide it. Never a guess,\nnever an empty string — a *CEP único* covers a whole small municipality\nand legitimately has no street.\n\nInput is accepted in every shape a CEP arrives in: `01310-100`,\n`01310100`, `01.310-100`, and the number `1310100` a spreadsheet\nproduced by dropping the leading zero.\n\n---\n\n## Options\n\n```ts\ncreateCep({\n  providers: [brasilapi(), viacep()],  // required, in order of preference\n  strategy: 'fallback',                // | 'race' | 'consensus'\n  timeoutMs: 3000,                     // per provider\n  cache: memoryCache(),                // default: nothing is cached\n  territory: ibge,                     // offline enrichment + range check\n  onWarning: (warning) => log(warning),\n  fetch: myInstrumentedFetch,\n})\n```\n\n**`strategy`** — `fallback` asks one at a time, in order: one request in\nthe common case, and the default. `race` asks all at once and takes the\nfirst answer, trading N times the traffic for the fastest provider's\nlatency. `consensus` asks all, waits for all, returns the majority and\nreports every disagreement — the only one that catches a provider that\nis *confidently wrong* rather than merely down.\n\n**`territory`** — pass `ibge` from `@br-geo-kit/ibge` and the kit fills\nthe area code, the IBGE code and the time zone that a provider left out,\nskips the network for a CEP in an unallocated block, and warns when an\nanswer's state contradicts the CEP's block. This package does **not**\ndepend on `@br-geo-kit/ibge`; it declares the three-method interface it\nneeds, so the 730 KB dataset never lands in a bundle that did not ask\nfor it.\n\n**`cache`** — turn it on. No public CEP service publishes a rate limit,\nwhich means the limit exists and you will find it in production. See\n[caching](https://github.com/arielff3/br-geo-kit/blob/main/docs/caching.md).\n\n---\n\n## Warnings\n\nEverything the resolver noticed but did not treat as fatal:\n\n```ts\nonWarning: (warning) => {\n  switch (warning.kind) {\n    case 'provider-failed':        // the chain recovered, but note it\n    case 'provider-disagreement':  // consensus only\n    case 'state-range-mismatch':   // the answer contradicts the CEP block\n  }\n}\n```\n\nWithout `provider-failed`, a provider that has been down for a week is\ninvisible for as long as the one behind it keeps working.\n\n`provider-disagreement` reports only genuine contradictions: a provider\nthat returns `null` for a field has not dissented, it just does not\ncarry that field, and coordinates are compared by distance rather than\nequality. Otherwise every record produces a warning and nobody reads\nthem.\n\n`state-range-mismatch` is not hypothetical: CEP `99999-999` does not\nexist in the Correios' base, but the `open-cep` base behind BrasilAPI\nand OpenCEP has a record placing it in Sarandi/PR — while the CEP itself\nsits inside Rio Grande do Sul's block.\n\n---\n\n## Reverse lookup\n\n```ts\nawait cep.reverse({ state: 'SP', city: 'São Paulo', street: 'Paulista' })\n```\n\nOnly providers that declare the capability are asked, and ViaCEP is the\nonly public one that has it. Returns `[]` rather than failing when no\nprovider in the chain can do it.\n\n---\n\n## Documentation\n\n[Providers and strategies](https://github.com/arielff3/br-geo-kit/blob/main/docs/providers.md)\n· [Caching](https://github.com/arielff3/br-geo-kit/blob/main/docs/caching.md)\n· [API conventions](https://github.com/arielff3/br-geo-kit/blob/main/docs/api-conventions.md)\n· [Browser and React](https://github.com/arielff3/br-geo-kit/blob/main/docs/browser.md)\n\n## Licence\n\nMIT\n","readmeFilename":"README.md","_rev":"1-3399fd5646bd77d4d534f0feba1277f4"}