@avss-tech/logger - Client SDK

Production-ready TypeScript SDK for the AVSS Centralized Logging Platform.

Features

✅ Async/Non-blocking - Fire-and-forget logging
✅ Retry Logic - Exponential backoff with jitter
✅ Batch Processing - Optional queue for high-volume scenarios
✅ Type-Safe - Complete TypeScript definitions
✅ Validation - Input validation & sanitization
✅ Error Handling - Graceful degradation
✅ Statistics - Built-in metrics tracking
✅ Production-Ready - Security & best practices built-in

Installation

npm install @avss-tech/logger

Quick Start

import { AVSSLogger } from '@avss-tech/logger';

const logger = new AVSLogger({
  project: 'my-app',
  apiKey: 'your-api-key',
  endpoint: 'http://logging-service:4000/logs',
  onFatalError: (error) => {
        console.error('AVS Logger Fatal Error:', error);
  },
});

// Log message
await logger.log({
  message: 'Application started',
  level: 'info',
});

// Log audit event
await logger.audit({
  actor: { userId: 'user123' },
  action: 'USER_LOGIN',
  entity: { type: 'USER', id: 'user123' },
});

API Documentation

Configuration

interface AVSLoggerConfig {
  project: string;                    // Required: Project identifier
  apiKey: string;                     // Required: API key for authentication
  endpoint?: string;                  // Optional: Logging service URL
  timeout?: number;                   // Optional: Request timeout in ms
  enableQueue?: boolean;              // Optional: Enable queue batching
  batchSize?: number;                 // Optional: Batch size for queue
  batchTimeout?: number;              // Optional: Batch timeout in ms
  maxRetries?: number;                // Optional: Max retries for failed requests
  initialRetryDelay?: number;         // Optional: Initial retry delay in ms
  debug?: boolean;                    // Optional: Enable debug logging
  customHeaders?: Record<string, string>; // Optional: Custom headers
  onFatalError?: (error: Error) => void;  // Optional: Error callback
}

Methods

log() - Generic Logging

await logger.log({
  message: 'User action completed',
  level: 'info',
  userId: 'user123',
  meta: { action: 'profile_update' }
});

audit() - Audit Logging

await logger.audit({
  actor: { userId: 'user123', email: '[email protected]' },
  action: 'DOCUMENT_SIGNED',
  entity: { type: 'DOCUMENT', id: 'doc456' },
  metadata: { version: '2.0' }
});

access() - Access Logging

await logger.access({
  endpoint: '/api/users',
  method: 'GET',
  statusCode: 200,
  ip: '192.168.1.1',
  responseTimeMs: 45,
  userId: 'user123'
});

error() - Error Logging

await logger.error({
  message: 'Database connection failed',
  stack: error.stack,
  context: { database: 'postgresql' },
  userId: 'user123'
});

Queue Management

const logger = new AVSLogger({
  project: 'my-app',
  apiKey: 'your-api-key',
  enableQueue: true,
  batchSize: 50,
  batchTimeout: 5000
});

// Logs are automatically batched and sent
await logger.log({ message: 'Test' });

// Manually flush the queue
await logger.flush();

// Cleanup
logger.destroy();

Statistics

const stats = logger.getStatistics();
console.log(stats);
// {
//   totalLogsAttempted: 10,
//   successfulLogs: 9,
//   failedLogs: 1,
//   retriedLogs: 2,
//   averageResponseTimeMs: 35,
//   queueLength: 0
// }

logger.resetStatistics();

Search logs

await logger.search({ startDate: '2026-01-01', endDate: '2026-01-31', level: 'info', userId: '', project: 'esign-saas' })

Audit logs

await logger.getAuditLogs(50, 'esign-saas',1)

Error logs

await logger.getErrorLogs(50, 'esign-saas',1)

Access logs

await logger.getAccessLogs(50, 'esign-saas',1)

Verify logs

await logger.verify('esign-saas')

Error Handling

try {
  await logger.log({
    message: 'Important event',
    level: 'warn'
  });
} catch (error) {
  console.error('Logging failed:', error);
}

// Or use the returned LogResult
const result = await logger.log({ message: 'Test' });
if (!result.success) {
  console.error(result.message);
}

License

MIT