Skip to main content

​
Installation

Install the SDK for your environment: Web SDK: 
npm install @miradorlabs/web-sdk
Node.js SDK: 
npm install @miradorlabs/nodejs-sdk

​
Basic Usage

​
1. Initialize the Client

Web SDK: 
import { Client } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key');
Node.js SDK: 
import { Client } from '@miradorlabs/nodejs-sdk';

const client = new Client('your-api-key');

​
2. Create a Trace

Web SDK: 
const trace = client.trace({ name: 'UserAction' })
  .addAttribute('userId', 'user-123')
  .addEvent('action_started');
// → CreateTrace sent automatically at end of current microtask
Node.js SDK: 
const trace = client.trace({ name: 'UserAction' })
  .addAttribute('userId', 'user-123')
  .addEvent('action_started');

const traceId = await trace.create();
// → CreateTrace sent immediately

​
3. Update the Trace

As your application flow progresses, add more data: Web SDK: 
trace.addEvent('processing')
     .addAttribute('step', 'validation');
// → UpdateTrace sent automatically at end of current microtask

trace.addEvent('completed', { result: 'success' });
// → UpdateTrace sent automatically at end of current microtask
Node.js SDK: 
trace.addEvent('processing')
     .addAttribute('step', 'validation');
// Updates are queued locally

trace.addEvent('completed', { result: 'success' });
// Updates are queued locally

// Close the trace to send final updates
await trace.close('Workflow completed');

​
Complete Example

Here’s a real-world example tracking a blockchain transaction: Web SDK: 
import { Client } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key');

async function handleTransaction(userAddress: string, amount: string) {
  // Create trace with initial context
  const trace = client.trace({ name: 'SendETH' })
    .addAttribute('from', userAddress)
    .addAttribute('amount', amount)
    .addTags(['transaction', 'ethereum'])
    .addEvent('wallet_connected');
  // → CreateTrace sent automatically

  try {
    // Sign transaction
    trace.addEvent('user_signing');
    const receipt = await sendTransaction();

    // Record transaction hash for correlation
    trace.addEvent('transaction_sent', { txHash: receipt.hash })
         .addTxHint(receipt.hash, 'ethereum');
    // → UpdateTrace sent automatically
    
    // Close the trace when done
    await trace.close('Transaction completed successfully');
  } catch (error) {
    trace.addEvent('transaction_failed', { error: error.message });
    await trace.close('Transaction failed');
  }
}
Node.js SDK: 
import { Client } from '@miradorlabs/nodejs-sdk';

const client = new Client('your-api-key');

async function handleTransaction(userAddress: string, amount: string) {
  // Create trace with initial context
  const trace = client.trace({ name: 'SendETH' })
    .addAttribute('from', userAddress)
    .addAttribute('amount', amount)
    .addTags(['transaction', 'ethereum'])
    .addEvent('wallet_connected');

  try {
    const traceId = await trace.create();
    // → CreateTrace sent immediately

    // Sign transaction
    trace.addEvent('user_signing');
    const receipt = await sendTransaction();

    // Record transaction hash for correlation
    trace.addEvent('transaction_sent', { txHash: receipt.hash })
         .addTxHint(receipt.hash, 'ethereum');
    
    // Close the trace when done
    await trace.close('Transaction completed successfully');
  } catch (error) {
    trace.addEvent('transaction_failed', { error: error.message });
    await trace.close('Transaction failed');
  }
}

​
Flushing (Web SDK)

The Web SDK automatically batches and sends trace data at the end of the current JavaScript tick (microtask). You can also call flush() manually at any time to send pending data immediately.
The Node.js SDK uses explicit create() and close() methods instead of automatic flushing.

​
Next Steps