@tokenflight/swap 0.0.4 → 0.1.1

package/dist/index.d.ts

@@ -1,688 +0,0 @@
-/**
- * Add thousands separators (commas) to the integer part of a numeric string.
- * e.g., "3200" → "3,200", "1234567.89" → "1,234,567.89", "0.5" → "0.5"
- */
-export declare function addThousandsSeparator(value: string): string;
-
-/** Amount change data */
-export declare interface AmountChangedData {
-    amount: string;
-    direction: "from" | "to";
-}
-
-/**
- * Boolean HTML attribute — accepts both native booleans and the
- * string equivalents that `parseBooleanProp()` understands.
- */
-declare type BooleanAttribute = boolean | "true" | "false" | "1" | "0" | "yes" | "no" | "";
-
-/**
- * Build offers for ranking from API routes (EXACT_OUTPUT mode).
- * Routes with unparseable amountIn are excluded from ranking.
- */
-export declare function buildOffersForRanking(routes: readonly QuoteRoute[], tradeType: TradeType | null): OfferForRanking[];
-
-/** Callback interfaces for widget events */
-export declare interface Callbacks {
-    onSwapSuccess?(data: SwapSuccessData): void;
-    onSwapError?(data: SwapErrorData): void;
-    onWalletConnected?(data: WalletConnectedData): void;
-    onQuoteReceived?(data: QuoteResponse): void;
-    onAmountChanged?(data: AmountChangedData): void;
-    /** Called when user clicks Connect Wallet and no walletAdapter is provided */
-    onConnectWallet?(): void;
-    /** Called when user clicks the connected wallet address (for custom account modal handling) */
-    onAccountModal?(): void;
-}
-
-export declare type ChainInfo = HyperstreamApi.Chain;
-
-/** Chain type for multi-chain support */
-export declare type ChainType = "evm" | "solana";
-
-/** Clear all TokenFlight token cache entries */
-export declare function clearTokenCache(): void;
-
-/**
- * Compute exchange rate as a display string.
- * Returns how many toToken units you get per 1 fromToken.
- */
-export declare function computeExchangeRate(amountIn: string, decimalsIn: number, amountOut: string, decimalsOut: number): string;
-
-export declare type ContractCallDeposit = HyperstreamApi.ContractCallDeposit;
-
-/**
- * Custom color overrides — keys are CSS variable names.
- *
- * ```ts
- * customColors: {
- *   "--tf-primary": "#FF6B00",
- *   "--tf-bg": "#1A1A2E",
- *   "--tf-text": "#FFFFFF",
- * }
- * ```
- */
-export declare type CustomColors = Record<string, string>;
-
-export declare const DEFAULT_API_ENDPOINT = "https://api.hyperstream.dev";
-
-export declare type DepositApproval = HyperstreamApi.Approval;
-
-export declare type DepositBuildResponse = HyperstreamApi.Deposit;
-
-export declare type EIP1193RequestApproval = HyperstreamApi.EIP1193RequestApproval;
-
-/** Error codes for TokenFlight SDK */
-export declare const ErrorCode: {
-    readonly INVALID_CONFIG: "TF1001";
-    readonly INVALID_TOKEN_IDENTIFIER: "TF1002";
-    readonly INVALID_AMOUNT: "TF1003";
-    readonly MISSING_REQUIRED_CONFIG: "TF1004";
-    readonly WALLET_NOT_CONNECTED: "TF2001";
-    readonly WALLET_CONNECTION_FAILED: "TF2002";
-    readonly WALLET_ACTION_FAILED: "TF2003";
-    readonly WALLET_ACTION_REJECTED: "TF2004";
-    readonly UNSUPPORTED_ACTION_TYPE: "TF2005";
-    readonly API_REQUEST_FAILED: "TF3001";
-    readonly API_TIMEOUT: "TF3002";
-    readonly API_INVALID_RESPONSE: "TF3003";
-    readonly QUOTE_FAILED: "TF3004";
-    readonly QUOTE_EXPIRED: "TF3005";
-    readonly DEPOSIT_BUILD_FAILED: "TF3006";
-    readonly DEPOSIT_SUBMIT_FAILED: "TF3007";
-    readonly ORDER_FAILED: "TF3008";
-    readonly TRANSACTION_FAILED: "TF4001";
-    readonly TRANSACTION_REJECTED: "TF4002";
-    readonly INSUFFICIENT_BALANCE: "TF4003";
-    readonly ELEMENT_NOT_FOUND: "TF5001";
-    readonly INITIALIZATION_FAILED: "TF5002";
-};
-
-export declare type ErrorCode = typeof ErrorCode[keyof typeof ErrorCode];
-
-/** EVM wallet action via EIP-1193 */
-export declare interface EvmWalletAction {
-    type: "eip1193_request";
-    chainId: number;
-    method: string;
-    params: unknown[];
-}
-
-export declare type ExactOutMethod = HyperstreamApi.ExactOutMethod;
-
-/** Execution-only phases for the async build→wallet→submit→track→success flow */
-export declare type ExecPhase = "building" | "awaiting-wallet" | "submitting" | "tracking" | "success";
-
-/**
- * Format a display amount to a fixed number of significant decimals.
- * Avoids showing excessive precision in the UI.
- *
- * When the integer part is "0", ensures at least `maxDecimals` significant
- * digits are shown (e.g., "0.00472" → "0.0047" with maxDecimals=2).
- */
-export declare function formatDisplayAmount(amount: string, maxDecimals?: number): string;
-
-/** Get the best overall route ID for exact output. */
-export declare function getBestOverallRouteId(routes: readonly QuoteRoute[], tradeType: TradeType | null): string | null;
-
-/** Get chain type from chainId */
-export declare function getChainType(chainId: number): "evm" | "solana";
-
-declare class HyperstreamApi {
-    readonly baseUrl: string;
-    private readonly ky;
-    constructor(options: {
-        baseUrl: string;
-    });
-    private request;
-    getQuotes(request: HyperstreamApi.QuoteRequest, signal?: AbortSignal): Promise<HyperstreamApi.GetQuotesResponse>;
-    buildDeposit(params: {
-        from: string;
-        quoteId: string;
-        routeId: string;
-    }, signal?: AbortSignal): Promise<HyperstreamApi.Deposit>;
-    submitDeposit(params: {
-        quoteId: string;
-        routeId: string;
-    } & ({
-        txHash: string;
-    } | {
-        signedTransaction: string;
-    }), signal?: AbortSignal): Promise<HyperstreamApi.SubmitDepositResponse>;
-    getOrdersByAddress(address: string, options?: {
-        orderIds?: string[];
-        limit?: number;
-        cursor?: number;
-    }): Promise<HyperstreamApi.GetOrderResponse>;
-    getOrderById(address: string, orderId: string): Promise<HyperstreamApi.Order | null>;
-    getTokens(params?: {
-        q?: string;
-        chainIds?: number[];
-        limit?: number;
-        cursor?: number;
-    }): Promise<HyperstreamApi.GetTokensResponse>;
-    searchTokens(query: string, options?: {
-        chainIds?: number[];
-    }): Promise<HyperstreamApi.TokenSearchResponse>;
-    getTopTokens(params?: {
-        chainIds?: number[];
-    }): Promise<HyperstreamApi.Token[]>;
-    getTokenBalances(address: string, options?: {
-        chainIds?: number[];
-    }): Promise<HyperstreamApi.Token[]>;
-    getChains(): Promise<HyperstreamApi.Chain[]>;
-}
-
-declare namespace HyperstreamApi {
-    interface TokenExtensions {
-        balance?: string;
-        isRiskToken?: boolean;
-        price?: {
-            usd: string;
-        };
-        change?: string;
-        volume?: string;
-        marketCap?: string;
-        liquidity?: string;
-        spokeToken?: Token;
-    }
-    interface Token {
-        address: string;
-        chainId: number;
-        name: string;
-        symbol: string;
-        decimals: number;
-        logoURI?: string;
-        platform?: string;
-        id?: string;
-        extensions?: TokenExtensions;
-    }
-    interface TokenSearchResponse {
-        data: Token[];
-    }
-    interface GetTokensResponse {
-        data: Token[];
-        cursor?: number;
-    }
-    interface BlockExplorer {
-        name: string;
-        url: string;
-    }
-    interface Chain {
-        id: number;
-        name: string;
-        type?: string;
-        blockExplorers?: {
-            [key: string]: BlockExplorer;
-            default: BlockExplorer;
-        };
-        [key: string]: unknown;
-    }
-    type TradeType = "EXACT_INPUT" | "EXACT_OUTPUT";
-    type ExactOutMethod = "native" | "adaptive";
-    type RouteTag = "1-click" | "needs-approval";
-    interface QuoteRequest {
-        tradeType: TradeType;
-        fromChainId: number;
-        fromToken: string;
-        toChainId: number;
-        toToken: string;
-        amount: string;
-        fromAddress: string;
-        recipient?: string;
-        slippageTolerance?: number;
-    }
-    interface Quote {
-        amountIn: string;
-        amountOut: string;
-        minAmountOut?: string;
-        slippageTolerance?: number;
-        expectedDurationSeconds: number;
-        validBefore: number;
-        estimatedGas?: string;
-        tags?: RouteTag[];
-    }
-    interface Route {
-        routeId: string;
-        type: string;
-        icon?: string;
-        exactOutMethod?: ExactOutMethod;
-        tags?: RouteTag[];
-        quote: Quote;
-    }
-    interface GetQuotesResponse {
-        quoteId: string;
-        routes: Route[];
-    }
-    interface EIP1193RequestApproval {
-        type: "eip1193_request";
-        request: {
-            method: string;
-            params: unknown[];
-        };
-        waitForReceipt?: boolean;
-        deposit?: boolean;
-    }
-    interface SolanaApproval {
-        type: "solana_sendTransaction";
-        transaction: string;
-        deposit?: boolean;
-    }
-    type Approval = EIP1193RequestApproval | SolanaApproval;
-    interface ContractCallDeposit {
-        kind: "CONTRACT_CALL";
-        approvals?: Approval[];
-    }
-    type Deposit = ContractCallDeposit;
-    interface SubmitDepositResponse {
-        orderId: string;
-        txHash: string;
-    }
-    type OrderStatus = "created" | "deposited" | "published" | "filled" | "refund_pending" | "refunded" | "failed";
-    interface OnChainTx {
-        timestamp: string;
-        txHash: string;
-        chainId: number;
-        amount?: string;
-    }
-    interface OrderTransactions {
-        deposit?: OnChainTx;
-        fill?: OnChainTx;
-        refund?: OnChainTx;
-    }
-    interface OrderTimestamps {
-        createdAt: string;
-        publishedAt?: string;
-        failedAt?: string;
-    }
-    interface TokenMeta {
-        symbol: string;
-        decimals: number;
-        logoURI: string | null;
-    }
-    interface Order {
-        id: string;
-        type: string;
-        quoteId: string;
-        routeId: string;
-        fromChainId: number;
-        fromToken: string;
-        toChainId: number;
-        toToken: string;
-        srcAmount: string;
-        destAmount: string;
-        status: OrderStatus;
-        author: string;
-        recipient: string | null;
-        depositTxHash: string;
-        tradeType: string;
-        createdAt: string;
-        updatedAt: string;
-        transactions?: OrderTransactions;
-        timestamps?: OrderTimestamps;
-        stepsCompleted?: OrderStatus[];
-        fromTokenMeta?: TokenMeta | null;
-        toTokenMeta?: TokenMeta | null;
-    }
-    interface GetOrderResponse {
-        data: Order[];
-        cursor?: number;
-    }
-}
-
-/** Check if two chains are of different types (cross-chain swap) */
-export declare function isCrossChainSwap(fromChainId: number, toChainId: number): boolean;
-
-/** Check if a chainId is EVM */
-export declare function isEvmChain(chainId: number): boolean;
-
-/** Check if a chainId is Solana */
-export declare function isSolanaChain(chainId: number): boolean;
-
-/** Wallet adapter interface that all adapters must implement */
-export declare interface IWalletAdapter {
-    /** Human-readable name */
-    readonly name: string;
-    /** Icon URL */
-    readonly icon?: string;
-    /** Supported action types */
-    readonly supportedActionTypes: WalletActionType[];
-    /** Optional: supported chain IDs — when set, the widget only shows tokens on these chains */
-    readonly supportedChainIds?: number[];
-    /** Connect the wallet */
-    connect(chainType?: ChainType): Promise<void>;
-    /** Disconnect the wallet */
-    disconnect(): Promise<void>;
-    /** Check if connected */
-    isConnected(chainType?: ChainType): boolean;
-    /** Get the current address */
-    getAddress(chainType?: ChainType): Promise<string | null>;
-    /** Execute a wallet action */
-    executeWalletAction(action: WalletAction): Promise<WalletActionResult>;
-    /** Optional: sign a message */
-    signMessage?(message: string, chainType?: ChainType): Promise<string>;
-    /** Optional: open the wallet's native account/connected modal */
-    openAccountModal?(): Promise<void>;
-    /** Optional: clean up internal subscriptions and watchers */
-    destroy?(): void;
-    /** Subscribe to wallet events */
-    on(event: WalletEventType, handler: (event: WalletEvent) => void): void;
-    /** Unsubscribe from wallet events */
-    off(event: WalletEventType, handler: (event: WalletEvent) => void): void;
-}
-
-export declare class MockWalletAdapter implements IWalletAdapter {
-    readonly name = "Mock Wallet";
-    readonly icon: undefined;
-    readonly supportedActionTypes: WalletActionType[];
-    private connected;
-    private address;
-    private listeners;
-    connect(_chainType?: ChainType): Promise<void>;
-    disconnect(): Promise<void>;
-    isConnected(_chainType?: ChainType): boolean;
-    getAddress(_chainType?: ChainType): Promise<string | null>;
-    executeWalletAction(action: WalletAction): Promise<WalletActionResult>;
-    signMessage(message: string): Promise<string>;
-    openAccountModal(): Promise<void>;
-    on(event: WalletEventType, handler: (event: WalletEvent) => void): void;
-    off(event: WalletEventType, handler: (event: WalletEvent) => void): void;
-    private emit;
-}
-
-/**
- * Minimal offer data needed for ranking offers.
- * For offers (EXACT_OUTPUT): lower amountIn is better.
- */
-declare interface OfferForRanking {
-    routeId: string;
-    amountIn: bigint;
-    etaSeconds: number;
-    isGuaranteedOutput: boolean;
-    isOneClick: boolean;
-}
-
-export declare type OnChainTx = HyperstreamApi.OnChainTx;
-
-export declare type OrderListResponse = HyperstreamApi.GetOrderResponse;
-
-export declare type OrderResponse = HyperstreamApi.Order;
-
-export declare type OrderStatus = HyperstreamApi.OrderStatus;
-
-export declare type OrderTimestamps = HyperstreamApi.OrderTimestamps;
-
-export declare type OrderTransactions = HyperstreamApi.OrderTransactions;
-
-export declare type QuoteRequest = HyperstreamApi.QuoteRequest;
-
-export declare type QuoteResponse = HyperstreamApi.GetQuotesResponse;
-
-export declare type QuoteRoute = HyperstreamApi.Route;
-
-/**
- * Rank offers where lower input amount is better (EXACT_OUTPUT).
- *
- * Same algorithm as rankSwapOffers but inverted:
- * best price = lowest amountIn, threshold = lowestAmountIn * 1.001
- */
-export declare function rankOffers(offers: readonly OfferForRanking[]): string[];
-
-/**
- * Non-derivable state for `<tokenflight-receive>`.
- *
- * Derivable values (phase, selectedQuote, paymentTokens) are computed in
- * ReceiveComponent from payTokenQuotes + loadingQuotes + these signals.
- */
-export declare interface ReceiveState {
-    targetToken: ResolvedToken | null;
-    targetAmount: string;
-    /** Set before execution starts for TransactionComplete display */
-    fromToken: ResolvedToken | null;
-    /** Recipient address for cross-chain swaps */
-    recipient: string | null;
-    walletAddress: string | null;
-    /** Current execution phase, or null when idle/quoting/quoted */
-    execPhase: ExecPhase | null;
-    order: OrderResponse | null;
-    error: string | null;
-    errorCode: string | null;
-}
-
-export declare function registerElements(options?: RegisterElementsOptions): void;
-
-export declare interface RegisterElementsOptions {
-    walletAdapter?: IWalletAdapter;
-    callbacks?: Callbacks;
-    /** Custom CSS variable overrides merged on top of the active theme.
-     *  Keys are CSS variable names, e.g. `"--tf-primary"`, `"--tf-font-family"`. */
-    customColors?: CustomColors;
-    /** Default API endpoint for all widget instances. */
-    apiEndpoint?: string;
-    /** Default theme for all widget instances. */
-    theme?: Theme;
-    /** Default locale for all widget instances. */
-    locale?: SupportedLocale;
-}
-
-/** Resolved token with full metadata for local display state */
-export declare interface ResolvedToken {
-    chainId: number;
-    address: string;
-    symbol?: string;
-    name?: string;
-    decimals?: number;
-    logoURI?: string;
-    priceUsd?: number;
-}
-
-export declare type RouteQuote = HyperstreamApi.Quote;
-
-export declare type RouteTag = HyperstreamApi.RouteTag;
-
-/** Chain ID for Solana mainnet in the API */
-export declare const SOLANA_CHAIN_ID = 20011000000;
-
-export declare type SolanaApproval = HyperstreamApi.SolanaApproval;
-
-/** Solana sign and send transaction action */
-export declare interface SolanaSignAndSendAction {
-    type: "solana_signAndSendTransaction";
-    transaction: string;
-}
-
-/** Solana sign transaction action */
-export declare interface SolanaSignTransactionAction {
-    type: "solana_signTransaction";
-    transaction: string;
-}
-
-export declare type SubmitDepositResponse = HyperstreamApi.SubmitDepositResponse;
-
-/** Supported locale identifiers. Accepts any string for forward-compat; known values get bundled translations. */
-export declare type SupportedLocale = "en-US" | "zh-CN" | "zh-TW" | "ja-JP" | "ko-KR" | (string & {});
-
-/** Data emitted on swap error */
-export declare interface SwapErrorData {
-    code: string;
-    message: string;
-    details?: unknown;
-}
-
-/** Swap flow phases */
-export declare type SwapPhase = "idle" | "quoting" | "quoted" | "building" | "awaiting-wallet" | "submitting" | "tracking" | "success" | "error";
-
-/** Data emitted on swap success */
-export declare interface SwapSuccessData {
-    orderId: string;
-    fromToken: string;
-    toToken: string;
-    fromAmount: string;
-    toAmount: string;
-    txHash: string;
-}
-
-/** Terminal order statuses */
-export declare const TERMINAL_ORDER_STATUSES: HyperstreamApi.OrderStatus[];
-
-/** Visual theme mode. */
-export declare type Theme = "light" | "dark" | "auto";
-
-/**
- * Convert display amount to base units (bigint string) using token decimals.
- * e.g., toBaseUnits("1", 6) → "1000000"
- *       toBaseUnits("1.5", 6) → "1500000"
- */
-export declare function toBaseUnits(displayAmount: string, decimals: number): string;
-
-/**
- * Convert base units (bigint string) to display amount using token decimals.
- * e.g., toDisplayAmount("1000000", 6) → "1"
- *       toDisplayAmount("1500000", 6) → "1.5"
- */
-export declare function toDisplayAmount(baseUnits: string, decimals: number): string;
-
-export declare type TokenExtensions = HyperstreamApi.TokenExtensions;
-
-/** Shared configuration fields for both widgets */
-export declare interface TokenFlightConfigBase {
-    /** HyperStream API endpoint */
-    apiEndpoint?: string;
-    /** Visual theme */
-    theme?: Theme;
-    /** Locale for i18n */
-    locale?: SupportedLocale;
-    /** Custom CSS color overrides */
-    customColors?: CustomColors;
-    /** Optional custom widget title text */
-    titleText?: string;
-    /** Optional custom widget title image URL */
-    titleImageUrl?: string;
-    /** Hide top title/header area */
-    hideTitle?: boolean;
-    /** Hide "Powered by TokenFlight" footer */
-    hidePoweredBy?: boolean;
-    /** Remove container background (transparent) */
-    noBackground?: boolean;
-    /** Remove container border and shadow */
-    noBorder?: boolean;
-}
-
-/** Custom error class for TokenFlight SDK */
-export declare class TokenFlightError extends Error {
-    readonly code: ErrorCode;
-    readonly details?: unknown;
-    constructor(code: ErrorCode, message: string | unknown, details?: unknown);
-}
-
-export declare class TokenFlightReceive {
-    private dispose;
-    private unwatchTheme;
-    private container;
-    private shadowRoot;
-    private config;
-    private walletAdapter?;
-    private callbacks?;
-    constructor(options: TokenFlightReceiveOptions);
-    initialize(): void;
-    destroy(): void;
-    setTheme(theme: Theme): void;
-    setCustomColors(colors: CustomColors): void;
-    private applyThemeStyles;
-    private setupAutoThemeWatch;
-}
-
-/** Attributes accepted by `<tokenflight-receive>`. */
-export declare interface TokenFlightReceiveAttributes {
-    "api-endpoint"?: string;
-    target?: string;
-    amount?: string;
-    "from-token"?: string;
-    recipient?: string;
-    "title-text"?: string;
-    "title-image"?: string;
-    theme?: Theme;
-    locale?: SupportedLocale;
-    "csp-nonce"?: string;
-    icon?: string;
-    "hide-title"?: BooleanAttribute;
-    "hide-powered-by"?: BooleanAttribute;
-    "no-background"?: BooleanAttribute;
-    "no-border"?: BooleanAttribute;
-}
-
-/** Configuration for `<tokenflight-receive>` */
-export declare interface TokenFlightReceiveConfig extends TokenFlightConfigBase {
-    /** Required: target token to receive */
-    target: TokenIdentifier;
-    /** Required: amount to receive */
-    amount: string;
-    /** Optional source token to pay with */
-    fromToken?: TokenIdentifier;
-    /** Optional recipient address (for cross-chain swaps to a different address) */
-    recipient?: string;
-    /** Optional icon URL for the target token */
-    icon?: string;
-}
-
-export declare interface TokenFlightReceiveOptions {
-    container: string | HTMLElement;
-    config: TokenFlightReceiveConfig;
-    walletAdapter?: IWalletAdapter;
-    callbacks?: Callbacks;
-}
-
-/**
- * Flexible token identifier supporting:
- * - Direct object: { chainId: 1, address: "0x..." }
- * - CAIP-10 string: "eip155:1:0x..."
- * - JSON string: '{"chainId":1,"address":"0x..."}'
- */
-export declare type TokenIdentifier = string | TokenTarget;
-
-export declare type TokenInfo = HyperstreamApi.Token;
-
-export declare type TokenListResponse = HyperstreamApi.GetTokensResponse;
-
-export declare type TokenMeta = HyperstreamApi.TokenMeta;
-
-export declare type TokenSearchResponse = HyperstreamApi.TokenSearchResponse;
-
-/** Token target as chain + address pair */
-export declare interface TokenTarget {
-    chainId: number;
-    address: string;
-}
-
-export declare type TradeType = HyperstreamApi.TradeType;
-
-/** Union of all wallet action types */
-export declare type WalletAction = EvmWalletAction | SolanaSignTransactionAction | SolanaSignAndSendAction;
-
-/** Result of executing a wallet action */
-export declare interface WalletActionResult {
-    success: boolean;
-    data?: unknown;
-    error?: string;
-    txHash?: string;
-}
-
-/** Wallet action types */
-export declare type WalletActionType = "eip1193_request" | "solana_signTransaction" | "solana_signAndSendTransaction";
-
-/** Data emitted when wallet is connected */
-export declare interface WalletConnectedData {
-    address: string;
-    chainType: string;
-}
-
-/** Wallet event payload */
-export declare interface WalletEvent {
-    type: WalletEventType;
-    data?: unknown;
-}
-
-/** Wallet event types */
-export declare type WalletEventType = "connect" | "disconnect" | "chainChanged" | "accountsChanged";
-
-export { }