blorq-logger 1.0.0

package/.env.example

@@ -0,0 +1,6 @@
+BLORQ_APP_NAME=my-api
+BLORQ_URL=http://localhost:9900/api/logs
+BLORQ_API_KEY=blq_your_key_here
+BLORQ_LEVEL=info
+BLORQ_INTERCEPT=false
+BLORQ_SKIP_PATHS=/health,/ping,/favicon,/_next/static

package/README.md

@@ -0,0 +1,282 @@
+# blorq-logger
+
+Zero-dependency structured logger for Node.js ≥18. Ships logs to [Blorq](https://github.com/your-org/blorq) or any compatible HTTP endpoint. Works with **Express**, **Next.js**, **Fastify**, **Koa**, **NestJS**, and plain **Node.js**.
+
+```bash
+npm install blorq-logger
+```
+
+---
+
+## Quick setup (any framework)
+
+```js
+const logger = require('blorq-logger');
+
+logger.configure({
+  appName:  'my-api',
+  remoteUrl: 'http://localhost:9900/api/logs',  // your Blorq instance
+  apiKey:    process.env.BLORQ_API_KEY,
+});
+
+// Intercept existing console.log/warn/error — zero other changes needed
+logger.install();
+```
+
+From here, **every existing `console.log()`** in your app ships to Blorq automatically, while still printing to the terminal. No code changes needed in existing files.
+
+---
+
+## Structured logging
+
+```js
+const logger = require('blorq-logger');
+
+// Root logger
+logger.info('Server started', { port: 3000 });
+logger.warn('Rate limit approaching', { userId: 'u123' });
+logger.error('DB timeout', new Error('Connection refused'));
+
+// Child loggers — carry context into every line they emit
+const paymentLog = logger.create({ service: 'PaymentService', version: '2' });
+paymentLog.info('Charge processed', { amount: 99, currency: 'USD' });
+
+// Chain: inherit + add more context
+const reqLog = paymentLog.child({ requestId: req.requestId });
+reqLog.error('Stripe declined', new Error('card_declined'));
+```
+
+Each log line is structured JSON:
+```json
+{
+  "ts": "2024-01-15T10:23:45.000Z",
+  "level": "ERROR",
+  "appName": "my-api",
+  "service": "PaymentService",
+  "requestId": "abc-123",
+  "message": "Stripe declined",
+  "data": [{ "error": "card_declined", "stack": "..." }]
+}
+```
+
+---
+
+## Framework adapters
+
+### Express / NestJS / Connect
+
+```js
+const express = require('express');
+const logger  = require('blorq-logger');
+
+logger.configure({ appName: 'my-api', remoteUrl: '...', apiKey: '...' });
+
+const app = express();
+
+// Ships every request as a structured log to {appName}-requests/
+app.use(logger.requestLogger());
+
+// req.blorqLogger is a child logger pre-loaded with requestId
+app.get('/users/:id', (req, res) => {
+  req.blorqLogger.info('Fetching user', { userId: req.params.id });
+  res.json({ ok: true });
+});
+```
+
+### Next.js — Pages Router (API routes)
+
+```js
+// pages/api/hello.js
+const logger = require('blorq-logger');
+const { withLogger } = require('blorq-logger/next');
+
+logger.configure({ appName: 'my-nextapp', remoteUrl: '...', apiKey: '...' });
+
+export default withLogger(async (req, res) => {
+  logger.info('hello called');
+  res.json({ message: 'hello' });
+});
+```
+
+### Next.js — App Router (middleware.js)
+
+```js
+// middleware.js (runs in Edge Runtime)
+import { nextMiddleware } from 'blorq-logger/next';
+
+export default nextMiddleware({
+  appName:   'my-nextapp',
+  remoteUrl: 'https://blorq.yourdomain.com/api/logs',
+  apiKey:    process.env.BLORQ_API_KEY,
+});
+
+export const config = { matcher: '/api/:path*' };
+```
+
+### Fastify
+
+```js
+const fastify = require('fastify')();
+const logger  = require('blorq-logger');
+
+logger.configure({ appName: 'my-api', remoteUrl: '...', apiKey: '...' });
+
+// Register as a Fastify plugin
+await fastify.register(logger.requestLogger({ framework: 'fastify' }));
+
+fastify.get('/hello', async (request) => {
+  request.log.info('hello route hit');        // per-request structured logger
+  return { hello: 'world' };
+});
+```
+
+### Koa
+
+```js
+const Koa    = require('koa');
+const logger = require('blorq-logger');
+
+logger.configure({ appName: 'my-api', remoteUrl: '...', apiKey: '...' });
+
+const app = new Koa();
+app.use(logger.requestLogger({ framework: 'koa' }));
+
+app.use(async ctx => {
+  ctx.log.info('request received');           // per-request structured logger
+  ctx.body = 'hello';
+});
+```
+
+### NestJS
+
+```ts
+// main.ts
+import logger from 'blorq-logger';
+import { requestMiddleware } from 'blorq-logger/express';
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  logger.configure({
+    appName:   'my-nest-api',
+    remoteUrl: process.env.BLORQ_URL,
+    apiKey:    process.env.BLORQ_API_KEY,
+    interceptConsole: true,             // capture NestJS's own console output
+  });
+
+  const app = await NestFactory.create(AppModule);
+  app.use(requestMiddleware());          // from 'blorq-logger/express'
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+---
+
+## Configuration reference
+
+All options can be set via `configure()` or environment variables.
+
+| Option | Env var | Default | Description |
+|---|---|---|---|
+| `appName` | `BLORQ_APP_NAME` | `'app'` | Name of your service |
+| `remoteUrl` | `BLORQ_URL` | `null` | Blorq ingest URL |
+| `apiKey` | `BLORQ_API_KEY` | `''` | `X-Api-Key` value |
+| `level` | `BLORQ_LEVEL` | `'info'` | Minimum level: `debug\|info\|warn\|error\|fatal\|silent` |
+| `prettyPrint` | — | `true` in dev | Pretty-print JSON to stdout |
+| `stdout` | — | `true` | Write to `process.stdout` (besides remote) |
+| `interceptConsole` | `BLORQ_INTERCEPT` | `false` | Patch `console.*` globally |
+| `bufferSize` | — | `50` | Flush when buffer hits this size |
+| `flushIntervalMs` | — | `200` | Flush timer in ms |
+| `remoteTimeoutMs` | — | `3000` | HTTP timeout for remote sends |
+| `remoteRetries` | — | `2` | Retry attempts on failure |
+| `skipPaths` | `BLORQ_SKIP_PATHS` | `/health,/ping,/favicon,/_next/static` | Paths skipped by `requestLogger()` |
+
+### .env example
+
+```bash
+BLORQ_APP_NAME=my-api
+BLORQ_URL=http://blorq:9900/api/logs
+BLORQ_API_KEY=blq_abc123...
+BLORQ_LEVEL=info
+BLORQ_INTERCEPT=true
+```
+
+---
+
+## Console drop-in
+
+If you have a codebase full of `console.log()` and don't want to change anything:
+
+```js
+// At the very top of your entry file:
+const logger = require('blorq-logger');
+logger.configure({ appName: 'my-api', remoteUrl: '...', apiKey: '...' });
+logger.install();   // patches console.* globally
+
+// Everything from here ships to Blorq
+// console.log, console.warn, console.error all still print to terminal too
+```
+
+Or use it as a direct `console` replacement in a single file:
+
+```js
+const console = require('blorq-logger').console;
+// Now console.log/warn/error/debug in this file go to Blorq
+```
+
+---
+
+## Graceful shutdown
+
+The logger auto-flushes on `SIGINT`, `SIGTERM`, and `beforeExit`. For manual control:
+
+```js
+process.on('SIGTERM', async () => {
+  await logger.flush();
+  process.exit(0);
+});
+```
+
+---
+
+## How request logs appear in Blorq
+
+Request logs land in `logs/{appName}-requests/{date}.log` and are visible in **Insights → API Analytics**. Each line contains:
+
+```json
+{
+  "ts": "...",
+  "level": "INFO",
+  "appName": "my-api-requests",
+  "type": "api_request",
+  "requestId": "uuid",
+  "method": "POST",
+  "path": "/api/orders",
+  "statusCode": 201,
+  "durationMs": 47.2,
+  "reqSizeBytes": 128,
+  "resSizeBytes": 256
+}
+```
+
+---
+
+## TypeScript
+
+Full types included via `src/index.d.ts`:
+
+```ts
+import logger, { Logger, BlorqConfig } from 'blorq-logger';
+
+logger.configure({ appName: 'my-api' } satisfies BlorqConfig);
+
+const paymentLog: Logger = logger.create({ service: 'PaymentService' });
+paymentLog.info('Charge processed', { amount: 99 });
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "blorq-logger",
+  "version": "1.0.0",
+  "description": "Zero-dependency structured logger for Node.js — ships logs to Blorq or any HTTP endpoint. Works with Express, Next.js, Fastify, Koa, NestJS, and plain Node.",
+  "main": "src/index.js",
+  "exports": {
+    ".":          "./src/index.js",
+    "./express":  "./src/adapters/express.js",
+    "./next":     "./src/adapters/next.js",
+    "./fastify":  "./src/adapters/fastify.js",
+    "./koa":      "./src/adapters/koa.js"
+  },
+  "types": "src/index.d.ts",
+  "scripts": {
+    "test": "node tests/basic.test.js"
+  },
+  "keywords": ["logger","logging","blorq","structured","observability","express","nextjs","fastify","koa"],
+  "license": "MIT",
+  "dependencies": {},
+  "engines": { "node": ">=18.0.0" }
+}

