W3MSG Protocol Abstraction Layer - API Reference

This document provides comprehensive API reference for the W3MSG Protocol Abstraction Layer.

Table of Contents

• Core Classes
• Interfaces
• Enums
• Types
• Utility Functions
• Error Classes

---

Core Classes

W3MSGSDK

The main SDK class that orchestrates all protocol operations.

class W3MSGSDK extends EventEmitter {
  constructor(config: W3MSGSDKConfig)
  
  // Core Methods
  initialize(): Promise<void>
  connect(): Promise<void>
  disconnect(): Promise<void>
  isInitialized(): boolean
  isConnected(): boolean
  
  // Messaging
  send(params: SendMessageParams): Promise<MessageResult>
  listen(callback: MessageCallback): Promise<() => void>
  stopListening(): Promise<void>
  
  // Protocol Management
  getAvailableProtocols(): string[]
  getCurrentProtocol(): string | null
  switchProtocol(protocolName: string): Promise<void>
  
  // Health & Status
  getStatus(): SDKStatus
  getHealth(): HealthReport
  
  // Configuration
  updateConfig(config: Partial<W3MSGSDKConfig>): Promise<void>
  getConfig(): W3MSGSDKConfig
}

MessageProtocol (Abstract)

Base class for all protocol implementations.

abstract class MessageProtocol extends EventEmitter {
  abstract readonly name: string
  protected signer?: Signer
  protected config: ProtocolConfig = {}
  protected connectionStatus: ConnectionStatus = 'disconnected'
  
  // Lifecycle Methods
  abstract initialize(config: ProtocolConfig): Promise<void>
  abstract connect(): Promise<void>
  abstract disconnect(): Promise<void>
  
  // Messaging Methods
  abstract sendMessage(params: SendMessageParams): Promise<MessageResult>
  abstract startListening(callback: MessageCallback): Promise<() => void>
  abstract stopListening(): Promise<void>
  
  // Conversation Management
  abstract getConversations(): Promise<Conversation[]>
  abstract createConversation(participants: string[]): Promise<Conversation>
  
  // Health & Capabilities
  abstract performHealthCheck(): Promise<ProtocolHealthStatus>
  abstract getCapabilities(): ProtocolCapabilities
  
  // Status Methods
  getConnectionStatus(): ConnectionStatus
  getSigner(): Signer | undefined
  getConfig(): ProtocolConfig
  
  // Utility Methods (implemented)
  protected withRetry<T>(operation: () => Promise<T>, policy?: Partial<RetryPolicy>): Promise<T>
  protected normalizeError(error: unknown, context?: Partial<ErrorContext>): ProtocolError
  protected validateSigner(signer: any): signer is Signer
}

XMTPProtocol

XMTP protocol implementation.

class XMTPProtocol extends MessageProtocol {
  readonly name = 'xmtp'
  private client: Client | null = null
  private conversations: Map<string, Conversation> = new Map()
  
  // XMTP-specific Methods
  canMessage(address: string): Promise<boolean>
  getInboxId(address: string): Promise<string | null>
  exportConversations(): Promise<ConversationExport[]>
  importConversations(data: ConversationExport[]): Promise<void>
  
  // Inherited Methods (see MessageProtocol)
  initialize(config: ProtocolConfig): Promise<void>
  connect(): Promise<void>
  disconnect(): Promise<void>
  sendMessage(params: SendMessageParams): Promise<MessageResult>
  // ... etc
}

PushProtocol

Push Protocol implementation with browser compatibility.

class PushProtocol extends MessageProtocol {
  readonly name = 'push'
  private channel: string | null = null
  private subscriptions: Map<string, Subscription> = new Map()
  
  // Browser Compatibility
  private isPushSupported(): boolean
  private requestNotificationPermission(): Promise<NotificationPermission>
  private registerServiceWorker(): Promise<ServiceWorkerRegistration>
  
  // Push-specific Methods
  createChannel(channelData: ChannelData): Promise<string>
  subscribe(channelAddress: string): Promise<void>
  unsubscribe(channelAddress: string): Promise<void>
  getSubscriptions(): Promise<Subscription[]>
  
