@miradorlabs/parallax-web 1.0.4 → 1.0.7

package/example/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "parallax-web-demo",
+  "version": "1.0.0",
+  "description": "Interactive demo for Parallax Web SDK",
+  "type": "module",
+  "scripts": {
+    "build-sdk": "cd .. && npm run build",
+    "build": "npm run build-sdk && rollup -c",
+    "proxy": "node proxy-server.js",
+    "start": "npm run build && python3 -m http.server 8000",
+    "serve": "npm run build && npx http-server -p 8000 -o",
+    "dev": "npm run build && npx concurrently \"npm run proxy\" \"npx http-server -p 8000 -o\"",
+    "dev:no-proxy": "npm run build && npx http-server -p 8000 -o"
+  },
+  "keywords": [
+    "parallax",
+    "demo",
+    "web",
+    "tracing"
+  ],
+  "author": "@mirador",
+  "license": "ISC",
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "rollup": "^4.53.3"
+  },
+  "dependencies": {
+    "concurrently": "^9.1.0",
+    "cors": "^2.8.5",
+    "express": "^4.22.1",
+    "http-proxy-middleware": "^3.0.3"
+  }
+}

package/example/proxy-server.js

@@ -0,0 +1,86 @@
+/**
+ * Simple Express proxy server to handle CORS issues
+ * Proxies gRPC-Web requests to the Parallax Gateway
+ */
+
+import express from 'express';
+import cors from 'cors';
+import { createProxyMiddleware } from 'http-proxy-middleware';
+
+const app = express();
+const PORT = 3001;
+
+// Target Parallax Gateway
+const GATEWAY_URL = 'https://parallax-gateway.dev.mirador.org:443';
+
+// Enable CORS for all origins (development only)
+app.use(cors({
+  origin: '*',
+  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+  allowedHeaders: ['Content-Type', 'x-grpc-web', 'x-user-agent', 'x-api-key'],
+  exposedHeaders: ['grpc-status', 'grpc-message'],
+  credentials: true
+}));
+
+// Health check endpoint (before proxy)
+app.get('/health', (req, res) => {
+  res.json({
+    status: 'ok',
+    proxy: GATEWAY_URL,
+    timestamp: new Date().toISOString()
+  });
+});
+
+// Log all requests
+app.use((req, res, next) => {
+  console.log(`[${new Date().toLocaleTimeString()}] ${req.method} ${req.path}`);
+  next();
+});
+
+// Proxy all other requests to the gateway (gRPC-Web)
+app.use('/', createProxyMiddleware({
+  target: GATEWAY_URL,
+  changeOrigin: true,
+  secure: true,
+  ws: false,
+  onProxyReq: (proxyReq, req, res) => {
+    console.log(`  → Proxying to: ${GATEWAY_URL}${req.url}`);
+
+    // Forward gRPC-Web headers
+    if (req.headers['content-type']) {
+      proxyReq.setHeader('content-type', req.headers['content-type']);
+    }
+    if (req.headers['x-grpc-web']) {
+      proxyReq.setHeader('x-grpc-web', req.headers['x-grpc-web']);
+    }
+    if (req.headers['x-user-agent']) {
+      proxyReq.setHeader('x-user-agent', req.headers['x-user-agent']);
+    }
+  },
+  onProxyRes: (proxyRes, req, res) => {
+    console.log(`  ← Response: ${proxyRes.statusCode}`);
+  },
+  onError: (err, req, res) => {
+    console.error('Proxy error:', err.message);
+    res.status(500).json({
+      error: 'Proxy error',
+      message: err.message
+    });
+  }
+}));
+
+app.listen(PORT, () => {
+  console.log(`
+╔════════════════════════════════════════════════════════════╗
+║  Parallax gRPC-Web Proxy Server                            ║
+╟────────────────────────────────────────────────────────────╢
+║  Proxy running at: http://localhost:${PORT}                    ║
+║  Gateway target:   ${GATEWAY_URL}  ║
+╟────────────────────────────────────────────────────────────╢
+║  Usage:                                                    ║
+║  - All gRPC-Web requests are proxied to the gateway       ║
+║  - CORS headers are automatically added                   ║
+║  - Health check: http://localhost:${PORT}/health            ║
+╚════════════════════════════════════════════════════════════╝
+  `);
+});

