@miradorlabs/parallax-web 2.3.1 → 2.4.0

package/README.md

@@ -16,6 +16,7 @@ npm install @miradorlabs/parallax-web
 - **Fluent Builder Pattern** - Method chaining for building traces
 - **Browser-optimized** - Automatic client metadata collection (browser, OS, etc.)
 - **Blockchain Integration** - Built-in support for correlating traces with blockchain transactions
+- **Stack Trace Capture** - Automatic or manual capture of call stack for debugging
 - **TypeScript Support** - Full type definitions included
 - **Strict Ordering** - Flush calls maintain strict ordering even when async
 
@@ -187,6 +188,9 @@ Creates a new trace builder.
 const trace = client.trace({ name: 'MyTrace' });
 const trace = client.trace({ name: 'MyTrace', autoFlush: false });
 const trace = client.trace({ autoFlush: false, flushPeriodMs: 100 });
+
+// With stack trace capture - records where in your code the trace was created
+const trace = client.trace({ name: 'MyTrace', captureStackTrace: true });
 ```
 
 | Option | Type | Default | Description |
@@ -198,6 +202,7 @@ const trace = client.trace({ autoFlush: false, flushPeriodMs: 100 });
 | `maxRetries` | `number` | `3` | Maximum retry attempts on network failure |
 | `retryBackoff` | `number` | `1000` | Base delay in ms for exponential backoff (doubles each retry) |
 | `autoClose` | `boolean` | `false` | Automatically close trace on page unload |
+| `captureStackTrace` | `boolean` | `false` | Capture stack trace at trace creation point |
 
 Returns: `ParallaxTrace` builder instance
 
@@ -237,16 +242,62 @@ trace.addTag('transaction')
      .addTags(['ethereum', 'send'])
 ```
 
-#### `addEvent(name, details?, timestamp?)`
+#### `addEvent(name, details?, options?)`
 
-Add an event with optional details (string or object).
+Add an event with optional details (string or object) and optional settings.
 
 ```typescript
 trace.addEvent('wallet_connected', { wallet: 'MetaMask' })
      .addEvent('transaction_initiated')
      .addEvent('transaction_confirmed', { blockNumber: 12345 })
+
+// With stack trace - captures where in your code the event was added
+trace.addEvent('error_occurred', { code: 500 }, { captureStackTrace: true })
+
+// Legacy: timestamp can still be passed as third parameter for backward compatibility
+trace.addEvent('custom_event', 'details', new Date())
+```
+
+| Parameter | Type                       | Description                                         |
+|-----------|----------------------------|-----------------------------------------------------|
+| `name`    | `string`                   | Event name                                          |
+| `details` | `string \| object`         | Optional event details (objects are stringified)    |
+| `options` | `AddEventOptions \| Date`  | Options with `captureStackTrace`, or legacy Date    |
+
+#### `addStackTrace(eventName?, additionalDetails?)`
+
+Capture and add the current stack trace as an event. Useful for debugging or tracking code paths.
+
+```typescript
+trace.addStackTrace()  // Creates event named "stack_trace"
+trace.addStackTrace('checkpoint', { stage: 'validation' })
+```
+
+| Parameter           | Type     | Description                                      |
+|---------------------|----------|--------------------------------------------------|
+| `eventName`         | `string` | Event name (defaults to "stack_trace")           |
+| `additionalDetails` | `object` | Optional additional details to include           |
+
+#### `addExistingStackTrace(stackTrace, eventName?, additionalDetails?)`
+
+Add a previously captured stack trace as an event. Useful when you need to capture a stack trace at one point but record it later.
+
+```typescript
+import { captureStackTrace } from '@miradorlabs/parallax-web';
+
+// Capture stack trace now
+const stack = captureStackTrace();
+
+// ... later ...
+trace.addExistingStackTrace(stack, 'deferred_location', { reason: 'async operation' })
 ```
 
+| Parameter           | Type         | Description                                      |
+|---------------------|--------------|--------------------------------------------------|
+| `stackTrace`        | `StackTrace` | Previously captured stack trace                  |
+| `eventName`         | `string`     | Event name (defaults to "stack_trace")           |
+| `additionalDetails` | `object`     | Optional additional details to include           |
+
 #### `addTxHint(txHash, chain, details?)`
 
 Add a transaction hash hint for blockchain correlation. Multiple hints can be added.
@@ -384,6 +435,32 @@ When `includeClientMeta: true` is set (default), the SDK automatically collects:
 
 Note: IP address is captured by the backend from request headers.
 
