# SDK Web JavaScript (@cybercore/signer-sdk)

O `@cybercore/signer-sdk` é a biblioteca oficial cliente em JavaScript para integrar aplicações web modernas com o agente desktop **CyberCore Signer** via protocolo **CCSP/1**.

---

## 1. Instalação e Importação

### Via Módulo ES6 (Browser ou Bundler Vite/Webpack/Next.js)
```javascript
import { CyberCoreSigner } from '@cybercore/signer-sdk';

const signer = new CyberCoreSigner({
  applicationName: 'Portal Meu Negócio'
});
```

---

## 2. Métodos da API

### `isInstalled(timeoutMs = 2000): Promise<boolean>`
Testa rapidamente se o agente desktop está ativo na porta local `21325`.

### `connect(): Promise<boolean>`
Realiza o handshake inicial de autorização. Se for a primeira vez que a aplicação tenta se conectar, abre uma caixa de diálogo nativa no desktop do usuário para concessão de acesso.

### `getCertificates(): Promise<Array<Object>>`
Retorna todos os certificados A1 e A3 disponíveis e operacionais na máquina do usuário.

```javascript
const certs = await signer.getCertificates();
certs.forEach(cert => {
  console.log(`[${cert.type}] ${cert.common_name} (Validade: ${cert.valid_to})`);
});
```

### `sign(options): Promise<Object>`
Solicita a assinatura digital local de um digest ou conteúdo bruto.

### `signPdf(pdfFile, options): Promise<Object>`
Assina um documento PDF (PAdES / Assinatura desacoplada). Recebe `File`, `Blob`, `ArrayBuffer` ou `Uint8Array`.
Calcula o SHA-256 no próprio navegador e transmite metadados do documento (`PDF`) ao agente para exibição clara na janela de confirmação.

```javascript
const pdfResult = await signer.signPdf(fileInput.files[0], {
  certificateId: certs[0].id
});
```

### `signXml(xmlContent, options): Promise<Object>`
Assina um documento XML (XMLDSig / NF-e). Aceita string com o XML formatado ou objeto de arquivo `File`/`Blob`.

```javascript
const xmlResult = await signer.signXml(xmlString, {
  certificateId: certs[0].id,
  documentName: 'nfe-3524.xml'
});
```

### `signFile(file, options): Promise<Object>`
Assina qualquer arquivo (ZIP, DOCX, imagens, binários, executáveis) gerando pacote de assinatura detached / CAdES.

```javascript
const fileResult = await signer.signFile(fileInput.files[0], {
  certificateId: certs[0].id
});
```

### `authenticate(options): Promise<Object>` (ou `login(options)`)
Executa login seguro com certificado digital via desafio criptográfico (Challenge-Response).

```javascript
const auth = await signer.authenticate({
  certificateId: certs[0].id,
  challenge: 'server-nonce-12345'
});

console.log('Bem-vindo,', auth.subjectName);
console.log('CPF/CNPJ:', auth.subjectCpfCnpj);
console.log('Assinatura do Desafio:', auth.signature);
```

### `extractSubjectInfo(certificateBase64): { name, cpfCnpj }`
Decodifica o certificado X.509 e extrai os dados do titular ICP-Brasil (Nome, CPF ou CNPJ).

### `verify(options): Promise<boolean>`
Validação sintática e criptográfica da integridade da assinatura gerada.

---

## 3. Tratamento Estruturado de Erros

O SDK expõe classes de erro dedicadas que herdam de `CyberCoreError`:

```javascript
import {
  UserCancelledError,
  CertificateNotFoundError,
  PinIncorrectError,
  TokenNotFoundError
} from '@cybercore/signer-sdk/errors';

try {
  await signer.sign({ certificateId: 'cert-1', data: 'Contrato' });
} catch (err) {
  if (err instanceof UserCancelledError) {
    alert('Você cancelou a assinatura no CyberCore Signer.');
  } else if (err instanceof PinIncorrectError) {
    alert('O PIN do token informado está incorreto.');
  } else if (err instanceof TokenNotFoundError) {
    alert('Conecte o seu token USB na máquina para assinar.');
  } else {
    console.error('Erro na assinatura:', err);
  }
}
```