Sign Client Interface

/**
 * Main sign client interface with session management capabilities
 * Provides the primary API for WalletConnect sign operations
 */
interface ISignClient extends IEvents {
  /** Client metadata for identification */
  readonly metadata: CoreTypes.Metadata;
  /** Protocol identifier */
  readonly protocol: string;
  /** Protocol version */
  readonly version: number;
  /** Core protocol instance */
  readonly core: ICore;
  /** Logger instance */
  readonly logger: ILogger;
  /** Event emitter */
  readonly events: EventEmitter;
  /** Engine instance for session management */
  readonly engine: IEngine;
  /** Session store */
  readonly session: ISession;
  /** Proposal store */
  readonly proposal: IProposal;
  /** Pending request store */
  readonly pendingRequest: IPendingRequest;
  /** Authentication interface */
  readonly auth: IAuth;

  /** Initiate a new session connection */
  connect(params?: SignClientTypes.ConnectParams): Promise<{ 
    uri?: string; 
    approval(): Promise<SessionTypes.Struct>; 
  }>;
  /** Pair with a peer using URI */
  pair(params: { uri: string }): Promise<PairingTypes.Struct>;
  /** Approve a session proposal */
  approve(params: {
    id: number;
    namespaces: SessionTypes.Namespaces;
    sessionProperties?: ProposalTypes.SessionProperties;
  }): Promise<SessionTypes.Struct>;
  /** Reject a session proposal */
  reject(params: { id: number; reason: ErrorResponse }): Promise<void>;
  /** Update session namespaces */
  update(params: { topic: string; namespaces: SessionTypes.Namespaces }): Promise<void>;
  /** Extend session expiry */
  extend(params: { topic: string }): Promise<void>;
  /** Send a request to peer */
  request(params: { 
    topic: string; 
    request: RequestArguments; 
    chainId: string 
  }): Promise<any>;
  /** Respond to a peer request */
  respond(params: { topic: string; response: JsonRpcResponse }): Promise<void>;
  /** Ping peer connection */
  ping(params: { topic: string }): Promise<void>;
  /** Emit an event to peer */
  emit(params: { 
    topic: string; 
    event: SessionTypes.EventArguments; 
    chainId: string 
  }): Promise<void>;
  /** Disconnect from session */
  disconnect(params: { topic: string; reason: ErrorResponse }): Promise<void>;
  /** Find sessions matching criteria */
  find(params: { 
    requiredNamespaces: ProposalTypes.RequiredNamespaces 
  }): SessionTypes.Struct[];
}

namespace SignClientTypes {
  /**
   * All sign client event types
   */
  type Event = 
    | "session_proposal"
    | "session_update" 
    | "session_extend"
    | "session_ping"
    | "session_delete"
    | "session_expire"
    | "session_request"
    | "session_request_sent"
    | "session_event"
    | "proposal_expire"
    | "session_authenticate";

  /**
   * Base event arguments structure
   */
  interface BaseEventArgs<T = {}> {
    id: number;
    topic: string;
    params: T;
  }

  /**
   * Event arguments for all sign client events
   */
  interface EventArguments {
    session_proposal: Omit<BaseEventArgs<{
      id: number;
      pairingTopic: string;
      expiry: number;
      relays: RelayerTypes.ProtocolOptions[];
      proposer: SessionTypes.Participant;
      requiredNamespaces: ProposalTypes.RequiredNamespaces;
      optionalNamespaces?: ProposalTypes.OptionalNamespaces;
      sessionProperties?: ProposalTypes.SessionProperties;
    }>, "topic">;
    session_update: BaseEventArgs<{ namespaces: SessionTypes.Namespaces }>;
    session_extend: BaseEventArgs<{}>;
    session_ping: BaseEventArgs<{}>;
    session_delete: BaseEventArgs<{ code: number; message: string }>;
    session_expire: { topic: string };
    session_request: BaseEventArgs<{ 
      request: { method: string; params: any }; 
      chainId: string;
    }>;
    session_request_sent: { 
      request: { method: string; params: any };
      topic: string;
      chainId: string;
      id: number;
    };
    session_event: BaseEventArgs<{ 
      event: { name: string; data: any }; 
      chainId: string;
    }>;
    proposal_expire: { id: number };
    session_authenticate: AuthTypes.SessionAuthenticateRequest;
  }

  /**
   * Client metadata type (alias for CoreTypes.Metadata)
   */
   type Metadata = CoreTypes.Metadata;

