brutils

%% @doc Utils library for Brazilian-specific businesses.
%%
%% This module is the flat facade of the library: it re-exports the
%% domain modules' functions under suffixed names (for example
%% `is_valid_cpf/1' delegating to {@link brutils_cpf:is_valid/1}) so
%% callers can depend on a single module.
-module(brutils).

%% CPF
-export([is_valid_cpf/1, format_cpf/1, remove_symbols_cpf/1, generate_cpf/0]).
%% CNPJ
-export([is_valid_cnpj/1, format_cnpj/1, remove_symbols_cnpj/1,
         generate_cnpj/0, generate_cnpj/1, generate_cnpj/2]).
%% PIS
-export([is_valid_pis/1, format_pis/1, remove_symbols_pis/1, generate_pis/0]).
%% CNH
-export([is_valid_cnh/1]).
%% RENAVAM
-export([is_valid_renavam/1]).
%% CEP
-export([is_valid_cep/1, format_cep/1, remove_symbols_cep/1, generate_cep/0]).
%% Phone
-export([is_valid_phone/1, is_valid_phone/2, format_phone/1,
         remove_symbols_phone/1, remove_international_dialing_code/1,
         generate_phone/0, generate_phone/1]).
%% Passport
-export([is_valid_passport/1, format_passport/1, remove_symbols_passport/1,
         generate_passport/0]).
%% License plate
-export([is_valid_license_plate/1, is_valid_license_plate/2,
         format_license_plate/1, remove_symbols_license_plate/1,
         convert_license_plate_to_mercosul/1, get_format_license_plate/1,
         generate_license_plate/0, generate_license_plate/1]).
%% Voter ID
-export([is_valid_voter_id/1, format_voter_id/1,
         generate_voter_id/0, generate_voter_id/1]).

%%--------------------------------------------------------------------
%% CPF
%%--------------------------------------------------------------------

%% @doc Returns whether the given term is a valid CPF.
%% @see brutils_cpf:is_valid/1
-spec is_valid_cpf(term()) -> boolean().
is_valid_cpf(Cpf) ->
    brutils_cpf:is_valid(Cpf).

%% @doc Formats a valid CPF for display (`<<"XXX.XXX.XXX-XX">>').
%% @see brutils_cpf:format/1
-spec format_cpf(binary()) ->
        {ok, brutils_cpf:formatted_cpf()} | {error, invalid}.
format_cpf(Cpf) ->
    brutils_cpf:format(Cpf).

%% @doc Removes the formatting symbols `.' and `-' from a CPF string.
%% @see brutils_cpf:remove_symbols/1
-spec remove_symbols_cpf(binary()) -> binary().
remove_symbols_cpf(Cpf) ->
    brutils_cpf:remove_symbols(Cpf).

%% @doc Generates a random valid CPF.
%% @see brutils_cpf:generate/0
-spec generate_cpf() -> brutils_cpf:cpf().
generate_cpf() ->
    brutils_cpf:generate().

%%--------------------------------------------------------------------
%% CNPJ
%%--------------------------------------------------------------------

%% @doc Returns whether the given term is a valid CNPJ.
%% @see brutils_cnpj:is_valid/1
-spec is_valid_cnpj(term()) -> boolean().
is_valid_cnpj(Cnpj) ->
    brutils_cnpj:is_valid(Cnpj).

