//#region src/get-address-info-by-cep/get-address-info-by-cep.d.ts
/** Base class of every error `getAddressInfoByCep` rejects with. */
export declare class GetAddressInfoByCepError extends Error {
  constructor(message: string);
}
/** Thrown by `getAddressInfoByCep` when the value given is not a valid CEP. */
export declare class GetAddressInfoByCepValidationError extends GetAddressInfoByCepError {
  constructor(message: string);
}
/** Thrown by `getAddressInfoByCep` when no CEP service knows the CEP. */
export declare class GetAddressInfoByCepNotFoundError extends GetAddressInfoByCepError {
  constructor(message: string);
}
/** Thrown by `getAddressInfoByCep` when every CEP service failed to answer. */
export declare class GetAddressInfoByCepServiceError extends GetAddressInfoByCepError {
  constructor(message: string);
}
/** The address `getAddressInfoByCep` returns for a CEP. */
export type AddressInfo = {
  /** The 8 digit CEP, no mask. */
  cep: string;
  /** Two letter state code, e.g. "SP". */
  state: string;
  /** City name. */
  city: string;
  /** Neighborhood name, empty when the CEP covers a whole city. */
  neighborhood: string;
  /** Street name, empty when the CEP covers a whole city. */
  street: string;
};
/** The CEP services `getAddressInfoByCep` can query. */
export type CepProvider = "viacep" | "widenet" | "brasilapi";
/** Options of `getAddressInfoByCep`. */
export type GetAddressInfoByCepOptions = {
  /**
   * Which CEP services to race, in the order given (default: `["viacep", "brasilapi"]`; the
   * deprecated `"widenet"` provider is excluded from the default list, but can still be
   * requested explicitly).
   */
  providers?: CepProvider[];
};
/**
 * Fetches address information for a given CEP using multiple providers simultaneously.
 * Returns the result from the first provider that responds successfully.
 *
 * The providers are started together and raced with `Promise.any`, not tried one after the
 * other, so a provider that is retrying delays nothing for the others: its retries only push
 * back the moment its own failure lands, and therefore the moment an all-failed rejection can
 * surface.
 *
 * @param {string|number} cep - The CEP (Brazilian postal code) to search for. Can be a string or number.
 * @param {GetAddressInfoByCepOptions} options - Optional configuration for the function.
 * @param {CepProvider[]} options.providers - List of providers to use. Defaults to `["viacep", "brasilapi"]`
 * if not specified (the deprecated `"widenet"` provider is excluded from the default list, but can still
 * be requested explicitly).
 * @returns {Promise<AddressInfo>} A promise that resolves to the address information.
 * @throws {GetAddressInfoByCepValidationError} If the CEP format is invalid, or if
 * `options.providers` is given and names no known provider: an empty array, an array of unknown
 * names, and a value that is not an array at all (`null` included) all reject this way rather
 * than with a raw `TypeError`.
 * @throws {GetAddressInfoByCepNotFoundError} If the CEP is not found in any of the services.
 * @throws {GetAddressInfoByCepServiceError} If all services are unavailable.
 *
 * @example
 * ```typescript
 * // Using the default providers (["viacep", "brasilapi"])
 * const address = await getAddressInfoByCep("01310100");
 *
 * // Using specific providers
 * const address = await getAddressInfoByCep("01310-100", {
 *   providers: ["viacep", "brasilapi"]
 * });
 *
 * // Using number input
 * const address = await getAddressInfoByCep(1310100);
 * ```
 *
 * @see Official: https://www.correios.com.br/enviar/precisa-de-ajuda/tudo-sobre-cep
 * @see Based on: https://viacep.com.br/
 * ViaCEP, one of the two default providers. A third-party service, not a Correios one.
 * @see Based on: https://brasilapi.com.br/docs#tag/CEP
 * BrasilAPI, the other default provider. A third-party service, not a Correios one.
 */
export declare const getAddressInfoByCep: (cep: string | number, options?: GetAddressInfoByCepOptions) => Promise<AddressInfo>;
//#endregion