{"_id":"@aldeia/audit-sdk","_rev":"2-7c086537cd797013eea3b67afcf48202","name":"@aldeia/audit-sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@aldeia/audit-sdk","version":"0.1.0","keywords":["audit","logging","sdk","typescript","kafka","microservices","observability"],"author":{"name":"mathausdev"},"license":"MIT","_id":"@aldeia/audit-sdk@0.1.0","maintainers":[{"name":"mathauscm","email":"mathauscarvalho@gmail.com"}],"homepage":"https://github.com/mathauscm/audit-sdk#readme","bugs":{"url":"https://github.com/mathauscm/audit-sdk/issues"},"dist":{"shasum":"80c96686a5931bfabf808533eac7076e1d75bea5","tarball":"https://registry.npmjs.org/@aldeia/audit-sdk/-/audit-sdk-0.1.0.tgz","fileCount":7,"integrity":"sha512-fSYiTnSFKbS8Xldn4aP2hfPtNBBXlpaJwpoSsS/32TXuzPHX4jTYt4kiqXC1imK7QobJXTu0I9yoTLfTFgf+ZA==","signatures":[{"sig":"MEQCIGh/ds6AWrSMoN7vQfUbVrkYJ5tv8pTiY3JSkiI03YO0AiBD1eBSD7hVpqZZCm4lU23SVd2/pwpI9vJswiivBV8BxA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10205},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"private":false,"scripts":{"lint":"npm run typecheck","test":"npm run build && node --test \"test/**/*.test.mjs\"","build":"tsc -p tsconfig.json","format":"echo \"no formatter configured\"","typecheck":"tsc --noEmit -p tsconfig.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"mathauscm","email":"mathauscarvalho@gmail.com"},"repository":{"url":"git+https://github.com/mathauscm/audit-sdk.git","type":"git"},"_npmVersion":"11.6.2","description":"SDK de audit logging para serviços internos (HTTP → serviço de auditoria)","directories":{"test":"test"},"_nodeVersion":"24.13.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/audit-sdk_0.1.0_1772030986251_0.14114163918666112","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aldeia/audit-sdk","version":"0.1.1","private":false,"description":"SDK de audit logging para serviços internos (HTTP → serviço de auditoria)","keywords":["audit","logging","sdk","typescript","kafka","microservices","observability"],"homepage":"https://github.com/mathauscm/audit-sdk#readme","bugs":{"url":"https://github.com/mathauscm/audit-sdk/issues"},"repository":{"type":"git","url":"git+https://github.com/mathauscm/audit-sdk.git"},"license":"MIT","author":{"name":"mathausdev"},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"main":"dist/index.js","types":"dist/index.d.ts","directories":{"test":"test"},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc --noEmit -p tsconfig.json","prepublishOnly":"npm run build","format":"echo \"no formatter configured\"","lint":"npm run typecheck","test":"npm run build && node --test test/*.test.mjs"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.0.0"},"engines":{"node":">=18"},"_id":"@aldeia/audit-sdk@0.1.1","gitHead":"cd170d4904e1a48aaf9c3962bb93aeafe7875586","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-wIwyCMCO4VP0JsvLOG0jyP30XCpCJ9CJqjVioZnrOq28mYpbZsYzNT6z4rtkjjCeU3RpQDggjhAUbTm/gpQqbw==","shasum":"a8c09d5196423b751657201e684431323c1484b5","tarball":"https://registry.npmjs.org/@aldeia/audit-sdk/-/audit-sdk-0.1.1.tgz","fileCount":7,"unpackedSize":10198,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aldeia%2faudit-sdk@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAUqALGkPOlsHxWEqKJ2pu7o5P3lmRsliXEunxEBH1DQAiBRCxWeEPKs+GKwHxrLxj59WB2d+mRY+IXSuK/QLCx3bw=="}]},"_npmUser":{"name":"mathauscm","email":"mathauscarvalho@gmail.com"},"maintainers":[{"name":"mathauscm","email":"mathauscarvalho@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/audit-sdk_0.1.1_1772031901542_0.7166768854030385"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-25T14:49:46.172Z","modified":"2026-02-25T15:05:02.016Z","0.1.0":"2026-02-25T14:49:46.392Z","0.1.1":"2026-02-25T15:05:01.715Z"},"bugs":{"url":"https://github.com/mathauscm/audit-sdk/issues"},"author":{"name":"mathausdev"},"license":"MIT","homepage":"https://github.com/mathauscm/audit-sdk#readme","keywords":["audit","logging","sdk","typescript","kafka","microservices","observability"],"repository":{"type":"git","url":"git+https://github.com/mathauscm/audit-sdk.git"},"description":"SDK de audit logging para serviços internos (HTTP → serviço de auditoria)","maintainers":[{"name":"mathauscm","email":"mathauscarvalho@gmail.com"}],"readme":"# @aldeia/audit-sdk\n\n[![npm version](https://img.shields.io/npm/v/@aldeia/audit-sdk.svg)](https://www.npmjs.com/package/@aldeia/audit-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nSDK de audit logging para Node.js e TypeScript.\n\nPermite registrar eventos de auditoria de forma padronizada e enviá-los para um serviço central via HTTP. Ideal para arquiteturas baseadas em microserviços, eventos e observabilidade.\n\nZero dependências de produção. Compatível com Node 18+ e Bun.\n\n---\n\n## 📦 Instalação\n\n```bash\nnpm install @aldeia/audit-sdk\n```\n\nou\n\n```bash\nbun add @aldeia/audit-sdk\n```\n\n---\n\n## 🚀 Uso Básico\n\n```ts\nimport { createAuditLogger } from '@aldeia/audit-sdk';\n\nconst audit = createAuditLogger({\n  serviceName: 'user-service',\n  endpoint: 'http://localhost:3000/logs',\n  apiKey: process.env.AUDIT_API_KEY,\n});\n\naudit.log({\n  workspaceId: 'workspace-123',\n  action: 'UPDATE',\n  resourceType: 'user',\n  resourceId: 'user-42',\n  actorType: 'user',\n  actorId: 'admin-1',\n  metadata: {\n    changedFields: ['email']\n  }\n});\n```\n\nPor padrão, o SDK funciona em modo **fire-and-forget** (não bloqueia o fluxo principal da aplicação).\n\n---\n\n## ⚙️ Criando uma Instância\n\n```ts\nimport { createAuditLogger } from '@aldeia/audit-sdk';\n\nconst audit = createAuditLogger({\n  serviceName: 'my-service',\n  endpoint: 'https://audit.mycompany.com/logs',\n  apiKey: 'my-secret-key',\n  fireAndForget: true\n});\n```\n\n### Opções Disponíveis\n\n| Opção | Tipo | Obrigatório | Descrição |\n|-------|------|------------|------------|\n| serviceName | string | ✅ | Nome do serviço que está gerando os logs |\n| endpoint | string | ✅ | URL do serviço de auditoria |\n| apiKey | string | ❌ | Token opcional enviado no header `x-api-key` |\n| fireAndForget | boolean | ❌ | Se true (default), não aguarda resposta HTTP |\n\n---\n\n## 🧾 Estrutura do Evento\n\n```ts\ninterface AuditEvent {\n  timestamp?: string;\n  workspaceId?: string;\n  serviceName: string;\n\n  action: string;\n  resourceType: string;\n  resourceId?: string;\n\n  actorType?: 'user' | 'system';\n  actorId?: string | number;\n\n  ip?: string;\n  userAgent?: string;\n  requestId?: string;\n\n  before?: unknown;\n  after?: unknown;\n  metadata?: Record<string, unknown>;\n}\n```\n\n### Observações\n\n- `serviceName` e `timestamp` são preenchidos automaticamente pelo SDK.\n- `before` e `after` podem armazenar estado anterior e posterior de uma operação.\n- `metadata` permite extensão livre do evento.\n\n---\n\n## ⏳ Usando com Await\n\nSe desejar aguardar confirmação do serviço de audit:\n\n```ts\nconst audit = createAuditLogger({\n  serviceName: 'my-service',\n  endpoint: 'http://localhost:3000/logs',\n  fireAndForget: false\n});\n\nawait audit.log({\n  action: 'CREATE',\n  resourceType: 'invoice',\n  resourceId: 'inv-999'\n});\n```\n\n---\n\n## 🏗️ Arquitetura Recomendada\n\nAplicação → SDK → Serviço de Auditoria → Event Bus (ex: Kafka) → Writer → Banco de Dados\n\nO SDK é responsável apenas por padronizar e enviar o evento. Persistência e processamento ficam no serviço de auditoria.\n\n---\n\n## 🔒 Garantias\n\n- Nunca lança erro para a aplicação chamadora.\n- Não bloqueia o fluxo principal por padrão.\n- Sem dependências externas em runtime.\n- Compatível com ESM.\n\n---\n\n## 🧩 Compatibilidade\n\n- Node.js 18+\n- Bun\n- TypeScript\n- ESM\n\n---\n\n## 📄 Licença\n\nMIT\n\n---\n\nPowered by [@mathauscm](https://github.com/mathauscm)","readmeFilename":"README.md"}