/**
 * 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();
}