@miradorlabs/parallax-web 1.0.3 → 1.0.6

package/PARALLAX_SERVICE_USAGE.md

@@ -0,0 +1,306 @@
+# ParallaxService Usage Guide
+
+The `ParallaxService` provides a simplified, high-level interface for tracking transactions in web applications. It automatically manages trace lifecycle, client metadata collection, and blockchain correlation.
+
+## Features
+
+- **Automatic Root Span Creation**: When you create a trace, a root span is automatically created (no need to call `startSpan` separately)
+- **Transaction Lifecycle Management**: Track transactions from initiation to completion
+- **Automatic Client Metadata**: Optionally includes browser, OS, IP, and other client details
+- **Blockchain Integration**: Associate transaction hashes with traces for correlation
+- **Event Tracking**: Add events at any point in the transaction lifecycle
+- **Error Tracking**: Proper error handling with stack traces
+
+## Quick Start
+
+### Using the Singleton Instance
+
+```typescript
+import { parallaxService } from '@miradorlabs/parallax-web';
+
+// Start tracking a transaction
+const { traceId, rootSpanId, txId } = await parallaxService.startTransactionTrace(
+  {
+    from: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+    to: '0x8626f6940E2eb28930eFb4CeF49B2d1F2C9C1199',
+    value: '0.1',
+    network: 'ethereum',
+    walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+  },
+  'SendTransaction', // trace name
+  {
+    includeClientMeta: true, // include browser, OS, IP, etc.
+    apiKey: 'your-api-key', // optional
+    gatewayUrl: 'https://gateway-parallax-dev.mirador.org', // optional
+  }
+);
+
+// Later, when you get the transaction hash
+await parallaxService.associateTransactionHash(txId, '0xabc123...', 1);
+
+// Add events
+await parallaxService.addTransactionEvent(txId, 'wallet_signed', {
+  timestamp: new Date().toISOString(),
+});
+
+// Track errors
+try {
+  // transaction logic
+} catch (error) {
+  await parallaxService.addTransactionError(txId, error, 'TransactionError');
+}
+
+// Finish the trace
+await parallaxService.finishTransactionTrace(txId, {
+  success: true,
+});
+```
+
+### Creating Your Own Instance
+
+```typescript
+import { ParallaxService } from '@miradorlabs/parallax-web';
+
+const myService = new ParallaxService();
+// Use the same API as above
+```
+
+## API Reference
+
+### `startTransactionTrace(txData, name, options)`
+
+Starts a new transaction trace with automatic root span creation.
+
+**Parameters:**
+- `txData`: Object with transaction details
+  - `from`: Sender address (required)
+  - `to`: Recipient address (required)
+  - `value`: Transaction value (required)
+  - `network`: Network name (optional)
+  - `walletAddress`: Wallet address (optional)
+  - `additionalData`: Any extra data (optional)
+- `name`: Trace name (default: 'WalletTransaction')
+- `options`: Optional configuration
+  - `apiKey`: API key for authentication
+  - `gatewayUrl`: Custom gateway URL
+  - `includeClientMeta`: Include browser/OS metadata (default: true)
+
+**Returns:**
+```typescript
+Promise<{
+  traceId: string;
+  rootSpanId: string; // This is the automatically created root span
+  txId: string;       // Internal transaction identifier
+}>
+```
+
+### `associateTransactionHash(txId, txHash, chainId)`
+
+Associates a blockchain transaction hash with the trace for correlation.
+
+**Parameters:**
+- `txId`: Transaction identifier from `startTransactionTrace`
+- `txHash`: Blockchain transaction hash
+- `chainId`: Chain ID (e.g., 1 for Ethereum mainnet)
+
+### `addTransactionEvent(txId, eventName, attributes)`
+
+Adds an event to the transaction trace.
+
+**Parameters:**
+- `txId`: Transaction identifier
+- `eventName`: Event name (e.g., 'wallet_signed', 'sent_to_network')
+- `attributes`: Event attributes (object)
+
+### `addTransactionError(txId, error, errorType)`
+
+Adds an error to the transaction trace with stack trace support.
+
+**Parameters:**
+- `txId`: Transaction identifier
+- `error`: Error object or message
+- `errorType`: Error category (default: 'TransactionError')
+
+### `finishTransactionTrace(txId, options)`
+
+Completes the transaction trace.
+
+**Parameters:**
+- `txId`: Transaction identifier
+- `options`: Finish options
+  - `success`: Whether transaction succeeded (required)
+  - `error`: Error message if failed (optional)
+
+### `getTransactionInfo(txId)`
+
+Gets information about an active transaction.
+
+**Returns:** Transaction info object or null
+
+### `getAllActiveTransactions()`
+
+Gets all currently active transactions.
+
+**Returns:** Array of transaction info objects
+
+### `getClient(apiKey?, gatewayUrl?)`
+
+Gets the underlying `ParallaxClient` for advanced usage.
+
+## Important Note: Automatic Root Span Creation
+
+**The key difference** from previous versions: When you call `createTrace`, a root span is **automatically created** on the backend. You receive a `rootSpanId` in the response.
+
+You **do NOT need** to call `startSpan` after creating a trace anymore. The `rootSpanId` serves as the parent span for any child spans you want to create.
+
+### Example of Creating Child Spans (Optional)
+
+If you need child spans for more detailed tracking:
+
+```typescript
+// Start transaction (creates trace + root span automatically)
+const { traceId, rootSpanId, txId } = await parallaxService.startTransactionTrace(
+  txData,
+  'ComplexTransaction'
+);
+
+// Access the underlying client for advanced usage
+const client = parallaxService.getClient();
+
+// Create a child span if needed
+const childSpanReq = await client.createStartSpanRequest({
+  traceId: traceId,
+  name: 'SigningPhase',
+  parentSpanId: rootSpanId, // Use the root span as parent
+  attr: { phase: 'signing' },
+});
+
+const childSpanResponse = await client.startSpan(childSpanReq);
+const childSpanId = childSpanResponse.getSpanId();
+
+// Later, finish the child span
+const finishReq = client.createFinishSpanRequest({
+  traceId: traceId,
+  spanId: childSpanId,
+  status: { success: true, errorMessage: '' },
+});
+
+await client.finishSpan(finishReq);
+```
+
+## Client Metadata
+
+When `includeClientMeta: true`, the following metadata is automatically collected:
+- Browser (Chrome, Firefox, Safari, Edge)
+- Operating System (Windows, macOS, Linux, Android, iOS)
+- User Agent
+- Platform
+- Language
+- Screen dimensions
+- Viewport dimensions
+- Timezone
+- Page URL
+- Referrer
+- IP address (if not blocked by CSP)
+
+All metadata is prefixed with `client.` in attributes.
+
+## Environment Detection
+
+The service automatically detects the environment:
+- **Localhost/127.0.0.1**: Uses proxy endpoint `${window.location.protocol}//${window.location.host}/parallax-gateway`
+- **Production**: Uses `https://gateway-parallax-dev.mirador.org`
+
+You can override this with the `gatewayUrl` option.
+
+## Example: Complete Transaction Flow
+
+```typescript
+import { parallaxService } from '@miradorlabs/parallax-web';
+
+async function handleTransaction() {
+  let txId: string;
+
+  try {
+    // 1. Start the trace
+    const result = await parallaxService.startTransactionTrace(
+      {
+        from: userAddress,
+        to: recipientAddress,
+        value: amount,
+        network: 'ethereum',
+        walletAddress: userAddress,
+        additionalData: {
+          gasPrice: gasPrice,
+          gasLimit: gasLimit,
+        },
+      },
+      'SendETH',
+      { includeClientMeta: true }
+    );
+
+    txId = result.txId;
+
+    // 2. User signs the transaction
+    await parallaxService.addTransactionEvent(txId, 'user_signing', {});
+
+    const signedTx = await wallet.signTransaction(txData);
+
+    await parallaxService.addTransactionEvent(txId, 'transaction_signed', {});
+
+    // 3. Send to network
+    await parallaxService.addTransactionEvent(txId, 'sending_to_network', {});
+
+    const txReceipt = await provider.sendTransaction(signedTx);
+
+    // 4. Associate the transaction hash
+    await parallaxService.associateTransactionHash(
+      txId,
+      txReceipt.hash,
+      1 // Ethereum mainnet
+    );
+
+    // 5. Wait for confirmation
+    await parallaxService.addTransactionEvent(txId, 'waiting_confirmation', {
+      txHash: txReceipt.hash,
+    });
+
+    await txReceipt.wait();
+
+    // 6. Success!
+    await parallaxService.finishTransactionTrace(txId, { success: true });
+
+  } catch (error) {
+    // Track the error
+    if (txId) {
+      await parallaxService.addTransactionError(txId, error, 'TransactionError');
+      await parallaxService.finishTransactionTrace(txId, {
+        success: false,
+        error: error.message,
+      });
+    }
+    throw error;
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  CreateTraceRequest,
+  CreateTraceResponse,
+  StartSpanRequest,
+  StartSpanResponse,
+  FinishSpanRequest,
+  FinishSpanResponse,
+  AddSpanEventRequest,
+  AddSpanEventResponse,
+  AddSpanErrorRequest,
+  AddSpanErrorResponse,
+  AddSpanHintRequest,
+  AddSpanHintResponse,
+} from '@miradorlabs/parallax-web';
+```