  // Inherited Methods (see MessageProtocol)
  initialize(config: ProtocolConfig): Promise<void>
  connect(): Promise<void>
  disconnect(): Promise<void>
  sendMessage(params: SendMessageParams): Promise<MessageResult>
  // ... etc
}

ProtocolManager

Manages protocol selection, switching, and health monitoring.

class ProtocolManager extends EventEmitter {
  constructor(
    signer: Signer,
    globalConfig: W3MSGSDKConfig,
    strategy?: Partial<ProtocolSelectionStrategy>,
    preferences?: Partial<UserProtocolPreferences>
  )
  
  // Protocol Management
  registerProtocol(protocol: MessageProtocol): Promise<void>
  unregisterProtocol(protocolName: string): Promise<void>
  getRegisteredProtocols(): string[]
  getProtocol(name: string): MessageProtocol | null
  
  // Protocol Selection
  selectBestProtocol(requirements?: MessageRequirements): Promise<ProtocolSelection>
  switchProtocol(protocolName: string, reason?: string): Promise<void>
  getCurrentProtocol(): MessageProtocol | null
  
  // Message Operations
  sendMessage(params: SendMessageParams): Promise<MessageResult>
  sendWithFallback(params: SendMessageParams): Promise<MessageResult>
  
  // Health & Status
  getProtocolHealth(protocolName: string): ProtocolHealth | null
  getAllProtocolHealth(): Map<string, ProtocolHealth>
  
  // Configuration
  updateStrategy(strategy: Partial<ProtocolSelectionStrategy>): void
  updatePreferences(preferences: Partial<UserProtocolPreferences>): void
  getStatus(): ProtocolManagerStatus
}

RetryManager

Centralized retry logic with multiple backoff strategies.

class RetryManager extends EventEmitter {
  static getInstance(): RetryManager
  
  // Core Execution
  execute<T>(
    operation: () => Promise<T>,
    policy?: Partial<RetryPolicy>
  ): Promise<T>
  
  // Policy Management
  createPolicy(config: Partial<RetryPolicy>): RetryPolicy
  getDefaultPolicy(type?: 'network' | 'api' | 'protocol'): RetryPolicy
  
  // Operation Management
  getActiveOperations(): ActiveOperation[]
  abortOperation(operationId: string): boolean
  abortAllOperations(): void
  
  // Statistics
  getStatistics(): RetryStatistics
  clearStatistics(): void
  
  // Helper Methods
  static createNetworkPolicy(overrides?: Partial<RetryPolicy>): RetryPolicy
  static createApiPolicy(overrides?: Partial<RetryPolicy>): RetryPolicy
  static createProtocolPolicy(overrides?: Partial<RetryPolicy>): RetryPolicy
}

HealthMonitor

Real-time protocol health monitoring and alerting.

class HealthMonitor extends EventEmitter {
  static getInstance(): HealthMonitor
  
  // Protocol Registration
  registerProtocol(
    protocolName: string,
    healthCheck: () => Promise<ProtocolHealthStatus>
  ): void
  unregisterProtocol(protocolName: string): void
  
  // Monitoring Control
  startMonitoring(): void
  stopMonitoring(): void
  configure(config: Partial<HealthCheckConfig>): void
  
  // Health Data
  getProtocolHealth(protocolName: string): HealthMetric | null
  getHealthTrend(protocolName: string, timeRangeMs?: number): HealthTrend | null
  generateHealthReport(): HealthReport
  
  // Manual Health Checks
  performHealthChecks(): Promise<void>
  checkProtocolHealth(protocolName: string): Promise<HealthMetric>
  
  // Data Management
  clearAllData(): void
  getMonitoringStatus(): MonitoringStatus
  
  // Event Handling
  on(event: string, handler: Function): this
  off(event: string, handler: Function): this
  emit(event: string, data: any): boolean
}

CircuitBreaker

Fault tolerance and automatic failover protection.

class CircuitBreaker extends EventEmitter {
  constructor(config: CircuitBreakerConfig)
  
  // Static Factory Methods
  static createForProtocol(protocolName: string): CircuitBreaker
  static createRealtimeBreaker(): CircuitBreaker
  static createNotificationBreaker(): CircuitBreaker
  
