@miradorlabs/parallax-web 1.0.7 → 2.0.0

package/SETUP.md

@@ -1,220 +0,0 @@
-# Web Parallax Client Setup Summary
-
-This document summarizes the complete configuration and structure of the web-parallax-client SDK.
-
-## Directory Structure
-
-```
-web-parallax-client/
-├── dist/                          # Build output (generated)
-│   ├── index.esm.js              # ES Module bundle
-│   ├── index.esm.js.map          # ESM source map
-│   ├── index.umd.js              # UMD bundle (browser global)
-│   ├── index.umd.js.map          # UMD source map
-│   └── index.d.ts                # TypeScript declarations
-├── src/
-│   ├── grpc/
-│   │   └── index.ts              # GrpcWebRpc adapter (uses Fetch API)
-│   ├── parallax/
-│   │   └── index.ts              # ParallaxClient main class
-│   └── helpers/
-│       └── index.ts              # Serialization helpers
-├── tests/
-│   └── parallax.test.ts          # Jest unit tests
-├── index.ts                       # Main entry point
-├── package.json                   # NPM package configuration
-├── tsconfig.json                  # TypeScript config (dev)
-├── tsconfig.build.json            # TypeScript config (build)
-├── rollup.config.mjs              # Rollup bundler configuration
-├── jest.config.ts                 # Jest test configuration
-├── eslint.config.js               # ESLint configuration
-├── .prettierrc                    # Prettier configuration
-├── .nvmrc                         # Node version (22.13.0)
-├── .gitignore                     # Git ignore rules
-└── README.md                      # User documentation
-```
-
-## Key Configuration Files
-
-### package.json
-
-- **Name**: `@miradorlabs/parallax-web`
-- **Main Entry Points**:
-  - `main`: `dist/index.umd.js` (UMD for Node.js/CommonJS)
-  - `module`: `dist/index.esm.js` (ES Module for bundlers)
-  - `browser`: `dist/index.umd.js` (Browser global)
-  - `types`: `dist/index.d.ts` (TypeScript definitions)
-- **Dependencies**:
-  - `google-protobuf`: ^4.0.1
-  - `mirador-gateway-parallax-web`: grpc-web package from GCS
-  - `rxjs`: ^7.8.2
-- **Scripts**:
-  - `build`: Build all bundles with Rollup
-  - `test`: Run Jest tests
-  - `test:watch`: Run Jest in watch mode
-  - `test:coverage`: Generate coverage report
-
-### rollup.config.mjs
-
-Generates three outputs:
-
-1. **ESM Bundle** (`dist/index.esm.js`)
-   - Format: ES Module
-   - For modern bundlers (Webpack, Vite, etc.)
-
-2. **UMD Bundle** (`dist/index.umd.js`)
-   - Format: UMD
-   - Global name: `ParallaxWeb`
-   - For browser `<script>` tags
-
-3. **Type Definitions** (`dist/index.d.ts`)
-   - TypeScript declarations
-
-All bundles treat external dependencies as external:
-- `google-protobuf`
-- `mirador-gateway-parallax-web/*`
-- `rxjs/*`
-
-### tsconfig.json
-
-- Target: ES2020
-- Module: ESNext (for browser)
-- Lib: ES2020, DOM, DOM.Iterable
-- Strict mode enabled
-- Module resolution: bundler
-
-### jest.config.ts
-
-- Preset: ts-jest
-- Test environment: **jsdom** (browser simulation)
-- Test match: `**/*.test.ts`
-- Coverage from `src/**/*.ts`
-
-## Key Differences from nodejs-parallax-client
-
-| Feature | nodejs-parallax-client | web-parallax-client |
-|---------|------------------------|---------------------|
-| gRPC Library | `@grpc/grpc-js` | Fetch API (gRPC-Web compatible) |
-| Transport | Native gRPC | HTTP/HTTPS with gRPC-Web protocol |
-| Environment | Node.js | Browser |
-| Module System | CommonJS | ESM + UMD |
-| Test Environment | Node | jsdom (browser) |
-| Connection | Can use insecure | Always uses HTTPS |
-| Default URL | localhost:50053 | https://gateway-parallax-dev... |
-
-## Source Files
-
-### src/grpc/index.ts - GrpcWebRpc
-
-Implements the gRPC-Web RPC adapter using browser Fetch API:
-
-- **Unary requests**: Standard HTTP POST with protobuf binary body
-- **Server streaming**: Uses ReadableStream from Response.body
-- **Headers**: Includes `Content-Type: application/grpc-web+proto`
-- **API Key**: Sent as `x-api-key` header
-- **Type casting**: `data.buffer as ArrayBuffer` for Fetch compatibility
-
-### src/parallax/index.ts - ParallaxClient
-
-Main SDK client with methods:
-- `createTrace()`: Create a new trace
-- `startSpan()`: Start a span within a trace
-- `finishSpan()`: Finish a span
-- `addSpanAttributes()`: Add attributes to a span
-- `addSpanEvent()`: Add an event to a span
-- `addSpanError()`: Add an error to a span
-- `addSpanHint()`: Add a blockchain transaction hint
-
-### tests/parallax.test.ts
-
-Comprehensive test suite covering:
-- Client instantiation
-- All SDK methods (success and error cases)
-- Integration scenarios
-- API key handling
-- Mock implementation of GrpcWebRpc
-
-## Build Process
-
-```bash
-npm run build
-```
-
-1. Clears `dist/` directory
-2. Runs Rollup with three configurations in parallel:
-   - ESM bundle with source maps
-   - UMD bundle with source maps
-   - TypeScript declarations
-
-Build warnings about `mirador-gateway-parallax-web` imports are **expected** - these are external dependencies resolved at runtime.
-
-## Testing
-
-```bash
-npm test              # Run all tests
-npm run test:watch    # Watch mode
-npm run test:coverage # Generate coverage report
-```
-
-Tests use:
-- **jsdom**: Simulates browser environment
-- **ts-jest**: TypeScript transformation
-- **Mocking**: GrpcWebRpc is mocked for unit tests
-
-## Publishing
-
-```bash
-npm run release:patch   # Bump patch version (1.0.0 -> 1.0.1)
-npm run release:minor   # Bump minor version (1.0.0 -> 1.1.0)
-npm run release:major   # Bump major version (1.0.0 -> 2.0.0)
-```
-
-Versioning automatically:
-1. Updates `package.json` version
-2. Creates git tag
-3. Pushes with `--follow-tags`
-
-## Browser Compatibility
-
-Requires modern browsers supporting:
-- ES2020 features
-- Fetch API
-- Promises
-- ReadableStream
-- Uint8Array
-
-For older browsers, polyfills may be needed.
-
-## Usage in Browser
-
-### Via NPM/Bundler (Recommended)
-
-```typescript
-import { ParallaxClient } from '@miradorlabs/parallax-web';
-
-const client = new ParallaxClient('your-api-key');
-```
-
-### Via UMD Script Tag
-
-```html
-<script src="node_modules/@miradorlabs/parallax-web/dist/index.umd.js"></script>
-<script>
-  const client = new ParallaxWeb.ParallaxClient('your-api-key');
-</script>
-```
-
-## Next Steps
-
-1. **Install dependencies**: Already done (`npm install`)
-2. **Build**: Already done (`npm run build`)
-3. **Test**: Run `npm test` to verify all tests pass
-4. **Customize**: Update `GRPC_GATEWAY_API_URL` in `src/parallax/index.ts` if needed
-5. **Publish**: When ready, use `npm run release:patch` to version and publish
-
-## Notes
-
-- The package uses the grpc-web package from GCS: `mirador-gateway-parallax-grpc-web-1.0.9.tgz`
-- Type warnings during build about missing type declarations are expected for external packages
-- All gRPC-Web requests use the browser's Fetch API, making this SDK compatible with modern web applications
-- The SDK maintains the same API surface as the Node.js client for consistency

