@miradorlabs/parallax-web 2.0.1 → 2.2.0

package/example/README.md

@@ -184,7 +184,7 @@ By default, the demo connects to:
 ```javascript
 const client = new ParallaxClient(
   'demo-api-key',
-  'https://parallax-gateway.dev.mirador.org:443'
+  'https://parallax-gateway-dev.mirador.org:443'
 );
 ```
 

package/example/app.js

@@ -3,11 +3,11 @@ import { ParallaxClient } from '../dist/index.esm.js';
 
 // Initialize the client
 // Use proxy to avoid CORS issues (default)
-// To use direct connection, change to: 'https://parallax-gateway.dev.mirador.org:443'
+// To use direct connection, change to: 'https://parallax-gateway-dev.mirador.org:443'
 const USE_PROXY = true;
-const GATEWAY_URL = USE_PROXY 
+const GATEWAY_URL = USE_PROXY
   ? 'http://localhost:3001'  // Proxy server (no CORS issues)
-  : 'https://parallax-gateway.dev.mirador.org:443';  // Direct (may have CORS issues)
+  : 'https://parallax-gateway-dev.mirador.org:443';  // Direct (may have CORS issues)
 
 const client = new ParallaxClient('demo-api-key', GATEWAY_URL);
 

package/example/proxy-server.js

@@ -11,7 +11,7 @@ const app = express();
 const PORT = 3001;
 
 // Target Parallax Gateway
