{"_id":"@consultas-de-veiculos/sdk","name":"@consultas-de-veiculos/sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@consultas-de-veiculos/sdk","version":"1.0.0","description":"SDK Node.js do https://consultasdeveiculos.com","main":"src/index.js","type":"module","homepage":"https://github.com/DataCube/consultasdeveiculos-sdk-nodejs#readme","publishConfig":{"access":"public"},"bin":{"consultas-de-veiculos-sdk":"src/cli/index.js"},"scripts":{"postinstall":"node ./scripts/postinstall.js","test":"node --experimental-vm-modules node_modules/jest/bin/jest.js","update":"node ./src/cli/index.js update","version":"node ./src/cli/index.js version","doctor":"node ./src/cli/index.js doctor","clear-cache":"node ./src/cli/index.js clear-cache"},"keywords":["sdk","consultasdeveiculos","api","dynamic","veiculos","debitos","runtime"],"repository":{"type":"git","url":"git+https://github.com/DataCube/consultasdeveiculos-sdk-nodejs.git"},"author":{"name":"DATACUBE SERVICO DE INFORMACAO VIA WEB LTDA"},"license":"MIT","engines":{"node":">=18.0.0"},"dependencies":{"dotenv":"^16.0.0","undici":"^6.0.0"},"devDependencies":{"jest":"^29.7.0"},"gitHead":"227aaf77d8549f4eadc09c93ba552ad57a108fe0","_id":"@consultas-de-veiculos/sdk@1.0.0","bugs":{"url":"https://github.com/DataCube/consultasdeveiculos-sdk-nodejs/issues"},"_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-MNo7b/vLpr9uXqhv9hi1TqnprFAUiXVaJB908RWwsXYhnvnra35F4l6XVamJtW6PZqe2egczUEiPPOzBtICvCw==","shasum":"67ac0f46615e4da1a8dd3b1dc374779444be8b24","tarball":"https://registry.npmjs.org/@consultas-de-veiculos/sdk/-/sdk-1.0.0.tgz","fileCount":25,"unpackedSize":1789044,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICbYnQoZ0vaKK/4dLDmqaNvWUTB94hkcDvTAG5JSelWgAiEApFNl1ZgSuniVlf9uqtGLMRJuzCo2y7OQSEhud6XsMWk="}]},"_npmUser":{"name":"consultasdeveiculos","email":"contato@consultasdeveiculos.com"},"directories":{},"maintainers":[{"name":"mbnunes","email":"mutila@gmail.com"},{"name":"consultasdeveiculos","email":"contato@consultasdeveiculos.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.0_1781550611841_0.7074544289705302"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-15T19:10:11.599Z","1.0.0":"2026-06-15T19:10:12.056Z","modified":"2026-06-15T19:10:12.357Z"},"maintainers":[{"name":"mbnunes","email":"mutila@gmail.com"},{"name":"consultasdeveiculos","email":"contato@consultasdeveiculos.com"}],"description":"SDK Node.js do https://consultasdeveiculos.com","homepage":"https://github.com/DataCube/consultasdeveiculos-sdk-nodejs#readme","keywords":["sdk","consultasdeveiculos","api","dynamic","veiculos","debitos","runtime"],"repository":{"type":"git","url":"git+https://github.com/DataCube/consultasdeveiculos-sdk-nodejs.git"},"author":{"name":"DATACUBE SERVICO DE INFORMACAO VIA WEB LTDA"},"bugs":{"url":"https://github.com/DataCube/consultasdeveiculos-sdk-nodejs/issues"},"license":"MIT","readme":"# ConsultadeveiculosSDK\n\nSDK Node.js dinâmica para consultas de veículos, baseada em coleções Postman.\n\n## 🚀 Visão Geral\n\nEsta SDK funciona como um **Runtime Engine** que consome endpoints definidos em uma coleção Postman, sem necessidade de implementação manual de cada endpoint.\n\n**TODAS as funções são geradas dinamicamente via Proxy. Nenhuma função é declarada diretamente na classe.**\n\n### Características\n\n- ✅ **100% Proxy-based**: Zero funções hardcoded - tudo vem do Postman\n- ✅ **Slug-based API**: Chamadas simples via `client.veiculos_agregados()`\n- ✅ **Modo Sandbox**: Teste sem conexão com a API real\n- ✅ **177 endpoints**: Gerados automaticamente da coleção Postman\n- ✅ **CLI Completo**: Liste endpoints disponíveis\n\n## 📦 Instalação\n\n```bash\nnpm install @consultas-de-veiculos/sdk\n```\n\n## 🏁 Início Rápido\n\n### Modo Produção\n\n```javascript\nimport ConsultadeveiculosSDK from '@consultas-de-veiculos/sdk';\n\n// Inicializa com token obrigatório\nvar client = new ConsultadeveiculosSDK({\n    auth_token: 'SEU_TOKEN_AQUI'\n});\n\n// Consulta usando o slug do endpoint\nconst resultado = await client.veiculos_agregados({\n    placa: 'ABC1234'\n});\n\nconsole.log(resultado.data);\n```\n\n### Modo Sandbox\n\n```javascript\nimport ConsultadeveiculosSDK from '@consultas-de-veiculos/sdk';\n\n// Inicializa em modo sandbox (sem token necessário)\nvar client = new ConsultadeveiculosSDK({\n    sandbox: true\n});\n\n// As chamadas retornam respostas simuladas\nconst resultado = await client.veiculos_agregados({\n    placa: 'ABC1234'\n});\n\nconsole.log(resultado.data); // true\n```\n\n## 📖 API\n\n### Inicialização\n\n```javascript\nvar client = new ConsultadeveiculosSDK({\n    auth_token: 'TOKEN',    // Obrigatório em produção\n    sandbox: false,         // Modo sandbox (padrão: false)\n    baseUrl: 'URL',         // URL base customizada (opcional)\n    timeout: 30000,         // Timeout em ms (padrão: 30000)\n    maxRetries: 3           // Máximo de retries (padrão: 3)\n});\n```\n\n### Como Chamar Endpoints\n\nO slug é derivado da URL do endpoint, substituindo `/` e `-` por `_`:\n\n| URL do Endpoint | Slug para Chamar |\n|-----------------|------------------|\n| `/veiculos/agregados` | `client.veiculos_agregados()` |\n| `/veiculos/debitos-sp` | `client.veiculos_debitos_sp()` |\n| `/cnh/nacional/simples` | `client.cnh_nacional_simples()` |\n| `/pessoas/nome` | `client.pessoas_nome()` |\n\n```javascript\n// Consulta de veículo\nconst veiculo = await client.veiculos_agregados({ placa: 'ABC1234' });\n\n// Consulta de CNH\nconst cnh = await client.cnh_nacional_simples({ \n    cnh: '12345678901',\n    data_nascimento: '01/01/1990' \n});\n\n// Consulta de pessoa por CPF\nconst pessoa = await client.pessoas_nome({ cpf: '123.456.789-00' });\n```\n\n### Métodos de Ajuda (Console / Browser)\n\nA SDK inclui métodos auxiliares que funcionam tanto no Node.js quanto no console do browser:\n\n```javascript\nvar client = new ConsultadeveiculosSDK({ sandbox: true });\n\n// Exibe ajuda completa\nclient.help();\n\n// Filtra endpoints por termo\nclient.help('veiculos');  // Mostra endpoints de veículos\nclient.help('cnh');       // Mostra endpoints de CNH\n\n// Lista todos os endpoints agrupados por namespace\nclient.endpoints();\n\n// Informações do SDK\nclient.info();\n// { runtimeVersion, specVersion, sandbox, endpointsCount, namespaces }\n\n// Busca endpoints por termo\nclient.search('debitos');  // Busca \"debitos\" nos slugs e nomes\n```\n\n#### Exemplo de `client.help()`:\n\n```\n📦 ConsultadeveiculosSDK - Help\n════════════════════════════════════════════════════════════════\n\n   Runtime: v1.0.0\n   Spec: v2.10.2.82\n   Modo: 🧪 SANDBOX\n   Endpoints: 177\n   Namespaces: conta, assincrono, cadastros, orgaos, credito, veiculos, cnh, inmetro, reclameAqui\n\n────────────────────────────────────────────────────────────────\n📖 USO BÁSICO\n────────────────────────────────────────────────────────────────\n\n   var client = new ConsultadeveiculosSDK({ auth_token: \"SEU_TOKEN\" });\n   const result = await client.SLUG({ param: \"valor\" });\n\n────────────────────────────────────────────────────────────────\n🔧 MÉTODOS AUXILIARES\n────────────────────────────────────────────────────────────────\n\n   client.help()              Exibe esta ajuda\n   client.help(\"veiculos\")    Filtra endpoints por termo\n   client.endpoints()         Lista todos os endpoints\n   client.info()              Informações do SDK\n   client.search(\"placa\")     Busca endpoints\n```\n\n### Métodos Internos (prefixados com `_`)\n\n```javascript\n// Informações da SDK\nclient._info()\n// { runtimeVersion, specVersion, endpointsCount, namespaces, slugsCount }\n\n// Listar todos os slugs disponíveis\nclient._listSlugs()\n// ['veiculos_agregados', 'veiculos_debitos_sp', ...]\n\n// Listar todos os endpoints com detalhes\nclient._listEndpoints()\n// [{ slug, name, description, url }, ...]\n\n// Buscar endpoints por padrão\nclient._searchEndpoints('placa')\n// [endpoints que contêm \"placa\"]\n```\n\n## 🖥️ CLI\n\nA SDK inclui um CLI completo para explorar os endpoints disponíveis.\n\n### Comandos Disponíveis\n\n```bash\n# Listar todos os endpoints\nnpx consultas-de-veiculos-sdk endpoints\n\n# Filtrar por namespace\nnpx consultas-de-veiculos-sdk endpoints veiculos\nnpx consultas-de-veiculos-sdk endpoints cnh\nnpx consultas-de-veiculos-sdk endpoints credito\n\n# Com descrições e URLs detalhadas\nnpx consultas-de-veiculos-sdk endpoints --verbose\n\n# Saída em formato JSON\nnpx consultas-de-veiculos-sdk endpoints --json\n\n# Ver versão da SDK e especificação\nnpx consultas-de-veiculos-sdk version\n\n# Diagnóstico do ambiente\nnpx consultas-de-veiculos-sdk doctor\n\n# Atualizar especificação Postman\nnpx consultas-de-veiculos-sdk update\n\n# Limpar cache\nnpx consultas-de-veiculos-sdk clear-cache\n\n# Ajuda\nnpx consultas-de-veiculos-sdk --help\n```\n\n### Exemplo de Saída do CLI\n\n```\n📡 Endpoints Disponíveis\n\n   Specification: v2.10.2.81\n   Total: 177 endpoints\n   Namespaces: conta, assincrono, cadastros, orgaos, credito, veiculos, cnh, inmetro, reclameAqui\n\n   💡 Use o SLUG para chamar: client.<slug>({ params })\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n📁 VEICULOS (74 endpoints)\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n   📌 client.veiculos_agregados()\n      Nome: Consulta nacional - Agregados\n\n   📌 client.veiculos_agregados_v2()\n      Nome: Consulta nacional - Agregados V2\n   ...\n```\n\n## 🛡️ Tratamento de Erros\n\n```javascript\nimport ConsultadeveiculosSDK, { \n    AuthenticationError, \n    ValidationError, \n    RateLimitError,\n    EndpointNotFoundError,\n    SDKError \n} from '@consultas-de-veiculos/sdk';\n\ntry {\n    await client.veiculos_agregados({ placa: 'ABC1234' });\n} catch (error) {\n    if (error instanceof AuthenticationError) {\n        console.log('Token inválido');\n    } else if (error instanceof ValidationError) {\n        console.log('Dados inválidos:', error.details);\n    } else if (error instanceof RateLimitError) {\n        console.log('Limite atingido, aguarde:', error.retryAfter);\n    } else if (error instanceof EndpointNotFoundError) {\n        console.log('Slug não encontrado');\n    }\n}\n```\n\n### Hierarquia de Erros\n\n```\nSDKError (classe base)\n├── AuthenticationError  (401, 403 - token inválido/expirado)\n├── ValidationError      (400, 422 - dados inválidos)\n├── RateLimitError       (429 - limite de requisições)\n├── EndpointNotFoundError (slug não existe)\n└── SpecificationError    (erro na especificação Postman)\n```\n\n## 📡 Namespaces Disponíveis\n\n| Namespace | Endpoints | Descrição |\n|-----------|-----------|-----------|\n| conta | 2 | Informações da conta e consumo |\n| assincrono | 3 | Consultas assíncronas (criar/buscar/recuperar tasks) |\n| cadastros | 11 | Dados cadastrais de pessoas e empresas |\n| orgaos | 18 | Consultas em órgãos públicos (Sintegra, Receita, etc) |\n| credito | 6 | Análise de crédito e score |\n| veiculos | 74 | Consultas de veículos (placa, agregados, débitos) |\n| cnh | 25 | Consultas de CNH (nacional e estaduais) |\n| inmetro | 2 | Dados do INMETRO |\n| reclameAqui | 5 | Consultas no Reclame Aqui |\n\n**Total: 177 endpoints**\n\n---\n\n## 📁 Estrutura do Projeto\n\n```\nconsultas-de-veiculos-sdk-nodejs/\n│\n├── 📄 package.json              # Configuração do pacote npm\n├── 📄 README.md                 # Esta documentação\n├── 📄 .env.example              # Exemplo de variáveis de ambiente\n├── 📄 .gitignore                # Arquivos ignorados pelo git\n├── 📄 jest.config.js            # Configuração de testes\n│\n├── 📁 src/                      # Código fonte principal\n│   ├── 📄 index.js              # Entry point - exporta SDK e erros\n│   │\n│   ├── 📁 core/                 # Núcleo da SDK\n│   │   ├── 📄 SDK.js            # ⭐ Classe principal com Proxy\n│   │   ├── 📄 ConfigManager.js  # Gerenciamento de configuração e cache\n│   │   ├── 📄 EndpointRegistry.js # Registro de endpoints\n│   │   ├── 📄 EndpointBuilder.js  # Construtor de endpoints\n│   │   └── 📄 PostmanLoader.js    # Carregador de coleções Postman\n│   │\n│   ├── 📁 parser/               # Parsers do Postman\n│   │   ├── 📄 PostmanParser.js  # Parser principal da coleção\n│   │   ├── 📄 FolderParser.js   # Parser de pastas/namespaces\n│   │   └── 📄 RequestParser.js  # Parser de requisições\n│   │\n│   ├── 📁 transport/            # Camada de transporte HTTP\n│   │   ├── 📄 Transport.js      # Classe base abstrata\n│   │   ├── 📄 HttpTransport.js  # Transporte HTTP real (produção)\n│   │   └── 📄 SandboxTransport.js # Transporte simulado (sandbox)\n│   │\n│   ├── 📁 errors/               # Classes de erro\n│   │   ├── 📄 index.js          # Exporta todos os erros\n│   │   └── 📄 SDKError.js       # Definição das classes de erro\n│   │\n│   ├── 📁 cli/                  # Interface de linha de comando\n│   │   ├── 📄 index.js          # Entry point do CLI\n│   │   ├── 📄 endpoints.js      # Comando: listar endpoints\n│   │   ├── 📄 version.js        # Comando: exibir versão\n│   │   ├── 📄 doctor.js         # Comando: diagnóstico\n│   │   ├── 📄 update.js         # Comando: atualizar spec\n│   │   └── 📄 clear-cache.js    # Comando: limpar cache\n│   │\n│   └── 📁 cache/                # Utilitários de cache\n│\n├── 📁 spec/                     # Especificação da API\n│   ├── 📄 Consultas - V2.10.2.81.postman_collection.json  # Coleção Postman\n│   └── 📄 manifest.json         # Metadados da especificação\n│\n├── 📁 examples/                 # Exemplos de uso\n│   ├── 📄 basic-usage.js        # Uso básico da SDK\n│   ├── 📄 sandbox-mode.js       # Exemplo do modo sandbox\n│   ├── 📄 error-handling.js     # Tratamento de erros\n│   └── 📄 explore-endpoints.js  # Exploração de endpoints\n│\n└── 📁 tests/                    # Testes automatizados\n    └── 📄 sdk.test.js           # Testes da SDK\n```\n\n---\n\n## 📝 Descrição Detalhada dos Arquivos\n\n### `/src/core/SDK.js` ⭐ (Arquivo Principal)\n\nO coração da SDK. Implementa o padrão **Proxy** do JavaScript para interceptar todas as chamadas de método e roteá-las dinamicamente para os endpoints corretos.\n\n**Responsabilidades:**\n- Carrega a coleção Postman na inicialização\n- Gera slugs a partir das URLs dos endpoints\n- Intercepta chamadas via `Proxy.get()`\n- Valida `auth_token` em modo produção\n- Delega para `HttpTransport` ou `SandboxTransport`\n\n**Fluxo:**\n```\nclient.veiculos_agregados({placa: 'ABC'})\n       ↓\n   Proxy intercepta\n       ↓\n   Busca slug no _slugMap\n       ↓\n   Monta requisição\n       ↓\n   HttpTransport.request() ou SandboxTransport.request()\n       ↓\n   Retorna resposta\n```\n\n### `/src/core/ConfigManager.js`\n\nGerencia configurações e cache local da SDK.\n\n**Responsabilidades:**\n- Encontra arquivo Postman no diretório (por padrão `*.postman_collection.json`)\n- Extrai versão do nome do arquivo\n- Gerencia diretório de cache (`~/.consultas-de-veiculos-sdk/`)\n- Carrega/salva configurações\n\n### `/src/parser/PostmanParser.js`\n\nParser principal que converte a coleção Postman em estrutura utilizável.\n\n**Responsabilidades:**\n- Lê o JSON da coleção Postman\n- Extrai metadados (versão, nome, descrição)\n- Delega parsing de pastas para `FolderParser`\n- Delega parsing de requests para `RequestParser`\n\n### `/src/transport/HttpTransport.js`\n\nCamada de transporte para requisições HTTP reais.\n\n**Responsabilidades:**\n- Executa requisições HTTP via `fetch`\n- Injeta `auth_token` no body da requisição\n- Implementa retry com backoff exponencial\n- Trata erros HTTP e converte para classes de erro da SDK\n\n### `/src/transport/SandboxTransport.js`\n\nTransporte simulado para modo sandbox.\n\n**Responsabilidades:**\n- Retorna respostas simuladas sem fazer requisições reais\n- Útil para desenvolvimento e testes\n- Simula latência opcional\n\n### `/src/cli/endpoints.js`\n\nComando CLI para listar endpoints.\n\n**Funcionalidades:**\n- Lista todos os 177 endpoints\n- Filtra por namespace\n- Modo verbose com descrições\n- Saída JSON para integração\n\n### `/src/errors/SDKError.js`\n\nDefine a hierarquia de erros da SDK.\n\n**Classes:**\n- `SDKError` - Classe base\n- `AuthenticationError` - Erros de autenticação\n- `ValidationError` - Erros de validação de dados\n- `RateLimitError` - Limite de requisições excedido\n- `EndpointNotFoundError` - Slug não encontrado\n- `SpecificationError` - Erro na especificação Postman\n\n---\n\n## 🔧 Variáveis de Ambiente\n\n```env\n# Token de autenticação (obrigatório em produção)\nAUTH_TOKEN=seu_token_aqui\n\n# URL base da API (opcional - padrão: https://api.consultasdeveiculos.com)\nAPI_BASE_URL=https://api.consultasdeveiculos.com\n\n# Timeout em ms (opcional - padrão: 30000)\nAPI_TIMEOUT=30000\n```\n\n## 🧪 Executando os Exemplos\n\n```bash\n# Instalar dependências\nnpm install\n\n# Executar exemplo básico (modo sandbox)\nnode examples/basic-usage.js\n\n# Executar exemplo de sandbox\nnode examples/sandbox-mode.js\n\n# Executar exemplo de tratamento de erros\nnode examples/error-handling.js\n\n# Executar exemplo de exploração de endpoints\nnode examples/explore-endpoints.js\n```\n\n## 🧪 Testes\n\n```bash\n# Executar testes\nnpm test\n\n# Executar testes com coverage\nnpm run test:coverage\n```\n\n## 📄 Licença\n\nMIT\n\n## 🤝 Contribuindo\n\n1. Fork o projeto\n2. Crie sua branch (`git checkout -b feature/nova-feature`)\n3. Commit suas mudanças (`git commit -am 'Adiciona nova feature'`)\n4. Push para a branch (`git push origin feature/nova-feature`)\n5. Abra um Pull Request\n","readmeFilename":"README.md","_rev":"1-6f33eb2f8bc9bc42b335b7d05180e82e"}