### Install Brazilian Utils with Yarn

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/getting-started.md

Install the library using the yarn package manager.

```bash
yarn add @brazilian-utils/brazilian-utils
```

--------------------------------

### Install Brazilian Utils with npm

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/getting-started.md

Install the library using npm for use in your Node.js projects.

```bash
npm install --save @brazilian-utils/brazilian-utils
```

--------------------------------

### Common Development Commands

Source: https://github.com/brazilian-utils/javascript/blob/main/README.md

Execute common development tasks such as installation, checks, testing, and building using the `vp` toolchain.

```bash
vp install
vp check
vp test
vp run build
```

--------------------------------

### Get Municipality Info or IBGE Code

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Fetches municipality information (name and UF) using an IBGE code, or retrieves the IBGE code from a municipality name and UF. Requires an asynchronous context.

```javascript
import { getMunicipality } from '@brazilian-utils/brazilian-utils';

await getMunicipality({ code: '3550308' });
// ['São Paulo', 'SP']

await getMunicipality({ municipalityName: 'São Paulo', uf: 'SP' });
// '3550308'
```

--------------------------------

### Get Legal Natures Map

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Retrieves a map of legal natures where keys are the codes and values are their descriptions. Useful for lookups.

```javascript
import { getLegalNatures } from '@brazilian-utils/brazilian-utils';

const legalNatures = getLegalNatures();

legalNatures['2062']; // 'Sociedade Empresária Limitada'
```

--------------------------------

### Get Brazilian Cities (v2)

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Retrieves a list of Brazilian cities, which are now sorted alphabetically by default. This applies to both national and state-specific queries.

```javascript
getCities(); // Returns sorted alphabetically
getCities('SP'); // Returns sorted alphabetically
```

--------------------------------

### Get Brazilian Holidays

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Retrieves national and state-specific Brazilian holidays for a given year. Ensure the library is imported correctly.

```javascript
import { getHolidays } from '@brazilian-utils/brazilian-utils';

// Get all national holidays
const holidays = getHolidays(2024);

// Get holidays for a specific state
const spHolidays = getHolidays({ year: 2024, stateCode: 'SP' });
```

--------------------------------

### Get All Brazilian States

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Retrieves a list of all Brazilian states, each with its code and name. This function requires no arguments.

```javascript
import { getStates } from '@brazilian-utils/brazilian-utils';

getStates();
// [ 
//   { code: 'AC', name: 'Acre' },
//   { code: 'AL', name: 'Alagoas' },
//   { code: 'AP', name: 'Amapá' },
//   { code: 'AM', name: 'Amazonas' },
//   { code: 'BA', name: 'Bahia' },
//   { code: 'CE', name: 'Ceará' },
//   { code: 'DF', name: 'Distrito Federal' },
//   { code: 'ES', name: 'Espírito Santo' },
//   { code: 'GO', name: 'Goiás' },
//   { code: 'MA', name: 'Maranhão' },
//   { code: 'MT', name: 'Mato Grosso' },
//   { code: 'MS', name: 'Mato Grosso do Sul' },
//   { code: 'MG', name: 'Minas Gerais' },
//   { code: 'PA', name: 'Pará' },
//   { code: 'PB', name: 'Paraíba' },
//   { code: 'PR', name: 'Paraná' },
//   { code: 'PE', name: 'Pernambuco' },
//   { code: 'PI', name: 'Piauí' },
//   { code: 'RJ', name: 'Rio de Janeiro' },
//   { code: 'RN', name: 'Rio Grande do Norte' },
//   { code: 'RS', name: 'Rio Grande do Sul' },
//   { code: 'RO', name: 'Rondônia' },
//   { code: 'RR', name: 'Roraima' },
//   { code: 'SC', name: 'Santa Catarina' },
//   { code: 'SP', name: 'São Paulo' },
//   { code: 'SE', name: 'Sergipe' },
//   { code: 'TO', name: 'Tocantins' },
// ]
```

--------------------------------

### Get Brazilian Cities (v1)

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

This is the previous behavior of `getCities` which returned an unsorted array of cities. The function now returns results sorted alphabetically.

```javascript
getCities(); // Returned unsorted array
getCities('SP'); // Returned unsorted array
```

--------------------------------

### Get Brazilian Cities

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Retrieves a list of Brazilian cities. If no state code is provided, it returns all cities; otherwise, it returns cities for the specified state. Results are sorted alphabetically.