%% @doc Formats a valid CNPJ for display (`<<"XX.XXX.XXX/XXXX-XX">>').
%% @see brutils_cnpj:format/1
-spec format_cnpj(binary()) ->
        {ok, brutils_cnpj:formatted_cnpj()} | {error, invalid}.
format_cnpj(Cnpj) ->
    brutils_cnpj:format(Cnpj).

%% @doc Removes the formatting symbols `.', `/' and `-' from a CNPJ
%% string.
%% @see brutils_cnpj:remove_symbols/1
-spec remove_symbols_cnpj(binary()) -> binary().
remove_symbols_cnpj(Cnpj) ->
    brutils_cnpj:remove_symbols(Cnpj).

%% @doc Generates a random valid CNPJ with branch number `0001'.
%% @see brutils_cnpj:generate/0
-spec generate_cnpj() -> brutils_cnpj:cnpj().
generate_cnpj() ->
    brutils_cnpj:generate().

%% @doc Generates a random valid CNPJ with the given branch number.
%% @see brutils_cnpj:generate/1
-spec generate_cnpj(Branch :: non_neg_integer() | binary()) ->
        brutils_cnpj:cnpj().
generate_cnpj(Branch) ->
    brutils_cnpj:generate(Branch).

%% @doc Generates a random valid CNPJ, optionally alphanumeric.
%% @see brutils_cnpj:generate/2
-spec generate_cnpj(Branch :: non_neg_integer() | binary(),
                    Alphanumeric :: boolean()) -> brutils_cnpj:cnpj().
generate_cnpj(Branch, Alphanumeric) ->
    brutils_cnpj:generate(Branch, Alphanumeric).

%%--------------------------------------------------------------------
%% PIS
%%--------------------------------------------------------------------

%% @doc Returns whether the given term is a valid PIS.
%% @see brutils_pis:is_valid/1
-spec is_valid_pis(term()) -> boolean().
is_valid_pis(Pis) ->
    brutils_pis:is_valid(Pis).

%% @doc Formats a valid PIS for display (`<<"NNN.NNNNN.NN-N">>').
%% @see brutils_pis:format/1
-spec format_pis(binary()) ->
        {ok, brutils_pis:formatted_pis()} | {error, invalid}.
format_pis(Pis) ->
    brutils_pis:format(Pis).

%% @doc Removes the formatting symbols `.' and `-' from a PIS string.
%% @see brutils_pis:remove_symbols/1
-spec remove_symbols_pis(binary()) -> binary().
remove_symbols_pis(Pis) ->
    brutils_pis:remove_symbols(Pis).

%% @doc Generates a random valid PIS.
%% @see brutils_pis:generate/0
-spec generate_pis() -> brutils_pis:pis().
generate_pis() ->
    brutils_pis:generate().

%%--------------------------------------------------------------------
%% CNH
%%--------------------------------------------------------------------

%% @doc Returns whether the given term is a valid CNH (2022 layout).
%% Non-digit characters are stripped before validation.
%% @see brutils_cnh:is_valid/1
-spec is_valid_cnh(term()) -> boolean().
is_valid_cnh(Cnh) ->
    brutils_cnh:is_valid(Cnh).

%%--------------------------------------------------------------------
%% RENAVAM
%%--------------------------------------------------------------------

%% @doc Returns whether the given term is a valid RENAVAM.
%% Symbols are not stripped: the input must be digits only.
%% @see brutils_renavam:is_valid/1
-spec is_valid_renavam(term()) -> boolean().
is_valid_renavam(Renavam) ->
    brutils_renavam:is_valid(Renavam).

%%--------------------------------------------------------------------
%% CEP
%%--------------------------------------------------------------------

%% @doc Returns whether the given term is a valid CEP (8 digits; no
%% check digit exists, so validity says nothing about existence).
%% @see brutils_cep:is_valid/1
-spec is_valid_cep(term()) -> boolean().
is_valid_cep(Cep) ->
    brutils_cep:is_valid(Cep).

%% @doc Formats a valid CEP for display (`<<"NNNNN-NNN">>').
%% @see brutils_cep:format/1
-spec format_cep(binary()) ->
        {ok, brutils_cep:formatted_cep()} | {error, invalid}.
format_cep(Cep) ->
    brutils_cep:format(Cep).

%% @doc Removes the formatting symbols `.' and `-' from a CEP string.
%% @see brutils_cep:remove_symbols/1
-spec remove_symbols_cep(binary()) -> binary().
remove_symbols_cep(Cep) ->
    brutils_cep:remove_symbols(Cep).

%% @doc Generates a random CEP.
%% @see brutils_cep:generate/0
-spec generate_cep() -> brutils_cep:cep().
generate_cep() ->
    brutils_cep:generate().

%%--------------------------------------------------------------------
%% Phone
%%--------------------------------------------------------------------

%% @doc Returns whether the given term is a valid Brazilian phone
%% number, mobile or landline.
%% @see brutils_phone:is_valid/1
-spec is_valid_phone(term()) -> boolean().
is_valid_phone(Phone) ->
    brutils_phone:is_valid(Phone).

%% @doc Returns whether the given term is a valid Brazilian phone
%% number of the given type (`mobile' or `landline').
%% @see brutils_phone:is_valid/2
-spec is_valid_phone(term(), brutils_phone:phone_type()) -> boolean().
is_valid_phone(Phone, Type) ->
    brutils_phone:is_valid(Phone, Type).

%% @doc Formats a valid phone number for display
%% (`<<"(DD)NNNNN-NNNN">>' / `<<"(DD)NNNN-NNNN">>').
%% @see brutils_phone:format/1
-spec format_phone(binary()) -> {ok, binary()} | {error, invalid}.
format_phone(Phone) ->
    brutils_phone:format(Phone).

%% @doc Removes common phone punctuation: `(', `)', `-', `+' and
%% spaces (dots are kept).
%% @see brutils_phone:remove_symbols/1
-spec remove_symbols_phone(binary()) -> binary().
remove_symbols_phone(Phone) ->
    brutils_phone:remove_symbols(Phone).

%% @doc Removes the Brazilian international dialing code (`55') from
%% a phone number; see the domain module for the sharp edges.
%% @see brutils_phone:remove_international_dialing_code/1
-spec remove_international_dialing_code(binary()) -> binary().
remove_international_dialing_code(Phone) ->
    brutils_phone:remove_international_dialing_code(Phone).

%% @doc Generates a random valid phone number of a random type.
%% @see brutils_phone:generate/0
-spec generate_phone() -> binary().
generate_phone() ->
    brutils_phone:generate().

%% @doc Generates a random valid phone number of the given type.
%% @see brutils_phone:generate/1
-spec generate_phone(brutils_phone:phone_type()) -> binary().
generate_phone(Type) ->
    brutils_phone:generate(Type).

%%--------------------------------------------------------------------
%% Passport
%%--------------------------------------------------------------------

%% @doc Returns whether the given term is a valid passport number
%% (2 uppercase letters + 6 digits; case-sensitive, no stripping).
%% @see brutils_passport:is_valid/1
-spec is_valid_passport(term()) -> boolean().
is_valid_passport(Passport) ->
    brutils_passport:is_valid(Passport).

%% @doc Normalizes (uppercases, strips symbols) and formats a
%% passport number — the lenient counterpart to
%% {@link is_valid_passport/1}.
%% @see brutils_passport:format/1
-spec format_passport(binary()) ->
        {ok, brutils_passport:passport()} | {error, invalid}.
format_passport(Passport) ->
    brutils_passport:format(Passport).

%% @doc Removes the symbols `-', `.' and spaces from a passport
%% string (case is preserved).
%% @see brutils_passport:remove_symbols/1
-spec remove_symbols_passport(binary()) -> binary().
remove_symbols_passport(Passport) ->
    brutils_passport:remove_symbols(Passport).

%% @doc Generates a random valid passport number.
%% @see brutils_passport:generate/0
-spec generate_passport() -> brutils_passport:passport().
generate_passport() ->
    brutils_passport:generate().

%%--------------------------------------------------------------------
%% License plate
%%--------------------------------------------------------------------

%% @doc Returns whether the given term is a valid license plate of
%% either pattern (old format or Mercosul).
%% @see brutils_license_plate:is_valid/1
-spec is_valid_license_plate(term()) -> boolean().
is_valid_license_plate(Plate) ->
    brutils_license_plate:is_valid(Plate).

%% @doc Returns whether the given term is a valid license plate of
%% the given pattern (`old_format' or `mercosul').
%% @see brutils_license_plate:is_valid/2
-spec is_valid_license_plate(term(), brutils_license_plate:plate_type()) ->
        boolean().
is_valid_license_plate(Plate, Type) ->
    brutils_license_plate:is_valid(Plate, Type).

%% @doc Formats a valid license plate for display (old format gets a
%% dash, Mercosul comes out bare; both uppercased).
%% @see brutils_license_plate:format/1
-spec format_license_plate(binary()) ->
        {ok, brutils_license_plate:formatted_plate()} | {error, invalid}.
format_license_plate(Plate) ->
    brutils_license_plate:format(Plate).

%% @doc Removes the dash (`-') from a license plate string.
%% @see brutils_license_plate:remove_symbols/1
-spec remove_symbols_license_plate(binary()) -> binary().
remove_symbols_license_plate(Plate) ->
    brutils_license_plate:remove_symbols(Plate).

%% @doc Converts an old-format plate to the Mercosul pattern.
%% @see brutils_license_plate:convert_to_mercosul/1
-spec convert_license_plate_to_mercosul(binary()) ->
        {ok, brutils_license_plate:plate()} | {error, invalid}.
convert_license_plate_to_mercosul(Plate) ->
    brutils_license_plate:convert_to_mercosul(Plate).

%% @doc Detects the pattern of a license plate (`old_format' or
%% `mercosul').
%% @see brutils_license_plate:get_format/1
-spec get_format_license_plate(binary()) ->
        {ok, brutils_license_plate:plate_type()} | {error, invalid}.
get_format_license_plate(Plate) ->
    brutils_license_plate:get_format(Plate).

%% @doc Generates a random valid Mercosul plate.
%% @see brutils_license_plate:generate/0
-spec generate_license_plate() -> {ok, brutils_license_plate:plate()}.
generate_license_plate() ->
    brutils_license_plate:generate().

%% @doc Generates a random valid plate in the given pattern
%% (`<<"LLLNNNN">>' or `<<"LLLNLNN">>').
%% @see brutils_license_plate:generate/1
-spec generate_license_plate(binary()) ->
        {ok, brutils_license_plate:plate()} | {error, invalid}.
generate_license_plate(Pattern) ->
    brutils_license_plate:generate(Pattern).

%%--------------------------------------------------------------------
%% Voter ID
%%--------------------------------------------------------------------

%% @doc Returns whether the given term is a valid voter id (título de
%% eleitor); 12 digits, or 13 for some São Paulo / Minas Gerais
%% titles.
%% @see brutils_voter_id:is_valid/1
-spec is_valid_voter_id(term()) -> boolean().
is_valid_voter_id(VoterId) ->
    brutils_voter_id:is_valid(VoterId).

%% @doc Formats a valid 12-digit voter id for display
%% (`<<"NNNN NNNN NN NN">>'); valid 13-digit titles are refused
%% rather than truncated.
%% @see brutils_voter_id:format/1
-spec format_voter_id(binary()) ->
        {ok, brutils_voter_id:formatted_voter_id()} | {error, invalid}.
format_voter_id(VoterId) ->
    brutils_voter_id:format(VoterId).

%% @doc Generates a random valid voter id for a title issued abroad
%% (federative union `ZZ').
%% @see brutils_voter_id:generate/0
-spec generate_voter_id() -> {ok, brutils_voter_id:voter_id()}.
generate_voter_id() ->
    brutils_voter_id:generate().

%% @doc Generates a random valid voter id for the given federative
%% union (two-letter code, case insensitive).
%% @see brutils_voter_id:generate/1
-spec generate_voter_id(binary()) ->
        {ok, brutils_voter_id:voter_id()} | {error, invalid}.
generate_voter_id(Uf) ->
    brutils_voter_id:generate(Uf).