Relay Communication

/**
 * Main relay interface extending IEvents for message routing
 * Handles all network communication in the WalletConnect protocol
 */
interface IRelayer extends IEvents {
  /** Core protocol instance */
  readonly core: ICore;
  /** Logger instance */
  readonly logger: ILogger;
  /** Event emitter */
  readonly events: EventEmitter;
  /** JSON-RPC provider for relay communication */
  readonly provider: JsonRpcProvider;
  /** Message tracking interface */
  readonly messages: IMessageTracker;
  /** Subscription management interface */
  readonly subscriber: ISubscriber;
  /** Publishing interface */
  readonly publisher: IPublisher;
  /** Whether transport was explicitly closed */
  readonly transportExplicitlyClosed: boolean;

  /** Initialize the relayer */
  init(): Promise<void>;
  /** Publish message to topic */
  publish(topic: string, message: string, opts?: RelayerTypes.PublishOptions): Promise<void>;
  /** Subscribe to topic for incoming messages */
  subscribe(topic: string, opts?: RelayerTypes.SubscribeOptions): Promise<string>;
  /** Unsubscribe from topic */
  unsubscribe(topic: string, opts?: RelayerTypes.UnsubscribeOptions): Promise<void>;
}

namespace RelayerTypes {
  /**
   * Relay protocol configuration
   */
  interface ProtocolOptions {
    /** Protocol name (e.g., "irn") */
    protocol: string;
    /** Optional protocol-specific data */
    data?: string;
  }

  /**
   * Transport method options for communication
   */
  type TransportType = "relay" | "link_mode";

  /**
   * Message publishing options with TTL, tags, and attestation
   */
  interface PublishOptions {
    /** Relay protocol options */
    relay?: ProtocolOptions;
    /** Time-to-live in seconds */
    ttl?: number;
    /** Whether to prompt user for confirmation */
    prompt?: boolean;
    /** Message tag for categorization */
    tag?: number;
    /** Request ID for tracking */
    id?: number;
    /** Attestation string for verification */
    attestation?: string;
  }

  /**
   * Subscription options for topics
   */
  interface SubscribeOptions {
    /** Relay protocol options */
    relay?: ProtocolOptions;
  }

  /**
   * Unsubscription options
   */
  interface UnsubscribeOptions {
    /** Unsubscription ID */
    id?: string;
    /** Relay protocol options */
    relay?: ProtocolOptions;
  }

  /**
   * Union of all request option types
   */
  type RequestOptions = PublishOptions | SubscribeOptions | UnsubscribeOptions;

  /**
   * Message direction for tracking
   */
  type MessageDirection = "inbound" | "outbound";
}

namespace RelayerTypes {
  /**
   * Payload structure for publishing messages
   */
  interface PublishPayload {
    /** Message topic */
    topic: string;
    /** Message content */
    message: string;
    /** Publishing options */
    opts?: PublishOptions;
  }

  /**
   * Incoming message event structure
   */
  interface MessageEvent {
    /** Message topic */
    topic: string;
    /** Message content */
    message: string;
    /** Publication timestamp */
    publishedAt: number;
    /** Optional attestation for verification */
    attestation?: string;
  }

  /**
   * RPC URL construction parameters
   */
  interface RpcUrlParams {
    /** WalletConnect Cloud project ID */
    projectId: string;
    /** Relay URL */
    relayUrl: string;
    /** SDK version */
    sdkVersion: string;
    /** Authentication token (optional) */
    auth?: string;
    /** User agent string (optional) */
    userAgent?: string;
  }

  /**
   * Transaction verification framework parameters
   */
  interface ITVF {
    /** Verification URL */
    url: string;
    /** Validation type */
    validation: string;
  }
}

/**
 * Relayer initialization options
 */
interface RelayerOptions {
  /** Core protocol instance */
  core: ICore;
  /** Logger instance */
  logger: ILogger;
  /** Relay URL */
  relayUrl: string;
  /** WalletConnect Cloud project ID */
  projectId: string;
}

/**
 * Client metadata for relayer identification
 */
interface RelayerClientMetadata {
  /** Protocol name */
  protocol: string;
  /** Protocol version */
  version: number;
  /** Environment (e.g., "browser", "react-native") */
  env: string;
  /** Host information (optional) */
  host?: string;
}

/**
 * Message publishing interface extending IEvents
 * Handles outbound message transmission
 */
interface IPublisher extends IEvents {
  readonly name: string;
  readonly context: string;

  /** Publish message to topic */
  publish(topic: string, message: string, opts?: PublisherTypes.Params): Promise<void>;
}

namespace PublisherTypes {
  /**
   * Publishing parameters with topic, message, and options
   */
  interface Params {
    /** Target topic */
    topic: string;
    /** Message content */
    message: string;
    /** Publishing options */
    opts?: RelayerTypes.PublishOptions;
  }
}

/**
 * Subscription management interface extending IEvents
 * Handles topic subscriptions and message receipt
 */
