@miradorlabs/parallax-web 1.0.8 → 2.0.1

package/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)",
+      "Bash(npx jest:*)",
+      "Bash(npm install:*)",
+      "Bash(npm run build:*)",
+      "Bash(mkdir:*)",
+      "Bash(chmod:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh api:*)",
+      "Bash(npm run lint:*)"
+    ]
+  }
+}

package/.github/dependabot.yml

@@ -0,0 +1,33 @@
+version: 2
+updates:
+  # npm dependencies
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      # Group minor and patch updates together
+      minor-and-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+      # Keep major updates separate for review
+    ignore:
+      # Ignore major version updates for stability (review manually)
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "chore(ci)"

package/.github/workflows/pr.yml

@@ -0,0 +1,33 @@
+name: PR Build & Lint
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build

package/README.md

@@ -10,267 +10,168 @@ npm install @miradorlabs/parallax-web
 
 ## Features
 
-- 🚀 **ParallaxService** - High-level API for transaction tracing with automatic lifecycle management
-- 🔧 **ParallaxClient** - Low-level client for advanced use cases
-- 🌐 **Browser-optimized** - Automatic client metadata collection (browser, OS, IP, etc.)
-- ⛓️ **Blockchain integration** - Built-in support for correlating transactions with blockchain events
-- 📦 **TypeScript support** - Full type definitions included
-- 🎯 **Automatic root spans** - Creating a trace now automatically creates a root span
+- **Fluent Builder Pattern** - Method chaining for creating 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
 
-## Quick Start with ParallaxService (Recommended)
-
-The `ParallaxService` provides a simplified API for tracking transactions:
+## Quick Start
 
 ```typescript
-import { parallaxService } from '@miradorlabs/parallax-web';
-
-// Start tracking a transaction (creates trace + root span automatically)
-const { traceId, rootSpanId, txId } = await parallaxService.startTransactionTrace(
-  {
-    from: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
-    to: '0x8626f6940E2eb28930eFb4CeF49B2d1F2C9C1199',
-    value: '0.1',
-    network: 'ethereum',
-    walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
-  },
-  'SendTransaction',
-  { includeClientMeta: true } // Automatically collects browser, OS, IP, etc.
-);
-
-// Associate the blockchain transaction hash
-await parallaxService.associateTransactionHash(txId, '0xabc123...', 1);
-
-// Add events as the transaction progresses
-await parallaxService.addTransactionEvent(txId, 'wallet_signed', {
-  timestamp: new Date().toISOString(),
-});
-
-// Track errors if they occur
-try {
-  // transaction logic
-} catch (error) {
-  await parallaxService.addTransactionError(txId, error, 'TransactionError');
-}
-
-// Finish the trace when done
-await parallaxService.finishTransactionTrace(txId, { success: true });
-```
-
-### ParallaxService API
+import { ParallaxClient } from '@miradorlabs/parallax-web';
 
-#### `startTransactionTrace(txData, name, options)`
+// API key is required, gateway URL is optional
+const client = new ParallaxClient('your-api-key');
 
-Starts a new transaction trace with automatic root span creation.
+// Create and submit a trace
+const traceId = await client.trace('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();
+
+console.log('Trace ID:', traceId);
+```
 
-**Important:** When you create a trace, a root span is **automatically created** on the backend. You receive a `rootSpanId` in the response - no need to call `startSpan` separately!
+## API Reference
 
-**Parameters:**
-- `txData`: Transaction details (from, to, value, network, etc.)
-- `name`: Trace name (default: 'WalletTransaction')
-- `options`: Optional configuration
-  - `apiKey`: API key for authentication
-  - `gatewayUrl`: Custom gateway URL
-  - `includeClientMeta`: Include browser/OS metadata (default: true)
+### ParallaxClient
 
-**Returns:** `{ traceId, rootSpanId, txId }`
+The main client for interacting with the Parallax Gateway.
 
-#### Other Methods
+#### Constructor
 
-- `associateTransactionHash(txId, txHash, chainId)` - Link blockchain transaction
-- `addTransactionEvent(txId, eventName, attributes)` - Add event to trace
-- `addTransactionError(txId, error, errorType)` - Track errors with stack traces
-- `finishTransactionTrace(txId, options)` - Complete the trace
-- `getTransactionInfo(txId)` - Get active transaction info
-- `getAllActiveTransactions()` - List all active transactions
-- `getClient()` - Access underlying ParallaxClient for advanced usage
+```typescript
+new ParallaxClient(apiKey: string, apiUrl?: string)
+```
 
-See [PARALLAX_SERVICE_USAGE.md](./PARALLAX_SERVICE_USAGE.md) for comprehensive documentation.
+| 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`) |
 
