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,82 @@
+/**
+ * Exemplo 04: Tratamento Estruturado e Acionável de Erros
+ *
+ * Demonstra como capturar cada erro específico do CCSP/1 e orientar
+ * o usuário final com mensagens claras e passos práticos de resolução.
+ */
+
+import {
+  CyberCoreSigner,
+  AgentNotRunningError,
+  ApplicationNotAuthorizedError,
+  UserCancelledError,
+  CertificateNotFoundError,
+  CertificateExpiredError,
+  CertificateInvalidError,
+  PrivateKeyNotAvailableError,
+  PinRequiredError,
+  PinIncorrectError,
+  TokenNotFoundError,
+  RequestExpiredError,
+  TimeoutError,
+  CyberCoreError
+} from '@cybercore/signer-sdk';
+
+async function performSigningOperation(signer, certId, fileDigest) {
+  try {
+    return await signer.sign({
+      certificateId: certId,
+      digest: fileDigest,
+      documentName: 'termo_responsabilidade.pdf'
+    });
+  } catch (err) {
+    if (err instanceof AgentNotRunningError) {
+      // O agente local está fechado ou bloqueado
+      console.warn('⚠️ AGENTE NÃO DETECTADO:');
+      console.warn(err.actionableGuidance);
+      // Sugestão de UI: exibir banner com botão "Baixar CyberCore Signer"
+    } else if (err instanceof ApplicationNotAuthorizedError) {
+      // O usuário clicou em "Rejeitar" no prompt de autorização da aplicação
+      console.warn('⚠️ APLICAÇÃO NÃO AUTORIZADA:');
+      console.warn('O usuário não autorizou este portal no diálogo de segurança do CyberCore Signer.');
+    } else if (err instanceof UserCancelledError) {
+      // O usuário cancelou a assinatura explicitamente na janela nativa
+      console.info('ℹ️ Assinatura cancelada pelo usuário.');
+    } else if (err instanceof CertificateExpiredError) {
+      console.error('❌ CERTIFICADO EXPIRADO: O certificado digital selecionado expirou.');
+    } else if (err instanceof CertificateInvalidError) {
+      console.error('❌ CERTIFICADO INVÁLIDO: O certificado possui estrutura corrompida ou foi revogado.');
+    } else if (err instanceof PrivateKeyNotAvailableError) {
+      console.error('❌ CHAVE PRIVADA INDISPONÍVEL: A chave privada deste certificado não está acessível no computador.');
+    } else if (err instanceof PinIncorrectError) {
+      console.error('❌ PIN INCORRETO: O PIN digitado para o token A3 está errado. Cuidado com o bloqueio do dispositivo.');
+    } else if (err instanceof PinRequiredError) {
+      console.error('❌ PIN OBRIGATÓRIO: É necessário fornecer o PIN do dispositivo criptográfico.');
+    } else if (err instanceof TokenNotFoundError) {
+      console.error('❌ TOKEN NÃO ENCONTRADO: O token USB ou smart card foi removido da porta USB.');
+    } else if (err instanceof RequestExpiredError) {
+      console.warn('⚠️ REQUISIÇÃO EXPIRADA: O tempo limite para confirmação do usuário esgotou.');
+    } else if (err instanceof TimeoutError) {
+      console.error('⏱️ TIMEOUT: O agente demorou mais tempo que o esperado para responder.');
+    } else if (err instanceof CyberCoreError) {
+      console.error(`⚠️ ERRO DO PROTOCOLO CCSP (${err.code}):`, err.message);
+    } else {
+      console.error('Erro desconhecido:', err);
+    }
+    throw err;
+  }
+}
+
+async function main() {
+  const signer = new CyberCoreSigner({ timeoutMs: 15000 });
+  const fakeDigest = Buffer.alloc(32, 9).toString('base64');
+
+  console.log('Testando tratamento de erros com certificado simulado expirado...');
+  try {
+    await performSigningOperation(signer, 'cert-expirado', fakeDigest);
+  } catch {
+    console.log('Tratamento de exceções concluído com sucesso.');
+  }
+}
+
+main().catch(() => {});