```javascript
import { getCities } from '@brazilian-utils/brazilian-utils';

// Return all Brazilian cities (sorted alphabetically).
getCities();
// [ 
//   'Abadia de Goiás',
//   'Abadia dos Dourados',
//   'Abadiânia',
//   'Abaeté',
//   'Abaetetuba',
//   'Abaiara',
//   'Abaíra',
//   'Abaré',
//   'Abatiá',
//   'Abdon Batista',
//   ... 5460 more items
// ]

// Return all Brazilian cities of the São Paulo state (sorted alphabetically).
getCities('SP');
// [ 
//   "Adamantina",
//   "Adolfo",
//   "Aguaí",
//   "Águas da Prata",
//   "Águas de Lindóia",
//   "Águas de Santa Bárbara",
//   "Águas de São Pedro",
//   "Agudos",
//   "Alambari",
//   "Alfredo Marcondes",
//   ... 635 more items
// ]
```

--------------------------------

### Get Brazilian Holidays

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Retrieves a list of Brazilian holidays for a given year. It can return national holidays, and optionally include state-specific holidays if a state code is provided.

```javascript
import { getHolidays } from '@brazilian-utils/brazilian-utils';

// Get all national holidays for 2024
getHolidays(2024);
// [ 
//   { name: 'Ano novo', date: Date('2024-01-01') },
//   { name: 'Carnaval (terça-feira)', date: Date('2024-02-13') },
//   { name: 'Sexta-feira Santa', date: Date('2024-03-29') },
//   { name: 'Páscoa', date: Date('2024-03-31') },
//   // ... more holidays
// ]

// Get holidays for a specific state
getHolidays({ year: 2024, stateCode: 'SP' });
// Includes national holidays plus state-specific holidays (e.g., "Revolução Constitucionalista")
```

--------------------------------

### Running Browser Tests

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Execute browser-specific tests using npm scripts. These commands ensure cross-browser compatibility for your application.

```bash
npm run test:chrome-browser
```

```bash
npm run test:firefox-browser
```

```bash
npm run test:safari-browser
```

```bash
npm run test:edge-browser
```

--------------------------------

### Fetch Address Info by CEP (v1)

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

This is the previous version of `getAddressInfoByCep` which only accepted a CEP string. It is still functional but lacks new features.

```javascript
const address = await getAddressInfoByCep('01310100');
```

--------------------------------

### Handle `getAddressInfoByCep` Errors

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Demonstrates how to handle specific error types thrown by `getAddressInfoByCep` in v2, including validation, not found, and service errors. Ensure you import the necessary error classes.

```javascript
import {
  getAddressInfoByCep,
  GetAddressInfoByCepValidationError,
  GetAddressInfoByCepNotFoundError,
  GetAddressInfoByCepServiceError
} from '@brazilian-utils/brazilian-utils';

try {
  const address = await getAddressInfoByCep('01310100');
} catch (error) {
  if (error instanceof GetAddressInfoByCepValidationError) {
    // Handle validation error
  } else if (error instanceof GetAddressInfoByCepNotFoundError) {
    // Handle not found error
  } else if (error instanceof GetAddressInfoByCepServiceError) {
    // Handle service error
  }
}
```

--------------------------------

### Include Brazilian Utils via Script Tag

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/getting-started.md

Include the library directly in your HTML using a script tag for global access.

```html
<script src="https://unpkg.com/@brazilian-utils/brazilian-utils/dist/brazilian-utils.cjs.production.min.js"></script>
```

--------------------------------

### Importing Specific Functions with ES Modules

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Use ES module imports to include only the functions you need, enabling better tree shaking in modern bundlers. This is the recommended way to import from v2.x.

```javascript
import { isValidCpf, formatCpf } from '@brazilian-utils/brazilian-utils';
```

--------------------------------

### Import and Use isValidCpf

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/getting-started.md

Import and use the isValidCpf function from the library. Ensure the function is imported correctly before calling it.

```javascript
import { isValidCpf } from '@brazilian-utils/brazilian-utils';

isValidCpf('1232454233345'); // false
```

--------------------------------

### Migrate from v1 to v2 Imports and Function Calls

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Update your import statements and function calls to use the new camelCase names in v2. Existing code using PascalCase names will work but will generate deprecation warnings.

```javascript
import { isValidCPF, formatCPF, generateCNPJ } from '@brazilian-utils/brazilian-utils';

const isValid = isValidCPF('12345678909');
const formatted = formatCPF('12345678909');
const cnpj = generateCNPJ();
```