interface ISubscriber extends IEvents {
  readonly name: string;
  readonly context: string;
  readonly logger: ILogger;
  readonly subscription: ISubscriberTopicMap;

  /** Initialize subscriber */
  init(): Promise<void>;
  /** Subscribe to topic */
  subscribe(topic: string, opts?: SubscriberTypes.Params): Promise<string>;
  /** Unsubscribe from topic with optional ID */
  unsubscribe(topic: string, opts?: { id?: string }): Promise<void>;
  /** Check if subscribed to topic */
  isSubscribed(topic: string): boolean;
}

namespace SubscriberTypes {
  /**
   * Subscription parameters extending relay options
   */
  interface Params extends RelayerTypes.SubscribeOptions {
    /** Relay protocol options */
    relay?: RelayerTypes.ProtocolOptions;
  }

  /**
   * Active subscription with ID
   */
  interface Active {
    /** Subscription topic */
    topic: string;
    /** Subscription ID */
    id: string;
  }
}

namespace SubscriberEvents {
  /**
   * Created subscription event
   */
  type Created = SubscriberTypes.Active;

  /**
   * Deleted subscription event with reason
   */
  interface Deleted extends SubscriberTypes.Active {
    /** Deletion reason */
    reason: string;
  }

  /**
   * Expired subscription event
   */
  type Expired = SubscriberTypes.Active;
}

/**
 * Topic-to-subscription mapping interface
 */
interface ISubscriberTopicMap extends IEvents {
  readonly map: Map<string, string>;

  /** Check if topic exists */
  exists(topic: string, id: string): boolean;
  /** Set topic mapping */
  set(topic: string, id: string): void;
  /** Get subscription ID for topic */
  get(topic: string): string;
  /** Delete topic mapping */
  delete(topic: string, id: string): void;
  /** Clear all mappings */
  clear(): void;
}

/**
 * Pairing management interface for creating, managing, and querying pairings
 */
interface IPairing extends IEvents {
  readonly core: ICore;
  readonly logger: ILogger;
  readonly events: EventEmitter;
  readonly pairings: IPairingStore;

  /** Initialize pairing module */
  init(): Promise<void>;
  /** Create new pairing */
  create(): Promise<PairingTypes.Struct>;
  /** Pair using URI */
  pair(params: { uri: string; activatePairing?: boolean }): Promise<PairingTypes.Struct>;
  /** Activate existing pairing */
  activate(params: { topic: string }): Promise<void>;
  /** Register pairing */
  register(params: { topic: string; peerMetadata: CoreTypes.Metadata; relay: RelayerTypes.ProtocolOptions }): Promise<PairingTypes.Struct>;
  /** Update pairing metadata */
  update(params: { topic: string; metadata: CoreTypes.Metadata }): Promise<void>;
  /** Ping pairing */
  ping(params: { topic: string }): Promise<void>;
  /** Disconnect pairing */
  disconnect(params: { topic: string }): Promise<void>;
  /** Get pairing by topic */
  getPairings(): PairingTypes.Struct[];
}

/**
 * Private pairing methods for internal operations
 */
interface IPairingPrivate {
  sendRequest<T>(params: { topic: string; method: string; params: any; ttl?: number }): Promise<T>;
  sendResult(params: { id: number; topic: string; result: any; throwOnFailedPublish?: boolean }): Promise<void>;
  sendError(params: { id: number; topic: string; error: ErrorResponse }): Promise<void>;
}

namespace PairingTypes {
  /**
   * Pairing structure with topic, expiry, relay options, and metadata
   */
  interface Struct {
    /** Pairing topic */
    topic: string;
    /** Pairing expiry timestamp */
    expiry: number;
    /** Relay protocol options */
    relay: RelayerTypes.ProtocolOptions;
    /** Whether pairing is active */
    active: boolean;
    /** Peer metadata (optional) */
    peerMetadata?: CoreTypes.Metadata;
  }
}

namespace PairingJsonRpcTypes {
  /**
   * Standard pairing response type
   */
  type DefaultResponse = true;

  /**
   * Pairing method names for JSON-RPC communication
   */
  type WcMethod = "wc_pairingDelete" | "wc_pairingPing";

  /**
   * Pairing error response type
   */
  type Error = ErrorResponse;

  /**
   * Request parameters for pairing methods
   */
  interface RequestParams {
    wc_pairingDelete: { code: number; message: string };
    wc_pairingPing: {};
  }

  /**
   * Response results for pairing methods
   */
  interface Results {
    wc_pairingDelete: DefaultResponse;
    wc_pairingPing: DefaultResponse;
  }

  /**
   * Event callback structure for pairing
   */
  interface EventCallback<T = any> {
    resolve: (value: T) => void;
    reject: (reason: any) => void;
  }
}

/**
 * Store interface for pairing data
 */
type IPairingStore = IStore<PairingTypes.Struct>;

interface IMessageTracker extends IEvents {
  readonly name: string;
  readonly context: string;
  readonly map: Map<string, MessageRecord>;

