1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
/**
* TypeScript client for the public CEP API at [cep.is](https://cep.is).
*
* Quick use — for a script, the module-level functions are enough:
*
* ```ts
* import { lookup } from "cepis";
*
* const address = await lookup("01001-000");
* console.log(address.localidade, address.uf); // São Paulo SP
* ```
*
* In an application, build a {@link Client} once and reuse it:
*
* ```ts
* import { Client } from "cepis";
*
* const client = new Client({ timeoutMs: 5_000, totalTimeoutMs: 15_000 });
* const address = await client.lookup("01001000");
* ```
*
* Pointing at a local instance:
*
* ```ts
* const client = new Client({ baseUrl: "http://localhost:8080" });
* ```
*
* Errors are explicit and split by decision — whether retrying helps or not:
*
* ```ts
* import { CEPNotFound, CepisError, lookup } from "cepis";
*
* try {
* const address = await lookup(cepFromForm);
* } catch (error) {
* if (error instanceof CEPNotFound) {
* // the CEP does not exist: ask the user for another. `error.faixa`, when
* // present, names the municipality it would have belonged to — context
* // for the message, not an address.
* } else if (error instanceof CepisError) {
* // network, server, rate limit: retry later
* } else {
* throw error;
* }
* }
* ```
*
* Note on field names: the API surface is English, but the **data fields keep
* the API's own Portuguese names** (`logradouro`, `bairro`, `localidade`).
* What you read in the JSON is what you access on the object.
*
* The module-level functions share one default client, built once because
* {@link Client} keeps no state between calls. Anyone needing different
* settings should build their own.
*
* @module
*/
import { Client } from "./client.js";
import type { Address, Health } from "./models.js";
export { Client, DEFAULT_URL, MAX_BATCH, normalizeCep, type ClientOptions } from "./client.js";
export { parseCsv, type CsvRecord } from "./csv.js";
export {
CEPNotFound,
CepisError,
InvalidCEP,
InvalidResponse,
NetworkError,
RateLimited,
ServerError,
} from "./errors.js";
export {
Address,
Faixa,
Geo,
Health,
type AddressFields,
type FaixaFields,
type GeoFields,
type HealthFields,
type RawObject,
} from "./models.js";
export { VERSION } from "./version.js";
const shared = new Client();
/**
* Look up a CEP using the default configuration.
*
* Shorthand for `new Client().lookup(cep)`. See {@link Client.lookup}.
*/
export function lookup(cep: string): Promise<Address> {
return shared.lookup(cep);
}
/**
* Look up many CEPs in one batch, using the default configuration.
*
* Shorthand for {@link Client.lookupMany} — read that one, especially the
* warning that batches carry no coordinate.
*/
export function lookupMany(ceps: readonly string[]): Promise<(Address | null)[]> {
return shared.lookupMany(ceps);
}
/**
* Query the API's health using the default configuration.
*
* Shorthand for {@link Client.health}.
*/
export function health(): Promise<Health> {
return shared.health();
}
|