@kisameholmes/horizon_node 1.0.0

package/README.md

@@ -0,0 +1,93 @@
+# Horizon Node.js SDK
+
+High-performance observability and logging for Node.js.
+
+## Installation
+
+```bash
+npm install @horizon/node
+```
+
+## Features
+
+- **Class-based Client**: Easy to use manual logging.
+- **Batching**: Logs are buffered and sent in batches to minimize HTTP overhead.
+- **Resilience**: Automatic exponential backoff for 5xx errors.
+- **Transports**: Native support for Pino and Winston.
+- **Middlewares**: One-line integration for Fastify and Express.
+- **Error Watchdog**: Automatically catches uncaught exceptions and rejections.
+
+## Core Usage
+
+```typescript
+import { HorizonClient } from '@horizon/node';
+
+const horizon = new HorizonClient({
+  apiKey: 'YOUR_API_KEY',
+  environment: 'production'
+});
+
+// Capture manual logs
+horizon.captureLog('info', 'Process started', { version: '1.2.0' });
+
+// Auto-capture global errors
+horizon.autoCaptureErrors();
+```
+
+## Framework Integration
+
+### Fastify
+
+```typescript
+import Fastify from 'fastify';
+import { fastifyHorizonMiddleware } from '@horizon/node';
+
+const app = Fastify();
+app.addHook('onRequest', fastifyHorizonMiddleware(horizon));
+```
+
+### Express
+
+```typescript
+import express from 'express';
+import { expressHorizonMiddleware } from '@horizon/node';
+
+const app = express();
+app.use(expressHorizonMiddleware(horizon));
+```
+
+## Transports
+
+### Pino
+
+```typescript
+const logger = pino({
+  transport: {
+    target: '@horizon/node/pino',
+    options: { apiKey: '...' }
+  }
+});
+```
+
+### Winston
+
+```typescript
+import { HorizonWinstonTransport } from '@horizon/node';
+
+const logger = winston.createLogger({
+  transports: [
+    new HorizonWinstonTransport({ apiKey: '...' })
+  ]
+});
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiKey` | string | **Required** | Your environment API key. |
+| `ingestUrl` | string | `https://horizon-api.bylinee.com/v1/ingest` | Horizon ingestion endpoint. |
+| `environment` | string | `production` | Deployment environment name. |
+| `batchSize` | number | `50` | Maximum logs per batch. |
+| `flushInterval` | number | `2000` | Max wait time (ms) before flushing. |
+| `maxRetries` | number | `3` | Number of retry attempts for 5xx errors. |

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+export interface HorizonClientOptions {
+    apiKey: string;
+    ingestUrl?: string;
+    environment?: string;
+    batchSize?: number;
+    flushInterval?: number;
+    maxRetries?: number;
+}
+/**
+ * Horizon Node.js SDK Client
+ *
+ * Provides unified ingestion, batching, and resilience.
+ */
+export declare class HorizonClient {
+    private apiKey;
+    private ingestUrl;
+    private environment;
+    private batchSize;
+    private flushInterval;
+    private maxRetries;
+    private buffer;
+    private timer;
+    constructor(opts: HorizonClientOptions);
+    /**
+     * Send a manual log to Horizon (Buffered)
+     */
+    captureLog(level: 'debug' | 'info' | 'warn' | 'error' | 'fatal', message: string, metadata?: any): Promise<void>;
+    /**
+     * Internal flush with Exponential Backoff
+     */
+    private flush;
+    /**
+     * Automatically capture uncaught exceptions and unhandled rejections.
+     */
+    autoCaptureErrors(): void;
+}