package/src/adapters/express.js

@@ -0,0 +1,74 @@
+/**
+ * Express / Connect / NestJS / plain http adapter
+ * Works with any Connect-compatible framework.
+ */
+'use strict';
+
+const crypto = require('crypto');
+const { state, enqueue, buildEntry } = require('../core');
+
+/**
+ * Returns Express-compatible middleware: (req, res, next) => void
+ *
+ * Options:
+ *   appName     – override default appName for request logs
+ *   skipPaths   – override default skip paths
+ *   logBody     – include request body (careful: reads stream, default false)
+ */
+function requestMiddleware(opts = {}) {
+  const appName  = opts.appName  || state.cfg.appName;
+  const skip     = opts.skipPaths || state.cfg.skipPaths;
+
+  return function blorqRequestLogger(req, res, next) {
+    const rawPath = req.path || (req.url || '/').split('?')[0];
+
+    if (skip.some(p => rawPath.startsWith(p))) return next();
+
+    const startHr   = process.hrtime.bigint();
+    const requestId = req.headers['x-request-id'] || crypto.randomUUID();
+    const reqSize   = parseInt(req.headers['content-length'] || '0', 10) || 0;
+
+    // Attach to request so route handlers can reference it
+    req.requestId = requestId;
+    req.blorqLogger = require('..').create({ requestId });
+    res.setHeader('X-Request-Id', requestId);
+
+    let recorded = false;
+    function record() {
+      if (recorded) return;
+      recorded = true;
+
+      const ms        = Math.round(Number(process.hrtime.bigint() - startHr) / 1e4) / 100;
+      const status    = res.statusCode;
+      const routePath = req.route
+        ? (req.baseUrl || '') + req.route.path
+        : rawPath;
+      const resSize   = parseInt(res.getHeader('content-length') || '0', 10) || 0;
+      const level     = status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info';
+
+      const entry = JSON.stringify({
+        ts:           new Date().toISOString(),
+        level:        level.toUpperCase(),
+        appName:      appName + '-requests',
+        type:         'api_request',
+        requestId,
+        method:       req.method,
+        path:         routePath,
+        statusCode:   status,
+        durationMs:   ms,
+        reqSizeBytes: reqSize,
+        resSizeBytes: resSize,
+        userAgent:    req.headers['user-agent'] || '',
+        message:      req.method + ' ' + routePath + ' ' + status + ' ' + ms + 'ms',
+      });
+
+      enqueue(entry);
+    }
+
+    res.once('finish', record);
+    res.once('close',  record);
+    next();
+  };
+}
+
+module.exports = { requestMiddleware };

