@fullevent/node 0.0.1

package/src/index.ts

@@ -0,0 +1,272 @@
+/**
+ * @packageDocumentation
+ * 
+ * # FullEvent Node.js SDK
+ * 
+ * The official Node.js SDK for FullEvent - the wide event analytics platform.
+ * 
+ * ## Installation
+ * 
+ * ```bash
+ * npm install @fullevent/node
+ * ```
+ * 
+ * ## Quick Start
+ * 
+ * ### Direct Event Ingestion
+ * 
+ * ```typescript
+ * import { FullEvent } from '@fullevent/node';
+ * 
+ * const client = new FullEvent({
+ *   apiKey: process.env.FULLEVENT_API_KEY!,
+ * });
+ * 
+ * await client.ingest('user.signup', { plan: 'pro' });
+ * ```
+ * 
+ * ### Wide Event Middleware (Recommended)
+ * 
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { wideLogger, WideEventVariables } from '@fullevent/node';
+ * 
+ * const app = new Hono<{ Variables: WideEventVariables }>();
+ * 
+ * app.use(wideLogger({
+ *   apiKey: process.env.FULLEVENT_API_KEY!,
+ *   service: 'my-api',
+ * }));
+ * 
+ * app.post('/checkout', async (c) => {
+ *   const event = c.get('wideEvent');
+ *   event.user = { id: user.id, plan: user.plan };
+ *   event.cart = { total_cents: cart.total, items: cart.items.length };
+ *   return c.json({ success: true });
+ * });
+ * ```
+ * 
+ * @module @fullevent/node
+ */
+
+export * from './middleware/hono';
+export * from './middleware/express';
+export * from './client';
+export * from './builder';
+
+/**
+ * A Wide Event captures the complete context of a request in a single,
+ * self-describing record.
+ * 
+ * @remarks
+ * Instead of emitting many small logs, you build one rich event throughout
+ * the request lifecycle and emit it at the end. This makes debugging and
+ * analytics significantly easier.
+ * 
+ * ## The Wide Event Pattern
+ * 
+ * 1. **Initialize**: Middleware creates the event with request context
+ * 2. **Enrich**: Handlers add business context throughout the request
+ * 3. **Emit**: Middleware sends the complete event when the request ends
+ * 
+ * ## Auto-Captured Fields
+ * 
+ * The middleware automatically captures:
+ * - `request_id`, `trace_id` - For distributed tracing
+ * - `timestamp` - When the request started
+ * - `method`, `path` - HTTP method and path
+ * - `status_code` - HTTP response status
+ * - `duration_ms` - Total request duration
+ * - `outcome` - 'success' or 'error'
+ * - `service`, `environment`, `region` - Infrastructure context
+ * 
+ * ## Your Business Context
+ * 
+ * Add any fields your application needs:
+ * 
+ * ```typescript
+ * event.user = { id: 'usr_123', plan: 'premium', ltv_cents: 50000 };
+ * event.cart = { id: 'cart_xyz', items: 3, total_cents: 15999 };
+ * event.payment = { provider: 'stripe', method: 'card', latency_ms: 234 };
+ * event.feature_flags = { new_checkout: true };
+ * event.experiment = { name: 'pricing_v2', variant: 'control' };
+ * ```
+ * 
+ * @example Basic Wide Event
+ * ```typescript
+ * const event: WideEvent = {
+ *   // Auto-captured by middleware
+ *   request_id: 'req_abc123',
+ *   timestamp: '2024-01-15T10:23:45.612Z',
+ *   method: 'POST',
+ *   path: '/api/checkout',
+ *   service: 'checkout-api',
+ *   status_code: 200,
+ *   duration_ms: 847,
+ *   outcome: 'success',
+ *   
+ *   // Your business context
+ *   user: { id: 'usr_456', plan: 'premium' },
+ *   cart: { total_cents: 15999, items: 3 },
+ *   payment: { provider: 'stripe', latency_ms: 234 },
+ * };
+ * ```
+ * 
+ * @category Types
+ */
+export interface WideEvent {
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Core Request Context (auto-populated by middleware)
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Unique identifier for this request.
+     * 
+     * @remarks
+     * Auto-generated or extracted from `x-request-id` / `x-fullevent-trace-id` headers.
+     */
+    request_id?: string;
+
+    /**
+     * Trace ID for distributed tracing.
+     * 
+     * @remarks
+     * Propagated across service boundaries via the `x-fullevent-trace-id` header.
+     * Same as `request_id` by default.
+     * 
+     * @see {@link https://fullevent.io/docs/distributed-tracing | Distributed Tracing Guide}
+     */
+    trace_id?: string;
+
+    /**
+     * ISO timestamp when the request started.
+     */
+    timestamp: string;
+
+    /**
+     * HTTP method (GET, POST, PUT, DELETE, etc.)
+     */
+    method: string;
+
+    /**
+     * Request path (e.g., `/api/checkout`)
+     */
+    path: string;
+
+    /**
+     * HTTP status code.
+     * 
+     * @remarks
+     * Auto-captured from the response. Used for error rate calculations.
+     */
+    status_code?: number;
+
+    /**
+     * Request duration in milliseconds.
+     * 
+     * @remarks
+     * Auto-captured by middleware in the `finally` block.
+     */
+    duration_ms?: number;
+
+    /**
+     * Request outcome: 'success' or 'error'.
+     * 
+     * @remarks
+     * Auto-set based on `status_code` (>= 400 = error).
+     * Can be overridden manually.
+     */
+    outcome?: 'success' | 'error';
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Infrastructure Context
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Service name (e.g., 'checkout-api', 'user-service').
+     * 
+     * @remarks
+     * Set via middleware config. Used for filtering and grouping.
+     */
+    service: string;
+
+    /**
+     * Deployment region (e.g., 'us-east-1', 'eu-west-1').
+     */
+    region?: string;
+
+    /**
+     * Environment (e.g., 'production', 'staging', 'development').
+     * 
+     * @remarks
+     * Defaults to `NODE_ENV` if not specified.
+     */
+    environment?: string;
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Common Context Fields
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * User identifier.
+     * 
+     * @remarks
+     * The most commonly enriched field. For richer user context,
+     * add a `user` object with additional properties.
+     */
+    user_id?: string;
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Error Details
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Structured error information.
+     * 
+     * @remarks
+     * Auto-populated when an exception is thrown. Can also be set manually
+     * for handled errors (e.g., payment failures).
+     * 
+     * @example
+     * ```typescript
+     * event.error = {
+     *   type: 'PaymentError',
+     *   code: 'card_declined',
+     *   message: 'Your card was declined',
+     *   stripe_decline_code: 'insufficient_funds',
+     * };
+     * ```
+     */
+    error?: {
+        /** Error class/type name (e.g., 'TypeError', 'PaymentError') */
+        type: string;
+        /** Human-readable error message */
+        message: string;
+        /** Stack trace (auto-captured for thrown errors) */
+        stack?: string;
+        /** Error code (e.g., 'ECONNREFUSED', 'card_declined') */
+        code?: string;
+        /** Additional error context */
+        [key: string]: unknown;
+    };
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Your Business Context
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * Dynamic business context.
+     * 
+     * @remarks
+     * Add any fields your application needs. Common patterns:
+     * 
+     * - `user` - User context (id, plan, ltv, etc.)
+     * - `cart` - Shopping cart (id, items, total, coupon)
+     * - `payment` - Payment details (provider, method, latency)
+     * - `order` - Order details (id, status, items)
+     * - `feature_flags` - Feature flag states
+     * - `experiment` - A/B test assignments
+     * - `llm` - LLM usage (model, tokens, latency)
+     */
+    [key: string]: unknown;
+}

