@fullevent/node 0.0.1

package/dist/index.mjs

@@ -0,0 +1,543 @@
+// src/client.ts
+var FullEvent = class {
+  /**
+   * Creates a new FullEvent client instance.
+   * 
+   * @param config - Configuration options
+   */
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || "https://api.fullevent.io";
+    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, properties = {}, timestamp) {
+    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 || (/* @__PURE__ */ 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, timestamp) {
+    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() {
+    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",
+        sdk_version: "1.0.0",
+        // Runtime info
+        runtime: typeof process !== "undefined" ? "node" : "browser",
+        node_version: typeof process !== "undefined" ? process.version : void 0,
+        platform: typeof process !== "undefined" ? process.platform : "browser",
+        // Ping metadata
+        ping_type: "connection_test",
+        message: "\u{1F389} 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 };
+    }
+  }
+};
+
+// src/middleware/hono.ts
+function shouldSample(event, config) {
+  const sampling = config ?? {};
+  const defaultRate = sampling.defaultRate ?? 1;
+  const alwaysKeepErrors = sampling.alwaysKeepErrors ?? true;
+  const slowThreshold = sampling.slowRequestThresholdMs ?? 2e3;
+  if (alwaysKeepErrors) {
+    if (event.outcome === "error") return true;
+    if (event.status_code && event.status_code >= 400) return true;
+  }
+  if (event.duration_ms && event.duration_ms > slowThreshold) return true;
+  if (sampling.alwaysKeepPaths?.some((p) => event.path.includes(p))) return true;
+  if (event.user_id && sampling.alwaysKeepUsers?.includes(String(event.user_id))) return true;
+  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);
+    }
+    const normalized = (hash >>> 0) % 1e4 / 1e4;
+    return normalized < defaultRate;
+  }
+  return Math.random() < defaultRate;
+}
+var wideLogger = (config) => {
+  const client = new FullEvent({
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl
+  });
+  return async (c, next) => {
+    const startTime = Date.now();
+    const requestId = c.req.header("x-fullevent-trace-id") || c.req.header("x-request-id") || crypto.randomUUID();
+    const event = {
+      request_id: requestId,
+      trace_id: requestId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      method: c.req.method,
+      path: c.req.path,
+      service: config.service,
+      environment: config.environment || process.env.NODE_ENV || "development",
+      region: config.region
+    };
+    c.set("wideEvent", event);
+    c.res.headers.set("x-fullevent-trace-id", requestId);
+    try {
+      await next();
+      event.status_code = c.res.status;
+      event.outcome = c.res.status >= 400 ? "error" : "success";
+    } catch (err) {
+      event.status_code = 500;
+      event.outcome = "error";
+      if (err instanceof Error) {
+        event.error = {
+          type: err.name || "Error",
+          message: err.message || String(err),
+          stack: err.stack
+        };
+      } else {
+        event.error = {
+          type: "Error",
+          message: String(err)
+        };
+      }
+      throw err;
+    } finally {
+      event.duration_ms = Date.now() - startTime;
+      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);
+        });
+      }
+    }
+  };
+};
+
+// src/middleware/express.ts
+function shouldSample2(event, config) {
+  const sampling = config ?? {};
+  const defaultRate = sampling.defaultRate ?? 1;
+  const alwaysKeepErrors = sampling.alwaysKeepErrors ?? true;
+  const slowThreshold = sampling.slowRequestThresholdMs ?? 2e3;
+  if (alwaysKeepErrors) {
+    if (event.outcome === "error") return true;
+    if (event.status_code && event.status_code >= 400) return true;
+  }
+  if (event.duration_ms && event.duration_ms > slowThreshold) return true;
+  if (sampling.alwaysKeepPaths?.some((p) => event.path.includes(p))) return true;
+  if (event.user_id && sampling.alwaysKeepUsers?.includes(String(event.user_id))) return true;
+  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);
+    }
+    const normalized = (hash >>> 0) % 1e4 / 1e4;
+    return normalized < defaultRate;
+  }
+  return Math.random() < defaultRate;
+}
+function expressWideLogger(config) {
+  const client = new FullEvent({
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl
+  });
+  return (req, res, next) => {
+    const startTime = Date.now();
+    const requestId = req.headers["x-fullevent-trace-id"] || req.headers["x-request-id"] || crypto.randomUUID();
+    const event = {
+      request_id: requestId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      method: req.method,
+      path: req.path,
+      service: config.service,
+      environment: config.environment || process.env.NODE_ENV || "development",
+      region: config.region
+    };
+    req.wideEvent = event;
+    res.setHeader("x-fullevent-trace-id", requestId);
+    res.on("finish", () => {
+      event.status_code = res.statusCode;
+      event.outcome = res.statusCode >= 400 ? "error" : "success";
+      event.duration_ms = Date.now() - startTime;
+      if (config.apiKey && shouldSample2(event, config.sampling)) {
+        client.ingest(
+          `${event.method} ${event.path}`,
+          event,
+          event.timestamp
+        ).catch((err) => {
+          console.error("[FullEvent] Failed to send event:", err);
+        });
+      }
+    });
+    next();
+  };
+}
+
+// src/builder.ts
+var WideEventBuilder = class {
+  /**
+   * Creates a new builder wrapping the given event.
+   * 
+   * @param event - The wide event to enrich
+   */
+  constructor(event) {
+    this.event = event;
+  }
+  /**
+   * Returns the underlying event object for direct access.
+   * 
+   * @returns The wrapped WideEvent
+   * 
+   * @example
+   * ```typescript
+   * const event = builder.getEvent();
+   * console.log(event.user_id);
+   * ```
+   */
+  getEvent() {
+    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, value) {
+    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, data) {
+    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, data) {
+    const existing = this.event[name];
+    if (existing && typeof existing === "object" && !Array.isArray(existing)) {
+      this.event[name] = { ...existing, ...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) {
+    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) {
+    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) {
+    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, startTime) {
+    this.event[key] = Date.now() - startTime;
+    return this;
+  }
+};
+export {
+  FullEvent,
+  WideEventBuilder,
+  expressWideLogger,
+  wideLogger
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+    "name": "@fullevent/node",
+    "version": "0.0.1",
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts",
+        "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+        "lint": "tsc",
+        "generate:docs": "tsx scripts/generate-docs.ts"
+    },
+    "devDependencies": {
+        "@types/express": "^5.0.6",
+        "@types/node": "^20.0.0",
+        "tsup": "^8.0.0",
+        "tsx": "^4.7.0",
+        "typescript": "^5.0.0"
+    },
+    "peerDependencies": {
+        "hono": "^4.0.0"
+    }
+}