@miradorlabs/parallax-web 1.0.6 → 1.0.8

package/PARALLAX_SERVICE_USAGE.md

@@ -1,306 +0,0 @@
-# ParallaxService Usage Guide
-
-The `ParallaxService` provides a simplified, high-level interface for tracking transactions in web applications. It automatically manages trace lifecycle, client metadata collection, and blockchain correlation.
-
-## Features
-
-- **Automatic Root Span Creation**: When you create a trace, a root span is automatically created (no need to call `startSpan` separately)
-- **Transaction Lifecycle Management**: Track transactions from initiation to completion
-- **Automatic Client Metadata**: Optionally includes browser, OS, IP, and other client details
-- **Blockchain Integration**: Associate transaction hashes with traces for correlation
-- **Event Tracking**: Add events at any point in the transaction lifecycle
-- **Error Tracking**: Proper error handling with stack traces
-
-## Quick Start
-
-### Using the Singleton Instance
-
-```typescript
-import { parallaxService } from '@miradorlabs/parallax-web';
-
-// Start tracking a transaction
-const { traceId, rootSpanId, txId } = await parallaxService.startTransactionTrace(
-  {
-    from: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
-    to: '0x8626f6940E2eb28930eFb4CeF49B2d1F2C9C1199',
-    value: '0.1',
-    network: 'ethereum',
-    walletAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
-  },
-  'SendTransaction', // trace name
-  {
-    includeClientMeta: true, // include browser, OS, IP, etc.
-    apiKey: 'your-api-key', // optional
-    gatewayUrl: 'https://gateway-parallax-dev.mirador.org', // optional
-  }
-);
-
-// Later, when you get the transaction hash
-await parallaxService.associateTransactionHash(txId, '0xabc123...', 1);
-
-// Add events
-await parallaxService.addTransactionEvent(txId, 'wallet_signed', {
-  timestamp: new Date().toISOString(),
-});
-
-// Track errors
-try {
-  // transaction logic
-} catch (error) {
-  await parallaxService.addTransactionError(txId, error, 'TransactionError');
-}
-
-// Finish the trace
-await parallaxService.finishTransactionTrace(txId, {
-  success: true,
-});
-```
-
-### Creating Your Own Instance
-
-```typescript
-import { ParallaxService } from '@miradorlabs/parallax-web';
-
-const myService = new ParallaxService();
-// Use the same API as above
-```
-
-## API Reference
-
-### `startTransactionTrace(txData, name, options)`
-
-Starts a new transaction trace with automatic root span creation.
-
-**Parameters:**
-- `txData`: Object with transaction details
-  - `from`: Sender address (required)
-  - `to`: Recipient address (required)
-  - `value`: Transaction value (required)
-  - `network`: Network name (optional)
-  - `walletAddress`: Wallet address (optional)
-  - `additionalData`: Any extra data (optional)
-- `name`: Trace name (default: 'WalletTransaction')
-- `options`: Optional configuration
-  - `apiKey`: API key for authentication
-  - `gatewayUrl`: Custom gateway URL
-  - `includeClientMeta`: Include browser/OS metadata (default: true)
-
-**Returns:**
-```typescript
-Promise<{
-  traceId: string;
-  rootSpanId: string; // This is the automatically created root span
-  txId: string;       // Internal transaction identifier
-}>
-```
-
-### `associateTransactionHash(txId, txHash, chainId)`
-
-Associates a blockchain transaction hash with the trace for correlation.
-
-**Parameters:**
-- `txId`: Transaction identifier from `startTransactionTrace`
-- `txHash`: Blockchain transaction hash
-- `chainId`: Chain ID (e.g., 1 for Ethereum mainnet)
-
-### `addTransactionEvent(txId, eventName, attributes)`
-
-Adds an event to the transaction trace.
-
-**Parameters:**
-- `txId`: Transaction identifier
-- `eventName`: Event name (e.g., 'wallet_signed', 'sent_to_network')
-- `attributes`: Event attributes (object)
-
-### `addTransactionError(txId, error, errorType)`
-
-Adds an error to the transaction trace with stack trace support.
-
-**Parameters:**
-- `txId`: Transaction identifier
-- `error`: Error object or message
-- `errorType`: Error category (default: 'TransactionError')
-
-### `finishTransactionTrace(txId, options)`
-
-Completes the transaction trace.
-
-**Parameters:**
-- `txId`: Transaction identifier
-- `options`: Finish options
-  - `success`: Whether transaction succeeded (required)
-  - `error`: Error message if failed (optional)
-
-### `getTransactionInfo(txId)`
-
-Gets information about an active transaction.
-
-**Returns:** Transaction info object or null
-
-### `getAllActiveTransactions()`
-
-Gets all currently active transactions.
-
-**Returns:** Array of transaction info objects
-
-### `getClient(apiKey?, gatewayUrl?)`
-
-Gets the underlying `ParallaxClient` for advanced usage.
-
-## Important Note: Automatic Root Span Creation
-
-**The key difference** from previous versions: When you call `createTrace`, a root span is **automatically created** on the backend. You receive a `rootSpanId` in the response.
-
-You **do NOT need** to call `startSpan` after creating a trace anymore. The `rootSpanId` serves as the parent span for any child spans you want to create.
-
-### Example of Creating Child Spans (Optional)
-
-If you need child spans for more detailed tracking:
-
-```typescript
-// Start transaction (creates trace + root span automatically)
-const { traceId, rootSpanId, txId } = await parallaxService.startTransactionTrace(
-  txData,
-  'ComplexTransaction'
-);
-
-// Access the underlying client for advanced usage
-const client = parallaxService.getClient();
-
-// Create a child span if needed
-const childSpanReq = await client.createStartSpanRequest({
-  traceId: traceId,
-  name: 'SigningPhase',
-  parentSpanId: rootSpanId, // Use the root span as parent
-  attr: { phase: 'signing' },
-});
-
-const childSpanResponse = await client.startSpan(childSpanReq);
-const childSpanId = childSpanResponse.getSpanId();
-
-// Later, finish the child span
-const finishReq = client.createFinishSpanRequest({
-  traceId: traceId,
-  spanId: childSpanId,
-  status: { success: true, errorMessage: '' },
-});
-
-await client.finishSpan(finishReq);
-```
-
-## Client Metadata
-
-When `includeClientMeta: true`, the following metadata is automatically collected:
-- Browser (Chrome, Firefox, Safari, Edge)
-- Operating System (Windows, macOS, Linux, Android, iOS)
-- User Agent
-- Platform
-- Language
-- Screen dimensions
-- Viewport dimensions
-- Timezone
-- Page URL
-- Referrer
-- IP address (if not blocked by CSP)
-
-All metadata is prefixed with `client.` in attributes.
-
-## Environment Detection
-
-The service automatically detects the environment:
-- **Localhost/127.0.0.1**: Uses proxy endpoint `${window.location.protocol}//${window.location.host}/parallax-gateway`
-- **Production**: Uses `https://gateway-parallax-dev.mirador.org`
-
-You can override this with the `gatewayUrl` option.
-
-## Example: Complete Transaction Flow
-
-```typescript
-import { parallaxService } from '@miradorlabs/parallax-web';
-
-async function handleTransaction() {
-  let txId: string;
-
-  try {
-    // 1. Start the trace
-    const result = await parallaxService.startTransactionTrace(
-      {
-        from: userAddress,
-        to: recipientAddress,
-        value: amount,
-        network: 'ethereum',
-        walletAddress: userAddress,
-        additionalData: {
-          gasPrice: gasPrice,
-          gasLimit: gasLimit,
-        },
-      },
-      'SendETH',
-      { includeClientMeta: true }
-    );
-
-    txId = result.txId;
-
-    // 2. User signs the transaction
-    await parallaxService.addTransactionEvent(txId, 'user_signing', {});
-
-    const signedTx = await wallet.signTransaction(txData);
-
-    await parallaxService.addTransactionEvent(txId, 'transaction_signed', {});
-
-    // 3. Send to network
-    await parallaxService.addTransactionEvent(txId, 'sending_to_network', {});
-
-    const txReceipt = await provider.sendTransaction(signedTx);
-
-    // 4. Associate the transaction hash
-    await parallaxService.associateTransactionHash(
-      txId,
-      txReceipt.hash,
-      1 // Ethereum mainnet
-    );
-
-    // 5. Wait for confirmation
-    await parallaxService.addTransactionEvent(txId, 'waiting_confirmation', {
-      txHash: txReceipt.hash,
-    });
-
-    await txReceipt.wait();
-
-    // 6. Success!
-    await parallaxService.finishTransactionTrace(txId, { success: true });
-
-  } catch (error) {
-    // Track the error
-    if (txId) {
-      await parallaxService.addTransactionError(txId, error, 'TransactionError');
-      await parallaxService.finishTransactionTrace(txId, {
-        success: false,
-        error: error.message,
-      });
-    }
-    throw error;
-  }
-}
-```
-
-## TypeScript Support
-
-Full TypeScript support with exported types:
-
-```typescript
-import type {
-  CreateTraceRequest,
-  CreateTraceResponse,
-  StartSpanRequest,
-  StartSpanResponse,
-  FinishSpanRequest,
-  FinishSpanResponse,
-  AddSpanEventRequest,
-  AddSpanEventResponse,
-  AddSpanErrorRequest,
-  AddSpanErrorResponse,
-  AddSpanHintRequest,
-  AddSpanHintResponse,
-} from '@miradorlabs/parallax-web';
-```

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