@meistrari/audit-sdk 0.4.2 → 0.5.0

package/README.md

@@ -0,0 +1,130 @@
+# @meistrari/audit-sdk
+
+TypeScript client for the Audit Service. Sends audit events to `POST /v1/events` with retries, backoff and `429 Retry-After` handling. Failures after retries are logged via `@meistrari/logger` instead of throwing.
+
+## Install
+
+```bash
+bun add @meistrari/audit-sdk
+# or
+npm install @meistrari/audit-sdk
+```
+
+## Configuration
+
+| Option | Env var | Default | Description |
+| --- | --- | --- | --- |
+| `baseUrl` | `AUDIT_API_BASE_URL` | — (required) | Base URL of the Audit API |
+| `sourceApp` | `AUDIT_SOURCE_APP` | — (required) | Identifier of the application sending events (e.g. `tela`) |
+| `timeoutMs` | — | `5000` | Per-request timeout |
+| `maxRetries` | — | `3` | Retry attempts on 5xx / network errors |
+
+The constructor throws if `baseUrl` or `sourceApp` cannot be resolved from either the config object or the environment.
+
+## Event shape
+
+```ts
+interface AuditEvent {
+    action: string                       // required, e.g. 'create'
+    object_type: string                  // required, e.g. 'api_key'
+    origin: 'api' | 'worker' | 'ui'      // required
+    object_id?: string
+    actor_type?: 'user' | 'system' | 'api_key'
+    correlation_id?: string
+    user_agent?: string
+    occurred_at?: Date
+    ip_address?: string
+    metadata?: Record<string, unknown>
+}
+```
+
+All calls require a `dataToken` issued by the API Gateway / Auth API. It carries the workspace (and user, when available) the events belong to.
+
+## Examples
+
+### Track a single event
+
+```ts
+import { AuditClient } from '@meistrari/audit-sdk'
+
+const audit = new AuditClient({
+    baseUrl: 'https://audit.tela.com',
+    sourceApp: 'tela',
+})
+
+await audit.track(dataToken, {
+    action: 'create',
+    object_type: 'api_key',
+    object_id: 'key_abc123',
+    origin: 'api',
+    actor_type: 'user',
+    metadata: { name: 'CI token' },
+})
+```
+
+### Configure from environment
+
+```ts
+// AUDIT_API_BASE_URL and AUDIT_SOURCE_APP must be set
+const audit = new AuditClient()
+
+await audit.track(dataToken, {
+    action: 'login',
+    object_type: 'session',
+    origin: 'ui',
+})
+```
+
+### Batch multiple events
+
+```ts
+await audit.trackMany(dataToken, [
+    {
+        action: 'create',
+        object_type: 'document',
+        object_id: 'doc_1',
+        origin: 'worker',
+        actor_type: 'system',
+        correlation_id: 'job_42',
+    },
+    {
+        action: 'update',
+        object_type: 'document',
+        object_id: 'doc_1',
+        origin: 'worker',
+        actor_type: 'system',
+        correlation_id: 'job_42',
+        metadata: { fields: ['title'] },
+    },
+])
+```
+
+### Custom timeout and retries
+
+```ts
+const audit = new AuditClient({
+    baseUrl: 'https://audit.tela.com',
+    sourceApp: 'my-app',
+    timeoutMs: 2000,
+    maxRetries: 5,
+})
+```
+
+### Handling errors
+
+`track` / `trackMany` only throw `AuditError` for 4xx responses (the request is malformed and retrying won't help). 5xx, network errors and timeouts are retried with exponential backoff; if all attempts fail, the SDK logs the failure and resolves without throwing — the caller's flow is never blocked by audit.
+
+```ts
+import { AuditClient, AuditError } from '@meistrari/audit-sdk'
+
+try {
+    await audit.track(dataToken, event)
+}
+catch (err) {
+    if (err instanceof AuditError) {
+        // 4xx — bad payload, missing fields, invalid token, etc.
+        console.error('Audit rejected event:', err.details)
+    }
+    throw err
+}
+```

package/dist/client.d.ts

@@ -1,5 +1,4 @@
 export type AuditOrigin = 'api' | 'worker' | 'ui';
-type SourceApp = 'tela' | 'defesa' | 'calculo';
 type ActorType = 'user' | 'system' | 'api_key';
 export interface AuditEvent {
     action: string;
@@ -17,7 +16,7 @@ export interface AuditClientConfig {
     baseUrl?: string;
     timeoutMs?: number;
     maxRetries?: number;
-    sourceApp?: SourceApp;
+    sourceApp?: string;
 }
 export declare class AuditClient {
     private baseUrl;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAA;AAEjD,KAAK,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAA;AAC9C,KAAK,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE9C,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,WAAW,CAAA;IACnB,UAAU,CAAC,EAAE,SAAS,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,iBAAiB;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,SAAS,CAAA;CACxB;AAED,qBAAa,WAAW;IACpB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,SAAS,CAAQ;IAEzB;;;;;;;;OAQG;gBACS,MAAM,GAAE,iBAAsB;IAmBpC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU;IAI1C,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE;IA6CvD,OAAO,CAAC,UAAU;YAgBJ,KAAK;CAGtB;AAED,qBAAa,UAAW,SAAQ,KAAK;IACG,OAAO,CAAC,EAAE,OAAO;gBAAzC,OAAO,EAAE,MAAM,EAAS,OAAO,CAAC,EAAE,OAAO,YAAA;CAIxD"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAA;AAEjD,KAAK,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE9C,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,WAAW,CAAA;IACnB,UAAU,CAAC,EAAE,SAAS,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,iBAAiB;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,qBAAa,WAAW;IACpB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,SAAS,CAAQ;IAEzB;;;;;;;;OAQG;gBACS,MAAM,GAAE,iBAAsB;IAmBpC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU;IAI1C,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE;IA6CvD,OAAO,CAAC,UAAU;YAgBJ,KAAK;CAGtB;AAED,qBAAa,UAAW,SAAQ,KAAK;IACG,OAAO,CAAC,EAAE,OAAO;gBAAzC,OAAO,EAAE,MAAM,EAAS,OAAO,CAAC,EAAE,OAAO,YAAA;CAIxD"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@meistrari/audit-sdk",
-    "version": "0.4.2",
+    "version": "0.5.0",
     "type": "module",
     "main": "dist/index.js",
     "description": "",
@@ -21,11 +21,11 @@
         "node": ">=18"
     },
     "devDependencies": {
-        "@meistrari/mise-en-place": "^2.10.3",
+        "@meistrari/mise-en-place": "^2.15.0",
         "@types/node": "^25.2.3",
         "typescript": "^5.3.3"
     },
     "dependencies": {
-        "@meistrari/logger": "^2.1.3"
+        "@meistrari/logger": "^2.1.8"
     }
 }