@avss-tech/logger 1.0.0

package/README.md

@@ -0,0 +1,220 @@
+# @avss-tech/logger - Client SDK
+
+Production-ready TypeScript SDK for the AVS 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
+
+```bash
+npm install @avss-tech/logger
+```
+
+## Quick Start
+
+```typescript
+import { AVSLogger } from '@avss-tech/logger';
+
+const logger = new AVSLogger({
+  project: 'my-app',
+  apiKey: 'your-api-key',
+  endpoint: 'http://logging-service:4000/logs',
+});
+
+// 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
+
+```typescript
+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
+
+```typescript
+await logger.log({
+  message: 'User action completed',
+  level: 'info',
+  userId: 'user123',
+  meta: { action: 'profile_update' }
+});
+```
+
+#### audit() - Audit Logging
+
+```typescript
+await logger.audit({
+  actor: { userId: 'user123', email: 'user@example.com' },
+  action: 'DOCUMENT_SIGNED',
+  entity: { type: 'DOCUMENT', id: 'doc456' },
+  metadata: { version: '2.0' }
+});
+```
+
+#### access() - Access Logging
+
+```typescript
+await logger.access({
+  endpoint: '/api/users',
+  method: 'GET',
+  statusCode: 200,
+  ip: '192.168.1.1',
+  responseTimeMs: 45,
+  userId: 'user123'
+});
+```
+
+#### error() - Error Logging
+
+```typescript
+await logger.error({
+  message: 'Database connection failed',
+  stack: error.stack,
+  context: { database: 'postgresql' },
+  userId: 'user123'
+});
+```
+
+### Queue Management
+
+```typescript
+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
+
+```typescript
+const stats = logger.getStatistics();
+console.log(stats);
+// {
+//   totalLogsAttempted: 10,
+//   successfulLogs: 9,
+//   failedLogs: 1,
+//   retriedLogs: 2,
+//   averageResponseTimeMs: 35,
+//   queueLength: 0
+// }
+
+logger.resetStatistics();
+```
+
+## Error Handling
+
+```typescript
+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);
+}
+```
+
+## Best Practices
+
+1. **Initialize once** - Create a single logger instance in your app
+2. **Use async/await** - Handle promises properly for error handling
+3. **Enable queue for production** - Batch logs to reduce server load
+4. **Set custom headers** - Add authentication or tracking headers
+5. **Monitor statistics** - Track logging performance
+6. **Clean up on shutdown** - Call `destroy()` when app closes
+
+## Project Structure
+
+```
+src/
+├── index.ts           # Main exports
+├── logger.ts          # Core SDK class
+├── types.ts           # TypeScript definitions
+├── http-client.ts     # HTTP client
+├── retry.ts           # Retry logic
+├── queue.ts           # Batch queue
+├── validators.ts      # Input validation
+└── constants.ts       # Configuration constants
+```
+
+## Build & Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the SDK
+npm run build
+
+# Watch mode
+npm run watch
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@avss-tech/logger",
+  "version": "1.0.0",
+  "description": "TypeScript client SDK for AVS Centralized Logging Platform",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts"
+  },
+  "keywords": [
+    "logging",
+    "audit",
+    "monitoring",
+    "typescript",
+    "sdk",
+    "avs"
+  ],
+  "author": "Your Organization",
+  "license": "MIT",
+  "dependencies": {
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "prettier": "^3.0.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "ts-jest": "^29.0.0"
+  },
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}