  // Execution
  execute<T>(operation: () => Promise<T>): Promise<T>
  
  // State Management
  getState(): CircuitBreakerState
  reset(): void
  forceOpen(): void
  forceHalfOpen(): void
  
  // Metrics
  getMetrics(): CircuitBreakerMetrics
  recordSuccess(): void
  recordFailure(): void
  
  // Configuration
  updateConfig(config: Partial<CircuitBreakerConfig>): void
  getConfig(): CircuitBreakerConfig
}

MigrationManager

Handles protocol version migrations and data transitions.

class MigrationManager extends EventEmitter {
  static getInstance(): MigrationManager
  
  // Migration Detection
  needsMigration(protocolName: string): Promise<boolean>
  getStoredVersion(protocolName: string): string | null
  getCurrentVersion(protocolName: string): string
  
  // Migration Planning
  createMigrationPlan(protocolName: string): Promise<MigrationPlan>
  validateMigrationPlan(plan: MigrationPlan): Promise<MigrationValidation>
  
  // Migration Execution
  executeMigration(
    protocolName: string,
    options?: MigrationOptions
  ): Promise<MigrationResult>
  rollbackMigration(
    protocolName: string,
    targetVersion?: string
  ): Promise<MigrationResult>
  
  // Migration History
  getMigrationHistory(protocolName: string): MigrationRecord[]
  clearMigrationHistory(protocolName: string): void
  
  // Step Management
  registerMigrationStep(step: MigrationStep): void
  getAvailableSteps(protocolName: string): MigrationStep[]
}

BrowserCompatibility

Browser feature detection and compatibility management.

class BrowserCompatibility extends EventEmitter {
  static getInstance(): BrowserCompatibility
  
  // Browser Detection
  getBrowser(): BrowserInfo
  getPlatform(): PlatformInfo
  getEngine(): EngineInfo
  isSecureContext(): boolean
  
  // Feature Detection
  hasFeature(feature: string): boolean
  getWebAPISupport(): WebAPISupport
  getW3MSGCompatibilityReport(): CompatibilityReport
  isW3MSGCompatible(): boolean
  
  // Performance & Metrics
  getPerformanceSupport(): PerformanceSupport
  getMemoryInfo(): MemoryInfo | null
  getNetworkInfo(): NetworkInfo | null
  
  // Polyfill Management
  loadPolyfill(polyfillName: string): Promise<void>
  registerPolyfill(name: string, loader: () => Promise<void>): void
  getLoadedPolyfills(): string[]
}

---

Interfaces

Core Configuration

interface W3MSGSDKConfig {
  signer: Signer
  protocols?: string[]
  environment?: 'development' | 'staging' | 'production'
  apiKeys?: Record<string, string>
  endpoints?: Record<string, string>
  relayEndpoint?: string
  retryPolicy?: 'aggressive' | 'moderate' | 'conservative' | RetryPolicy
  healthMonitoring?: boolean | HealthCheckConfig
  circuitBreaker?: boolean | CircuitBreakerConfig
  migration?: boolean | MigrationConfig
  browserCompatibility?: boolean | BrowserCompatibilityConfig
}

interface ProtocolConfig {
  signer: Signer
  environment: 'development' | 'staging' | 'production'
  apiKeys?: Record<string, string>
  endpoints?: Record<string, string>
  features?: ProtocolFeatures
  retryPolicy?: RetryPolicy
}

interface ProtocolFeatures {
  encryption?: boolean
  groupChat?: boolean
  fileAttachments?: boolean
  reactions?: boolean
  messageEditing?: boolean
  messageHistory?: boolean
}

Message Types

interface SendMessageParams {
  to: string
  content: string | MessageContent
  type?: MessageType
  conversationId?: string
  metadata?: Record<string, any>
  options?: MessageOptions
}

interface MessageContent {
  title?: string
  body: string
  image?: string
  cta?: string
  url?: string
  payload?: Record<string, any>
}

interface MessageResult {
  id: string
  status: MessageStatus
  timestamp: number
  protocol: string
  conversationId?: string
  metadata?: Record<string, any>
}