-const GATEWAY_URL = 'https://parallax-gateway.dev.mirador.org:443';
+const GATEWAY_URL = 'https://parallax-gateway-dev.mirador.org:443';
 
 // Enable CORS for all origins (development only)
 app.use(cors({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miradorlabs/parallax-web",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "type": "module",
   "description": "Parallax Web Client Side SDK ",
   "main": "dist/index.umd.js",
@@ -50,7 +50,7 @@
   "dependencies": {
     "google-protobuf": "^3.21.4",
     "grpc-web": "^2.0.2",
-    "mirador-gateway-parallax-web": "https://storage.googleapis.com/mirador-shd-packages/gateway/parallax/grpc-web/mirador-gateway-parallax-grpc-web-1.0.13.tgz",
+    "mirador-gateway-parallax-web": "https://storage.googleapis.com/mirador-shd-packages/gateway/parallax/grpc-web/mirador-gateway-parallax-grpc-web-1.0.14.tgz",
     "rxjs": "^7.8.2"
   },
   "author": "@mirador",

package/src/parallax/client.ts

@@ -1,11 +1,21 @@
 /**
  * ParallaxClient - Main client for interacting with the Parallax Gateway
  */
-import { CreateTraceRequest } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
+import {
+  CreateTraceRequest,
+  UpdateTraceRequest,
+} 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 { ParallaxTrace } from './trace';
+import type { ParallaxClientOptions, TraceOptions } from './types';
 
-const DEFAULT_API_URL = 'https://parallax-gateway.dev.mirador.org:443';
+// Default configuration values
+const DEFAULT_API_URL = 'https://parallax-gateway-dev.mirador.org:443';
+const DEFAULT_AUTO_FLUSH = true;
+const DEFAULT_FLUSH_PERIOD_MS = 50;
+const DEFAULT_INCLUDE_CLIENT_META = true;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RETRY_BACKOFF = 1000;
 
 /**
  * Main client for interacting with the Parallax Gateway API
@@ -18,49 +28,42 @@ export 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)
+   * @param options Optional configuration options
    */
-  constructor(apiKey: string, apiUrl?: string) {
+  constructor(apiKey: string, options?: ParallaxClientOptions) {
     this.apiKey = apiKey;
-    this.apiUrl = apiUrl || DEFAULT_API_URL;
+    this.apiUrl = options?.apiUrl || DEFAULT_API_URL;
 
-    // API key is required - always include in credentials
     const credentials = { 'x-parallax-api-key': apiKey };
-
-    // Initialize the gRPC-Web client
     this.client = new ParallaxGatewayServiceClient(this.apiUrl, credentials);
   }
 
-  /**
-   * Internal method to send trace to gateway
-   * @internal
-   */
+  /** @internal */
   async _sendTrace(request: CreateTraceRequest) {
     const metadata = { 'x-parallax-api-key': this.apiKey };
     return await this.client.createTrace(request, metadata);
   }
 
+  /** @internal */
+  async _updateTrace(request: UpdateTraceRequest) {
+    const metadata = { 'x-parallax-api-key': this.apiKey };
+    return await this.client.updateTrace(request, metadata);
+  }
+
   /**
    * 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 = true): ParallaxTrace {
-    return new ParallaxTrace(this, name, includeClientMeta);
+  trace(options?: TraceOptions): ParallaxTrace {
+    return new ParallaxTrace(this, {
+      name: options?.name,
+      autoFlush: options?.autoFlush ?? DEFAULT_AUTO_FLUSH,
+      flushPeriodMs: options?.flushPeriodMs ?? DEFAULT_FLUSH_PERIOD_MS,
+      includeClientMeta: options?.includeClientMeta ?? DEFAULT_INCLUDE_CLIENT_META,
+      maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
+      retryBackoff: options?.retryBackoff ?? DEFAULT_RETRY_BACKOFF,
+    });
   }
 }

package/src/parallax/index.ts

@@ -9,7 +9,8 @@ export { ParallaxTrace } from './trace';
 
 // Types
 export type {
-  ParallaxClientConfig,
+  ParallaxClientOptions,
+  TraceOptions,
   ClientMetadata,
   TraceEvent,
   TxHashHint,

package/src/parallax/trace.ts

@@ -4,6 +4,11 @@
 import {
   CreateTraceRequest,
   CreateTraceResponse,
+  UpdateTraceRequest,
+  UpdateTraceResponse,
+  TraceData,
+  Attributes,
+  Tags,
   Event,
   TxHashHint as TxHashHintProto,
   Chain,
@@ -31,25 +36,78 @@ const CHAIN_MAP: Record<ChainName, Chain> = {
  */
 export 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().
  */
 export class ParallaxTrace {
-  private name: string;
-  private attributes: { [key: string]: string } = {};
-  private tags: string[] = [];
-  private events: TraceEvent[] = [];
-  private txHashHint?: TxHashHint;
+  private name?: string;
   private client: TraceSubmitter;
   private includeClientMeta: boolean;
 
-  constructor(client: TraceSubmitter, name: string = '', includeClientMeta: boolean = true) {
+  // Flush configuration
+  private autoFlush: boolean;
+  private flushPeriodMs: number;
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // Retry configuration
+  private maxRetries: number;
+  private retryBackoff: number;
+
+  // State tracking
+  private traceId: string | null = null;
+  private pendingAttributes: { [key: string]: string } = {};
+  private pendingTags: string[] = [];
+  private pendingEvents: TraceEvent[] = [];
+  private pendingTxHashHints: TxHashHint[] = [];
+
+  // Queue for maintaining strict ordering of flushes
+  private flushQueue: Promise<void> = Promise.resolve();
+
+  constructor(client: TraceSubmitter, options: ResolvedTraceOptions) {
     this.client = client;
-    this.name = name;
-    this.includeClientMeta = includeClientMeta;
+    this.name = options.name;
+    this.autoFlush = options.autoFlush;
+    this.flushPeriodMs = options.flushPeriodMs;
+    this.includeClientMeta = options.includeClientMeta;
+    this.maxRetries = options.maxRetries;
+    this.retryBackoff = options.retryBackoff;
+  }
+
+  /**
+   * 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(): void {
+    if (!this.autoFlush) return;
+
+    // flushPeriodMs === 0 means flush immediately on every call
+    if (this.flushPeriodMs === 0) {
+      this.flush();
+      return;
+    }
+
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+    }
+    this.flushTimer = setTimeout(() => {
+      this.flush();
+    }, this.flushPeriodMs);
   }
 
   /**
@@ -59,10 +117,11 @@ export class ParallaxTrace {
    * @returns This trace builder for chaining
    */
   addAttribute(key: string, value: string | number | boolean | object): this {
-    this.attributes[key] =
+    this.pendingAttributes[key] =
       typeof value === 'object' && value !== null
         ? JSON.stringify(value)
         : String(value);
+    this.scheduleFlush();
     return this;
   }
 
@@ -73,11 +132,12 @@ export class ParallaxTrace {
    */
   addAttributes(attributes: { [key: string]: string | number | boolean | object }): this {
     for (const [key, value] of Object.entries(attributes)) {
-      this.attributes[key] =
+      this.pendingAttributes[key] =
         typeof value === 'object' && value !== null
           ? JSON.stringify(value)
           : String(value);
     }
+    this.scheduleFlush();
     return this;
   }
 
@@ -87,7 +147,8 @@ export class ParallaxTrace {
    * @returns This trace builder for chaining
    */
   addTag(tag: string): this {
-    this.tags.push(tag);
+    this.pendingTags.push(tag);
+    this.scheduleFlush();
     return this;
   }
 
@@ -97,7 +158,8 @@ export class ParallaxTrace {
    * @returns This trace builder for chaining
    */
   addTags(tags: string[]): this {
-    this.tags.push(...tags);
+    this.pendingTags.push(...tags);
+    this.scheduleFlush();
     return this;
   }
 
@@ -113,97 +175,238 @@ export class ParallaxTrace {
       ? JSON.stringify(details)
       : details;
 
-    this.events.push({
+    this.pendingEvents.push({
       eventName,
       details: detailsString,
       timestamp: timestamp || new Date(),
     });
+    this.scheduleFlush();
     return 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 {
-    this.txHashHint = {
+  addTxHint(txHash: string, chain: ChainName, details?: string): this {
+    this.pendingTxHashHints.push({
       txHash,
       chain,
       details,
       timestamp: new Date(),
-    };
+    });
+    this.scheduleFlush();
     return this;
   }
 
   /**
-   * Create and submit the trace to the gateway
-   * @returns The trace ID if successful, undefined if failed
+   * 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.
    */
-  async create(): Promise<string | undefined> {
-    // Build the CreateTraceRequest
-    const request = new CreateTraceRequest();
-    request.setName(this.name);
-    request.setTagsList(this.tags);
+  flush(): void {
+    // Cancel any pending auto-flush timer
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    // Check if there's anything to flush
+    const hasPendingData =
+      Object.keys(this.pendingAttributes).length > 0 ||
+      this.pendingTags.length > 0 ||
+      this.pendingEvents.length > 0 ||
+      this.pendingTxHashHints.length > 0;
 
-    // Add attributes
-    const attrsMap = request.getAttributesMap();
-    for (const [key, value] of Object.entries(this.attributes)) {
-      attrsMap.set(key, value);
+    if (!hasPendingData && this.traceId !== null) {
+      return; // Nothing to flush
     }
 
-    // Add client metadata if requested
-    if (this.includeClientMeta) {
-      const clientMetadata = getClientMetadata();
-      for (const [key, value] of Object.entries(clientMetadata)) {
-        attrsMap.set(`client.${key}`, value);
+    // Capture pending data NOW (before it changes)
+    const traceData = this.buildTraceData();
+
+    // Capture context for error reporting
+    const isCreateOp = this.traceId === null;
+    const traceName = this.name;
+
+    // Clear pending immediately so next flush doesn't re-send
+    this.clearPending();
+
+    // Chain onto the queue for strict ordering
+    // Check traceId inside the queue to ensure proper ordering
+    this.flushQueue = this.flushQueue.then(async () => {
+      if (this.traceId === null) {
+        await this.createTrace(traceData);
+      } else {
+        await this.updateTrace(traceData);
       }
+    }).catch(err => {
+      const operation = isCreateOp ? 'CreateTrace' : 'UpdateTrace';
+      const context = traceName ? ` (trace: ${traceName})` : '';
+      console.error(`[ParallaxTrace] Flush error during ${operation}${context}:`, err);
+    });
+  }
+
+  /**
+   * Build TraceData from pending state
+   */
+  private buildTraceData(): TraceData {
+    const traceData = new TraceData();
+
+    // Add pending attributes (+ client metadata on first flush)
+    const allAttrs = { ...this.pendingAttributes };
+    if (this.traceId === null && this.includeClientMeta) {
+      const clientMeta = getClientMetadata();
+      for (const [key, value] of Object.entries(clientMeta)) {
+        allAttrs[`client.${key}`] = value;
+      }
+    }
+    if (Object.keys(allAttrs).length > 0) {
+      const attrsMsg = new Attributes();
+      const attrsMap = attrsMsg.getAttributesMap();
+      for (const [key, value] of Object.entries(allAttrs)) {
+        attrsMap.set(key, value);
+      }
+      traceData.addAttributes(attrsMsg);
+    }
+
+    // Add pending tags
+    if (this.pendingTags.length > 0) {
+      const tagsMsg = new Tags();
+      tagsMsg.setTagsList(this.pendingTags);
+      traceData.addTags(tagsMsg);
     }
 
-    // Add events
-    const eventsList: Event[] = [];
-    for (const event of this.events) {
+    // Add pending events
+    for (const event of this.pendingEvents) {
       const eventMsg = new Event();
       eventMsg.setName(event.eventName);
       if (event.details) {
         eventMsg.setDetails(event.details);
       }
-      const timestamp = new Timestamp();
-      timestamp.fromDate(event.timestamp);
-      eventMsg.setTimestamp(timestamp);
-      eventsList.push(eventMsg);
+      const ts = new Timestamp();
+      ts.fromDate(event.timestamp);
+      eventMsg.setTimestamp(ts);
+      traceData.addEvents(eventMsg);
     }
-    request.setEventsList(eventsList);
-
-    // Add transaction hash hint if present
-    if (this.txHashHint) {
-      const txHint = new TxHashHintProto();
-      txHint.setTxHash(this.txHashHint.txHash);
-      txHint.setChain(CHAIN_MAP[this.txHashHint.chain]);
-      if (this.txHashHint.details) {
-        txHint.setDetails(this.txHashHint.details);
+
+    // Add pending tx hints
+    for (const hint of this.pendingTxHashHints) {
+      const hintMsg = new TxHashHintProto();
+      hintMsg.setTxHash(hint.txHash);
+      hintMsg.setChain(CHAIN_MAP[hint.chain]);
+      if (hint.details) {
+        hintMsg.setDetails(hint.details);
       }
-      const timestamp = new Timestamp();
-      timestamp.fromDate(this.txHashHint.timestamp);
-      txHint.setTimestamp(timestamp);
-      request.setTxHashHint(txHint);
+      const ts = new Timestamp();
+      ts.fromDate(hint.timestamp);
+      hintMsg.setTimestamp(ts);
+      traceData.addTxHashHints(hintMsg);
     }
 
-    try {
-      const response = await this.client._sendTrace(request);
-      const responseStatus = response.getStatus();
+    return traceData;
+  }
 
-      if (responseStatus?.getCode() !== ResponseStatus.StatusCode.STATUS_CODE_SUCCESS) {
-        console.log('[ParallaxTrace] Error:', responseStatus?.getErrorMessage() || 'Unknown error');
-        return undefined;
+  /**
+   * Sleep for the specified duration
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Execute an operation with exponential backoff retry
+   */
+  private async retryWithBackoff<T>(
+    operation: () => Promise<T>,
+    operationName: string
+  ): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (err) {
+        lastError = err as Error;
+
+        if (attempt < this.maxRetries) {
+          const delay = this.retryBackoff * Math.pow(2, attempt);
+          console.warn(
+            `[ParallaxTrace] ${operationName} failed, retrying in ${delay}ms (attempt ${attempt + 1}/${this.maxRetries})`
+          );
+          await this.sleep(delay);
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Send CreateTrace request
+   */
+  private async createTrace(traceData: TraceData): Promise<void> {
+    const request = new CreateTraceRequest();
+    if (this.name) {
+      request.setName(this.name);
+    }
+    request.setData(traceData);
+
+    try {
+      const response = await this.retryWithBackoff(
+        () => this.client._sendTrace(request),
+        'CreateTrace'
+      );
+      if (response.getStatus()?.getCode() === ResponseStatus.StatusCode.STATUS_CODE_SUCCESS) {
+        this.traceId = response.getTraceId();
+      } else {
+        console.error('[ParallaxTrace] CreateTrace failed:', response.getStatus()?.getErrorMessage());
       }
+    } catch (err) {
+      console.error('[ParallaxTrace] CreateTrace error after retries:', err);
+    }
+  }
 
-      return response.getTraceId();
-    } catch (error) {
-      console.log('[ParallaxTrace] Error creating trace:', error);
-      return undefined;
+  /**
+   * Send UpdateTrace request
+   */
+  private async updateTrace(traceData: TraceData): Promise<void> {
+    const request = new UpdateTraceRequest();
+    request.setTraceId(this.traceId!);
+    request.setData(traceData);
+
+    try {
+      const response = await this.retryWithBackoff(
+        () => this.client._updateTrace(request),
+        'UpdateTrace'
+      );
+      if (response.getStatus()?.getCode() !== ResponseStatus.StatusCode.STATUS_CODE_SUCCESS) {
+        console.error('[ParallaxTrace] UpdateTrace failed:', response.getStatus()?.getErrorMessage());
+      }
+    } catch (err) {
+      console.error('[ParallaxTrace] UpdateTrace error after retries:', err);
     }
   }
+
+  /**
+   * Clear all pending data
+   */
+  private clearPending(): void {
+    this.pendingAttributes = {};
+    this.pendingTags = [];
+    this.pendingEvents = [];
+    this.pendingTxHashHints = [];
+  }
+
+  /**
+   * Get the trace ID (available after first flush completes)
+   * @returns The trace ID or null if not yet created
+   */
+  getTraceId(): string | null {
+    return this.traceId;
+  }
 }

package/src/parallax/types.ts

@@ -3,13 +3,31 @@
  */
 
 /**
- * Configuration options for ParallaxClient
+ * Options for ParallaxClient constructor
  */
-export interface ParallaxClientConfig {
-  apiKey: string;
+export interface ParallaxClientOptions {
+  /** Gateway URL (defaults to parallax-gateway-dev.mirador.org:443) */
   apiUrl?: string;
 }
 
+/**
+ * Options for creating a trace
+ */
+export 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;
+}
+
 /**
  * Client metadata collected from the browser environment
  */