package/example/rollup.config.js

@@ -0,0 +1,16 @@
+import resolve from '@rollup/plugin-node-resolve';
+
+export default {
+  input: 'app.js',
+  output: {
+    file: 'bundle.js',
+    format: 'es',
+    sourcemap: true
+  },
+  plugins: [
+    resolve({
+      browser: true,
+      preferBuiltins: false
+    })
+  ]
+};

package/index.ts

@@ -1,18 +1,11 @@
 export * from './src/parallax';
 export { GrpcWebRpc } from './src/grpc';
 
+// Export ParallaxService
+export { ParallaxService, parallaxService } from './src/parallax/ParallaxService';
+
 // Re-export proto types for convenience
 export {
   CreateTraceRequest,
   CreateTraceResponse,
-  StartSpanRequest,
-  StartSpanResponse,
-  FinishSpanRequest,
-  FinishSpanResponse,
-  AddSpanEventRequest,
-  AddSpanEventResponse,
-  AddSpanErrorRequest,
-  AddSpanErrorResponse,
-  AddSpanHintRequest,
-  AddSpanHintResponse,
 } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miradorlabs/parallax-web",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "description": "Parallax Web Client Side SDK ",
   "main": "dist/index.umd.js",
   "module": "dist/index.esm.js",
@@ -25,6 +25,7 @@
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
+    "@types/google-protobuf": "^3.15.12",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.10.1",
     "eslint": "^9.39.1",
@@ -46,7 +47,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.9.tgz",
+    "mirador-gateway-parallax-web": "https://storage.googleapis.com/mirador-shd-packages/gateway/parallax/grpc-web/mirador-gateway-parallax-grpc-web-1.0.11.tgz",
     "rxjs": "^7.8.2"
   },
   "author": "@mirador",

package/src/parallax/ParallaxService.ts

