@miradorlabs/parallax-web 2.0.1 → 2.2.0

package/.claude/settings.local.json

@@ -9,7 +9,13 @@
       "Bash(chmod:*)",
       "Bash(gh pr view:*)",
       "Bash(gh api:*)",
-      "Bash(npm run lint:*)"
+      "Bash(npm run lint:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(npm pack:*)"
     ]
-  }
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "playwright"
+  ]
 }

package/CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Browser SDK for the Parallax tracing platform using gRPC-Web to communicate with the Parallax Gateway API. Published as `@miradorlabs/parallax-web`.
+
+## Commands
+
+```bash
+npm run build          # Build ESM, UMD, and type definitions via Rollup
+npm test               # Run Jest tests
+npm run test:watch     # Run tests in watch mode
+npm run lint           # Lint src/ and tests/
+npm run lint:fix       # Lint and auto-fix
+```
+
+## Architecture
+
+```
+src/
+├── index.ts              # Re-exports from parallax/
+└── parallax/
+    ├── index.ts          # Public exports
+    ├── client.ts         # ParallaxClient - main entry point, holds gRPC client
+    ├── trace.ts          # ParallaxTrace - fluent builder with flush logic
+    ├── types.ts          # TypeScript interfaces (TraceOptions, ChainName, etc.)
+    └── metadata.ts       # Browser metadata detection utilities
+```
+
+### Key Classes
+
+**ParallaxClient** (`client.ts`)
+- Creates gRPC-Web client for Parallax Gateway
+- `trace(options?)` returns a `ParallaxTrace` builder
+- `_sendTrace()` / `_updateTrace()` are internal methods called by trace
+
+**ParallaxTrace** (`trace.ts`)
+- Fluent builder: `addAttribute()`, `addEvent()`, `addTags()`, `addTxHint()`
+- Manages pending state and flush queue for strict ordering
+- `flush()` sends `CreateTrace` (first call) or `UpdateTrace` (subsequent)
+- Auto-flush mode: debounced timer resets on each SDK call
+- `flushPeriod: 0` means immediate flush on every call
+
+### Proto Dependency
+
+The gRPC types come from `mirador-gateway-parallax-web` (private package). Key imports:
+- `CreateTraceRequest`, `UpdateTraceRequest`, `TraceData`
+- `Attributes`, `Tags`, `Event`, `TxHashHint`, `Chain`
+
+## Build Output
+
+- `dist/index.esm.js` - ES modules
+- `dist/index.umd.js` - UMD for browsers
+- `dist/index.d.ts` - TypeScript declarations

package/README.md

@@ -10,31 +10,69 @@ npm install @miradorlabs/parallax-web
 
 ## Features
 
-- **Fluent Builder Pattern** - Method chaining for creating traces
+- **Auto-Flush Mode** - Data automatically batches and sends after a configurable period of inactivity
+- **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
 - **TypeScript Support** - Full type definitions included
-- **Single Request** - All trace data submitted in one efficient gRPC call
+- **Strict Ordering** - Flush calls maintain strict ordering even when async
 
-## Quick Start
+## Quick Start (Auto-Flush - Default)
 
 ```typescript
 import { ParallaxClient } from '@miradorlabs/parallax-web';
 
-// API key is required, gateway URL is optional
 const client = new ParallaxClient('your-api-key');
 
-// Create and submit a trace
-const traceId = await client.trace('SwapExecution')
+const trace = client.trace({ name: 'SwapExecution' })
   .addAttribute('from', '0xabc...')
-  .addAttribute('slippage', { bps: 50, tolerance: 'auto' })  // objects are stringified
   .addTags(['dex', 'swap'])
-  .addEvent('quote_received', { provider: 'Uniswap' })
-  .addEvent('transaction_signed')
-  .setTxHint('0xtxhash...', 'ethereum')  // optional
-  .create();
+  .addEvent('quote_received');
+// → CreateTrace sent after 50ms of inactivity
 
-console.log('Trace ID:', traceId);
+trace.addEvent('transaction_signed')
+     .addTxHint('0xtxhash...', 'ethereum');
+// → UpdateTrace sent after 50ms of inactivity
+
+// You can still call flush() explicitly to send immediately
+trace.addEvent('confirmed');
+trace.flush();  // → UpdateTrace sent immediately
+```
+
+## Manual Flush Mode
+
+```typescript
+import { ParallaxClient } from '@miradorlabs/parallax-web';
+
+const client = new ParallaxClient('your-api-key');
+
+const trace = client.trace({ name: 'SwapExecution', autoFlush: false })
+  .addAttribute('from', '0xabc...')
+  .addTags(['dex', 'swap'])
+  .addEvent('quote_received');
+
+trace.flush();  // → CreateTrace
+
+trace.addEvent('transaction_signed')
+     .addTxHint('0xtxhash...', 'ethereum');
+
+trace.flush();  // → UpdateTrace
+```
+
+## Immediate Flush Mode
+
+Set `flushPeriodMs: 0` to flush immediately on every SDK call (no batching):
+
+```typescript
+import { ParallaxClient } from '@miradorlabs/parallax-web';
+
+const client = new ParallaxClient('your-api-key');
+
+const trace = client.trace({ name: 'SwapExecution', flushPeriodMs: 0 })
+  .addAttribute('from', '0xabc...');  // → CreateTrace sent immediately
+
+trace.addEvent('transaction_signed'); // → UpdateTrace sent immediately
+trace.addTxHint('0x...', 'ethereum'); // → UpdateTrace sent immediately
 ```
 
 ## API Reference
