@miradorlabs/parallax-web 1.0.8 → 2.0.0

package/src/parallax/metadata.ts

@@ -0,0 +1,173 @@
+/**
+ * Browser metadata collection utilities
+ */
+
+interface BrowserInfo {
+  name: string;
+  version: string;
+}
+
+interface OSInfo {
+  name: string;
+  version: string;
+}
+
+interface NetworkInformation {
+  effectiveType?: string;
+  downlink?: number;
+  saveData?: boolean;
+}
+
+/**
+ * Detect browser name and version from user agent
+ */
+export function detectBrowser(ua: string): BrowserInfo {
+  if (ua.includes('Edg/')) {
+    return {
+      name: 'Edge',
+      version: ua.match(/Edg\/(\d+(\.\d+)?)/)?.[1] || 'unknown',
+    };
+  }
+  if (ua.includes('Chrome/')) {
+    return {
+      name: 'Chrome',
+      version: ua.match(/Chrome\/(\d+(\.\d+)?)/)?.[1] || 'unknown',
+    };
+  }
+  if (ua.includes('Firefox/')) {
+    return {
+      name: 'Firefox',
+      version: ua.match(/Firefox\/(\d+(\.\d+)?)/)?.[1] || 'unknown',
+    };
+  }
+  if (ua.includes('Safari/') && !ua.includes('Chrome')) {
+    return {
+      name: 'Safari',
+      version: ua.match(/Version\/(\d+(\.\d+)?)/)?.[1] || 'unknown',
+    };
+  }
+  return { name: 'Unknown', version: 'unknown' };
+}
+
+/**
+ * Detect operating system name and version from user agent
+ */
+export function detectOS(ua: string): OSInfo {
+  if (ua.includes('Windows NT')) {
+    const ntVersion = ua.match(/Windows NT (\d+\.\d+)/)?.[1];
+    return {
+      name: 'Windows',
+      version: ntVersion === '10.0' ? '10/11' : ntVersion || 'unknown',
+    };
+  }
+  if (ua.includes('Mac OS X')) {
+    return {
+      name: 'macOS',
+      version: ua.match(/Mac OS X (\d+[._]\d+)/)?.[1]?.replace('_', '.') || 'unknown',
+    };
+  }
+  if (ua.includes('Android')) {
+    return {
+      name: 'Android',
+      version: ua.match(/Android (\d+(\.\d+)?)/)?.[1] || 'unknown',
+    };
+  }
+  if (ua.includes('iPhone') || ua.includes('iPad')) {
+    return {
+      name: 'iOS',
+      version: ua.match(/OS (\d+[._]\d+)/)?.[1]?.replace('_', '.') || 'unknown',
+    };
+  }
+  if (ua.includes('Linux')) {
+    return { name: 'Linux', version: 'unknown' };
+  }
+  return { name: 'Unknown', version: 'unknown' };
+}
+
+/**
+ * Detect device type from user agent
+ */
+export function detectDeviceType(ua: string): 'desktop' | 'mobile' | 'tablet' {
+  if (/Mobile|Android|iPhone|iPad|iPod/i.test(ua)) {
+    return /iPad|Tablet/i.test(ua) ? 'tablet' : 'mobile';
+  }
+  return 'desktop';
+}
+
+/**
+ * Gather client metadata from the browser environment
+ * Note: IP address is captured by the backend from request headers
+ */
+export function getClientMetadata(): { [key: string]: string } {
+  const metadata: { [key: string]: string } = {};
+  const ua = navigator.userAgent;
+
+  // Browser detection
+  const browser = detectBrowser(ua);
+  metadata.browser = browser.name;
+  metadata.browserVersion = browser.version;
+
+  // OS detection
+  const os = detectOS(ua);
+  metadata.os = os.name;
+  metadata.osVersion = os.version;
+
+  // Device type
+  metadata.deviceType = detectDeviceType(ua);
+
+  // Core browser info
+  metadata.userAgent = ua;
+  metadata.language = navigator.language;
+  metadata.languages = navigator.languages?.join(',') || navigator.language;
+
+  // Screen and display
+  metadata.screenWidth = window.screen.width.toString();
+  metadata.screenHeight = window.screen.height.toString();
+  metadata.viewportWidth = window.innerWidth.toString();
+  metadata.viewportHeight = window.innerHeight.toString();
+  metadata.colorDepth = window.screen.colorDepth.toString();
+  metadata.pixelRatio = window.devicePixelRatio?.toString() || '1';
+
+  // Hardware capabilities
+  metadata.cpuCores = navigator.hardwareConcurrency?.toString() || 'unknown';
+  const nav = navigator as Navigator & { deviceMemory?: number };
+  if (nav.deviceMemory) {
+    metadata.deviceMemory = nav.deviceMemory.toString();
+  }
+
+  // Touch support
+  metadata.touchSupport = ('ontouchstart' in window || navigator.maxTouchPoints > 0).toString();
+  metadata.maxTouchPoints = navigator.maxTouchPoints?.toString() || '0';
+
+  // Connection info (Network Information API - non-standard)
+  const connection = (navigator as Navigator & { connection?: NetworkInformation }).connection;
+  if (connection) {
+    metadata.connectionType = connection.effectiveType || 'unknown';
+    if (connection.downlink) {
+      metadata.connectionSpeed = connection.downlink.toString();
+    }
+    if (connection.saveData !== undefined) {
+      metadata.dataSaver = connection.saveData.toString();
+    }
+  }
+
+  // Browser state
+  metadata.cookiesEnabled = navigator.cookieEnabled.toString();
+  metadata.online = navigator.onLine.toString();
+  metadata.doNotTrack = navigator.doNotTrack || 'unspecified';
+
+  // Timezone
+  metadata.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  metadata.timezoneOffset = new Date().getTimezoneOffset().toString();
+
+  // Page context
+  metadata.url = window.location.href;
+  metadata.origin = window.location.origin;
+  metadata.pathname = window.location.pathname;
+  metadata.referrer = document.referrer || 'direct';
+
+  // Document state
+  metadata.documentVisibility = document.visibilityState;
+
+  return metadata;
+}

