Types

import type {
  ClientOptions,
  TraceOptions,
  AddEventOptions,
  ChainName,
  ClientMetadata,
  TraceEvent,
  TxHashHint,
  StackFrame,
  StackTrace
} from '@miradorlabs/web-sdk';

import type {
  ClientOptions,
  TraceOptions,
  AddEventOptions,
  ChainName,
  StackFrame,
  StackTrace
} from '@miradorlabs/nodejs-sdk';

interface ClientOptions {
  /**
   * Gateway URL for the Mirador Ingest API
   * @default 'ingest-gateway-dev.mirador.org:443'
   */
  apiUrl?: string;

  /**
   * Keep-alive ping interval in milliseconds
   * @default 10000
   */
  keepAliveIntervalMs?: number;
}

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

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

interface TraceOptions {
  /**
   * Name identifying the trace
   */
  name?: string;

  /**
   * Include browser metadata on first flush
   * @default true
   */
  includeUserMeta?: boolean;

  /**
   * Maximum retry attempts on network failure
   * @default 3
   */
  maxRetries?: number;

  /**
   * Base delay in ms for exponential backoff
   * @default 1000
   */
  retryBackoff?: number;

  /**
   * Automatically close trace on page unload
   * @default false
   */
  autoClose?: boolean;
}

interface TraceOptions {
  /**
   * Name identifying the trace
   */
  name?: string;

  /**
   * Capture stack trace at trace creation point
   * @default true
   */
  captureStackTrace?: boolean;

  /**
   * Maximum retry attempts on network failure
   * @default 3
   */
  maxRetries?: number;

  /**
   * Base delay in ms for exponential backoff
   * @default 1000
   */
  retryBackoff?: number;
}

const options: TraceOptions = {
  name: 'MyTrace',
  includeUserMeta: true,
  maxRetries: 5,
  retryBackoff: 2000
};

const trace = client.trace(options);

const options: TraceOptions = {
  name: 'MyTrace',
  captureStackTrace: false
};

const trace = client.trace(options);

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

const chain: ChainName = 'ethereum';
trace.addTxHint(txHash, chain);

// Type-safe: only valid chains allowed
trace.addTxHint(hash, 'polygon');   // ✓
trace.addTxHint(hash, 'invalid');   // ✗ Type error

interface TraceEvent {
  /**
   * Event name
   */
  eventName: string;

  /**
   * Optional event details (stringified if object)
   */
  details?: string;

  /**
   * Timestamp of the event
   */
  timestamp: Date;
}

// Events are created internally by addEvent()
trace.addEvent('my_event', { key: 'value' });

// The SDK creates a TraceEvent like:
// {
//   eventName: 'my_event',
//   details: '{"key":"value"}',
//   timestamp: new Date()
// }

interface TxHashHint {
  /**
   * Transaction hash
   */
  txHash: string;

  /**
   * Blockchain network
   */
  chain: ChainName;

  /**
   * Optional description
   */
  details?: string;

  /**
   * Timestamp of the hint
   */
  timestamp: Date;
}

// TxHashHints are created internally by addTxHint()
trace.addTxHint('0x123...', 'ethereum', 'Swap transaction');

// The SDK creates a TxHashHint like:
// {
//   txHash: '0x123...',
//   chain: 'ethereum',
//   details: 'Swap transaction'
// }

interface AddEventOptions {
  /**
   * Capture stack trace at event location
   * @default false
   */
  captureStackTrace?: boolean;
}

// Capture stack trace for debugging
trace.addEvent('error_occurred', { code: 500 }, { captureStackTrace: true });

interface StackFrame {
  /**
   * Function name (or '<anonymous>')
   */
  functionName: string;

  /**
   * File name or URL
   */
  fileName: string;

  /**
   * Line number
   */
  lineNumber: number;

  /**
   * Column number
   */
  columnNumber: number;
}

interface StackTrace {
  /**
   * Parsed stack frames
   */
  frames: StackFrame[];

  /**
   * Original Error.stack string
   */
  raw: string;
}

import { captureStackTrace, formatStackTrace } from '@miradorlabs/web-sdk';

// Capture current stack trace
const stack = captureStackTrace();

// Format for storage
const json = formatStackTrace(stack);

// Format for display
const readable = formatStackTraceReadable(stack);

interface ClientMetadata {
  // Browser
  browser?: string;
  browserVersion?: string;
  userAgent?: string;

  // Operating System
  os?: string;
  osVersion?: string;
  deviceType?: string;

  // Display
  screenWidth?: string;
  screenHeight?: string;
  viewportWidth?: string;
  viewportHeight?: string;
  colorDepth?: string;
  pixelRatio?: string;

  // Hardware
  cpuCores?: string;
  deviceMemory?: string;
  touchSupport?: string;

  // Network
  connectionType?: string;
  online?: string;

  // Locale
  language?: string;
  languages?: string;
  timezone?: string;
  timezoneOffset?: string;

  // Page Context
  url?: string;
  origin?: string;
  pathname?: string;
  referrer?: string;
  documentVisibility?: string;

  // Privacy
  cookiesEnabled?: string;
  doNotTrack?: string;
}

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

const metadata: ClientMetadata = getClientMetadata();
console.log(metadata.browser);      // 'Chrome'
console.log(metadata.deviceType);   // 'desktop'

import {
  getClientMetadata,
  detectBrowser,
  detectOS,
  detectDeviceType,
  captureStackTrace,
  formatStackTrace,
  formatStackTraceReadable
} from '@miradorlabs/web-sdk';

// Get full metadata object
const metadata = getClientMetadata();

// Individual detection
const browser = detectBrowser();
// { name: 'Chrome', version: '120.0.0' }

const os = detectOS();
// { name: 'macOS', version: '14.0' }

const device = detectDeviceType();
// 'desktop' | 'mobile' | 'tablet'