@miradorlabs/parallax-web 1.0.7 → 2.0.0

package/example/proxy-server.js

@@ -17,7 +17,7 @@ const GATEWAY_URL = 'https://parallax-gateway.dev.mirador.org:443';
 app.use(cors({
   origin: '*',
   methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
-  allowedHeaders: ['Content-Type', 'x-grpc-web', 'x-user-agent', 'x-api-key'],
+  allowedHeaders: ['Content-Type', 'x-grpc-web', 'x-user-agent', 'x-parallax-api-key'],
   exposedHeaders: ['grpc-status', 'grpc-message'],
   credentials: true
 }));

package/index.ts

@@ -1,8 +1,5 @@
-export * from './src/parallax';
-export { GrpcWebRpc } from './src/grpc';
-
-// Export ParallaxService
-export { ParallaxService, parallaxService } from './src/parallax/ParallaxService';
+// Core SDK exports
+export { ParallaxClient, ParallaxTrace } from './src/parallax';
 
 // Re-export proto types for convenience
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miradorlabs/parallax-web",
-  "version": "1.0.7",
+  "version": "2.0.0",
   "description": "Parallax Web Client Side SDK ",
   "main": "dist/index.umd.js",
   "module": "dist/index.esm.js",
@@ -13,6 +13,8 @@
   "scripts": {
     "prepare": "npm run build",
     "build": "rm -rf dist/ && rollup -c",
+    "lint": "eslint src/ tests/",
+    "lint:fix": "eslint src/ tests/ --fix",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
@@ -47,7 +49,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.11.tgz",
+    "mirador-gateway-parallax-web": "https://storage.googleapis.com/mirador-shd-packages/gateway/parallax/grpc-web/mirador-gateway-parallax-grpc-web-1.0.13.tgz",
     "rxjs": "^7.8.2"
   },
   "author": "@mirador",

package/scripts/release.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}  Parallax Web Client Release Script${NC}"
+echo -e "${BLUE}========================================${NC}"
+echo ""
+
+# Check if logged in to npm
+echo -e "${YELLOW}Checking npm login status...${NC}"
+if ! npm whoami &> /dev/null; then
+    echo -e "${RED}Not logged in to npm. Starting login...${NC}"
+    npm login
+    echo ""
+fi
+
+NPM_USER=$(npm whoami)
+echo -e "${GREEN}Logged in as: ${NPM_USER}${NC}"
+echo ""
+
+# Get current version
+CURRENT_VERSION=$(node -p "require('./package.json').version")
+echo -e "Current version: ${YELLOW}${CURRENT_VERSION}${NC}"
+
+# Parse version components
+IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+
+# Calculate next versions
+NEXT_PATCH="$MAJOR.$MINOR.$((PATCH + 1))"
+NEXT_MINOR="$MAJOR.$((MINOR + 1)).0"
+NEXT_MAJOR="$((MAJOR + 1)).0.0"
+
+echo ""
+echo -e "${BLUE}Select release type:${NC}"
+echo -e "  ${GREEN}1)${NC} patch  → ${NEXT_PATCH}  (bug fixes)"
+echo -e "  ${GREEN}2)${NC} minor  → ${NEXT_MINOR}  (new features, backwards compatible)"
+echo -e "  ${GREEN}3)${NC} major  → ${NEXT_MAJOR}  (breaking changes)"
+echo -e "  ${GREEN}4)${NC} cancel"
+echo ""
+
+read -p "Enter choice [1-4]: " choice
+
+case $choice in
+    1)
+        RELEASE_TYPE="patch"
+        NEXT_VERSION=$NEXT_PATCH
+        ;;
+    2)
+        RELEASE_TYPE="minor"
+        NEXT_VERSION=$NEXT_MINOR
+        ;;
+    3)
+        RELEASE_TYPE="major"
+        NEXT_VERSION=$NEXT_MAJOR
+        ;;
+    4)
+        echo -e "${YELLOW}Release cancelled.${NC}"
+        exit 0
+        ;;
+    *)
+        echo -e "${RED}Invalid choice. Exiting.${NC}"
+        exit 1
+        ;;
+esac
+
+echo ""
+echo -e "${YELLOW}Releasing version ${NEXT_VERSION}...${NC}"
+echo ""
+
+# Check for uncommitted changes
+if [[ -n $(git status --porcelain) ]]; then
+    echo -e "${RED}Error: You have uncommitted changes.${NC}"
+    echo "Please commit or stash your changes before releasing."
+    git status --short
+    exit 1
+fi
+
+# Run tests
+echo -e "${BLUE}Running tests...${NC}"
+npm test
+
+# Build
+echo -e "${BLUE}Building...${NC}"
+npm run build
+
+# Bump version and create git tag
+echo -e "${BLUE}Bumping version...${NC}"
+npm version $RELEASE_TYPE
+
+# Push to git with tags
+echo -e "${BLUE}Pushing to git...${NC}"
+git push --follow-tags
+
+# Publish to npm
+echo -e "${BLUE}Publishing to npm...${NC}"
+npm publish
+
+echo ""
+echo -e "${GREEN}========================================${NC}"
+echo -e "${GREEN}  Successfully released v${NEXT_VERSION}${NC}"
+echo -e "${GREEN}========================================${NC}"

