@miradorlabs/parallax-web 1.0.4 → 1.0.7

package/example/README.md

@@ -0,0 +1,257 @@
+# Parallax Web Client Demo
+
+An interactive web application demonstrating how to use the Parallax SDK to create and manage transaction traces.
+
+## Features
+
+- **Builder Pattern Interface**: Use the fluent API to construct traces step-by-step
+- **Real-time Trace Building**: Add attributes, tags, and events dynamically
+- **Transaction Hash Support**: Optionally associate traces with blockchain transactions
+- **Activity Logging**: See all SDK operations in real-time
+- **Client Metadata**: Automatically includes browser, OS, and screen information
+
+## Getting Started
+
+### Quick Start (Recommended)
+
+The easiest way to run the demo:
+
+```bash
+cd ./example
+npm install
+npm run dev
+```
+
+This will:
+1. Install dependencies (Rollup)
+2. Bundle from TypeScript source
+3. Compile TypeScript and bundle everything
+4. Start a local web server
+5. Open your browser automatically
+
+That's it! The demo will be running at http://localhost:8000
+
+### Manual Setup
+
+If you prefer to run it manually:
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Build the bundle
+npm run build
+
+# 3. Start a web server
+npm start           # Using Python
+# OR
+npm run serve       # Using http-server (auto-opens browser)
+```
+
+### Alternative: Using VS Code Live Server
+1. Run `npm run build` to create the bundle
+2. Install the "Live Server" extension in VS Code
+3. Right-click on `index.html`
+4. Select "Open with Live Server"
+
+## How to Use
+
+### Step 1: Create a Trace
+1. Fill in the trace name (e.g., "swap_execution", "payment_flow")
+2. Enter transaction details:
+   - From address
+   - To address
+   - Value (in ETH)
+   - Network (Ethereum, Polygon, etc.)
+3. Click "Create Trace"
+
+This initializes a trace builder with:
+- Default transaction attributes
+- Network-specific tags
+- Automatic client metadata (browser, OS, screen size, etc.)
+
+### Step 2: Add Custom Attributes (Optional)
+Add any custom key-value pairs to enrich your trace:
+- `slippage_bps`: "50"
+- `gas_limit`: "21000"
+- `dex`: "uniswap"
+- Any other relevant metadata
+
+### Step 3: Add Tags (Optional)
+Add tags to categorize your trace:
+- "dex"
+- "swap"
+- "critical"
+- "production"
+
+### Step 4: Add Events (Optional)
+Track important moments in the transaction lifecycle:
+- Event name: "wallet_connected"
+- Details: `{"wallet": "MetaMask", "version": "10.0.0"}`
+
+Or:
+- Event name: "quote_received"
+- Details: (leave empty for timestamp-only events)
+
+**JSON Support**: If your details start with `{` or `[`, they'll be parsed as JSON automatically.
+
+### Step 5: Submit the Trace
+Submit your trace to the Parallax Gateway:
+
+**Without Transaction Hash:**
+- Just click "Submit Trace"
+- Use this when you don't have a blockchain tx hash yet
+
+**With Transaction Hash:**
+- Enter the transaction hash
+- Enter the chain ID (1 for Ethereum, 137 for Polygon, etc.)
+- Click "Submit Trace"
+
+## Example Usage Flow
+
+```javascript
+// The demo app uses the builder pattern like this:
+
+// 1. Create trace builder
+const trace = client.trace("swap_execution", true); // includeClientMeta
+
+// 2. Add attributes
+trace
+  .addAttribute("from", "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb")
+  .addAttribute("to", "0x1234567890123456789012345678901234567890")
+  .addAttribute("value", "0.5")
+  .addAttribute("network", "ethereum")
+  .addAttribute("slippage_bps", "50");
+
+// 3. Add tags
+trace
+  .addTag("dex")
+  .addTag("swap")
+  .addTag("uniswap");
+
+// 4. Add events
+trace
+  .addEvent("wallet_connected", { wallet: "MetaMask" })
+  .addEvent("quote_received", { amount: "0.5 ETH", price: "$2000" })
+  .addEvent("tx_signed");
+
+// 5. Submit with transaction hash
+const response = await trace.submit(
+  "0x1234567890abcdef...", // txHash
+  "1",                     // chainId (Ethereum)
+  "Swap transaction"       // details (optional)
+);
+
+console.log("Trace ID:", response.getTraceId());
+```
+
+## Understanding the Builder Pattern
+
+The Parallax SDK uses a **builder pattern** for creating traces:
+
+```javascript
+client.trace(name, includeClientMeta)
+  .addAttribute(key, value)     // Add single attribute
+  .addAttributes({...})          // Add multiple attributes
+  .addTag(tag)                   // Add single tag
+  .addTags([...])                // Add multiple tags
+  .addEvent(name, details, ts)   // Add event
+  .setTxHash(hash, chainId)      // Set transaction hash
+  .submit()                      // Submit without tx hash
+  .submit(hash, chainId)         // Submit with tx hash
+```
+
+**Benefits:**
+- ✅ Method chaining for clean, readable code
+- ✅ All data collected before submission
+- ✅ Type-safe with TypeScript
+- ✅ Automatic JSON stringification for objects
+- ✅ Optional client metadata collection
+
+## Activity Log
+
+The demo includes a real-time activity log showing:
+- ✅ Successful operations (green)
+- ❌ Errors (red)
+- ℹ️  Information messages (blue)
+- ⚠️  Warnings (yellow)
+
+All SDK operations are logged with timestamps for debugging.
+
+## API Configuration
+
+By default, the demo connects to:
+```javascript
+const client = new ParallaxClient(
+  'demo-api-key',
+  'https://parallax-gateway.dev.mirador.org:443'
+);
+```
+
+To use a different endpoint, modify `app.js`:
+```javascript
+const client = new ParallaxClient(
+  'your-api-key',
+  'https://your-gateway-url:port'
+);
+```
+
+## Client Metadata
+
+When `includeClientMeta` is `true`, the SDK automatically includes:
+- Browser name and version
+- Operating system
+- Screen resolution
+- Viewport size
+- User agent
+- Language
+- Timezone
+- Current URL
+- Referrer
+
+All metadata is prefixed with `client.*` (e.g., `client.browser`, `client.os`)
+
+## Troubleshooting
+
+### CORS Errors
+If you see CORS errors in the console:
+- Make sure you're serving the files via HTTP (not opening `file://` directly)
+- Check that the Parallax Gateway allows requests from your origin
+
+### Import Errors
+If you see module import errors:
+- Ensure the SDK is built: `npm run build`
+- Check that `dist/index.esm.js` exists
+- Verify you're using a browser that supports ES modules
+
+### Connection Errors
+If trace submission fails:
+- Check that the gateway URL is correct
+- Verify your API key is valid
+- Check the browser console for detailed error messages
+- Look at the Activity Log for specific error details
+
+## Code Structure
+
+```
+example/
+├── index.html          # Main HTML page with styles
+├── app.js              # Application logic using Parallax SDK
+└── README.md           # This file
+```
+
+The demo is intentionally simple (vanilla JavaScript + HTML/CSS) to focus on SDK usage without framework complexity.
+
+## Next Steps
+
+After exploring the demo:
+1. Check the Activity Log to see all SDK operations
+2. Open the browser DevTools to see network requests
+3. Modify `app.js` to experiment with different trace patterns
+4. Integrate the builder pattern into your own application
+
+## Learn More
+
+- [Parallax SDK Documentation](../README.md)
+- [API Reference](../src/parallax/index.ts)
+- [ParallaxService](../src/parallax/ParallaxService.ts) - Higher-level service wrapper

package/example/app.js

@@ -0,0 +1,411 @@
+// Import the Parallax SDK
+import { ParallaxClient } from '../dist/index.esm.js';
+
+// Initialize the client
+// Use proxy to avoid CORS issues (default)
+// To use direct connection, change to: 'https://parallax-gateway.dev.mirador.org:443'
+const USE_PROXY = true;
+const GATEWAY_URL = USE_PROXY 
+  ? 'http://localhost:3001'  // Proxy server (no CORS issues)
+  : 'https://parallax-gateway.dev.mirador.org:443';  // Direct (may have CORS issues)
+
+const client = new ParallaxClient('demo-api-key', GATEWAY_URL);
+
+// State management
+let currentTrace = null;
+let attributes = {};
+let tags = [];
+let events = [];
+
+// DOM elements
+const elements = {
+  // Inputs
+  traceName: document.getElementById('traceName'),
+  fromAddress: document.getElementById('fromAddress'),
+  toAddress: document.getElementById('toAddress'),
+  value: document.getElementById('value'),
+  network: document.getElementById('network'),
+  attrKey: document.getElementById('attrKey'),
+  attrValue: document.getElementById('attrValue'),
+  tagInput: document.getElementById('tagInput'),
+  eventName: document.getElementById('eventName'),
+  eventDetails: document.getElementById('eventDetails'),
+  txHash: document.getElementById('txHash'),
+  chainId: document.getElementById('chainId'),
+
+  // Buttons
+  createTraceBtn: document.getElementById('createTraceBtn'),
+  addAttributeBtn: document.getElementById('addAttributeBtn'),
+  addTagBtn: document.getElementById('addTagBtn'),
+  addEventBtn: document.getElementById('addEventBtn'),
+  submitBtn: document.getElementById('submitBtn'),
+  resetBtn: document.getElementById('resetBtn'),
+
+  // Sections
+  attributesSection: document.getElementById('attributesSection'),
+  tagsSection: document.getElementById('tagsSection'),
+  eventsSection: document.getElementById('eventsSection'),
+  submitSection: document.getElementById('submitSection'),
+
+  // Display
+  traceInfo: document.getElementById('traceInfo'),
+  traceId: document.getElementById('traceId'),
+  txId: document.getElementById('txId'),
+  attributesContainer: document.getElementById('attributesContainer'),
+  tagsContainer: document.getElementById('tagsContainer'),
+  log: document.getElementById('log'),
+  status: document.getElementById('status'),
+};
+
+// Logging functions
+function log(message, type = 'info') {
+  const time = new Date().toLocaleTimeString();
+  const entry = document.createElement('div');
+  entry.className = 'log-entry';
+  entry.innerHTML = `<span class="log-time">[${time}]</span> <span class="log-${type}">${message}</span>`;
+  elements.log.appendChild(entry);
+  elements.log.scrollTop = elements.log.scrollHeight;
+}
+
+function showStatus(message, type = 'info') {
+  elements.status.textContent = message;
+  elements.status.className = `status ${type} show`;
+  setTimeout(() => {
+    elements.status.classList.remove('show');
+  }, 5000);
+}
+
+// Step 1: Create Trace
+elements.createTraceBtn.addEventListener('click', () => {
+  const traceName = elements.traceName.value.trim();
+  const from = elements.fromAddress.value.trim();
+  const to = elements.toAddress.value.trim();
+  const value = elements.value.value.trim();
+  const network = elements.network.value;
+
+  if (!traceName || !from || !to || !value) {
+    showStatus('Please fill in all transaction fields', 'error');
+    log('❌ Validation failed: Missing required fields', 'error');
+    return;
+  }
+
+  try {
+    // Initialize a new trace builder
+    currentTrace = client.trace(traceName, true); // includeClientMeta = true
+
+    // Add default transaction attributes
+    currentTrace
+      .addAttribute('from', from)
+      .addAttribute('to', to)
+      .addAttribute('value', value)
+      .addAttribute('network', network)
+      .addAttribute('timestamp', new Date().toISOString())
+      .addTags(['demo', 'web-app', network]);
+
+    // Generate a mock transaction ID for demo purposes
+    const mockTxId = `demo_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+
+    // Show trace info
+    elements.traceInfo.classList.add('show');
+    elements.traceId.textContent = 'Pending (will be generated on submit)';
+    elements.txId.textContent = mockTxId;
+
+    // Show next sections
+    elements.attributesSection.classList.remove('hidden');
+    elements.tagsSection.classList.remove('hidden');
+    elements.eventsSection.classList.remove('hidden');
+    elements.submitSection.classList.remove('hidden');
+
+    log(`✅ Trace builder created: "${traceName}"`, 'success');
+    log(`📝 Added default attributes: from, to, value, network, timestamp`, 'info');
+    log(`🏷️  Added default tags: demo, web-app, ${network}`, 'info');
+    showStatus('Trace builder initialized! Add attributes, tags, and events below.', 'success');
+
+    // Disable create button
+    elements.createTraceBtn.disabled = true;
+    elements.createTraceBtn.textContent = 'Trace Created ✓';
+  } catch (error) {
+    log(`❌ Error creating trace: ${error.message}`, 'error');
+    showStatus(`Error: ${error.message}`, 'error');
+  }
+});
+
+// Step 2: Add Attributes
+elements.addAttributeBtn.addEventListener('click', () => {
+  const key = elements.attrKey.value.trim();
+  const value = elements.attrValue.value.trim();
+
+  if (!key || !value) {
+    showStatus('Please enter both key and value', 'error');
+    return;
+  }
+
+  if (!currentTrace) {
+    showStatus('Please create a trace first', 'error');
+    return;
+  }
+
+  // Add to trace builder
+  currentTrace.addAttribute(key, value);
+  attributes[key] = value;
+
+  // Update UI
+  updateAttributesDisplay();
+
+  // Clear inputs
+  elements.attrKey.value = '';
+  elements.attrValue.value = '';
+
+  log(`➕ Added attribute: ${key} = "${value}"`, 'info');
+  showStatus('Attribute added successfully', 'success');
+});
+
+function updateAttributesDisplay() {
+  if (Object.keys(attributes).length === 0) {
+    elements.attributesContainer.innerHTML = '<em style="color: #6c757d; font-size: 13px;">No custom attributes added yet</em>';
+    return;
+  }
+
+  elements.attributesContainer.innerHTML = '';
+  for (const [key, value] of Object.entries(attributes)) {
+    const item = document.createElement('div');
+    item.className = 'attribute-item';
+    item.innerHTML = `
+      <span class="attribute-key">${key}:</span>
+      <span class="attribute-value">${value}</span>
+    `;
+    elements.attributesContainer.appendChild(item);
+  }
+}
+
+// Step 3: Add Tags
+elements.addTagBtn.addEventListener('click', () => {
+  const tag = elements.tagInput.value.trim();
+
+  if (!tag) {
+    showStatus('Please enter a tag', 'error');
+    return;
+  }
+
+  if (!currentTrace) {
+    showStatus('Please create a trace first', 'error');
+    return;
+  }
+
+  if (tags.includes(tag)) {
+    showStatus('Tag already added', 'error');
+    return;
+  }
+
+  // Add to trace builder
+  currentTrace.addTag(tag);
+  tags.push(tag);
+
+  // Update UI
+  updateTagsDisplay();
+
+  // Clear input
+  elements.tagInput.value = '';
+
+  log(`🏷️  Added tag: "${tag}"`, 'info');
+  showStatus('Tag added successfully', 'success');
+});
+
+function updateTagsDisplay() {
+  if (tags.length === 0) {
+    elements.tagsContainer.innerHTML = '<em style="color: #6c757d; font-size: 13px;">No tags added yet</em>';
+    return;
+  }
+
+  elements.tagsContainer.innerHTML = '';
+  tags.forEach(tag => {
+    const chip = document.createElement('span');
+    chip.className = 'chip';
+    chip.textContent = tag;
+    elements.tagsContainer.appendChild(chip);
+  });
+}
+
+// Step 4: Add Events
+elements.addEventBtn.addEventListener('click', () => {
+  const eventName = elements.eventName.value.trim();
+  const eventDetails = elements.eventDetails.value.trim();
+
+  if (!eventName) {
+    showStatus('Please enter an event name', 'error');
+    return;
+  }
+
+  if (!currentTrace) {
+    showStatus('Please create a trace first', 'error');
+    return;
+  }
+
+  try {
+    let details = eventDetails;
+
+    // Try to parse as JSON if it looks like JSON
+    if (eventDetails && (eventDetails.startsWith('{') || eventDetails.startsWith('['))) {
+      try {
+        details = JSON.parse(eventDetails);
+      } catch (e) {
+        // If parsing fails, use as string
+        details = eventDetails;
+      }
+    }
+
+    // Add to trace builder
+    currentTrace.addEvent(eventName, details || undefined);
+    events.push({ name: eventName, details });
+
+    // Clear inputs
+    elements.eventName.value = '';
+    elements.eventDetails.value = '';
+
+    log(`📌 Added event: "${eventName}"${details ? ` with details` : ''}`, 'info');
+    showStatus('Event added successfully', 'success');
+  } catch (error) {
+    log(`❌ Error adding event: ${error.message}`, 'error');
+    showStatus(`Error: ${error.message}`, 'error');
+  }
+});
+
+// Step 5: Submit Trace
+elements.submitBtn.addEventListener('click', async () => {
+  if (!currentTrace) {
+    showStatus('Please create a trace first', 'error');
+    return;
+  }
+
+  const txHash = elements.txHash.value.trim();
+  const chainId = elements.chainId.value.trim();
+
+  try {
+    elements.submitBtn.disabled = true;
+    elements.submitBtn.textContent = 'Submitting...';
+
+    log('🚀 Submitting trace to Parallax Gateway...', 'info');
+
+    let response;
+    if (txHash && chainId) {
+      // Submit with transaction hash
+      response = await currentTrace.submit(txHash, chainId, 'Demo transaction');
+      log(`✅ Trace submitted with tx hash: ${txHash}`, 'success');
+    } else {
+      // Submit without transaction hash
+      response = await currentTrace.submit();
+      log('✅ Trace submitted without tx hash', 'success');
+    }
+
+    const traceId = response.getTraceId();
+    elements.traceId.textContent = traceId;
+
+    log(`🎉 Trace ID: ${traceId}`, 'success');
+    showStatus('Trace submitted successfully! Check the Activity Log for details.', 'success');
+
+    // Update button
+    elements.submitBtn.textContent = 'Submitted ✓';
+    elements.submitBtn.classList.remove('btn-success');
+    elements.submitBtn.classList.add('btn-secondary');
+
+    // Log summary
+    log('📊 Trace Summary:', 'info');
+    log(`   - Name: ${elements.traceName.value}`, 'info');
+    log(`   - Attributes: ${Object.keys(attributes).length + 5} total`, 'info');
+    log(`   - Tags: ${tags.length + 3} total`, 'info');
+    log(`   - Events: ${events.length} total`, 'info');
+    if (txHash) {
+      log(`   - Transaction Hash: ${txHash}`, 'info');
+      log(`   - Chain ID: ${chainId}`, 'info');
+    }
+  } catch (error) {
+    log(`❌ Error submitting trace: ${error.message}`, 'error');
+    showStatus(`Error: ${error.message}`, 'error');
+    elements.submitBtn.disabled = false;
+    elements.submitBtn.textContent = 'Submit Trace';
+  }
+});
+
+// Reset functionality
+elements.resetBtn.addEventListener('click', () => {
+  if (confirm('Are you sure you want to reset and start over?')) {
+    // Reset state
+    currentTrace = null;
+    attributes = {};
+    tags = [];
+    events = [];
+
+    // Reset UI
+    elements.traceName.value = 'demo_transaction';
+    elements.fromAddress.value = '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb';
+    elements.toAddress.value = '0x1234567890123456789012345678901234567890';
+    elements.value.value = '0.5';
+    elements.network.value = 'ethereum';
+    elements.txHash.value = '';
+    elements.chainId.value = '1';
+
+    // Hide sections
+    elements.attributesSection.classList.add('hidden');
+    elements.tagsSection.classList.add('hidden');
+    elements.eventsSection.classList.add('hidden');
+    elements.submitSection.classList.add('hidden');
+    elements.traceInfo.classList.remove('show');
+
+    // Reset buttons
+    elements.createTraceBtn.disabled = false;
+    elements.createTraceBtn.textContent = 'Create Trace';
+    elements.submitBtn.disabled = false;
+    elements.submitBtn.textContent = 'Submit Trace';
+    elements.submitBtn.classList.remove('btn-secondary');
+    elements.submitBtn.classList.add('btn-success');
+
+    // Clear displays
+    updateAttributesDisplay();
+    updateTagsDisplay();
+
+    log('🔄 Reset complete. Ready to create a new trace.', 'warn');
+    showStatus('Reset complete! You can create a new trace.', 'info');
+  }
+});
+
+// Keyboard shortcuts
+document.addEventListener('keydown', (e) => {
+  // Ctrl/Cmd + Enter to submit in text areas
+  if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') {
+    if (document.activeElement === elements.eventDetails) {
+      elements.addEventBtn.click();
+    }
+  }
+});
+
+log('🎨 Demo application loaded', 'success');
+log('ℹ️  Fill in the transaction details and click "Create Trace" to begin', 'info');
+
+// Check if proxy is running
+async function checkProxy() {
+  const proxyStatus = document.getElementById('proxyStatus');
+  if (!proxyStatus) return;
+
+  if (!USE_PROXY) {
+    proxyStatus.innerHTML = '<span style="color: #856404;">Direct connection (may have CORS issues)</span>';
+    return;
+  }
+
+  try {
+    const response = await fetch('http://localhost:3001/health');
+    const data = await response.json();
+    if (data.status === 'ok') {
+      proxyStatus.innerHTML = '<span style="color: #155724;">✓ Proxy server running on port 3001</span>';
+      log('✓ Proxy server is running', 'success');
+    } else {
+      proxyStatus.innerHTML = '<span style="color: #721c24;">✗ Proxy server error</span>';
+      log('✗ Proxy server returned unexpected response', 'error');
+    }
+  } catch (error) {
+    proxyStatus.innerHTML = '<span style="color: #721c24;">✗ Proxy server not running - run "npm run proxy" in a separate terminal</span>';
+    log('✗ Proxy server not running. Start it with: npm run proxy', 'error');
+  }
+}
+
+// Check proxy status on load
+checkProxy();