package/src/adapters/fastify.js

@@ -0,0 +1,66 @@
+/**
+ * Fastify adapter — registers as a Fastify plugin
+ *
+ * Usage:
+ *   const fastify = require('fastify')();
+ *   await fastify.register(require('blorq-logger/fastify'), {
+ *     appName: 'my-api',
+ *     remoteUrl: 'http://blorq:9900/api/logs',
+ *     apiKey: 'blq_...',
+ *   });
+ */
+'use strict';
+
+const crypto = require('crypto');
+const { state, enqueue } = require('../core');
+
+function plugin(opts = {}) {
+  const appName = opts.appName || state.cfg.appName;
+  const skip    = opts.skipPaths || state.cfg.skipPaths;
+
+  // fastify-plugin style (no encapsulation)
+  async function blorqPlugin(fastify, options) {
+    fastify.addHook('onRequest', async (request, reply) => {
+      const rawPath = request.routerPath || request.url.split('?')[0];
+      if (skip.some(p => rawPath.startsWith(p))) return;
+
+      request.blorqStart     = process.hrtime.bigint();
+      request.blorqRequestId = request.headers['x-request-id'] || crypto.randomUUID();
+      reply.header('X-Request-Id', request.blorqRequestId);
+    });
+
+    fastify.addHook('onResponse', async (request, reply) => {
+      if (!request.blorqStart) return;
+
+      const ms        = Math.round(Number(process.hrtime.bigint() - request.blorqStart) / 1e4) / 100;
+      const status    = reply.statusCode;
+      const routePath = request.routerPath || request.url.split('?')[0];
+
+      enqueue(JSON.stringify({
+        ts:         new Date().toISOString(),
+        level:      status >= 500 ? 'ERROR' : status >= 400 ? 'WARN' : 'INFO',
+        appName:    appName + '-requests',
+        type:       'api_request',
+        requestId:  request.blorqRequestId,
+        method:     request.method,
+        path:       routePath,
+        statusCode: status,
+        durationMs: ms,
+        message:    request.method + ' ' + routePath + ' ' + status + ' ' + ms + 'ms',
+      }));
+    });
+
+    // Attach a structured logger to every request
+    fastify.decorateRequest('log', null);
+    fastify.addHook('onRequest', async (request) => {
+      const Logger = require('../core').Logger;
+      request.log = new Logger({ requestId: request.blorqRequestId });
+    });
+  }
+
+  // Mark as fastify-plugin so it doesn't create a new scope
+  blorqPlugin[Symbol.for('skip-override')] = true;
+  return blorqPlugin;
+}
+
+module.exports = { plugin };

package/src/adapters/koa.js