```javascript
import { isValidCpf, formatCpf, generateCnpj } from '@brazilian-utils/brazilian-utils';

const isValid = isValidCpf('12345678909');
const formatted = formatCpf('12345678909');
const cnpj = generateCnpj();
```

--------------------------------

### Currency Formatting

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Formats numbers into a Brazilian Real (BRL) currency string.

```APIDOC
## formatCurrency

### Description
Formats an integer or float to a string in the BRL pattern

### Method
`formatCurrency(value: number, options?: { precision?: number }): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { formatCurrency } from '@brazilian-utils/brazilian-utils';

formatCurrency(10); // 10,00
formatCurrency(10756.11); // 10.756,11
formatCurrency(10756.123, { precision: 3 }); // 10.756,123
```

### Response
#### Success Response (200)
`string` - The formatted currency string.

#### Response Example
```json
"10,00"
```
```

--------------------------------

### Parse Processo Jurídico

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Removes 'processo jurídico' formatting, keeping only digits and capping the result to 20 digits.

```javascript
import { parseProcessoJuridico } from '@brazilian-utils/brazilian-utils';

parseProcessoJuridico('0002080-25.2012.515.0049'); // 00020802520125150049
```

--------------------------------

### Fetch Address Info by CEP

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Fetches address information for a given CEP using multiple providers. Accepts CEP as string or number.

```javascript
import { getAddressInfoByCep } from '@brazilian-utils/brazilian-utils';

// Using all providers (default)
const address = await getAddressInfoByCep('01310100');
// { cep: '01310100', state: 'SP', city: 'São Paulo', neighborhood: 'Bela Vista', street: 'Avenida Paulista' }

// Using specific providers
const address = await getAddressInfoByCep('01310-100', {
  providers: ['viacep', 'brasilapi']
});

// Using number input (will be padded automatically)
const address = await getAddressInfoByCep(1310100);
```

--------------------------------

### Fetch Address Info by CEP (v2)

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Fetches address information using a CEP. This version supports additional options for providers and accepts CEPs with or without hyphens, as well as numeric inputs.

```javascript
// Still works the same way
const address = await getAddressInfoByCep('01310100');

// But now supports options
const address = await getAddressInfoByCep('01310-100', {
  providers: ['viacep', 'brasilapi']
});

// Also accepts numbers (will be padded automatically)
const address = await getAddressInfoByCep(1310100);
```

--------------------------------

### Address Utilities

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Utilities for fetching CEP information from an address.

```APIDOC
## getCepInfoByAddress

### Description
Fetch CEPs from an address using ViaCEP.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Request Body
- **federalUnit** (string) - Required - The federal unit (state) abbreviation.
- **city** (string) - Required - The city name.
- **street** (string) - Required - The street name.

### Request Example
```json
{
  "federalUnit": "SP",
  "city": "Sao Paulo",
  "street": "Avenida Paulista"
}
```

### Response
#### Success Response (200)
- **Array of Objects** - Each object contains CEP details.
  - **cep** (string) - The postal code.
  - **logradouro** (string) - The street name.
  - **complemento** (string) - The complement.
  - **bairro** (string) - The neighborhood.
  - **localidade** (string) - The city.
  - **uf** (string) - The federal unit (state).

### Response Example
```json
[
  {
    "cep": "01310100",
    "logradouro": "Avenida Paulista",
    "complemento": "lado par",
    "bairro": "Bela Vista",
    "localidade": "São Paulo",
    "uf": "SP"
  }
]
```
```

--------------------------------

### getBoletoInfo

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Extracts key information such as amount, expiration date, and bank code from a boleto string.

```APIDOC
## getBoletoInfo

### Description
Extract information from a boleto (amount, expiration date, bank code).

### Method
`getBoletoInfo(boletoString: string): BoletoInfo`

### Parameters
#### Path Parameters
- **boletoString** (string) - Required - The boleto number string.

### Request Example
```javascript
import { getBoletoInfo } from '@brazilian-utils/brazilian-utils';

const info = getBoletoInfo('00190000090114971860168524522114675860000102656');
```

### Response
#### Success Response (200)
- **amount** (number) - The monetary amount of the boleto.
- **expirationDate** (Date) - The expiration date of the boleto.
- **bankCode** (string) - The bank code associated with the boleto.

#### Response Example
```json
{
  "amount": 102656,
  "expirationDate": "2023-10-27T00:00:00.000Z",
  "bankCode": "001"
}
```
```

--------------------------------

### getStates

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Retrieves a list of all Brazilian states.