package/dist/client.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HorizonClient = void 0;
+/**
+ * Horizon Node.js SDK Client
+ *
+ * Provides unified ingestion, batching, and resilience.
+ */
+class HorizonClient {
+    constructor(opts) {
+        this.buffer = [];
+        this.timer = null;
+        this.apiKey = opts.apiKey;
+        this.ingestUrl = opts.ingestUrl || 'https://horizon-api.bylinee.com/v1/ingest';
+        this.environment = opts.environment || 'production';
+        this.batchSize = opts.batchSize || 50;
+        this.flushInterval = opts.flushInterval || 2000;
+        this.maxRetries = opts.maxRetries || 3;
+        if (!this.apiKey) {
+            throw new Error('Horizon API Key is required');
+        }
+    }
+    /**
+     * Send a manual log to Horizon (Buffered)
+     */
+    async captureLog(level, message, metadata = {}) {
+        this.buffer.push({
+            level,
+            message,
+            metadata: {
+                ...metadata,
+                sdk_env: this.environment,
+            },
+            timestamp: new Date().toISOString(),
+        });
+        if (this.buffer.length >= this.batchSize) {
+            await this.flush();
+        }
+        else if (!this.timer) {
+            this.timer = setTimeout(() => this.flush(), this.flushInterval);
+        }
+    }
+    /**
+     * Internal flush with Exponential Backoff
+     */
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const payload = [...this.buffer];
+        this.buffer = [];
+        const send = async (attempt) => {
+            try {
+                const res = await fetch(this.ingestUrl, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-api-key': this.apiKey,
+                    },
+                    body: JSON.stringify(payload),
+                });
+                if (res.ok || (res.status >= 400 && res.status < 500)) {
+                    return true;
+                }
+                if (res.status >= 500 && attempt < this.maxRetries) {
+                    const delay = Math.pow(2, attempt) * 1000;
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    return send(attempt + 1);
+                }
+                return false;
+            }
+            catch (e) {
+                if (attempt < this.maxRetries) {
+                    const delay = Math.pow(2, attempt) * 1000;
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    return send(attempt + 1);
+                }
+                return false;
+            }
+        };
+        const success = await send(0);
+        if (!success) {
+            console.error('[Horizon SDK] Failed to send logs after multiple retries.');
+        }
+    }
+    /**
+     * Automatically capture uncaught exceptions and unhandled rejections.
+     */
+    autoCaptureErrors() {
+        process.on('uncaughtException', async (error) => {
+            console.error('[Horizon SDK] Uncaught Exception detected.');
+            await this.captureLog('fatal', error.message || 'Uncaught Exception', {
+                stack: error.stack,
+                type: 'uncaughtException',
+            });
+            await this.flush(); // Force flush
+            process.exit(1);
+        });
+        process.on('unhandledRejection', async (reason) => {
+            const message = reason instanceof Error ? reason.message : String(reason);
+            await this.captureLog('fatal', message || 'Unhandled Rejection', {
+                type: 'unhandledRejection',
+                reason: reason instanceof Error ? reason.stack : reason
+            });
+        });
+    }
+}
+exports.HorizonClient = HorizonClient;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './client';
+export * from './pino-horizon';
+export * from './winston-horizon';
+export * from './middleware';

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client"), exports);
+__exportStar(require("./pino-horizon"), exports);
+__exportStar(require("./winston-horizon"), exports);
+__exportStar(require("./middleware"), exports);

package/dist/middleware.d.ts

@@ -0,0 +1,13 @@
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import type { Request, Response, NextFunction } from 'express';
+import { HorizonClient } from './client';
+/**
+ * Fastify Middleware (Hook)
+ * Automatically logs incoming requests and response times.
+ */
+export declare function fastifyHorizonMiddleware(client: HorizonClient): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+/**
+ * Express Middleware
+ * Automatically logs incoming requests and response times.
+ */
+export declare function expressHorizonMiddleware(client: HorizonClient): (req: Request, res: Response, next: NextFunction) => void;

package/dist/middleware.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fastifyHorizonMiddleware = fastifyHorizonMiddleware;
+exports.expressHorizonMiddleware = expressHorizonMiddleware;
+/**
+ * Fastify Middleware (Hook)
+ * Automatically logs incoming requests and response times.
+ */
+function fastifyHorizonMiddleware(client) {
+    return async (request, reply) => {
+        const start = Date.now();
+        // Listen for when the response is sent
+        reply.raw.on('finish', () => {
+            const duration = Date.now() - start;
+            client.captureLog('info', `${request.method} ${request.url} - ${reply.statusCode}`, {
+                method: request.method,
+                url: request.url,
+                statusCode: reply.statusCode,
+                durationMs: duration,
+                ip: request.ip,
+                userAgent: request.headers['user-agent'],
+            });
+        });
+    };
+}
+/**
+ * Express Middleware
+ * Automatically logs incoming requests and response times.
+ */
+function expressHorizonMiddleware(client) {
+    return (req, res, next) => {
+        const start = Date.now();
+        res.on('finish', () => {
+            const duration = Date.now() - start;
+            client.captureLog('info', `${req.method} ${req.originalUrl} - ${res.statusCode}`, {
+                method: req.method,
+                url: req.originalUrl,
+                statusCode: res.statusCode,
+                durationMs: duration,
+                ip: req.ip,
+                userAgent: req.get('user-agent'),
+            });
+        });
+        next();
+    };
+}