@@ -0,0 +1,55 @@
+/**
+ * Koa adapter
+ *
+ * Usage:
+ *   const Koa = require('koa');
+ *   const { requestMiddleware } = require('blorq-logger/koa');
+ *   const app = new Koa();
+ *   app.use(requestMiddleware({ appName: 'my-api' }));
+ */
+'use strict';
+
+const crypto = require('crypto');
+const { state, enqueue } = require('../core');
+
+function requestMiddleware(opts = {}) {
+  const appName = opts.appName || state.cfg.appName;
+  const skip    = opts.skipPaths || state.cfg.skipPaths;
+
+  return async function blorqKoaMiddleware(ctx, next) {
+    const rawPath = ctx.path;
+    if (skip.some(p => rawPath.startsWith(p))) return next();
+
+    const startHr   = process.hrtime.bigint();
+    const requestId = ctx.headers['x-request-id'] || crypto.randomUUID();
+
+    ctx.state.requestId = requestId;
+    ctx.set('X-Request-Id', requestId);
+
+    // Attach structured logger to context
+    const Logger = require('../core').Logger;
+    ctx.log = new Logger({ requestId });
+
+    try {
+      await next();
+    } finally {
+      const ms        = Math.round(Number(process.hrtime.bigint() - startHr) / 1e4) / 100;
+      const status    = ctx.status;
+
+      enqueue(JSON.stringify({
+        ts:         new Date().toISOString(),
+        level:      status >= 500 ? 'ERROR' : status >= 400 ? 'WARN' : 'INFO',
+        appName:    appName + '-requests',
+        type:       'api_request',
+        requestId,
+        method:     ctx.method,
+        path:       rawPath,
+        statusCode: status,
+        durationMs: ms,
+        message:    ctx.method + ' ' + rawPath + ' ' + status + ' ' + ms + 'ms',
+      }));
+    }
+  };
+}
+
+module.exports = { requestMiddleware };

package/src/adapters/next.js

@@ -0,0 +1,142 @@
+/**
+ * Next.js adapter
+ *
+ * Works for:
+ *   - App Router (Next 13+) — middleware.js
+ *   - Pages Router — API routes via withLogger()
+ *   - Edge Runtime — uses global fetch (already available)
+ */
+'use strict';
+
+const crypto = require('crypto');
+const { state, enqueue } = require('../core');
+
+// ── Pages Router (API routes) ─────────────────────────────────────────────
+/**
+ * Wraps a Next.js API route handler with request logging.
+ *
+ * Usage (pages/api/hello.js):
+ *   const { withLogger } = require('blorq-logger/next');
+ *   export default withLogger(async (req, res) => { res.json({ ok: true }); });
+ *
+ * Or use the root convenience shorthand:
+ *   const logger = require('blorq-logger');
+ *   export default logger.requestLogger({ framework:'next' })(handler);
+ */
+function withLogger(optsOrHandler, maybeOpts = {}) {
+  // Support: withLogger(handler) or withLogger(opts)(handler)
+  if (typeof optsOrHandler === 'function') {
+    return _wrapHandler(optsOrHandler, maybeOpts);
+  }
+  const opts = optsOrHandler || {};
+  return function (handler) { return _wrapHandler(handler, opts); };
+}
+
+function _wrapHandler(handler, opts = {}) {
+  const appName = opts.appName || state.cfg.appName;
+  const skip    = opts.skipPaths || state.cfg.skipPaths;
+
+  return async function blorqNextHandler(req, res) {
+    const rawPath = req.url ? req.url.split('?')[0] : '/';
+    if (skip.some(p => rawPath.startsWith(p))) return handler(req, res);
+
+    const startHr   = process.hrtime.bigint();
+    const requestId = req.headers['x-request-id'] || crypto.randomUUID();
+    req.requestId   = requestId;
+    if (res.setHeader) res.setHeader('X-Request-Id', requestId);
+
+    let status = 200;
+    const origJson    = res.json?.bind(res);
+    const origSend    = res.send?.bind(res);
+    const origStatus  = res.status?.bind(res);
+
+    if (origStatus) res.status = (code) => { status = code; return origStatus(code); };
+
+    const origEnd = res.end?.bind(res);
+    if (origEnd) {
+      res.end = function (...args) {
+        record();
+        return origEnd(...args);
+      };
+    }
+
+    let recorded = false;
+    function record() {
+      if (recorded) return;
+      recorded = true;
+      const ms = Math.round(Number(process.hrtime.bigint() - startHr) / 1e4) / 100;
+      const sc = res.statusCode || status;
+      enqueue(JSON.stringify({
+        ts: new Date().toISOString(),
+        level: sc >= 500 ? 'ERROR' : sc >= 400 ? 'WARN' : 'INFO',
+        appName: appName + '-requests',
+        type: 'api_request',
+        requestId,
+        method:     req.method,
+        path:       rawPath,
+        statusCode: sc,
+        durationMs: ms,
+        message:    req.method + ' ' + rawPath + ' ' + sc + ' ' + ms + 'ms',
+      }));
+    }
+
+    try { await handler(req, res); } catch (err) { status = 500; record(); throw err; }
+    record();
+  };
+}
+
+// ── App Router (Next 13+ middleware.js) ───────────────────────────────────
+/**
+ * Usage in middleware.js:
+ *   import { nextMiddleware } from 'blorq-logger/next';
+ *   export default nextMiddleware();
+ *   export const config = { matcher: '/api/:path*' };
+ *
+ * Note: Next middleware runs in the Edge Runtime.
+ * This uses fetch (always available in Edge) and does NOT use Node.js built-ins.
+ */
+function nextMiddleware(opts = {}) {
+  const appName = opts.appName || state.cfg.appName || 'app';
+  const apiKey  = opts.apiKey  || state.cfg.apiKey  || '';
+  const url     = opts.remoteUrl || state.cfg.remoteUrl;
+  const skip    = opts.skipPaths || state.cfg.skipPaths || [];
+
+  return async function blorqEdgeMiddleware(request, event) {
+    const { NextResponse } = await import('next/server');
+    const pathname = new URL(request.url).pathname;
+
+    if (skip.some(p => pathname.startsWith(p))) return NextResponse.next();
+
+    const start     = Date.now();
+    const requestId = request.headers.get('x-request-id') || crypto.randomUUID();
+
+    const response  = NextResponse.next();
+    response.headers.set('X-Request-Id', requestId);
+
+    const ms   = Date.now() - start;
+    const entry = JSON.stringify({
+      ts:         new Date().toISOString(),
+      level:      'INFO',
+      appName:    appName + '-requests',
+      type:       'api_request',
+      requestId,
+      method:     request.method,
+      path:       pathname,
+      durationMs: ms,
+      message:    request.method + ' ' + pathname + ' ' + ms + 'ms',
+    });
+
+    if (url) {
+      // Fire-and-forget in Edge (no await — keeps it non-blocking)
+      fetch(url, {
+        method:  'POST',
+        headers: { 'Content-Type': 'application/json', ...(apiKey ? { 'x-api-key': apiKey } : {}) },
+        body:    JSON.stringify({ appName, logs: [entry] }),
+      }).catch(() => {});
+    }
+
+    return response;
+  };
+}
+
+module.exports = { withLogger, nextMiddleware };