```APIDOC
## getStates

### Description
Get all Brazilian states.

### Method
N/A (This is a utility function, not an API endpoint)

### Endpoint
N/A

### Parameters
None

### Request Example
```javascript
import { getStates } from '@brazilian-utils/brazilian-utils';

getStates();
// [
//   { code: 'AC', name: 'Acre' },
//   { code: 'AL', name: 'Alagoas' },
//   // ... more states
// ]
```

### Response
- **Array of Objects**: Each object contains `code` (string) and `name` (string) for a Brazilian state.

```

--------------------------------

### Address Information by CEP

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Fetches address details for a given CEP using multiple external providers.

```APIDOC
## getAddressInfoByCep

### Description
Fetch address information for a given CEP using multiple providers.

### Method
`getAddressInfoByCep(cep: string | number, options?: { providers?: ('viacep' | 'brasilapi')[] }): Promise<AddressInfo>

interface AddressInfo {
  cep: string;
  state: string;
  city: string;
  neighborhood: string;
  street: string;
}

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { getAddressInfoByCep } from '@brazilian-utils/brazilian-utils';

// Using all providers (default)
const address = await getAddressInfoByCep('01310100');
// { cep: '01310100', state: 'SP', city: 'São Paulo', neighborhood: 'Bela Vista', street: 'Avenida Paulista' }

// Using specific providers
const address = await getAddressInfoByCep('01310-100', {
  providers: ['viacep', 'brasilapi']
});

// Using number input (will be padded automatically)
const address = await getAddressInfoByCep(1310100);
```

### Response
#### Success Response (200)
`Promise<AddressInfo>` - An object containing address details.

#### Response Example
```json
{
  "cep": "01310100",
  "state": "SP",
  "city": "São Paulo",
  "neighborhood": "Bela Vista",
  "street": "Avenida Paulista"
}
```
```

--------------------------------

### Capitalization Utility

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Transforms the first letter of each word to uppercase, optionally ignoring or enforcing case for specific words.

```APIDOC
## capitalize

### Description
Transforms the first letter into a capital one of each word ignoring prepositions.

### Method
`capitalize(text: string, options?: { lowerCaseWords?: string[], upperCaseWords?: string[] }): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { capitalize } from '@brazilian-utils/brazilian-utils';

capitalize('josé e maria'); // José e Maria
capitalize('josé Ama MARIA', { lowerCaseWords: ['ama'] }); // José ama Maria
capitalize('doc inválido', { upperCaseWords: ['DOC'] }); // DOC Inválido
```

### Response
#### Success Response (200)
`string` - The capitalized string.

#### Response Example
```json
"José e Maria"
```
```

--------------------------------

### Import and Use isValidCpf Utility

Source: https://github.com/brazilian-utils/javascript/blob/main/README.md

Import the `isValidCpf` function from the library and use it to validate a CPF number. Ensure the CPF format is correct for accurate validation.

```javascript
import { isValidCpf } from "@brazilian-utils/brazilian-utils";

isValidCpf("1232454233345"); // false
```

--------------------------------

### Implement Custom Random Number Generation

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

This function is no longer exported and should be replaced with a custom implementation. Use this snippet as a reference for creating your own.

```javascript
// v1 - Don't use this anymore
import { generateRandomNumber } from '@brazilian-utils/brazilian-utils';

// v2 - Use your own implementation
function generateRandomNumber(length) {
  let result = '';
  for (let i = 0; i < length; i++) {
    result += Math.floor(Math.random() * 10).toString();
  }
  return result;
}
```

--------------------------------

### Accessing Removed `generateChecksum` Helper (Internal)

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

The `generateChecksum` function is no longer part of the public API. Importing it from internal modules is not recommended as it may change without notice.

```javascript
// v1 - Don't use this anymore
import { generateChecksum } from '@brazilian-utils/brazilian-utils';

// v2 - If you absolutely need it, import from internals (not recommended)
// This is not part of the public API and may change without notice
import { generateChecksum } from '@brazilian-utils/brazilian-utils/dist/_internals/generate-checksum/generate-checksum';
```

--------------------------------

### getCities

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Retrieves a list of Brazilian cities, with results now sorted alphabetically.

```APIDOC
## getCities

### Description
Returns a list of Brazilian cities. In v2.0.0 and later, the results are always sorted alphabetically.

### Method
`getCities(stateCode?: string): string[]`

### Parameters
#### Query Parameters
- **stateCode** (string) - Optional - The two-letter state code (e.g., 'SP') to filter cities for a specific state. If omitted, returns cities for all states.

### Request Example
```javascript
import { getCities } from '@brazilian-utils/brazilian-utils';