@@ -46,36 +84,48 @@ The main client for interacting with the Parallax Gateway.
 #### Constructor
 
 ```typescript
-new ParallaxClient(apiKey: string, apiUrl?: string)
+new ParallaxClient(apiKey: string, options?: ParallaxClientOptions)
 ```
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `apiKey` | `string` | Yes | API key for authentication (sent as `x-parallax-api-key` header) |
-| `apiUrl` | `string` | No | Gateway URL (defaults to `https://parallax-gateway.dev.mirador.org:443`) |
+| `options` | `ParallaxClientOptions` | No | Configuration options |
+
+#### Options
+
+```typescript
+interface ParallaxClientOptions {
+  apiUrl?: string;  // Gateway URL (defaults to parallax-gateway-dev.mirador.org:443)
+}
+```
 
 #### Methods
 
-##### `trace(name?, includeClientMeta?)`
+##### `trace(options?)`
 
 Creates a new trace builder.
 
 ```typescript
-const trace = client.trace('MyTrace');  // client metadata included by default
-const trace = client.trace();           // name is optional (defaults to empty string)
-// Or explicitly disable client metadata: client.trace('MyTrace', false)
+const trace = client.trace({ name: 'MyTrace' });
+const trace = client.trace({ name: 'MyTrace', autoFlush: false });
+const trace = client.trace({ autoFlush: false, flushPeriodMs: 100 });
 ```
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `name` | `string` | `''` | Optional name of the trace |
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | `undefined` | Optional name of the trace |
+| `autoFlush` | `boolean` | `true` | Auto-flush after period of inactivity |
+| `flushPeriodMs` | `number` | `50` | Debounce period in ms (0 = immediate flush on every call) |
 | `includeClientMeta` | `boolean` | `true` | Include browser/OS metadata |
+| `maxRetries` | `number` | `3` | Maximum retry attempts on network failure |
+| `retryBackoff` | `number` | `1000` | Base delay in ms for exponential backoff (doubles each retry) |
 
 Returns: `ParallaxTrace` builder instance
 
 ### ParallaxTrace (Builder)
 
-Fluent builder for constructing traces. All methods return `this` for chaining.
+Fluent builder for constructing traces. All builder methods return `this` for chaining.
 
 #### `addAttribute(key, value)`
 
@@ -109,7 +159,7 @@ trace.addTag('transaction')
      .addTags(['ethereum', 'send'])
 ```
 
-#### `addEvent(name, details?)`
+#### `addEvent(name, details?, timestamp?)`
 
 Add an event with optional details (string or object).
 
@@ -119,12 +169,13 @@ trace.addEvent('wallet_connected', { wallet: 'MetaMask' })
      .addEvent('transaction_confirmed', { blockNumber: 12345 })
 ```
 
-#### `setTxHint(txHash, chain, details?)`
+#### `addTxHint(txHash, chain, details?)`
 
-Set the transaction hash hint for blockchain correlation.
+Add a transaction hash hint for blockchain correlation. Multiple hints can be added.
 
 ```typescript
-trace.setTxHint('0x123...', 'ethereum', 'Main transaction')
+trace.addTxHint('0x123...', 'ethereum', 'Main transaction')
+     .addTxHint('0x456...', 'polygon', 'Bridge transaction')
 ```
 
 | Parameter | Type | Description |
@@ -133,15 +184,26 @@ trace.setTxHint('0x123...', 'ethereum', 'Main transaction')
 | `chain` | `ChainName` | Chain name: 'ethereum' \| 'polygon' \| 'arbitrum' \| 'base' \| 'optimism' \| 'bsc' |
 | `details` | `string` | Optional details about the transaction |
 
-#### `create()`
+#### `flush()`
 
-Submit the trace to the gateway.
+Flush pending data to the gateway. Fire-and-forget - returns immediately but maintains strict ordering.
+
+- First flush calls `CreateTrace`
+- Subsequent flushes call `UpdateTrace`
 
 ```typescript
-const traceId = await trace.create();
+trace.flush();
 ```
 