interface Message {
  id: string
  conversationId: string
  from: string
  to: string[]
  content: string | MessageContent
  timestamp: number
  status: MessageStatus
  protocol: string
  metadata?: Record<string, any>
}

Protocol Health & Status

interface ProtocolHealthStatus {
  isHealthy: boolean
  latency: number
  errorCount: number
  uptime: number
  lastCheck: number
  features: Record<string, boolean>
  metadata?: Record<string, any>
}

interface HealthMetric {
  timestamp: number
  protocolName: string
  isHealthy: boolean
  latency: number
  errorCount: number
  successCount: number
  uptime: number
  features: Record<string, boolean>
  metadata?: Record<string, any>
}

interface HealthTrend {
  protocolName: string
  timeRange: { start: number; end: number }
  averageLatency: number
  errorRate: number
  uptimePercent: number
  trend: 'improving' | 'stable' | 'degrading'
  confidence: number
  issues: string[]
  recommendations: string[]
}

interface HealthReport {
  timestamp: number
  overallHealth: 'healthy' | 'degraded' | 'unhealthy'
  protocolCount: number
  healthyCount: number
  protocols: {
    name: string
    status: ProtocolHealthStatus
    trend: HealthTrend
    alerts: HealthAlert[]
  }[]
  systemMetrics: SystemMetrics
  recommendations: string[]
}

Error Handling

interface ProtocolError extends Error {
  category: ErrorCategory
  severity: ErrorSeverity
  protocol: string
  method: string
  timestamp: number
  recovery?: ErrorRecovery
  context: ErrorContext
}

interface ErrorRecovery {
  canRetry: boolean
  maxRetries?: number
  retryAfterMs?: number
  fallbackAvailable: boolean
  userAction?: 'none' | 'retry' | 'switchProtocol' | 'reconnect'
  autoRecovery: boolean
}

interface ErrorContext {
  protocol: string
  method: string
  timestamp: number
  originalError?: Error
  additionalData?: Record<string, any>
}

Retry Logic

interface RetryPolicy {
  maxRetries: number
  baseDelay: number
  multiplier: number
  backoffStrategy: BackoffStrategy
  timeoutMs: number
  shouldRetry?: (error: any, attempt: number) => boolean
  onRetry?: (error: any, attempt: number) => void
}

interface ActiveOperation {
  id: string
  operation: Function
  policy: RetryPolicy
  startTime: number
  attempts: number
  abortController: AbortController
}

interface RetryStatistics {
  totalOperations: number
  successfulOperations: number
  failedOperations: number
  totalRetries: number
  averageRetries: number
  averageLatency: number
}

Circuit Breaker

interface CircuitBreakerConfig {
  failureThreshold: number
  recoveryTimeout: number
  halfOpenRetries: number
  monitoringPeriod: number
  exponentialBackoff: boolean
  jitter: boolean
}

interface CircuitBreakerMetrics {
  state: CircuitBreakerState
  failureCount: number
  successCount: number
  totalRequests: number
  lastFailureTime: number
  nextRetryTime: number
}

---

Enums

enum MessageType {
  CHAT = 'chat',
  NOTIFICATION = 'notification',
  SYSTEM = 'system'
}

enum MessageStatus {
  PENDING = 'pending',
  SENT = 'sent',
  DELIVERED = 'delivered',
  READ = 'read',
  FAILED = 'failed'
}

enum ConnectionStatus {
  DISCONNECTED = 'disconnected',
  CONNECTING = 'connecting',
  CONNECTED = 'connected',
  RECONNECTING = 'reconnecting',
  ERROR = 'error'
}

enum ErrorCategory {
  NETWORK = 'NETWORK',
  AUTHENTICATION = 'AUTHENTICATION',
  PROTOCOL_INIT = 'PROTOCOL_INIT',
  MESSAGE_SEND = 'MESSAGE_SEND',
  RATE_LIMIT = 'RATE_LIMIT',
  BROWSER_UNSUPPORTED = 'BROWSER_UNSUPPORTED',
  VC_VERIFICATION = 'VC_VERIFICATION',
  CONVERSATION_NOT_FOUND = 'CONVERSATION_NOT_FOUND',
  PERMISSION_DENIED = 'PERMISSION_DENIED',
  WALLET_ERROR = 'WALLET_ERROR'
}

