@naculus/connect-appkit-vue 0.2.4 → 0.2.5

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { StencilVueComponent } from '@stencil/vue-output-target/runtime';
 import { JSX } from '@naculus/connect-appkit-wc';
-import { ComputedRef, MaybeRefOrGetter, shallowRef, ref, ShallowRef } from 'vue';
-import { WalletChain, ChainInfo, ChainCapabilities, AtomicSupport, SolanaRoles, SolanaRolesAbsence, SolanaIdentity, SolanaSigner, SolanaPayer, SolanaRolesSource } from '@naculus/connect-appkit-core';
+import { ComputedRef, MaybeRefOrGetter, MaybeRef, ShallowRef, shallowRef, ref } from 'vue';
+import { NotificationSettingsStorage, RouteQuote, RouteQuoteInput, GetRouteQuotes, CostComparison, CompareCostsInput, CompareCosts, ExecutableQuote, ExecuteRouteOptions, ExecuteRouteResult, ExecuteRouteError, ExecuteRoute, DestinationValidation, WalletChain, ChainInfo, ChainCapabilities, AtomicSupport, SolanaRoles, SolanaRolesAbsence, SolanaIdentity, SolanaSigner, SolanaPayer, SolanaRolesSource } from '@naculus/connect-appkit-core';
 export { AtomicSupport, ChainCapabilities, SolanaIdentity, SolanaPayer, SolanaRoles, SolanaRolesAbsence, SolanaRolesSource, SolanaSigner, SolanaWalletFeatures } from '@naculus/connect-appkit-core';
-import { PassphraseGate } from '@naculus/connect-core';
+import { InAppChannel, NotificationItem, NotificationSettings, ActiveSessionBundle, ChainSession, SessionManager, WalletError, TokenListSource, TokenListManager, TokenListEntry, TokenSearchResult, ERC20_MIN_ABI, AddressResult, NameResolverConfig, NameResult, PassphraseGate } from '@naculus/connect-core';
 
 declare const AppkitAccordion: StencilVueComponent<JSX.AppkitAccordion>;
 declare const AppkitAccountButton: StencilVueComponent<JSX.AppkitAccountButton>;