package/src/parallax/trace.ts

@@ -0,0 +1,209 @@
+/**
+ * ParallaxTrace builder class for constructing traces with method chaining
+ */
+import {
+  CreateTraceRequest,
+  CreateTraceResponse,
+  Event,
+  TxHashHint as TxHashHintProto,
+  Chain,
+} from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
+import { ResponseStatus } from 'mirador-gateway-parallax-web/proto/common/v1/status_pb';
+import { Timestamp } from 'google-protobuf/google/protobuf/timestamp_pb';
+import type { TraceEvent, TxHashHint, ChainName } from './types';
+import { getClientMetadata } from './metadata';
+
+/**
+ * Maps chain names to proto Chain enum values
+ */
+const CHAIN_MAP: Record<ChainName, Chain> = {
+  ethereum: Chain.CHAIN_ETHEREUM,
+  polygon: Chain.CHAIN_POLYGON,
+  arbitrum: Chain.CHAIN_ARBITRUM,
+  base: Chain.CHAIN_BASE,
+  optimism: Chain.CHAIN_OPTIMISM,
+  bsc: Chain.CHAIN_BSC,
+};
+
+/**
+ * Interface for the client that ParallaxTrace uses to submit traces
+ * @internal
+ */
+export interface TraceSubmitter {
+  _sendTrace(request: CreateTraceRequest): Promise<CreateTraceResponse>;
+}
+
+/**
+ * Builder class for constructing traces with method chaining
+ * Automatically handles web-specific features like client metadata
+ */
+export class ParallaxTrace {
+  private name: string;
+  private attributes: { [key: string]: string } = {};
+  private tags: string[] = [];
+  private events: TraceEvent[] = [];
+  private txHashHint?: TxHashHint;
+  private client: TraceSubmitter;
+  private includeClientMeta: boolean;
+
+  constructor(client: TraceSubmitter, name: string = '', includeClientMeta: boolean = true) {
+    this.client = client;
+    this.name = name;
+    this.includeClientMeta = includeClientMeta;
+  }
+
+  /**
+   * Add an attribute to the trace
+   * @param key Attribute key
+   * @param value Attribute value (objects are stringified, primitives converted to string)
+   * @returns This trace builder for chaining
+   */
+  addAttribute(key: string, value: string | number | boolean | object): this {
+    this.attributes[key] =
+      typeof value === 'object' && value !== null
+        ? JSON.stringify(value)
+        : String(value);
+    return this;
+  }
+
+  /**
+   * Add multiple attributes to the trace
+   * @param attributes Object containing key-value pairs (objects are stringified)
+   * @returns This trace builder for chaining
+   */
+  addAttributes(attributes: { [key: string]: string | number | boolean | object }): this {
+    for (const [key, value] of Object.entries(attributes)) {
+      this.attributes[key] =
+        typeof value === 'object' && value !== null
+          ? JSON.stringify(value)
+          : String(value);
+    }
+    return this;
+  }
+
+  /**
+   * Add a tag to the trace
+   * @param tag Tag to add
+   * @returns This trace builder for chaining
+   */
+  addTag(tag: string): this {
+    this.tags.push(tag);
+    return this;
+  }
+
+  /**
+   * Add multiple tags to the trace
+   * @param tags Array of tags to add
+   * @returns This trace builder for chaining
+   */
+  addTags(tags: string[]): this {
+    this.tags.push(...tags);
+    return this;
+  }
+
+  /**
+   * 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
+   */
+  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;
+  }
+
+  /**
+   * Set the transaction hash hint for blockchain correlation
+   * @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 = {
+      txHash,
+      chain,
+      details,
+      timestamp: new Date(),
+    };
+    return this;
+  }
+
+  /**
+   * Create and submit the trace to the gateway
+   * @returns The trace ID if successful, undefined if failed
+   */
+  async create(): Promise<string | undefined> {
+    // 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);
+    }
+
+    // Add client metadata if requested
+    if (this.includeClientMeta) {
+      const clientMetadata = getClientMetadata();
+      for (const [key, value] of Object.entries(clientMetadata)) {
+        attrsMap.set(`client.${key}`, value);
+      }
+    }
+
+    // Add events
+    const eventsList: Event[] = [];
+    for (const event of this.events) {
+      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);
+    }
+    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);
+      }
+      const timestamp = new Timestamp();
+      timestamp.fromDate(this.txHashHint.timestamp);
+      txHint.setTimestamp(timestamp);
+      request.setTxHashHint(txHint);
+    }
+
+    try {
+      const response = await this.client._sendTrace(request);
+      const responseStatus = response.getStatus();
+
+      if (responseStatus?.getCode() !== ResponseStatus.StatusCode.STATUS_CODE_SUCCESS) {
+        console.log('[ParallaxTrace] Error:', responseStatus?.getErrorMessage() || 'Unknown error');
+        return undefined;
+      }
+
+      return response.getTraceId();
+    } catch (error) {
+      console.log('[ParallaxTrace] Error creating trace:', error);
+      return undefined;
+    }
+  }
+}