enum ErrorSeverity {
  LOW = 'LOW',
  MEDIUM = 'MEDIUM',
  HIGH = 'HIGH',
  CRITICAL = 'CRITICAL'
}

enum BackoffStrategy {
  EXPONENTIAL = 'exponential',
  LINEAR = 'linear',
  FIXED = 'fixed',
  EXPONENTIAL_JITTER = 'exponential_jitter',
  POLYNOMIAL = 'polynomial'
}

enum CircuitBreakerState {
  CLOSED = 'CLOSED',
  OPEN = 'OPEN',
  HALF_OPEN = 'HALF_OPEN'
}

---

Types

type MessageCallback = (message: Message) => void | Promise<void>

type HealthCheckCallback = () => Promise<ProtocolHealthStatus>

type ProtocolSelection = {
  protocol: MessageProtocol
  score: number
  reasons: string[]
  alternatives: { protocol: string; score: number }[]
}

type SystemMetrics = {
  totalRequests: number
  totalErrors: number
  averageLatency: number
  overallUptime: number
}

type BrowserInfo = {
  name: string
  version: string
  majorVersion: number
}

type PlatformInfo = {
  name: string
  version: string
  architecture: string
  isMobile: boolean
}

---

Utility Functions

RetryHelpers

// Network operations retry helper
function withNetworkRetry<T>(
  operation: () => Promise<T>,
  overrides?: Partial<RetryPolicy>
): Promise<T>

// API calls retry helper
function withApiRetry<T>(
  operation: () => Promise<T>,
  overrides?: Partial<RetryPolicy>
): Promise<T>

// Protocol operations retry helper
function withProtocolRetry<T>(
  operation: () => Promise<T>,
  overrides?: Partial<RetryPolicy>
): Promise<T>

// Timeout-constrained operations
function withTimeout<T>(
  operation: () => Promise<T>,
  timeoutMs: number
): Promise<T>

// Custom retry conditions
function withCondition<T>(
  operation: () => Promise<T>,
  shouldRetry: (error: any, attempt: number) => boolean,
  policy?: Partial<RetryPolicy>
): Promise<T>

Web3Utils

// Address validation
function isValidAddress(address: string): boolean

// Address formatting
function normalizeAddress(address: string): string

// Signer validation
function validateSigner(signer: any): signer is Signer

// Transaction safety
function simulateTransaction(params: TransactionParams): Promise<TransactionSimulation>

// Provider utilities
function createProvider(config: ProviderConfig): Provider
function getNetwork(provider: Provider): Promise<Network>

---

Error Classes

class W3MSGError extends Error {
  constructor(message: string, cause?: Error)
  
  toJSON(): ErrorJSON
  toString(): string
  getStackTrace(): string
}

class ProtocolError extends W3MSGError {
  constructor(
    message: string,
    category: ErrorCategory,
    severity: ErrorSeverity,
    context: ErrorContext,
    recovery?: ErrorRecovery
  )
}

class WalletConnectionError extends W3MSGError {
  constructor(message: string, walletType?: string)
}

class VCVerificationError extends W3MSGError {
  constructor(message: string, vcType?: string)
}

---

Events

SDK Events

// Connection events
'connected' | 'disconnected' | 'reconnecting' | 'error'

// Message events  
'message:sent' | 'message:received' | 'message:failed'

// Protocol events
'protocol:registered' | 'protocol:switched' | 'protocol:error'

// Health events
'health:alert' | 'health:recovered' | 'health:degraded'

Protocol Events

// Lifecycle events
'initialized' | 'connected' | 'disconnected'

// Message events
'message:sent' | 'message:received' | 'conversation:created'

// Health events
'health:check' | 'health:changed'

Monitoring Events

// Health monitoring
'health:protocol_checked' | 'health:alert_created' | 'health:data_cleared'

// Retry events
'retry:attempt' | 'retry:success' | 'retry:exhausted'

// Circuit breaker events
'circuit:opened' | 'circuit:closed' | 'circuit:half_open'

---

Usage Examples

See Usage Examples for practical implementation examples using these APIs.