@@ -56,6 +56,303 @@ interface UseAccountsReturn {
  */
 declare function useAccounts(accounts: MaybeRefOrGetter<string[] | null | undefined>): UseAccountsReturn;
 
+interface UseNotificationOptions {
+    channel?: MaybeRef<InAppChannel>;
+    storage?: MaybeRef<NotificationSettingsStorage>;
+}
+interface UseNotificationReturn {
+    notifications: ShallowRef<NotificationItem[]>;
+    unreadCount: ComputedRef<number>;
+    settings: ShallowRef<NotificationSettings>;
+    addNotification: (item: Omit<NotificationItem, "id" | "timestamp">) => void;
+    clear: () => void;
+    clearOne: (id: string) => void;
+    markAsRead: (id: string) => void;
+    markAllAsRead: () => void;
+    updateSettings: (update: Partial<NotificationSettings>) => void;
+    setChannels: (channels: string[]) => void;
+    muteChain: (chainId: string) => void;
+    unmuteChain: (chainId: string) => void;
+}
+/** Vue state shell over the shared in-app notification actions. */
+declare function useNotification(options?: UseNotificationOptions): UseNotificationReturn;
+
+interface UseAccountReturn {
+    accounts: ComputedRef<AccountEntry[] | null>;
+    evmAccount: ComputedRef<string | null>;
+    primaryAccount: ComputedRef<string | null>;
+    isConnected: ComputedRef<boolean>;
+    count: ComputedRef<number>;
+}
+/** React useAccount's connected-state view of the shared account parser. */
+declare function useAccount(accounts: MaybeRefOrGetter<string[] | null | undefined>, connected: MaybeRefOrGetter<boolean>): UseAccountReturn;
+
+interface UseSessionReturn {
+    session: ComputedRef<ActiveSessionBundle["walletSession"] | null>;
+    chainSessions: ComputedRef<ChainSession[]>;
+    activeChainId: ComputedRef<string | null>;
+    isConnected: ComputedRef<boolean>;
+    connectorId: ComputedRef<string | null>;
+}
+/** Reactively expose a caller-owned SessionManager's active bundle. */
+declare function useSession(manager: MaybeRefOrGetter<SessionManager | null | undefined>): UseSessionReturn;
+
+interface UseConnectReturn {
+    connect: () => Promise<void>;
+    isConnecting: ComputedRef<boolean>;
+    error: ShallowRef<Error | null>;
+}
+/** Connection state around a caller-owned action; never connects on mount. */
+declare function useConnect(action: MaybeRef<() => Promise<void>>, status: MaybeRefOrGetter<string>): UseConnectReturn;
+
+interface UseDisconnectReturn {
+    disconnect: () => Promise<void>;
+    isDisconnecting: ShallowRef<boolean>;
+    error: ShallowRef<Error | null>;
+    cleanup: () => void;
+}
+/** Disconnect through a caller-owned action, preserving React's no-op when already disconnected. */
+declare function useDisconnect(action: MaybeRef<() => Promise<void>>, status: MaybeRefOrGetter<string>): UseDisconnectReturn;
+
+interface UseSwitchChainReturn {
+    switchChain: (chainId: string) => Promise<void>;
+    isSwitching: ShallowRef<boolean>;
+    currentChainId: ComputedRef<string | null>;
+    error: ShallowRef<WalletError | null>;
+    clearError: () => void;
+}
+/** Vue counterpart of React useSwitchChain around a caller-owned action. */
+declare function useSwitchChain(action: MaybeRef<(chainId: string) => Promise<void>>, chainId: MaybeRefOrGetter<string | null | undefined>): UseSwitchChainReturn;
+
+/** Minimal read-only contract; a viem PublicClient satisfies it. */
+interface NativeBalanceReader {
+    getBalance(args: {
+        address: `0x${string}`;
+    }): Promise<bigint>;
+}
+interface UseBalanceOptions {
+    /** Native currency decimals. Default 18. */
+    decimals?: MaybeRefOrGetter<number | null | undefined>;
+    /**
+     * Native currency symbol, or null when it is not known. Null rather than
+     * "ETH": a wrong unit beside the number is worse than no unit.
+     */
+    symbol?: MaybeRefOrGetter<string | null | undefined>;
+    /** Auto-refresh interval in milliseconds. Default: no auto-refresh. */
+    refreshInterval?: MaybeRefOrGetter<number | null | undefined>;
+}
+interface UseBalanceReturn {
+    /** Raw balance in wei as a decimal string, or null when unread. */
+    balance: ShallowRef<string | null>;
+    /** Human-readable balance in the native unit, or null when unread. */
+    formatted: ComputedRef<string | null>;
+    symbol: ComputedRef<string | null>;
+    isFetching: ShallowRef<boolean>;
+    error: ShallowRef<Error | null>;
+    refetch: () => Promise<void>;
+}
+/**
+ * Native balance of an EVM account through a caller-owned reader.
+ *
+ * Vue has no AppKit provider, so the client is explicit. Unlike the React
+ * hook this does not fetch a USD price: that is an outward HTTP call the
+ * caller did not hand us, and it belongs beside the reader they did.
+ */
+declare function useBalance(account: MaybeRefOrGetter<string | null | undefined>, client: MaybeRefOrGetter<NativeBalanceReader | null | undefined>, options?: UseBalanceOptions): UseBalanceReturn;
+
+interface UseRouteQuoteOptions {
+    /** Debounce before auto-fetching after an input change (default 300 ms). */
+    debounceMs?: number;
+}
+interface UseRouteQuoteReturn {
+    quotes: ShallowRef<RouteQuote[]>;
+    loading: ShallowRef<boolean>;
+    error: ShallowRef<Error | null>;
+    refresh: () => Promise<void>;
+    clear: () => void;
+}
+/**
+ * Debounced cross-chain route quotes through a caller-supplied quote
+ * function, mirroring the React hook. Which inputs are quotable is decided
+ * in appkit-core; this file debounces and drops late results.
+ */
+declare function useRouteQuote(input: MaybeRefOrGetter<RouteQuoteInput>, getQuotes?: MaybeRef<GetRouteQuotes | null | undefined>, options?: UseRouteQuoteOptions): UseRouteQuoteReturn;
+
+interface UseCompareCostsReturn {
+    comparisons: ShallowRef<CostComparison[]>;
+    loading: ShallowRef<boolean>;
+    error: ShallowRef<Error | null>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Compare an operation's cost across chains through a caller-supplied
+ * function, mirroring the React hook. Re-fetches when the input's *value*
+ * changes (appkit-core's `compareCostsKey`), not when a new array or object
+ * with the same content is passed; only the newest request may write.
+ */
+declare function useCompareCosts(input: MaybeRefOrGetter<CompareCostsInput>, compareCosts?: MaybeRef<CompareCosts | null | undefined>): UseCompareCostsReturn;
+
+interface UseExecuteRouteReturn {
+    execute: (quote: ExecutableQuote, recipient: string, options?: ExecuteRouteOptions) => Promise<ExecuteRouteResult | null>;
+    executing: ShallowRef<boolean>;
+    result: ShallowRef<ExecuteRouteResult | null>;
+    error: ShallowRef<ExecuteRouteError | null>;
+    reset: () => void;
+}
+/**
+ * Execute a quoted route once through a caller-supplied executor, mirroring
+ * the React hook. The recipient check and error shape are appkit-core's. A
+ * second call while one is in flight is refused, and `reset()` deliberately
+ * does not unlock that guard: the first request is still out there.
+ */
+declare function useExecuteRoute(executeRoute?: MaybeRef<ExecuteRoute | null | undefined>): UseExecuteRouteReturn;
+
+interface UseTokenListOptions {
+    /** Load on creation (default: true). */
+    autoLoad?: boolean;
+    /** Custom sources; the manager's defaults otherwise. */
+    sources?: TokenListSource[];
+    /** Reuse a caller-owned manager instead of creating one. */
+    manager?: TokenListManager;
+}
+interface UseTokenListReturn {
+    /** Tokens for the given chain, or all chains when none is given. */
+    tokens: ShallowRef<TokenListEntry[]>;
+    isLoading: ShallowRef<boolean>;
+    /** True once a load has completed at least once. */
+    isLoaded: ShallowRef<boolean>;
+    error: ShallowRef<Error | null>;
+    /** Force a refresh from all sources. */
+    refetch: () => Promise<void>;
+}
+/**
+ * Token list for a chain, mirroring the React hook. The list logic, caching
+ * and chain filtering are `TokenListManager`'s; this file is Vue plumbing.
+ * The chain id is CAIP-2; a non-EVM chain yields the unfiltered list rather
+ * than a bogus numeric filter.
+ */
+declare function useTokenList(chainId?: MaybeRefOrGetter<string | null | undefined>, options?: UseTokenListOptions): UseTokenListReturn;
+
+interface UseTokenSearchOptions {
+    /** Reuse a caller-owned manager; otherwise one shared instance per page. */
+    manager?: TokenListManager;
+    /** Debounce in ms (default 300). */
+    debounceMs?: number;
+    /** Max results per bucket (default 20). */
+    limit?: number;
+}
+interface UseTokenSearchReturn {
+    results: ShallowRef<TokenSearchResult>;
+    /** True from the first keystroke until the debounced search has run. */
+    isSearching: ShallowRef<boolean>;
+}
+/**
+ * Debounced token search by symbol, name or address, mirroring the React
+ * hook. Matching lives in `TokenListManager.search`; this file only debounces
+ * and keeps a late timer from writing after the query moved on.
+ */
+declare function useTokenSearch(query: MaybeRefOrGetter<string | null | undefined>, chainId?: MaybeRefOrGetter<string | null | undefined>, options?: UseTokenSearchOptions): UseTokenSearchReturn;
+
+interface UseValidateDestinationReturn {
+    validation: ComputedRef<DestinationValidation>;
+}
+/**
+ * Syntactic destination checks, shared with the React hook through
+ * `@naculus/connect-appkit-core`. Returns a machine-readable `issue`; the
+ * Vue package carries no locale table, so the caller maps it to a string.
+ * `level: "ok"` means nothing wrong was found — not that it is safe.
+ */
+declare function useValidateDestination(address: MaybeRefOrGetter<string | null | undefined>): UseValidateDestinationReturn;
+
+interface TokenInfo {
+    /** ERC-20 token contract address */
+    address: `0x${string}`;
+    symbol: string;
+    decimals: number;
+    name?: string;
+}
+/** Minimal read-only contract; a viem PublicClient satisfies it. */
+interface TokenBalanceReader {
+    readContract(args: {
+        address: `0x${string}`;
+        abi: typeof ERC20_MIN_ABI;
+        functionName: "balanceOf";
+        args: readonly [`0x${string}`];
+    }): Promise<unknown>;
+}
+interface TokenBalanceResult extends TokenInfo {
+    /** Raw balance in the smallest unit as a decimal string, or null if unread. */
+    balance: string | null;
+    /** Human-readable balance, or null if unread. */
+    formatted: string | null;
+}
+interface UseTokenBalanceOptions {
+    /** Auto-refresh interval in milliseconds. Default: no auto-refresh. */
+    refreshInterval?: MaybeRefOrGetter<number | null | undefined>;
+}
+interface UseTokenBalanceReturn {
+    tokenBalances: ShallowRef<TokenBalanceResult[]>;
+    isFetching: ShallowRef<boolean>;
+    error: ShallowRef<Error | null>;
+    refetch: () => Promise<void>;
+    getTokenBalance: (tokenAddress: `0x${string}`) => TokenBalanceResult | undefined;
+}
+/**
+ * ERC-20 balances of an EVM account through a caller-owned reader.
+ *
+ * Mirrors the React hook: one token failing to read leaves that entry with a
+ * null balance and does not fail the others. A late response for a previous
+ * account, reader or token list is dropped.
+ */
+declare function useTokenBalance(account: MaybeRefOrGetter<string | null | undefined>, client: MaybeRefOrGetter<TokenBalanceReader | null | undefined>, tokens: MaybeRefOrGetter<readonly TokenInfo[] | null | undefined>, options?: UseTokenBalanceOptions): UseTokenBalanceReturn;
+
+/** Minimal read-only contract; a viem PublicClient can supply getCode. */
+interface DelegationCodeReader {
+    getCode(args: {
+        address: `0x${string}`;
+    }): Promise<`0x${string}` | undefined>;
+}
+interface UseDelegationReturn {
+    delegated: ComputedRef<boolean | null>;
+    delegate: ComputedRef<`0x${string}` | null>;
+    isFetching: ShallowRef<boolean>;
+    error: ShallowRef<Error | null>;
+    refetch: () => Promise<void>;
+}
+/** Read current EIP-7702 delegation without treating an unread account as undelegated. */
+declare function useDelegation(account: MaybeRefOrGetter<string | null | undefined>, client: MaybeRefOrGetter<DelegationCodeReader | null | undefined>, chainId?: MaybeRefOrGetter<string | null | undefined>): UseDelegationReturn;
+
+interface NameLookupReturn<T> {
+    data: ShallowRef<T | null>;
+    isLoading: ComputedRef<boolean>;
+    error: ShallowRef<Error | null>;
+    refetch: () => void;
+}
+
+type UseResolveNameReturn = NameLookupReturn<AddressResult>;
+/** Resolve a reactive ENS or SNS name to an address. */
+declare function useResolveName(name: MaybeRefOrGetter<string>, options?: {
+    skip?: MaybeRefOrGetter<boolean | undefined>;
+    resolverConfig?: MaybeRefOrGetter<NameResolverConfig | undefined>;
+}): UseResolveNameReturn;
+
+type UseLookupAddressReturn = NameLookupReturn<NameResult>;
+/** Reverse-resolve a reactive address, optionally scoped to a CAIP-2 chain. */
+declare function useLookupAddress(address: MaybeRefOrGetter<string>, options?: {
+    chainId?: MaybeRefOrGetter<string | undefined>;
+    skip?: MaybeRefOrGetter<boolean | undefined>;
+    resolverConfig?: MaybeRefOrGetter<NameResolverConfig | undefined>;
+}): UseLookupAddressReturn;
+
+interface UseSolanaAccountReturn {
+    address: ComputedRef<string | null>;
+    caip10: ComputedRef<string | null>;
+    chainId: ComputedRef<string | null>;
+    isConnected: ComputedRef<boolean>;
+}
+/** Read the connected Solana CAIP-10 account from any wallet. */
+declare function useSolanaAccount(accounts: MaybeRefOrGetter<string[] | null | undefined>, connected: MaybeRefOrGetter<boolean>): UseSolanaAccountReturn;
+
 interface UseChainReturn {
     /** The configured chain matching the connected CAIP-2 id, or null. */
     currentChain: ComputedRef<WalletChain | null>;
@@ -133,6 +430,81 @@ interface UseSolanaBalanceReturn {
  */
 declare function useSolanaBalance(address: MaybeRefOrGetter<string | null | undefined>, rpcUrl: MaybeRefOrGetter<string | null | undefined>): UseSolanaBalanceReturn;
 
+type TxStatus = "pending" | "mined" | "confirmed" | "failed" | "unknown";
+interface TxStatusEntry {
+    hash: string;
+    chainId: number;
+    from: string;
+    to: string;
+    value: string;
+    data?: string;
+    nonce?: number;
+    status: TxStatus;
+    blockNumber?: number;
+    blockHash?: string;
+    gasUsed?: string;
+    effectiveGasPrice?: string;
+    createdAt: number;
+    confirmedAt?: number;
+    updatedAt: number;
+    error?: string;
+    label?: string;
+    memo?: string;
+    replacementCount?: number;
+}
+/** Structural contract accepted by the transaction-monitor composables. */
+interface TxMonitorLike {
+    watchTx(hash: string, chainId: number, options?: Record<string, unknown>): Promise<TxStatusEntry>;
+    stopWatching(hash: string, chainId?: number): void;
+    getTxStatus(hash: string, chainId?: number): TxStatusEntry | null;
+    getTxHistory(address?: string, chainId?: number): Promise<TxStatusEntry[]>;
+    refreshTx(hash: string, chainId?: number): Promise<void>;
+    on(event: "statusChange", listener: (entry: TxStatusEntry) => void): this;
+    on(event: "confirmed", listener: (entry: TxStatusEntry) => void): this;
+    on(event: "failed", listener: (entry: TxStatusEntry) => void): this;
+    off(event: string, listener: Function): this;
+}
+interface UseTxMonitorReturn {
+    entry: ShallowRef<TxStatusEntry | null>;
+    status: ComputedRef<TxStatus | "idle">;
+    isLoading: ShallowRef<boolean>;
+    isWatching: ShallowRef<boolean>;
+    error: ShallowRef<Error | null>;
+    refresh: () => Promise<void>;
+    stopWatching: () => void;
+}
+/**
+ * Reactively monitor one transaction using a caller-owned TxMonitor.
+ *
+ * Vue has no AppKit monitor provider, so the monitor is explicit. The hook
+ * listens only while its source values are current; a late promise from a
+ * previous hash, chain, or monitor cannot overwrite the active result.
+ */
+declare function useTxMonitor(hash: MaybeRefOrGetter<string | null | undefined>, chainId: MaybeRefOrGetter<number | null | undefined>, monitor: MaybeRefOrGetter<TxMonitorLike | null | undefined>): UseTxMonitorReturn;
+
+interface UseLastTxReturn {
+    lastTx: ShallowRef<TxStatusEntry | null>;
+    lastConfirmedTx: ShallowRef<TxStatusEntry | null>;
+    lastFailedTx: ShallowRef<TxStatusEntry | null>;
+    clear: () => void;
+}
+/** Track the latest confirmed or failed transaction from a caller-owned monitor. */
+declare function useLastTx(monitor: MaybeRefOrGetter<TxMonitorLike | null | undefined>): UseLastTxReturn;
+
+interface UseTxHistoryReturn {
+    entries: ShallowRef<TxStatusEntry[]>;
+    isLoading: ShallowRef<boolean>;
+    error: ShallowRef<Error | null>;
+    refresh: () => Promise<void>;
+    summary: ComputedRef<{
+        pending: number;
+        confirmed: number;
+        failed: number;
+    }>;
+}
+/** Query and keep a caller-owned monitor's transaction history current. */
+declare function useTxHistory(address: MaybeRefOrGetter<string | null | undefined>, chainId: MaybeRefOrGetter<number | null | undefined>, monitor: MaybeRefOrGetter<TxMonitorLike | null | undefined>): UseTxHistoryReturn;
+
 /** The part of a connector this needs. Anything with these two is enough. */
 interface CapabilityClient {
     getCapabilities?: (session: unknown) => Promise<Record<string, unknown>>;
@@ -199,4 +571,4 @@ declare function useSolanaRoles(connector: MaybeRefOrGetter<SolanaRolesSource |
     walletType?: string;
 } | null | undefined>): UseSolanaRolesReturn;
 
-export { type AccountEntry, AppkitAccordion, AppkitAccountButton, AppkitAlertDialog, AppkitAvatar, AppkitBadge, AppkitButton, AppkitCard, AppkitCardContent, AppkitCardDescription, AppkitCardFooter, AppkitCardHeader, AppkitCardTitle, AppkitCheckbox, AppkitCollapsible, AppkitConnectButton, AppkitDialog, AppkitDropdownMenu, AppkitInput, AppkitPopover, AppkitProgress, AppkitScrollArea, AppkitSelect, AppkitSeparator, AppkitSkeleton, AppkitSwitch, AppkitTabs, AppkitToggleGroup, AppkitTooltip, type CapabilityClient, type UseAccountsReturn, type UseCapabilitiesReturn, type UseChainReturn, type UsePassphraseGateReturn, type UseSolanaBalanceReturn as UseSolanaBalanceVueReturn, type UseSolanaRolesReturn, useAccounts, useCapabilities, useChain, usePassphraseGate, useSolanaBalance, useSolanaRoles };
+export { type AccountEntry, AppkitAccordion, AppkitAccountButton, AppkitAlertDialog, AppkitAvatar, AppkitBadge, AppkitButton, AppkitCard, AppkitCardContent, AppkitCardDescription, AppkitCardFooter, AppkitCardHeader, AppkitCardTitle, AppkitCheckbox, AppkitCollapsible, AppkitConnectButton, AppkitDialog, AppkitDropdownMenu, AppkitInput, AppkitPopover, AppkitProgress, AppkitScrollArea, AppkitSelect, AppkitSeparator, AppkitSkeleton, AppkitSwitch, AppkitTabs, AppkitToggleGroup, AppkitTooltip, type CapabilityClient, type DelegationCodeReader, type NativeBalanceReader, type TokenBalanceReader, type TokenBalanceResult, type TokenInfo, type TxMonitorLike, type TxStatus, type TxStatusEntry, type UseAccountReturn, type UseAccountsReturn, type UseBalanceOptions, type UseBalanceReturn, type UseCapabilitiesReturn, type UseChainReturn, type UseCompareCostsReturn, type UseConnectReturn, type UseDelegationReturn, type UseDisconnectReturn, type UseExecuteRouteReturn, type UseLastTxReturn, type UseLookupAddressReturn, type UseNotificationOptions, type UseNotificationReturn, type UsePassphraseGateReturn, type UseResolveNameReturn, type UseRouteQuoteOptions, type UseRouteQuoteReturn, type UseSessionReturn, type UseSolanaAccountReturn, type UseSolanaBalanceReturn as UseSolanaBalanceVueReturn, type UseSolanaRolesReturn, type UseSwitchChainReturn, type UseTokenBalanceOptions, type UseTokenBalanceReturn, type UseTokenListOptions, type UseTokenListReturn, type UseTokenSearchOptions, type UseTokenSearchReturn, type UseTxHistoryReturn, type UseTxMonitorReturn, type UseValidateDestinationReturn, useAccount, useAccounts, useBalance, useCapabilities, useChain, useCompareCosts, useConnect, useDelegation, useDisconnect, useExecuteRoute, useLastTx, useLookupAddress, useNotification, usePassphraseGate, useResolveName, useRouteQuote, useSession, useSolanaAccount, useSolanaBalance, useSolanaRoles, useSwitchChain, useTokenBalance, useTokenList, useTokenSearch, useTxHistory, useTxMonitor, useValidateDestination };