package/src/grpc/index.ts

@@ -1,155 +0,0 @@
-import { Observable } from "rxjs";
-
-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>;
-}
-
-export class GrpcWebRpc implements Rpc {
-  private url: string;
-  private apiKey?: string;
-
-  constructor(url: string, apiKey?: string) {
-    this.url = url;
-    this.apiKey = apiKey;
-  }
-
-  async request(
-    service: string,
-    method: string,
-    data: Uint8Array,
-    metadata?: Metadata
-  ): Promise<Uint8Array> {
-    console.log(`[gRPC-Web] Making request to ${this.url}/${service}/${method}`);
-
-    const headers: HeadersInit = {
-      'Content-Type': 'application/grpc-web+proto',
-      'X-Grpc-Web': '1',
-    };
-
-    // Add API key to headers if provided
-    if (this.apiKey) {
-      headers['x-api-key'] = this.apiKey;
-    }
-
-    // Add custom metadata
-    if (metadata) {
-      Object.entries(metadata).forEach(([key, value]) => {
-        headers[key] = value;
-      });
-    }
-
-    try {
-      const response = await fetch(`${this.url}/${service}/${method}`, {
-        method: 'POST',
-        headers,
-        body: data.buffer as ArrayBuffer,
-      });
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Error(`gRPC-Web error: ${response.status} ${response.statusText} - ${errorText}`);
-      }
-
-      const arrayBuffer = await response.arrayBuffer();
-      console.log(`[gRPC-Web] Success from ${this.url}/${service}/${method}`);
-      return new Uint8Array(arrayBuffer);
-    } catch (error) {
-      console.error(
-        `[gRPC-Web] Error from ${this.url}/${service}/${method}:`,
-        error instanceof Error ? error.message : String(error)
-      );
-      throw error;
-    }
-  }
-
-  clientStreamingRequest(): Promise<Uint8Array> {
-    throw new Error("Client streaming not yet implemented for gRPC-Web");
-  }
-
-  serverStreamingRequest(
-    service: string,
-    method: string,
-    data: Uint8Array
-  ): Observable<Uint8Array> {
-    return new Observable((subscriber) => {
-      const headers: HeadersInit = {
-        'Content-Type': 'application/grpc-web+proto',
-        'X-Grpc-Web': '1',
-      };
-
-      // Add API key to headers if provided
-      if (this.apiKey) {
-        headers['x-api-key'] = this.apiKey;
-      }
-
-      fetch(`${this.url}/${service}/${method}`, {
-        method: 'POST',
-        headers,
-        body: data.buffer as ArrayBuffer,
-      })
-        .then(async (response) => {
-          if (!response.ok) {
-            throw new Error(`gRPC-Web error: ${response.status} ${response.statusText}`);
-          }
-
-          if (!response.body) {
-            throw new Error('Response body is null');
-          }
-
-          const reader = response.body.getReader();
-
-          try {
-            while (true) {
-              const { done, value } = await reader.read();
-
-              if (done) {
-                subscriber.complete();
-                break;
-              }
-
-              if (value) {
-                subscriber.next(value);
-              }
-            }
-          } catch (error) {
-            subscriber.error(error);
-          }
-        })
-        .catch((error) => {
-          subscriber.error(error);
-        });
-
-      return () => {
-        // Cleanup logic if needed
-      };
-    });
-  }
-
-  bidirectionalStreamingRequest(): Observable<Uint8Array> {
-    throw new Error("Bidirectional streaming not yet implemented for gRPC-Web");
-  }
-}