// Get all cities, sorted alphabetically
const allCities = getCities();

// Get cities for a specific state, sorted alphabetically
const spCities = getCities('SP');
```

### Response
#### Success Response (200)
- **cities** (Array<string>) - An array of city names, sorted alphabetically.

#### Response Example
```json
[
  "Adamantina",
  "Adolfo",
  "Aguaí",
  "..."
]
```
```

--------------------------------

### PIS Utilities

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Utilities for generating PIS numbers.

```APIDOC
## generatePis

### Description
Generate a valid random PIS.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Response
- **string** - A valid random PIS number.
```

--------------------------------

### Generate CNPJ with Version Specification

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Always specify the version when generating CNPJ to ensure predictable behavior, as the default will change in v3.0.0.

```javascript
generateCnpj(1); // Always generates numeric CNPJ
generateCnpj(2); // Always generates alphanumeric CNPJ

// Not recommended: Relying on default behavior
generateCnpj(); // Currently generates numeric (v1), but will be random in v3.0.0
```

--------------------------------

### Format Processo Jurídico

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Formats a 'processo jurídico' number according to CNJ's definition.

```javascript
import { formatProcessoJuridico } from '@brazilian-utils/brazilian-utils';

formatProcessoJuridico('00020802520125150049'); // 0002080-25.2012.515.0049
```

--------------------------------

### Boleto Utilities

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Utilities for validating, formatting, parsing, and generating Brazilian Boleto bancário numbers.

```APIDOC
## isValidBoleto

### Description
Check if boleto (Brazilian payment method) is valid.

### Method
`isValidBoleto(boleto: string): boolean`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { isValidBoleto } from '@brazilian-utils/brazilian-utils';

isValidBoleto('00190000090114971860168524522114675860000102656'); // true
```

### Response
#### Success Response (200)
- **boolean**: True if the boleto is valid, false otherwise.

#### Response Example
```json
{
  "isValid": true
}
```
```

```APIDOC
## formatBoleto

### Description
Format a boleto number.

### Method
`formatBoleto(boleto: string, options?: { pad?: boolean }): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { formatBoleto } from '@brazilian-utils/brazilian-utils';

formatBoleto('00190000090114971860168524522114675860000102656'); // 00190.00009 01149.718601 68524.522114 6 75860000102656
formatBoleto('1900000901149', { pad: true }); // 00000.00000 00000.000019 00000.901149 0 00000000000000
```

### Response
#### Success Response (200)
- **string**: The formatted boleto number.

#### Response Example
```json
{
  "formattedBoleto": "00190.00009 01149.718601 68524.522114 6 75860000102656"
}
```
```

```APIDOC
## parseBoleto

### Description
Remove boleto formatting, keep only digits, and cap the result to 47 digits.

### Method
`parseBoleto(boleto: string): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { parseBoleto } from '@brazilian-utils/brazilian-utils';

parseBoleto('00190.00009 01149.718601 68524.522114 6 75860000102656'); // 00190000090114971860168524522114675860000102656
```

### Response
#### Success Response (200)
- **string**: The parsed boleto number with only digits.

#### Response Example
```json
{
  "parsedBoleto": "00190000090114971860168524522114675860000102656"
}
```
```

```APIDOC
## generateBoleto

### Description
Generate a valid random boleto.

### Method
`generateBoleto(): string`

### Parameters
None

### Request Example
```javascript
import { generateBoleto } from '@brazilian-utils/brazilian-utils';

generateBoleto(); // "00190000090114971860168524522114675860000102656"
```

### Response
#### Success Response (200)
- **string**: A valid random boleto number.

#### Response Example
```json
{
  "generatedBoleto": "00190000090114971860168524522114675860000102656"
}
```
```

```APIDOC
## getBoletoInfo

### Description
Extract information from a boleto (amount, expiration date, bank code).

### Method
`getBoletoInfo(boleto: string): { amount: number, expirationDate: Date, bankCode: string }`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { getBoletoInfo } from '@brazilian-utils/brazilian-utils';

getBoletoInfo('00190000090114971860168524522114675860000102656');
// { amount: 102656, expirationDate: Date, bankCode: '001' }
```

### Response
#### Success Response (200)
- **object**: An object containing the amount, expiration date, and bank code.
  - **amount** (number): The amount of the boleto.
  - **expirationDate** (Date): The expiration date of the boleto.
  - **bankCode** (string): The bank code associated with the boleto.

#### Response Example
```json
{
  "amount": 102656,
  "expirationDate": "2023-10-27T00:00:00.000Z",
  "bankCode": "001"
}
```
```