  /**
   * Sign client configuration options
   */
  interface SignConfig {
    /** Project ID for WalletConnect Cloud */
    projectId: string;
    /** Custom relay URL (optional) */
    relayUrl?: string;
    /** Client metadata */
    metadata: Metadata;
    /** Custom storage implementation (optional) */
    storage?: IKeyValueStorage;
    /** Custom logger (optional) */
    logger?: string | ILogger;
  }

  /**
   * Sign client initialization options
   */
  interface Options extends SignConfig {
    /** Custom core instance (optional) */
    core?: ICore;
    /** Custom name for client (optional) */
    name?: string;
  }

  /**
   * Connection parameters for initiating sessions
   */
  interface ConnectParams {
    /** Required namespaces for the session */
    requiredNamespaces: ProposalTypes.RequiredNamespaces;
    /** Optional namespaces for the session */
    optionalNamespaces?: ProposalTypes.OptionalNamespaces;
    /** Custom session properties */
    sessionProperties?: ProposalTypes.SessionProperties;
    /** Existing pairing topic (optional) */
    pairingTopic?: string;
  }
}

/**
 * Sign client event emitter interface
 */
interface ISignClientEvents extends IEvents {
  on<E extends SignClientTypes.Event>(
    event: E, 
    listener: (args: SignClientTypes.EventArguments[E]) => void
  ): this;
  
  once<E extends SignClientTypes.Event>(
    event: E, 
    listener: (args: SignClientTypes.EventArguments[E]) => void
  ): this;
  
  off<E extends SignClientTypes.Event>(
    event: E, 
    listener: (args: SignClientTypes.EventArguments[E]) => void
  ): this;
  
  removeAllListeners<E extends SignClientTypes.Event>(event?: E): this;
  
  emit<E extends SignClientTypes.Event>(
    event: E, 
    args: SignClientTypes.EventArguments[E]
  ): boolean;
}

/**
 * Main engine interface for session lifecycle management
 * Handles the core protocol operations and state management
 */
interface IEngine extends IEvents {
  readonly name: string;
  readonly context: string;
  readonly client: ISignClient;
  readonly signClient: ISignClient;

  /** Initialize the engine */
  init(): Promise<void>;
  /** Connect to a peer and create session */
  connect(params?: EngineTypes.ConnectParams): Promise<{ uri?: string; approval(): Promise<SessionTypes.Struct> }>;
  /** Pair with a peer using URI */
  pair(params: EngineTypes.PairParams): Promise<PairingTypes.Struct>;
  /** Approve a session proposal */
  approve(params: EngineTypes.ApproveParams): Promise<SessionTypes.Struct>;
  /** Reject a session proposal */
  reject(params: EngineTypes.RejectParams): Promise<void>;
  /** Update an existing session */
  update(params: EngineTypes.UpdateParams): Promise<void>;
  /** Extend session expiry */
  extend(params: EngineTypes.ExtendParams): Promise<void>;
  /** Send a request to the peer */
  request(params: EngineTypes.RequestParams): Promise<any>;
  /** Respond to a peer request */
  respond(params: EngineTypes.RespondParams): Promise<void>;
  /** Ping the peer */
  ping(params: EngineTypes.PingParams): Promise<void>;
  /** Emit an event to the peer */
  emit(params: EngineTypes.EmitParams): Promise<void>;
  /** Disconnect from a session */
  disconnect(params: EngineTypes.DisconnectParams): Promise<void>;
  /** Find sessions matching criteria */
  find(params: { requiredNamespaces: ProposalTypes.RequiredNamespaces }): SessionTypes.Struct[];
  /** Get active pairings */
  getPairings(): PairingTypes.Struct[];
  /** Get active sessions */
  getActiveSessions(): Record<string, SessionTypes.Struct>;
  /** Get pending session proposals */
  getPendingSessionProposals(): Record<number, ProposalTypes.Struct>;
  /** Get pending session requests */
  getPendingSessionRequests(): PendingRequestTypes.Struct[];
}

/**
 * Engine event emitter interface
 */
interface IEngineEvents extends IEvents {
  on<E extends EngineTypes.Event>(
    event: E,
    listener: (args: EngineTypes.EventArguments[E]) => void
  ): this;
}

/**
 * Private engine methods for internal operations
 */
interface EnginePrivate {
  /** Private session management methods */
  sendRequest<T>(params: EngineTypes.RequestParams): Promise<T>;
  sendResult(params: EngineTypes.RespondParams): Promise<void>;
  sendError(id: number, topic: string, error: ErrorResponse): Promise<void>;
}

namespace EngineTypes {
  /**
   * Engine event types
   */
  type Event = SignClientTypes.Event;

  /**
   * Engine event argument types
   */
  interface EventArguments extends SignClientTypes.EventArguments {}

