@miradorlabs/parallax-web 1.0.4 → 1.0.7

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { CreateTraceRequest, CreateTraceResponse, StartSpanRequest, StartSpanResponse, FinishSpanRequest, FinishSpanResponse, AddSpanEventRequest, AddSpanEventResponse, AddSpanErrorRequest, AddSpanErrorResponse, AddSpanHintRequest, AddSpanHintResponse } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
-export { AddSpanErrorRequest, AddSpanErrorResponse, AddSpanEventRequest, AddSpanEventResponse, AddSpanHintRequest, AddSpanHintResponse, CreateTraceRequest, CreateTraceResponse, FinishSpanRequest, FinishSpanResponse, StartSpanRequest, StartSpanResponse } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
+import { CreateTraceRequest, CreateTraceResponse } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
+export { CreateTraceRequest, CreateTraceResponse } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
 import { Observable } from 'rxjs';
 
 declare class ParallaxClient {
@@ -39,97 +39,96 @@ declare class ParallaxClient {
      */
     createTrace(params: CreateTraceRequest): Promise<CreateTraceResponse>;
     /**
-     * Create a StartSpanRequest with optional attributes and client metadata
-     * @param traceId trace id to associate the span with
-     * @param name name of the span
-     * @param parentSpanId (optional) create a span off a parent span id
-     * @param attr (optional) attributes to add to the span
-     * @param includeClientMeta (optional) flag to include client metadata (ip, browser, os, etc)
-     * @returns
+     * 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
      */
-    createStartSpanRequest({ traceId, name, parentSpanId, attr, includeClientMeta }: {
-        traceId: string;
-        name: string;
-        parentSpanId?: string;
-        attr?: {
-            [key: string]: string;
-        };
-        includeClientMeta?: boolean;
-    }): Promise<StartSpanRequest>;
+    trace(name: string, includeClientMeta?: boolean): ParallaxTrace;
+}
+/**
+ * Builder class for constructing traces with method chaining
+ * Automatically handles web-specific features like client metadata
+ */
+declare class ParallaxTrace {
+    private name;
+    private attributes;
+    private tags;
+    private events;
+    private txHashHint?;
+    private client;
+    private includeClientMeta;
+    constructor(client: ParallaxClient, name: string, includeClientMeta?: boolean);
     /**
-     * Start a new span within a trace
-     * @param params Parameters to start a new span
+     * 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
      */
-    startSpan(params: StartSpanRequest): Promise<StartSpanResponse>;
+    addAttribute(key: string, value: string | number | boolean): this;
     /**
-     * Create a FinishSpanRequest
-     * @param params Parameters to finish a span - traceId, spanId, status (optional) (success, errorMessage)
-     * @returns FinishSpanRequest
+     * Add multiple attributes to the trace
+     * @param attributes Object containing key-value pairs
+     * @returns This trace builder for chaining
      */
-    createFinishSpanRequest({ traceId, spanId, status }: {
-        traceId: string;
-        spanId: string;
-        status?: {
-            success: boolean;
-            errorMessage: string;
-        };
-    }): FinishSpanRequest;
+    addAttributes(attributes: {
+        [key: string]: string | number | boolean;
+    }): this;
     /**
-     * Finish a span within a trace
-     * @param params Parameters to finish a span
+     * Add a tag to the trace
+     * @param tag Tag to add
+     * @returns This trace builder for chaining
      */
-    finishSpan(params: FinishSpanRequest): Promise<FinishSpanResponse>;
+    addTag(tag: string): this;
     /**
-     * Creates the add span event request
-     * @param params - Parameters to create an AddSpanEventRequest - traceId, spanId, eventName, attr (optional)
-     * @returns AddSpanEventRequest
+     * Add multiple tags to the trace
+     * @param tags Array of tags to add
+     * @returns This trace builder for chaining
      */
-    createAddSpanEventRequest({ traceId, spanId, eventName, attr }: {
-        traceId: string;
-        spanId: string;
-        eventName: string;
-        attr?: {
-            [key: string]: string;
-        };
-    }): AddSpanEventRequest;
-    /**
-     * Add an event to a span
-     * @param params Parameters to add an event to a span
-     */
-    addSpanEvent(params: AddSpanEventRequest): Promise<AddSpanEventResponse>;
+    addTags(tags: string[]): this;
     /**
-     * Creates the add span error request
-     * @param params - params used to generate the error request ( traceid, span id, error message, error type, stack trace)
-     * @returns AddSpanErrorRequest
+     * 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
      */
-    createAddSpanErrorRequest({ traceId, spanId, errorMessage, errorType, stackTrace }: {
-        traceId: string;
-        spanId: string;
-        errorMessage: string;
-        errorType?: string;
-        stackTrace?: string;
-    }): AddSpanErrorRequest;
+    addEvent(eventName: string, details?: string | object, timestamp?: Date): this;
     /**
-     * Add an error to a span
-     * @param params Parameters to add an error to a span
+     * 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
      */
-    addSpanError(params: AddSpanErrorRequest): Promise<AddSpanErrorResponse>;
+    setTxHash(txHash: string, chainId: string, details?: string, timestamp?: Date): this;
     /**
-     * Creates the add span hint request
-     * @param params - params used to generate the span hint (trace id, parentSpanId, txHash and chainId)
-     * @returns AddSpanHintRequest
+     * Submit the trace without a transaction hash hint (if not already set via setTxHash)
+     * @returns Response from the create trace operation
      */
-    createAddSpanHintRequest({ traceId, parentSpanId, txHash, chainId }: {
-        traceId: string;
-        parentSpanId: string;
-        txHash?: string;
-        chainId?: number;
-    }): AddSpanHintRequest;
+    submit(): Promise<CreateTraceResponse>;
     /**
-     * Add a hint to a span
-     * @param params Parameters to add a hint to a span
+     * 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
      */
-    addSpanHint(params: AddSpanHintRequest): Promise<AddSpanHintResponse>;
+    submit(txHash: string, chainId: string, details?: string): Promise<CreateTraceResponse>;
 }
 
 interface Metadata {
@@ -151,4 +150,134 @@ declare class GrpcWebRpc implements Rpc {
     bidirectionalStreamingRequest(): Observable<Uint8Array>;
 }
 
-export { GrpcWebRpc, ParallaxClient };
+/**
+ * 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.
+ */
+
+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;
+}
+declare class ParallaxService {
+    private client;
+    private activeTransactions;
+    constructor();
+    /**
+     * Initialize the Parallax client (lazy initialization)
+     * @param apiKey - Optional API key for authentication
+     * @param gatewayUrl - Optional custom gateway URL
+     */
+    private _ensureClient;
+    /**
+     * 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
+     */
+    startTransactionTrace(txData: TransactionData, name?: string, options?: {
+        apiKey?: string;
+        gatewayUrl?: string;
+        includeClientMeta?: boolean;
+    }): Promise<{
+        traceId: string;
+        rootSpanId: string;
+        txId: string;
+    }>;
+    /**
+     * 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
+     */
+    associateTransactionHash(txId: string, txHash: string, chainId: number): Promise<void>;
+    /**
+     * 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
+     */
+    addTransactionEvent(txId: string, eventName: string, attributes?: Record<string, any>): Promise<void>;
+    /**
+     * 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
+     */
+    addTransactionError(txId: string, error: Error | string, errorType?: string): Promise<void>;
+    /**
+     * 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
+     */
+    finishTransactionTrace(txId: string, options?: FinishOptions): Promise<void>;
+    /**
+     * Get info about an active transaction
+     *
+     * @param txId - Transaction identifier
+     * @returns Transaction info or null if not found
+     */
+    getTransactionInfo(txId: string): TransactionInfo | null;
+    /**
+     * Get all active transactions
+     *
+     * @returns Array of active transaction info
+     */
+    getAllActiveTransactions(): Array<TransactionInfo & {
+        txId: string;
+    }>;
+    /**
+     * Get the ParallaxClient instance for advanced usage
+     * @param apiKey - Optional API key
+     * @param gatewayUrl - Optional gateway URL
+     */
+    getClient(apiKey?: string, gatewayUrl?: string): ParallaxClient;
+}
+declare const parallaxService: ParallaxService;
+
+export { GrpcWebRpc, ParallaxClient, ParallaxService, ParallaxTrace, parallaxService };