{"_id":"@4signer/signer-connector-sdk","name":"@4signer/signer-connector-sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@4signer/signer-connector-sdk","version":"1.0.0","description":"Official JavaScript SDK for Signer Connector API and Desktop Agent flow","type":"module","main":"./src/index.js","module":"./src/index.js","exports":{".":{"import":"./src/index.js","types":"./types/index.d.ts"},"./telemetry":{"import":"./src/telemetry.js","types":"./types/index.d.ts"}},"types":"./types/index.d.ts","scripts":{"check":"node --input-type=module -e \"import('./src/index.js').then(()=>process.exit(0)).catch((e)=>{console.error(e);process.exit(1)})\""},"keywords":["signer","pdf","xml","signature","connector","agent","a3","a1"],"license":"MIT","engines":{"node":">=18"},"_id":"@4signer/signer-connector-sdk@1.0.0","gitHead":"14074ba13ad90eaa4d1c3fe56ccae59122e02201","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-LWP6QGHhMlB5Ll4TPyt5UFOeudyLL17fQYIqBkH+2CDbiKba4Of1Hp/hAL7bQNPg9NwXKeRfZgcUD6QuY4OtTA==","shasum":"afed19000125de827dc4e35b5de2874ce0cc829b","tarball":"https://registry.npmjs.org/@4signer/signer-connector-sdk/-/signer-connector-sdk-1.0.0.tgz","fileCount":6,"unpackedSize":28096,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDhw0TgxSG8HUSZLs+HOqbSXA1XhnwJC5TVV0mqduACWwIhALWgW/FpMx3zacRwbSye+VpJxbGRM/dn9aqFeFbdW7UK"}]},"_npmUser":{"name":"jeidison","email":"jeidison.farias@gmail.com"},"directories":{},"maintainers":[{"name":"jeidison","email":"jeidison.farias@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/signer-connector-sdk_1.0.0_1771359091529_0.6019200282352206"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-17T20:11:31.420Z","1.0.0":"2026-02-17T20:11:31.707Z","modified":"2026-02-17T20:11:31.989Z"},"maintainers":[{"name":"jeidison","email":"jeidison.farias@gmail.com"}],"description":"Official JavaScript SDK for Signer Connector API and Desktop Agent flow","keywords":["signer","pdf","xml","signature","connector","agent","a3","a1"],"license":"MIT","readme":"# @4signer/signer-connector-sdk\n\nSDK oficial JavaScript para orquestrar assinatura de documentos (PDF/XML) com a Signer API:\n- fluxo local via Desktop Agent (A1/A3 instalados)\n- fluxo nuvem via provider credential\n- fallback automático (`certificateMode: auto`)\n\n## Instalação\n\n```bash\nnpm install @4signer/signer-connector-sdk\n```\n\n## Uso rápido\n\n```js\nimport { createSignerConnector } from '@4signer/signer-connector-sdk';\n\nconst connector = createSignerConnector({\n  apiBaseUrl: 'https://seu-saas.com/api/v1',\n  bearerToken: process.env.SIGNER_API_TOKEN, // token da account\n  accountSlug: 'clinica-abc', // opcional se backend inferir pela conta do token\n  localAgentBaseUrl: 'http://127.0.0.1:9876',\n  telemetryEndpoint: 'https://seu-saas.com/api/v1/telemetry/logs',\n  sdkVersion: '1.0.0',\n});\n\nconst result = await connector.sign({\n  documentId: 'prescricao-0001',\n  documentType: 'pdf', // pdf | xml\n  xmlProfile: 'fiscal', // fiscal | diploma (quando documentType=xml)\n  xmlPolicy: 'nfe-4.00', // opcional para XML\n  certificateMode: 'auto', // auto | local | cloud\n  documentContentBase64: pdfBase64,\n  providerHint: 'birdid', // usado quando cloud\n  providerCredentialId: 10, // preferencial quando cloud\n  metadata: { source: 'prontuario' },\n  requestOptions: { certificateId: 'abc' }, // usado no fluxo local\n});\n\nconsole.log(result.status);\n```\n\n## Eventos de fluxo\n\n- `flow:started`\n- `flow:awaiting_approval`\n- `flow:fallback_cloud`\n- `flow:signed`\n- `flow:failed`\n- `agent:not_found`\n\n```js\nconst unsub = connector.on('flow:failed', (event) => {\n  console.error('Falha de assinatura', event);\n});\n```\n\n## Erros\n\nTodos os erros de SDK/API são `SignerConnectorError`:\n\n```js\ntry {\n  await connector.sign(payload);\n} catch (error) {\n  if (error.name === 'SignerConnectorError') {\n    console.error(error.code, error.message, error.recoverable, error.details);\n  }\n}\n```\n\n## Recomendações para produção\n\n- Gere token Sanctum por account, com expiração curta.\n- Se usar local, mantenha Desktop Agent em `http://127.0.0.1:9876`.\n- Em cloud, trate estado `pending_approval` e faça polling com `getStatus`.\n- Baixe o arquivo assinado apenas quando `status === 'signed'`.\n- Envie `metadata` com `document_id` do parceiro para rastreabilidade.\n\n## Exemplos\n\n- `examples/node-cloud-sign.mjs`\n- `examples/browser-cloud.html`\n- `examples/browser-local-agent.html`\n\n### Executar exemplo Node com XML\n\n```bash\nSIGNER_API_BASE_URL=\"http://127.0.0.1:8000/api/v1\" \\\nSIGNER_API_TOKEN=\"seu_token\" \\\nSIGNER_PROVIDER_HINT=\"serproid\" \\\nSIGNER_PROVIDER_CREDENTIAL_ID=\"12\" \\\nSIGNER_DOCUMENT_TYPE=\"xml\" \\\nSIGNER_XML_PROFILE=\"diploma\" \\\nSIGNER_XML_POLICY=\"diploma-icpbrasil-xades-1.0\" \\\nSIGNER_XML_PATH=\"/caminho/para/documento.xml\" \\\nnode examples/node-cloud-sign.mjs\n```\n\n## API pública\n\n- `createSignerConnector(options)`\n- `createSignerConnectorTelemetry(options)`\n- `SignerConnector`\n- `SignerConnectorError`\n","readmeFilename":"README.md","_rev":"1-16e3b8bc441f74207752e4c27de8d431"}