--------------------------------

### Format Currency (BRL)

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Formats an integer or float to a string in the Brazilian Real (BRL) pattern. Allows specifying precision.

```javascript
import { formatCurrency } from '@brazilian-utils/brazilian-utils';

formatCurrency(10); // 10,00
formatCurrency(10756.11); // 10.756,11
formatCurrency(10756.123, { precision: 3 }); // 10.756,123
```

--------------------------------

### Legal Document Utilities

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Utilities for generating and formatting legal document numbers and codes.

```APIDOC
## generateProcessoJuridico

### Description
Generate a valid random processo jurídico number according to CNJ's definition.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Request Body
- **year** (number) - Optional - The year for the processo jurídico number.
- **court** (number) - Optional - The court number for the processo jurídico number.

### Request Example
```json
{
  "year": 2026,
  "court": 5
}
```

### Response
- **string** - A randomly generated processo jurídico number, or null if parameters are invalid.
```

```APIDOC
## formatLegalNature

### Description
Format a legal nature code.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Request Body
- **code** (string) - Required - The legal nature code to format.

### Response
- **string** - The formatted legal nature code.
```

```APIDOC
## isValidLegalNature

### Description
Check if a legal nature code exists in the official list.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Request Body
- **code** (string) - Required - The legal nature code to validate.

### Response
- **boolean** - True if the code is valid, false otherwise.
```

```APIDOC
## generateLegalNature

### Description
Generate a random valid legal nature code.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Response
- **string** - A randomly generated valid legal nature code.
```

```APIDOC
## parseLegalNature

### Description
Remove legal nature formatting, keep only digits, and cap the result to 4 digits.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Request Body
- **formattedCode** (string) - Required - The formatted legal nature code.

### Response
- **string** - The parsed and capped legal nature code.
```

```APIDOC
## getLegalNatures

### Description
Get the legal nature map keyed by code.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Response
- **object** - A map where keys are legal nature codes and values are their descriptions.
```

--------------------------------

### Capitalize Words

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Transforms the first letter of each word into a capital one, ignoring prepositions. Can specify words to force uppercase or lowercase.

```javascript
import { capitalize } from '@brazilian-utils/brazilian-utils';

capitalize('josé e maria'); // José e Maria
capitalize('josé Ama MARIA', { lowerCaseWords: ['ama'] }); // José ama Maria
capitalize('doc inválido', { upperCaseWords: ['DOC'] }); // DOC Inválido
```

--------------------------------

### PIS Validation, Formatting, and Parsing

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Utilities for validating, formatting, and parsing Brazilian PIS numbers.

```APIDOC
## isValidPis

### Description
Check if PIS is valid.

### Method
`isValidPis(pis: string): boolean`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { isValidPis } from '@brazilian-utils/brazilian-utils';

isValidPis('12056412547'); // false
```

### Response
#### Success Response (200)
`boolean` - True if the PIS is valid, false otherwise.

#### Response Example
```json
false
```
```

```APIDOC
## formatPis

### Description
Format PIS number.

### Method
`formatPis(pis: string, options?: { pad?: boolean }): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { formatPis } from '@brazilian-utils/brazilian-utils';

formatPis('12345678901'); // 123.45678.90-1
formatPis('123456789', { pad: true }); // 001.23456.78-9
```

### Response
#### Success Response (200)
`string` - The formatted PIS number.

#### Response Example
```json
"123.45678.90-1"
```
```

```APIDOC
## parsePis

### Description
Remove PIS formatting, keep only digits, and cap the result to 11 digits.

### Method
`parsePis(pis: string): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { parsePis } from '@brazilian-utils/brazilian-utils';

parsePis('123.45678.90-1'); // 12345678901
```

### Response
#### Success Response (200)
`string` - The parsed PIS number (digits only, max 11 digits).

#### Response Example
```json
"12345678901"
```
```

--------------------------------

### getAddressInfoByCep

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Fetches address information using a CEP (Brazilian postal code). Supports multiple providers and improved error handling.

```APIDOC
## getAddressInfoByCep

### Description
Retrieve address information based on a CEP (Brazilian postal code). This function has been updated to support multiple providers and enhanced error handling.

### Method
`getAddressInfoByCep(cep: string | number, options?: { providers?: string[] }): Promise<AddressInfo>`