+## Stack Trace Utilities
+
+The SDK exports utilities for capturing and formatting stack traces:
+
+```typescript
+import {
+  captureStackTrace,
+  formatStackTrace,
+  formatStackTraceReadable
+} from '@miradorlabs/parallax-web';
+
+// Capture current stack trace
+const stack = captureStackTrace();
+// stack.frames: Array of { functionName, fileName, lineNumber, columnNumber }
+// stack.raw: Original Error.stack string
+
+// Format for storage (JSON string)
+const json = formatStackTrace(stack);
+
+// Format for display (human-readable)
+const readable = formatStackTraceReadable(stack);
+// Output:
+//   at myFunction (/path/to/file.js:42:10)
+//   at caller (/path/to/other.js:15:5)
+```
+
 ## TypeScript Support
 
 Full TypeScript support with exported types:
@@ -393,8 +470,11 @@ import {
   ParallaxClient,
   ParallaxTrace,
   ParallaxClientOptions,
-  TraceOptions,
-  ChainName,  // 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bsc'
+  TraceOptions,      // { captureStackTrace?: boolean, ... }
+  AddEventOptions,   // { captureStackTrace?: boolean }
+  StackFrame,        // { functionName, fileName, lineNumber, columnNumber }
+  StackTrace,        // { frames: StackFrame[], raw: string }
+  ChainName,         // 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bsc'
 } from '@miradorlabs/parallax-web';
 ```
 

package/dist/index.d.ts

@@ -32,11 +32,95 @@ interface TraceOptions {
     retryBackoff?: number;
     /** Automatically close trace on page unload (default: false) */
     autoClose?: boolean;
+    /** Capture stack trace at trace creation point */
+    captureStackTrace?: boolean;
+}
+/**
+ * Client metadata collected from the browser environment
+ */
+interface ClientMetadata {
+    browser: string;
+    browserVersion: string;
+    os: string;
+    osVersion: string;
+    deviceType: 'desktop' | 'mobile' | 'tablet';
+    userAgent: string;
+    language: string;
+    languages: string;
+    screenWidth: string;
+    screenHeight: string;
+    viewportWidth: string;
+    viewportHeight: string;
+    colorDepth: string;
+    pixelRatio: string;
+    cpuCores: string;
+    deviceMemory?: string;
+    touchSupport: string;
+    maxTouchPoints: string;
+    connectionType?: string;
+    connectionSpeed?: string;
+    dataSaver?: string;
+    cookiesEnabled: string;
+    online: string;
+    doNotTrack: string;
+    timezone: string;
+    timezoneOffset: string;
+    url: string;
+    origin: string;
+    pathname: string;
+    referrer: string;
+    documentVisibility: string;
+}
+/**
+ * An event to be recorded in a trace
+ */
+interface TraceEvent {
+    eventName: string;
+    details?: string;
+    timestamp: Date;
 }
 /**
  * Supported chain names (maps to Chain enum in proto)
  */
 type ChainName = 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bsc';
+/**
+ * Transaction hash hint for blockchain correlation
+ */
+interface TxHashHint {
+    txHash: string;
+    chain: ChainName;
+    details?: string;
+    timestamp: Date;
+}
+/**
+ * A single frame in a stack trace
+ */
+interface StackFrame {
+    /** Function or method name */
+    functionName: string;
+    /** File path */
+    fileName: string;
+    /** Line number */
+    lineNumber: number;
+    /** Column number */
+    columnNumber: number;
+}
+/**
+ * A captured stack trace
+ */
+interface StackTrace {
+    /** Array of stack frames (top of stack first) */
+    frames: StackFrame[];
+    /** Raw stack string from Error.stack */
+    raw: string;
+}
+/**
+ * Options for adding an event
+ */
+interface AddEventOptions {
+    /** Capture stack trace at the point where addEvent is called */
+    captureStackTrace?: boolean;
+}
 
 /**
  * ParallaxTrace builder class for constructing traces with method chaining
@@ -62,6 +146,7 @@ interface ResolvedTraceOptions {
     retryBackoff: number;
     keepAliveIntervalMs: number;
     autoClose: boolean;
+    captureStackTrace: boolean;
 }
 /**
  * Builder class for constructing traces with method chaining.
@@ -87,6 +172,7 @@ declare class ParallaxTrace {
     private pendingTags;
     private pendingEvents;
     private pendingTxHashHints;
+    private creationStackTrace;
     private flushQueue;
     constructor(client: TraceSubmitter, options: ResolvedTraceOptions);
     /**
@@ -126,10 +212,25 @@ declare class ParallaxTrace {
      * Add an event to the trace
      * @param eventName Name of the event
      * @param details Optional details (can be a JSON string or object that will be stringified)
-     * @param timestamp Optional timestamp (defaults to current time)
+     * @param options Optional settings including captureStackTrace, or a Date for backward compatibility
+     * @returns This trace builder for chaining
+     */
+    addEvent(eventName: string, details?: string | object, options?: AddEventOptions | Date): this;
+    /**
+     * Capture and add the current stack trace as an event
+     * @param eventName Name for the stack trace event (defaults to "stack_trace")
+     * @param additionalDetails Optional additional details to include with the stack trace
+     * @returns This trace builder for chaining
+     */
+    addStackTrace(eventName?: string, additionalDetails?: object): this;
+    /**
+     * Add a pre-captured stack trace as an event
+     * @param stackTrace The stack trace to add
+     * @param eventName Name for the stack trace event (defaults to "stack_trace")
+     * @param additionalDetails Optional additional details to include with the stack trace
      * @returns This trace builder for chaining
      */
-    addEvent(eventName: string, details?: string | object, timestamp?: Date): this;
+    addExistingStackTrace(stackTrace: StackTrace, eventName?: string, additionalDetails?: object): this;
     /**
      * Add a transaction hash hint for blockchain correlation.
      * Multiple hints can be added to the same trace.
@@ -230,4 +331,59 @@ declare class ParallaxClient {
     trace(options?: TraceOptions): ParallaxTrace;
 }
 
-export { ParallaxClient, ParallaxTrace };
+/**
+ * Stack trace capture utilities
+ */
+
+/**
+ * Capture the current stack trace
+ * @param skipFrames Number of frames to skip from the top (default: 1 to skip this function)
+ * @returns Captured stack trace with parsed frames and raw string
+ */
+declare function captureStackTrace(skipFrames?: number): StackTrace;
+/**
+ * Format a stack trace for storage/display
+ * @param stackTrace The stack trace to format
+ * @returns JSON string representation of the stack trace
+ */
+declare function formatStackTrace(stackTrace: StackTrace): string;
+/**
+ * Format a stack trace as a human-readable string
+ * @param stackTrace The stack trace to format
+ * @returns Human-readable stack trace string
+ */
+declare function formatStackTraceReadable(stackTrace: StackTrace): string;
+
+/**
+ * Browser metadata collection utilities
+ */
+interface BrowserInfo {
+    name: string;
+    version: string;
+}
+interface OSInfo {
+    name: string;
+    version: string;
+}
+/**
+ * Detect browser name and version from user agent
+ */
+declare function detectBrowser(ua: string): BrowserInfo;
+/**
+ * Detect operating system name and version from user agent
+ */
+declare function detectOS(ua: string): OSInfo;
+/**
+ * Detect device type from user agent
+ */
+declare function detectDeviceType(ua: string): 'desktop' | 'mobile' | 'tablet';
+/**
+ * Gather client metadata from the browser environment
+ * Note: IP address is captured by the backend from request headers
+ */
+declare function getClientMetadata(): {
+    [key: string]: string;
+};
+
+export { ParallaxClient, ParallaxTrace, captureStackTrace, detectBrowser, detectDeviceType, detectOS, formatStackTrace, formatStackTraceReadable, getClientMetadata };
+export type { AddEventOptions, ChainName, ClientMetadata, ParallaxClientOptions, StackFrame, StackTrace, TraceEvent, TraceOptions, TxHashHint };

package/dist/index.esm.js

@@ -3908,6 +3908,94 @@ function getClientMetadata() {
     return metadata;
 }
 
+/**
+ * Parse a V8/browser stack trace string into structured frames
+ * @param stack Raw stack string from Error.stack
+ * @returns Array of parsed stack frames
+ */
+function parseStackString(stack) {
+    const frames = [];
+    const lines = stack.split('\n');
+    for (const line of lines) {
+        // Skip the first line (error message) and empty lines
+        if (!line.trim().startsWith('at ')) {
+            continue;
+        }
+        // Parse V8 stack frame format:
+        // "    at functionName (filename:line:column)"
+        // "    at filename:line:column"
+        // "    at async functionName (filename:line:column)"
+        const trimmed = line.trim().slice(3); // Remove "at "
+        let functionName = '<anonymous>';
+        let locationPart = trimmed;
+        // Check if there's a function name before the location
+        const parenMatch = trimmed.match(/^(.*?)\s*\((.+)\)$/);
+        if (parenMatch) {
+            functionName = parenMatch[1].replace(/^async\s+/, '').trim() || '<anonymous>';
+            locationPart = parenMatch[2];
+        }
+        // Parse location: filename:line:column
+        const locationMatch = locationPart.match(/^(.+):(\d+):(\d+)$/);
+        if (locationMatch) {
+            frames.push({
+                functionName,
+                fileName: locationMatch[1],
+                lineNumber: parseInt(locationMatch[2], 10),
+                columnNumber: parseInt(locationMatch[3], 10),
+            });
+        }
+        else {
+            // Fallback for unusual formats
+            frames.push({
+                functionName,
+                fileName: locationPart,
+                lineNumber: 0,
+                columnNumber: 0,
+            });
+        }
+    }
+    return frames;
+}
+/**
+ * Capture the current stack trace
+ * @param skipFrames Number of frames to skip from the top (default: 1 to skip this function)
+ * @returns Captured stack trace with parsed frames and raw string
+ */
+function captureStackTrace(skipFrames = 1) {
+    const error = new Error();
+    const rawStack = error.stack || '';
+    // Parse all frames
+    const allFrames = parseStackString(rawStack);
+    // Skip internal frames (this function + any additional requested skips)
+    // Add 1 to account for this function itself
+    const frames = allFrames.slice(skipFrames + 1);
+    return {
+        frames,
+        raw: rawStack,
+    };
+}
+/**
+ * Format a stack trace for storage/display
+ * @param stackTrace The stack trace to format
+ * @returns JSON string representation of the stack trace
+ */
+function formatStackTrace(stackTrace) {
+    return JSON.stringify({
+        frames: stackTrace.frames,
+        raw: stackTrace.raw,
+    });
+}
+/**
+ * Format a stack trace as a human-readable string
+ * @param stackTrace The stack trace to format
+ * @returns Human-readable stack trace string
+ */
+function formatStackTraceReadable(stackTrace) {
+    return stackTrace.frames
+        .map((frame) => `  at ${frame.functionName} (${frame.fileName}:${frame.lineNumber}:${frame.columnNumber})`)
+        .join('\n');
+}
+
 /**
  * ParallaxTrace builder class for constructing traces with method chaining
  */
@@ -4042,6 +4130,12 @@ class ParallaxTrace {
             writable: true,
             value: []
         });
+        Object.defineProperty(this, "creationStackTrace", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         // Queue for maintaining strict ordering of flushes
         Object.defineProperty(this, "flushQueue", {
             enumerable: true,
@@ -4058,6 +4152,10 @@ class ParallaxTrace {
         this.retryBackoff = options.retryBackoff;
         this.keepAliveIntervalMs = options.keepAliveIntervalMs;
         this.autoClose = options.autoClose;
+        if (options.captureStackTrace) {
+            // Skip 2 frames: this constructor and the trace() method that called it
+            this.creationStackTrace = captureStackTrace(2);
+        }
         // Set up auto-close on page unload if enabled
         if (this.autoClose && typeof window !== 'undefined') {
             this.unloadHandler = () => {
@@ -4156,25 +4254,108 @@ class ParallaxTrace {
      * Add an event to the trace
      * @param eventName Name of the event
      * @param details Optional details (can be a JSON string or object that will be stringified)
-     * @param timestamp Optional timestamp (defaults to current time)
+     * @param options Optional settings including captureStackTrace, or a Date for backward compatibility
      * @returns This trace builder for chaining
      */
-    addEvent(eventName, details, timestamp) {
+    addEvent(eventName, details, options) {
         if (this.closed) {
             console.warn('[ParallaxTrace] Trace is closed. Ignoring addEvent call.');
             return this;
         }
-        const detailsString = typeof details === 'object' && details !== null
-            ? JSON.stringify(details)
-            : details;
+        // Handle backward compatibility: options can be a Date (legacy timestamp parameter)
+        let timestamp;
+        let eventOptions;
+        if (options instanceof Date) {
+            timestamp = options;
+        }
+        else {
+            eventOptions = options;
+        }
+        // Build details object with optional stack trace
+        let finalDetails;
+        if (eventOptions?.captureStackTrace) {
+            const stackTrace = captureStackTrace(1); // Skip 1 frame (this method)
+            const detailsObj = typeof details === 'object' && details !== null
+                ? details
+                : details !== undefined
+                    ? { message: details }
+                    : {};
+            finalDetails = JSON.stringify({
+                ...detailsObj,
+                stackTrace: {
+                    frames: stackTrace.frames,
+                    raw: stackTrace.raw,
+                },
+            });
+        }
+        else {
+            finalDetails =
+                typeof details === 'object' && details !== null
+                    ? JSON.stringify(details)
+                    : details;
+        }
         this.pendingEvents.push({
             eventName,
-            details: detailsString,
+            details: finalDetails,
             timestamp: timestamp || new Date(),
         });
         this.scheduleFlush();
         return this;
     }
+    /**
+     * Capture and add the current stack trace as an event
+     * @param eventName Name for the stack trace event (defaults to "stack_trace")
+     * @param additionalDetails Optional additional details to include with the stack trace
+     * @returns This trace builder for chaining
+     */
+    addStackTrace(eventName = 'stack_trace', additionalDetails) {
+        if (this.closed) {
+            console.warn('[ParallaxTrace] Trace is closed. Ignoring addStackTrace call.');
+            return this;
+        }
+        const stackTrace = captureStackTrace(1); // Skip 1 frame (this method)
+        const details = {
+            ...additionalDetails,
+            stackTrace: {
+                frames: stackTrace.frames,
+                raw: stackTrace.raw,
+            },
+        };
+        this.pendingEvents.push({
+            eventName,
+            details: JSON.stringify(details),
+            timestamp: new Date(),
+        });
+        this.scheduleFlush();
+        return this;
+    }
+    /**
+     * Add a pre-captured stack trace as an event
+     * @param stackTrace The stack trace to add
+     * @param eventName Name for the stack trace event (defaults to "stack_trace")
+     * @param additionalDetails Optional additional details to include with the stack trace
+     * @returns This trace builder for chaining
+     */
+    addExistingStackTrace(stackTrace, eventName = 'stack_trace', additionalDetails) {
+        if (this.closed) {
+            console.warn('[ParallaxTrace] Trace is closed. Ignoring addExistingStackTrace call.');
+            return this;
+        }
+        const details = {
+            ...additionalDetails,
+            stackTrace: {
+                frames: stackTrace.frames,
+                raw: stackTrace.raw,
+            },
+        };
+        this.pendingEvents.push({
+            eventName,
+            details: JSON.stringify(details),
+            timestamp: new Date(),
+        });
+        this.scheduleFlush();
+        return this;
+    }
     /**
      * Add a transaction hash hint for blockchain correlation.
      * Multiple hints can be added to the same trace.
@@ -4247,7 +4428,7 @@ class ParallaxTrace {
      */
     buildTraceData() {
         const traceData = new parallax_gateway_pbExports.TraceData();
-        // Add pending attributes (+ client metadata on first flush)
+        // Add pending attributes (+ client metadata on first flush + stack trace if captured)
         const allAttrs = { ...this.pendingAttributes };
         if (this.traceId === null && this.includeClientMeta) {
             const clientMeta = getClientMetadata();
@@ -4255,6 +4436,16 @@ class ParallaxTrace {
                 allAttrs[`client.${key}`] = value;
             }
         }
+        // Add creation stack trace attributes on first flush
+        if (this.traceId === null && this.creationStackTrace) {
+            allAttrs['source.stack_trace'] = formatStackTrace(this.creationStackTrace);
+            if (this.creationStackTrace.frames.length > 0) {
+                const topFrame = this.creationStackTrace.frames[0];
+                allAttrs['source.file'] = topFrame.fileName;
+                allAttrs['source.line'] = String(topFrame.lineNumber);
+                allAttrs['source.function'] = topFrame.functionName;
+            }
+        }
         if (Object.keys(allAttrs).length > 0) {
             const attrsMsg = new parallax_gateway_pbExports.Attributes();
             const attrsMap = attrsMsg.getAttributesMap();
@@ -4557,11 +4748,12 @@ class ParallaxClient {
             retryBackoff: options?.retryBackoff ?? DEFAULT_RETRY_BACKOFF,
             keepAliveIntervalMs: this.keepAliveIntervalMs,
             autoClose: options?.autoClose ?? DEFAULT_AUTO_CLOSE,
+            captureStackTrace: options?.captureStackTrace ?? false,
         });
     }
 }
 
 var CreateTraceRequest = parallax_gateway_pbExports.CreateTraceRequest;
 var CreateTraceResponse = parallax_gateway_pbExports.CreateTraceResponse;
-export { CreateTraceRequest, CreateTraceResponse, ParallaxClient, ParallaxTrace };
+export { CreateTraceRequest, CreateTraceResponse, ParallaxClient, ParallaxTrace, captureStackTrace, detectBrowser, detectDeviceType, detectOS, formatStackTrace, formatStackTraceReadable, getClientMetadata };
 //# sourceMappingURL=index.esm.js.map