package/dist/pino-horizon.d.ts

@@ -0,0 +1,17 @@
+import build from 'pino-abstract-transport';
+interface HorizonTransportOptions {
+    apiKey: string;
+    ingestUrl?: string;
+    batchSize?: number;
+    flushInterval?: number;
+}
+/**
+ * Horizon Pino Transport
+ *
+ * Performance features:
+ * - Batches logs up to batchSize (default 50)
+ * - Flushes every flushInterval (default 2s)
+ * - Converts Pino numeric levels to Horizon string levels
+ */
+export default function (opts: HorizonTransportOptions): Promise<import("stream").Transform & build.OnUnknown>;
+export {};

package/dist/pino-horizon.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = default_1;
+const pino_abstract_transport_1 = __importDefault(require("pino-abstract-transport"));
+/**
+ * Pino Numeric Levels:
+ * 10: trace
+ * 20: debug
+ * 30: info
+ * 40: warn
+ * 50: error
+ * 60: fatal
+ */
+const PINO_LEVEL_MAP = {
+    10: 'debug', // Map trace to debug as per Horizon capabilities
+    20: 'debug',
+    30: 'info',
+    40: 'warn',
+    50: 'error',
+    60: 'fatal',
+};
+/**
+ * Horizon Pino Transport
+ *
+ * Performance features:
+ * - Batches logs up to batchSize (default 50)
+ * - Flushes every flushInterval (default 2s)
+ * - Converts Pino numeric levels to Horizon string levels
+ */
+async function default_1(opts) {
+    const { apiKey, ingestUrl = 'https://horizon-api.bylinee.com/v1/ingest', batchSize = 50, flushInterval = 2000, } = opts;
+    if (!apiKey) {
+        throw new Error('Horizon API Key is required for ingestion');
+    }
+    let buffer = [];
+    let timer = null;
+    const flush = async () => {
+        if (buffer.length === 0)
+            return;
+        const payload = [...buffer];
+        buffer = [];
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        try {
+            const res = await fetch(ingestUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': apiKey,
+                },
+                body: JSON.stringify(payload),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: 'Unknown server error' }));
+                console.warn(`[Horizon Pino] Ingestion failed (${res.status}): ${err.error}`);
+            }
+        }
+        catch (e) {
+            console.error('[Horizon Pino] Critical transport error:', e);
+        }
+    };
+    return (0, pino_abstract_transport_1.default)(async function (source) {
+        for await (const obj of source) {
+            if (!obj)
+                continue;
+            const level = PINO_LEVEL_MAP[obj.level] || 'info';
+            const message = obj.msg || 'No message';
+            const timestamp = obj.time ? new Date(obj.time).toISOString() : new Date().toISOString();
+            // Clean pino-specific internal fields from metadata
+            const metadata = { ...obj };
+            delete metadata.level;
+            delete metadata.msg;
+            delete metadata.time;
+            delete metadata.v;
+            buffer.push({
+                level,
+                message,
+                metadata,
+                timestamp,
+            });
+            if (buffer.length >= batchSize) {
+                await flush();
+            }
+            else if (!timer) {
+                timer = setTimeout(flush, flushInterval);
+            }
+        }
+    }, {
+        async close() {
+            // Ensure remaining logs are sent on process exit
+            await flush();
+        },
+    });
+}

package/dist/winston-horizon.d.ts

@@ -0,0 +1,34 @@
+import Transport from 'winston-transport';
+interface HorizonWinstonOptions extends Transport.TransportStreamOptions {
+    apiKey: string;
+    ingestUrl?: string;
+    batchSize?: number;
+    flushInterval?: number;
+}
+/**
+ * Winston Transport for Horizon
+ *
+ * Integration:
+ * logger.add(new HorizonWinstonTransport({ apiKey: '...' }));
+ *
+ * Features:
+ * - Batched ingestion (batchSize, flushInterval)
+ * - Resilience: Fails silently to console.warn to protect host app
+ * - Standard level mapping
+ */
+export declare class HorizonWinstonTransport extends Transport {
+    private apiKey;
+    private ingestUrl;
+    private batchSize;
+    private flushInterval;
+    private buffer;
+    private timer;
+    constructor(opts: HorizonWinstonOptions);
+    log(info: any, callback: () => void): void;
+    private flush;
+    /**
+     * Ensure pending logs are flushed on close/exit
+     */
+    close(): Promise<void>;
+}
+export {};

