@getlimelight/sdk 0.6.1 → 0.7.8

package/README.md

@@ -1,6 +1,7 @@
 # Limelight SDK
 
-> **Chrome DevTools for React Native** - Real-time debugging with state inspection, network monitoring, console streaming, and render tracking.
+> **React Native Devtools** - Zero-config network inspector, render profiling, state tracking, and console streaming —
+> all in one workspace. Designed for AI workflows.
 
 [![npm version](https://img.shields.io/npm/v/@getlimelight/sdk.svg)](https://www.npmjs.com/package/@getlimelight/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -8,16 +9,24 @@
 
 ## Documentation
 
-📚 **Full documentation at [docs.getlimelight.io](https://docs.getlimelight.io)**
+**Full documentation at [docs.getlimelight.io](https://docs.getlimelight.io)**
+
+## Landing page
+
+**Landing page at [getlimelight.io](https://getlimelight.io)**
 
 ## Features
 
-- 🔮 **State Inspection** - Debug Zustand and Redux stores in real-time
-- 🔍 **Network Monitoring** - Inspect all HTTP requests with GraphQL-first support
-- 📊 **Console Streaming** - View logs with stack traces and source detection
-- ⚡ **Render Tracking** - Find why components re-render
-- 🛡️ **Privacy-First** - Automatic redaction of sensitive data
-- 🎨 **Zero Config** - Works out of the box
+- **State Inspection** - Debug Zustand and Redux stores in real-time
+- **Network Monitoring** - Inspect all HTTP requests with GraphQL-first support
+- **Console Streaming** - View logs with stack traces and source detection
+- **Render Tracking** - Find why components re-render
+- **Privacy-First** - Automatic redaction of sensitive data
+- **Zero Config** - Works out of the box
+- **Framework Agnostic** - Work in React, RN, Node, Nextjs, etc...
+- **Full-Stack** - See client to server requests traced together and full-stack logs in one place
+- **Automatic Issue Detection** - Limelight automatically detects issues in your app and server
+- **AI Enabled** - Give your AI coding tools insights into your apps runtime context via the Limelight MCP or thorugh the app
 
 ## Installation
 
@@ -90,14 +99,51 @@ Limelight.connect({
 });
 ```
 
+### Server-Side (Express / Next.js)
+
+Capture incoming HTTP requests and responses on your backend.
+
+**Express / Connect:**
+
+```typescript
+import express from "express";
+import { Limelight } from "@getlimelight/sdk";
+
+const app = express();
+
+app.use(express.json());
+app.use(Limelight.middleware());
+```
+
+**Next.js Pages Router (`pages/api/`):**
+
+```typescript
+// pages/api/users.ts
+import { Limelight } from "@getlimelight/sdk";
+
+export default Limelight.withLimelight((req, res) => {
+  res.json({ ok: true });
+});
+```
+
+Both methods automatically capture request/response headers, bodies, status codes, and timing — and propagate a trace ID (`x-limelight-trace-id`) for full-stack tracing.
+
+**Outbound HTTP interception** is automatic in Node.js environments. When `enableNetworkInspector` is `true` (the default), the SDK patches `http.request` and `https.request` to capture all outgoing calls your server makes — API calls to other services, auth servers, databases over HTTP, etc. Combined with the incoming middleware, this gives you full end-to-end tracing:
+
+```
+Client (fetch) → Your Server (middleware) → Downstream Service (http interceptor)
+       ↑ same trace ID propagated across all three ↑
+```
+
+No additional setup is required — just connect the SDK and add the middleware.
+
 ## Learn More
 
 - [Quick Start Guide](https://docs.getlimelight.io/quickstart)
 - [State Inspection](https://docs.getlimelight.io/features/state)
-- [Network Monitoring](https://docs.getlimelight.io/features/network)
-- [Console Streaming](https://docs.getlimelight.io/features/console)
-- [Render Tracking](https://docs.getlimelight.io/features/renders)
-- [Configuration Reference](https://docs.getlimelight.io/configuration)
+- [Network Monitoring](https://docs.getlimelight.io/features/network-requests)
+- [Console Streaming](https://docs.getlimelight.io/features/console-logs)
+- [Render Tracking](https://docs.getlimelight.io/features/render-tracking)
 
 ## License
 
@@ -105,4 +151,4 @@ MIT © Limelight
 
 ---
 
-[Documentation](https://docs.getlimelight.io) · [GitHub](https://github.com/getlimelight/limelight) · [Issues](https://github.com/getlimelight/limelight/issues)
+[Documentation](https://docs.getlimelight.io) · [GitHub](https://github.com/getlimelight/limelight-sdk) · [Issues](https://github.com/getlimelight/limelight-sdk/issues)

package/dist/index.d.mts

@@ -1,7 +1,12 @@
+import * as http from 'http';
+import { IncomingMessage, ServerResponse } from 'http';
+
 declare enum NetworkType {
     FETCH = "fetch",
     XHR = "xhr",
-    GRAPHQL = "graphql"
+    GRAPHQL = "graphql",
+    INCOMING = "incoming",
+    HTTP = "http"
 }
 declare enum NetworkPhase {
     CONNECT = "CONNECT",
@@ -51,6 +56,7 @@ interface SerializedBody {
  */
 interface BaseNetworkEvent {
     id: string;
+    traceId?: string;
     sessionId: string;
     timestamp: number;
     phase: NetworkPhase;
@@ -109,6 +115,9 @@ interface ConnectEvent {
         platform: "ios" | "android";
     };
 }
+/**
+ * Request with its corresponding response (for UI display)
+ */
 declare enum EventType {
     NETWORK = "NETWORK",
     CONSOLE = "CONSOLE"
@@ -118,29 +127,6 @@ declare enum EventType {
  */
 type NetworkEvent = ConnectEvent | NetworkRequest | NetworkResponse | NetworkErrorEvent | GraphQLRequest | GraphQLResponse;
 type LimelightEvent = NetworkEvent | ConsoleEvent;
-interface Session {
-    id: string;
-    appName: string;
-    platform: "ios" | "android";
-    connectedAt: number;
-}
-/**
- * Request with its corresponding response (for UI display)
- */
-interface NetworkRequestWithResponse extends NetworkRequest {
-    response?: NetworkResponse;
-    status?: number;
-    duration?: number;
-    error?: NetworkErrorEvent;
-}
-/**
- * Request with its corresponding response (for UI display)
- */
-interface NetworkRequestWithResponse extends NetworkRequest {
-    response?: NetworkResponse;
-    status?: number;
-    duration?: number;
-}
 
 /**
  * Console log levels
@@ -398,9 +384,9 @@ interface LimelightConfig {
      */
     projectKey?: string;
     /**
-     * The platform of the application (e.g., "ios", "android").
+     * The platform of the application. Auto-detected if not provided.
      */
-    platform?: string;
+    platform?: "ios" | "android" | "web" | "react-native" | "node" | (string & {});
     /**
      * The URL of the Limelight server to connect to. If not provided, it falls back to the local wss server url if there is no project key, or the web wss url if there is a project key.
      */
@@ -411,26 +397,32 @@ interface LimelightConfig {
     appName?: string;
     /**
      * Flag to enable or disable the Limelight SDK.
+     * @default true (SDK is enabled by default)
      */
     enabled?: boolean;
     /**
      * Flag to enable or disable network request inspection.
+     * @default true
      */
     enableNetworkInspector?: boolean;
     /**
      * Flag to enable or disable console event capturing.
+     * @default true
      */
     enableConsole?: boolean;
     /**
      * Flag to enable or disable GraphQL request capturing.
+     * @default true
      */
     enableGraphQL?: boolean;
     /**
      * Flag to disable capturing of request and response bodies.
+     * @default false (bodies are captured by default)
      */
     disableBodyCapture?: boolean;
     /**
      * Flag to enable or disable render inspection.
+     * @default true
      */
     enableRenderInspector?: boolean;
     /**
@@ -445,16 +437,30 @@ interface LimelightConfig {
     enableStateInspector?: boolean;
     /**
      * Flag to enable or disable internal logging for the Limelight SDK
+     * @default false
      */
     enableInternalLogging?: boolean;
     /**
      * Target destination for events. Set to "mcp" to send events to the MCP server at ws://localhost:9229.
      */
     target?: "mcp";
+    /**
+     * Custom header name used for trace ID propagation across client and server.
+     * @default 'x-limelight-trace-id'
+     */
+    traceHeaderName?: string;
     /**
      * A callback function to modify or filter events before they are sent to the server
      */
     beforeSend?: (event: LimelightMessage) => LimelightMessage | null;
+    /**
+     * Custom WebSocket implementation for Node.js environments where WebSocket
+     * is not globally available (Node < 22). Pass the `ws` package constructor.
+     * @example
+     * import WebSocket from 'ws';
+     * Limelight.connect({ webSocketImpl: WebSocket });
+     */
+    webSocketImpl?: new (url: string, protocols?: string | string[]) => WebSocket;
 }
 /**
  * Represents a connection or disconnection event in the Limelight SDK.
@@ -520,6 +526,41 @@ interface ResponseBridgeConfig {
     body?: any;
 }
 
+interface MiddlewareOptions {
+    /** Maximum body size to capture in bytes. Bodies larger than this are truncated. Default: 64KB */
+    maxBodySize?: number;
+}
+
+type NextApiHandler = (req: IncomingMessage & {
+    body?: unknown;
+    query?: Record<string, unknown>;
+}, res: ServerResponse) => void | Promise<void>;
+/**
+ * Wraps a Next.js Pages API route handler with Limelight request/response capture.
+ *
+ * NOTE: This works with Next.js Pages Router API routes (`pages/api/`)
+ * which use the Node.js `(req, res)` signature. It does NOT work with
+ * App Router route handlers (`app/api/`) which use the Web Standard
+ * `Request`/`Response` objects. App Router support is planned for a future release.
+ *
+ * @example
+ * ```ts
+ * // pages/api/users.ts
+ * import { Limelight } from '@getlimelight/sdk';
+ *
+ * export default Limelight.withLimelight((req, res) => {
+ *   res.json({ ok: true });
+ * });
+ * ```
+ *
+ * @param sendMessage Function to send Limelight messages to the server
+ * @param getSessionId Function to retrieve the current Limelight session ID
+ * @param getConfig Function to retrieve the current Limelight configuration
+ * @param options Optional middleware options (e.g. maxBodySize)
+ * @returns A function that wraps a Next.js API route handler with Limelight capture
+ */
+declare const createWithLimelight: (sendMessage: (message: LimelightMessage) => void, getSessionId: () => string, getConfig: () => LimelightConfig | null, options?: MiddlewareOptions) => (handler: NextApiHandler) => NextApiHandler;
+
 declare class LimelightClient {
     private ws;
     private config;
@@ -532,9 +573,11 @@ declare class LimelightClient {
     private maxQueueSize;
     private networkInterceptor;
     private xhrInterceptor;
+    private httpInterceptor;
     private consoleInterceptor;
     private renderInterceptor;
     private stateInterceptor;
+    private errorInterceptor;
     private requestBridge;
     private commandHandler;
     constructor();
@@ -620,6 +663,37 @@ declare class LimelightClient {
      * @param error - The error that occurred
      */
     failRequest(requestId: string, error: unknown): void;
+    /**
+     * Returns an Express/Connect-compatible middleware that captures incoming
+     * HTTP requests and responses.
+     *
+     * Place after body-parser middleware (express.json(), etc.) for request body capture.
+     *
+     * @example
+     * ```ts
+     * app.use(express.json());
+     * app.use(Limelight.middleware());
+     * ```
+     */
+    middleware(options?: MiddlewareOptions): (req: http.IncomingMessage & {
+        body?: unknown;
+    }, res: http.ServerResponse, next: () => void) => void;
+    /**
+     * Wraps a Next.js Pages API route handler with request/response capture.
+     * Works with Pages Router (`pages/api/`), not App Router (`app/api/`).
+     *
+     * @example
+     * ```ts
+     * // pages/api/users.ts
+     * export default Limelight.withLimelight((req, res) => {
+     *   res.json({ ok: true });
+     * });
+     * ```
+     */
+    withLimelight(handler: Parameters<ReturnType<typeof createWithLimelight>>[0]): (req: http.IncomingMessage & {
+        body?: unknown;
+        query?: Record<string, unknown>;
+    }, res: http.ServerResponse) => void | Promise<void>;
 }
 declare const Limelight: LimelightClient;
 
@@ -627,6 +701,7 @@ declare global {
     interface XMLHttpRequest {
         _limelightData?: {
             id: string;
+            traceId?: string;
             method: string;
             url: string;
             headers: Record<string, string>;
@@ -637,4 +712,4 @@ declare global {
     }
 }
 
-export { type BaseCommand, type BaseNetworkEvent, BodyFormat, type ClearRendersCommand, type Command, type CommandAckEvent, CommandType, type ConnectEvent, type ConnectionEvent, type ConsoleEvent, ConsoleLevel, ConsoleSource, ConsoleType, EventType, type GraphQLRequest, type GraphQLResponse, GraphqlOprtation, HttpMethod, HttpStatusClass, Limelight, type LimelightConfig, type LimelightEvent, type LimelightMessage, type NetworkErrorEvent, type NetworkEvent, NetworkPhase, type NetworkRequest, type NetworkRequestWithResponse, type NetworkResponse, NetworkType, type ParsedStackTrace, type RequestBridgeConfig, type ResponseBridgeConfig, type SerializedBody, type Session, type StackFrame };
+export { type BaseCommand, type BaseNetworkEvent, BodyFormat, type ClearRendersCommand, type Command, type CommandAckEvent, CommandType, type ConnectEvent, type ConnectionEvent, type ConsoleEvent, ConsoleLevel, ConsoleSource, ConsoleType, EventType, type GraphQLRequest, type GraphQLResponse, GraphqlOprtation, HttpMethod, HttpStatusClass, Limelight, type LimelightConfig, type LimelightEvent, type LimelightMessage, type NetworkErrorEvent, type NetworkEvent, NetworkPhase, type NetworkRequest, type NetworkResponse, NetworkType, type ParsedStackTrace, type RequestBridgeConfig, type ResponseBridgeConfig, type SerializedBody, type StackFrame };

package/dist/index.d.ts

@@ -1,7 +1,12 @@
+import * as http from 'http';
+import { IncomingMessage, ServerResponse } from 'http';
+
 declare enum NetworkType {
     FETCH = "fetch",
     XHR = "xhr",
-    GRAPHQL = "graphql"
+    GRAPHQL = "graphql",
+    INCOMING = "incoming",
+    HTTP = "http"
 }
 declare enum NetworkPhase {
     CONNECT = "CONNECT",
@@ -51,6 +56,7 @@ interface SerializedBody {
  */
 interface BaseNetworkEvent {
     id: string;
+    traceId?: string;
     sessionId: string;
     timestamp: number;
     phase: NetworkPhase;
@@ -109,6 +115,9 @@ interface ConnectEvent {
         platform: "ios" | "android";
     };
 }
+/**
+ * Request with its corresponding response (for UI display)
+ */
 declare enum EventType {
     NETWORK = "NETWORK",
     CONSOLE = "CONSOLE"
@@ -118,29 +127,6 @@ declare enum EventType {
  */
 type NetworkEvent = ConnectEvent | NetworkRequest | NetworkResponse | NetworkErrorEvent | GraphQLRequest | GraphQLResponse;
 type LimelightEvent = NetworkEvent | ConsoleEvent;
-interface Session {
-    id: string;
-    appName: string;
-    platform: "ios" | "android";
-    connectedAt: number;
-}
-/**
- * Request with its corresponding response (for UI display)
- */
-interface NetworkRequestWithResponse extends NetworkRequest {
-    response?: NetworkResponse;
-    status?: number;
-    duration?: number;
-    error?: NetworkErrorEvent;
-}
-/**
- * Request with its corresponding response (for UI display)
- */
-interface NetworkRequestWithResponse extends NetworkRequest {
-    response?: NetworkResponse;
-    status?: number;
-    duration?: number;
-}
 
 /**
  * Console log levels
@@ -398,9 +384,9 @@ interface LimelightConfig {
      */
     projectKey?: string;
     /**
-     * The platform of the application (e.g., "ios", "android").
+     * The platform of the application. Auto-detected if not provided.
      */
-    platform?: string;
+    platform?: "ios" | "android" | "web" | "react-native" | "node" | (string & {});
     /**
      * The URL of the Limelight server to connect to. If not provided, it falls back to the local wss server url if there is no project key, or the web wss url if there is a project key.
      */
@@ -411,26 +397,32 @@ interface LimelightConfig {
     appName?: string;
     /**
      * Flag to enable or disable the Limelight SDK.
+     * @default true (SDK is enabled by default)
      */
     enabled?: boolean;
     /**
      * Flag to enable or disable network request inspection.
+     * @default true
      */
     enableNetworkInspector?: boolean;
     /**
      * Flag to enable or disable console event capturing.
+     * @default true
      */
     enableConsole?: boolean;
     /**
      * Flag to enable or disable GraphQL request capturing.
+     * @default true
      */
     enableGraphQL?: boolean;
     /**
      * Flag to disable capturing of request and response bodies.
+     * @default false (bodies are captured by default)
      */
     disableBodyCapture?: boolean;
     /**
      * Flag to enable or disable render inspection.
+     * @default true
      */
     enableRenderInspector?: boolean;
     /**
@@ -445,16 +437,30 @@ interface LimelightConfig {
     enableStateInspector?: boolean;
     /**
      * Flag to enable or disable internal logging for the Limelight SDK
+     * @default false
      */
     enableInternalLogging?: boolean;
     /**
      * Target destination for events. Set to "mcp" to send events to the MCP server at ws://localhost:9229.
      */
     target?: "mcp";
+    /**
+     * Custom header name used for trace ID propagation across client and server.
+     * @default 'x-limelight-trace-id'
+     */
+    traceHeaderName?: string;
     /**
      * A callback function to modify or filter events before they are sent to the server
      */
     beforeSend?: (event: LimelightMessage) => LimelightMessage | null;
+    /**
+     * Custom WebSocket implementation for Node.js environments where WebSocket
+     * is not globally available (Node < 22). Pass the `ws` package constructor.
+     * @example
+     * import WebSocket from 'ws';
+     * Limelight.connect({ webSocketImpl: WebSocket });
+     */
+    webSocketImpl?: new (url: string, protocols?: string | string[]) => WebSocket;
 }
 /**
  * Represents a connection or disconnection event in the Limelight SDK.
@@ -520,6 +526,41 @@ interface ResponseBridgeConfig {
     body?: any;
 }
 
+interface MiddlewareOptions {
+    /** Maximum body size to capture in bytes. Bodies larger than this are truncated. Default: 64KB */
+    maxBodySize?: number;
+}
+
+type NextApiHandler = (req: IncomingMessage & {
+    body?: unknown;
+    query?: Record<string, unknown>;
+}, res: ServerResponse) => void | Promise<void>;
+/**
+ * Wraps a Next.js Pages API route handler with Limelight request/response capture.
+ *
+ * NOTE: This works with Next.js Pages Router API routes (`pages/api/`)
+ * which use the Node.js `(req, res)` signature. It does NOT work with
+ * App Router route handlers (`app/api/`) which use the Web Standard
+ * `Request`/`Response` objects. App Router support is planned for a future release.
+ *
+ * @example
+ * ```ts
+ * // pages/api/users.ts
+ * import { Limelight } from '@getlimelight/sdk';
+ *
+ * export default Limelight.withLimelight((req, res) => {
+ *   res.json({ ok: true });
+ * });
+ * ```
+ *
+ * @param sendMessage Function to send Limelight messages to the server
+ * @param getSessionId Function to retrieve the current Limelight session ID
+ * @param getConfig Function to retrieve the current Limelight configuration
+ * @param options Optional middleware options (e.g. maxBodySize)
+ * @returns A function that wraps a Next.js API route handler with Limelight capture
+ */
+declare const createWithLimelight: (sendMessage: (message: LimelightMessage) => void, getSessionId: () => string, getConfig: () => LimelightConfig | null, options?: MiddlewareOptions) => (handler: NextApiHandler) => NextApiHandler;
+
 declare class LimelightClient {
     private ws;
     private config;
@@ -532,9 +573,11 @@ declare class LimelightClient {
     private maxQueueSize;
     private networkInterceptor;
     private xhrInterceptor;
+    private httpInterceptor;
     private consoleInterceptor;
     private renderInterceptor;
     private stateInterceptor;
+    private errorInterceptor;
     private requestBridge;
     private commandHandler;
     constructor();
@@ -620,6 +663,37 @@ declare class LimelightClient {
      * @param error - The error that occurred
      */
     failRequest(requestId: string, error: unknown): void;
+    /**
+     * Returns an Express/Connect-compatible middleware that captures incoming
+     * HTTP requests and responses.
+     *
+     * Place after body-parser middleware (express.json(), etc.) for request body capture.
+     *
+     * @example
+     * ```ts
+     * app.use(express.json());
+     * app.use(Limelight.middleware());
+     * ```
+     */
+    middleware(options?: MiddlewareOptions): (req: http.IncomingMessage & {
+        body?: unknown;
+    }, res: http.ServerResponse, next: () => void) => void;
+    /**
+     * Wraps a Next.js Pages API route handler with request/response capture.
+     * Works with Pages Router (`pages/api/`), not App Router (`app/api/`).
+     *
+     * @example
+     * ```ts
+     * // pages/api/users.ts
+     * export default Limelight.withLimelight((req, res) => {
+     *   res.json({ ok: true });
+     * });
+     * ```
+     */
+    withLimelight(handler: Parameters<ReturnType<typeof createWithLimelight>>[0]): (req: http.IncomingMessage & {
+        body?: unknown;
+        query?: Record<string, unknown>;
+    }, res: http.ServerResponse) => void | Promise<void>;
 }
 declare const Limelight: LimelightClient;
 
@@ -627,6 +701,7 @@ declare global {
     interface XMLHttpRequest {
         _limelightData?: {
             id: string;
+            traceId?: string;
             method: string;
             url: string;
             headers: Record<string, string>;
@@ -637,4 +712,4 @@ declare global {
     }
 }
 
-export { type BaseCommand, type BaseNetworkEvent, BodyFormat, type ClearRendersCommand, type Command, type CommandAckEvent, CommandType, type ConnectEvent, type ConnectionEvent, type ConsoleEvent, ConsoleLevel, ConsoleSource, ConsoleType, EventType, type GraphQLRequest, type GraphQLResponse, GraphqlOprtation, HttpMethod, HttpStatusClass, Limelight, type LimelightConfig, type LimelightEvent, type LimelightMessage, type NetworkErrorEvent, type NetworkEvent, NetworkPhase, type NetworkRequest, type NetworkRequestWithResponse, type NetworkResponse, NetworkType, type ParsedStackTrace, type RequestBridgeConfig, type ResponseBridgeConfig, type SerializedBody, type Session, type StackFrame };
+export { type BaseCommand, type BaseNetworkEvent, BodyFormat, type ClearRendersCommand, type Command, type CommandAckEvent, CommandType, type ConnectEvent, type ConnectionEvent, type ConsoleEvent, ConsoleLevel, ConsoleSource, ConsoleType, EventType, type GraphQLRequest, type GraphQLResponse, GraphqlOprtation, HttpMethod, HttpStatusClass, Limelight, type LimelightConfig, type LimelightEvent, type LimelightMessage, type NetworkErrorEvent, type NetworkEvent, NetworkPhase, type NetworkRequest, type NetworkResponse, NetworkType, type ParsedStackTrace, type RequestBridgeConfig, type ResponseBridgeConfig, type SerializedBody, type StackFrame };