docs(sdk): add comprehensive integration examples in sdk/examples

2026-10-20 16:43:46 -03:00
parent 50b5feced5
commit b19d09a236
5 changed files with 345 additions and 0 deletions
@@ -0,0 +1,75 @@
+# Exemplos de Integração — CyberCore Signer Web SDK
+
+Este diretório contém exemplos práticos e prontos para uso demonstrando os principais fluxos de integração do `@cybercore/signer-sdk` com aplicações web.
+
+---
+
+## 📁 Arquivos de Exemplo
+
+| Arquivo | Descrição |
+| :--- | :--- |
+| [`01-crypto-login.js`](./01-crypto-login.js) | Autenticação segura por desafio criptográfico (Challenge-Response) sem senhas. |
+| [`02-sign-digest.js`](./02-sign-digest.js) | Assinatura desacoplada em que o navegador calcula o hash SHA-256 e o CyberCore assina apenas o digest. |
+| [`03-sign-pades.js`](./03-sign-pades.js) | Assinatura digital completa de PDF (PAdES) com selo gráfico posicionado (ICP-Brasil / Gov.br). |
+| [`04-error-handling.js`](./04-error-handling.js) | Captura e tratamento estruturado de todos os erros do protocolo CCSP/1 com guia acionável. |
+
+---
+
+## 🚀 Como Executar
+
+### Pré-requisitos
+1. Agente desktop **CyberCore Signer** em execução na máquina (`127.0.0.1:21325`).
+2. Node.js 18+ instalado.
+
+### Execução direta via Node.js
+Como o pacote usa módulos ES (`"type": "module"`), você pode testar diretamente com:
+
+```bash
+# Executar exemplo de login
+node examples/01-crypto-login.js
+
+# Executar exemplo de assinatura de digest
+node examples/02-sign-digest.js
+
+# Executar exemplo de assinatura PAdES com selo
+node examples/03-sign-pades.js
+
+# Executar exemplo de tratamento de erros
+node examples/04-error-handling.js
+```
+
+---
+
+## 💡 Uso em Projetos Frontend (React, Vue, Angular, Svelte, Vanilla)
+
+Instale o pacote a partir do seu registry npm privado:
+```bash
+npm install @cybercore/signer-sdk
+```
+
+Importe os métodos e tipos em qualquer componente ou serviço web:
+```typescript
+import { CyberCoreSigner, AgentNotRunningError } from '@cybercore/signer-sdk';
+
+const signer = new CyberCoreSigner({
+  applicationName: 'Meu Sistema Web'
+});
+
+async function assinarDocumento(arquivoPdf: File, certId: string) {
+  try {
+    const resultado = await signer.signPdfDocument({
+      pdf: arquivoPdf,
+      certificateId: certId,
+      position: 'BOTTOM_RIGHT',
+      sealThemeId: 'icp-brasil'
+    });
+
+    // Baixa o documento assinado no navegador
+    resultado.download('documento_assinado.pdf');
+  } catch (err) {
+    if (err instanceof AgentNotRunningError) {
+      alert(err.actionableGuidance);
+    }
+  }
+}
+```