@fullevent/node 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,1096 @@
+import { Context, Next } from 'hono';
+import { Request, Response, NextFunction } from 'express';
+
+/**
+ * Configuration for tail-based sampling.
+ *
+ * @remarks
+ * Tail sampling makes the decision AFTER the request completes,
+ * allowing you to keep all errors and slow requests while sampling
+ * normal traffic. This gives you 100% visibility into problems.
+ *
+ * @example
+ * ```typescript
+ * const sampling: SamplingConfig = {
+ *   defaultRate: 0.1,            // Keep 10% of normal requests
+ *   alwaysKeepErrors: true,      // But 100% of errors
+ *   slowRequestThresholdMs: 500, // And anything slow
+ *   alwaysKeepPaths: ['/api/checkout', '/api/payment'],
+ *   alwaysKeepUsers: ['usr_vip_123'],
+ * };
+ * ```
+ *
+ * @category Middleware
+ */
+interface SamplingConfig {
+    /**
+     * Base sample rate for normal successful requests.
+     *
+     * @remarks
+     * Value between 0.0 and 1.0. For example, 0.1 means 10% of
+     * successful requests are kept.
+     *
+     * @defaultValue `1.0` (keep all)
+     */
+    defaultRate?: number;
+    /**
+     * Always keep error responses (4xx/5xx status codes).
+     *
+     * @remarks
+     * Highly recommended to leave enabled. Errors are rare and
+     * you want 100% visibility into failures.
+     *
+     * @defaultValue `true`
+     */
+    alwaysKeepErrors?: boolean;
+    /**
+     * Always keep requests slower than this threshold.
+     *
+     * @remarks
+     * Slow requests often indicate problems. This ensures you
+     * capture them even at low sample rates.
+     *
+     * @defaultValue `2000` (2 seconds)
+     */
+    slowRequestThresholdMs?: number;
+    /**
+     * Always keep requests matching these paths.
+     *
+     * @remarks
+     * Uses substring matching. Useful for critical paths like
+     * checkout, payment, or authentication.
+     *
+     * @example
+     * ```typescript
+     * alwaysKeepPaths: ['/api/checkout', '/api/payment', '/auth']
+     * ```
+     */
+    alwaysKeepPaths?: string[];
+    /**
+     * Always keep requests from these user IDs.
+     *
+     * @remarks
+     * Useful for debugging specific users or VIP accounts.
+     * Requires `user_id` to be set on the event.
+     *
+     * @example
+     * ```typescript
+     * alwaysKeepUsers: ['usr_vip_123', 'usr_debug_456']
+     * ```
+     */
+    alwaysKeepUsers?: string[];
+}
+/**
+ * Configuration for the wide logger middleware.
+ *
+ * @example Minimal Config
+ * ```typescript
+ * wideLogger({
+ *   apiKey: process.env.FULLEVENT_API_KEY!,
+ *   service: 'checkout-api',
+ * })
+ * ```
+ *
+ * @example Full Config
+ * ```typescript
+ * wideLogger({
+ *   apiKey: process.env.FULLEVENT_API_KEY!,
+ *   service: 'checkout-api',
+ *   environment: 'production',
+ *   region: 'us-east-1',
+ *   sampling: {
+ *     defaultRate: 0.1,
+ *     alwaysKeepErrors: true,
+ *     slowRequestThresholdMs: 500,
+ *   },
+ * })
+ * ```
+ *
+ * @category Middleware
+ */
+interface WideLoggerConfig {
+    /**
+     * Your FullEvent API key.
+     *
+     * @remarks
+     * Get this from your FullEvent dashboard under Project Settings → API Keys.
+     */
+    apiKey: string;
+    /**
+     * Service name to tag all events with.
+     *
+     * @remarks
+     * Used for filtering and grouping in the dashboard.
+     * Examples: 'checkout-api', 'user-service', 'payment-worker'
+     */
+    service: string;
+    /**
+     * Base URL for the FullEvent API.
+     *
+     * @defaultValue `'https://api.fullevent.io'`
+     *
+     * @remarks
+     * Only override for self-hosted deployments or local development.
+     */
+    baseUrl?: string;
+    /**
+     * Environment tag for all events.
+     *
+     * @defaultValue `process.env.NODE_ENV` or `'development'`
+     */
+    environment?: string;
+    /**
+     * Region tag for all events.
+     *
+     * @remarks
+     * Useful for multi-region deployments. Examples: 'us-east-1', 'eu-west-1'
+     */
+    region?: string;
+    /**
+     * Sampling configuration for tail-based sampling.
+     *
+     * @see {@link SamplingConfig}
+     */
+    sampling?: SamplingConfig;
+}
+/**
+ * Type for Hono context variables.
+ *
+ * @remarks
+ * Use this to type your Hono app for proper TypeScript support.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { wideLogger, WideEventVariables } from '@fullevent/node-sdk';
+ *
+ * const app = new Hono<{ Variables: WideEventVariables }>();
+ *
+ * app.use(wideLogger({ apiKey: '...', service: 'my-api' }));
+ *
+ * app.get('/', (c) => {
+ *   const event = c.get('wideEvent'); // Properly typed!
+ *   event.user_id = 'usr_123';
+ *   return c.text('Hello!');
+ * });
+ * ```
+ *
+ * @category Middleware
+ */
+type WideEventVariables = {
+    /** The wide event for the current request */
+    wideEvent: WideEvent;
+};
+/**
+ * Hono 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 `c.get('wideEvent')`
+ * 3. **Request End**: Middleware adds status/duration and sends to FullEvent
+ *
+ * ## Features
+ *
+ * - **Automatic context capture**: method, path, status, duration, errors
+ * - **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 Hono middleware function
+ *
+ * @example Quick Start
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { wideLogger, WideEventVariables } from '@fullevent/node-sdk';
+ *
+ * const app = new Hono<{ Variables: WideEventVariables }>();
+ *
+ * app.use(wideLogger({
+ *   apiKey: process.env.FULLEVENT_API_KEY!,
+ *   service: 'checkout-api',
+ * }));
+ * ```
+ *
+ * @example Enriching Events
+ * ```typescript
+ * app.post('/checkout', async (c) => {
+ *   const event = c.get('wideEvent');
+ *
+ *   // Add user context
+ *   event.user = {
+ *     id: user.id,
+ *     subscription: user.plan,
+ *     account_age_days: daysSince(user.createdAt),
+ *   };
+ *
+ *   // 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,
+ *   };
+ *
+ *   return c.json({ orderId: payment.orderId });
+ * });
+ * ```
+ *
+ * @example With Sampling
+ * ```typescript
+ * app.use(wideLogger({
+ *   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
+ *     alwaysKeepPaths: ['/api/checkout'], // Critical paths
+ *   },
+ * }));
+ * ```
+ *
+ * @category Middleware
+ */
+declare const wideLogger: (config: WideLoggerConfig) => (c: Context<{
+    Variables: WideEventVariables;
+}>, next: Next) => Promise<void>;
+
+declare global {
+    namespace Express {
+        interface Request {
+            /** The wide event for the current request */
+            wideEvent: WideEvent;
+        }
+    }
+}
+/**
+ * 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-sdk';
+ *
+ * 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
+ */
+declare function expressWideLogger(config: WideLoggerConfig): (req: Request, res: Response, next: NextFunction) => void;
+
+/**
+ * Configuration options for the FullEvent client.
+ *
+ * @example
+ * ```typescript
+ * const client = new FullEvent({
+ *   apiKey: process.env.FULLEVENT_API_KEY!,
+ *   baseUrl: 'https://api.fullevent.io', // optional
+ *   ping: true, // send a test ping on initialization
+ * });
+ * ```
+ *
+ * @category Client
+ */
+interface FullEventConfig {
+    /**
+     * Your FullEvent project API key.
+     *
+     * @remarks
+     * Get this from your FullEvent dashboard under Project Settings → API Keys.
+     */
+    apiKey: string;
+    /**
+     * Base URL for the FullEvent API.
+     *
+     * @defaultValue `'https://api.fullevent.io'`
+     *
+     * @remarks
+     * Only override this for self-hosted deployments or local development.
+     */
+    baseUrl?: string;
+    /**
+     * Send a ping event on initialization to verify connection.
+     *
+     * @defaultValue `false`
+     *
+     * @remarks
+     * Set to `true` during initial setup to verify your SDK configuration
+     * is working correctly. The ping is sent asynchronously and won't block
+     * your application startup.
+     */
+    ping?: boolean;
+}
+/**
+ * Standard properties for HTTP request events.
+ *
+ * These properties are automatically extracted by FullEvent for first-class
+ * filtering, dashboards, and error rate calculations.
+ *
+ * @example
+ * ```typescript
+ * const props: HttpRequestProperties = {
+ *   status_code: 200,
+ *   method: 'POST',
+ *   path: '/api/checkout',
+ *   duration_ms: 234,
+ *   outcome: 'success',
+ *   // Plus any custom properties
+ *   user_id: 'usr_123',
+ *   order_total: 9999,
+ * };
+ * ```
+ *
+ * @category Client
+ */
+interface HttpRequestProperties {
+    /**
+     * HTTP status code (e.g., 200, 404, 500).
+     *
+     * @remarks
+     * Used for automatic error rate calculations:
+     * - `< 400` = success
+     * - `>= 400` = error
+     */
+    status_code: number;
+    /**
+     * HTTP method (GET, POST, PUT, DELETE, etc.)
+     */
+    method?: string;
+    /**
+     * Request path (e.g., `/api/users`, `/checkout`)
+     */
+    path?: string;
+    /**
+     * Request duration in milliseconds.
+     */
+    duration_ms?: number;
+    /**
+     * Explicit success/error indicator.
+     *
+     * @remarks
+     * If set, this takes precedence over `status_code` for error rate calculations.
+     */
+    outcome?: 'success' | 'error';
+    /**
+     * Additional custom properties.
+     *
+     * @remarks
+     * Add any context relevant to your application.
+     */
+    [key: string]: unknown;
+}
+/**
+ * The main FullEvent client for ingesting events.
+ *
+ * @remarks
+ * Use this client to send events directly from your application.
+ * For automatic request logging, see the middleware integrations:
+ * - {@link wideLogger} for Hono
+ * - {@link expressWideLogger} for Express
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { FullEvent } from '@fullevent/node-sdk';
+ *
+ * const client = new FullEvent({
+ *   apiKey: process.env.FULLEVENT_API_KEY!,
+ * });
+ *
+ * // Ingest a simple event
+ * await client.ingest('user.signup', {
+ *   plan: 'pro',
+ *   referral: 'newsletter',
+ * });
+ * ```
+ *
+ * @example Fire and Forget
+ * ```typescript
+ * // Don't await if you don't want to block
+ * client.ingest('page.view', { path: '/home' })
+ *   .catch(err => console.error('FullEvent error:', err));
+ * ```
+ *
+ * @category Client
+ */
+declare class FullEvent {
+    private apiKey;
+    private baseUrl;
+    /**
+     * Creates a new FullEvent client instance.
+     *
+     * @param config - Configuration options
+     */
+    constructor(config: FullEventConfig);
+    /**
+     * Ingest a generic event with any properties.
+     *
+     * @param event - Event name/type (e.g., 'user.signup', 'order.completed')
+     * @param properties - Key-value pairs of event data
+     * @param timestamp - Optional ISO timestamp (defaults to now)
+     * @returns Promise resolving to success/error status
+     *
+     * @remarks
+     * Events are processed asynchronously. The promise resolves when
+     * the event is accepted by the API, not when it's fully processed.
+     *
+     * @example
+     * ```typescript
+     * await client.ingest('checkout.completed', {
+     *   order_id: 'ord_123',
+     *   total_cents: 9999,
+     *   items: 3,
+     *   user: {
+     *     id: 'usr_456',
+     *     plan: 'premium',
+     *   },
+     * });
+     * ```
+     */
+    ingest(event: string, properties?: Record<string, unknown>, timestamp?: string): Promise<{
+        success: boolean;
+        error?: unknown;
+    }>;
+    /**
+     * Ingest an HTTP request event with typed properties.
+     *
+     * @param properties - HTTP request properties with optional custom data
+     * @param timestamp - Optional ISO timestamp (defaults to now)
+     * @returns Promise resolving to success/error status
+     *
+     * @remarks
+     * This is a convenience method that provides TypeScript autocomplete
+     * for standard HTTP properties. Under the hood, it calls `ingest()`
+     * with the event type `'http_request'`.
+     *
+     * @example
+     * ```typescript
+     * await client.ingestHttpRequest({
+     *   status_code: 200,
+     *   method: 'POST',
+     *   path: '/api/checkout',
+     *   duration_ms: 234,
+     *   outcome: 'success',
+     *   // Custom properties
+     *   user_id: 'usr_123',
+     * });
+     * ```
+     */
+    ingestHttpRequest(properties: HttpRequestProperties, timestamp?: string): Promise<{
+        success: boolean;
+        error?: unknown;
+    }>;
+    /**
+     * Ping the FullEvent API to verify connection.
+     *
+     * @returns Promise resolving to connection status with latency
+     *
+     * @remarks
+     * Use this method to verify your SDK is correctly configured.
+     * It sends a lightweight ping event and measures round-trip latency.
+     * Commonly used during setup or in health check endpoints.
+     *
+     * @example Basic ping
+     * ```typescript
+     * const result = await client.ping();
+     * if (result.success) {
+     *   console.log(`Connected! Latency: ${result.latency_ms}ms`);
+     * } else {
+     *   console.error('Connection failed:', result.error);
+     * }
+     * ```
+     *
+     * @example Health check endpoint
+     * ```typescript
+     * app.get('/health', async (c) => {
+     *   const ping = await fullevent.ping();
+     *   return c.json({
+     *     status: ping.success ? 'healthy' : 'degraded',
+     *     fullevent: ping,
+     *   });
+     * });
+     * ```
+     */
+    ping(): Promise<{
+        success: boolean;
+        latency_ms?: number;
+        error?: unknown;
+    }>;
+}
+
+/**
+ * A fluent builder for enriching wide events throughout the request lifecycle.
+ *
+ * @remarks
+ * While you can modify the event object directly (and that's perfectly fine),
+ * the builder provides chainable methods for cleaner code and useful helpers.
+ *
+ * ## Two Approaches
+ *
+ * **Direct access (simple):**
+ * ```typescript
+ * const event = c.get('wideEvent');
+ * event.user = { id: user.id, plan: user.plan };
+ * event.cart = { total: cart.total, items: cart.items.length };
+ * ```
+ *
+ * **Builder pattern (chainable):**
+ * ```typescript
+ * new WideEventBuilder(c.get('wideEvent'))
+ *   .setContext('user', { id: user.id, plan: user.plan })
+ *   .setContext('cart', { total: cart.total, items: cart.items.length })
+ *   .setTiming('db_latency_ms', dbStart);
+ * ```
+ *
+ * @example Full Example
+ * ```typescript
+ * const builder = new WideEventBuilder(c.get('wideEvent'));
+ *
+ * builder
+ *   .setUser(user.id)
+ *   .setContext('user', {
+ *     subscription: user.plan,
+ *     account_age_days: daysSince(user.createdAt),
+ *     lifetime_value_cents: user.ltv,
+ *   })
+ *   .setContext('cart', {
+ *     id: cart.id,
+ *     item_count: cart.items.length,
+ *     total_cents: cart.total,
+ *   });
+ *
+ * // Later, after payment processing
+ * builder
+ *   .setContext('payment', { method: 'card', provider: 'stripe' })
+ *   .setTiming('payment_latency_ms', paymentStart);
+ *
+ * if (paymentError) {
+ *   builder.setError({
+ *     type: 'PaymentError',
+ *     code: paymentError.code,
+ *     message: paymentError.message,
+ *     stripe_decline_code: paymentError.declineCode,
+ *   });
+ * }
+ * ```
+ *
+ * @category Builder
+ */
+declare class WideEventBuilder {
+    private event;
+    /**
+     * Creates a new builder wrapping the given event.
+     *
+     * @param event - The wide event to enrich
+     */
+    constructor(event: WideEvent);
+    /**
+     * Returns the underlying event object for direct access.
+     *
+     * @returns The wrapped WideEvent
+     *
+     * @example
+     * ```typescript
+     * const event = builder.getEvent();
+     * console.log(event.user_id);
+     * ```
+     */
+    getEvent(): WideEvent;
+    /**
+     * Sets any key-value pair on the event.
+     *
+     * @param key - Property name
+     * @param value - Property value (any type)
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder
+     *   .set('order_id', 'ord_123')
+     *   .set('llm_model', 'gpt-4')
+     *   .set('tokens_used', 1500);
+     * ```
+     */
+    set(key: string, value: unknown): this;
+    /**
+     * Sets a named context object on the event.
+     *
+     * @remarks
+     * This is the primary method for adding structured business context.
+     * Each context is a nested object that groups related properties.
+     *
+     * @param name - Context name (e.g., 'user', 'cart', 'payment')
+     * @param data - Context data as key-value pairs
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder
+     *   .setContext('user', {
+     *     id: 'user_456',
+     *     subscription: 'premium',
+     *     account_age_days: 847,
+     *   })
+     *   .setContext('cart', {
+     *     id: 'cart_xyz',
+     *     item_count: 3,
+     *     total_cents: 15999,
+     *   })
+     *   .setContext('payment', {
+     *     method: 'card',
+     *     provider: 'stripe',
+     *   });
+     * ```
+     */
+    setContext(name: string, data: Record<string, unknown>): this;
+    /**
+     * Merges additional fields into an existing context object.
+     *
+     * @remarks
+     * Useful for progressively building context throughout the request.
+     * If the context doesn't exist, it will be created.
+     *
+     * @param name - Context name to merge into
+     * @param data - Additional data to merge
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * // Initial payment context
+     * builder.setContext('payment', { method: 'card', provider: 'stripe' });
+     *
+     * // After payment completes, add timing
+     * builder.mergeContext('payment', {
+     *   latency_ms: Date.now() - paymentStart,
+     *   attempt: 1,
+     *   transaction_id: 'txn_123',
+     * });
+     *
+     * // Result: { method, provider, latency_ms, attempt, transaction_id }
+     * ```
+     */
+    mergeContext(name: string, data: Record<string, unknown>): this;
+    /**
+     * Sets the user ID on the event.
+     *
+     * @remarks
+     * This sets the top-level `user_id` field, which is commonly used
+     * for filtering and user-centric analytics. For richer user context,
+     * use `setContext('user', {...})` instead or in addition.
+     *
+     * @param userId - The user identifier
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setUser('usr_123');
+     *
+     * // For richer context, also set a user object:
+     * builder.setContext('user', {
+     *   id: 'usr_123',
+     *   plan: 'premium',
+     *   ltv_cents: 50000,
+     * });
+     * ```
+     */
+    setUser(userId: string): this;
+    /**
+     * Captures an error with structured details.
+     *
+     * @remarks
+     * Automatically sets `outcome` to 'error'. Accepts either a native
+     * Error object or a custom error object with additional fields.
+     *
+     * @param err - Error object or custom error details
+     * @returns `this` for chaining
+     *
+     * @example Native Error
+     * ```typescript
+     * try {
+     *   await riskyOperation();
+     * } catch (err) {
+     *   builder.setError(err);
+     * }
+     * ```
+     *
+     * @example Custom Error with Context
+     * ```typescript
+     * builder.setError({
+     *   type: 'PaymentError',
+     *   message: 'Card declined by issuer',
+     *   code: 'card_declined',
+     *   stripe_decline_code: 'insufficient_funds',
+     *   card_brand: 'visa',
+     *   card_last4: '4242',
+     * });
+     * ```
+     */
+    setError(err: Error | {
+        type?: string;
+        message: string;
+        code?: string;
+        stack?: string;
+        [key: string]: unknown;
+    }): this;
+    /**
+     * Sets the HTTP status code and outcome.
+     *
+     * @remarks
+     * Automatically sets `outcome` based on the status code:
+     * - `< 400` → 'success'
+     * - `>= 400` → 'error'
+     *
+     * @param code - HTTP status code
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setStatus(404); // outcome = 'error'
+     * builder.setStatus(200); // outcome = 'success'
+     * ```
+     */
+    setStatus(code: number): this;
+    /**
+     * Records timing for a specific operation.
+     *
+     * @remarks
+     * A convenience method for calculating and setting duration values.
+     * The value is calculated as `Date.now() - startTime`.
+     *
+     * @param key - Property name for the timing (e.g., 'db_latency_ms')
+     * @param startTime - Start timestamp from `Date.now()`
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * const dbStart = Date.now();
+     * const result = await db.query('SELECT ...');
+     * builder.setTiming('db_latency_ms', dbStart);
+     *
+     * const paymentStart = Date.now();
+     * await processPayment();
+     * builder.setTiming('payment_latency_ms', paymentStart);
+     * ```
+     */
+    setTiming(key: string, startTime: number): this;
+}
+
+/**
+ * @packageDocumentation
+ *
+ * # FullEvent Node.js SDK
+ *
+ * The official Node.js SDK for FullEvent - the wide event analytics platform.
+ *
+ * ## Installation
+ *
+ * ```bash
+ * npm install @fullevent/node-sdk
+ * ```
+ *
+ * ## Quick Start
+ *
+ * ### Direct Event Ingestion
+ *
+ * ```typescript
+ * import { FullEvent } from '@fullevent/node-sdk';
+ *
+ * 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-sdk';
+ *
+ * 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-sdk
+ */
+
+/**
+ * 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
+ */
+interface WideEvent {
+    /**
+     * 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';
+    /**
+     * 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;
+    /**
+     * User identifier.
+     *
+     * @remarks
+     * The most commonly enriched field. For richer user context,
+     * add a `user` object with additional properties.
+     */
+    user_id?: string;
+    /**
+     * 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;
+    };
+    /**
+     * 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;
+}
+
+export { FullEvent, type FullEventConfig, type HttpRequestProperties, type SamplingConfig, type WideEvent, WideEventBuilder, type WideEventVariables, type WideLoggerConfig, expressWideLogger, wideLogger };