@trustware/sdk-staging 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,705 @@
+import React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+export { API_PREFIX, API_ROOT, ASSETS_BASE_URL, SDK_NAME, SDK_VERSION, WALLETCONNECT_PROJECT_ID } from './constants.js';
+
+declare enum TrustwareErrorCode {
+    INVALID_CONFIG = "INVALID_CONFIG",
+    WALLET_NOT_CONNECTED = "WALLET_NOT_CONNECTED",
+    BRIDGE_FAILED = "BRIDGE_FAILED",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR",
+    INPUT_ERROR = "INPUT_ERROR"
+}
+
+declare class TrustwareError extends Error {
+    code: TrustwareErrorCode;
+    userMessage?: string;
+    cause?: unknown;
+    constructor(params: {
+        code: TrustwareErrorCode;
+        message: string;
+        userMessage?: string;
+        cause?: unknown;
+    });
+    toJSON(): {
+        name: string;
+        code: TrustwareErrorCode;
+        message: string;
+        userMessage: string | undefined;
+    };
+}
+
+type TrustwareWidgetTheme = {
+    primaryColor: string;
+    secondaryColor: string;
+    backgroundColor: string;
+    textColor: string;
+    borderColor: string;
+    radius: number;
+};
+type TrustwareWidgetMessages = {
+    title: string;
+    description: string;
+};
+declare const DEFAULT_THEME: TrustwareWidgetTheme;
+declare const DEFAULT_MESSAGES: TrustwareWidgetMessages;
+
+type BuildRouteBody = {
+    fromChain: string;
+    toChain: string;
+    fromToken: string;
+    toToken: string;
+    fromAmount: string;
+    fromAddress: string;
+    toAddress: string;
+    fromAmountUsd?: string;
+    refundAddress?: string;
+    slippage?: number;
+    linkId?: string;
+    memo?: string;
+};
+type TxRequest = {
+    to?: string;
+    target?: string;
+    data: string;
+    value?: string;
+    gasLimit?: string;
+    maxFeePerGas?: string;
+    maxPriorityFeePerGas?: string;
+    chainId?: number | string;
+    gasPrice?: string;
+};
+declare function buildRoute(body: BuildRouteBody, signal?: AbortSignal): Promise<{
+    intentId: string;
+    txReq: TxRequest;
+    actions: unknown[];
+    finalExchangeRate: {
+        fromAmountUSD?: string;
+        toAmountMinUSD?: string;
+    };
+    route: RoutePlan | undefined;
+}>;
+declare function submitReceipt(intentId: string, txHash: string): Promise<any>;
+declare function getStatus(intentId: string): Promise<Transaction>;
+declare function pollStatus(intentId: string, { intervalMs, timeoutMs }?: {
+    intervalMs?: number | undefined;
+    timeoutMs?: number | undefined;
+}): Promise<Transaction>;
+
+type RouteParams = {
+    fromChain: string;
+    toChain: string;
+    fromToken: string;
+    toToken: string;
+    fromAmount: string | number;
+    fromAddress: string;
+    toAddress: string;
+    slippage?: number;
+};
+type RouteIntent = {
+    id: string;
+    fromChainId: string | number;
+    toChainId: string | number;
+    fromToken: string;
+    toToken: string;
+    fromAddress: string;
+    toAddress: string;
+    fromAmountWei: string | number;
+    quoteToAmountWei: string | number;
+    minToAmountWei: string | number;
+    requestId?: string;
+    routeRaw?: unknown;
+    status: "created" | "submitted" | "bridging" | "success" | "failed";
+    createdDate: Date | string;
+    updatedDate: Date | string;
+};
+type Transaction = {
+    id: string;
+    intentId: string;
+    fromAddress: string;
+    toAddress: string;
+    fromChainId: string | number;
+    toChainId: string | number;
+    sourceTxHash: string;
+    destTxHash: string;
+    requestId: string;
+    transactionRequest: unknown;
+    status: "submitted" | "bridging" | "success" | "failed";
+    statusRaw?: unknown;
+    routePath?: unknown;
+    routeStatus?: unknown;
+    toAmountWei?: string | number;
+    fromChainBlock: number;
+    toChainBlock: number;
+    fromChainTxUrl?: string;
+    toChainTxUrl?: string;
+    gasStatus?: string;
+    isGMPTransaction?: boolean;
+    axelarTransactionUrl?: string;
+    createdDate: Date | string;
+    updatedDate: Date | string;
+    timeSpentMs?: number;
+};
+type RouteEstimate = {
+    fromAmount?: string;
+    toAmount?: string;
+    toAmountMin?: string;
+    fromAmountUsd?: string;
+    toAmountUsd?: string;
+    totalFeesUsd?: string;
+    toAmountMinUsd?: string;
+    fees?: unknown[];
+};
+type RoutePlan = {
+    estimate?: RouteEstimate;
+    execution?: {
+        transaction?: TxRequest;
+    };
+    steps?: unknown[];
+    provider?: string;
+    requestId?: string;
+    reliabilityScore?: number;
+    diagnostics?: {
+        rawPayload?: unknown;
+    };
+};
+type BuildRouteResult = {
+    intentId: string;
+    txReq: TxRequest;
+    actions: unknown[];
+    finalExchangeRate: {
+        fromAmountUSD?: string;
+        toAmountMinUSD?: string;
+    };
+    route: RoutePlan | undefined;
+};
+
+type TrustwareEvent = {
+    type: "error";
+    error: TrustwareError;
+} | {
+    type: "transaction_started";
+} | {
+    type: "transaction_success";
+    txHash: string;
+    transaction?: Transaction;
+} | {
+    type: "wallet_connected";
+    address: string;
+};
+
+/** WalletConnect configuration options (all optional - SDK has built-in defaults) */
+type WalletConnectConfig = {
+    /** Override the built-in WalletConnect project ID (optional - SDK includes one) */
+    projectId?: string;
+    /** Chain IDs to support (defaults to [1] for Ethereum mainnet) */
+    chains?: number[];
+    /** Optional chain IDs (chains that can be switched to) */
+    optionalChains?: number[];
+    /** dApp metadata shown in wallet */
+    metadata?: {
+        name: string;
+        description?: string;
+        url: string;
+        icons?: string[];
+    };
+    /** Custom relay URL (defaults to WalletConnect's relay) */
+    relayUrl?: string;
+    /** Whether to show our custom QR modal (default: true) */
+    showQrModal?: boolean;
+    /** Disable WalletConnect entirely (default: false) */
+    disabled?: boolean;
+};
+/** Resolved WalletConnect config with defaults applied */
+type ResolvedWalletConnectConfig = {
+    projectId: string;
+    chains: number[];
+    optionalChains: number[];
+    metadata: {
+        name: string;
+        description: string;
+        url: string;
+        icons: string[];
+    };
+    relayUrl?: string;
+    showQrModal: boolean;
+};
+type TrustwareConfigOptions = {
+    apiKey: string;
+    routes: {
+        toChain: string;
+        toToken: string;
+        fromToken?: string;
+        fromAddress?: string;
+        toAddress?: string;
+        defaultSlippage?: number;
+        routeType?: string;
+        options?: {
+            routeRefreshMs?: number;
+            fixedFromAmount?: string | number;
+            minAmountOut?: string | number;
+            maxAmountOut?: string | number;
+        };
+    };
+    autoDetectProvider?: boolean;
+    theme?: TrustwareWidgetTheme;
+    messages?: Partial<TrustwareWidgetMessages>;
+    retry?: RetryConfig;
+    walletConnect?: WalletConnectConfig;
+    onError?: (error: TrustwareError) => void;
+    onSuccess?: (transaction: Transaction) => void;
+    onEvent?: (event: TrustwareEvent) => void;
+};
+type ResolvedTrustwareConfig = {
+    apiKey: string;
+    routes: {
+        toChain: string;
+        toToken: string;
+        fromToken?: string;
+        fromAddress?: string;
+        toAddress?: string;
+        defaultSlippage: number;
+        routeType: string;
+        options: {
+            routeRefreshMs?: number;
+            fixedFromAmount?: string | number;
+            minAmountOut?: string | number;
+            maxAmountOut?: string | number;
+        };
+    };
+    autoDetectProvider: boolean;
+    theme: TrustwareWidgetTheme;
+    messages: TrustwareWidgetMessages;
+    retry: ResolvedRetryConfig;
+    walletConnect?: ResolvedWalletConnectConfig;
+};
+declare const DEFAULT_SLIPPAGE = 1;
+declare const DEFAULT_AUTO_DETECT_PROVIDER = false;
+type RateLimitInfo = {
+    /** Maximum requests allowed in the current window */
+    limit: number;
+    /** Requests remaining in the current window */
+    remaining: number;
+    /** Unix timestamp when the rate limit window resets */
+    reset: number;
+    /** Seconds until rate limit resets (only present on 429 responses) */
+    retryAfter?: number;
+};
+type RetryConfig = {
+    /** Enable automatic retry on 429 responses (default: true). Note: This does NOT disable backend rate limits, only client-side retry behavior. */
+    autoRetry?: boolean;
+    /** Maximum number of retries on 429 (default: 3) */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    baseDelayMs?: number;
+    /** Callback when rate limit info is received from server */
+    onRateLimitInfo?: (info: RateLimitInfo) => void;
+    /** Callback when rate limit is hit (429 received) */
+    onRateLimited?: (info: RateLimitInfo, retryCount: number) => void;
+    /** Callback when remaining requests fall below threshold */
+    onRateLimitApproaching?: (info: RateLimitInfo, threshold: number) => void;
+    /** Threshold for onRateLimitApproaching callback (default: 5) */
+    approachingThreshold?: number;
+};
+type ResolvedRetryConfig = {
+    autoRetry: boolean;
+    maxRetries: number;
+    baseDelayMs: number;
+    approachingThreshold: number;
+    onRateLimitInfo?: (info: RateLimitInfo) => void;
+    onRateLimited?: (info: RateLimitInfo, retryCount: number) => void;
+    onRateLimitApproaching?: (info: RateLimitInfo, threshold: number) => void;
+};
+declare const DEFAULT_RETRY_CONFIG: ResolvedRetryConfig;
+
+type WalletId = "metamask" | "coinbase" | "walletconnect" | "rainbow" | "phantom-evm" | "rabby" | "brave" | "okx" | "zerion" | "taho" | "safe" | "imtoken" | "trust" | "bitget" | "kucoin";
+type WalletCategory = "injected" | "walletconnect" | "app";
+type WalletMeta = {
+    id: WalletId;
+    name: string;
+    category: WalletCategory;
+    logo: string;
+    emoji?: string;
+    homepage?: string;
+    chromeWebStore?: string;
+    android?: string;
+    ios?: string;
+    deepLink?: (currentUrl: string) => string;
+    detectFlags?: string[];
+};
+type EIP1193 = {
+    request(args: {
+        method: string;
+        params?: unknown[] | object;
+    }): Promise<unknown>;
+};
+type EIP6963ProviderDetail = {
+    info: {
+        uuid: string;
+        name: string;
+        icon: string;
+        rdns?: string;
+        version?: string;
+        wallets?: {
+            name: string;
+            version?: string;
+        }[];
+        features?: string[];
+    };
+    provider: any;
+    methods: string[];
+    events: string[];
+};
+type DetectedWallet = {
+    meta: WalletMeta;
+    via: "eip6963" | "injected-flag" | "walletconnect";
+    detail?: EIP6963ProviderDetail;
+    provider?: any;
+};
+type WalletInterFaceAPI = {
+    getAddress(): Promise<string>;
+    getChainId(): Promise<number>;
+    switchChain(chainId: number): Promise<void>;
+} & ({
+    type: "eip1193";
+    request(args: {
+        method: string;
+        params?: unknown[] | object;
+    }): Promise<unknown>;
+} | {
+    type: "wagmi";
+    sendTransaction(tx: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+        value?: bigint;
+        chainId?: number;
+    }): Promise<{
+        hash: `0x${string}`;
+    }>;
+});
+type SimpleWalletInterface = {
+    getAddress(): Promise<string>;
+    getChainId(): Promise<number>;
+    switchChain(chainId: number): Promise<void>;
+};
+
+type ChainMeta = {
+    id: string;
+    networkIdentifier: string;
+    nativeCurrency: {
+        symbol: string;
+        decimals: number;
+        name: string;
+    };
+};
+type TokenMeta = {
+    chainId: string;
+    address: `0x${string}`;
+    symbol: string;
+    decimals: number;
+    visible?: boolean;
+    active?: boolean;
+};
+type BalanceRow = {
+    chain_key: string;
+    category: "native" | "erc20" | "spl" | "btc";
+    contract?: `0x${string}`;
+    symbol?: string;
+    decimals: number;
+    balance: string;
+    name?: string;
+};
+type WalletAddressBalanceWrapper = {
+    chain_id: string;
+    balances: BalanceRow[];
+    count: number;
+    error: string | null;
+    source: string;
+};
+type ChainType = "evm" | "cosmos" | "solana" | "btc" | string;
+interface NativeCurrency {
+    symbol: string;
+    name?: string;
+    decimals?: number;
+    icon?: string;
+}
+interface ChainDef {
+    /** API commonly sends both. We canonicalize on chainId as string. */
+    chainId: string | number;
+    id?: string | number;
+    /** Keys we use to resolve chains from presets / user input */
+    networkIdentifier?: string;
+    axelarChainName?: string;
+    networkName?: string;
+    /** UI/availability flags */
+    enabled?: boolean;
+    visible?: boolean;
+    isTestnet?: boolean;
+    /** Display */
+    chainIconURI?: string;
+    nativeCurrency?: NativeCurrency;
+    /** Kinds (some payloads use both) */
+    type?: ChainType;
+    chainType?: ChainType;
+    /** Nice-to-have extras we won't rely on but keep for completeness */
+    blockExplorerUrls?: string[];
+    rpc?: string;
+    rpcList?: string[];
+}
+type TokenType = "evm" | "solana" | "btc" | string;
+interface TokenDef {
+    /** Core identity */
+    address: string;
+    chainId: string | number;
+    /** Display */
+    logoURI?: string;
+    name: string;
+    symbol: string;
+    /** Behavior / filtering */
+    decimals: number;
+    active?: boolean;
+    visible?: boolean;
+    type: TokenType;
+    /** Optional metadata */
+    usdPrice?: number;
+    coingeckoId?: string;
+    createdBy?: string;
+    subGraphIds?: string[];
+    subGraphOnly?: boolean;
+}
+type TokenWithBalance = TokenDef & {
+    balance?: bigint;
+};
+
+/** Map chainId -> backend chain_key and return balances */
+declare function getBalances(chainId: string | number, address: string): Promise<BalanceRow[]>;
+declare function getBalancesByAddress(address: string): Promise<WalletAddressBalanceWrapper[]>;
+
+declare function sendRouteTransaction(b: BuildRouteResult, fallbackChainId?: number): Promise<`0x${string}`>;
+/** One-shot flow that mirrors your old runTopUp */
+declare function runTopUp(params: {
+    fromChain?: string;
+    toChain?: string;
+    fromToken?: string;
+    toToken?: string;
+    toAddress?: string;
+    fromAmount: string | number;
+}): Promise<Transaction>;
+
+interface UseChainsResult {
+    /** All available chains */
+    chains: ChainDef[];
+    /** Popular/featured chains (Ethereum, Polygon, Base) */
+    popularChains: ChainDef[];
+    /** Other chains (not in popular list) */
+    otherChains: ChainDef[];
+    /** Whether chains are currently loading */
+    isLoading: boolean;
+    /** Error message if loading failed */
+    error: string | null;
+    chainMap: Map<string, ChainDef>;
+}
+/**
+ * Hook to load available chains from the registry.
+ * Returns chains split into popular and other categories.
+ */
+declare function useChains(): UseChainsResult;
+
+/**
+ * Navigation states for the deposit widget flow
+ */
+type NavigationStep = "home" | "select-token" | "crypto-pay" | "processing" | "success" | "error";
+/**
+ * Token information for deposit selection
+ */
+interface Token {
+    /** Token contract address (or 'native' for native tokens) */
+    address: string;
+    /** Token symbol (e.g., 'USDC', 'ETH') */
+    symbol: string;
+    /** Token display name (e.g., 'USD Coin', 'Ethereum') */
+    name: string;
+    /** Number of decimals for the token */
+    decimals: number;
+    /** URL to token icon/logo */
+    iconUrl?: string;
+    logoURI?: string;
+    /** Raw smallest-unit balance string (e.g. wei/lamports) when wallet connected */
+    balance?: string;
+    chainId: string | number;
+    usdPrice: number | undefined;
+}
+
+interface UseTokensResult {
+    /** All available tokens for the selected chain */
+    tokens: Token[];
+    /** Filtered tokens based on search query */
+    filteredTokens: Token[];
+    /** Whether tokens are currently loading */
+    isLoading: boolean;
+    /** Error message if loading failed */
+    error: string | null;
+    /** Current search query */
+    searchQuery: string;
+    /** Set the search query to filter tokens */
+    setSearchQuery: (query: string) => void;
+}
+/**
+ * Hook to load available tokens for a selected chain from the registry.
+ * Supports filtering tokens by name or symbol.
+ */
+declare function useTokens(chainId: number | null | undefined): UseTokensResult;
+
+declare const Trustware: {
+    /** Initialize config */
+    init(cfg: TrustwareConfigOptions): Promise</*elided*/ any>;
+    /** Attach a wallet interface directly (skips detection) */
+    useWallet(w: WalletInterFaceAPI): /*elided*/ any;
+    /** Best-effort background attach to detected wallet(s) (detection hook should be running in the app) */
+    autoDetect(_timeoutMs?: number): Promise<boolean>;
+    /** Read resolved config */
+    getConfig(): ResolvedTrustwareConfig;
+    setDestinationAddress(address?: string | null): /*elided*/ any;
+    /** Read active wallet */
+    getWallet(): WalletInterFaceAPI | null;
+    /** Simple helpers */
+    getAddress(): Promise<string>;
+    buildRoute: typeof buildRoute;
+    submitReceipt: typeof submitReceipt;
+    getStatus: typeof getStatus;
+    pollStatus: typeof pollStatus;
+    getBalances: typeof getBalances;
+    getBalancesByAddress: typeof getBalancesByAddress;
+    useChains: typeof useChains;
+    useTokens: typeof useTokens;
+    sendRouteTransaction: typeof sendRouteTransaction;
+    runTopUp: typeof runTopUp;
+};
+type TrustwareCore = typeof Trustware;
+
+declare class RateLimitError extends Error {
+    readonly rateLimitInfo: RateLimitInfo;
+    readonly retriesExhausted: boolean;
+    constructor(info: RateLimitInfo, retriesExhausted: boolean);
+}
+
+type WagmiConnector = {
+    /** Human label like "MetaMask", "WalletConnect" */
+    name: string;
+    /** Free-form type hint: "injected" | "walletConnect" | ... */
+    type?: string;
+};
+type WagmiBridge = {
+    /** Host app believes it’s connected (Wagmi state) */
+    isConnected(): boolean;
+    /** List of available connectors */
+    connectors(): WagmiConnector[];
+    /** Try connecting via a specific connector */
+    connect(connector: WagmiConnector): Promise<void>;
+    /** Disconnect current session */
+    disconnect(): Promise<void>;
+};
+
+/** Try wagmi bridge first (if provided), otherwise return EIP-1193 adapter. */
+declare function connectDetectedWallet(dw: DetectedWallet, opts?: {
+    wagmi?: WagmiBridge;
+    touchAddress?: boolean;
+}): Promise<{
+    via: "wagmi" | "eip1193" | "walletconnect";
+    api: WalletInterFaceAPI | null;
+}>;
+
+/** If you’re in React, call this once near your widget to push detection results into the manager. */
+declare function useWireDetectionIntoManager(): void;
+
+declare function useEIP1193(eth: EIP1193): WalletInterFaceAPI;
+declare function useWagmi(client: any): WalletInterFaceAPI;
+
+declare function toWalletInterfaceFromDetected(dw: DetectedWallet): WalletInterFaceAPI;
+
+declare function useWalletDetection(timeoutMs?: number): {
+    detected: DetectedWallet[];
+    detectedIds: Set<WalletId>;
+};
+
+type Theme = "light" | "dark" | "system";
+
+/**
+ * Ref methods exposed by TrustwareWidgetV2
+ */
+interface TrustwareWidgetV2Ref {
+    /** Open the widget */
+    open: () => void;
+    /** Close the widget (shows confirmation if transaction active) */
+    close: () => void;
+    /** Check if widget is currently open */
+    isOpen: () => boolean;
+}
+interface TrustwareWidgetV2Props {
+    /** Widget theme - light, dark, or system preference (used as initial theme) */
+    theme?: Theme;
+    /** Additional inline styles */
+    style?: React.CSSProperties;
+    /** Initial navigation step (defaults to 'home') */
+    initialStep?: NavigationStep;
+    /** Whether the widget is initially open (defaults to true for inline usage) */
+    defaultOpen?: boolean;
+    /** Callback when the widget is closed */
+    onClose?: () => void;
+    /** Callback when the widget is opened */
+    onOpen?: () => void;
+    /** Whether to show the theme toggle button (defaults to true) */
+    showThemeToggle?: boolean;
+}
+/**
+ * TrustwareWidgetV2 - Main widget component for deposit flow.
+ *
+ * Provides a complete deposit experience with:
+ * - Page navigation based on state machine
+ * - Animated transitions between pages
+ * - Theme support (light/dark/system)
+ * - Context-based state management
+ * - Programmatic open/close API via ref
+ * - State persistence in sessionStorage
+ *
+ * @example
+ * ```tsx
+ * // Basic inline usage
+ * <TrustwareWidgetV2 theme="dark" />
+ *
+ * // With ref for programmatic control
+ * const widgetRef = useRef<TrustwareWidgetV2Ref>(null);
+ *
+ * <TrustwareWidgetV2
+ *   ref={widgetRef}
+ *   defaultOpen={false}
+ *   onClose={() => console.log('Widget closed')}
+ *   onOpen={() => console.log('Widget opened')}
+ * />
+ *
+ * // Open/close programmatically
+ * widgetRef.current?.open();
+ * widgetRef.current?.close();
+ * ```
+ */
+declare const TrustwareWidgetV2: React.ForwardRefExoticComponent<TrustwareWidgetV2Props & React.RefAttributes<TrustwareWidgetV2Ref>>;
+
+type Status = "idle" | "initializing" | "ready" | "error";
+type Ctx = {
+    status: Status;
+    errors?: string;
+    core: typeof Trustware;
+    emitError?: (error: TrustwareError) => void;
+    emitSuccess?: (transaction: Transaction) => void;
+    emitEvent?: (event: TrustwareEvent) => void;
+};
+declare const Ctx: React.Context<Ctx>;
+declare function TrustwareProvider({ config, wallet, autoDetect, children, }: {
+    config: TrustwareConfigOptions;
+    wallet?: WalletInterFaceAPI;
+    autoDetect?: boolean;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useTrustware(): Ctx;
+
+export { type BalanceRow, type BuildRouteResult, type ChainDef, type ChainMeta, type ChainType, DEFAULT_AUTO_DETECT_PROVIDER, DEFAULT_MESSAGES, DEFAULT_RETRY_CONFIG, DEFAULT_SLIPPAGE, DEFAULT_THEME, type DetectedWallet, type EIP1193, type EIP6963ProviderDetail, type NativeCurrency, RateLimitError, type RateLimitInfo, type ResolvedRetryConfig, type ResolvedTrustwareConfig, type ResolvedWalletConnectConfig, type RetryConfig, type RouteEstimate, type RouteIntent, type RouteParams, type RoutePlan, type SimpleWalletInterface, type TokenDef, type TokenMeta, type TokenType, type TokenWithBalance, type Transaction, Trustware, type TrustwareConfigOptions, type TrustwareCore, TrustwareError, TrustwareProvider, TrustwareWidgetV2 as TrustwareWidget, type TrustwareWidgetMessages, type TrustwareWidgetTheme, type WagmiBridge, type WagmiConnector, type WalletAddressBalanceWrapper, type WalletCategory, type WalletConnectConfig, type WalletId, type WalletInterFaceAPI, type WalletMeta, connectDetectedWallet, toWalletInterfaceFromDetected, useEIP1193, useTrustware, useWagmi, useWalletDetection, useWireDetectionIntoManager };