feat: merge develop into main

.editorconfig

@@ -10,4 +10,4 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 
 [*.md]
-trim_trailing_whitespace = false
+trim_trailing_whitespace = false

.eslintrc.json

@@ -6,11 +6,12 @@
   "extends": [
     "standard",
     "plugin:@typescript-eslint/eslint-recommended",
-    "plugin:@typescript-eslint/recommended"
+    "plugin:@typescript-eslint/recommended",
+    "plugin:prettier/recommended"
   ],
   "parser": "@typescript-eslint/parser",
   "parserOptions": {
-    "ecmaVersion": 12,
+    "ecmaVersion": "latest",
     "sourceType": "module"
   },
   "plugins": ["@typescript-eslint"],
@@ -29,6 +30,12 @@
       "rules": {
         "camelcase": "off"
       }
+    },
+    {
+      "files": ["*"],
+      "rules": {
+        "space-before-function-paren": "off"
+      }
     }
   ]
 }

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+github: [AlexandreBellas]
+ko_fi: alebatistella
+custom: ["https://www.paypal.com/donate/?hosted_button_id=G2NJKZ5MUMKBS"]

.github/workflows/on-commit-test.yaml

@@ -0,0 +1,21 @@
+name: On commit => execute test workflow
+
+on: push
+
+jobs:
+  unit-feature-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build project
+        run: npm run build
+
+      - name: Execute tests
+        run: npm run test

.prettierrc.json

@@ -1,6 +1,6 @@
 {
-    "trailingComma": "none",
-    "tabWidth": 2,
-    "semi": false,
-    "singleQuote": true
-}
+  "trailingComma": "none",
+  "tabWidth": 2,
+  "semi": false,
+  "singleQuote": true
+}

.vscode/settings.json