### Parameters
#### Path Parameters
- **cep** (string | number) - Required - The CEP to search for. Can be a string (e.g., '01310-100' or '01310100') or a number.

#### Query Parameters
- **providers** (Array<string>) - Optional - An array of provider names (e.g., ['viacep', 'brasilapi']) to use for fetching the address. Defaults to all available providers.

### Request Example
```javascript
import { getAddressInfoByCep } from '@brazilian-utils/brazilian-utils';

// Basic usage (still works)
const address = await getAddressInfoByCep('01310100');

// Using options to specify providers
const addressWithProviders = await getAddressInfoByCep('01310-100', {
  providers: ['viacep', 'brasilapi']
});

// Using a number for CEP
const addressFromNumber = await getAddressInfoByCep(1310100);
```

### Response
#### Success Response (200)
- **street** (string) - The street name.
- **neighborhood** (string) - The neighborhood.
- **city** (string) - The city name.
- **state** (string) - The state abbreviation (e.g., 'SP').
- **zipcode** (string) - The CEP.

#### Response Example
```json
{
  "street": "Avenida Paulista",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "zipcode": "01310-100"
}
```

### Error Handling
This function now exports specific error classes for better error management:
- `GetAddressInfoByCepValidationError`: Thrown for invalid input (e.g., invalid CEP format).
- `GetAddressInfoByCepNotFoundError`: Thrown when no address is found for the given CEP.
- `GetAddressInfoByCepServiceError`: Thrown when there's an issue with the external service provider.

#### Error Handling Example
```javascript
import {
  getAddressInfoByCep,
  GetAddressInfoByCepValidationError,
  GetAddressInfoByCepNotFoundError,
  GetAddressInfoByCepServiceError
} from '@brazilian-utils/brazilian-utils';

try {
  const address = await getAddressInfoByCep('invalid-cep');
} catch (error) {
  if (error instanceof GetAddressInfoByCepValidationError) {
    console.error('Validation Error:', error.message);
  } else if (error instanceof GetAddressInfoByCepNotFoundError) {
    console.error('Not Found Error:', error.message);
  } else if (error instanceof GetAddressInfoByCepServiceError) {
    console.error('Service Error:', error.message);
  } else {
    console.error('An unexpected error occurred:', error);
  }
}
```
```

--------------------------------

### Holiday Utilities

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Utilities for checking Brazilian holidays.

```APIDOC
## isHoliday

### Description
Check if a specific date is a Brazilian holiday.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Request Body
- **targetDate** (Date) - Required - The date to check.
- **stateCode** (string) - Optional - The state code to check for state-specific holidays.

### Request Example
```json
{
  "targetDate": "2024-01-01"
}
```

```json
{
  "targetDate": "2024-07-09",
  "stateCode": "SP"
}
```

### Response
- **boolean** - True if the date is a holiday, false otherwise.
```

--------------------------------

### Municipality Utilities

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Utilities for retrieving municipality information and IBGE codes.

```APIDOC
## getMunicipality

### Description
Get municipality information by IBGE code, or get an IBGE code from municipality name and UF.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
#### Request Body
- **code** (string) - Optional - The IBGE code of the municipality.
- **municipalityName** (string) - Optional - The name of the municipality.
- **uf** (string) - Optional - The federal unit (state) abbreviation.

### Request Example
```json
{
  "code": "3550308"
}
```

```json
{
  "municipalityName": "São Paulo",
  "uf": "SP"
}
```

### Response
- **Array of strings** - If searching by code, returns `[municipalityName, uf]`.
- **string** - If searching by name and UF, returns the IBGE code.
```

--------------------------------

### Extract Boleto Information

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/migration-v1-to-v2.md

Parses a boleto string to extract key information such as amount, expiration date, and bank code. The input must be a valid boleto string.

```javascript
import { getBoletoInfo } from '@brazilian-utils/brazilian-utils';

const info = getBoletoInfo('00190000090114971860168524522114675860000102656');
// { amount: 102656, expirationDate: Date, bankCode: '001' }
```

--------------------------------

### Email Utilities

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Utilities for validating email addresses.

```APIDOC
## isValidEmail

### Description
Check if email is valid.

### Method
`isValidEmail(email: string): boolean`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { isValidEmail } from '@brazilian-utils/brazilian-utils';

isValidEmail('john.doe@hotmail.com'); // true
```

### Response
#### Success Response (200)
- **boolean**: True if the email is valid, false otherwise.

#### Response Example
```json
{
  "isValid": true
}
```
```

--------------------------------

