@groundbrick/audit-service 1.1.3 → 1.2.0

package/README.md

@@ -0,0 +1,127 @@
+# @groundbrick/audit-service
+
+Pluggable audit service for asynchronously recording audit events. Designed for multi-tenant applications with a provider-based architecture that allows swapping storage backends.
+
+## Installation
+
+```bash
+npm install @groundbrick/audit-service
+```
+
+## Quick Start
+
+```typescript
+import { AuditService, DatabaseAuditProvider } from '@groundbrick/audit-service';
+
+// 1. Create a provider with your database query executor
+const provider = new DatabaseAuditProvider(async (query, params) => {
+  await db.query(query, params);
+});
+
+// 2. Get the singleton instance
+const auditService = AuditService.getInstance(provider);
+
+// 3. Log events (fire-and-forget, non-blocking)
+auditService.log({
+  actorId: '42',
+  tenantId: '1',
+  action: 'CREATE',
+  entity: 'USER',
+  entityId: '100',
+  newValue: { name: 'John Doe', email: 'john@example.com' },
+});
+```
+
+## Database Schema
+
+The `DatabaseAuditProvider` expects an `audit_logs` table with the following structure:
+
+```sql
+CREATE TABLE audit_logs (
+  id SERIAL PRIMARY KEY,
+  actor_id VARCHAR NOT NULL,
+  tenant_id VARCHAR NOT NULL,
+  action VARCHAR NOT NULL,
+  entity VARCHAR NOT NULL,
+  entity_id VARCHAR NOT NULL,
+  old_value JSONB,
+  new_value JSONB,
+  metadata JSONB,
+  "timestamp" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+## API
+
+### `AuditService`
+
+Singleton service that delegates event persistence to a provider.
+
+| Method | Description |
+|---|---|
+| `AuditService.getInstance(provider)` | Returns the singleton instance, initializing it with the given provider on first call. |
+| `auditService.log(event)` | Logs an audit event asynchronously (fire-and-forget). Errors are caught and logged to `console.error`. |
+
+### `AuditEvent`
+
+```typescript
+interface AuditEvent {
+  actorId: string;                // Who performed the action (user ID or 'system')
+  tenantId: string;               // Tenant/organization the action belongs to
+  action: AuditAction;            // What happened
+  entity: string;                 // Affected entity type (e.g. 'USER', 'ORDER')
+  entityId: string;               // ID of the affected entity
+  oldValue?: any | null;          // Previous state (UPDATE, DELETE)
+  newValue?: any | null;          // New state (CREATE, UPDATE)
+  timestamp?: Date;               // Auto-generated if not provided
+  metadata?: Record<string, any>; // Additional context (IP, user-agent, etc.)
+}
+```
+
+### `AuditAction`
+
+```typescript
+type AuditAction = 'CREATE' | 'UPDATE' | 'DELETE' | 'LOGIN' | 'LOGOUT';
+```
+
+### `IAuditProvider`
+
+Interface for implementing custom storage backends.
+
+```typescript
+interface IAuditProvider {
+  save(event: AuditEvent): Promise<void>;
+}
+```
+
+### `DatabaseAuditProvider`
+
+Built-in provider that persists events to a SQL database via a query executor function.
+
+```typescript
+const provider = new DatabaseAuditProvider(
+  async (query: string, params: any[]) => {
+    await pool.query(query, params);
+  }
+);
+```
+
+## Custom Provider
+
+Implement `IAuditProvider` to use any storage backend:
+
+```typescript
+import { IAuditProvider, AuditEvent } from '@groundbrick/audit-service';
+
+class RedisAuditProvider implements IAuditProvider {
+  constructor(private redis: RedisClient) {}
+
+  async save(event: AuditEvent): Promise<void> {
+    await this.redis.lpush('audit:logs', JSON.stringify(event));
+  }
+}
+```
+
+## License
+
+MIT

package/dist/providers/DatabaseAuditProvider.js

@@ -4,14 +4,14 @@ export class DatabaseAuditProvider {
         this.executeQuery = executeQuery;
     }
     async save(event) {
-        const { actorId, petshopId, action, entity, entityId, oldValue, newValue, metadata, } = event;
+        const { actorId, tenantId, action, entity, entityId, oldValue, newValue, metadata, } = event;
         const query = `
-      INSERT INTO audit_logs (actor_id, petshop_id, action, entity, entity_id, old_value, new_value, metadata, "timestamp")
+      INSERT INTO audit_logs (actor_id, tenant_id, action, entity, entity_id, old_value, new_value, metadata, "timestamp")
       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
     `;
         const params = [
             actorId,
-            petshopId,
+            tenantId,
             action,
             entity,
             entityId,

package/dist/types.d.ts

@@ -2,8 +2,8 @@ export type AuditAction = 'CREATE' | 'UPDATE' | 'DELETE' | 'LOGIN' | 'LOGOUT';
 export interface AuditEvent {
     /** ID do usuário ou sistema que realizou a ação. */
     actorId: string;
-    /** ID do petshop ao qual a ação está associada. */
-    petshopId: string;
+    /** ID do tenant (organização/empresa) ao qual a ação está associada. */
+    tenantId: string;
     /** A ação que foi realizada. */
     action: AuditAction;
     /** A entidade que foi afetada. Ex: 'PET', 'APPOINTMENT', 'USER'. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE9E,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,MAAM,EAAE,WAAW,CAAC;IACpB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB,wEAAwE;IACxE,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE9E,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,MAAM,EAAE,WAAW,CAAC;IACpB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB,wEAAwE;IACxE,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundbrick/audit-service",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Serviço de auditoria plugável para registrar eventos de log de forma assíncrona.",
   "type": "module",
   "main": "dist/index.js",