package/src/core.js

@@ -0,0 +1,190 @@
+/**
+ * blorq-logger — core engine
+ * Zero external dependencies. Works in any Node.js >=18 environment.
+ */
+'use strict';
+
+const os     = require('os');
+const crypto = require('crypto');
+
+// ── Default config ────────────────────────────────────────────────────────
+const DEFAULT_CFG = {
+  appName:          process.env.BLORQ_APP_NAME     || process.env.APP_NAME   || 'app',
+  remoteUrl:        process.env.BLORQ_URL          || process.env.LOG_REMOTE_URL || null,
+  apiKey:           process.env.BLORQ_API_KEY      || process.env.LOG_API_KEY    || '',
+  level:            process.env.BLORQ_LEVEL        || process.env.LOG_LEVEL      || 'info',
+  prettyPrint:      true,              // pretty-print JSON (with newlines + indentation)
+  stdout:           false,             // also write to stdout (besides sending remote)
+  bufferSize:       50,                // flush when buffer reaches this
+  flushIntervalMs:  200,               // flush every N ms
+  remoteTimeoutMs:  3000,
+  remoteRetries:    2,
+  retryDelayMs:     300,
+  // Console interception (set via configure({ interceptConsole:true }))
+  interceptConsole: process.env.BLORQ_INTERCEPT === 'true',
+  // Paths skipped by requestLogger()
+  skipPaths: (process.env.BLORQ_SKIP_PATHS || '/health,/ping,/favicon,/_next/static')
+    .split(',').map(s => s.trim()).filter(Boolean),
+};
+
+// ── Level ordering ────────────────────────────────────────────────────────
+const LEVELS = { silent:0, debug:10, info:20, warn:30, error:40, fatal:50 };
+
+// ── Sensitive keys masked in JSON output ───────────────────────────────────
+const MASK_KEYS = new Set(['authorization','token','password','secret','apikey','key','auth','passwd','credential','cookie','x-api-key']);
+
+// ── Shared mutable state (module singleton) ────────────────────────────────
+const state = {
+  cfg:            { ...DEFAULT_CFG },
+  buffer:         [],
+  flushTimer:     null,
+  flushPromise:   null,
+  consoleInstalled: false,
+  origConsole:    null,
+};
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function levelNum(l) { return LEVELS[String(l).toLowerCase()] ?? LEVELS.info; }
+function shouldLog(l) { return levelNum(l) >= levelNum(state.cfg.level); }
+
+function safeStringify(obj) {
+  const seen = new WeakSet();
+  return JSON.stringify(obj, (key, val) => {
+    if (typeof val === 'object' && val !== null) {
+      if (seen.has(val)) return '[Circular]';
+      seen.add(val);
+    }
+    if (key && MASK_KEYS.has(key.toLowerCase())) return '***';
+    return val;
+  });
+}
+
+function serializeExtras(extras) {
+  return (extras || []).map(x => {
+    if (x instanceof Error) return { error: x.message, stack: x.stack };
+    return x;
+  });
+}
+
+function buildEntry(level, appName, context, message, extras) {
+  const payload = {
+    ts:      new Date().toISOString(),
+    level:   level.toUpperCase(),
+    appName: appName || state.cfg.appName,
+    host:    os.hostname(),
+    pid:     process.pid,
+    ...context,
+    message: String(message == null ? '' : message),
+  };
+  const ex = serializeExtras(extras);
+  if (ex.length) payload.data = ex;
+  return state.cfg.prettyPrint ? JSON.stringify(payload, null, 2) : safeStringify(payload);
+}
+
+// ── Buffer + flush ────────────────────────────────────────────────────────
+
+function enqueue(line) {
+  state.buffer.push(line);
+  if (state.buffer.length >= state.cfg.bufferSize) { flush(); return; }
+  if (!state.flushTimer) {
+    state.flushTimer = setTimeout(() => { state.flushTimer = null; flush(); }, state.cfg.flushIntervalMs);
+    if (state.flushTimer.unref) state.flushTimer.unref();
+  }
+}
+
+function flush() {
+  if (state.flushPromise) {
+    state.flushPromise = state.flushPromise.then(() => drain());
+    return;
+  }
+  state.flushPromise = drain().finally(() => { state.flushPromise = null; });
+}
+
+async function drain() {
+  return new Promise(resolve => setImmediate(async () => {
+    const logs = state.buffer.splice(0);
+    if (!logs.length) { resolve(); return; }
+
+    // Local stdout
+    if (state.cfg.stdout) {
+      for (const l of logs) try { process.stdout.write(l + '\n'); } catch {}
+    }
+
+    // Remote ship
+    if (state.cfg.remoteUrl) await sendBatch(logs).catch(() => {});
+    resolve();
+  }));
+}
+
+async function sendBatch(logs) {
+  const { remoteUrl, apiKey, appName, remoteTimeoutMs, remoteRetries, retryDelayMs } = state.cfg;
+  let attempt = 0;
+  while (attempt < remoteRetries + 1) {
+    try {
+      const res = await fetch(remoteUrl, {
+        method:  'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(apiKey ? { 'x-api-key': apiKey } : {}),
+        },
+        body:   JSON.stringify({ appName, logs }),
+        signal: AbortSignal.timeout(remoteTimeoutMs),
+      });
+      if (res.ok) return;
+      throw new Error('HTTP ' + res.status);
+    } catch {
+      attempt++;
+      if (attempt > remoteRetries) return;
+      await new Promise(r => setTimeout(r, retryDelayMs * Math.pow(2, attempt - 1)));
+    }
+  }
+}
+
+// ── Logger class ──────────────────────────────────────────────────────────
+
+class Logger {
+  /**
+   * @param {object} context – Extra fields merged into every log entry
+   */
+  constructor(context = {}) {
+    this._ctx     = context;
+    this._appName = context.appName || null;
+  }
+
+  /** Create a child logger that inherits context + merges extra fields */
+  child(extra = {}) {
+    return new Logger({ ...this._ctx, ...extra });
+  }
+
+  /** Attach extra context to this logger (mutates) */
+  with(extra = {}) {
+    Object.assign(this._ctx, extra);
+    return this;
+  }
+
+  _log(level, message, params) {
+    if (!shouldLog(level)) return;
+    enqueue(buildEntry(level, this._appName, this._ctx, message, params));
+  }
+
+  debug(msg, ...p) { this._log('debug', msg, p.length ? p : undefined); }
+  info (msg, ...p) { this._log('info',  msg, p.length ? p : undefined); }
+  warn (msg, ...p) { this._log('warn',  msg, p.length ? p : undefined); }
+  error(msg, ...p) { this._log('error', msg, p.length ? p : undefined); }
+
+  /** Fatal: bypasses buffer, ships immediately (for crash handlers) */
+  fatal(msg, ...p) {
+    if (!shouldLog('fatal')) return;
+    const line = buildEntry('fatal', this._appName, this._ctx, msg, p.length ? p : undefined);
+    try { process.stderr.write(line + '\n'); } catch {}
+    if (state.cfg.remoteUrl) sendBatch([line]).catch(() => {});
+  }
+
+  /** Flush any buffered logs right now (useful before process.exit) */
+  flush() { return drain(); }
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────
+
+module.exports = { Logger, state, LEVELS, enqueue, buildEntry, flush, drain, shouldLog, safeStringify };

package/src/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * blorq-logger — TypeScript definitions
+ */
+
+export interface BlorqConfig {
+  /** Application name (default: APP_NAME env or 'app') */
+  appName?: string;
+  /** Blorq ingest URL e.g. http://localhost:9900/api/logs */
+  remoteUrl?: string | null;
+  /** API key for Blorq (X-Api-Key header) */
+  apiKey?: string;
+  /** Minimum log level: 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent' */
+  level?: "debug" | "info" | "warn" | "error" | "fatal" | "silent";
+  /** Pretty-print JSON to stdout (default: true in development) */
+  prettyPrint?: boolean;
+  /** Also write to process.stdout (default: true) */
+  stdout?: boolean;
+  /** Intercept console.log/warn/error/debug and ship them too */
+  interceptConsole?: boolean;
+  /** Flush when buffer reaches this size (default: 50) */
+  bufferSize?: number;
+  /** Flush interval in ms (default: 200) */
+  flushIntervalMs?: number;
+  /** HTTP timeout for remote sends in ms (default: 3000) */
+  remoteTimeoutMs?: number;
+  /** Retry attempts for failed sends (default: 2) */
+  remoteRetries?: number;
+  /** Paths skipped by requestLogger (default: /health, /ping, /favicon) */
+  skipPaths?: string[];
+}
+
+export interface RequestLoggerOptions {
+  framework?: "express" | "next" | "fastify" | "koa";
+  appName?: string;
+  skipPaths?: string[];
+}
+
+export declare class Logger {
+  constructor(context?: Record<string, unknown>);
+  child(extra?: Record<string, unknown>): Logger;
+  with(extra?: Record<string, unknown>): this;
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  fatal(message: string, ...args: unknown[]): void;
+  flush(): Promise<void>;
+}
+
+declare const logger: Logger & {
+  configure(opts: BlorqConfig): void;
+  create(context?: Record<string, unknown>): Logger;
+  install(): void;
+  uninstall(): void;
+  requestLogger(
+    opts?: RequestLoggerOptions,
+  ): (req: unknown, res: unknown, next?: unknown) => void;
+  requestId(): string;
+  console: {
+    log: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+  };
+};
+
+export default logger;
+// module.exports = logger;

package/src/index.js

@@ -0,0 +1,141 @@
+/**
+ * blorq-logger — main entry point
+ *
+ * Framework-agnostic. For framework-specific helpers use the adapters:
+ *   require('blorq-logger/express')
+ *   require('blorq-logger/next')
+ *   require('blorq-logger/fastify')
+ *   require('blorq-logger/koa')
+ */
+'use strict';
+
+const { Logger, state, flush, drain, shouldLog, safeStringify } = require('./core');
+const crypto = require('crypto');
+
+// ── Root singleton logger ─────────────────────────────────────────────────
+const root = new Logger();
+
+// ─────────────────────────────────────────────────────────────────────────
+// configure({ appName, remoteUrl, apiKey, level, ... })
+// Call once at startup before any logging.
+// ─────────────────────────────────────────────────────────────────────────
+root.configure = function configure(opts = {}) {
+  Object.assign(state.cfg, opts);
+  if (opts.interceptConsole) _installConsole();
+};
+
+// ─────────────────────────────────────────────────────────────────────────
+// create(context) — factory for child loggers
+// ─────────────────────────────────────────────────────────────────────────
+root.create = function create(context = {}) {
+  return new Logger(context);
+};
+
+// ─────────────────────────────────────────────────────────────────────────
+// install() — Patch global console.* to also ship to Blorq
+// All existing console.log/warn/error calls continue printing to terminal.
+// ─────────────────────────────────────────────────────────────────────────
+root.install = function install() { _installConsole(); };
+root.uninstall = function uninstall() { _uninstallConsole(); };
+
+// ─────────────────────────────────────────────────────────────────────────
+// console — a console-compatible object you can use as a drop-in replacement
+//   const console = require('blorq-logger').console;
+// ─────────────────────────────────────────────────────────────────────────
+root.console = {
+  log:   (...a) => root.info(...a),
+  info:  (...a) => root.info(...a),
+  warn:  (...a) => root.warn(...a),
+  error: (...a) => root.error(...a),
+  debug: (...a) => root.debug(...a),
+};
+
+// ─────────────────────────────────────────────────────────────────────────
+// requestLogger() — generic request logger middleware factory
+// Returns the right middleware for the detected / specified framework.
+//
+//   app.use(logger.requestLogger())                // auto-detect
+//   app.use(logger.requestLogger({ framework:'express' }))
+// ─────────────────────────────────────────────────────────────────────────
+root.requestLogger = function requestLogger(opts = {}) {
+  const framework = opts.framework || _detectFramework();
+
+  switch (framework) {
+    case 'koa':
+      return require('./adapters/koa').requestMiddleware(opts);
+    case 'fastify':
+      // Fastify uses plugins — this returns a plugin function
+      return require('./adapters/fastify').plugin(opts);
+    case 'next':
+      // For Next.js API routes, returns a wrapper function, not middleware
+      return require('./adapters/next').withLogger(opts);
+    default:
+      // Express / NestJS / Connect / plain http — returns (req, res, next)
+      return require('./adapters/express').requestMiddleware(opts);
+  }
+};
+
+// Convenience: generate a request ID
+root.requestId = function () { return crypto.randomUUID(); };
+
+// ── Auto-flush & shutdown ─────────────────────────────────────────────────
+if (process.env.BLORQ_NO_AUTOSHUTDOWN !== 'true') {
+  process.on('beforeExit',       () => drain());
+  process.on('exit',             () => { /* sync flush not possible */ });
+  process.on('SIGINT',  async () => { await drain(); process.exit(0); });
+  process.on('SIGTERM', async () => { await drain(); process.exit(0); });
+  process.on('uncaughtException', async (err) => {
+    root.fatal('Uncaught exception', err);
+    await drain();
+    process.exit(1);
+  });
+  process.on('unhandledRejection', async (r) => {
+    root.error('Unhandled rejection', r);
+  });
+}
+
+// Auto-install if env var set
+if (state.cfg.interceptConsole) _installConsole();
+
+// ── Console interception (private) ────────────────────────────────────────
+
+function _installConsole() {
+  if (state.consoleInstalled) return;
+  state.consoleInstalled = true;
+  state.origConsole = {
+    log:   console.log.bind(console),
+    info:  console.info.bind(console),
+    warn:  console.warn.bind(console),
+    error: console.error.bind(console),
+    debug: console.debug.bind(console),
+  };
+
+  const make = (level, orig) => function (...args) {
+    orig(...args);  // always preserve terminal output
+    if (!shouldLog(level)) return;
+    const msg = args.map(a => typeof a === 'string' ? a : safeStringify(a)).join(' ');
+    const { enqueue: eq, buildEntry: be } = require('./core');
+    eq(be(level, state.cfg.appName, {}, msg, []));
+  };
+
+  console.log   = make('info',  state.origConsole.log);
+  console.info  = make('info',  state.origConsole.info);
+  console.warn  = make('warn',  state.origConsole.warn);
+  console.error = make('error', state.origConsole.error);
+  console.debug = make('debug', state.origConsole.debug);
+}
+
+function _uninstallConsole() {
+  if (!state.consoleInstalled || !state.origConsole) return;
+  Object.assign(console, state.origConsole);
+  state.consoleInstalled = false;
+}
+
+function _detectFramework() {
+  // Check if we're in a Next.js environment
+  if (process.env.NEXT_RUNTIME || process.env.__NEXT_PRIVATE_RENDER_WORKER) return 'next';
+  // Otherwise assume Express/Connect
+  return 'express';
+}
+
+module.exports = root;

package/src/index.mjs

@@ -0,0 +1,22 @@
+// ESM re-export wrapper — allows `import logger from 'blorq-logger'`
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const logger  = require('./index.js');
+
+export default logger;
+export const configure      = logger.configure.bind(logger);
+export const create         = logger.create.bind(logger);
+export const install        = logger.install.bind(logger);
+export const uninstall      = logger.uninstall.bind(logger);
+export const express        = (...a) => logger.express(...a);
+export const nextjs         = (...a) => logger.nextjs(...a);
+export const fastify        = logger.fastify;
+export const node           = (...a) => logger.node(...a);
+export const nestjs         = (...a) => logger.nestjs(...a);
+
+export const debug  = (...a) => logger.debug(...a);
+export const info   = (...a) => logger.info(...a);
+export const warn   = (...a) => logger.warn(...a);
+export const error  = (...a) => logger.error(...a);
+export const fatal  = (...a) => logger.fatal(...a);
+export const flush  = () => logger.flush();

package/tests/basic.test.js

@@ -0,0 +1,91 @@
+"use strict";
+let p = 0,
+  f = 0;
+function ok(d, fn) {
+  try {
+    fn();
+    console.log("  \u2705 " + d);
+    p++;
+  } catch (e) {
+    console.error("  \u274c " + d + "\n     " + e.message);
+    f++;
+  }
+}
+console.log("\nblorq-logger tests\n");
+const {
+  Logger,
+  state,
+  buildEntry,
+  shouldLog,
+  safeStringify,
+} = require("../src/core");
+ok("buildEntry returns valid JSON", () => {
+  const obj = JSON.parse(
+    buildEntry("info", "test-app", { req: "abc" }, "hello", []),
+  );
+  if (obj.level !== "INFO") throw new Error("level=" + obj.level);
+  if (obj.message !== "hello") throw new Error("msg");
+});
+ok("shouldLog filters by level", () => {
+  state.cfg.level = "warn";
+  if (shouldLog("info")) throw new Error("info should be filtered");
+  if (!shouldLog("error")) throw new Error("error should pass");
+  state.cfg.level = "info";
+});
+ok("child logger inherits context", () => {
+  const c = new Logger({ svc: "pay" }).child({ uid: "123" });
+  if (c._ctx.svc !== "pay") throw new Error("parent ctx lost");
+  if (c._ctx.uid !== "123") throw new Error("child ctx not set");
+});
+ok("sensitive keys masked", () => {
+  const r = JSON.parse(
+    safeStringify({ user: "alice", password: "s3cr3t", token: "tok" }),
+  );
+  if (r.password !== "***") throw new Error("password not masked");
+  if (r.token !== "***") throw new Error("token not masked");
+  if (r.user !== "alice") throw new Error("user should not be masked");
+});
+const blorq = require("../src/index");
+ok("root logger has full API", () => {
+  [
+    "configure",
+    "create",
+    "install",
+    "uninstall",
+    "requestLogger",
+    "debug",
+    "info",
+    "warn",
+    "error",
+    "fatal",
+    "flush",
+  ].forEach((m) => {
+    if (typeof blorq[m] !== "function") throw new Error("missing: " + m);
+  });
+});
+ok("express middleware is (req,res,next)", () => {
+  const mw = require("../src/adapters/express").requestMiddleware();
+  if (typeof mw !== "function" || mw.length !== 3)
+    throw new Error("wrong signature");
+});
+ok("express middleware skips /health", () => {
+  const mw = require("../src/adapters/express").requestMiddleware({
+    skipPaths: ["/health"],
+  });
+  let called = false;
+  mw(
+    { path: "/health", url: "/health", headers: {}, method: "GET" },
+    {
+      statusCode: 200,
+      getHeader: () => "0",
+      setHeader: () => {},
+      once: () => {},
+    },
+    () => {
+      called = true;
+    },
+  );
+  if (!called) throw new Error("should have called next");
+});
+console.log("\n  " + (p + f) + " tests: " + p + " passed, " + f + " failed\n");
+if (f > 0) process.exit(1);