Widget Management

/**
 * Creates a new Torus instance with configurable widget settings
 * @param args - Optional configuration parameters
 */
constructor(args?: TorusCtorArgs);

interface TorusCtorArgs {
  /** Widget button position on the page */
  buttonPosition?: BUTTON_POSITION_TYPE;
  /** Size of the widget button in pixels */
  buttonSize?: number;
  /** Z-index for modal and iframe elements */
  modalZIndex?: number;
  /** API key for Torus services */
  apiKey?: string;
}

type BUTTON_POSITION_TYPE = "bottom-left" | "top-left" | "bottom-right" | "top-right";

import Torus from "@toruslabs/torus-embed";

const torus = new Torus({
  buttonPosition: "bottom-right",
  buttonSize: 64,
  modalZIndex: 100000,
  apiKey: "your-api-key"
});

/**
 * Initialize the Torus widget - must be called before any other operations
 * @param params - Initialization parameters including network and UI settings
 * @returns Promise that resolves when initialization is complete
 */
init(params?: TorusParams): Promise<void>;

interface TorusParams {
  /** Torus network configuration */
  network?: NetworkInterface;
  /** Build environment for Torus widget */
  buildEnv?: TORUS_BUILD_ENV_TYPE;
  /** Enable debug logging */
  enableLogging?: boolean;
  /** Show/hide the Torus widget button */
  showTorusButton?: boolean;
  /** Custom login provider configurations */
  loginConfig?: LoginConfig;
  /** Version integrity settings */
  integrity?: IntegrityParams;
  /** White label customization */
  whiteLabel?: WhiteLabelParams;
  /** Enable WalletConnect support */
  useWalletConnect?: boolean;
  /** Multi-factor authentication level */
  mfaLevel?: "none" | "default" | "optional" | "mandatory";
}

interface NetworkInterface {
  /** Ethereum network host */
  host: ETHEREUM_NETWORK_TYPE | string;
  /** Network chain ID */
  chainId?: number;
  /** Display name for the network */
  networkName?: string;
  /** Block explorer URL */
  blockExplorer?: string;
  /** Native currency ticker */
  ticker?: string;
  /** Native currency display name */
  tickerName?: string;
}

await torus.init({
  buildEnv: "production",
  network: {
    host: "mainnet",
    chainId: 1,
    networkName: "Ethereum Mainnet",
    blockExplorer: "https://etherscan.io",
    ticker: "ETH",
    tickerName: "Ether"
  },
  showTorusButton: true,
  enableLogging: false,
  mfaLevel: "default"
});

/**
 * Hide the Torus widget button from the page
 */
hideTorusButton(): void;

/**
 * Show the Torus widget button on the page
 */
showTorusButton(): void;

// Hide button during onboarding
torus.hideTorusButton();

// Show button after user setup
torus.showTorusButton();

/**
 * Clear initialization state and remove DOM elements
 * Does not log out the user
 */
clearInit(): void;

/**
 * Complete cleanup including logout and DOM element removal
 * @returns Promise that resolves when cleanup is complete
 */
cleanUp(): Promise<void>;

// Clean up when changing configuration
torus.clearInit();
await torus.init(newConfig);

// Complete cleanup when done with Torus
await torus.cleanUp();

/** Current button position */
readonly buttonPosition: BUTTON_POSITION_TYPE;

/** Current button size in pixels */
readonly buttonSize: number;

/** Current Torus service URL */
readonly torusUrl: string;

/** Whether widget is initialized */
readonly isInitialized: boolean;

/** Whether Torus button is visible */
readonly torusWidgetVisibility: boolean;

/** Current API key */
readonly apiKey: string;

/** Current modal z-index */
readonly modalZIndex: number;

/** Current alert z-index */
readonly alertZIndex: number;

/** Current white label configuration */
readonly whiteLabel: WhiteLabelParams;

/** Current verifier being used */
readonly currentVerifier: string;

/** Requested verifier for login */
readonly requestedVerifier: string;

/** Current embed translation settings */
readonly embedTranslations: EMBED_TRANSLATION_ITEM;

type TORUS_BUILD_ENV_TYPE = 
  | "production"    // Production environment (https://app.tor.us)
  | "development"   // Development environment (localhost:4050)
  | "binance"       // Binance environment (https://binance.tor.us)
  | "testing"       // Testing environment (https://testing.tor.us)
  | "lrc"           // LRC environment (https://lrc.tor.us)
  | "beta"          // Beta environment (https://beta.tor.us)
  | "bnb"           // BNB environment (https://bnb.tor.us)
  | "polygon"       // Polygon environment (https://polygon.tor.us)
  | "alpha";        // Alpha environment

type ETHEREUM_NETWORK_TYPE = 
  | "sepolia" | "mainnet" | "goerli" | "localhost"
  | "matic" | "mumbai" | "xdai" | "bsc_mainnet" | "bsc_testnet";

interface IntegrityParams {
  /** Specific version of torus-website to load */
  version?: string;
}

interface WhiteLabelParams {
  /** Theme customization */
  theme: ThemeParams;
  /** Default language for the interface */
  defaultLanguage?: string;
  /** Logo URL for light mode */
  logoDark: string;
  /** Logo URL for dark mode */
  logoLight: string;
  /** Hide topup functionality */
  topupHide?: boolean;
  /** Hide featured billboard */
  featuredBillboardHide?: boolean;
  /** Hide disclaimers on login */
  disclaimerHide?: boolean;
  /** Terms and conditions links */
  tncLink?: LocaleLinks<string>;
  /** Privacy policy links */
  privacyPolicy?: LocaleLinks<string>;
  /** Contact links */
  contactLink?: LocaleLinks<string>;
  /** Custom translations */
  customTranslations?: LocaleLinks<unknown>;
}

interface ThemeParams {
  /** Enable dark mode */
  isDark: boolean;
  /** Custom color configuration */
  colors: Record<string, string>;
}

interface LocaleLinks<T> {
  en?: T;
  ja?: T;
  ko?: T;
  de?: T;
  zh?: T;
  es?: T;
}

interface EMBED_TRANSLATION_ITEM {
  continue: string;
  actionRequired: string;
  pendingAction: string;
  cookiesRequired: string;
  enableCookies: string;
  clickHere: string;
}