  init(): Promise<void>;
  set(topic: string, message: string): Promise<void>;
  get(topic: string): MessageRecord | undefined;
  has(topic: string): boolean;
  delete(topic: string): Promise<void>;
  clear(): Promise<void>;
  on(event: MessageTrackerTypes.Event, listener: (args: MessageTrackerTypes.EventArguments[MessageTrackerTypes.Event]) => void): this;
  once(event: MessageTrackerTypes.Event, listener: (args: MessageTrackerTypes.EventArguments[MessageTrackerTypes.Event]) => void): this;
  off(event: MessageTrackerTypes.Event, listener: (args: MessageTrackerTypes.EventArguments[MessageTrackerTypes.Event]) => void): this;
  removeAllListeners(event?: MessageTrackerTypes.Event): this;
}

namespace MessageTrackerTypes {
  interface MessageRecord {
    topic: string;
    message: string;
    publishedAt: number;
    transportType: RelayerTypes.TransportType;
  }

  type Event = "message_ack" | "message_delivered";

  interface EventArguments {
    message_ack: {
      topic: string;
      message: string;
      publishedAt: number;
    };
    message_delivered: {
      topic: string;
      message: string;
      publishedAt: number;
    };
  }
}

interface IPublisher extends IEvents {
  readonly name: string;
  readonly context: string;
  readonly queue: Map<string, any>;

  init(): Promise<void>;
  publish(topic: string, message: string, opts?: PublisherTypes.PublishOptions): Promise<number>;
  on(event: PublisherTypes.Event, listener: (args: PublisherTypes.EventArguments[PublisherTypes.Event]) => void): this;
  once(event: PublisherTypes.Event, listener: (args: PublisherTypes.EventArguments[PublisherTypes.Event]) => void): this;
  off(event: PublisherTypes.Event, listener: (args: PublisherTypes.EventArguments[PublisherTypes.Event]) => void): this;
  removeAllListeners(event?: PublisherTypes.Event): this;
}

namespace PublisherTypes {
  interface PublishOptions {
    relay?: RelayerTypes.ProtocolOptions;
    ttl?: number;
    prompt?: boolean;
    tag?: number;
    id?: number;
    attestation?: string;
  }

  type Event = "publisher_publish";

  interface EventArguments {
    publisher_publish: {
      topic: string;
      message: string;
      publishedAt: number;
      transportType: RelayerTypes.TransportType;
    };
  }
}

interface ISubscriber extends IEvents {
  readonly name: string;
  readonly context: string;
  readonly pending: Map<string, any>;
  readonly cached: string[];
  readonly initialized: boolean;

  init(): Promise<void>;
  subscribe(topic: string, opts?: SubscriberTypes.SubscribeOptions): Promise<string>;
  unsubscribe(topic: string, opts?: SubscriberTypes.UnsubscribeOptions): Promise<void>;
  isSubscribed(topic: string): boolean;
  on(event: SubscriberTypes.Event, listener: (args: SubscriberTypes.EventArguments[SubscriberTypes.Event]) => void): this;
  once(event: SubscriberTypes.Event, listener: (args: SubscriberTypes.EventArguments[SubscriberTypes.Event]) => void): this;
  off(event: SubscriberTypes.Event, listener: (args: SubscriberTypes.EventArguments[SubscriberTypes.Event]) => void): this;
  removeAllListeners(event?: SubscriberTypes.Event): this;
}

namespace SubscriberTypes {
  interface SubscribeOptions {
    relay?: RelayerTypes.ProtocolOptions;
  }

  interface UnsubscribeOptions {
    id?: string;
    relay?: RelayerTypes.ProtocolOptions;
  }

  type Event = "subscriber_subscription" | "subscriber_message" | "subscriber_ping" | "subscriber_disconnect" | "subscriber_connection_stalled";

  interface EventArguments {
    subscriber_subscription: {
      id: string;
      topic: string;
    };
    subscriber_message: RelayerTypes.MessageEvent;
    subscriber_ping: {};
    subscriber_disconnect: {};
    subscriber_connection_stalled: {};
  }
}

import { IRelayer, RelayerTypes, IPairing, PairingTypes } from "@walletconnect/types";

// Publish a message to relay
const publishOptions: RelayerTypes.PublishOptions = {
  relay: { protocol: "irn" },
  ttl: 300, // 5 minutes
  prompt: true,
  tag: 1100
};

await relayer.publish("session_topic", JSON.stringify(payload), publishOptions);

// Subscribe to topic for incoming messages
const subscriptionId = await relayer.subscribe("session_topic", {
  relay: { protocol: "irn" }
});

// Create a pairing
const pairing: PairingTypes.Struct = await pairing.create();
console.log("Pairing topic:", pairing.topic);

// Pair using URI
const existingPairing = await pairing.pair({ 
  uri: "wc:abc123@2?relay-protocol=irn&symKey=def456" 
});

// Handle incoming messages
relayer.on("relayer_message", (event: RelayerTypes.MessageEvent) => {
  console.log("Received message on topic:", event.topic);
  console.log("Message content:", event.message);
  console.log("Published at:", event.publishedAt);
});