{"_id":"@angsana_consulting/logger-service","_rev":"3-a326f048810ded3ed6d63d8a8d4baf4a","name":"@angsana_consulting/logger-service","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@angsana_consulting/logger-service","version":"1.0.0","keywords":["angsana","logging","error-tracking","system-logs","usage-analytics","firebase","cloud-functions"],"author":{"name":"Angsana Platform Team"},"license":"MIT","_id":"@angsana_consulting/logger-service@1.0.0","maintainers":[{"name":"keithnew","email":"keith.new@aboutime.co.uk"}],"homepage":"https://github.com/angsana-consulting/angsana-platform/tree/main/packages/logger-service","bugs":{"url":"https://github.com/angsana-consulting/angsana-platform/issues"},"dist":{"shasum":"cf4d0a54b7ff669148290af26f167d65515de62c","tarball":"https://registry.npmjs.org/@angsana_consulting/logger-service/-/logger-service-1.0.0.tgz","fileCount":26,"integrity":"sha512-Y4ABvcDPTi5vNn+DRxwlBa3dHrGWO1hM4+XkhYv05cB2MXAGCp47hLyort04WFzSks/KHLNtWa4ktB1ruok/xQ==","signatures":[{"sig":"MEQCICAzjO7WHFlOkNwarhN4YV4K8bxWyrCxmYIahYj6pJLXAiBDw7v4y2YjOW4h0s9RiI9KO5rnqaMvcqYAhUgD0OpahQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":69940},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=14.0.0"},"gitHead":"a3f3e76960a62432c3c73ae110fad4edf47dad54","scripts":{"test":"echo \"No tests yet\" && exit 0","build":"tsc","clean":"rm -rf dist .tsbuildinfo","build:watch":"tsc --watch","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"keithnew","email":"keith.new@aboutime.co.uk"},"repository":{"url":"git+https://github.com/angsana-consulting/angsana-platform.git","type":"git","directory":"packages/logger-service"},"_npmVersion":"10.9.2","description":"Universal logging service for Angsana platform - handles error, system, and usage logs","directories":{},"_nodeVersion":"22.15.1","dependencies":{"express":"^4.18.0","firebase-admin":"^12.0.0","@angsana_consulting/utils":"^1.0.4","@angsana_consulting/config":"^1.0.4"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0","@types/express":"^4.17.17"},"peerDependencies":{"express":"^4.18.0","firebase-admin":"^11.0.0 || ^12.0.0"},"_npmOperationalInternal":{"tmp":"tmp/logger-service_1.0.0_1759743200070_0.14153206210276204","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@angsana_consulting/logger-service","version":"1.0.1","keywords":["angsana","logging","error-tracking","system-logs","usage-analytics","firebase","cloud-functions"],"author":{"name":"Angsana Platform Team"},"license":"MIT","_id":"@angsana_consulting/logger-service@1.0.1","maintainers":[{"name":"keithnew","email":"keith.new@aboutime.co.uk"}],"homepage":"https://github.com/angsana-consulting/angsana-platform/tree/main/packages/logger-service","bugs":{"url":"https://github.com/angsana-consulting/angsana-platform/issues"},"dist":{"shasum":"ff372e1346a88a39fadaf5f49d9e50cf1b966452","tarball":"https://registry.npmjs.org/@angsana_consulting/logger-service/-/logger-service-1.0.1.tgz","fileCount":26,"integrity":"sha512-tW7WRACYu82qaQf7C8+dJIriu0fTn4TvZugIQvU08SyuBlIdpLadTvlgl/yioU1eDV9ILbKHIaMU9R9b9EcDAA==","signatures":[{"sig":"MEQCIClgB3sgeVKDRFl1/hbKS2Fq+g/Dde/tmQBXeqBVfeV4AiBHeS0cHyVHna+lzoNvk4757FtqTAN0RUYppZW8dEhsmQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":70498},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=14.0.0"},"gitHead":"afbc46768ded62f68f9bfa49113ec2b89f153aab","scripts":{"test":"echo \"No tests yet\" && exit 0","build":"tsc","clean":"rm -rf dist .tsbuildinfo","build:watch":"tsc --watch","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"keithnew","email":"keith.new@aboutime.co.uk"},"repository":{"url":"git+https://github.com/angsana-consulting/angsana-platform.git","type":"git","directory":"packages/logger-service"},"_npmVersion":"10.9.2","description":"Universal logging service for Angsana platform - handles error, system, and usage logs","directories":{},"_nodeVersion":"22.15.1","dependencies":{"express":"^4.18.0","firebase-admin":"^12.0.0","@angsana_consulting/utils":"^1.0.4","@angsana_consulting/config":"^1.0.4"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0","@types/express":"^4.17.17"},"peerDependencies":{"express":"^4.18.0","firebase-admin":"^11.0.0 || ^12.0.0"},"_npmOperationalInternal":{"tmp":"tmp/logger-service_1.0.1_1759836983547_0.36143132839987846","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-10-06T09:33:19.993Z","modified":"2026-09-29T08:13:04.201Z","1.0.0":"2025-10-06T09:33:20.280Z","1.0.1":"2025-10-07T11:36:23.713Z"},"bugs":{"url":"https://github.com/angsana-consulting/angsana-platform/issues"},"author":{"name":"Angsana Platform Team"},"license":"MIT","homepage":"https://github.com/angsana-consulting/angsana-platform/tree/main/packages/logger-service","keywords":["angsana","logging","error-tracking","system-logs","usage-analytics","firebase","cloud-functions"],"repository":{"url":"git+https://github.com/angsana-consulting/angsana-platform.git","type":"git","directory":"packages/logger-service"},"description":"Universal logging service for Angsana platform - handles error, system, and usage logs","maintainers":[{"email":"jerome.glairan@angsana-uk.com","name":"jeromeglr"},{"email":"keith.new@aboutime.co.uk","name":"keithnew"}],"readme":"# @angsana_consulting/logger-service\n\nUniversal logging service for Angsana platform projects. Provides handlers for error, system, and usage logging with automatic TTL management, validation, and retry logic.\n\n## Installation\n\n```bash\nnpm install @angsana_consulting/logger-service\n```\n\n## Features\n\n- **Multi-collection logging**: Automatically routes logs to ErrorLogs, SystemLogs, or UsageLogs collections\n- **Automatic TTL management**: Configurable retention periods with automatic cleanup\n- **Built-in validation**: Validates payloads before writing to Firestore\n- **Retry logic**: Automatic retry with exponential backoff for transient failures\n- **Backward compatibility**: Works with existing errorLogger implementations\n- **Type safety**: Full TypeScript support with exported types\n\n## Usage\n\n### 1. Import in your Cloud Function\n\n```typescript\n// In your main functions file (e.g., functions/src/index.ts)\nimport { universalLoggerHandler } from '@angsana_consulting/logger-service';\n\n// Export as a Cloud Function\nexport const errorLogger = onRequest(\n  { region: 'europe-west2', timeoutSeconds: 10 },\n  universalLoggerHandler\n);\n```\n\n### 2. Register with your proxy (if using one)\n\n```typescript\n// In your proxy handler (e.g., functions/src/proxy/proxy.ts)\nimport { universalLoggerHandler } from '@angsana_consulting/logger-service';\n\n// Register the handler\nhandlers.set('errorLogger', universalLoggerHandler);\n```\n\n### 3. Call from Retool or other clients\n\n#### Error Logging\n```javascript\n// Retool JS Query: logError\nconst payload = {\n  type: 'error',  // Optional - defaults to 'error' if not specified\n  service: 'retool',\n  operation: 'submitRequestedNumbers',\n  level: 'error',\n  message: error.message,\n  errorMessage: error.message,\n  errorStack: error.stack,\n  errorCode: error.code,\n  context: { \n    component: 'SubmitButton', \n    userId: current_user.email,\n    payload: formData \n  }\n};\n\nawait fetch(\n  'https://your-project.cloudfunctions.net/proxyFn?target=errorLogger',\n  {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      'x-api-key': globals.api_key\n    },\n    body: JSON.stringify(payload)\n  }\n);\n```\n\n#### System Logging\n```javascript\n// Log a system event\nconst payload = {\n  type: 'system',\n  service: 'retool',\n  operation: 'configUpdate',\n  level: 'info',\n  message: 'User updated configuration settings',\n  context: {\n    userId: current_user.email,\n    changes: changedFields\n  }\n};\n\nawait fetch('https://your-project.cloudfunctions.net/proxyFn?target=errorLogger', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'x-api-key': globals.api_key\n  },\n  body: JSON.stringify(payload)\n});\n```\n\n#### Usage Logging\n```javascript\n// Log user activity\nconst payload = {\n  type: 'usage',\n  service: 'retool',\n  operation: 'powerDial',\n  userId: current_user.email,\n  clientId: selectedClient.value,\n  clientName: selectedClient.label,\n  sessionId: sessionId.value,\n  action: 'power_dial',\n  dialCount: selectedNumbers.length,\n  successfulConnect: true,\n  duration: callDuration,\n  countries: ['GB', 'US'],\n  metadata: {\n    campaign: campaignId,\n    callType: 'sales'\n  }\n};\n\nawait fetch('https://your-project.cloudfunctions.net/proxyFn?target=errorLogger', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'x-api-key': globals.api_key\n  },\n  body: JSON.stringify(payload)\n});\n```\n\n### 4. Direct usage in Cloud Functions\n\n```typescript\nimport { \n  universalLoggerHandler,\n  createLogPayload,\n  ErrorLogPayload,\n  SystemLogPayload,\n  UsageLogPayload\n} from '@angsana_consulting/logger-service';\n\n// In your function handlers\nexport async function myFunctionHandler(req: Request, res: Response) {\n  try {\n    // Your function logic here\n    \n    // Log success\n    const logReq = {\n      body: createLogPayload('system', 'myFunction', 'process', {\n        message: 'Processing completed successfully',\n        level: 'info',\n        context: { recordsProcessed: 100 }\n      })\n    } as Request;\n    \n    // Call the logger directly\n    await universalLoggerHandler(logReq, res);\n    \n  } catch (error) {\n    // Log error\n    const logReq = {\n      body: createLogPayload('error', 'myFunction', 'process', {\n        errorMessage: error.message,\n        errorStack: error.stack,\n        level: 'error'\n      })\n    } as Request;\n    \n    await universalLoggerHandler(logReq, res);\n  }\n}\n```\n\n## Log Types\n\n### Error Logs (`type: 'error'`)\nWritten to `ErrorLogs` collection. Use for:\n- Application errors\n- API failures\n- Validation errors\n- System exceptions\n\n### System Logs (`type: 'system'`)\nWritten to `SystemLogs` collection. Use for:\n- Service lifecycle events\n- Configuration changes\n- Performance metrics\n- Debug information\n\n### Usage Logs (`type: 'usage'`)\nWritten to `UsageLogs` collection. Use for:\n- User activity tracking\n- Feature usage metrics\n- Call/dial statistics\n- Business analytics\n\n## Auto-detection\n\nIf `type` is not specified, the logger will auto-detect based on fields:\n- Contains `userId` + (`action` or `dialCount`) → Usage log\n- Contains `errorMessage`, `errorStack`, or `level: 'error'` → Error log\n- Otherwise → Error log (for backward compatibility)\n\n## Response Format\n\n```typescript\n// Success response\n{\n  \"success\": true,\n  \"logType\": \"error\" | \"system\" | \"usage\",\n  \"message\": \"Log written to [collection] collection\"\n}\n\n// Error response\n{\n  \"error\": \"Error message\",\n  \"errors\": [...],  // Validation errors if any\n  \"logType\": \"error\" | \"system\" | \"usage\"\n}\n```\n\n## Configuration\n\nThe logger uses settings from your Firestore `Settings` collection for:\n- TTL/retention periods for each collection\n- Validation rules\n- Retry configuration\n\n## TypeScript Types\n\n```typescript\nimport {\n  LogType,\n  LogLevel,\n  LogPayload,\n  ErrorLogPayload,\n  SystemLogPayload,\n  UsageLogPayload,\n  LoggerResponse,\n  SystemEventType,\n  UsageActionType\n} from '@angsana_consulting/logger-service';\n```\n\n## Migration from errorLogger\n\nExisting `errorLogger` calls will continue to work without changes. The handler is backward compatible and will:\n1. Accept payloads without a `type` field\n2. Auto-detect the appropriate collection\n3. Default to ErrorLogs for backward compatibility\n\n## License\n\nMIT","readmeFilename":"README.md"}