brasilapi

defmodule Brasilapi do
  @moduledoc """
  A simple Elixir client for BrasilAPI.

  BrasilAPI is a public API that provides access to various Brazilian data
  such as postal codes, states, cities, banks, and more.

  ## Examples

      # Get all banks
      {:ok, banks} = Brasilapi.get_banks()

      # Get a specific bank by code
      {:ok, bank} = Brasilapi.get_bank_by_code(1)

      # Get all currencies
      {:ok, currencies} = Brasilapi.get_exchange_currencies()

      # Get exchange rate
      {:ok, exchange_rate} = Brasilapi.get_exchange_rate("USD", "2025-02-13")

      # Get CEP information
      {:ok, cep_data} = Brasilapi.get_cep("89010025")

      # Get CNPJ information
      {:ok, company} = Brasilapi.get_cnpj("19131243000197")

      # Get all brokerage firms
      {:ok, brokers} = Brasilapi.get_brokers()

      # Get specific brokerage firm by CNPJ
      {:ok, broker} = Brasilapi.get_broker_by_cnpj("02332886000104")

      # Get DDD information
      {:ok, ddd_info} = Brasilapi.get_ddd(11)

      # Get national holidays
      {:ok, holidays} = Brasilapi.get_holidays(2021)

      # Get FIPE vehicle brands
      {:ok, brands} = Brasilapi.get_fipe_brands("carros")

      # Get FIPE vehicle price
      {:ok, prices} = Brasilapi.get_fipe_price("001004-9")

      # Get FIPE reference tables
      {:ok, tables} = Brasilapi.get_fipe_reference_tables()

      # Get FIPE vehicles by brand
      {:ok, vehicles} = Brasilapi.get_fipe_vehicles("carros", 1)

      # Get all Brazilian states
      {:ok, states} = Brasilapi.get_states()

      # Get specific state information
      {:ok, state} = Brasilapi.get_state("SP")

      # Get municipalities for a state
      {:ok, municipalities} = Brasilapi.get_municipalities("SC")

      # Get book information by ISBN
      {:ok, book} = Brasilapi.get_book("9788545702870")

      # Get all NCM codes
      {:ok, ncms} = Brasilapi.get_ncms()

      # Search NCM codes
      {:ok, ncms} = Brasilapi.search_ncms("xampu")

      # Get specific NCM by code
      {:ok, ncm} = Brasilapi.get_ncm_by_code("33051000")

      # Get PIX participants
      {:ok, participants} = Brasilapi.get_pix_participants()

      # Get domain information
      {:ok, domain} = Brasilapi.get_domain_info("brasilapi.com.br")

      # Get all tax rates
      {:ok, rates} = Brasilapi.get_rates()

      # Get a specific tax rate
      {:ok, rate} = Brasilapi.get_rate_by_acronym("CDI")

      # List all CPTEC cities
      {:ok, all_cities} = Brasilapi.list_cptec_cities()

      # Search for cities in CPTEC
      {:ok, cities} = Brasilapi.search_cptec_cities("São Paulo")

      # Get current weather for all capitals
      {:ok, weather} = Brasilapi.get_capitals_weather()

      # Get airport weather
      {:ok, airport_weather} = Brasilapi.get_airport_weather("SBGR")

      # Get city weather forecast
      {:ok, forecast} = Brasilapi.get_city_forecast(244)

      # Get city weather forecast for 6 days
      {:ok, forecast} = Brasilapi.get_city_forecast(244, 6)

      # Get ocean forecast
      {:ok, ocean_forecast} = Brasilapi.get_ocean_forecast(241)

      # Get ocean forecast for 3 days
      {:ok, ocean_forecast} = Brasilapi.get_ocean_forecast(241, 3)

  """

  alias Brasilapi.{
    Banks,
    Brokers,
    Cep,
    Cnpj,
    Cptec,
    Ddd,
    Exchange,
    Fipe,
    Holidays,
    Ibge,
    Isbn,
    Ncm,
    Pix,
    Rates,
    RegistroBr
  }

  # BANKS

  @doc """
  Get all banks from BrasilAPI.

  ## API Reference
    https://brasilapi.com.br/docs#tag/BANKS/paths/~1banks~1v1/get
  """
  defdelegate get_banks(), to: Banks

  @doc """
  Get a specific bank by its code.

  ## API Reference
    https://brasilapi.com.br/docs#tag/BANKS/paths/~1banks~1v1~1%7Bcode%7D/get
  """
  defdelegate get_bank_by_code(code), to: Banks

  # CAMBIO (Exchange)

  @doc """
  Get all available currencies for exchange rate queries.

  ## API Reference
    https://brasilapi.com.br/docs#tag/CAMBIO/paths/~1cambio~1v1~1moedas/get
  """
  defdelegate get_exchange_currencies(), to: Exchange

  @doc """
  Get the exchange rate between Real and another currency for a specific date.

  ## API Reference
    https://brasilapi.com.br/docs#tag/CAMBIO/paths/~1cambio~1v1~1cotacao~1%7Bmoeda%7D~1%7Bdata%7D/get
  """
  defdelegate get_exchange_rate(currency, date), to: Exchange

  # CEP

  @doc """
  Get CEP (postal code) information.

  By default uses the v2 endpoint which includes geolocation data.
  You can use the v1 endpoint by passing `version: :v1` in the options.

  ## Options
    * `:version` - API version to use (`:v1` or `:v2`). Defaults to `:v2`.

  ## API Reference
    * V2: https://brasilapi.com.br/docs#tag/CEP-V2/paths/~1cep~1v2~1%7Bcep%7D/get
    * V1: https://brasilapi.com.br/docs#tag/CEP/paths/~1cep~1v1~1%7Bcep%7D/get
  """
  defdelegate get_cep(cep, opts \\ []), to: Cep, as: :get_by_cep

  # CNPJ

  @doc """
  Get company information by CNPJ.

  ## API Reference
    https://brasilapi.com.br/docs#tag/CNPJ/paths/~1cnpj~1v1~1%7Bcnpj%7D/get
  """
  defdelegate get_cnpj(cnpj), to: Cnpj, as: :get_by_cnpj

  # CPTEC

  @doc """
  List all cities available in CPTEC services.

  Returns a complete listing of all cities with their CPTEC codes.
  The city code (id) is used in other CPTEC endpoints for weather and ocean forecasts.

  Note: The CPTEC web service can be unstable. If you don't find a specific city
  in the complete listing, try searching by part of its name using `search_cptec_cities/1`.

  ## API Reference
    https://brasilapi.com.br/docs#tag/CPTEC/operation/listcities(/cptec/v1/cidade)
  """
  defdelegate list_cptec_cities(), to: Cptec, as: :list_cities

  @doc """
  Search for cities by name to get their CPTEC codes.

  Returns a list of cities matching the search term. The city code (id) is used
  in other CPTEC endpoints for weather and ocean forecasts.

  ## API Reference
    https://brasilapi.com.br/docs#tag/CPTEC/operation/searchcities(/cptec/v1/cidade/:cityName)
  """
  defdelegate search_cptec_cities(city_name), to: Cptec, as: :search_cities

  @doc """
  Get current weather conditions for all Brazilian state capitals.

  Returns meteorological data from airport weather stations in each capital city.

  ## API Reference
    https://brasilapi.com.br/docs#tag/CPTEC/operation/Condi%C3%A7%C3%B5esatuaisnascapitais(/cptec/v1/clima/capital)
  """
  defdelegate get_capitals_weather(), to: Cptec

  @doc """
  Get current weather conditions at a specific airport by ICAO code.

  The ICAO code must be 4 uppercase letters (e.g., "SBGR", "SBAR").

  ## API Reference
    https://brasilapi.com.br/docs#tag/CPTEC/operation/airportcurrentcondicao(/cptec/v1/clima/aeroporto/:icaoCode)
  """
  defdelegate get_airport_weather(icao_code), to: Cptec

  @doc """
  Get weather forecast for a city.

  Supports both 1-day and multi-day forecasts (up to 6 days).
  Use the city code obtained from `search_cptec_cities/1`.

  ## API Reference
    https://brasilapi.com.br/docs#tag/CPTEC/operation/climapredictionwithoutdays(/cptec/v1/clima/previsao/:cityCode)
    https://brasilapi.com.br/docs#tag/CPTEC/operation/upto14daysprediction(/cptec/v1/clima/previsao/:cityCode/:days)
  """
  defdelegate get_city_forecast(city_code), to: Cptec
  defdelegate get_city_forecast(city_code, days), to: Cptec

  @doc """
  Get ocean/wave forecast for a coastal city.

  Supports both 1-day and multi-day forecasts (up to 6 days).
  Use the city code obtained from `search_cptec_cities/1`.

  ## API Reference
    https://brasilapi.com.br/docs#tag/CPTEC/operation/ondaspredictionwithoutdays(/cptec/v1/ondas/:cityCode)
    https://brasilapi.com.br/docs#tag/CPTEC/operation/ondaspredictionupto6days(/cptec/v1/ondas/:cityCode/:days)
  """
  defdelegate get_ocean_forecast(city_code), to: Cptec
  defdelegate get_ocean_forecast(city_code, days), to: Cptec

  # Corretoras (Brokers)

  @doc """
  Get all active brokerage firms registered with CVM.

  ## API Reference
    https://brasilapi.com.br/docs#tag/Corretoras/paths/~1cvm~1corretoras~1v1/get
  """
  defdelegate get_brokers(), to: Brokers

  @doc """
  Get a specific brokerage firm by its CNPJ from CVM records.

  ## API Reference
    https://brasilapi.com.br/docs#tag/Corretoras/paths/~1cvm~1corretoras~1v1~1%7Bcnpj%7D/get
  """
  defdelegate get_broker_by_cnpj(cnpj), to: Brokers

  # DDD

  @doc """
  Get DDD (area code) information including state and cities.

  ## API Reference
    https://brasilapi.com.br/docs#tag/DDD/paths/~1ddd~1v1~1%7Bddd%7D/get
  """
  defdelegate get_ddd(ddd), to: Ddd, as: :get_by_ddd

  # Feriados Nacionais (National Holidays)

  @doc """
  Get national holidays for a specific year.

  ## API Reference
    https://brasilapi.com.br/docs#tag/Feriados-Nacionais/paths/~1feriados~1v1~1%7Bano%7D/get
  """
  defdelegate get_holidays(year), to: Holidays, as: :get_by_year

  # FIPE

  @doc """
  Get vehicle brands by type from FIPE table.

  Returns a list of brands for a specific vehicle type or all types.

  ## API Reference
    https://brasilapi.com.br/docs#tag/FIPE/paths/~1fipe~1marcas~1v1~1%7BtipoVeiculo%7D/get
  """
  defdelegate get_fipe_brands(vehicle_type \\ nil, opts \\ []), to: Fipe, as: :get_brands

  @doc """
  Get vehicle price by FIPE code.

  Returns detailed price information for a specific vehicle according to the FIPE table.

  ## API Reference
    https://brasilapi.com.br/docs#tag/FIPE/paths/~1fipe~1preco~1v1~1%7BcodigoFipe%7D/get
  """
  defdelegate get_fipe_price(fipe_code, opts \\ []), to: Fipe, as: :get_price

  @doc """
  Get all available FIPE reference tables.

  Returns a list of all reference tables with their codes and months.

  ## API Reference
    https://brasilapi.com.br/docs#tag/FIPE/paths/~1fipe~1tabelas~1v1/get
  """
  defdelegate get_fipe_reference_tables(), to: Fipe, as: :get_reference_tables

  @doc """
  Get vehicles by brand and type from FIPE table.

  Returns a list of vehicle models for a specific brand and vehicle type.

  ## API Reference
    https://brasilapi.com.br/docs#tag/FIPE/paths/~1fipe~1veiculos~1v1~1%7BtipoVeiculo%7D~1%7BcodigoMarca%7D/get
  """
  defdelegate get_fipe_vehicles(vehicle_type, brand_code, opts \\ []),
    to: Fipe,
    as: :get_vehicles

  # IBGE

  @doc """
  Get all Brazilian states.

  Returns information about all states including their regions.

  ## API Reference
    https://brasilapi.com.br/docs#tag/IBGE/paths/~1ibge~1uf~1v1/get
  """
  defdelegate get_states(), to: Ibge

  @doc """
  Get information about a specific state by code or abbreviation.

  ## API Reference
    https://brasilapi.com.br/docs#tag/IBGE/paths/~1ibge~1uf~1v1~1%7Bcode%7D/get
  """
  defdelegate get_state(code), to: Ibge

  @doc """
  Get municipalities for a given state.

  Returns a list of municipalities for the specified state (UF).
  Optionally accepts a list of data providers.

  ## API Reference
    https://brasilapi.com.br/docs#tag/IBGE/paths/~1ibge~1municipios~1v1~1%7BsiglaUF%7D?providers=dados-abertos-br,gov,wikipedia/get
  """
  defdelegate get_municipalities(uf, opts \\ []), to: Ibge

  # ISBN

  @doc """
  Get book information by ISBN from multiple providers.

  ## API Reference
    https://brasilapi.com.br/docs#tag/ISBN/paths/~1isbn~1v1~1%7Bisbn%7D/get
  """
  defdelegate get_book(isbn, opts \\ []), to: Isbn

  # NCM

  @doc """
  Get all NCM (Nomenclatura Comum do Mercosul) codes.

  ## API Reference
    https://brasilapi.com.br/docs#tag/NCM/paths/~1ncm~1v1/get
  """
  defdelegate get_ncms(), to: Ncm

  @doc """
  Search NCM codes using a code or description keyword.

  ## API Reference
    https://brasilapi.com.br/docs#tag/NCM/paths/~1ncm~1v1?search=%7Bcode%7D/get
  """
  defdelegate search_ncms(query), to: Ncm

  @doc """
  Get detailed information for a specific NCM code.

  ## API Reference
    https://brasilapi.com.br/docs#tag/NCM/paths/~1ncm~1v1~1%7Bcode%7D/get
  """
  defdelegate get_ncm_by_code(code), to: Ncm

  # PIX

  @doc """
  Get all PIX participants.

  ## API Reference
    https://brasilapi.com.br/docs#tag/PIX/paths/~1pix~1v1~1participants/get
  """
  defdelegate get_pix_participants(), to: Pix, as: :get_participants

  # REGISTRO BR

  @doc """
  Get Brazilian domain (.br) registration information.

  ## API Reference
    https://brasilapi.com.br/docs#tag/REGISTRO-BR/paths/~1registrobr~1v1~1%7Bdomain%7D/get
  """
  defdelegate get_domain_info(domain), to: RegistroBr, as: :get_domain_info

  # TAXAS (Rates)

  @doc """
  Get all available tax rates and indices.

  ## API Reference
    https://brasilapi.com.br/docs#tag/TAXAS/paths/~1taxas~1v1/get
  """
  defdelegate get_rates(), to: Rates, as: :get_rates

  @doc """
  Get a specific tax rate or index by its name/acronym.

  ## API Reference
    https://brasilapi.com.br/docs#tag/TAXAS/paths/~1taxas~1v1~1%7Bsigla%7D/get
  """
  defdelegate get_rate_by_acronym(acronym), to: Rates, as: :get_rates_by_acronym
end