  /**
   * URI parsing parameters
   */
  interface UriParameters {
    /** Protocol version */
    protocol: string;
    /** Protocol version number */
    version: number;
    /** Pairing topic */
    topic: string;
    /** Symmetric key */
    symKey: string;
    /** Relay protocol */
    relay: RelayerTypes.ProtocolOptions;
    /** Optional expiry timestamp */
    expiry?: number;
  }

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

  /**
   * Connection parameters for engine
   */
  interface ConnectParams extends SignClientTypes.ConnectParams {}

  /**
   * Pairing parameters
   */
  interface PairParams {
    /** Pairing URI */
    uri: string;
  }

  /**
   * Approval parameters
   */
  interface ApproveParams {
    /** Proposal ID */
    id: number;
    /** Approved namespaces */
    namespaces: SessionTypes.Namespaces;
    /** Optional session properties */
    sessionProperties?: ProposalTypes.SessionProperties;
  }

  /**
   * Rejection parameters
   */
  interface RejectParams {
    /** Proposal ID */
    id: number;
    /** Rejection reason */
    reason: ErrorResponse;
  }

  /**
   * Update parameters
   */
  interface UpdateParams {
    /** Session topic */
    topic: string;
    /** Updated namespaces */
    namespaces: SessionTypes.Namespaces;
  }

  /**
   * Extension parameters
   */
  interface ExtendParams {
    /** Session topic */
    topic: string;
  }

  /**
   * Request parameters
   */
  interface RequestParams {
    /** Session topic */
    topic: string;
    /** JSON-RPC request */
    request: RequestArguments;
    /** Target chain ID */
    chainId: string;
    /** Request expiry (optional) */
    expiry?: number;
  }

  /**
   * Response parameters
   */
  interface RespondParams {
    /** Session topic */
    topic: string;
    /** JSON-RPC response */
    response: JsonRpcResponse;
  }

  /**
   * Event emission parameters
   */
  interface EmitParams {
    /** Session topic */
    topic: string;
    /** Event to emit */
    event: SessionTypes.EventArguments;
    /** Target chain ID */
    chainId: string;
  }

  /**
   * Ping parameters
   */
  interface PingParams {
    /** Session topic */
    topic: string;
  }

  /**
   * Disconnection parameters
   */
  interface DisconnectParams {
    /** Session topic */
    topic: string;
    /** Disconnection reason */
    reason: ErrorResponse;
  }

  /**
   * Session finding parameters
   */
  interface FindParams {
    /** Required namespaces to match */
    requiredNamespaces: ProposalTypes.RequiredNamespaces;
  }

  /**
   * Promise with acknowledgment callback
   */
  type AcknowledgedPromise<T> = Promise<T> & {
    acknowledged: () => Promise<SessionTypes.Struct>;
  };

  /**
   * Authentication response promise structure
   */
  interface SessionAuthenticateResponsePromise {
    /** Authentication response promise */
    response: Promise<SessionTypes.Struct>;
    /** Acknowledgment callback */
    acknowledged: () => Promise<SessionTypes.Struct>;
  }

  /**
   * RPC options structure
   */
  interface RpcOpts {
    /** Request TTL in milliseconds */
    ttl: number;
    /** Whether to prompt user */
    prompt: boolean;
    /** Request tag */
    tag: number;
  }

  /**
   * RPC options mapping
   */
  type RpcOptsMap = Record<string, RpcOpts>;

  /**
   * Engine queue structure for managing operations
   */
  interface EngineQueue {
    /** Queue state */
    state: "IDLE" | "ACTIVE";
    /** Queued operations */
    queue: Array<() => Promise<void>>;
  }
}

import { ISignClient, SignClientTypes, EngineTypes } from "@walletconnect/types";

// Initialize sign client
const signClient: ISignClient = await SignClient.init({
  projectId: "your_project_id",
  metadata: {
    name: "Example dApp",
    description: "An example dApp using WalletConnect",
    url: "https://example.com",
    icons: ["https://example.com/icon.png"]
  }
});

// Connect to wallet
const connectParams: SignClientTypes.ConnectParams = {
  requiredNamespaces: {
    eip155: {
      methods: ["eth_sendTransaction", "personal_sign"],
      chains: ["eip155:1"],
      events: ["chainChanged", "accountsChanged"]
    }
  }
};

const { uri, approval } = await signClient.connect(connectParams);

// Handle session approval
approval().then((session) => {
  console.log("Session approved:", session);
});

// Send a request
const result = await signClient.request({
  topic: session.topic,
  chainId: "eip155:1",
  request: {
    method: "personal_sign",
    params: ["0x48656c6c6f20576f726c64", account]
  }
});