@miradorlabs/parallax-web 1.0.6 → 1.0.8

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
-     */
-    createStartSpanRequest({ traceId, name, parentSpanId, attr, includeClientMeta }: {
-        traceId: string;
-        name: string;
-        parentSpanId?: string;
-        attr?: {
-            [key: string]: string;
-        };
-        includeClientMeta?: boolean;
-    }): Promise<StartSpanRequest>;
-    /**
-     * Start a new span within a trace
-     * @param params Parameters to start a new span
+     * 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
      */
-    startSpan(params: StartSpanRequest): Promise<StartSpanResponse>;
+    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);
     /**
-     * Create a FinishSpanRequest
-     * @param params Parameters to finish a span - traceId, spanId, status (optional) (success, errorMessage)
-     * @returns FinishSpanRequest
+     * 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
      */
-    createFinishSpanRequest({ traceId, spanId, status }: {
-        traceId: string;
-        spanId: string;
-        status?: {
-            success: boolean;
-            errorMessage: string;
-        };
-    }): FinishSpanRequest;
+    addAttribute(key: string, value: string | number | boolean): this;
     /**
-     * Finish a span within a trace
-     * @param params Parameters to finish a span
+     * Add multiple attributes to the trace
+     * @param attributes Object containing key-value pairs
+     * @returns This trace builder for chaining
      */
-    finishSpan(params: FinishSpanRequest): Promise<FinishSpanResponse>;
+    addAttributes(attributes: {
+        [key: string]: string | number | boolean;
+    }): this;
     /**
-     * Creates the add span event request
-     * @param params - Parameters to create an AddSpanEventRequest - traceId, spanId, eventName, attr (optional)
-     * @returns AddSpanEventRequest
+     * Add a tag to the trace
+     * @param tag Tag to add
+     * @returns This trace builder for chaining
      */
-    createAddSpanEventRequest({ traceId, spanId, eventName, attr }: {
-        traceId: string;
-        spanId: string;
-        eventName: string;
-        attr?: {
-            [key: string]: string;
-        };
-    }): AddSpanEventRequest;
+    addTag(tag: string): this;
     /**
-     * Add an event to a span
-     * @param params Parameters to add an event to a span
+     * Add multiple tags to the trace
+     * @param tags Array of tags to add
+     * @returns This trace builder for chaining
      */
-    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 {
@@ -161,8 +160,6 @@ declare class GrpcWebRpc implements Rpc {
 
 interface TransactionInfo {
     traceId: string;
-    rootSpanId: string;
-    spanId: string | null;
     timestamp: string;
     txHash: string | null;
     from?: string;
@@ -195,8 +192,7 @@ declare 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')
@@ -216,34 +212,48 @@ declare 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
      */
     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
-     * 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
      */
     addTransactionError(txId: string, error: Error | string, errorType?: string): Promise<void>;
     /**
      * 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
      */
     finishTransactionTrace(txId: string, options?: FinishOptions): Promise<void>;
     /**
@@ -270,4 +280,4 @@ declare class ParallaxService {
 }
 declare const parallaxService: ParallaxService;
 
-export { GrpcWebRpc, ParallaxClient, ParallaxService, parallaxService };
+export { GrpcWebRpc, ParallaxClient, ParallaxService, ParallaxTrace, parallaxService };