package/dist/winston-horizon.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HorizonWinstonTransport = void 0;
+const winston_transport_1 = __importDefault(require("winston-transport"));
+/**
+ * Winston Default Levels:
+ * error: 0, warn: 1, info: 2, http: 3, verbose: 4, debug: 5, silly: 6
+ */
+const WINSTON_LEVEL_MAP = {
+    error: 'error',
+    warn: 'warn',
+    info: 'info',
+    http: 'info',
+    verbose: 'debug',
+    debug: 'debug',
+    silly: 'debug',
+};
+/**
+ * Winston Transport for Horizon
+ *
+ * Integration:
+ * logger.add(new HorizonWinstonTransport({ apiKey: '...' }));
+ *
+ * Features:
+ * - Batched ingestion (batchSize, flushInterval)
+ * - Resilience: Fails silently to console.warn to protect host app
+ * - Standard level mapping
+ */
+class HorizonWinstonTransport extends winston_transport_1.default {
+    constructor(opts) {
+        super(opts);
+        this.buffer = [];
+        this.timer = null;
+        this.apiKey = opts.apiKey;
+        this.ingestUrl = opts.ingestUrl || 'https://horizon-api.bylinee.com/v1/ingest';
+        this.batchSize = opts.batchSize || 50;
+        this.flushInterval = opts.flushInterval || 2000;
+        if (!this.apiKey) {
+            throw new Error('Horizon API Key is required for Winston Transport');
+        }
+    }
+    log(info, callback) {
+        setImmediate(() => {
+            this.emit('logged', info);
+        });
+        const { level, message, ...metadata } = info;
+        this.buffer.push({
+            level: WINSTON_LEVEL_MAP[level] || 'info',
+            message: message || '',
+            metadata: metadata || {},
+            timestamp: new Date().toISOString(),
+        });
+        if (this.buffer.length >= this.batchSize) {
+            this.flush();
+        }
+        else if (!this.timer) {
+            this.timer = setTimeout(() => this.flush(), this.flushInterval);
+        }
+        callback();
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const payload = [...this.buffer];
+        this.buffer = [];
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        try {
+            const res = await fetch(this.ingestUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey,
+                },
+                body: JSON.stringify(payload),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: 'Unknown response' }));
+                console.warn(`[Horizon Winston] Ingestion failed (${res.status}):`, err.error);
+            }
+        }
+        catch (e) {
+            // Resilience: Fail silently to protect host application
+            console.warn('[Horizon Winston] Resilience Mode: Failed to reach Horizon server.', e instanceof Error ? e.message : e);
+        }
+    }
+    /**
+     * Ensure pending logs are flushed on close/exit
+     */
+    async close() {
+        await this.flush();
+    }
+}
+exports.HorizonWinstonTransport = HorizonWinstonTransport;

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@kisameholmes/horizon_node",
+    "version": "1.0.0",
+    "description": "High-performance observability and logging for Node.js",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "logging",
+        "tracing",
+        "monitoring",
+        "horizon",
+        "pino",
+        "winston"
+    ],
+    "author": "Horizon",
+    "license": "MIT",
+    "dependencies": {
+        "axios": "^1.6.0"
+    },
+    "peerDependencies": {
+        "express": "^4.18.0",
+        "fastify": "^4.20.0",
+        "pino": "^8.0.0",
+        "winston": "^3.0.0"
+    },
+    "peerDependenciesMeta": {
+        "express": {
+            "optional": true
+        },
+        "fastify": {
+            "optional": true
+        },
+        "pino": {
+            "optional": true
+        },
+        "winston": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@types/express": "^4.17.0",
+        "@types/node": "^20.0.0",
+        "fastify": "^4.0.0",
+        "pino": "^8.0.0",
+        "winston-transport": "^4.0.0",
+        "pino-abstract-transport": "^3.0.0",
+        "typescript": "^5.0.0"
+    }
+}