package/src/helpers/index.ts

@@ -1,13 +0,0 @@
-// Helper serialization functions for browser environment
-function serialize(value: Uint8Array): Uint8Array {
-  return value;
-}
-
-function deserialize(bytes: Uint8Array): Uint8Array {
-  return bytes;
-}
-
-export {
-  deserialize,
-  serialize
-}

package/src/parallax/ParallaxService.ts

@@ -1,296 +0,0 @@
-/**
- * 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.
- */
-
-import { ParallaxClient } from './index';
-import type {
-  CreateTraceResponse,
-} from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
-
-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;
-}
-
-export class ParallaxService {
-  private client: ParallaxClient | null = null;
-  private activeTransactions: Map<string, TransactionInfo> = new Map();
-
-  constructor() {
-    // Client will be initialized lazily
-  }
-
-  /**
-   * Initialize the Parallax client (lazy initialization)
-   * @param apiKey - Optional API key for authentication
-   * @param gatewayUrl - Optional custom gateway URL
-   */
-  private _ensureClient(apiKey?: string, gatewayUrl?: string): void {
-    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
-   *
-   * 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
-   */
-  async startTransactionTrace(
-    txData: TransactionData,
-    name: string = 'WalletTransaction',
-    options?: { apiKey?: string; gatewayUrl?: string; includeClientMeta?: boolean }
-  ): Promise<{ traceId: string; rootSpanId: string; txId: string }> {
-    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();
-
-      // Build the trace using the builder pattern
-      const builder = this.client
-        .trace(name, options?.includeClientMeta ?? true)
-        .addAttribute('transactionId', txId)
-        .addAttribute('walletAddress', txData.walletAddress || txData.from)
-        .addAttribute('network', txData.network || 'Unknown')
-        .addAttribute('transactionStart', timestamp.toISOString())
-        .addAttribute('from', txData.from)
-        .addAttribute('to', txData.to)
-        .addAttribute('value', txData.value)
-        .addTags(['transaction', 'wallet', txData.network || 'unknown'])
-        .addEvent('transaction_initiated', {
-          from: txData.from,
-          to: txData.to,
-          value: txData.value,
-          timestamp: timestamp.toISOString(),
-        });
-
-      // Add any additional transaction data as attributes
-      if (txData.additionalData) {
-        Object.entries(txData.additionalData).forEach(([key, value]) => {
-          builder.addAttribute(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
-        });
-      }
-
-      // Submit the trace
-      const traceResponse: CreateTraceResponse = await builder.submit();
-      const traceId = traceResponse.getTraceId();
-
-      // Store transaction info
-      this.activeTransactions.set(txId, {
-        traceId,
-        timestamp: timestamp.toISOString(),
-        txHash: null,
-        from: txData.from,
-        to: txData.to,
-        network: txData.network,
-      });
-
-      console.log('[ParallaxService] Transaction trace started:', {
-        txId,
-        traceId,
-        from: txData.from,
-        to: txData.to,
-      });
-
-      return { traceId, rootSpanId: traceId, 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
-   *
-   * 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
-   */
-  async associateTransactionHash(txId: string, txHash: string, chainId: number): Promise<void> {
-    const txInfo = this.activeTransactions.get(txId);
-    if (!txInfo) {
-      console.warn(`[ParallaxService] Transaction ${txId} not found in active transactions`);
-      return;
-    }
-
-    // Update stored tx info
-    txInfo.txHash = txHash;
-    this.activeTransactions.set(txId, txInfo);
-
-    console.warn('[ParallaxService] associateTransactionHash is deprecated. The new API does not support adding transaction hashes after trace creation. Please provide the txHash when creating the trace using submit(txHash, chainId).');
-    console.log('[ParallaxService] Transaction hash updated in local cache:', {
-      txId,
-      txHash,
-      traceId: txInfo.traceId,
-    });
-  }
-
-  /**
-   * 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
-   */
-  async addTransactionEvent(
-    txId: string,
-    eventName: string,
-    attributes: Record<string, any> = {}
-  ): Promise<void> {
-    const txInfo = this.activeTransactions.get(txId);
-    if (!txInfo) {
-      console.warn(`[ParallaxService] Transaction ${txId} not found. Cannot add event '${eventName}'`);
-      return;
-    }
-
-    console.warn('[ParallaxService] addTransactionEvent is deprecated. The new API does not support adding events after trace creation. Events should be added using the builder pattern before calling submit().');
-  }
-
-  /**
-   * 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
-   */
-  async addTransactionError(
-    txId: string,
-    error: Error | string,
-    errorType: string = 'TransactionError'
-  ): Promise<void> {
-    const txInfo = this.activeTransactions.get(txId);
-    if (!txInfo) {
-      console.warn(`[ParallaxService] Transaction ${txId} not found. Cannot add error.`);
-      return;
-    }
-
-    console.warn('[ParallaxService] addTransactionError is deprecated. The new API does not support adding errors after trace creation. Add error events using the builder pattern before calling submit().');
-  }
-
-  /**
-   * 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
-   */
-  async finishTransactionTrace(txId: string, options: FinishOptions = { success: true }): Promise<void> {
-    const txInfo = this.activeTransactions.get(txId);
-    if (!txInfo) {
-      console.warn(`[ParallaxService] Transaction ${txId} not found. Cannot finish.`);
-      return;
-    }
-
-    console.warn('[ParallaxService] finishTransactionTrace is deprecated. The new API does not support span lifecycle. Traces are completed when submit() is called.');
-
-    console.log('[ParallaxService] Transaction trace marked as finished (local only):', {
-      txId,
-      traceId: txInfo.traceId,
-      success: options.success,
-      txHash: txInfo.txHash,
-    });
-
-    // Remove from active transactions
-    this.activeTransactions.delete(txId);
-  }
-
-  /**
-   * Get info about an active transaction
-   *
-   * @param txId - Transaction identifier
-   * @returns Transaction info or null if not found
-   */
-  getTransactionInfo(txId: string): TransactionInfo | null {
-    return this.activeTransactions.get(txId) || null;
-  }
-
-  /**
-   * Get all active transactions
-   *
-   * @returns Array of active transaction info
-   */
-  getAllActiveTransactions(): Array<TransactionInfo & { txId: string }> {
-    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?: string, gatewayUrl?: string): ParallaxClient {
-    this._ensureClient(apiKey, gatewayUrl);
-    if (!this.client) {
-      throw new Error('Failed to initialize Parallax client');
-    }
-    return this.client;
-  }
-}
-
-// Export singleton instance
-export const parallaxService = new ParallaxService();