@@ -0,0 +1,32 @@
+{
+  "material-icon-theme.folders.associations": {
+    "@shared": "Shared",
+    "exceptions": "Error"
+  },
+  "cSpell.words": [
+    "aliquota",
+    "Amazônia",
+    "borderô",
+    "Borderos",
+    "borderôs",
+    "Contabeis",
+    "Contábeis",
+    "Contabil",
+    "contábil",
+    "CONTRAN",
+    "customizado",
+    "Customizados",
+    "Eletrônicas",
+    "Frotista",
+    "ICMS",
+    "ICMSST",
+    "ICRT",
+    "intermediador",
+    "nfces",
+    "Parcelada",
+    "pickone",
+    "Rastreamento",
+    "sublimite",
+    "SUFRAMA"
+  ]
+}

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contribuição ao projeto
+
+Agradeço muito o interesse de apoio ao projeto. Para uma contribuição saudável e
+inclusiva, devemos manter um padrão de execução.
+
+## Como começar a contribuição
+
+1. Crie uma _issue_ explicando o problema e o desejo de alteração;
+2. Após receber um retorno validando o problema e permitindo a alteração, faça
+   um novo `fork` do repositório;
+3. Implemente as mudanças ou novas funcionalidades que deseja realizar em seu
+   `fork`;
+4. Crie um novo _pull request_ para a _branch_ `develop` do repositório oficial.
+
+## Padrões de projeto
+
+- Todas as variáveis e nomes de funções devem estar em `camelCase`;
+- Todas as classes devem estar em `PascalCase`;
+- Todas as entidades devem seguir o padrão:
+  1. Uma pasta para cada entidade;
+  2. Um arquivo para cada rota disponibilizada em relação aos envios/retornos;
+  3. Um arquivo principal de declaração e utilização da entidade;
+  4. Teste unitário de chamada e tipagem de retorno.
+- Deve-se manter o padrão do código baseado nas configurações do **prettier** e
+  do **eslint** do projeto.
+
+### Mensagens de _commits_
+
+Siga o padrão [_conventional commits_](https://www.conventionalcommits.org/en/v1.0.0/).
+
+## Adicionar uma nova linguagem de programação ao projeto
+
+1. Crie uma _issue_ anunciando o desejo de trabalhar em uma nova linguagem de
+   programação;
+2. A sua _issue_ será fixada para que outras pessoas possam acompanhar e apoiar
+   a sua implementação;
+3. Realize a sua implementação em uma nova pasta na raiz do projeto com o nome
+   da linguagem de programação em letras minúsculas (por exemplo: Java seria
+   criado como `java`, Elixir seria criado como `elixir`, etc);
+4. Crie um _pull request_ para a _branch_ `develop` do repositório oficial a
+   cada nova entidade implementada.
+
+A ideia é ter o pacote já inicializado e disponibilizado mesmo que nem todas as
+entidades estejam disponíveis. Isso permite uma contribuição mais facilitada de
+outros desenvolvedores.

README.md

@@ -4,10 +4,19 @@
 [![install size](https://packagephobia.com/badge?p=bling-erp-api)](https://packagephobia.com/result?p=bling-erp-api)
 [![code coverage](https://coveralls.io/repos/github/AlexandreBellas/bling-erp-api/badge.svg?branch=main)](https://coveralls.io/github/AlexandreBellas/bling-erp-api?branch=main)
 
-> ### A biblioteca atualmente usa a API v2 do Bling. Uma nova versão para uso da API v3 está em desenvolvimento no momento, com previsão de ser disponibilizada entre Dezembro/2023 e Janeiro/2024.
+Pacote de integração com a [API v3 do ERP Bling](https://developer.bling.com.br).
+O mais completo existente (e se não é, será).
 
-Pacote de integração com a [API do ERP Bling](https://ajuda.bling.com.br/hc/pt-br/categories/360002186394-API-para-Desenvolvedores). O mais completo existente (e se não é, será).
-Disponível também para **Typescript**.
+Disponível para:
+
+- [x] JavaScript
+- [x] TypeScript
+- [ ] PHP (em breve)
+- [ ] C# (em breve)
+
+**Atenção**: a versão 5.0.0+ do `bling-erp-api` utiliza a API v3 do Bling. Caso
+deseje utilizar a API v2 do Bling,
+[utilize a versão 4.0.0](https://github.com/AlexandreBellas/bling-erp-api/tree/v4.0.0).
 
 ## Instalação
 
@@ -22,102 +31,99 @@ npm i bling-erp-api
 ### CommonJS
 
 ```js
-const { Bling } = require('bling-erp-api')
+const Bling = require('bling-erp-api')
 ```
 
 ### ES6
 
 ```ts
-import { Bling } from 'bling-erp-api'
+import Bling from 'bling-erp-api'
 ```
 
 ## Criação de uma nova conexão
 
-Para criar uma conexão ao serviço do Bling, basta instanciar o objeto com a [API
-key](https://ajuda.bling.com.br/hc/pt-br/articles/360046937853-Introdu%C3%A7%C3%A3o-para-a-API-do-Bling-para-desenvolvedores-) em 
-seu construtor.
+Para criar uma conexão ao serviço do Bling, basta instanciar o objeto com a [API key](https://developer.bling.com.br/autenticacao) em seu construtor.
 
 ```js
 const apiKey = 'sua_api_key'
 const blingConnection = new Bling(apiKey)
 ```
 
+Vale destacar que o fluxo de criação e autorização do aplicativo **não é feito
+pela biblioteca**. Ou seja, a biblioteca somente recebe o `access_token` gerado
+a partir do _endpoint_ `/token`. [Veja a referência](https://developer.bling.com.br/aplicativos#tokens-de-acesso).
+
+Para entender na prática como a autenticação citada acima funciona, [veja o
+projeto de demonstração](https://github.com/AlexandreBellas/bling-erp-api/tree/main/demo).
+
 ## Entidades disponíveis
 
-As entidades atualmente permitidas para interação são:
-
-- Borderos (`.borderos()`)
-- Campos customizados (`.customizedFields()` ou `.camposCustomizados()`)
-- Categorias (`.categories()` ou `.categorias()`)
-- Categorias Loja (`.shopCategories()` ou `.categoriasLoja()`)
-- Contatos (`.contacts()` ou `.contatos()`)
-- Contas a pagar (`.billsToPay()` ou `.contasAPagar()`)
-- Contas a receber (`.billsToReceive()` ou `.contasAReceber()`)
-- Contratos (`.contracts()` ou `.contratos()`)
-- CTes (`.ctes()`)
-- Depósitos (`.deposits()` ou `.depositos()`)
-- Formas de pagamento (`.paymentMethods()` ou `.formasDePagamento()`)
-- Grupo de produtos (`.productGroups()` ou `.grupoDeProdutos()`)
-- NFCes (`.nfces()`)
-- Notas fiscais (`.invoices()` ou `.notasFiscais()`)
-- Notas de serviço (`.serviceInvoices()` ou `.notasServicos()`)
-- Pedidos (`.orders()` ou `.pedidos()`)
-- Pedidos de compra (`.purchaseOrders()` ou `.pedidosDeCompra()`)
-- Produtos (`.products()` ou `.produtos()`)
-- Propostas comerciais (`.commercialProposals()` ou `.propostasComerciais()`)
-
-Ainda estão em desenvolvimento as entidades:
-
-- Logística
-- Ordem de produção
-- Produto Fornecedores
-- Produto Loja
-
-Adicionaremos as restantes de acordo com as _releases_.
-
-## Métodos permitidos
-
-- `all()`: retorna todos os registros da entidade
-- `find()`: retorna um registro da entidade desejada através de seu `id` ou
-  `codigo`
-- `findBy()`: retorna os registros da entidade **que se adequem aos filtros
-  passados**
-- `create()`: cria um registro da entidade
-- `update()`: atualiza um registro da entidade a partir de seu `id` ou
-  `codigo`
-- `delete()`: remove um registro da entidade a partir de seu `id` ou
-  `codigo`
-
-Nem todas as entidades possuem interação com todos os métodos (de acordo com a 
-documentação da API do Bling). Ao utilizar o pacote e estar no VSCode, se o
-desenvolvedor utilizar intelliSense ao programar, os métodos permitidos
-aparecerão automaticamente após usar o atalho `Ctrl` + `Barra de espaço`.
+Todas as entidades do Bling atualmente são permitidas para interação. São elas:
+
+- [x] Borderos (`.borderos`)
+- [x] Campos customizados (`.camposCustomizados`)
+- [x] Categorias - Lojas (`.categoriasLojas`)
+- [x] Categorias - Produtos (`.categoriasProdutos`)
+- [x] Categorias - Receitas e Despesas (`.categoriasReceitasDespesas`)
+- [x] Contas a Pagar (`.contasPagar`)
+- [x] Contas a Receber (`.contasReceber`)
+- [x] Contas Contábeis (`.contasContabeis`)
+- [x] Contatos (`.contatos`)
+- [x] Contatos - Tipos (`.contatosTipos`)
+- [x] Contratos (`.contratos`)
+- [x] Depósitos (`.depositos`)
+- [x] Empresas (`.empresas`)
+- [x] Estoques (`.estoques`)
+- [x] Formas de pagamento (`.formasDePagamento`)
+- [x] Homologação (`.homologacao`)
+- [x] Logísticas (`.logisticas`)
+- [x] Logísticas - Etiquetas (`.logisticasEtiquetas`)
+- [x] Logísticas - Objetos (`.logisticasObjetos`)
+- [x] Logísticas - Serviços (`.logisticasServicos`)
+- [x] Naturezas de Operações (`.naturezasDeOperacoes`)
+- [x] Notas Fiscais de Consumidor Eletrônicas (`.nfces`)
+- [x] Notas Fiscais de Serviço Eletrônicas (`.nfses`)
+- [x] Notas Fiscais Eletrônicas (`.nfes`)
+- [x] Notificações (`.notificacoes`)
+- [x] Pedidos - Compras (`.pedidosCompras`)
+- [x] Pedidos - Vendas (`.pedidosVendas`)
+- [x] Produtos (`.produtos`)
+- [x] Produtos - Estruturas (`.produtosEstruturas`)
+- [x] Produtos - Fornecedores (`.produtosFornecedores`)
+- [x] Produtos - Lojas (`.produtosLojas`)
+- [x] Produtos - Variações (`.produtosVariacoes`)
+- [x] Situações (`.situacoes`)
+- [x] Situações - Módulos (`.situacoesModulos`)
+- [x] Situações - Transições (`.situacoesTransicoes`)
+- [x] Usuários (`.usuarios`)
+- [x] Vendedores (`.vendedores`)
 
 ## Exemplo de uso
 
-Para listar todos os produtos, basta executar:
+Para listar seus produtos, basta executar:
 
 ```js
-// Também disponível pelo método:
-// import { Bling } from 'bling-erp-api'
-const { Bling } = require('bling-erp-api')
+// Também disponível como:
+// import Bling from 'bling-erp-api'
+const Bling = require('bling-erp-api')
 const apiKey = 'sua_api_key'
 
 const blingConnection = new Bling(apiKey)
 
-const products = await blingConnection.products().all()
+const products = await blingConnection.produtos.get()
 
 console.log(products)
 ```
 
-## Executando testes automatizados
-Para isso, faça o clone do projeto e execute
+## Executando os testes do projeto
+
+Faça o clone do projeto, instale as dependências e execute:
 
 ```bash
 npm run test
 ```
 
-## Contribuição
+## Recursos
 
-Basta fazer um _fork_ do projeto e abrir novos _Pull Requests_ ou interagir
-conosco abrindo _issues_ sobre os problemas encontrados.
+- [Guia de contribuição](https://github.com/AlexandreBellas/bling-erp-api/blob/v5.0.0/CONTRIBUTING.md)
+- [Apoie o projeto](https://www.paypal.com/donate/?hosted_button_id=G2NJKZ5MUMKBS)

demo/README.md

@@ -0,0 +1,27 @@
+# Projeto de demonstração
+
+## Aplicativo no Bling
+
+Crie um aplicativo para teste [como esta página descreve](https://developer.bling.com.br/aplicativos#introdu%C3%A7%C3%A3o).
+
+É obrigatório que você crie com a URL de redirecionamento como `http://localhost:3000/auth`.
+
+Além disso, para fins de teste, conceda a permissão para listar produtos.
+
+## Execução
+
+Inicie o servidor executando:
+
+```bash
+npm i
+npm run dev
+```
+
+Abra o arquivo `index.html` e siga o que é apresentado.
+
+### Passo a passo
+
+1. Insira o _client ID_ e o _client secret_;
+2. Conceda as permissões pedidas;
+3. O _token_ de acesso aparecerá em seu navegador em formato JSON. Além disso,
+   será feita uma listagem de seus produtos ilustrando o uso da biblioteca.