Wallet Connectors¶

import { BrowserProvider, Signer } from 'ethers';

type ConnectorId = 'injected' | 'external' | (string & {});

interface WalletConnector {
  /** Unique connector identifier */
  readonly id: ConnectorId;

  /** Human-readable connector name (e.g. 'MetaMask', 'WalletConnect') */
  readonly name: string;

  /** Optional icon URL or data URI */
  readonly icon?: string;

  /** Check if this connector is available (e.g. MetaMask installed?) */
  isAvailable(): boolean;

  /** Connect the wallet. Shows popup/modal as needed. */
  connect(): Promise<ConnectResult>;

  /** Disconnect the wallet */
  disconnect(): Promise<void>;

  /**
   * Silent reconnect without popup (for session persistence).
   * Returns null if reconnection is not possible.
   */
  reconnect?(): Promise<ConnectResult | null>;

  /** Listen to account changes */
  onAccountsChanged?(callback: (accounts: string[]) => void): void;

  /** Listen to chain/network changes */
  onChainChanged?(callback: (chainId: number) => void): void;

  /** Remove all event listeners */
  removeListeners?(): void;

  /** Switch to a specific network */
  switchNetwork?(chainId: number): Promise<void>;
}

import { BrowserProvider, Signer } from 'ethers';

interface ConnectResult {
  /** ethers.js v6 BrowserProvider instance */
  provider: BrowserProvider;

  /** ethers.js v6 Signer for signing transactions */
  signer: Signer;

  /** Checksummed wallet address */
  address: string;

  /** Current chain ID (e.g. 42161 for Arbitrum One) */
  chainId: number;
}

import { InjectedConnector } from '@subscrypts/subscrypts-sdk-react';

const metamask = new InjectedConnector();
// or with options:
const customInjected = new InjectedConnector({
  name: 'My Wallet',
  icon: 'https://example.com/icon.svg'
});

import { ExternalConnector } from '@subscrypts/subscrypts-sdk-react';

const connector = new ExternalConnector(
  { provider, signer, address },  // ExternalWalletConfig
  42161                             // chainId
);

import { BrowserProvider, Signer } from 'ethers';
import type {
  WalletConnector,
  ConnectResult
} from '@subscrypts/subscrypts-sdk-react';

// Import your Privy SDK
import { PrivyClient } from '@privy-io/react-auth';

export class PrivyConnector implements WalletConnector {
  readonly id = 'privy';
  readonly name = 'Email / Social Login';
  readonly icon = 'https://your-cdn.com/privy-icon.svg';

  private privyClient: PrivyClient;
  private provider: BrowserProvider | null = null;

  constructor(privyClient: PrivyClient) {
    this.privyClient = privyClient;
  }

  /**
   * Privy is always available (it uses email/social, no extension needed)
   */
  isAvailable(): boolean {
    return true;
  }

  /**
   * Connect via Privy login flow
   */
  async connect(): Promise<ConnectResult> {
    // Trigger Privy login (shows email/social modal)
    const user = await this.privyClient.login();

    // Get the embedded wallet
    const wallet = user.wallet;
    if (!wallet) {
      throw new Error('No wallet found after Privy login');
    }

    // Get ethers provider from Privy's embedded wallet
    const ethereumProvider = await wallet.getEthereumProvider();
    this.provider = new BrowserProvider(ethereumProvider);
    const signer = await this.provider.getSigner();
    const network = await this.provider.getNetwork();

    return {
      provider: this.provider,
      signer,
      address: wallet.address,
      chainId: Number(network.chainId)
    };
  }

  /**
   * Disconnect: log out of Privy
   */
  async disconnect(): Promise<void> {
    await this.privyClient.logout();
    this.provider = null;
  }

  /**
   * Silent reconnect: check if user is already authenticated
   */
  async reconnect(): Promise<ConnectResult | null> {
    const user = this.privyClient.user;
    if (!user || !user.wallet) return null;

    const ethereumProvider = await user.wallet.getEthereumProvider();
    this.provider = new BrowserProvider(ethereumProvider);
    const signer = await this.provider.getSigner();
    const network = await this.provider.getNetwork();

    return {
      provider: this.provider,
      signer,
      address: user.wallet.address,
      chainId: Number(network.chainId)
    };
  }

  /**
   * Switch network via Privy's embedded wallet
   */
  async switchNetwork(chainId: number): Promise<void> {
    const user = this.privyClient.user;
    if (!user?.wallet) throw new Error('No wallet connected');

    await user.wallet.switchChain(chainId);
  }

  // Privy embedded wallets do not emit account/chain change events,
  // so these are intentionally omitted.
}

import type { ConnectorId } from '@subscrypts/subscrypts-sdk-react';

interface WalletSession {
  connectorId: ConnectorId;
  address: string;
  timestamp: number;
}

/** Save a wallet session to localStorage */
function saveSession(connectorId: ConnectorId, address: string): void;

/** Load a wallet session (returns null if none exists or invalid) */
function loadSession(): WalletSession | null;

/** Check if a session has expired */
function isSessionStale(session: WalletSession): boolean;

/** Clear the stored session */
function clearSession(): void;