@miradorlabs/parallax-web 1.0.6 → 1.0.7

package/src/parallax/index.ts

@@ -2,20 +2,11 @@
 import {
   CreateTraceRequest,
   CreateTraceResponse,
-  StartSpanRequest,
-  StartSpanResponse,
-  FinishSpanRequest,
-  FinishSpanResponse,
-  AddSpanEventRequest,
-  AddSpanEventResponse,
-  AddSpanErrorRequest,
-  AddSpanErrorResponse,
-  AddSpanHintRequest,
-  AddSpanHintResponse,
 } from "mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb";
 import { ParallaxGatewayServiceClient } from "mirador-gateway-parallax-web/proto/gateway/parallax/v1/Parallax_gatewayServiceClientPb";
+import { Timestamp } from "google-protobuf/google/protobuf/timestamp_pb";
 
-const GRPC_GATEWAY_API_URL = "https://gateway-parallax-dev.platform.svc.cluster.local:50053";
+const GRPC_GATEWAY_API_URL = "https://parallax-gateway.dev.mirador.org:443";
 
 const debugIssue = (trace: string, error: Error) => {
   // Handle our own debugging / logging here
@@ -176,187 +167,209 @@ class ParallaxClient {
   }
 
   /**
-   * Create a StartSpanRequest with optional attributes and client metadata
-   * @param traceId trace id to associate the span with
-   * @param name name of the span
-   * @param parentSpanId (optional) create a span off a parent span id
-   * @param attr (optional) attributes to add to the span
-   * @param includeClientMeta (optional) flag to include client metadata (ip, browser, os, etc)
-   * @returns 
+   * 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")
+   *   .submit("0x123...", "ethereum");
+   * ```
+   *
+   * @param name The name of the trace
+   * @param includeClientMeta Optional flag to automatically include client metadata
+   * @returns A ParallaxTrace builder instance
    */
-  async createStartSpanRequest({ traceId, name, parentSpanId, attr, includeClientMeta = false}: {traceId: string, name: string, parentSpanId?: string, attr?: { [key: string]: string }, includeClientMeta?: boolean}): Promise<StartSpanRequest> {
-    const startSpanReq = new StartSpanRequest();
-    startSpanReq.setTraceId(traceId);
-    startSpanReq.setName(name);
-    if (parentSpanId) {
-      startSpanReq.setParentSpanId(parentSpanId);
-    }
-    const spanAttrs = startSpanReq.getAttributesMap();
+  trace(name: string, includeClientMeta: boolean = false): ParallaxTrace {
+    return new ParallaxTrace(this, name, includeClientMeta);
+  }
 
-    if (attr) {
-      Object.entries(attr).forEach(([key, value]) => {
-        if (key.includes('client.')) {
-          console.warn(`Attribute key "${key}" is reserved for client metadata. It will be prefixed with "custom."`);
-        } else {
-          spanAttrs.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
-        }
-      });
-    }
-    try {
-      if (includeClientMeta) {
-        const clientMetadata = await this.getClientMetadata();
-        Object.entries(clientMetadata).forEach(([key, value]) => {
-          spanAttrs.set(`client.${key}`, value);
-        });
-      }
-    } catch (error) {
-      console.error('Error gathering client metadata for span:', error);
-    }
-    return startSpanReq;
+}
+
+/**
+ * Builder class for constructing traces with method chaining
+ * Automatically handles web-specific features like client metadata
+ */
+class ParallaxTrace {
+  private name: string;
+  private attributes: { [key: string]: string } = {};
+  private tags: string[] = [];
+  private events: Array<{ eventName: string; details?: string; timestamp: Date }> = [];
+  private txHashHint?: {
+    txHash: string;
+    chainId: string;
+    details?: string;
+    timestamp: Date;
+  };
+  private client: ParallaxClient;
+  private includeClientMeta: boolean;
+
+  constructor(client: ParallaxClient, name: string, includeClientMeta: boolean = false) {
+    this.client = client;
+    this.name = name;
+    this.includeClientMeta = includeClientMeta;
   }
 
   /**
-   * Start a new span within a trace
-   * @param params Parameters to start a new span
+   * Add an attribute to the trace
+   * @param key Attribute key
+   * @param value Attribute value (will be converted to string)
+   * @returns This trace builder for chaining
    */
-  async startSpan(params: StartSpanRequest): Promise<StartSpanResponse> {
-    try {
-      return await this.client.startSpan(params, null);
-    } catch (_error) {
-      debugIssue("startSpan", new Error('Error starting span'));
-      throw _error;
-    }
+  addAttribute(key: string, value: string | number | boolean): this {
+    this.attributes[key] = String(value);
+    return this;
   }
 
   /**
-   * Create a FinishSpanRequest
-   * @param params Parameters to finish a span - traceId, spanId, status (optional) (success, errorMessage) 
-   * @returns FinishSpanRequest
+   * Add multiple attributes to the trace
+   * @param attributes Object containing key-value pairs
+   * @returns This trace builder for chaining
    */
-  createFinishSpanRequest({ traceId, spanId, status }: { traceId: string, spanId: string, status?: { success: boolean, errorMessage: string } }): FinishSpanRequest {
-    const request = new FinishSpanRequest();
-    request.setTraceId(traceId);
-    request.setSpanId(spanId);
-    if (status !== undefined) {
-      const spanStatus = new FinishSpanRequest.SpanStatus();
-      spanStatus.setCode(status.success ? FinishSpanRequest.SpanStatus.StatusCode.STATUS_CODE_OK : FinishSpanRequest.SpanStatus.StatusCode.STATUS_CODE_ERROR);
-      if (status.errorMessage) {
-        spanStatus.setMessage(status.errorMessage);
-      }
-      request.setStatus(spanStatus);
+  addAttributes(attributes: { [key: string]: string | number | boolean }): this {
+    for (const [key, value] of Object.entries(attributes)) {
+      this.attributes[key] = String(value);
     }
-    return request;
+    return this;
   }
 
   /**
-   * Finish a span within a trace
-   * @param params Parameters to finish a span
+   * Add a tag to the trace
+   * @param tag Tag to add
+   * @returns This trace builder for chaining
    */
-  async finishSpan(params: FinishSpanRequest): Promise<FinishSpanResponse> {
-    try {
-      return await this.client.finishSpan(params, null);
-    } catch (_error) {
-      debugIssue("finishSpan", new Error('Error finishing span'));
-      throw _error;
-    }
+  addTag(tag: string): this {
+    this.tags.push(tag);
+    return this;
   }
 
   /**
-   * Creates the add span event request
-   * @param params - Parameters to create an AddSpanEventRequest - traceId, spanId, eventName, attr (optional) 
-   * @returns AddSpanEventRequest
+   * Add multiple tags to the trace
+   * @param tags Array of tags to add
+   * @returns This trace builder for chaining
    */
-  createAddSpanEventRequest({ traceId, spanId, eventName, attr }: { traceId: string, spanId: string, eventName: string,  attr?: { [key: string]: string } }): AddSpanEventRequest {
-    const request = new AddSpanEventRequest();
-    request.setTraceId(traceId);
-    request.setSpanId(spanId);
-    request.setEventName(eventName);
-    const eventAttrs = request.getAttributesMap();
-    if (attr) {
-      Object.entries(attr).forEach(([key, value]) => {
-        eventAttrs.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
-      });
-    }
-    eventAttrs.set('timestamp', new Date().toISOString());
-    return request;
+  addTags(tags: string[]): this {
+    this.tags.push(...tags);
+    return this;
   }
 
   /**
-   * Add an event to a span
-   * @param params Parameters to add an event to a span
+   * 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)
+   * @returns This trace builder for chaining
    */
-  async addSpanEvent(params: AddSpanEventRequest): Promise<AddSpanEventResponse> {
-    try {
-      return await this.client.addSpanEvent(params, null);
-    } catch (_error) {
-      debugIssue("addSpanEvent", new Error('Error adding span event'));
-      throw _error;
-    }
+  addEvent(eventName: string, details?: string | object, timestamp?: Date): this {
+    const detailsString = typeof details === 'object' && details !== null
+      ? JSON.stringify(details)
+      : details;
+
+    this.events.push({
+      eventName,
+      details: detailsString,
+      timestamp: timestamp || new Date(),
+    });
+    return this;
   }
 
   /**
-   * Creates the add span error request
-   * @param params - params used to generate the error request ( traceid, span id, error message, error type, stack trace)
-   * @returns AddSpanErrorRequest
+   * Set or update the transaction hash hint
+   * @param txHash Transaction hash
+   * @param chainId Chain ID (e.g., "ethereum", "polygon")
+   * @param details Optional details about the transaction
+   * @param timestamp Optional timestamp (defaults to current time)
+   * @returns This trace builder for chaining
    */
-  createAddSpanErrorRequest({ traceId, spanId, errorMessage, errorType, stackTrace }: { traceId: string, spanId: string, errorMessage: string, errorType?: string, stackTrace?: string }): AddSpanErrorRequest {
-    const request = new AddSpanErrorRequest();
-    request.setTraceId(traceId);
-    request.setSpanId(spanId);
-    request.setMessage(errorMessage);
-    if (errorType) {
-      request.setErrorType(errorType);
-    }
-    if (stackTrace) {
-      request.setStackTrace(stackTrace);
-    }
-    return request;
+  setTxHash(txHash: string, chainId: string, details?: string, timestamp?: Date): this {
+    this.txHashHint = {
+      txHash,
+      chainId,
+      details,
+      timestamp: timestamp || new Date(),
+    };
+    return this;
   }
 
   /**
-   * Add an error to a span
-   * @param params Parameters to add an error to a span
+   * Submit the trace without a transaction hash hint (if not already set via setTxHash)
+   * @returns Response from the create trace operation
    */
-  async addSpanError(params: AddSpanErrorRequest): Promise<AddSpanErrorResponse> {
-    try {
-      return await this.client.addSpanError(params, null);
-    } catch (_error) {
-      debugIssue("addSpanError", new Error('Error adding span error'));
-      throw _error;
-    }
-  }
+  async submit(): Promise<CreateTraceResponse>;
 
   /**
-   * Creates the add span hint request
-   * @param params - params used to generate the span hint (trace id, parentSpanId, txHash and chainId)
-   * @returns AddSpanHintRequest
+   * Submit the trace with a transaction hash hint (overrides any previously set via setTxHash)
+   * @param txHash Transaction hash
+   * @param chainId Chain ID (e.g., "ethereum", "polygon")
+   * @param details Optional details about the transaction
+   * @returns Response from the create trace operation
    */
-  createAddSpanHintRequest({ traceId, parentSpanId, txHash, chainId }: { traceId: string, parentSpanId: string, txHash?: string, chainId?: number }): AddSpanHintRequest {
-    const hintReq = new AddSpanHintRequest();
-    hintReq.setTraceId(traceId);
-    hintReq.setParentSpanId(parentSpanId);
-
-    if (txHash && chainId !== undefined) {
-      const chainTxReq = new AddSpanHintRequest.ChainTransaction();
-      chainTxReq.setTxHash(txHash);
-      chainTxReq.setChainId(chainId);
-      hintReq.setChainTransaction(chainTxReq);
+  async submit(txHash: string, chainId: string, details?: string): Promise<CreateTraceResponse>;
+
+  async submit(txHash?: string, chainId?: string, details?: string): Promise<CreateTraceResponse> {
+    // If txHash and chainId are provided in submit(), they override any previously set txHashHint
+    const finalTxHashHint = txHash && chainId ? {
+      txHash,
+      chainId,
+      details,
+      timestamp: new Date(),
+    } : this.txHashHint;
+
+    // Build the CreateTraceRequest
+    const request = new CreateTraceRequest();
+    request.setName(this.name);
+    request.setTagsList(this.tags);
+
+    // Add attributes
+    const attrsMap = request.getAttributesMap();
+    for (const [key, value] of Object.entries(this.attributes)) {
+      attrsMap.set(key, value);
     }
-    return hintReq;
-  }
 
-  /**
-   * Add a hint to a span
-   * @param params Parameters to add a hint to a span
-   */
-  async addSpanHint(params: AddSpanHintRequest): Promise<AddSpanHintResponse> {
-    try {
-      return await this.client.addSpanHint(params, null);
-    } catch (_error) {
-      debugIssue("addSpanHint", new Error('Error adding span hint'));
-      throw _error;
+    // Add client metadata if requested
+    if (this.includeClientMeta) {
+      const clientMetadata = await this.client.getClientMetadata();
+      for (const [key, value] of Object.entries(clientMetadata)) {
+        attrsMap.set(`client.${key}`, value);
+      }
     }
+
+    // Add events
+    const eventsList: CreateTraceRequest.Event[] = [];
+    for (const event of this.events) {
+      const eventMsg = new CreateTraceRequest.Event();
+      eventMsg.setEventName(event.eventName);
+      if (event.details) {
+        eventMsg.setDetails(event.details);
+      }
+      const timestamp = new Timestamp();
+      timestamp.fromDate(event.timestamp);
+      eventMsg.setTimestamp(timestamp);
+      eventsList.push(eventMsg);
+    }
+    request.setEventsList(eventsList);
+
+    // Add transaction hash hint if present
+    if (finalTxHashHint) {
+      const txHint = new CreateTraceRequest.TxHashHint();
+      txHint.setTxHash(finalTxHashHint.txHash);
+      txHint.setChainId(finalTxHashHint.chainId);
+      if (finalTxHashHint.details) {
+        txHint.setDetails(finalTxHashHint.details);
+      }
+      const timestamp = new Timestamp();
+      timestamp.fromDate(finalTxHashHint.timestamp);
+      txHint.setTimestamp(timestamp);
+      request.setTxHashHint(txHint);
+    }
+
+    return this.client.createTrace(request);
   }
 }
 
-export { ParallaxClient };
+export { ParallaxClient, ParallaxTrace };

package/PARALLAX_SERVICE_USAGE.md

@@ -1,306 +0,0 @@
-# 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';
-```