@onezlinks/session-logger 1.0.0

package/src/index.js

@@ -0,0 +1,74 @@
+/**
+ * @onezlinks/session-logger — Public API
+ * Session-based file logger with AsyncLocalStorage context propagation
+ *
+ * @module @onezlinks/session-logger
+ * @version 1.0.0
+ * @description Hybrid API: Wrapper (safe) + Manual (flexible) patterns
+ */
+
+// Re-export all public APIs from context
+const {
+  // Wrapper Pattern (Recommended)
+  withSession,
+
+  // Manual Pattern (Advanced)
+  startSession,
+  endSession,
+
+  // Context Inspection
+  getSessionContext,
+
+  // Logging Functions
+  log,
+  info,
+  error,
+  warn,
+
+  // Special Formatters
+  logCost,
+  logDuration,
+  logMetric
+} = require('./context')
+
+// Re-export cleanup utility
+const { cleanOldLogs } = require('./cleanup')
+
+// Re-export constants for advanced usage
+const { CONFIG, COMMON_TAGS } = require('./constants')
+
+module.exports = {
+  // ═══════════════════════════════════════════════════════════════
+  // Wrapper Pattern (Recommended for Production)
+  // ═══════════════════════════════════════════════════════════════
+  withSession,
+
+  // ═══════════════════════════════════════════════════════════════
+  // Manual Pattern (Advanced — for Complex Flow)
+  // ═══════════════════════════════════════════════════════════════
+  startSession,
+  endSession,
+
+  // ═══════════════════════════════════════════════════════════════
+  // Context & Logging
+  // ═══════════════════════════════════════════════════════════════
+  getSessionContext,
+  log,
+  info,
+  error,
+  warn,
+  logCost,
+  logDuration,
+  logMetric,
+
+  // ═══════════════════════════════════════════════════════════════
+  // Utilities
+  // ═══════════════════════════════════════════════════════════════
+  cleanOldLogs,
+
+  // ═══════════════════════════════════════════════════════════════
+  // Constants (Advanced Usage)
+  // ═══════════════════════════════════════════════════════════════
+  CONFIG,
+  COMMON_TAGS
+}

package/types/index.d.ts

