Skip to main content

​
Overview

The Mirador Web SDK is written in TypeScript and ships with complete type definitions. You get full IntelliSense, type checking, and autocompletion in supported editors.

​
Installation

Types are included in the package - no additional installation needed: 
npm install @miradorlabs/web-sdk

​
Importing Types

import {
  // Classes
  Client,
  Trace,

  // Types
  ClientOptions,
  TraceOptions,
  ChainName,
  ClientMetadata,
  TraceEvent,
  TxHashHint
} from '@miradorlabs/web-sdk';

​
Type Definitions

​
ClientOptions

Configuration for the client: 
interface ClientOptions {
  apiUrl?: string;  // Gateway URL
}

​
TraceOptions

Configuration for individual traces: 
interface TraceOptions {
  name?: string;              // Trace name
  includeUserMeta?: boolean;  // Include metadata (default: true)
  maxRetries?: number;        // Retry attempts (default: 3)
  retryBackoff?: number;      // Base backoff delay (default: 1000)
}

​
ChainName

Supported blockchain networks: 
type ChainName =
  | 'ethereum'
  | 'polygon'
  | 'arbitrum'
  | 'base'
  | 'optimism'
  | 'bsc';

​
TraceEvent

Structure of trace events: 
interface TraceEvent {
  name: string;
  details?: string;
  timestamp: number;
}

​
TxHashHint

Transaction hash hint structure: 
interface TxHashHint {
  txHash: string;
  chain: ChainName;
  details?: string;
}

​
ClientMetadata

Browser metadata structure: 
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;
}

​
Type-Safe Usage

​
Client Initialization

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

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

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

​
Trace Creation

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);

​
Chain Names

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

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

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

​
Generic Attribute Values

Attributes accept multiple types: 
// String
trace.addAttribute('userId', 'user-123');

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

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

​
Strict Mode

The SDK works well with TypeScript strict mode: 
// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true
  }
}

​
Handling Nullable Values

getTraceId() returns string | null: 
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');
}

​
IDE Support

​
VS Code

Full IntelliSense support out of the box:
  • Method autocompletion
  • Parameter hints
  • Type information on hover
  • Error highlighting for type mismatches

​
WebStorm / IntelliJ

Native TypeScript support provides:
  • Code completion
  • Quick documentation
  • Type inference
  • Refactoring support

​
Next Steps

Client API

Client class reference

Trace API

Trace builder reference