-## Advanced Usage with ParallaxClient
+#### Methods
 
-For more control, use the low-level `ParallaxClient`:
+##### `trace(name?, includeClientMeta?)`
 
-### Basic Setup
+Creates a new trace builder.
 
 ```typescript
-import { ParallaxClient } from '@miradorlabs/parallax-web';
-
-// Initialize the client
-const client = new ParallaxClient('your-api-key');
-
-// Or with a custom gateway URL
-const client = new ParallaxClient('your-api-key', 'https://your-gateway.example.com:50053');
+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)
 ```
 
-### Helper Methods
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `string` | `''` | Optional name of the trace |
+| `includeClientMeta` | `boolean` | `true` | Include browser/OS metadata |
 
-The client provides helper methods to create requests easily:
+Returns: `ParallaxTrace` builder instance
 
-#### Creating a Trace
+### ParallaxTrace (Builder)
 
-```typescript
-// Use the helper method
-const createTraceReq = await client.createTraceRequest({
-  name: 'My Application Trace',
-  attr: {
-    'project.id': 'my-project',
-    'environment': 'production',
-  },
-  tags: ['web', 'user-action'],
-  includeClientMeta: true, // Includes browser, OS, IP, etc.
-});
-
-const traceResponse = await client.createTrace(createTraceReq);
-const traceId = traceResponse.getTraceId();
-const rootSpanId = traceResponse.getRootSpanId(); // Root span automatically created!
-```
+Fluent builder for constructing traces. All methods return `this` for chaining.
 
-#### Starting a Span (Child Span)
+#### `addAttribute(key, value)`
 
-Note: You only need to call `startSpan` if you want to create **child spans**. The root span is automatically created when you create a trace.
+Add a single attribute. Objects are automatically stringified.
 
 ```typescript
-// Create a child span under the root span
-const startSpanReq = await client.createStartSpanRequest({
-  traceId: traceId,
-  name: 'User Login',
-  parentSpanId: rootSpanId, // Use root span as parent
-  attr: {
-    'user.id': 'user-123',
-    'action': 'login',
-  },
-  includeClientMeta: false, // Optional
-});
-
-const spanResponse = await client.startSpan(startSpanReq);
-const spanId = spanResponse.getSpanId();
+trace.addAttribute('user', '0xabc...')
+     .addAttribute('amount', 1.5)
+     .addAttribute('config', { slippage: 50, deadline: 300 })  // stringified to JSON
 ```
 
-#### Adding Span Events
+#### `addAttributes(attrs)`
 
-```typescript
-const eventReq = client.createAddSpanEventRequest({
-  traceId: traceId,
-  spanId: spanId,
-  eventName: 'User Authenticated',
-  attr: {
-    'auth.method': 'oauth',
-    'auth.provider': 'google',
-  },
-});
-
-await client.addSpanEvent(eventReq);
-```
-
-#### Adding Span Errors
+Add multiple attributes at once. Objects are automatically stringified.
 
 ```typescript
-try {
-  // some operation
-} catch (error) {
-  const errorReq = client.createAddSpanErrorRequest({
-    traceId: traceId,
-    spanId: spanId,
-    errorMessage: error.message,
-    errorType: 'ValidationError',
-    stackTrace: error.stack,
-  });
-
-  await client.addSpanError(errorReq);
-}
+trace.addAttributes({
+  from: '0xabc...',
+  to: '0xdef...',
+  value: 1.0,
+  metadata: { source: 'web', version: '1.0' }  // stringified to JSON
+})
 ```
 
-#### Adding Span Hints (Blockchain Transactions)
+#### `addTag(tag)` / `addTags(tags)`
 
-```typescript
-const hintReq = client.createAddSpanHintRequest({
-  traceId: traceId,
-  parentSpanId: rootSpanId,
-  txHash: '0x1234567890abcdef',
-  chainId: 1, // Ethereum mainnet
-});
-
-await client.addSpanHint(hintReq);
-```
-
-#### Finishing a Span
+Add tags to categorize the trace.
 
 ```typescript
-const finishReq = client.createFinishSpanRequest({
-  traceId: traceId,
-  spanId: spanId,
-  status: {
-    success: true,
-    errorMessage: '', // or error message if failed
-  },
-});
-
-await client.finishSpan(finishReq);
+trace.addTag('transaction')
+     .addTags(['ethereum', 'send'])
 ```
 
