> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirador.org/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript

> Full type definitions for the SDK

## 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:

```bash theme={null}
npm install @miradorlabs/web-sdk
```

## Importing Types

```typescript theme={null}
import {
  // Classes
  Client,
  Trace,

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

## Type Definitions

### ClientOptions

Configuration for the client:

```typescript theme={null}
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
}
```

### TraceOptions

Configuration for individual traces:

```typescript theme={null}
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
}
```

### ChainName

Supported blockchain networks:

```typescript theme={null}
type ChainName =
  | 'ethereum'
  | 'polygon'
  | 'arbitrum'
  | 'base'
  | 'optimism'
  | 'bsc';
```

### TraceEvent

Structure of trace events:

```typescript theme={null}
interface TraceEvent {
  name: string;
  details?: string;
  timestamp: number;
}
```

### TxHashHint

Transaction hash hint structure:

```typescript theme={null}
interface TxHashHint {
  txHash: string;
  chain: ChainName;
  details?: string;
}
```

### ClientMetadata

Browser metadata structure:

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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!
```

### Generic Attribute Values

Attributes accept multiple types:

```typescript theme={null}
// 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:

```json theme={null}
// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true
  }
}
```

### Handling Nullable Values

`getTraceId()` returns `string | null`:

```typescript theme={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

<CardGroup cols={2}>
  <Card title="Client API" icon="plug" href="/api-reference/client">
    Client class reference
  </Card>

  <Card title="Trace API" icon="route" href="/api-reference/trace">
    Trace builder reference
  </Card>
</CardGroup>