{"_id":"@alos32/signature-module-sdk","_rev":"5-c0c3e533098aed38f518abee9131492c","name":"@alos32/signature-module-sdk","dist-tags":{"latest":"3.3.0"},"versions":{"3.1.0":{"name":"@alos32/signature-module-sdk","version":"3.1.0","keywords":["digital-signature","api","sdk","typescript","envelope","document-signing","docx-templates","notifications","authentication","public-verification","multi-tenant"],"author":{"name":"Alos"},"license":"MIT","_id":"@alos32/signature-module-sdk@3.1.0","maintainers":[{"name":"alos32","email":"allissonlevi1@gmail.com"}],"homepage":"https://github.com/allissonsimplicio/signature_module_sdk#readme","bugs":{"url":"https://github.com/allissonsimplicio/signature_module_sdk/issues"},"dist":{"shasum":"623cf8c8ffca67e09e2b604edcc98b6fcf8867fe","tarball":"https://registry.npmjs.org/@alos32/signature-module-sdk/-/signature-module-sdk-3.1.0.tgz","fileCount":204,"integrity":"sha512-f6tRGhy1E6co8WLXyEFX/Cp/0Okf6B4IaRTi03HC7JdePxb0CahLVc+FuGP6kDrLCE1AnsqVfml+04WcZiauDw==","signatures":[{"sig":"MEQCIEPK96gpyJzlW4cF3b9eX5qIzIHTnmi2l0Em2VyTncv5AiBFORgeg2Rz7WuaXgJIQshpP6K32IrAmwHJT63AivkSsg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1236261},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"6abb2f74139518640e67926af93ebcc0e8f6be17","scripts":{"dev":"ts-node src/index.ts","test":"jest --config ./jest.config.js","build":"tsc","clean":"rm -rf dist","test:sdk":"jest --config ./jest.config.js","example:auth":"ts-node examples/03-authentication-workflow.ts","examples:all":"npm run example:basic && npm run example:template && npm run example:auth && npm run example:notifications && npm run example:complete","example:basic":"ts-node examples/01-basic-envelope.ts","prepublishOnly":"npm run clean && npm run build","example:complete":"ts-node examples/05-complete-workflow.ts","example:template":"ts-node examples/02-document-template-workflow.ts","example:notifications":"ts-node examples/04-notification-workflow.ts"},"_npmUser":{"name":"alos32","email":"allissonlevi1@gmail.com"},"repository":{"url":"git+https://github.com/allissonsimplicio/signature_module_sdk.git","type":"git"},"_npmVersion":"10.9.4","description":"SDK TypeScript para integração com AtlasSign API - assinatura digital, setores organizacionais, destinatários internos, templates DOCX, notificações multi-canal","directories":{"example":"examples"},"_nodeVersion":"22.22.0","dependencies":{"zod":"^4.0.5","axios":"^1.10.0","dotenv":"^17.2.0","form-data":"^4.0.1"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.4","ts-jest":"^29.4.0","ts-node":"^10.9.2","typescript":"^5.8.3","@types/jest":"^30.0.0","@types/node":"^24.0.13","axios-mock-adapter":"^2.1.0"},"_npmOperationalInternal":{"tmp":"tmp/signature-module-sdk_3.1.0_1770312230191_0.6058165988426019","host":"s3://npm-registry-packages-npm-production"}},"3.1.1":{"name":"@alos32/signature-module-sdk","version":"3.1.1","keywords":["digital-signature","api","sdk","typescript","envelope","document-signing","docx-templates","notifications","authentication","public-verification","multi-tenant"],"author":{"name":"Alos"},"license":"MIT","_id":"@alos32/signature-module-sdk@3.1.1","maintainers":[{"name":"alos32","email":"allissonlevi1@gmail.com"}],"homepage":"https://github.com/allissonsimplicio/signature_module_sdk#readme","bugs":{"url":"https://github.com/allissonsimplicio/signature_module_sdk/issues"},"dist":{"shasum":"60e8842ed225da08acd54f7916b5db02a3cd5cc6","tarball":"https://registry.npmjs.org/@alos32/signature-module-sdk/-/signature-module-sdk-3.1.1.tgz","fileCount":204,"integrity":"sha512-2UBpVT/Nvs5DlaCjdmvusjIfr08TPh8b42CCGtMjgwaSdBICd4JaiDTMBHosRCKSVMHs4Nfv54TJxvhsp2Y3yQ==","signatures":[{"sig":"MEUCIE3TTGfC6+JXJfivG8bwIO+vjcr4xCwYVIBIQMwgIeJjAiEAmOzkmfD0c/jC5bvfsbYUq9UHHbf0RBamrwBZZYs2C1g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1243000},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"96ab84518861e32739625a69d36634ae90ca8eab","scripts":{"dev":"ts-node src/index.ts","test":"jest --config ./jest.config.js","build":"tsc","clean":"rm -rf dist","test:sdk":"jest --config ./jest.config.js","example:auth":"ts-node examples/03-authentication-workflow.ts","examples:all":"npm run example:basic && npm run example:template && npm run example:auth && npm run example:notifications && npm run example:complete","example:basic":"ts-node examples/01-basic-envelope.ts","prepublishOnly":"npm run clean && npm run build","example:complete":"ts-node examples/05-complete-workflow.ts","example:template":"ts-node examples/02-document-template-workflow.ts","example:notifications":"ts-node examples/04-notification-workflow.ts"},"_npmUser":{"name":"alos32","email":"allissonlevi1@gmail.com"},"repository":{"url":"git+https://github.com/allissonsimplicio/signature_module_sdk.git","type":"git"},"_npmVersion":"10.8.2","description":"SDK TypeScript para integração com AtlasSign API - assinatura digital, setores organizacionais, destinatários internos, templates DOCX, notificações multi-canal","directories":{"example":"examples"},"_nodeVersion":"20.20.0","dependencies":{"zod":"^4.0.5","axios":"^1.10.0","dotenv":"^17.2.0","form-data":"^4.0.1"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.4","ts-jest":"^29.4.0","ts-node":"^10.9.2","typescript":"^5.8.3","@types/jest":"^30.0.0","@types/node":"^24.0.13","axios-mock-adapter":"^2.1.0"},"_npmOperationalInternal":{"tmp":"tmp/signature-module-sdk_3.1.1_1770480927017_0.6942030390037062","host":"s3://npm-registry-packages-npm-production"}},"3.2.0":{"name":"@alos32/signature-module-sdk","version":"3.2.0","keywords":["digital-signature","api","sdk","typescript","envelope","document-signing","docx-templates","notifications","authentication","public-verification","multi-tenant","ai","ai-document","document-generation","document-review"],"author":{"name":"Alos"},"license":"MIT","_id":"@alos32/signature-module-sdk@3.2.0","maintainers":[{"name":"alos32","email":"allissonlevi1@gmail.com"}],"homepage":"https://github.com/allissonsimplicio/signature_module_sdk#readme","bugs":{"url":"https://github.com/allissonsimplicio/signature_module_sdk/issues"},"dist":{"shasum":"a7301b5ec0d44991fc556b2725c0680a2d480edc","tarball":"https://registry.npmjs.org/@alos32/signature-module-sdk/-/signature-module-sdk-3.2.0.tgz","fileCount":216,"integrity":"sha512-OOki6NH8YTQxdGuZ+zLqBhbq5pA/Ix2goMAq3or3811e2cNkToj6f02HLhtoXBWRYawkaiXtJ77CHYJLbdz+rw==","signatures":[{"sig":"MEUCIQCWZmnK3Dmzr2JJtoQXyxY8eAG2xhIgc1YiUb5XReXxbgIgICS49mZplngIDxToeDEccHZCWYCNv3MglCL3DLJpoOU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1300414},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"8b386c6766e291d47624c2e731d4819dfcaf3193","scripts":{"dev":"ts-node src/index.ts","test":"jest --config ./jest.config.js","build":"tsc","clean":"rm -rf dist","test:sdk":"jest --config ./jest.config.js","example:auth":"ts-node examples/03-authentication-workflow.ts","examples:all":"npm run example:basic && npm run example:template && npm run example:auth && npm run example:notifications && npm run example:complete","example:basic":"ts-node examples/01-basic-envelope.ts","prepublishOnly":"npm run clean && npm run build","example:complete":"ts-node examples/05-complete-workflow.ts","example:template":"ts-node examples/02-document-template-workflow.ts","example:notifications":"ts-node examples/04-notification-workflow.ts"},"_npmUser":{"name":"alos32","email":"allissonlevi1@gmail.com"},"repository":{"url":"git+https://github.com/allissonsimplicio/signature_module_sdk.git","type":"git"},"_npmVersion":"10.8.2","description":"SDK TypeScript para integração com AtlasSign API - assinatura digital, IA para documentos, setores organizacionais, templates DOCX, notificações multi-canal","directories":{"example":"examples"},"_nodeVersion":"20.20.0","dependencies":{"zod":"^4.0.5","axios":"^1.10.0","dotenv":"^17.2.0","form-data":"^4.0.1"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.4","ts-jest":"^29.4.0","ts-node":"^10.9.2","typescript":"^5.8.3","@types/jest":"^30.0.0","@types/node":"^24.0.13","axios-mock-adapter":"^2.1.0"},"_npmOperationalInternal":{"tmp":"tmp/signature-module-sdk_3.2.0_1772291887013_0.24085445358297775","host":"s3://npm-registry-packages-npm-production"}},"3.2.1":{"name":"@alos32/signature-module-sdk","version":"3.2.1","keywords":["digital-signature","api","sdk","typescript","envelope","document-signing","docx-templates","notifications","authentication","public-verification","multi-tenant","ai","ai-document","document-generation","document-review"],"author":{"name":"Alos"},"license":"MIT","_id":"@alos32/signature-module-sdk@3.2.1","maintainers":[{"name":"alos32","email":"allissonlevi1@gmail.com"}],"homepage":"https://github.com/allissonsimplicio/signature_module_sdk#readme","bugs":{"url":"https://github.com/allissonsimplicio/signature_module_sdk/issues"},"dist":{"shasum":"7992662d57726977d3a823cb5f6fcaecbcf04359","tarball":"https://registry.npmjs.org/@alos32/signature-module-sdk/-/signature-module-sdk-3.2.1.tgz","fileCount":216,"integrity":"sha512-+HvS5hYYShzqqmRnpAb3jlDkPxfdN/LSeoX2ZOO08AHoLoNgQkLXy+qTCUCnvpi5tmjNvhGHJw4pmdtRYYGiOA==","signatures":[{"sig":"MEUCIQDaGL0mhPCFJ8rzfnziUT5z6q1dXZ//4GO1r56VZN+fXQIgBYiT/j+nlUh4fEbShfplASHej6qKAOzgJVVk0YtdI20=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1300274},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"8b386c6766e291d47624c2e731d4819dfcaf3193","scripts":{"dev":"ts-node src/index.ts","test":"jest --config ./jest.config.js","build":"tsc","clean":"rm -rf dist","test:sdk":"jest --config ./jest.config.js","example:auth":"ts-node examples/03-authentication-workflow.ts","examples:all":"npm run example:basic && npm run example:template && npm run example:auth && npm run example:notifications && npm run example:complete","example:basic":"ts-node examples/01-basic-envelope.ts","prepublishOnly":"npm run clean && npm run build","example:complete":"ts-node examples/05-complete-workflow.ts","example:template":"ts-node examples/02-document-template-workflow.ts","example:notifications":"ts-node examples/04-notification-workflow.ts"},"_npmUser":{"name":"alos32","email":"allissonlevi1@gmail.com"},"repository":{"url":"git+https://github.com/allissonsimplicio/signature_module_sdk.git","type":"git"},"_npmVersion":"11.8.0","description":"SDK TypeScript para integração com AtlasSign API - assinatura digital, IA para documentos, setores organizacionais, templates DOCX, notificações multi-canal","directories":{"example":"examples"},"_nodeVersion":"24.13.1","dependencies":{"zod":"^4.0.5","axios":"^1.10.0","dotenv":"^17.2.0","form-data":"^4.0.1"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.4","ts-jest":"^29.4.0","ts-node":"^10.9.2","typescript":"^5.8.3","@types/jest":"^30.0.0","@types/node":"^24.0.13","axios-mock-adapter":"^2.1.0"},"_npmOperationalInternal":{"tmp":"tmp/signature-module-sdk_3.2.1_1779829374611_0.3079014929417485","host":"s3://npm-registry-packages-npm-production"}},"3.3.0":{"name":"@alos32/signature-module-sdk","version":"3.3.0","description":"SDK TypeScript para integração com AtlasSign API - assinatura digital, IA para documentos, setores organizacionais, templates DOCX, notificações multi-canal","main":"dist/index.js","types":"dist/index.d.ts","directories":{"example":"examples"},"scripts":{"build":"tsc","dev":"ts-node src/index.ts","example:basic":"ts-node examples/01-basic-envelope.ts","example:template":"ts-node examples/02-document-template-workflow.ts","example:auth":"ts-node examples/03-authentication-workflow.ts","example:notifications":"ts-node examples/04-notification-workflow.ts","example:complete":"ts-node examples/05-complete-workflow.ts","examples:all":"npm run example:basic && npm run example:template && npm run example:auth && npm run example:notifications && npm run example:complete","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build","test":"jest --config ./jest.config.js","test:sdk":"jest --config ./jest.config.js"},"keywords":["digital-signature","api","sdk","typescript","envelope","document-signing","docx-templates","notifications","authentication","public-verification","multi-tenant","ai","ai-document","document-generation","document-review"],"author":{"name":"Alos"},"license":"MIT","engines":{"node":">=20.0.0"},"dependencies":{"axios":"^1.10.0","dotenv":"^17.2.0","form-data":"^4.0.1","zod":"^4.0.5"},"devDependencies":{"@types/jest":"^30.0.0","@types/node":"^24.0.13","axios-mock-adapter":"^2.1.0","jest":"^30.0.4","ts-jest":"^29.4.0","ts-node":"^10.9.2","typescript":"^5.8.3"},"publishConfig":{"registry":"https://registry.npmjs.org","access":"public"},"repository":{"type":"git","url":"git+https://github.com/allissonsimplicio/signature_module_sdk.git"},"gitHead":"bb4f3f091a40049d86690154f53513d1a8650bce","_id":"@alos32/signature-module-sdk@3.3.0","bugs":{"url":"https://github.com/allissonsimplicio/signature_module_sdk/issues"},"homepage":"https://github.com/allissonsimplicio/signature_module_sdk#readme","_nodeVersion":"24.13.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-Jwkm34bpEWLJTUaO+xJcdVui/uoiKv1OnZIqSaXWO28eevXiG0GnG7BzKlIEiGWYcf0PLlzPDhdLv2Hdw3rvnQ==","shasum":"6aefe75ba52916f3406c287ab36cd2a4c94f8721","tarball":"https://registry.npmjs.org/@alos32/signature-module-sdk/-/signature-module-sdk-3.3.0.tgz","fileCount":216,"unpackedSize":1300555,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIA8OIreTunfTUyfx9mvmmAS3/0YimwloY0VmYMY63FDKAiAJ3VZ8NR2Arh1K1xoZ+JAKPWixq8QABHD0kkvoHvJ1mw=="}]},"_npmUser":{"name":"alos32","email":"allissonlevi1@gmail.com"},"maintainers":[{"name":"alos32","email":"allissonlevi1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/signature-module-sdk_3.3.0_1780067200314_0.29497742159886986"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-05T17:23:50.116Z","modified":"2026-05-29T15:06:40.612Z","3.1.0":"2026-02-05T17:23:50.421Z","3.1.1":"2026-02-07T16:15:27.193Z","3.2.0":"2026-02-28T15:18:07.248Z","3.2.1":"2026-05-26T21:02:54.796Z","3.3.0":"2026-05-29T15:06:40.497Z"},"bugs":{"url":"https://github.com/allissonsimplicio/signature_module_sdk/issues"},"author":{"name":"Alos"},"license":"MIT","homepage":"https://github.com/allissonsimplicio/signature_module_sdk#readme","keywords":["digital-signature","api","sdk","typescript","envelope","document-signing","docx-templates","notifications","authentication","public-verification","multi-tenant","ai","ai-document","document-generation","document-review"],"repository":{"type":"git","url":"git+https://github.com/allissonsimplicio/signature_module_sdk.git"},"description":"SDK TypeScript para integração com AtlasSign API - assinatura digital, IA para documentos, setores organizacionais, templates DOCX, notificações multi-canal","maintainers":[{"name":"alos32","email":"allissonlevi1@gmail.com"}],"readme":"# Signature Module SDK v3.1.0\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)\n[![Node](https://img.shields.io/badge/Node.js-%3E%3D14.0.0-green.svg)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nSDK completo em TypeScript para integração com a API de Assinatura Digital. Inclui suporte avançado para gestão de usuários e organizações, API tokens, templates DOCX com variáveis, notificações multi-canal, autenticação de assinantes, verificação pública e arquitetura multi-tenant.\n\n## 📦 Instalação\n\n```bash\nnpm install @alos32/signature-module-sdk\n```\n\n## 🔐 Google OAuth Login\n\nA API suporta login via Google OAuth 2.0 além do login tradicional (email/senha).\n\n### Fluxo de Autenticação\n\n```\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│   Frontend  │     │   Backend   │     │   Google    │\n└──────┬──────┘     └──────┬──────┘     └──────┬──────┘\n       │                   │                   │\n       │ GET /auth/google  │                   │\n       │──────────────────>│                   │\n       │   302 Redirect    │                   │\n       │<──────────────────│                   │\n       │                   │                   │\n       │ User authorizes on Google             │\n       │──────────────────────────────────────>│\n       │                   │                   │\n       │ Redirect to callback with tokens      │\n       │<──────────────────────────────────────│\n```\n\n### Endpoints\n\n| Endpoint | Descrição |\n|----------|-----------|\n| `GET /auth/google` | Inicia o fluxo OAuth (redireciona para Google) |\n| `GET /auth/google/callback` | Callback que processa o retorno e gera JWT |\n| `POST /auth/google/link` | Vincula Google a conta existente (autenticado) |\n\n### Comportamento\n\n- **Usuário novo via Google** → Cria conta + organização automaticamente\n- **Email já existe** → Vincula Google à conta existente\n- **Já tem Google vinculado** → Login direto\n\n### Exemplo de Integração (React/Next.js)\n\n```typescript\n// Botão de login\nconst handleGoogleLogin = () => {\n  window.location.href = `${API_URL}/api/v1/auth/google`;\n};\n\n// Página de callback (/auth/callback)\nuseEffect(() => {\n  const params = new URLSearchParams(window.location.search);\n  const accessToken = params.get('accessToken');\n  const refreshToken = params.get('refreshToken');\n  \n  if (accessToken && refreshToken) {\n    localStorage.setItem('accessToken', accessToken);\n    localStorage.setItem('refreshToken', refreshToken);\n    router.push('/dashboard');\n  }\n}, []);\n```\n\n### Types\n\n```typescript\nimport { AuthProvider, UserWithOAuth } from '@alos32/signature-module-sdk';\n\n// AuthProvider: 'local' | 'google'\n// UserWithOAuth inclui: googleId, authProvider, avatarUrl\n```\n\n## 📋 Índice\n\n- [Recursos Principais](#-recursos-principais)\n- [Documentação](#-documentação)\n- [Exemplos](#-exemplos)\n- [Migration Guide](#-migration-guide)\n- [Suporte](#-suporte)\n\n## ✨ Recursos Principais\n\n### 📦 Envelopes\n- Criar, listar, atualizar e deletar envelopes\n- Ativar envelopes (inicia processo de assinatura)\n- Cancelar envelopes com notificação aos signatários\n- Suporte multi-organização (multitenancy)\n\n### 📄 Documentos\n- Upload de PDFs reais para S3\n- Geração de documentos a partir de templates DOCX\n- Download de documentos assinados — a API transmite o binário; use\n  `documents.downloadBlob(id)` (os métodos `getDownloadUrl`/`download` estão\n  deprecados, pois o endpoint não redireciona mais para URL assinada)\n- Download público por hash via `publicVerification.download(hash)` (retorna binário)\n- Preview de documentos\n- Versionamento automático\n\n### 📝 Templates DOCX (Fase 7)\n- Upload de templates .docx com variáveis `[[VARIAVEL]]`\n- Extração automática de variáveis\n- Mapeamento de variáveis para signatários, campos customizados ou sistema\n- Geração de PDFs a partir de templates configurados\n- Suporte a 9 transformações: `formatCPF`, `formatCNPJ`, `formatPhone`, `formatCEP`, `formatCurrency`, `formatDate` (customizável), `uppercase`, `lowercase`, `capitalize`\n\n### 🚀 Criação Automatizada de Envelopes via Templates (v3.0.1)\n- **Orquestração em uma chamada**: `envelopeService.createFromTemplates()`\n- **Processamento assíncrono**: Retorna 202 Accepted com jobId\n- **Polling de status**: `envelopeService.getJobStatus(jobId)`\n- **Cancelamento**: `envelopeService.cancelJob(jobId)`\n- **Recursos avançados**:\n  - Múltiplos templates + múltiplos signatários\n  - Deduplicação automática por email\n  - Variáveis globais com sobrescrita local\n  - Anchor strings para posicionamento inteligente\n  - Ativação e notificação opcionais\n- **Exemplo completo**: Ver `sdk/examples/25-envelope-from-templates.ts`\n- **Integração CRM**: Ideal para automação de processos documentais\n\n### ✍️ Assinantes\n- Adicionar múltiplos signatários\n- Configurar ordem de assinatura\n- Campos customizados por signatário\n- Qualificação (parte, testemunha)\n- Endereços completos\n\n### 🧾 Recebimento Simples (Fase 13)\n- **Tipo de Envelope**: Crie envelopes do tipo `RECEIPT` para confirmação de recebimento.\n- **Papel do Participante**: Adicione `Receivers` que apenas confirmam o recebimento, sem assinatura digital.\n- **Autenticação Simplificada**: Use tokens de 6 dígitos via Email, SMS ou WhatsApp para confirmar.\n- **Selo Visual**: O PDF é carimbado com \"RECEBIDO DIGITALMENTE\" e todas as evidências.\n- **Endpoints Públicos**: Permite a confirmação sem login de usuário, ideal para interfaces web simples.\n\n### ✅ Aprovação de Documentos (Fase 13)\n- **Tipo de Envelope**: Suporte ao tipo `APPROVAL` para fluxos de aprovação formais.\n- **Papel do Participante**: Adicione `Approvers` com poder de `APROVAR` ou `REJEITAR`.\n- **Fluxos de Aprovação**: Configure aprovações em `PARALELO` (todos juntos) ou `SEQUENCIAL` (em ordem).\n- **Lógica de Rejeição**: Cancele o envelope automaticamente se um aprovador rejeitar (`blockOnRejection`).\n- **Comentários e Selos**: Aprovadores podem deixar comentários, e o PDF recebe um selo visual da decisão.\n- **Endpoints Públicos**: Permite a decisão (aprovar/rejeitar) através de uma URL pública com token.\n\n### ✍️ Assinatura e Rubrica do Perfil (signatureFields)\n- **Upload de assinatura manuscrita**: Salvar assinatura PNG no perfil do signatário\n- **Upload de rubrica (iniciais)**: Salvar rubrica PNG no perfil do signatário\n- **Reutilização automática**: Backend busca imagens do perfil automaticamente ao assinar\n- **Stamp Group**: Criar carimbo de assinatura (SIGNATURE + TEXT + DATE) com posicionamento relativo automático\n- **Rubricas automáticas**: Criar campos INITIAL em todas as páginas (exceto última) com um único comando\n- **Gerenciamento**: Atualizar ou remover assinatura/rubrica salva\n- **Benefícios**:\n  - ✅ Cliente desenha assinatura UMA VEZ e reutiliza em todos os documentos\n  - ✅ Assinaturas consistentes em múltiplos contratos\n  - ✅ Processo muito mais rápido (sem reenvio de imagem)\n  - ✅ Layout profissional de carimbos automatizado\n  - ✅ Backend abstrai lógica de paginação e posicionamento\n\n### 🔐 Autenticação de Assinantes (Fase 8)\n- **10+ métodos de autenticação**:\n  - `EMAIL_TOKEN` - Token de 6 dígitos por email\n  - `SMS_TOKEN` - Token por SMS\n  - `WHATSAPP_TOKEN` - Token por WhatsApp\n  - `IP_ADDRESS` - Validação de endereço IP\n  - `GEOLOCATION` - Validação de localização GPS\n  - `OFFICIAL_DOCUMENT` - Processa automáticamente RG ou CNH - Usado em Validation Layer\n  - `SELFIE` - Selfie simples sem documento\n  - `SELFIE_WITH_DOCUMENT` - Selfie para comparação biométrica com documento\n  - `ADDRESS_PROOF` - Comprovante de residência\n  - `RG_FRONT` - RG Frente (Validation Layer)\n  - `RG_BACK` - RG Verso (Validation Layer)\n  - `CNH_FRONT` - CNH Frente (Validation Layer)\n\n### 🤖 Validation Layer (AI-Powered)\n- **Novos métodos específicos de documentos**:\n  - `RG_FRONT` - RG Frente (foto do rosto)\n  - `RG_BACK` - RG Verso (CPF e nome completo)\n  - `CNH_FRONT` - CNH Frente (foto, CPF e nome)\n- **Validação automatizada por IA**:\n  - **OCR**: Extração automática de CPF, nome e dados do documento\n  - **Biometria Facial**: Comparação 1:1 entre documento e selfie\n  - **Liveness Detection**: Anti-spoofing e detecção de fraudes\n  - **Quality Check**: Análise de nitidez, iluminação e enquadramento\n- **Estados de validação**: `PENDING` → `IN_ANALYSIS` → `VERIFIED` / `REJECTED`\n- **Processamento assíncrono**: BullMQ para filas e jobs paralelos\n- **Polling de progresso**: Consulta em tempo real (0-100%)\n- **Códigos de erro detalhados**: 15+ códigos com dicas amigáveis\n- **Gatekeeper contextual**: Validação de IP whitelist/blacklist e geofencing\n\n### 🔑 JWT Token System para Signatários (Fase 12)\n- **Autenticação segura** com tokens JWT assinados criptograficamente\n- **Access Token**: JWT de curta duração (15 minutos padrão)\n  - Assinado com algoritmo HMAC SHA-256\n  - Payload contém: signerId, envelopeId, email\n  - Validação automática de expiração e revogação\n- **Refresh Token**: UUID de longa duração (7 dias padrão)\n  - Armazenado no banco de dados\n  - Token rotation: gera novo par ao renovar\n  - Previne reutilização de tokens comprometidos\n- **Endpoints públicos** (não requerem autenticação de usuário):\n  - `POST /api/v1/signers/refresh-token` - Renovar access token\n  - `POST /api/v1/signers/revoke-token` - Logout/revogação\n- **Segurança multicamada**:\n  - Defense in depth: validação JWT + banco de dados\n  - Token mismatch detection (previne replay attacks)\n  - Revogação instantânea e irreversível\n  - Cleanup automático de tokens expirados/revogados\n- **Auto-refresh recomendado**: Renovar 2-5 minutos antes da expiração\n- **Configurável via ENV**: `SIGNER_JWT_EXPIRES_IN` e `SIGNER_JWT_REFRESH_EXPIRES_IN`\n- **Uso com preview**: o JWT do signatário pode acessar `GET /documents/:id/preview`, `GET /documents/:id/pages` e `GET /documents/:id/fields` (sem usuário interno).\n\n### 🧭 Signing Session (Signer JWT)\n- **Endpoint agregado**: `GET /api/v1/signing-session`\n- **Contexto completo**: envelope, signatário, documentos (com contagens de fields) e progresso\n- **Autenticação**: JWT do signatário (Bearer)\n- **Regras**: envelope precisa estar `RUNNING` e step-up obrigatório deve estar satisfeito\n- **Uso típico**: frontends públicos de assinatura sem proxies\n\n### 📢 Notificações Multi-Canal (Fase 6)\n- Notificações por **Email**, **SMS** e **WhatsApp**\n- Templates de notificação customizáveis\n- Lembretes automáticos agendados\n- Histórico completo de notificações\n- Retentativas automáticas para falhas\n\n### 🔍 Verificação Pública (Fase 4)\n- Verificação de documentos assinados por hash SHA256 (uso técnico/auditoria)\n- QR Code oficial usa token curto (`/api/v1/v/:token`)\n- Download público por hash existe apenas como fluxo avançado/auditoria\n- Exibição de signatários e status de assinaturas\n- Validação de integridade do documento\n\n### 🔐 Assinatura Digital PAdES (Fase 3)\n- Gerenciamento de certificados digitais ICP-Brasil (A1, A3, A4)\n- Upload seguro de certificados P12/PFX\n- Múltiplas estratégias de assinatura:\n- `VISUAL_ONLY`: Apenas carimbos visuais (padrão atual)\n  - `PADES_EACH`: PAdES em cada assinatura individual\n  - `PADES_FINAL`: Múltiplas assinaturas visuais + PAdES único ao final ⭐\n  - `HYBRID`: Assinaturas visuais + PAdES seletivo por signatário\n  - `HYBRID_SEALED`: Assinaturas visuais + selo organizacional automático\n- Assinatura PAdES-B compatível com Adobe Reader\n- Estatísticas de certificados (total, ativos, expirando)\n- Ativação/desativação e revogação de certificados\n- Armazenamento seguro de senhas para automação\n\n### 📄 Papel Timbrado (Fase 10)\n- Upload de papel timbrado/letterhead PNG\n- Aplicação automática em documentos PDF\n- Configuração de opacidade, posição e páginas\n- Download e gerenciamento via API\n- Integração transparente no workflow\n\n### 🖼️ Logo da Organização (Fase 12)\n- Upload de logo (PNG, JPG, SVG)\n- Dimensões recomendadas: 512x512px (quadrado)\n- Tamanho máximo: 5MB\n- Uso como stamp padrão nos documentos\n- Download e gerenciamento via API\n- Integração automática com stampTemplate\n\n### 🔐 Autenticação Híbrida de Usuários (JWT + API Token)\n- **JWT (JSON Web Token)**: Para usuários humanos com sessões\n  - Obtido via `POST /api/v1/auth/login` com email/senha\n  - Curta duração (15 minutos padrão)\n  - Refresh automático com refreshToken\n  - Ideal para: aplicações web, mobile apps, sessões interativas\n- **API Token**: Para integrações M2M (machine-to-machine)\n  - Criado via `POST /api/v1/api-tokens` (requer JWT)\n  - Longa duração ou permanente (configurável)\n  - Sem refresh - token estático até expirar/revogar\n  - Ideal para: CI/CD, webhooks, integrações, scripts automatizados\n- **Autenticação Unificada**: Ambos funcionam no mesmo header `Authorization: Bearer <token>`\n- **Prioridade**: API Token verificado primeiro (DB lookup), fallback para JWT (in-memory)\n- **Performance**: API Token ~2-5ms | JWT <1ms\n\n### 🚀 Performance: ETag Caching\n\nO SDK possui suporte integrado a **cache automático via ETags** para economizar largura de banda e melhorar performance.\n\n**O que são ETags?**\n- ETags (Entity Tags) são identificadores únicos retornados pelo servidor para cada versão de um recurso\n- Permitem validação condicional: cliente pergunta \"mudou desde a última vez?\" em vez de baixar tudo novamente\n- Se não mudou, servidor retorna `304 Not Modified` (sem corpo, ~100 bytes) em vez de `200 OK` com dados completos\n\n**Benefícios:**\n- ✅ Economiza largura de banda (até 95% em cache hits)\n- ✅ Reduz latência de rede\n- ✅ Menos processamento no servidor\n- ✅ Previne conflitos com optimistic locking\n\n### 🔐 Níveis de Autenticação Padrão para Assinantes (Fase 12)\n- **BASIC**: Email + IP + Geolocalização (mínimo recomendado)\n- **STANDARD**: BASIC + WhatsApp/SMS + Documento + Selfie\n- **STRICT**: STANDARD + Comprovante de endereço (obrigatório para PAdES)\n- Configuração por organização com override por envelope/signatário\n- Recomendação automática baseada na estratégia de assinatura\n\n### 🏢 Gestão de Usuários e Organizações (Fase 11 + Fase 12)\n- **Registro de Usuários**: Criar novos usuários via API pública\n- **API Tokens**: CRUD completo de tokens para acesso programático\n- **Organizações**: Gerenciar organizações, planos e limites\n- **Roles**: OWNER, ADMIN, MEMBER com controle de permissões\n- **Multi-tenancy**: Isolamento completo de dados por organização\n- **Estatísticas**: Usuários ativos, envelopes do mês, storage usado\n- **Planos**: FREE, BASIC, PREMIUM, ENTERPRISE\n- **🆕 Gerenciamento de Membros (Fase 12)**:\n  - Adicionar usuários a organizações existentes\n  - Vincular novos usuários sem criar nova organização\n  - Alterar roles de membros (promover/rebaixar)\n  - Remover membros da organização\n  - Validação de limites e permissões\n  - Controle granular de acesso (OWNER, ADMIN, MEMBER)\n\n### 🏗️ Setores Organizacionais\n- **Hierarquia de Setores**: Estrutura em árvore (Diretoria > Gerência > Equipe)\n- **Códigos Únicos**: Identificadores customizados (`JUR`, `TI`, `RH`)\n- **Path Automático**: Navegação hierárquica (`/diretoria/gerencia`)\n- **Gestores**: Atribuição de responsável por setor\n- **Membros N:N**: Usuário pode pertencer a múltiplos setores\n- **Destinatários Internos**: Vincular signatários a usuários via `userId`\n- **Busca por Setor**: Listar membros para adicionar como signatários\n- **Soft Delete**: Desativação sem perda de dados\n\n## 📖 Exemplos\n\nO SDK inclui **26+ exemplos práticos** no diretório `examples/` com um README.md próprio:\n\n**Destaque v3.0.1:**\n- **Exemplo 25**: Criação automatizada de envelopes via templates com processamento assíncrono\n- **Exemplo 26**: Gestão de setores organizacionais e destinatários internos\n\nVeja [examples/README.md](./examples/README.md) para a lista completa.\n\n---\n\n## ⚠️ Convenção de Nomenclatura (camelCase)\n\nO SDK segue o padrão **camelCase** para todos os campos (convenção JavaScript/TypeScript).\n\n**Exemplo de uso do SDK:**\n```typescript\nconst envelope = await client.envelopes.create({\n  name: 'Contrato',\n  deadline: '2024-02-15T23:59:59Z',\n  customFields: {\n    contractNumber: '2024/001'\n  }\n});\n```\n\n### Integração com Sistemas snake_case\n\nSe o seu sistema usa **snake_case** (comum em PostgreSQL, Python, Ruby), você precisará fazer transformação bidirecional dos dados antes de enviar ao SDK e após receber respostas.\n\n**Bibliotecas Recomendadas:**\n- **JavaScript/Node.js**: [`camelcase-keys`](https://www.npmjs.com/package/camelcase-keys), [`snakecase-keys`](https://www.npmjs.com/package/snakecase-keys)\n- **Python**: Módulos built-in ou [`humps`](https://github.com/nficano/humps)\n- **Ruby**: [`plissken`](https://github.com/Gaelan/plissken) gem\n\n**Exemplo de transformação (JavaScript):**\n```javascript\nimport camelcaseKeys from 'camelcase-keys';\nimport snakecaseKeys from 'snakecase-keys';\nimport { SignatureClient } from 'signature-module';\n\nconst client = new SignatureClient({\n  baseURL: 'https://api.example.com',\n  accessToken: 'your_token'\n});\n\n// Dados do seu sistema (snake_case)\nconst localData = {\n  envelope_name: 'Contrato',\n  created_at: '2024-01-15',\n  custom_fields: { contract_number: '2024/001' }\n};\n\n// Converter para camelCase antes de enviar ao SDK\nconst sdkPayload = camelcaseKeys(localData, { deep: true });\nconst envelope = await client.envelopes.create(sdkPayload);\n\n// Converter resposta para snake_case para uso local\nconst responseInSnakeCase = snakecaseKeys(envelope, { deep: true });\n// { id: 'env_123', envelope_name: 'Contrato', created_at: '2024-01-15', ... }\n```\n\n**Nota:** O SDK não oferece conversão automática para manter a biblioteca leve e previsível. A transformação é responsabilidade da aplicação cliente.\n\n---\n\n## 💡 Exemplos de Uso\n\n### Setores Organizacionais\n\n```typescript\n// Criar setor\nconst setor = await client.sectors.create({\n  name: 'Diretoria Jurídica',\n  code: 'JUR',\n});\n\n// Criar sub-setor\nconst subSetor = await client.sectors.create({\n  name: 'Equipe Contratos',\n  code: 'CONTR',\n  parentId: setor.id,\n});\n\n// Obter árvore completa\nconst tree = await client.sectors.getTree();\n\n// Adicionar membro\nawait client.sectors.addUser(setor.id, {\n  userId: 'user-123',\n  isPrimary: true,\n});\n\n// Listar membros de um setor\nconst membros = await client.sectors.getUsers(setor.id);\n```\n\n### Destinatários Internos\n\n```typescript\n// Adicionar signatário interno (name e email preenchidos do User)\nconst signer = await client.signers.create(envelopeId, {\n  userId: 'user-123',\n  signingOrder: 1,\n});\nconsole.log(signer.isInternal); // true\nconsole.log(signer.user?.name); // Nome do usuário\n```\n\n---\n\n## 📖 Quick Start e Documentação rápida\n\nVeja [QUICKSTART_DOCUMENTACAO.md](./QUICKSTART_DOCUMENTACAO.md) para acessar.\n\n**Cobertura de Testes:**\n- ✅ **56 testes unitários** dos validadores (100% cobertura das validações client-side)\n- ✅ **19 exemplos funcionais** que servem como documentação viva\n- ✅ **API completamente testada** (unit + integration + e2e)\n\n**Por que não temos testes de integração extensivos no SDK?**\n\nO SDK é essencialmente um cliente HTTP. Como a API já possui cobertura completa de testes, focamos em:\n1. Validar as **validações client-side** (tamanho arquivo, MIME types, etc.)\n2. Garantir que os **tipos TypeScript estão corretos** (typecheck)\n3. Manter **exemplos funcionais e atualizados**\n\n## 📊 API Swagger\n\nPara documentação interativa completa da API, acesse:\n\n```\nhttps://sua-api.com/api/docs\n```\n\nA documentação Swagger inclui:\n- Todos os endpoints disponíveis\n- Exemplos de request/response\n- Schemas detalhados\n- Interface para testar endpoints\n\n## 🔗 Links Úteis\n\n- **Swagger/OpenAPI**: `/api/docs` (documentação interativa)\n- **Migration Guide**: [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)\n- **Examples**: [examples/](./examples/)\n- **Types**: [src/types/](./src/types/)\n\n## 🤝 Suporte\n\nPara questões, bugs ou sugestões:\n\n1. Abra uma issue no repositório\n2. Consulte a documentação Swagger\n3. Veja os exemplos práticos em `examples/`\n\n## 📄 Licença\n\nMIT\n\n---\n","readmeFilename":"README.md"}