package/src/middleware/express.ts

@@ -0,0 +1,193 @@
+import { Request, Response, NextFunction } from 'express';
+import { WideEvent } from '../index';
+import { FullEvent } from '../client';
+import { SamplingConfig, WideLoggerConfig } from './hono';
+
+// Extend Express Request to include wideEvent
+declare global {
+    namespace Express {
+        interface Request {
+            /** The wide event for the current request */
+            wideEvent: WideEvent;
+        }
+    }
+}
+
+/**
+ * Determines whether to keep this event based on sampling config.
+ * Uses tail-based sampling: decision made AFTER request completes.
+ * 
+ * @internal
+ */
+function shouldSample(event: WideEvent, config?: SamplingConfig): boolean {
+    const sampling = config ?? {};
+    const defaultRate = sampling.defaultRate ?? 1.0;
+    const alwaysKeepErrors = sampling.alwaysKeepErrors ?? true;
+    const slowThreshold = sampling.slowRequestThresholdMs ?? 2000;
+
+    // Always keep errors (4xx/5xx or explicit error outcome)
+    if (alwaysKeepErrors) {
+        if (event.outcome === 'error') return true;
+        if (event.status_code && event.status_code >= 400) return true;
+    }
+
+    // Always keep slow requests
+    if (event.duration_ms && event.duration_ms > slowThreshold) return true;
+
+    // Always keep specific paths
+    if (sampling.alwaysKeepPaths?.some(p => event.path.includes(p))) return true;
+
+    // Always keep specific users
+    if (event.user_id && sampling.alwaysKeepUsers?.includes(String(event.user_id))) return true;
+
+    // Consistent Sampling based on Trace ID
+    // DJB2 hash for simple, string-based consistency
+    if (event.trace_id) {
+        let hash = 5381;
+        const str = event.trace_id;
+        for (let i = 0; i < str.length; i++) {
+            hash = ((hash << 5) + hash) + str.charCodeAt(i);
+        }
+        // Normalize to 0.0 - 1.0 (using 10000 for 4 decimal precision)
+        const normalized = (hash >>> 0) % 10000 / 10000;
+        return normalized < defaultRate;
+    }
+
+    // Fallback if no trace ID (shouldn't happen usually)
+    return Math.random() < defaultRate;
+}
+
+/**
+ * Express middleware for Wide Event logging.
+ * 
+ * @remarks
+ * Creates a single, rich event per request that captures the complete context.
+ * The event is initialized with request data and automatically finalized with
+ * status, duration, and outcome. Your handlers enrich it with business context.
+ * 
+ * ## How It Works
+ * 
+ * 1. **Request Start**: Middleware creates the event with request context
+ * 2. **Handler Runs**: Your code enriches the event via `req.wideEvent`
+ * 3. **Response Finish**: Middleware adds status/duration and sends to FullEvent
+ * 
+ * ## Features
+ * 
+ * - **Automatic context capture**: method, path, status, duration
+ * - **Distributed tracing**: Propagates `x-fullevent-trace-id` headers
+ * - **Tail-based sampling**: 100% error visibility at any sample rate
+ * - **Fire and forget**: Non-blocking, won't slow down your responses
+ * 
+ * @param config - Middleware configuration
+ * @returns Express middleware function
+ * 
+ * @example Quick Start
+ * ```typescript
+ * import express from 'express';
+ * import { expressWideLogger } from '@fullevent/node';
+ * 
+ * const app = express();
+ * 
+ * app.use(expressWideLogger({
+ *   apiKey: process.env.FULLEVENT_API_KEY!,
+ *   service: 'checkout-api',
+ * }));
+ * ```
+ * 
+ * @example Enriching Events
+ * ```typescript
+ * app.post('/checkout', async (req, res) => {
+ *   const event = req.wideEvent;
+ *   
+ *   // Add user context
+ *   event.user = {
+ *     id: req.user.id,
+ *     subscription: req.user.plan,
+ *   };
+ *   
+ *   // Add cart context
+ *   event.cart = {
+ *     id: cart.id,
+ *     item_count: cart.items.length,
+ *     total_cents: cart.total,
+ *   };
+ *   
+ *   // Add payment timing
+ *   const paymentStart = Date.now();
+ *   const payment = await processPayment(cart);
+ *   event.payment = {
+ *     provider: 'stripe',
+ *     latency_ms: Date.now() - paymentStart,
+ *   };
+ *   
+ *   res.json({ orderId: payment.orderId });
+ * });
+ * ```
+ * 
+ * @example With Sampling
+ * ```typescript
+ * app.use(expressWideLogger({
+ *   apiKey: process.env.FULLEVENT_API_KEY!,
+ *   service: 'checkout-api',
+ *   sampling: {
+ *     defaultRate: 0.1,           // 10% of normal traffic
+ *     alwaysKeepErrors: true,     // 100% of errors
+ *     slowRequestThresholdMs: 500, // Slow requests
+ *   },
+ * }));
+ * ```
+ * 
+ * @category Middleware
+ */
+export function expressWideLogger(config: WideLoggerConfig) {
+    const client = new FullEvent({
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+    });
+
+    return (req: Request, res: Response, next: NextFunction) => {
+        const startTime = Date.now();
+
+        // Distributed Tracing: Use existing trace ID or generate a new one
+        const requestId = (req.headers['x-fullevent-trace-id'] as string)
+            || (req.headers['x-request-id'] as string)
+            || crypto.randomUUID();
+
+        // Initialize the Wide Event with request context
+        const event: WideEvent = {
+            request_id: requestId,
+            timestamp: new Date().toISOString(),
+            method: req.method,
+            path: req.path,
+            service: config.service,
+            environment: config.environment || process.env.NODE_ENV || 'development',
+            region: config.region,
+        };
+
+        // Make the event accessible to handlers for enrichment
+        req.wideEvent = event;
+
+        // Propagate the trace ID in response headers
+        res.setHeader('x-fullevent-trace-id', requestId);
+
+        // Capture response finish to record status and send event
+        res.on('finish', () => {
+            event.status_code = res.statusCode;
+            event.outcome = res.statusCode >= 400 ? 'error' : 'success';
+            event.duration_ms = Date.now() - startTime;
+
+            // Only send if we have an API key and event passes sampling
+            if (config.apiKey && shouldSample(event, config.sampling)) {
+                client.ingest(
+                    `${event.method} ${event.path}`,
+                    event,
+                    event.timestamp
+                ).catch(err => {
+                    console.error('[FullEvent] Failed to send event:', err);
+                });
+            }
+        });
+
+        next();
+    };
+}