@miradorlabs/parallax-web 1.0.8 → 2.0.0

package/dist/index.d.ts

@@ -1,63 +1,22 @@
+import * as mirador_gateway_parallax_web_proto_gateway_parallax_v1_parallax_gateway_pb 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 {
-    apiKey?: string | undefined;
-    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 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
-     */
-    trace(name: string, includeClientMeta?: boolean): ParallaxTrace;
+/**
+ * Supported chain names (maps to Chain enum in proto)
+ */
+type ChainName = 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bsc';
+
+/**
+ * ParallaxTrace builder class for constructing traces with method chaining
+ */
+
+/**
+ * Interface for the client that ParallaxTrace uses to submit traces
+ * @internal
+ */
+interface TraceSubmitter {
+    _sendTrace(request: CreateTraceRequest): Promise<CreateTraceResponse>;
 }
 /**
  * Builder class for constructing traces with method chaining
@@ -71,21 +30,21 @@ declare class ParallaxTrace {
     private txHashHint?;
     private client;
     private includeClientMeta;
-    constructor(client: ParallaxClient, name: string, includeClientMeta?: boolean);
+    constructor(client: TraceSubmitter, name?: string, includeClientMeta?: boolean);
     /**
      * Add an attribute to the trace
      * @param key Attribute key
-     * @param value Attribute value (will be converted to string)
+     * @param value Attribute value (objects are stringified, primitives converted to string)
      * @returns This trace builder for chaining
      */
-    addAttribute(key: string, value: string | number | boolean): this;
+    addAttribute(key: string, value: string | number | boolean | object): this;
     /**
      * Add multiple attributes to the trace
-     * @param attributes Object containing key-value pairs
+     * @param attributes Object containing key-value pairs (objects are stringified)
      * @returns This trace builder for chaining
      */
     addAttributes(attributes: {
-        [key: string]: string | number | boolean;
+        [key: string]: string | number | boolean | object;
     }): this;
     /**
      * Add a tag to the trace
@@ -108,176 +67,59 @@ declare class ParallaxTrace {
      */
     addEvent(eventName: string, details?: string | object, timestamp?: Date): this;
     /**
-     * Set or update the transaction hash hint
+     * Set the transaction hash hint for blockchain correlation
      * @param txHash Transaction hash
-     * @param chainId Chain ID (e.g., "ethereum", "polygon")
+     * @param chain Chain name (e.g., "ethereum", "polygon", "base")
      * @param details Optional details about the transaction
-     * @param timestamp Optional timestamp (defaults to current time)
      * @returns This trace builder for chaining
      */
-    setTxHash(txHash: string, chainId: string, details?: string, timestamp?: Date): this;
-    /**
-     * Submit the trace without a transaction hash hint (if not already set via setTxHash)
-     * @returns Response from the create trace operation
-     */
-    submit(): Promise<CreateTraceResponse>;
+    setTxHint(txHash: string, chain: ChainName, details?: string): this;
     /**
-     * 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
+     * Create and submit the trace to the gateway
+     * @returns The trace ID if successful, undefined if failed
      */
-    submit(txHash: string, chainId: string, details?: string): Promise<CreateTraceResponse>;
-}
-
-interface Metadata {
-    [key: string]: string;
-}
-interface Rpc {
-    request(service: string, method: string, data: Uint8Array, metadata?: Metadata): Promise<Uint8Array>;
-    clientStreamingRequest(service: string, method: string, data: Observable<Uint8Array>): Promise<Uint8Array>;
-    serverStreamingRequest(service: string, method: string, data: Uint8Array): Observable<Uint8Array>;
-    bidirectionalStreamingRequest(service: string, method: string, data: Observable<Uint8Array>): Observable<Uint8Array>;
-}
-declare class GrpcWebRpc implements Rpc {
-    private url;
-    private apiKey?;
-    constructor(url: string, apiKey?: string);
-    request(service: string, method: string, data: Uint8Array, metadata?: Metadata): Promise<Uint8Array>;
-    clientStreamingRequest(): Promise<Uint8Array>;
-    serverStreamingRequest(service: string, method: string, data: Uint8Array): Observable<Uint8Array>;
-    bidirectionalStreamingRequest(): Observable<Uint8Array>;
+    create(): Promise<string | undefined>;
 }
 
 /**
- * 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.
+ * Main client for interacting with the Parallax Gateway API
  */
-
-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 {
+declare class ParallaxClient {
+    apiUrl: string;
+    apiKey: string;
     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
+     * Create a new ParallaxClient instance
+     * @param apiKey Required API key for authentication (sent as x-parallax-api-key header)
+     * @param apiUrl Optional gateway URL (defaults to parallax-gateway.dev.mirador.org:443)
      */
-    addTransactionError(txId: string, error: Error | string, errorType?: string): Promise<void>;
+    constructor(apiKey: string, apiUrl?: string);
     /**
-     * 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
+     * Internal method to send trace to gateway
+     * @internal
      */
-    finishTransactionTrace(txId: string, options?: FinishOptions): Promise<void>;
+    _sendTrace(request: CreateTraceRequest): Promise<mirador_gateway_parallax_web_proto_gateway_parallax_v1_parallax_gateway_pb.CreateTraceResponse>;
     /**
-     * Get info about an active transaction
+     * Create a new trace builder
      *
-     * @param txId - Transaction identifier
-     * @returns Transaction info or null if not found
-     */
-    getTransactionInfo(txId: string): TransactionInfo | null;
-    /**
-     * Get all active transactions
+     * 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")
+     *   .setTxHint("0x123...", "ethereum")
+     *   .create();
+     * ```
      *
-     * @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
+     * @param name Optional name of the trace (defaults to empty string)
+     * @param includeClientMeta Optional flag to automatically include client metadata
+     * @returns A ParallaxTrace builder instance
      */
-    getClient(apiKey?: string, gatewayUrl?: string): ParallaxClient;
+    trace(name?: string, includeClientMeta?: boolean): ParallaxTrace;
 }
-declare const parallaxService: ParallaxService;
 
-export { GrpcWebRpc, ParallaxClient, ParallaxService, ParallaxTrace, parallaxService };
+export { ParallaxClient, ParallaxTrace };