package/src/parallax/types.ts

@@ -0,0 +1,73 @@
+/**
+ * TypeScript interfaces for the Parallax SDK
+ */
+
+/**
+ * Configuration options for ParallaxClient
+ */
+export interface ParallaxClientConfig {
+  apiKey: string;
+  apiUrl?: string;
+}
+
+/**
+ * Client metadata collected from the browser environment
+ */
+export interface ClientMetadata {
+  browser: string;
+  browserVersion: string;
+  os: string;
+  osVersion: string;
+  deviceType: 'desktop' | 'mobile' | 'tablet';
+  userAgent: string;
+  language: string;
+  languages: string;
+  screenWidth: string;
+  screenHeight: string;
+  viewportWidth: string;
+  viewportHeight: string;
+  colorDepth: string;
+  pixelRatio: string;
+  cpuCores: string;
+  deviceMemory?: string;
+  touchSupport: string;
+  maxTouchPoints: string;
+  connectionType?: string;
+  connectionSpeed?: string;
+  dataSaver?: string;
+  cookiesEnabled: string;
+  online: string;
+  doNotTrack: string;
+  timezone: string;
+  timezoneOffset: string;
+  url: string;
+  origin: string;
+  pathname: string;
+  referrer: string;
+  documentVisibility: string;
+}
+
+/**
+ * An event to be recorded in a trace
+ */
+export interface TraceEvent {
+  eventName: string;
+  details?: string;
+  timestamp: Date;
+}
+
+/**
+ * Supported chain names (maps to Chain enum in proto)
+ */
+export type ChainName = 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bsc';
+
+/**
+ * Transaction hash hint for blockchain correlation
+ */
+export interface TxHashHint {
+  txHash: string;
+  chain: ChainName;
+  details?: string;
+  timestamp: Date;
+}
+