{"_id":"@archivehub/logger","name":"@archivehub/logger","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@archivehub/logger","version":"1.0.0","description":"Unified enterprise-grade logging package for ArchiveHub services. Pino v10 structured JSON logging with AsyncLocalStorage context propagation, automatic redaction, rotating file streams, security/audit loggers, and Express middleware.","main":"index.js","scripts":{"prepublishOnly":"node -e \"require('./index.js'); console.log('Package loads OK');\""},"keywords":["logging","pino","enterprise","archivehub","structured-logging","async-local-storage","request-context","rotating-log","audit-logger","security-logger","express-middleware","redaction"],"author":{"name":"ArchiveHub"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/nicloay/archivehub.git","directory":"packages/logger"},"homepage":"https://github.com/nicloay/archivehub/tree/main/packages/logger#readme","bugs":{"url":"https://github.com/nicloay/archivehub/issues"},"engines":{"node":">=18.0.0"},"dependencies":{"pino":"^10.0.0","pino-pretty":"^11.0.0","rotating-file-stream":"^3.2.0"},"peerDependencies":{"express":"^4.17.0 || ^5.0.0"},"peerDependenciesMeta":{"express":{"optional":true}},"_id":"@archivehub/logger@1.0.0","_nodeVersion":"18.19.1","_npmVersion":"9.2.0","dist":{"integrity":"sha512-yk//xH0ABYaKC/betr4TpAtgCXFuAYuPi/CAWIeSjrkFR5KwrcG4NAMG6pUhk5q2IXGub5d8X3STrA+RTpQ8Lg==","shasum":"0d92a9cef5dcf87520b17c1823a34ea627cdd294","tarball":"https://registry.npmjs.org/@archivehub/logger/-/logger-1.0.0.tgz","fileCount":19,"unpackedSize":78422,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDlE8/zqzmhqjMLVCeg3Cd3U65UvFOnTTYiSQ808KwrnAiBrW/52m0PTmio7JRCBBRlYjiCVHesk1YbB17ZUAXj9Iw=="}]},"_npmUser":{"name":"umayaraj_2025","email":"umayaraj@archivehub.io"},"directories":{},"maintainers":[{"name":"umayaraj_2025","email":"umayaraj@archivehub.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/logger_1.0.0_1772009794569_0.786834323632118"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-25T08:56:34.487Z","1.0.0":"2026-02-25T08:56:34.707Z","modified":"2026-02-25T08:56:35.011Z"},"maintainers":[{"name":"umayaraj_2025","email":"umayaraj@archivehub.io"}],"description":"Unified enterprise-grade logging package for ArchiveHub services. Pino v10 structured JSON logging with AsyncLocalStorage context propagation, automatic redaction, rotating file streams, security/audit loggers, and Express middleware.","homepage":"https://github.com/nicloay/archivehub/tree/main/packages/logger#readme","keywords":["logging","pino","enterprise","archivehub","structured-logging","async-local-storage","request-context","rotating-log","audit-logger","security-logger","express-middleware","redaction"],"repository":{"type":"git","url":"git+https://github.com/nicloay/archivehub.git","directory":"packages/logger"},"author":{"name":"ArchiveHub"},"bugs":{"url":"https://github.com/nicloay/archivehub/issues"},"license":"MIT","readme":"# @archivehub/logger\n\nUnified enterprise-grade logging package for ArchiveHub services.\n\nBuilt on [Pino v10](https://github.com/pinojs/pino) with AsyncLocalStorage context propagation, automatic sensitive data redaction, rotating file streams, security/audit loggers, and Express middleware.\n\n## Features\n\n- **Structured JSON logging** — Pino v10 with service/env/version base bindings\n- **Request context propagation** — AsyncLocalStorage for traceId, userId, database, ip across async chains\n- **Automatic redaction** — Passwords, tokens, authorization headers, SAMLResponse auto-masked\n- **Security logger** — Dual-write to stdout + dedicated `security.log` file\n- **Audit logger** — Fixed-schema events for DATA_ACCESS, AUTH, AUTHORIZATION, ADMIN\n- **Rotating file streams** — Daily rotation with size limits via `rotating-file-stream`\n- **Express middleware** — Request context setup, HTTP logging, error logging\n- **Startup display** — Professional startup output with Unicode tables and phase indicators\n- **Timezone-aware timestamps** — Configurable via `APP_TIMEZONE` or `COUNTRY` env vars\n\n## Installation\n\n```bash\nnpm install @archivehub/logger\n```\n\n## Quick Start\n\n```javascript\nconst {\n  initLogger,\n  createSecurityLogger,\n  createAuditLogger,\n  requestContextMiddleware,\n  httpLoggerMiddleware\n} = require('@archivehub/logger');\n\n// Initialize logger\nconst { logger, getLogger } = initLogger({\n  service: 'my-service',\n  version: '1.0.0',\n  logDir: './logs'\n});\n\n// Optional: create specialized loggers\nconst securityLogger = createSecurityLogger(logger);\nconst auditLogger = createAuditLogger(logger);\n\n// Express middleware\napp.use(requestContextMiddleware());\napp.use(httpLoggerMiddleware());\n\n// In route handlers — context-aware logging\ngetLogger().info({ userId, action: 'create' }, 'User created record');\n\n// Security events\nsecurityLogger.loginSuccess(userId, 'local');\n\n// Audit events\nauditLogger.logDataAccess('read', 'BKPF', { rowCount: 100 });\n```\n\n## API Reference\n\n### Core Logger\n\n| Export | Description |\n|--------|-------------|\n| `initLogger(options)` | Initialize logger, returns `{ logger, getLogger }` |\n| `createLogger(options)` | Create a configured Pino logger |\n| `getLogger()` | Get context-aware child logger (auto-enriches with request context) |\n| `setBaseLogger(logger)` | Cache the base logger instance |\n| `getBaseLogger()` | Retrieve cached logger |\n\n### Context Management\n\n| Export | Description |\n|--------|-------------|\n| `runWithContext(context, callback)` | Run async code within a context |\n| `setContext(key, value)` | Set a context value |\n| `getContext(key)` | Get a context value |\n| `getAllContext()` | Get entire context object |\n| `getTraceId()` / `setTraceId()` | Trace ID accessor/setter |\n| `getUserId()` / `setUserId()` | User ID accessor/setter |\n| `getEmail()` / `setEmail()` | Email accessor/setter |\n| `getDatabase()` / `setDatabase()` | Database accessor/setter |\n| `getIp()` | Client IP accessor |\n| `getUserAgent()` | User-Agent accessor |\n| `hasContext()` | Check if in active context |\n| `asyncLocalStorage` | Shared AsyncLocalStorage instance |\n\n### Specialized Loggers\n\n| Export | Description |\n|--------|-------------|\n| `createSecurityLogger(baseLogger, options)` | Dual-write security event logger |\n| `createAuditLogger(baseLogger, options)` | Structured audit event logger |\n| `AuditCategory` | Enum: DATA_ACCESS, AUTH, AUTHORIZATION, ADMIN |\n| `AuditOutcome` | Enum: SUCCESS, FAILURE |\n\n**Security logger methods:**\n- `loginSuccess(userId, method, details)`\n- `loginFailure(identifier, method, reason, details)`\n- `accessDenied(userId, resource, action, details)`\n- `logout(userId, reason)`\n- `adminAction(adminUserId, action, targetUserId, details)`\n\n**Audit logger methods:**\n- `logDataAccess(action, resource, options)`\n- `logAuthEvent(action, success, options)`\n- `logAuthorizationEvent(resource, action, allowed, options)`\n- `logAdminAction(action, options)`\n\n### Express Middleware\n\n| Export | Description |\n|--------|-------------|\n| `requestContextMiddleware(options)` | Establish AsyncLocalStorage context per request |\n| `httpLoggerMiddleware(options)` | Log HTTP requests/responses with timing |\n| `simpleRequestLogger(options)` | One-line request logger |\n| `errorLoggerMiddleware()` | Error handler logging |\n| `enrichContextWithUser(userId, email, data)` | Add user info to context |\n| `getDuration()` | Get request elapsed time (ms) |\n| `DEFAULT_SKIP_PATHS` | Paths excluded from logging |\n\n### Startup Display\n\n| Export | Description |\n|--------|-------------|\n| `printBanner(info)` | Print startup banner with service info |\n| `printPhase(num, title)` | Print phase header |\n| `printStatus(emoji, label, detail)` | Print status line |\n| `printServiceTable(services)` | Print connection status table |\n| `printSystemsTable(systems, totals)` | Print ERP systems summary |\n| `printLogRotation(config)` | Print log rotation settings |\n| `printReady(durationMs)` | Print boot completion banner |\n\n### Redaction & Sanitization\n\n| Export | Description |\n|--------|-------------|\n| `defaultRedactPaths` | List of auto-redacted field paths |\n| `createRedactConfig(options)` | Build Pino redact config |\n| `redactObject(obj, fields, censor)` | Manual object redaction |\n| `sanitizeData(data, options)` | Truncate large values for logging |\n\n### Streams\n\n| Export | Description |\n|--------|-------------|\n| `createMultistream(options)` | Composite stream (console + files) |\n| `createDedicatedStream(name, options)` | Single-purpose stream |\n| `getRotationConfig(overrides)` | Get rotation settings |\n\n### Timezone\n\n| Export | Description |\n|--------|-------------|\n| `getTimezone()` | Get configured IANA timezone |\n| `now(format)` | Current time in configured timezone |\n| `formatInTimezone(date, format, tz)` | Format date in specific timezone |\n| `resolveTimezone()` | Resolve timezone from env vars |\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `LOG_LEVEL` | `info` | Minimum log level (error, warn, info, debug, trace) |\n| `LOG_DIR` | `./logs` | Directory for log files |\n| `LOG_MAX_SIZE` | `10M` | Max file size before rotation |\n| `LOG_MAX_FILES` | `30` | Rotated files to retain |\n| `LOG_INTERVAL` | `1d` | Rotation interval |\n| `LOG_COMPRESS` | `false` | Gzip compression on rotation |\n| `NODE_ENV` | `production` | `development` enables pino-pretty console output |\n| `APP_TIMEZONE` | — | IANA timezone override (e.g., `Asia/Kolkata`) |\n| `COUNTRY` | — | Country code for timezone lookup (e.g., `US`, `IN`, `DE`) |\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-211e036ba94c1c29f06a84c9a12ace4a"}