-Returns: `Promise<string | undefined>` - The trace ID if successful, undefined if failed
+Returns: `void`
+
+#### `getTraceId()`
+
+Get the trace ID (available after first flush completes).
+
+```typescript
+const traceId = trace.getTraceId();  // string | null
+```
 
 ## Complete Example: Transaction Tracking
 
@@ -151,34 +213,27 @@ import { ParallaxClient } from '@miradorlabs/parallax-web';
 const client = new ParallaxClient('your-api-key');
 
 async function handleWalletTransaction(userAddress: string, recipientAddress: string, amount: string) {
-  // Build trace with all transaction details (client metadata included by default)
-  const traceId = await client.trace('SendETH')
+  const trace = client.trace({ name: 'SendETH' })
     .addAttribute('from', userAddress)
     .addAttribute('to', recipientAddress)
     .addAttribute('value', amount)
-    .addAttribute('network', 'ethereum')
     .addTags(['transaction', 'send', 'ethereum'])
-    .addEvent('wallet_connected', { wallet: 'MetaMask' })
-    .addEvent('transaction_initiated')
-    .addEvent('user_signed')
-    .addEvent('transaction_sent', {
-      txHash: receipt.hash,
-      blockNumber: receipt.blockNumber,
-      gasUsed: receipt.gasUsed,
-      success: true
-    })
-    .setTxHint(receipt.hash, 'ethereum')
-    .create();
-
-  if (traceId) {
-    console.log('Trace ID:', traceId);
-  }
+    .addEvent('wallet_connected', { wallet: 'MetaMask' });
+  // → CreateTrace sent automatically
+
+  trace.addEvent('user_signed');
+
+  const receipt = await sendTransaction();
+
+  trace.addEvent('transaction_sent', { txHash: receipt.hash })
+       .addTxHint(receipt.hash, 'ethereum');
+  // → UpdateTrace sent automatically
 }
 ```
 
 ## Automatic Client Metadata Collection
 
-When `includeClientMeta: true` is set, the SDK automatically collects:
+When `includeClientMeta: true` is set (default), the SDK automatically collects:
 
 | Metadata | Description |
 |----------|-------------|
@@ -219,6 +274,8 @@ Full TypeScript support with exported types:
 import {
   ParallaxClient,
   ParallaxTrace,
+  ParallaxClientOptions,
+  TraceOptions,
   ChainName,  // 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bsc'
 } from '@miradorlabs/parallax-web';
 ```

package/dist/index.d.ts

@@ -1,7 +1,34 @@
 import * as mirador_gateway_parallax_web_proto_gateway_parallax_v1_parallax_gateway_pb from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
-import { CreateTraceRequest, CreateTraceResponse } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
+import { CreateTraceRequest, CreateTraceResponse, UpdateTraceRequest, UpdateTraceResponse } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
 export { CreateTraceRequest, CreateTraceResponse } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
 
+/**
+ * TypeScript interfaces for the Parallax SDK
+ */
+/**
+ * Options for ParallaxClient constructor
+ */
+interface ParallaxClientOptions {
+    /** Gateway URL (defaults to parallax-gateway-dev.mirador.org:443) */
+    apiUrl?: string;
+}
+/**
+ * Options for creating a trace
+ */
+interface TraceOptions {
+    /** Trace name */
+    name?: string;
+    /** Enable auto-flush mode (default: true) */
+    autoFlush?: boolean;
+    /** Debounce period in ms before auto-flush triggers (default: 50) */
+    flushPeriodMs?: number;
+    /** Include browser/OS metadata in first flush (default: true) */
+    includeClientMeta?: boolean;
+    /** Maximum number of retry attempts on failure (default: 3) */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff between retries (default: 1000) */
+    retryBackoff?: number;
+}
 /**
  * Supported chain names (maps to Chain enum in proto)
  */