### Legal Process Number Validation, Formatting, and Parsing

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Utilities for validating, formatting, and parsing Brazilian legal process numbers according to CNJ standards.

```APIDOC
## isValidProcessoJuridico

### Description
Validate the processo jurídico number according to [CNJ's definition](https://www.conjur.com.br/dl/resolucao-65-cnj.pdf).

### Method
`isValidProcessoJuridico(processo: string): boolean`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { isValidProcessoJuridico } from '@brazilian-utils/brazilian-utils';

isValidProcessoJuridico('00020802520125150049'); // true
```

### Response
#### Success Response (200)
`boolean` - True if the legal process number is valid, false otherwise.

#### Response Example
```json
true
```
```

```APIDOC
## formatProcessoJuridico

### Description
Format the processo jurídico number according to [CNJ's definition](https://www.conjur.com.br/dl/resolucao-65-cnj.pdf).

### Method
`formatProcessoJuridico(processo: string): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { formatProcessoJuridico } from '@brazilian-utils/brazilian-utils';

formatProcessoJuridico('00020802520125150049'); // 0002080-25.2012.515.0049
```

### Response
#### Success Response (200)
`string` - The formatted legal process number.

#### Response Example
```json
"0002080-25.2012.515.0049"
```
```

```APIDOC
## parseProcessoJuridico

### Description
Remove processo jurídico formatting, keep only digits, and cap the result to 20 digits.

### Method
`parseProcessoJuridico(processo: string): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { parseProcessoJuridico } from '@brazilian-utils/brazilian-utils';

parseProcessoJuridico('0002080-25.2012.515.0049'); // 00020802520125150049
```

### Response
#### Success Response (200)
`string` - The parsed legal process number (digits only, max 20 digits).

#### Response Example
```json
"00020802520125150049"
```
```

--------------------------------

### CPF Utilities

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Utilities for validating, formatting, parsing, and generating Brazilian CPF (Cadastro de Pessoas Físicas) numbers.

```APIDOC
## isValidCpf

### Description
Check if CPF is valid.

### Method
`isValidCpf(cpf: string): boolean`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { isValidCpf } from '@brazilian-utils/brazilian-utils';

isValidCpf('155151475'); // false
```

### Response
#### Success Response (200)
- **boolean**: True if the CPF is valid, false otherwise.

#### Response Example
```json
{
  "isValid": true
}
```
```

```APIDOC
## formatCpf

### Description
Format CPF.

### Method
`formatCpf(cpf: string, options?: { pad?: boolean }): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { formatCpf } from '@brazilian-utils/brazilian-utils';

formatCpf('74650688000'); // 746.506.880-00
formatCpf('746506880', { pad: true }); // 007.465.068-80
```

### Response
#### Success Response (200)
- **string**: The formatted CPF.

#### Response Example
```json
{
  "formattedCpf": "746.506.880-00"
}
```
```

```APIDOC
## parseCpf

### Description
Remove CPF formatting, keep only digits, and cap the result to 11 digits.

### Method
`parseCpf(cpf: string): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { parseCpf } from '@brazilian-utils/brazilian-utils';

parseCpf('746.506.880-00'); // 74650688000
```

### Response
#### Success Response (200)
- **string**: The parsed CPF with only digits.

#### Response Example
```json
{
  "parsedCpf": "74650688000"
}
```
```

```APIDOC
## generateCpf

### Description
Generate a valid random CPF.

### Method
`generateCpf(): string`

### Parameters
None

### Request Example
```javascript
import { generateCpf } from '@brazilian-utils/brazilian-utils'

generateCpf();
```

### Response
#### Success Response (200)
- **string**: A valid random CPF.

#### Response Example
```json
{
  "generatedCpf": "12345678900"
}
```
```

--------------------------------

### Fetch CEPs from Address using ViaCEP

Source: https://github.com/brazilian-utils/javascript/blob/main/docs/utilities.md

Use this function to retrieve CEP (Brazilian postal code) information based on address details. Requires an asynchronous context.

```javascript
import { getCepInfoByAddress } from '@brazilian-utils/brazilian-utils';

const ceps = await getCepInfoByAddress({
  federalUnit: 'SP',
  city: 'Sao Paulo',
  street: 'Avenida Paulista'
});

// [
//   {
//     cep: '01310100',
//     logradouro: 'Avenida Paulista',
//     complemento: 'lado par',
//     bairro: 'Bela Vista',
//     localidade: 'São Paulo',
//     uf: 'SP'
//   }
// ]
```