@@ -0,0 +1,296 @@
+/**
+ * Parallax Service - Transaction Tracing for Web Applications
+ * Creates individual traces for each transaction and tracks them through their lifecycle
+ *
+ * This service provides a simplified interface for tracking transactions with automatic
+ * client metadata collection and lifecycle management.
+ */
+
+import { ParallaxClient } from './index';
+import type {
+  CreateTraceResponse,
+} from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
+
+interface TransactionInfo {
+  traceId: string;
+  timestamp: string;
+  txHash: string | null;
+  from?: string;
+  to?: string;
+  network?: string;
+}
+
+interface TransactionData {
+  from: string;
+  to: string;
+  value: string;
+  network?: string;
+  walletAddress?: string;
+  additionalData?: Record<string, any>;
+}
+
+interface FinishOptions {
+  success: boolean;
+  error?: string;
+}
+
+export class ParallaxService {
+  private client: ParallaxClient | null = null;
+  private activeTransactions: Map<string, TransactionInfo> = new Map();
+
+  constructor() {
+    // Client will be initialized lazily
+  }
+
+  /**
+   * Initialize the Parallax client (lazy initialization)
+   * @param apiKey - Optional API key for authentication
+   * @param gatewayUrl - Optional custom gateway URL
+   */
+  private _ensureClient(apiKey?: string, gatewayUrl?: string): void {
+    if (this.client) return;
+
+    // Determine gateway URL based on environment if not provided
+    let url = gatewayUrl;
+    if (!url && typeof window !== 'undefined') {
+      const isDevelopment =
+        window.location.hostname === 'localhost' ||
+        window.location.hostname === '127.0.0.1';
+
+      url = isDevelopment
+        ? `${window.location.protocol}//${window.location.host}/parallax-gateway`
+        : 'https://gateway-parallax-dev.mirador.org';
+    }
+
+    this.client = new ParallaxClient(apiKey || '', url);
+    console.log('[ParallaxService] Client initialized with URL:', url);
+  }
+
+  /**
+   * Start a new transaction trace
+   * Called when user initiates a transaction
+   *
+   * Uses the builder pattern to create a trace with events
+   *
+   * @param txData - Transaction data
+   * @param name - Name for the trace (e.g., 'SendingTrace', 'SwappingTrace')
+   * @param options - Optional configuration (apiKey, gatewayUrl, includeClientMeta)
+   * @returns Promise with traceId, rootSpanId, and txId
+   */
+  async startTransactionTrace(
+    txData: TransactionData,
+    name: string = 'WalletTransaction',
+    options?: { apiKey?: string; gatewayUrl?: string; includeClientMeta?: boolean }
+  ): Promise<{ traceId: string; rootSpanId: string; txId: string }> {
+    this._ensureClient(options?.apiKey, options?.gatewayUrl);
+
+    if (!this.client) {
+      throw new Error('Failed to initialize Parallax client');
+    }
+
+    try {
+      const txId = `tx_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+      const timestamp = new Date();
+
+      // Build the trace using the builder pattern
+      const builder = this.client
+        .trace(name, options?.includeClientMeta ?? true)
+        .addAttribute('transactionId', txId)
+        .addAttribute('walletAddress', txData.walletAddress || txData.from)
+        .addAttribute('network', txData.network || 'Unknown')
+        .addAttribute('transactionStart', timestamp.toISOString())
+        .addAttribute('from', txData.from)
+        .addAttribute('to', txData.to)
+        .addAttribute('value', txData.value)
+        .addTags(['transaction', 'wallet', txData.network || 'unknown'])
+        .addEvent('transaction_initiated', {
+          from: txData.from,
+          to: txData.to,
+          value: txData.value,
+          timestamp: timestamp.toISOString(),
+        });
+
+      // Add any additional transaction data as attributes
+      if (txData.additionalData) {
+        Object.entries(txData.additionalData).forEach(([key, value]) => {
+          builder.addAttribute(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+        });
+      }
+
+      // Submit the trace
+      const traceResponse: CreateTraceResponse = await builder.submit();
+      const traceId = traceResponse.getTraceId();
+
+      // Store transaction info
+      this.activeTransactions.set(txId, {
+        traceId,
+        timestamp: timestamp.toISOString(),
+        txHash: null,
+        from: txData.from,
+        to: txData.to,
+        network: txData.network,
+      });
+
+      console.log('[ParallaxService] Transaction trace started:', {
+        txId,
+        traceId,
+        from: txData.from,
+        to: txData.to,
+      });
+
+      return { traceId, rootSpanId: traceId, txId };
+    } catch (error) {
+      console.error('[ParallaxService] Failed to start transaction trace:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Associate a transaction hash with an existing trace
+   * Called when the transaction hash is available after signing/sending
+   *
+   * NOTE: This method is deprecated as the new API does not support adding hints to existing traces.
+   * Transaction hashes should be provided at trace creation time via the builder's submit(txHash, chainId) method.
+   *
+   * @param txId - Transaction identifier returned from startTransactionTrace
+   * @param txHash - Blockchain transaction hash
+   * @param chainId - Chain ID
+   * @deprecated Use submit(txHash, chainId) when creating the trace instead
+   */
+  async associateTransactionHash(txId: string, txHash: string, chainId: number): Promise<void> {
+    const txInfo = this.activeTransactions.get(txId);
+    if (!txInfo) {
+      console.warn(`[ParallaxService] Transaction ${txId} not found in active transactions`);
+      return;
+    }
+
+    // Update stored tx info
+    txInfo.txHash = txHash;
+    this.activeTransactions.set(txId, txInfo);
+
+    console.warn('[ParallaxService] associateTransactionHash is deprecated. The new API does not support adding transaction hashes after trace creation. Please provide the txHash when creating the trace using submit(txHash, chainId).');
+    console.log('[ParallaxService] Transaction hash updated in local cache:', {
+      txId,
+      txHash,
+      traceId: txInfo.traceId,
+    });
+  }
+
+  /**
+   * Add an event to a transaction trace
+   *
+   * NOTE: This method is deprecated as the new API does not support adding events to existing traces.
+   * Events should be added to the trace builder before calling submit().
+   *
+   * @param txId - Transaction identifier
+   * @param eventName - Event name
+   * @param attributes - Event attributes
+   * @deprecated Use the trace builder's addEvent() method before calling submit() instead
+   */
+  async addTransactionEvent(
+    txId: string,
+    eventName: string,
+    attributes: Record<string, any> = {}
+  ): Promise<void> {
+    const txInfo = this.activeTransactions.get(txId);
+    if (!txInfo) {
+      console.warn(`[ParallaxService] Transaction ${txId} not found. Cannot add event '${eventName}'`);
+      return;
+    }
+
+    console.warn('[ParallaxService] addTransactionEvent is deprecated. The new API does not support adding events after trace creation. Events should be added using the builder pattern before calling submit().');
+  }
+
+  /**
+   * Add an error to a transaction trace
+   *
+   * NOTE: This method is deprecated as the new API does not support adding errors to existing traces.
+   * Errors should be added as events to the trace builder before calling submit().
+   *
+   * @param txId - Transaction identifier
+   * @param error - Error object or message
+   * @param errorType - Type/category of error (e.g., 'TransactionError', 'NetworkError', 'UserRejection')
+   * @deprecated Use the trace builder's addEvent() method to add error events before calling submit() instead
+   */
+  async addTransactionError(
+    txId: string,
+    error: Error | string,
+    errorType: string = 'TransactionError'
+  ): Promise<void> {
+    const txInfo = this.activeTransactions.get(txId);
+    if (!txInfo) {
+      console.warn(`[ParallaxService] Transaction ${txId} not found. Cannot add error.`);
+      return;
+    }
+
+    console.warn('[ParallaxService] addTransactionError is deprecated. The new API does not support adding errors after trace creation. Add error events using the builder pattern before calling submit().');
+  }
+
+  /**
+   * Finish a transaction trace
+   *
+   * NOTE: This method is deprecated as the new API does not support span lifecycle management.
+   * Traces are completed when submit() is called on the builder.
+   *
+   * @param txId - Transaction identifier
+   * @param options - Finish options (success, error message)
+   * @deprecated Traces are automatically completed when submit() is called
+   */
+  async finishTransactionTrace(txId: string, options: FinishOptions = { success: true }): Promise<void> {
+    const txInfo = this.activeTransactions.get(txId);
+    if (!txInfo) {
+      console.warn(`[ParallaxService] Transaction ${txId} not found. Cannot finish.`);
+      return;
+    }
+
+    console.warn('[ParallaxService] finishTransactionTrace is deprecated. The new API does not support span lifecycle. Traces are completed when submit() is called.');
+
+    console.log('[ParallaxService] Transaction trace marked as finished (local only):', {
+      txId,
+      traceId: txInfo.traceId,
+      success: options.success,
+      txHash: txInfo.txHash,
+    });
+
+    // Remove from active transactions
+    this.activeTransactions.delete(txId);
+  }
+
+  /**
+   * Get info about an active transaction
+   *
+   * @param txId - Transaction identifier
+   * @returns Transaction info or null if not found
+   */
+  getTransactionInfo(txId: string): TransactionInfo | null {
+    return this.activeTransactions.get(txId) || null;
+  }
+
+  /**
+   * Get all active transactions
+   *
+   * @returns Array of active transaction info
+   */
+  getAllActiveTransactions(): Array<TransactionInfo & { txId: string }> {
+    return Array.from(this.activeTransactions.entries()).map(([txId, info]) => ({
+      txId,
+      ...info,
+    }));
+  }
+
+  /**
+   * Get the ParallaxClient instance for advanced usage
+   * @param apiKey - Optional API key
+   * @param gatewayUrl - Optional gateway URL
+   */
+  getClient(apiKey?: string, gatewayUrl?: string): ParallaxClient {
+    this._ensureClient(apiKey, gatewayUrl);
+    if (!this.client) {
+      throw new Error('Failed to initialize Parallax client');
+    }
+    return this.client;
+  }
+}
+
+// Export singleton instance
+export const parallaxService = new ParallaxService();