@miradorlabs/parallax-web 1.0.6 → 1.0.8

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-parallax-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

@@ -8,14 +8,4 @@ export { ParallaxService, parallaxService } from './src/parallax/ParallaxService
 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.6",
+  "version": "1.0.8",
   "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.10.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/grpc/index.ts

@@ -52,7 +52,7 @@ export class GrpcWebRpc implements Rpc {
 
     // Add API key to headers if provided
     if (this.apiKey) {
-      headers['x-api-key'] = this.apiKey;
+      headers['x-parallax-api-key'] = this.apiKey;
     }
 
     // Add custom metadata
@@ -103,7 +103,7 @@ export class GrpcWebRpc implements Rpc {
 
       // Add API key to headers if provided
       if (this.apiKey) {
-        headers['x-api-key'] = this.apiKey;
+        headers['x-parallax-api-key'] = this.apiKey;
       }
 
       fetch(`${this.url}/${service}/${method}`, {

package/src/parallax/ParallaxService.ts

@@ -9,17 +9,10 @@
 import { ParallaxClient } from './index';
 import type {
   CreateTraceResponse,
-  StartSpanResponse,
-  FinishSpanResponse,
-  AddSpanEventResponse,
-  AddSpanErrorResponse,
-  AddSpanHintResponse,
 } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
 
 interface TransactionInfo {
   traceId: string;
-  rootSpanId: string;
-  spanId: string | null;
   timestamp: string;
   txHash: string | null;
   from?: string;
@@ -77,8 +70,7 @@ export class ParallaxService {
    * Start a new transaction trace
    * Called when user initiates a transaction
    *
-   * Note: Since createTrace now automatically creates a root span, we don't need
-   * to call startSpan separately. The rootSpanId from the response is the parent span.
+   * Uses the builder pattern to create a trace with events
    *
    * @param txData - Transaction data
    * @param name - Name for the trace (e.g., 'SendingTrace', 'SwappingTrace')
@@ -98,44 +90,41 @@ export class ParallaxService {
 
     try {
       const txId = `tx_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-      const timestamp = new Date().toISOString();
-
-      // Create trace attributes
-      const traceAttributes: Record<string, string> = {
-        transactionId: txId,
-        walletAddress: txData.walletAddress || txData.from,
-        network: txData.network || 'Unknown',
-        transactionStart: timestamp,
-        from: txData.from,
-        to: txData.to,
-        value: txData.value,
-      };
+      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
+      // Add any additional transaction data as attributes
       if (txData.additionalData) {
         Object.entries(txData.additionalData).forEach(([key, value]) => {
-          traceAttributes[key] = typeof value === 'object' ? JSON.stringify(value) : String(value);
+          builder.addAttribute(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
         });
       }
 
-      // Create a trace for this transaction
-      const createTraceReq = await this.client.createTraceRequest({
-        name: name,
-        attr: traceAttributes,
-        tags: ['transaction', 'wallet', txData.network || 'unknown'],
-        includeClientMeta: options?.includeClientMeta ?? true,
-      });
-
-      const traceResponse: CreateTraceResponse = await this.client.createTrace(createTraceReq);
+      // Submit the trace
+      const traceResponse: CreateTraceResponse = await builder.submit();
       const traceId = traceResponse.getTraceId();
-      const rootSpanId = traceResponse.getRootSpanId();
 
       // Store transaction info
       this.activeTransactions.set(txId, {
         traceId,
-        rootSpanId,
-        spanId: rootSpanId, // Use rootSpanId as the main span for this transaction
-        timestamp,
+        timestamp: timestamp.toISOString(),
         txHash: null,
         from: txData.from,
         to: txData.to,
@@ -145,20 +134,11 @@ export class ParallaxService {
       console.log('[ParallaxService] Transaction trace started:', {
         txId,
         traceId,
-        rootSpanId,
-        from: txData.from,
-        to: txData.to,
-      });
-
-      // Add initial event to the root span
-      await this.addTransactionEvent(txId, 'transaction_initiated', {
         from: txData.from,
         to: txData.to,
-        value: txData.value,
-        timestamp,
       });
 
-      return { traceId, rootSpanId, txId };
+      return { traceId, rootSpanId: traceId, txId };
     } catch (error) {
       console.error('[ParallaxService] Failed to start transaction trace:', error);
       throw error;
@@ -169,9 +149,13 @@ export class ParallaxService {
    * 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);
@@ -180,49 +164,28 @@ export class ParallaxService {
       return;
     }
 
-    if (!this.client) {
-      console.warn('[ParallaxService] Client not initialized');
-      return;
-    }
-
-    try {
-      // Update stored tx info
-      txInfo.txHash = txHash;
-      this.activeTransactions.set(txId, txInfo);
-
-      // Add chain hint to correlate with blockchain events
-      const hintReq = this.client.createAddSpanHintRequest({
-        traceId: txInfo.traceId,
-        parentSpanId: txInfo.rootSpanId,
-        txHash: txHash,
-        chainId: chainId,
-      });
+    // Update stored tx info
+    txInfo.txHash = txHash;
+    this.activeTransactions.set(txId, txInfo);
 
-      await this.client.addSpanHint(hintReq);
-
-      // Add event for transaction sent
-      await this.addTransactionEvent(txId, 'transaction_hash_available', {
-        txHash,
-        chainId: chainId.toString(),
-        timestamp: new Date().toISOString(),
-      });
-
-      console.log('[ParallaxService] Transaction hash associated with trace:', {
-        txId,
-        txHash,
-        traceId: txInfo.traceId,
-      });
-    } catch (error) {
-      console.error('[ParallaxService] Failed to associate transaction hash:', error);
-    }
+    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,
@@ -235,38 +198,19 @@ export class ParallaxService {
       return;
     }
 
-    if (!this.client || !txInfo.spanId) {
-      console.warn('[ParallaxService] Client not initialized or span not available');
-      return;
-    }
-
-    try {
-      // Convert attributes to plain object with string values
-      const eventAttributes: Record<string, string> = {};
-      Object.entries(attributes).forEach(([key, value]) => {
-        eventAttributes[key] = typeof value === 'object' ? JSON.stringify(value) : String(value);
-      });
-
-      const request = this.client.createAddSpanEventRequest({
-        traceId: txInfo.traceId,
-        spanId: txInfo.spanId,
-        eventName: eventName,
-        attr: eventAttributes,
-      });
-
-      await this.client.addSpanEvent(request);
-    } catch (error) {
-      console.error(`[ParallaxService] Failed to add transaction event '${eventName}':`, error);
-    }
+    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
-   * Creates a proper span error event in Parallax
+   *
+   * 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,
@@ -279,49 +223,18 @@ export class ParallaxService {
       return;
     }
 
-    if (!this.client || !txInfo.spanId) {
-      console.warn('[ParallaxService] Client not initialized or span not available');
-      return;
-    }
-
-    try {
-      // Extract error message and stack trace
-      let errorMessage = '';
-      let stackTrace: string | undefined;
-
-      if (error instanceof Error) {
-        errorMessage = error.message;
-        stackTrace = error.stack;
-      } else {
-        errorMessage = String(error);
-      }
-
-      const request = this.client.createAddSpanErrorRequest({
-        traceId: txInfo.traceId,
-        spanId: txInfo.spanId,
-        errorMessage: errorMessage,
-        errorType: errorType,
-        stackTrace: stackTrace,
-      });
-
-      await this.client.addSpanError(request);
-
-      console.log('[ParallaxService] Transaction error added to trace:', {
-        txId,
-        errorType,
-        message: error instanceof Error ? error.message : String(error),
-      });
-    } catch (err) {
-      console.error('[ParallaxService] Failed to add transaction error:', err);
-    }
+    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
-   * Called when transaction is confirmed or permanently failed
+   *
+   * 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);
@@ -330,48 +243,17 @@ export class ParallaxService {
       return;
     }
 
-    if (!this.client || !txInfo.spanId) {
-      console.warn('[ParallaxService] Client not initialized or span not available');
-      return;
-    }
+    console.warn('[ParallaxService] finishTransactionTrace is deprecated. The new API does not support span lifecycle. Traces are completed when submit() is called.');
 
-    try {
-      // Add final event
-      await this.addTransactionEvent(
-        txId,
-        options.success ? 'transaction_completed' : 'transaction_failed',
-        {
-          success: options.success.toString(),
-          error: options.error || '',
-          duration: (Date.now() - new Date(txInfo.timestamp).getTime()).toString(),
-          timestamp: new Date().toISOString(),
-        }
-      );
-
-      // Finish the span
-      const request = this.client.createFinishSpanRequest({
-        traceId: txInfo.traceId,
-        spanId: txInfo.spanId,
-        status: {
-          success: options.success,
-          errorMessage: options.error || '',
-        },
-      });
-
-      await this.client.finishSpan(request);
-
-      console.log('[ParallaxService] Transaction trace finished:', {
-        txId,
-        traceId: txInfo.traceId,
-        success: options.success,
-        txHash: txInfo.txHash,
-      });
+    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);
-    } catch (error) {
-      console.error('[ParallaxService] Failed to finish transaction trace:', error);
-    }
+    // Remove from active transactions
+    this.activeTransactions.delete(txId);
   }
 
   /**