@@ -17,20 +44,44 @@ type ChainName = 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bs
  */
 interface TraceSubmitter {
     _sendTrace(request: CreateTraceRequest): Promise<CreateTraceResponse>;
+    _updateTrace(request: UpdateTraceRequest): Promise<UpdateTraceResponse>;
+}
+/** Options passed to ParallaxTrace constructor (with defaults applied) */
+interface ResolvedTraceOptions {
+    name?: string;
+    autoFlush: boolean;
+    flushPeriodMs: number;
+    includeClientMeta: boolean;
+    maxRetries: number;
+    retryBackoff: number;
 }
 /**
- * Builder class for constructing traces with method chaining
- * Automatically handles web-specific features like client metadata
+ * Builder class for constructing traces with method chaining.
+ * Supports auto-flush mode (default) where data is automatically sent after a period of inactivity,
+ * or manual flush mode where you explicitly call flush().
  */
 declare class ParallaxTrace {
-    private name;
-    private attributes;
-    private tags;
-    private events;
-    private txHashHint?;
+    private name?;
     private client;
     private includeClientMeta;
-    constructor(client: TraceSubmitter, name?: string, includeClientMeta?: boolean);
+    private autoFlush;
+    private flushPeriodMs;
+    private flushTimer;
+    private maxRetries;
+    private retryBackoff;
+    private traceId;
+    private pendingAttributes;
+    private pendingTags;
+    private pendingEvents;
+    private pendingTxHashHints;
+    private flushQueue;
+    constructor(client: TraceSubmitter, options: ResolvedTraceOptions);
+    /**
+     * Schedule an auto-flush after the configured period.
+     * Resets the timer on each call.
+     * If flushPeriodMs is 0, flushes immediately on every call.
+     */
+    private scheduleFlush;
     /**
      * Add an attribute to the trace
      * @param key Attribute key
@@ -67,18 +118,49 @@ declare class ParallaxTrace {
      */
     addEvent(eventName: string, details?: string | object, timestamp?: Date): this;
     /**
-     * Set the transaction hash hint for blockchain correlation
+     * Add a transaction hash hint for blockchain correlation.
+     * Multiple hints can be added to the same trace.
      * @param txHash Transaction hash
      * @param chain Chain name (e.g., "ethereum", "polygon", "base")
      * @param details Optional details about the transaction
      * @returns This trace builder for chaining
      */
-    setTxHint(txHash: string, chain: ChainName, details?: string): this;
+    addTxHint(txHash: string, chain: ChainName, details?: string): this;
+    /**
+     * Flush pending data to the gateway.
+     * Fire-and-forget - returns immediately but maintains strict ordering of requests.
+     * First flush calls CreateTrace, subsequent flushes call UpdateTrace.
+     */
+    flush(): void;
+    /**
+     * Build TraceData from pending state
+     */
+    private buildTraceData;
+    /**
+     * Sleep for the specified duration
+     */
+    private sleep;
+    /**
+     * Execute an operation with exponential backoff retry
+     */
+    private retryWithBackoff;
+    /**
+     * Send CreateTrace request
+     */
+    private createTrace;
     /**
-     * Create and submit the trace to the gateway
-     * @returns The trace ID if successful, undefined if failed
+     * Send UpdateTrace request
      */
-    create(): Promise<string | undefined>;
+    private updateTrace;
+    /**
+     * Clear all pending data
+     */
+    private clearPending;
+    /**
+     * Get the trace ID (available after first flush completes)
+     * @returns The trace ID or null if not yet created
+     */
+    getTraceId(): string | null;
 }
 
 /**
@@ -91,35 +173,20 @@ declare class ParallaxClient {
     /**
      * Create a new ParallaxClient instance
      * @param apiKey Required API key for authentication (sent as x-parallax-api-key header)
-     * @param apiUrl Optional gateway URL (defaults to parallax-gateway.dev.mirador.org:443)
-     */
-    constructor(apiKey: string, apiUrl?: string);
-    /**
-     * Internal method to send trace to gateway
-     * @internal
+     * @param options Optional configuration options
      */
+    constructor(apiKey: string, options?: ParallaxClientOptions);
+    /** @internal */
     _sendTrace(request: CreateTraceRequest): Promise<mirador_gateway_parallax_web_proto_gateway_parallax_v1_parallax_gateway_pb.CreateTraceResponse>;
+    /** @internal */
+    _updateTrace(request: UpdateTraceRequest): Promise<mirador_gateway_parallax_web_proto_gateway_parallax_v1_parallax_gateway_pb.UpdateTraceResponse>;
     /**
      * Create a new trace builder
      *
-     * Example usage:
-     * ```typescript
-     * const response = await client.trace("swap_execution")
-     *   .addAttribute("user", "0xabc...")
-     *   .addAttribute("slippage_bps", 25)
-     *   .addTag("dex")
-     *   .addTag("swap")
-     *   .addEvent("wallet_connected", { wallet: "MetaMask" })
-     *   .addEvent("quote_received")
-     *   .setTxHint("0x123...", "ethereum")
-     *   .create();
-     * ```
-     *
-     * @param name Optional name of the trace (defaults to empty string)
-     * @param includeClientMeta Optional flag to automatically include client metadata
+     * @param options Trace configuration options
      * @returns A ParallaxTrace builder instance
      */
-    trace(name?: string, includeClientMeta?: boolean): ParallaxTrace;
+    trace(options?: TraceOptions): ParallaxTrace;
 }
 
 export { ParallaxClient, ParallaxTrace };