@@ -0,0 +1,208 @@
+/**
+ * @onezlinks/session-logger — TypeScript Definitions
+ */
+
+// ═══════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════
+
+export interface SessionOptions {
+  /** Unique session identifier (e.g. UUID, MongoDB ObjectId) */
+  sessionId: string
+
+  /** Log category — used as subdirectory name (e.g. 'ai-pipeline', 'order') */
+  category: string
+
+  /** Additional metadata included in session header */
+  metadata?: Record<string, string | number>
+
+  /** Override base log directory (default: CONFIG.LOG_BASE_DIR) */
+  logDir?: string
+
+  /** Enable file logging (default: true) */
+  enableFile?: boolean
+
+  /** Enable stdout/stderr output (default: true) */
+  enableStdout?: boolean
+}
+
+export interface SessionContext {
+  sessionId: string
+  category: string
+  metadata: Record<string, string | number>
+  fileConsole: Console | null
+  logPath: string | null
+  errLogPath: string | null
+  startTime: number
+  stats: SessionStats
+}
+
+export interface SessionStats {
+  logs: number
+  errors: number
+  warnings: number
+}
+
+export interface CostData {
+  totalUSD: number
+  totalTHB: number
+}
+
+export interface CleanupResult {
+  deleted: string[]
+  errors: string[]
+}
+
+export interface SessionConfig {
+  /** Base directory for all session logs (env: SESSION_LOG_DIR, default: 'logs') */
+  readonly LOG_BASE_DIR: string
+
+  /** Days to retain logs before cleanup (env: SESSION_LOG_RETENTION_DAYS, default: 30) */
+  readonly LOG_RETENTION_DAYS: number
+
+  /** Enable/disable file logging (env: SESSION_LOG_TO_FILE, default: true) */
+  readonly ENABLE_FILE: boolean
+
+  /** Enable/disable stdout output (env: SESSION_LOG_TO_STDOUT, default: true) */
+  readonly ENABLE_STDOUT: boolean
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Wrapper Pattern (Recommended)
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Run async function within session logger context.
+ * Automatically initializes and finalizes the session.
+ *
+ * @example
+ * await withSession({
+ *   sessionId: order._id.toString(),
+ *   category: 'ai-pipeline',
+ *   metadata: { orderId: order._id }
+ * }, async () => {
+ *   log('Pipeline', 'Processing started')
+ *   // ... your logic
+ * })
+ */
+export function withSession<T>(options: SessionOptions, asyncFn: () => Promise<T>): Promise<T>
+
+// ═══════════════════════════════════════════════════════════════
+// Manual Pattern (Advanced)
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Start a session logger context.
+ * ⚠️ Must call endSession() in a finally block.
+ */
+export function startSession(options: SessionOptions): void
+
+/**
+ * End current session logger context.
+ * ⚠️ Must be called in a finally block after startSession().
+ */
+export function endSession(): Promise<void>
+
+// ═══════════════════════════════════════════════════════════════
+// Context Inspection
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Get current session context, or null if not inside a session.
+ */
+export function getSessionContext(): SessionContext | null
+
+// ═══════════════════════════════════════════════════════════════
+// Logging Functions
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Log an info message.
+ * Falls back to console.log when outside a session context.
+ */
+export function log(tag: string, message: string, ...args: unknown[]): void
+
+/**
+ * Alias for log() — semantic clarity.
+ */
+export function info(tag: string, message: string, ...args: unknown[]): void
+
+/**
+ * Log an error message.
+ * Falls back to console.error when outside a session context.
+ */
+export function error(tag: string, message: string, ...args: unknown[]): void
+
+/**
+ * Log a warning message.
+ * Falls back to console.warn when outside a session context.
+ */
+export function warn(tag: string, message: string, ...args: unknown[]): void
+
+// ═══════════════════════════════════════════════════════════════
+// Special Formatters
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Log cost/billing data with consistent formatting.
+ */
+export function logCost(
+  tag: string,
+  costData: CostData,
+  inputUnits?: number,
+  outputUnits?: number,
+  cachedUnits?: number
+): void
+
+/**
+ * Log duration/performance metrics.
+ */
+export function logDuration(tag: string, durationMs: number, label?: string): void
+
+/**
+ * Log custom metrics with optional unit.
+ */
+export function logMetric(tag: string, metricName: string, value: number | string, unit?: string): void
+
+// ═══════════════════════════════════════════════════════════════
+// Utilities
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Clean up old log files beyond retention period.
+ */
+export function cleanOldLogs(category?: string, daysToKeep?: number): Promise<CleanupResult>
+
+// ═══════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════
+
+/** Configuration with lazy environment variable evaluation */
+export const CONFIG: SessionConfig
+
+/** Common tag suggestions (reference only — not enforced) */
+export const COMMON_TAGS: {
+  readonly PIPELINE: 'Pipeline'
+  readonly QUALITY: 'Quality'
+  readonly OCR: 'OCR'
+  readonly OPENAI: 'OpenAI'
+  readonly CLIENT: 'Client'
+  readonly REDEMPTION: 'Redemption'
+  readonly POINTS: 'Points'
+  readonly VALIDATION: 'Validation'
+  readonly NOTIFICATION: 'Notification'
+  readonly SURVEY: 'Survey'
+  readonly STORAGE: 'Storage'
+  readonly ANALYTICS: 'Analytics'
+  readonly ORDER: 'Order'
+  readonly PAYMENT: 'Payment'
+  readonly INVENTORY: 'Inventory'
+  readonly SHIPPING: 'Shipping'
+  readonly MESSAGE: 'Message'
+  readonly WEBHOOK: 'Webhook'
+  readonly RESPONSE: 'Response'
+  readonly BROADCAST: 'Broadcast'
+  readonly DATABASE: 'Database'
+  readonly CACHE: 'Cache'
+  readonly WORKER: 'Worker'
+}