package/src/index.ts

@@ -0,0 +1,2 @@
+// Parallax Web Client SDK - Public API
+export * from './parallax';

package/src/parallax/client.ts

@@ -0,0 +1,66 @@
+/**
+ * ParallaxClient - Main client for interacting with the Parallax Gateway
+ */
+import { CreateTraceRequest } 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';
+
+const DEFAULT_API_URL = 'https://parallax-gateway.dev.mirador.org:443';
+
+/**
+ * Main client for interacting with the Parallax Gateway API
+ */
+export class ParallaxClient {
+  public apiUrl: string;
+  public apiKey: string;
+  private client: ParallaxGatewayServiceClient;
+
+  /**
+   * 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)
+   */
+  constructor(apiKey: string, apiUrl?: string) {
+    this.apiKey = apiKey;
+    this.apiUrl = 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
+   */
+  async _sendTrace(request: CreateTraceRequest) {
+    const metadata = { 'x-parallax-api-key': this.apiKey };
+    return await this.client.createTrace(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
+   * @returns A ParallaxTrace builder instance
+   */
+  trace(name: string = '', includeClientMeta: boolean = true): ParallaxTrace {
+    return new ParallaxTrace(this, name, includeClientMeta);
+  }
+}

package/src/parallax/index.ts

@@ -1,375 +1,25 @@
-// Parallax SDK Web Client
-import {
-  CreateTraceRequest,
-  CreateTraceResponse,
-} 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://parallax-gateway.dev.mirador.org:443";
-
-const debugIssue = (trace: string, error: Error) => {
-  // Handle our own debugging / logging here
-  console.error(`[ParallaxClient][${trace}] Error:`, error);
-}
-
-class ParallaxClient {
-  public apiUrl: string = GRPC_GATEWAY_API_URL;
-  private client: ParallaxGatewayServiceClient;
-
-  constructor(public apiKey?: string, apiUrl?: string) {
-    if (apiUrl) {
-      this.apiUrl = apiUrl;
-    }
-
-    // Create credentials object with API key if provided
-    const credentials = apiKey ? { 'x-api-key': apiKey } : undefined;
-
-    // Initialize the gRPC-Web client
-    this.client = new ParallaxGatewayServiceClient(this.apiUrl, credentials);
-  }
-
-  /**
-   * Gather client metadata for traces/spans
-   * Returns a metadata object with client environment details
-   * This includes browser, OS, screen size, IP address, and more
-   * @returns metadata
-   */
-  async getClientMetadata(): Promise<{ [key: string]: string }> {
-    const metadata: { [key: string]: string } = {};
-    // Browser info
-    metadata.userAgent = navigator.userAgent;
-    metadata.platform = navigator.platform;
-    metadata.language = navigator.language;
-
-    // Screen info
-    metadata.screenWidth = window.screen.width.toString();
-    metadata.screenHeight = window.screen.height.toString();
-    metadata.viewportWidth = window.innerWidth.toString();
-    metadata.viewportHeight = window.innerHeight.toString();
-
-    // Try to get IP address (non-blocking)
-    // Note: This may be blocked by Content Security Policy (CSP)
-    // If blocked, the backend should capture IP from request headers instead
-    try {
-      // Use ipify API (simple and fast JSON response)
-      const ipResponse: Response | Error = await fetch('https://api.ipify.org?format=json');
-
-      if (ipResponse && ipResponse.ok) {
-        const data = await ipResponse.json();
-        if (data && data.ip) {
-          metadata.ip = data.ip;
-        } else {
-          metadata.ip = 'client_unavailable';
-        }
-      } else {
-        metadata.ip = 'client_unavailable';
-      }
-    } catch (error) {
-      // IP lookup failed (CSP block, timeout, or network error)
-      // This is expected if CSP blocks external requests
-      // Backend should capture IP from request headers instead
-      if (error instanceof Error && error.message.includes('Content Security Policy')) {
-        console.debug('IP fetch blocked by CSP - backend will capture from headers');
-      } else {
-        console.debug('Could not fetch IP address');
-      }
-      metadata.ip = 'client_unavailable';
-    }
-
-    // Browser details (parse from user agent)
-    const ua = navigator.userAgent;
-    if (ua.includes('Chrome')) {
-      metadata.browser = 'Chrome';
-    } else if (ua.includes('Firefox')) {
-      metadata.browser = 'Firefox';
-    } else if (ua.includes('Safari')) {
-      metadata.browser = 'Safari';
-    } else if (ua.includes('Edge')) {
-      metadata.browser = 'Edge';
-    } else {
-      metadata.browser = 'Unknown';
-    }
-
-    // OS detection
-    if (ua.includes('Windows')) {
-      metadata.os = 'Windows';
-    } else if (ua.includes('Mac')) {
-      metadata.os = 'macOS';
-    } else if (ua.includes('Linux')) {
-      metadata.os = 'Linux';
-    } else if (ua.includes('Android')) {
-      metadata.os = 'Android';
-    } else if (ua.includes('iOS')) {
-      metadata.os = 'iOS';
-    } else {
-      metadata.os = 'Unknown';
-    }
-
-    // Timezone
-    metadata.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
-    metadata.timezoneOffset = new Date().getTimezoneOffset().toString();
-
-    // Page info
-    metadata.url = window.location.href;
-    metadata.referrer = document.referrer || 'direct';
-
-    return metadata;
-  }
-
-  /**
-   * Creates a CreateTraceRequest with optional attributes and client metadata
-   * @param name name of the trace
-   * @param tags optional tags for trace
-   * @param attr optional attributes for trace
-   * @param includeClientMeta optional flag to include client metadata (ip, browser, os, etc)
-   * @returns a CreateTraceRequest object to be used for the createTrace request
-   */
-  async createTraceRequest({name, tags, attr, includeClientMeta = false}: {name: string, tags?: string[], attr?: { [key: string]: string }, includeClientMeta?: boolean}): Promise<CreateTraceRequest> {
-    const createTraceReq = new CreateTraceRequest();
-    createTraceReq.setName(name);
-    if (tags) {
-      createTraceReq.setTagsList(tags);
-    }
-    const traceAttrs = createTraceReq.getAttributesMap();
-
-    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 {
-          traceAttrs.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
-        }
-      });
-    }
-    if (includeClientMeta) {
-      const clientMetadata = await this.getClientMetadata();
-      Object.entries(clientMetadata).forEach(([key, value]) => {
-        traceAttrs.set(`client.${key}`, value);
-      });
-    }
-    return createTraceReq;
-  }
-
-
-  /**
-   * Create a new trace
-   * @param params Parameters to create a new trace
-   * @returns Response from the create trace operation
-   */
-  async createTrace(params: CreateTraceRequest): Promise<CreateTraceResponse> {
-    try {
-      return await this.client.createTrace(params, null);
-    } catch (_error) {
-      debugIssue("createTrace", new Error('Error creating trace'));
-      throw _error;
-    }
-  }
-
-  /**
-   * 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
-   */
-  trace(name: string, includeClientMeta: boolean = false): ParallaxTrace {
-    return new ParallaxTrace(this, name, includeClientMeta);
-  }
-
-}
-
 /**
- * Builder class for constructing traces with method chaining
- * Automatically handles web-specific features like client metadata
+ * Parallax Web Client SDK
+ * Browser SDK for the Parallax tracing platform
  */