-## Complete Example: Transaction Tracking
-
-```typescript
-import { parallaxService } from '@miradorlabs/parallax-web';
-
-async function handleWalletTransaction(userAddress, recipientAddress, amount) {
-  let txId;
+#### `addEvent(name, details?)`
 
-  try {
-    // 1. Start the trace (automatically creates root span)
-    const result = await parallaxService.startTransactionTrace(
-      {
-        from: userAddress,
-        to: recipientAddress,
-        value: amount,
-        network: 'ethereum',
-        walletAddress: userAddress,
-      },
-      'SendETH',
-      { includeClientMeta: true }
-    );
+Add an event with optional details (string or object).
 
-    txId = result.txId;
-    console.log('Trace started:', result.traceId);
+```typescript
+trace.addEvent('wallet_connected', { wallet: 'MetaMask' })
+     .addEvent('transaction_initiated')
+     .addEvent('transaction_confirmed', { blockNumber: 12345 })
+```
 
-    // 2. User signs the transaction
-    await parallaxService.addTransactionEvent(txId, 'user_signing', {});
+#### `setTxHint(txHash, chain, details?)`
 
-    const signedTx = await wallet.signTransaction(txData);
+Set the transaction hash hint for blockchain correlation.
 
-    await parallaxService.addTransactionEvent(txId, 'transaction_signed', {});
+```typescript
+trace.setTxHint('0x123...', 'ethereum', 'Main transaction')
+```
 
-    // 3. Send to network
-    await parallaxService.addTransactionEvent(txId, 'sending_to_network', {});
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `txHash` | `string` | Transaction hash |
+| `chain` | `ChainName` | Chain name: 'ethereum' \| 'polygon' \| 'arbitrum' \| 'base' \| 'optimism' \| 'bsc' |
+| `details` | `string` | Optional details about the transaction |
 
-    const txReceipt = await provider.sendTransaction(signedTx);
+#### `create()`
 
-    // 4. Associate the blockchain transaction hash
-    await parallaxService.associateTransactionHash(txId, txReceipt.hash, 1);
+Submit the trace to the gateway.
 
-    // 5. Wait for confirmation
-    await parallaxService.addTransactionEvent(txId, 'waiting_confirmation', {
-      txHash: txReceipt.hash,
-    });
+```typescript
+const traceId = await trace.create();
+```
 
-    await txReceipt.wait();
+Returns: `Promise<string | undefined>` - The trace ID if successful, undefined if failed
 
-    // 6. Success!
-    await parallaxService.finishTransactionTrace(txId, { success: true });
-    console.log('Transaction completed successfully');
+## Complete Example: Transaction Tracking
 
-  } catch (error) {
-    console.error('Transaction failed:', error);
+```typescript
+import { ParallaxClient } from '@miradorlabs/parallax-web';
 
-    if (txId) {
-      await parallaxService.addTransactionError(txId, error, 'TransactionError');
-      await parallaxService.finishTransactionTrace(txId, {
-        success: false,
-        error: error.message,
-      });
-    }
+const client = new ParallaxClient('your-api-key');
 
