@miradorlabs/parallax-web 1.0.4 → 1.0.6

package/dist/index.umd.js

@@ -1057,7 +1057,8 @@
 			  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) {
@@ -1108,6 +1109,11 @@
 			      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;
@@ -1155,6 +1161,14 @@
 			      f
 			    );
 			  }
+			  f = message.getStartTime();
+			  if (f != null) {
+			    writer.writeMessage(
+			      4,
+			      f,
+			      google_protobuf_timestamp_pb.Timestamp.serializeBinaryToWriter
+			    );
+			  }
 			};
 
 
@@ -1236,6 +1250,43 @@
 			};
 
 
+			/**
+			 * 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;
+			};
+
+
 
 
 
@@ -1269,7 +1320,8 @@
 			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) {
@@ -1315,6 +1367,10 @@
 			      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;
@@ -1359,6 +1415,13 @@
 			      f
 			    );
 			  }
+			  f = message.getRootSpanId();
+			  if (f.length > 0) {
+			    writer.writeString(
+			      3,
+			      f
+			    );
+			  }
 			};
 
 
@@ -1417,6 +1480,24 @@
 			};
 
 
+			/**
+			 * 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);
+			};
+
+
 
 
 
@@ -1451,7 +1532,7 @@
 			  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)
 			  };
@@ -1556,8 +1637,8 @@
 			      f
 			    );
 			  }
-			  f = /** @type {string} */ (jspb.Message.getField(message, 3));
-			  if (f != null) {
+			  f = message.getParentSpanId();
+			  if (f.length > 0) {
 			    writer.writeString(
 			      3,
 			      f
@@ -1628,25 +1709,7 @@
 			 * @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);
 			};
 
 
@@ -4693,6 +4756,339 @@
 	    }
 	}
 
+	/**
+	 * 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();
+
 	exports.AddSpanErrorRequest = parallax_gateway_pbExports.AddSpanErrorRequest;
 	exports.AddSpanErrorResponse = parallax_gateway_pbExports.AddSpanErrorResponse;
 	exports.AddSpanEventRequest = parallax_gateway_pbExports.AddSpanEventRequest;
@@ -4705,8 +5101,10 @@
 	exports.FinishSpanResponse = parallax_gateway_pbExports.FinishSpanResponse;
 	exports.GrpcWebRpc = GrpcWebRpc;
 	exports.ParallaxClient = ParallaxClient;
+	exports.ParallaxService = ParallaxService;
 	exports.StartSpanRequest = parallax_gateway_pbExports.StartSpanRequest;
 	exports.StartSpanResponse = parallax_gateway_pbExports.StartSpanResponse;
+	exports.parallaxService = parallaxService;
 
 }));
 //# sourceMappingURL=index.umd.js.map