TypeScript

npm install @miradorlabs/web-sdk

import {
  // Classes
  Client,
  Trace,

  // Types
  ClientOptions,
  TraceOptions,
  ChainName,
  Severity,
  ClientMetadata,
  TraceEvent,
  TxHashHint,
  TraceCallbacks,
  MiradorPlugin,
  TraceContext,
  PluginSetupResult,
  FlushBuilder,
  NoopTrace,
  HintType
} from '@miradorlabs/web-sdk';

interface ClientOptions {
  apiUrl?: string;        // Gateway URL
  debug?: boolean;        // Enable debug logging
  plugins?: MiradorPlugin[];  // Plugins to install
  sampleRate?: number;    // Sampling rate (0-1)
  callbacks?: TraceCallbacks; // Lifecycle callbacks
}

interface TraceOptions {
  name?: string;              // Trace name
  traceId?: string;           // Pre-set trace ID (W3C compatible, 32-char hex)
  includeUserMeta?: boolean;  // Include metadata (default: true)
  maxRetries?: number;        // Retry attempts (default: 2)
  retryBackoff?: number;      // Base backoff delay (default: 500)
  maxQueueSize?: number;      // Max queue size (default: 4096)
  callbacks?: TraceCallbacks; // Per-trace lifecycle callbacks
}

type ChainName =
  | 'ethereum'
  | 'polygon'
  | 'arbitrum'
  | 'base'
  | 'optimism'
  | 'bsc';

interface TraceEvent {
  name: string;
  details?: string;
  timestamp: number;
}

interface TxHashHint {
  txHash: string;
  chain: ChainName;
  details?: string;
}

interface ClientMetadata {
  browser?: string;
  browserVersion?: string;
  os?: string;
  osVersion?: string;
  deviceType?: string;
  userAgent?: string;
  language?: string;
  languages?: string;
  screenWidth?: number;
  screenHeight?: number;
  viewportWidth?: number;
  viewportHeight?: number;
  colorDepth?: number;
  pixelRatio?: number;
  cpuCores?: number;
  deviceMemory?: number;
  touchSupport?: boolean;
  connectionType?: string;
  cookiesEnabled?: boolean;
  online?: boolean;
  doNotTrack?: boolean;
  timezone?: string;
  timezoneOffset?: number;
  url?: string;
  origin?: string;
  pathname?: string;
  referrer?: string;
  documentVisibility?: string;
}

import { Client, ClientOptions } from '@miradorlabs/web-sdk';

const options: ClientOptions = {
  apiUrl: 'https://custom-gateway.example.com'
};

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

import { Client, TraceOptions } from '@miradorlabs/web-sdk';

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

const traceOptions: TraceOptions = {
  name: 'TypedTrace',
  maxRetries: 5
};

const trace = client.trace(traceOptions);

import { ChainName } from '@miradorlabs/web-sdk';

function addTransaction(txHash: string, chain: ChainName) {
  trace.web3.evm.addTxHint(txHash, chain);
}

// Type-safe - only valid chains allowed
addTransaction('0x123...', 'ethereum');  // ✓
addTransaction('0x456...', 'polygon');   // ✓
addTransaction('0x789...', 'invalid');   // ✗ Type error!

// String
trace.addAttribute('userId', 'user-123');

// Number
trace.addAttribute('amount', 1.5);

// Object (stringified)
trace.addAttribute('config', { slippage: 0.5, deadline: 300 });

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true
  }
}

const traceId = trace.getTraceId();

if (traceId) {
  // traceId is string here
  console.log(`Trace: ${traceId}`);
} else {
  // First flush hasn't completed yet
  console.log('Trace ID not yet available');
}