@miradorlabs/parallax-web 1.0.4 → 1.0.6

package/dist/index.esm.js

@@ -1053,7 +1053,8 @@ function requireParallax_gateway_pb () {
 		  var f, obj = {
 		name: jspb.Message.getFieldWithDefault(msg, 1, ""),
 		attributesMap: (f = msg.getAttributesMap()) ? f.toObject(includeInstance, undefined) : [],
-		tagsList: (f = jspb.Message.getRepeatedField(msg, 3)) == null ? undefined : f
+		tagsList: (f = jspb.Message.getRepeatedField(msg, 3)) == null ? undefined : f,
+		startTime: (f = msg.getStartTime()) && google_protobuf_timestamp_pb.Timestamp.toObject(includeInstance, f)
 		  };
 
 		  if (includeInstance) {
@@ -1104,6 +1105,11 @@ function requireParallax_gateway_pb () {
 		      var value = /** @type {string} */ (reader.readString());
 		      msg.addTags(value);
 		      break;
+		    case 4:
+		      var value = new google_protobuf_timestamp_pb.Timestamp;
+		      reader.readMessage(value,google_protobuf_timestamp_pb.Timestamp.deserializeBinaryFromReader);
+		      msg.setStartTime(value);
+		      break;
 		    default:
 		      reader.skipField();
 		      break;
@@ -1151,6 +1157,14 @@ function requireParallax_gateway_pb () {
 		      f
 		    );
 		  }
+		  f = message.getStartTime();
+		  if (f != null) {
+		    writer.writeMessage(
+		      4,
+		      f,
+		      google_protobuf_timestamp_pb.Timestamp.serializeBinaryToWriter
+		    );
+		  }
 		};
 
 
@@ -1232,6 +1246,43 @@ function requireParallax_gateway_pb () {
 		};
 
 
+		/**
+		 * optional google.protobuf.Timestamp start_time = 4;
+		 * @return {?proto.google.protobuf.Timestamp}
+		 */
+		proto.gateway.parallax.v1.CreateTraceRequest.prototype.getStartTime = function() {
+		  return /** @type{?proto.google.protobuf.Timestamp} */ (
+		    jspb.Message.getWrapperField(this, google_protobuf_timestamp_pb.Timestamp, 4));
+		};
+
+
+		/**
+		 * @param {?proto.google.protobuf.Timestamp|undefined} value
+		 * @return {!proto.gateway.parallax.v1.CreateTraceRequest} returns this
+		*/
+		proto.gateway.parallax.v1.CreateTraceRequest.prototype.setStartTime = function(value) {
+		  return jspb.Message.setWrapperField(this, 4, value);
+		};
+
+
+		/**
+		 * Clears the message field making it undefined.
+		 * @return {!proto.gateway.parallax.v1.CreateTraceRequest} returns this
+		 */
+		proto.gateway.parallax.v1.CreateTraceRequest.prototype.clearStartTime = function() {
+		  return this.setStartTime(undefined);
+		};
+
+
+		/**
+		 * Returns whether this field is set.
+		 * @return {boolean}
+		 */
+		proto.gateway.parallax.v1.CreateTraceRequest.prototype.hasStartTime = function() {
+		  return jspb.Message.getField(this, 4) != null;
+		};
+
+
 
 
 
@@ -1265,7 +1316,8 @@ function requireParallax_gateway_pb () {
 		proto.gateway.parallax.v1.CreateTraceResponse.toObject = function(includeInstance, msg) {
 		  var f, obj = {
 		status: (f = msg.getStatus()) && proto_common_v1_status_pb.ResponseStatus.toObject(includeInstance, f),
-		traceId: jspb.Message.getFieldWithDefault(msg, 2, "")
+		traceId: jspb.Message.getFieldWithDefault(msg, 2, ""),
+		rootSpanId: jspb.Message.getFieldWithDefault(msg, 3, "")
 		  };
 
 		  if (includeInstance) {
@@ -1311,6 +1363,10 @@ function requireParallax_gateway_pb () {
 		      var value = /** @type {string} */ (reader.readString());
 		      msg.setTraceId(value);
 		      break;
+		    case 3:
+		      var value = /** @type {string} */ (reader.readString());
+		      msg.setRootSpanId(value);
+		      break;
 		    default:
 		      reader.skipField();
 		      break;
@@ -1355,6 +1411,13 @@ function requireParallax_gateway_pb () {
 		      f
 		    );
 		  }
+		  f = message.getRootSpanId();
+		  if (f.length > 0) {
+		    writer.writeString(
+		      3,
+		      f
+		    );
+		  }
 		};
 
 
@@ -1413,6 +1476,24 @@ function requireParallax_gateway_pb () {
 		};
 
 
+		/**
+		 * optional string root_span_id = 3;
+		 * @return {string}
+		 */
+		proto.gateway.parallax.v1.CreateTraceResponse.prototype.getRootSpanId = function() {
+		  return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 3, ""));
+		};
+
+
+		/**
+		 * @param {string} value
+		 * @return {!proto.gateway.parallax.v1.CreateTraceResponse} returns this
+		 */
+		proto.gateway.parallax.v1.CreateTraceResponse.prototype.setRootSpanId = function(value) {
+		  return jspb.Message.setProto3StringField(this, 3, value);
+		};
+
+
 
 
 
@@ -1447,7 +1528,7 @@ function requireParallax_gateway_pb () {
 		  var f, obj = {
 		name: jspb.Message.getFieldWithDefault(msg, 1, ""),
 		traceId: jspb.Message.getFieldWithDefault(msg, 2, ""),
-		parentSpanId: (f = jspb.Message.getField(msg, 3)) == null ? undefined : f,
+		parentSpanId: jspb.Message.getFieldWithDefault(msg, 3, ""),
 		attributesMap: (f = msg.getAttributesMap()) ? f.toObject(includeInstance, undefined) : [],
 		startTime: (f = msg.getStartTime()) && google_protobuf_timestamp_pb.Timestamp.toObject(includeInstance, f)
 		  };
@@ -1552,8 +1633,8 @@ function requireParallax_gateway_pb () {
 		      f
 		    );
 		  }
-		  f = /** @type {string} */ (jspb.Message.getField(message, 3));
-		  if (f != null) {
+		  f = message.getParentSpanId();
+		  if (f.length > 0) {
 		    writer.writeString(
 		      3,
 		      f
@@ -1624,25 +1705,7 @@ function requireParallax_gateway_pb () {
 		 * @return {!proto.gateway.parallax.v1.StartSpanRequest} returns this
 		 */
 		proto.gateway.parallax.v1.StartSpanRequest.prototype.setParentSpanId = function(value) {
-		  return jspb.Message.setField(this, 3, value);
-		};
-
-
-		/**
-		 * Clears the field making it undefined.
-		 * @return {!proto.gateway.parallax.v1.StartSpanRequest} returns this
-		 */
-		proto.gateway.parallax.v1.StartSpanRequest.prototype.clearParentSpanId = function() {
-		  return jspb.Message.setField(this, 3, undefined);
-		};
-
-
-		/**
-		 * Returns whether this field is set.
-		 * @return {boolean}
-		 */
-		proto.gateway.parallax.v1.StartSpanRequest.prototype.hasParentSpanId = function() {
-		  return jspb.Message.getField(this, 3) != null;
+		  return jspb.Message.setProto3StringField(this, 3, value);
 		};
 
 
@@ -4689,6 +4752,339 @@ class GrpcWebRpc {
     }
 }
 
+/**
+ * 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.
+ */
+class ParallaxService {
+    constructor() {
+        Object.defineProperty(this, "client", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "activeTransactions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        // Client will be initialized lazily
+    }
+    /**
+     * Initialize the Parallax client (lazy initialization)
+     * @param apiKey - Optional API key for authentication
+     * @param gatewayUrl - Optional custom gateway URL
+     */
+    _ensureClient(apiKey, gatewayUrl) {
+        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
+     *
+     * 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.
+     *
+     * @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, name = 'WalletTransaction', options) {
+        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().toISOString();
+            // Create trace attributes
+            const traceAttributes = {
+                transactionId: txId,
+                walletAddress: txData.walletAddress || txData.from,
+                network: txData.network || 'Unknown',
+                transactionStart: timestamp,
+                from: txData.from,
+                to: txData.to,
+                value: txData.value,
+            };
+            // Add any additional transaction data
+            if (txData.additionalData) {
+                Object.entries(txData.additionalData).forEach(([key, value]) => {
+                    traceAttributes[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 = await this.client.createTrace(createTraceReq);
+            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,
+                txHash: null,
+                from: txData.from,
+                to: txData.to,
+                network: txData.network,
+            });
+            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 };
+        }
+        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
+     *
+     * @param txId - Transaction identifier returned from startTransactionTrace
+     * @param txHash - Blockchain transaction hash
+     * @param chainId - Chain ID
+     */
+    async associateTransactionHash(txId, txHash, chainId) {
+        const txInfo = this.activeTransactions.get(txId);
+        if (!txInfo) {
+            console.warn(`[ParallaxService] Transaction ${txId} not found in active transactions`);
+            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,
+            });
+            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);
+        }
+    }
+    /**
+     * Add an event to a transaction trace
+     *
+     * @param txId - Transaction identifier
+     * @param eventName - Event name
+     * @param attributes - Event attributes
+     */
+    async addTransactionEvent(txId, eventName, attributes = {}) {
+        const txInfo = this.activeTransactions.get(txId);
+        if (!txInfo) {
+            console.warn(`[ParallaxService] Transaction ${txId} not found. Cannot add event '${eventName}'`);
+            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 = {};
+            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);
+        }
+    }
+    /**
+     * Add an error to a transaction trace
+     * Creates a proper span error event in Parallax
+     *
+     * @param txId - Transaction identifier
+     * @param error - Error object or message
+     * @param errorType - Type/category of error (e.g., 'TransactionError', 'NetworkError', 'UserRejection')
+     */
+    async addTransactionError(txId, error, errorType = 'TransactionError') {
+        const txInfo = this.activeTransactions.get(txId);
+        if (!txInfo) {
+            console.warn(`[ParallaxService] Transaction ${txId} not found. Cannot add error.`);
+            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;
+            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);
+        }
+    }
+    /**
+     * Finish a transaction trace
+     * Called when transaction is confirmed or permanently failed
+     *
+     * @param txId - Transaction identifier
+     * @param options - Finish options (success, error message)
+     */
+    async finishTransactionTrace(txId, options = { success: true }) {
+        const txInfo = this.activeTransactions.get(txId);
+        if (!txInfo) {
+            console.warn(`[ParallaxService] Transaction ${txId} not found. Cannot finish.`);
+            return;
+        }
+        if (!this.client || !txInfo.spanId) {
+            console.warn('[ParallaxService] Client not initialized or span not available');
+            return;
+        }
+        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,
+            });
+            // Remove from active transactions
+            this.activeTransactions.delete(txId);
+        }
+        catch (error) {
+            console.error('[ParallaxService] Failed to finish transaction trace:', error);
+        }
+    }
+    /**
+     * Get info about an active transaction
+     *
+     * @param txId - Transaction identifier
+     * @returns Transaction info or null if not found
+     */
+    getTransactionInfo(txId) {
+        return this.activeTransactions.get(txId) || null;
+    }
+    /**
+     * Get all active transactions
+     *
+     * @returns Array of active transaction info
+     */
+    getAllActiveTransactions() {
+        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, gatewayUrl) {
+        this._ensureClient(apiKey, gatewayUrl);
+        if (!this.client) {
+            throw new Error('Failed to initialize Parallax client');
+        }
+        return this.client;
+    }
+}
+// Export singleton instance
+const parallaxService = new ParallaxService();
+
 var AddSpanErrorRequest = parallax_gateway_pbExports.AddSpanErrorRequest;
 var AddSpanErrorResponse = parallax_gateway_pbExports.AddSpanErrorResponse;
 var AddSpanEventRequest = parallax_gateway_pbExports.AddSpanEventRequest;
@@ -4701,5 +5097,5 @@ var FinishSpanRequest = parallax_gateway_pbExports.FinishSpanRequest;
 var FinishSpanResponse = parallax_gateway_pbExports.FinishSpanResponse;
 var StartSpanRequest = parallax_gateway_pbExports.StartSpanRequest;
 var StartSpanResponse = parallax_gateway_pbExports.StartSpanResponse;
-export { AddSpanErrorRequest, AddSpanErrorResponse, AddSpanEventRequest, AddSpanEventResponse, AddSpanHintRequest, AddSpanHintResponse, CreateTraceRequest, CreateTraceResponse, FinishSpanRequest, FinishSpanResponse, GrpcWebRpc, ParallaxClient, StartSpanRequest, StartSpanResponse };
+export { AddSpanErrorRequest, AddSpanErrorResponse, AddSpanEventRequest, AddSpanEventResponse, AddSpanHintRequest, AddSpanHintResponse, CreateTraceRequest, CreateTraceResponse, FinishSpanRequest, FinishSpanResponse, GrpcWebRpc, ParallaxClient, ParallaxService, StartSpanRequest, StartSpanResponse, parallaxService };
 //# sourceMappingURL=index.esm.js.map