@fullevent/node 0.0.1

package/src/builder.ts

@@ -0,0 +1,307 @@
+import { WideEvent } from './index';
+
+/**
+ * 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
+ */
+export class WideEventBuilder {
+    /**
+     * Creates a new builder wrapping the given event.
+     * 
+     * @param event - The wide event to enrich
+     */
+    constructor(private 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 {
+        return this.event;
+    }
+
+    /**
+     * 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 {
+        this.event[key] = value;
+        return 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 {
+        this.event[name] = data;
+        return 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 {
+        const existing = this.event[name];
+        if (existing && typeof existing === 'object' && !Array.isArray(existing)) {
+            this.event[name] = { ...(existing as Record<string, unknown>), ...data };
+        } else {
+            this.event[name] = data;
+        }
+        return 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 {
+        this.event.user_id = userId;
+        return 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 {
+        this.event.outcome = 'error';
+
+        if (err instanceof Error) {
+            this.event.error = {
+                type: err.name,
+                message: err.message,
+                stack: err.stack,
+            };
+        } else {
+            const { type, message, code, stack, ...extra } = err;
+            this.event.error = {
+                type: type || 'Error',
+                message,
+                code,
+                stack,
+                ...extra,
+            };
+        }
+        return 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 {
+        this.event.status_code = code;
+        this.event.outcome = code >= 400 ? 'error' : 'success';
+        return 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 {
+        this.event[key] = Date.now() - startTime;
+        return this;
+    }
+}

package/src/client.ts

@@ -0,0 +1,325 @@
+import { WideEvent } from './index';
+
+/**
+ * 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
+ */
+export 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
+ */
+export 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';
+ * 
+ * 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
+ */
+export class FullEvent {
+    private apiKey: string;
+    private baseUrl: string;
+
+    /**
+     * Creates a new FullEvent client instance.
+     * 
+     * @param config - Configuration options
+     */
+    constructor(config: FullEventConfig) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl || 'https://api.fullevent.io';
+
+        // Auto-ping if enabled
+        if (config.ping) {
+            this.ping().catch((err) => {
+                console.error('[FullEvent SDK] Auto-ping failed:', err);
+            });
+        }
+    }
+
+    /**
+     * 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',
+     *   },
+     * });
+     * ```
+     */
+    async ingest(
+        event: string,
+        properties: Record<string, unknown> = {},
+        timestamp?: string
+    ): Promise<{ success: boolean; error?: unknown }> {
+        try {
+            const response = await fetch(`${this.baseUrl}/ingest`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({
+                    event,
+                    properties,
+                    timestamp: timestamp || new Date().toISOString(),
+                }),
+            });
+
+            if (!response.ok) {
+                const error = await response.json();
+                console.error('[FullEvent SDK] Ingestion failed:', error);
+                return { success: false, error };
+            }
+
+            return { success: true };
+        } catch (error) {
+            console.error('[FullEvent SDK] Network error during ingestion:', error);
+            return { success: false, error };
+        }
+    }
+
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    async ingestHttpRequest(
+        properties: HttpRequestProperties,
+        timestamp?: string
+    ): Promise<{ success: boolean; error?: unknown }> {
+        return this.ingest('http_request', properties, timestamp);
+    }
+
+    /**
+     * 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,
+     *   });
+     * });
+     * ```
+     */
+    async ping(): Promise<{ success: boolean; latency_ms?: number; error?: unknown }> {
+        const start = Date.now();
+
+        try {
+            const result = await this.ingest('fullevent.ping', {
+                // Standard wide event properties
+                status_code: 200,
+                outcome: 'success',
+                duration_ms: 0, // Will be updated after
+
+                // SDK info
+                sdk: '@fullevent/node',
+                sdk_version: '1.0.0',
+
+                // Runtime info
+                runtime: typeof process !== 'undefined' ? 'node' : 'browser',
+                node_version: typeof process !== 'undefined' ? process.version : undefined,
+                platform: typeof process !== 'undefined' ? process.platform : 'browser',
+
+                // Ping metadata
+                ping_type: 'connection_test',
+                message: '🎉 Your first event! FullEvent is connected and ready.',
+            });
+
+            const latency_ms = Date.now() - start;
+
+            if (result.success) {
+                return { success: true, latency_ms };
+            } else {
+                return { success: false, latency_ms, error: result.error };
+            }
+        } catch (error) {
+            const latency_ms = Date.now() - start;
+            return { success: false, latency_ms, error };
+        }
+    }
+}
+