-    throw error;
+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')
+    .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);
   }
 }
 ```
@@ -279,47 +180,46 @@ async function handleWalletTransaction(userAddress, recipientAddress, amount) {
 
 When `includeClientMeta: true` is set, the SDK automatically collects:
 
-- **Browser**: Chrome, Firefox, Safari, Edge, etc.
-- **Operating System**: Windows, macOS, Linux, Android, iOS
-- **User Agent**: Full user agent string
-- **Platform**: Browser platform
-- **Language**: Browser language
-- **Screen**: Width and height
-- **Viewport**: Width and height
-- **Timezone**: User's timezone and offset
-- **URL**: Current page URL
-- **Referrer**: Page referrer
-- **IP Address**: Client IP (if not blocked by CSP)
-
-All metadata is prefixed with `client.` in trace attributes.
-
-## Environment Detection
-
-The SDK automatically detects the environment:
-
-- **Localhost/127.0.0.1**: Uses proxy at `${window.location.protocol}//${window.location.host}/parallax-gateway`
-- **Production**: Uses `https://gateway-parallax-dev.mirador.org`
-
-Override with the `gatewayUrl` option.
+| Metadata | Description |
+|----------|-------------|
+| `client.browser` | Chrome, Firefox, Safari, Edge |
+| `client.browserVersion` | Browser version number |
+| `client.os` | Windows, macOS, Linux, Android, iOS |
+| `client.osVersion` | Operating system version |
+| `client.deviceType` | desktop, mobile, or tablet |
+| `client.userAgent` | Full user agent string |
+| `client.language` | Primary browser language |
+| `client.languages` | All preferred languages (comma-separated) |
+| `client.screenWidth` / `client.screenHeight` | Screen dimensions |
+| `client.viewportWidth` / `client.viewportHeight` | Viewport dimensions |
+| `client.colorDepth` | Screen color depth |
+| `client.pixelRatio` | Device pixel ratio (for retina displays) |
+| `client.cpuCores` | Number of CPU cores |
+| `client.deviceMemory` | Device memory in GB (if available) |
+| `client.touchSupport` | Whether touch is supported |
+| `client.connectionType` | Network connection type (4g, 3g, wifi, etc.) |
+| `client.cookiesEnabled` | Whether cookies are enabled |
+| `client.online` | Whether browser is online |
+| `client.doNotTrack` | Do Not Track preference |
+| `client.timezone` | User's timezone |
+| `client.timezoneOffset` | Timezone offset from UTC |
+| `client.url` | Current page URL |
+| `client.origin` | Page origin |
+| `client.pathname` | Page pathname |
+| `client.referrer` | Page referrer |
+| `client.documentVisibility` | Document visibility state |
+
+Note: IP address is captured by the backend from request headers.
 
 ## TypeScript Support
 
 Full TypeScript support with exported types:
 
 ```typescript
-import type {
-  CreateTraceRequest,
-  CreateTraceResponse,
-  StartSpanRequest,
-  StartSpanResponse,
-  FinishSpanRequest,
-  FinishSpanResponse,
-  AddSpanEventRequest,
-  AddSpanEventResponse,
-  AddSpanErrorRequest,
-  AddSpanErrorResponse,
-  AddSpanHintRequest,
-  AddSpanHintResponse,
+import {
+  ParallaxClient,
+  ParallaxTrace,
+  ChainName,  // 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bsc'
 } from '@miradorlabs/parallax-web';
 ```
 
@@ -330,7 +230,6 @@ This SDK uses modern browser APIs and is compatible with:
 - ES2020+
 - Fetch API
 - Promises
-- Uint8Array
 - Modern browsers (Chrome, Firefox, Safari, Edge)
 
 For older browsers, you may need polyfills.
@@ -343,35 +242,6 @@ The package provides multiple module formats:
 - **UMD** (`dist/index.umd.js`): For browser globals and older module systems
 - **TypeScript** (`dist/index.d.ts`): Type definitions
 
-## Key Differences from Node.js Client
-
-The web client (`@miradorlabs/parallax-web`) differs from the Node.js client (`@miradorlabs/parallax`):
-
-| Feature | Web Client | Node.js Client |
-|---------|------------|----------------|
-| Transport | gRPC-Web (HTTP/1.1) | gRPC (@grpc/grpc-js) |
-| Protocol | `https://` | `http://` or `https://` |
-| Environment | Browser | Node.js |
-| Protobuf | google-protobuf (classes) | ts-proto (plain objects) |
-| API Style | `.getTraceId()` setters/getters | `.traceId` properties |
-| Client Metadata | Browser-specific | Server-specific |
-
-## Important Update: Automatic Root Span Creation
-
-**Breaking Change (v1.0.5+):**
-
-When you call `createTrace()`, a root span is now **automatically created** on the backend. The response includes:
-- `traceId`: The trace identifier
-- `rootSpanId`: The automatically created root span ID
-
-**You no longer need to:**
-- Call `startSpan()` immediately after `createTrace()`
-- Manually create the first span
-
-**When to use `startSpan()`:**
-- Only when you need **child spans** for more detailed tracking
-- Use `rootSpanId` as the `parentSpanId` for child spans
-
 ## Development
 
 ### Building
@@ -396,11 +266,6 @@ npm run release:minor  # 1.x.0
 npm run release:major  # x.0.0
 ```
 
-## Documentation
-
-- [ParallaxService Usage Guide](./PARALLAX_SERVICE_USAGE.md) - Comprehensive guide for the high-level API
-- [Examples](./examples) - More usage examples
-
 ## License
 
 ISC