@miradorlabs/parallax-web 1.0.3 → 1.0.6

package/dist/index.d.ts

@@ -7,32 +7,124 @@ declare class ParallaxClient {
     apiUrl: string;
     private client;
     constructor(apiKey?: string | undefined, apiUrl?: string);
+    /**
+     * Gather client metadata for traces/spans
+     * Returns a metadata object with client environment details
+     * This includes browser, OS, screen size, IP address, and more
+     * @returns metadata
+     */
+    getClientMetadata(): Promise<{
+        [key: string]: string;
+    }>;
+    /**
+     * Creates a CreateTraceRequest with optional attributes and client metadata
+     * @param name name of the trace
+     * @param tags optional tags for trace
+     * @param attr optional attributes for trace
+     * @param includeClientMeta optional flag to include client metadata (ip, browser, os, etc)
+     * @returns a CreateTraceRequest object to be used for the createTrace request
+     */
+    createTraceRequest({ name, tags, attr, includeClientMeta }: {
+        name: string;
+        tags?: string[];
+        attr?: {
+            [key: string]: string;
+        };
+        includeClientMeta?: boolean;
+    }): Promise<CreateTraceRequest>;
     /**
      * Create a new trace
      * @param params Parameters to create a new trace
      * @returns Response from the create trace operation
      */
     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
      */
     startSpan(params: StartSpanRequest): Promise<StartSpanResponse>;
+    /**
+     * Create a FinishSpanRequest
+     * @param params Parameters to finish a span - traceId, spanId, status (optional) (success, errorMessage)
+     * @returns FinishSpanRequest
+     */
+    createFinishSpanRequest({ traceId, spanId, status }: {
+        traceId: string;
+        spanId: string;
+        status?: {
+            success: boolean;
+            errorMessage: string;
+        };
+    }): FinishSpanRequest;
     /**
      * Finish a span within a trace
      * @param params Parameters to finish a span
      */
     finishSpan(params: FinishSpanRequest): Promise<FinishSpanResponse>;
+    /**
+     * Creates the add span event request
+     * @param params - Parameters to create an AddSpanEventRequest - traceId, spanId, eventName, attr (optional)
+     * @returns AddSpanEventRequest
+     */
+    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>;
+    /**
+     * 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
+     */
+    createAddSpanErrorRequest({ traceId, spanId, errorMessage, errorType, stackTrace }: {
+        traceId: string;
+        spanId: string;
+        errorMessage: string;
+        errorType?: string;
+        stackTrace?: string;
+    }): AddSpanErrorRequest;
     /**
      * Add an error to a span
      * @param params Parameters to add an error to a span
      */
     addSpanError(params: AddSpanErrorRequest): Promise<AddSpanErrorResponse>;
+    /**
+     * Creates the add span hint request
+     * @param params - params used to generate the span hint (trace id, parentSpanId, txHash and chainId)
+     * @returns AddSpanHintRequest
+     */
+    createAddSpanHintRequest({ traceId, parentSpanId, txHash, chainId }: {
+        traceId: string;
+        parentSpanId: string;
+        txHash?: string;
+        chainId?: number;
+    }): AddSpanHintRequest;
     /**
      * Add a hint to a span
      * @param params Parameters to add a hint to a span
@@ -59,4 +151,123 @@ 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;
+    rootSpanId: string;
+    spanId: string | null;
+    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
+     *
+     * 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
+     */
+    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
+     *
+     * @param txId - Transaction identifier returned from startTransactionTrace
+     * @param txHash - Blockchain transaction hash
+     * @param chainId - Chain ID
+     */
+    associateTransactionHash(txId: string, txHash: string, chainId: number): Promise<void>;
+    /**
+     * Add an event to a transaction trace
+     *
+     * @param txId - Transaction identifier
+     * @param eventName - Event name
+     * @param attributes - Event attributes
+     */
+    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
+     *
+     * @param txId - Transaction identifier
+     * @param error - Error object or message
+     * @param errorType - Type/category of error (e.g., 'TransactionError', 'NetworkError', 'UserRejection')
+     */
+    addTransactionError(txId: string, error: Error | string, errorType?: string): Promise<void>;
+    /**
+     * Finish a transaction trace
+     * Called when transaction is confirmed or permanently failed
+     *
+     * @param txId - Transaction identifier
+     * @param options - Finish options (success, error message)
+     */
+    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, parallaxService };