-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;
-  }
-
-  /**
-   * 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
-   */
-  addAttribute(key: string, value: string | number | boolean): this {
-    this.attributes[key] = String(value);
-    return this;
-  }
-
-  /**
-   * Add multiple attributes to the trace
-   * @param attributes Object containing key-value pairs
-   * @returns This trace builder for chaining
-   */
-  addAttributes(attributes: { [key: string]: string | number | boolean }): this {
-    for (const [key, value] of Object.entries(attributes)) {
-      this.attributes[key] = 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 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
-   */
-  setTxHash(txHash: string, chainId: string, details?: string, timestamp?: Date): this {
-    this.txHashHint = {
-      txHash,
-      chainId,
-      details,
-      timestamp: timestamp || new Date(),
-    };
-    return this;
-  }
-
-  /**
-   * Submit the trace without a transaction hash hint (if not already set via setTxHash)
-   * @returns Response from the create trace operation
-   */
-  async submit(): Promise<CreateTraceResponse>;
-
-  /**
-   * 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
-   */
-  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);
-    }
-
-    // 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, ParallaxTrace };
+// Classes
+export { ParallaxClient } from './client';
+export { ParallaxTrace } from './trace';
+
+// Types
+export type {
+  ParallaxClientConfig,
+  ClientMetadata,
+  TraceEvent,
+  TxHashHint,
+  ChainName,
+} from './types';
+
+// Metadata utilities (for advanced usage)
+export {
+  getClientMetadata,
+  detectBrowser,
+  detectOS,
+  detectDeviceType,
+} from './metadata';