@naculus/connect-appkit-core 0.2.3 → 0.2.5

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Namespace, UniversalWalletSession, TokenConfig, WalletError, WalletErrorCode, NameResolverConfig, NameResolver } from '@naculus/connect-core';
+import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem } from '@naculus/connect-core';
 
 /**
  * The types the framework-neutral half of appkit is built on.
@@ -42,6 +42,149 @@ interface Web3State {
     error: Error | null;
 }
 
+/**
+ * EIP-5792 capability answers, normalised once.
+ *
+ * Deciding how to execute before sending is the whole point of
+ * `wallet_getCapabilities`, and the reasoning that turns a raw answer into
+ * that decision is not React's. It lived inside the React hook, which meant a
+ * Vue composable could only get it by copying — and a second copy of "absence
+ * is not a denial" is exactly the copy that drifts back into `false`.
+ */
+
+/**
+ * Whether a wallet can execute a batch atomically.
+ *
+ * Three values, not two. A wallet that does not implement
+ * `wallet_getCapabilities` has not said no — it has said nothing, and EIP-5792
+ * is explicit that absence is not a denial. Collapsing that into `false` sends
+ * every such wallet down the sequential path, which is the one where an
+ * approve can land and the swap it was for can fail.
+ */
+type AtomicSupport = "supported" | "unsupported" | "unknown";
+interface ChainCapabilities {
+    /** CAIP-2 chain this describes. */
+    chainId: string;
+    atomic: AtomicSupport;
+    /** Largest batch the wallet will accept, when it says. */
+    maxBatchSize?: number;
+    /** The raw entry, for capabilities this SDK does not model. */
+    raw: WalletCapabilities;
+}
+/**
+ * Turn a wallet's raw answer into per-chain entries.
+ *
+ * Entries that are not objects are dropped rather than coerced: a wallet
+ * answering `null` for a chain has said nothing about it, and inventing an
+ * `"unsupported"` there would be the same mistake as reading absence as denial.
+ */
+declare function normalizeCapabilities(raw: Record<string, unknown> | null | undefined): Record<string, ChainCapabilities>;
+/**
+ * Find the entry for a chain, by CAIP-2 or by the hex form.
+ *
+ * Connectors normalise keys to CAIP-2, but a wallet answering in raw hex
+ * through a custom connector should still be found rather than reported as
+ * "unknown" next to an entry that is sitting right there.
+ */
+declare function selectChainCapabilities(capabilities: Record<string, ChainCapabilities> | null | undefined, chainId: string | null | undefined): ChainCapabilities | null;
+/**
+ * Atomic support for a chain.
+ *
+ * `"unknown"` covers every case where we have not been told: no query yet, a
+ * wallet without the method, a failed query, one still in flight. A caller
+ * choosing between an atomic and a sequential path needs that distinction, not
+ * a confident `false`.
+ */
+declare function atomicSupportFor(capabilities: Record<string, ChainCapabilities> | null | undefined, chainId: string | null | undefined): AtomicSupport;
+
+/**
+ * Solana signer roles, read once for both frameworks.
+ *
+ * `@naculus/connector-solana` splits a connected wallet into `identity`,
+ * `signer` and `payer`, each `null` when the wallet declared it cannot fill
+ * that job. That answer is the connector's. What this module owns is the part
+ * a UI has to decide before it can show anything: *why* there is no answer —
+ * because nothing is connected, because the connected wallet is not Solana,
+ * or because the connector predates the roles API and has not said. Those are
+ * three different screens, and a hook that hands back one `null` for all of
+ * them makes every consumer rediscover the distinction.
+ */
+/** Which account this is, with no ability to sign for it. */
+interface SolanaIdentity {
+    /** Base58 public key. */
+    readonly address: string;
+    /** CAIP-2 chain this account is being used on. */
+    readonly chain: string;
+}
+/** An account that will contribute a signature without submitting anything. */
+interface SolanaSigner extends SolanaIdentity {
+    signMessage?: (message: Uint8Array) => Promise<Uint8Array>;
+    signTransaction: (transaction: Uint8Array) => Promise<Uint8Array>;
+    /** Absent, not throwing, when the wallet has no batch feature. */
+    signAllTransactions?: (transactions: Uint8Array[]) => Promise<Uint8Array[]>;
+}
+/** An account that signs and broadcasts through the wallet's own RPC. */
+interface SolanaPayer extends SolanaIdentity {
+    /** Returns the base58 transaction signature the cluster accepted. */
+    signAndSendTransaction: (transaction: Uint8Array) => Promise<string>;
+}
+/** What the wallet declared, recorded at discovery. Two-state on purpose. */
+interface SolanaWalletFeatures {
+    signMessage: boolean;
+    signTransaction: boolean;
+    signAllTransactions: boolean;
+    signAndSendTransaction: boolean;
+}
+/**
+ * The roles a connected account can fill.
+ *
+ * Structurally identical to `SolanaRoles` in `@naculus/connector-solana`,
+ * declared here rather than imported because this package depends only on
+ * `@naculus/connect-core`, and the connector's own declaration is what its
+ * `getRoles` returns — a value of that type satisfies this one unchanged.
+ */
+interface SolanaRoles {
+    identity: SolanaIdentity;
+    signer: SolanaSigner | null;
+    payer: SolanaPayer | null;
+    features: SolanaWalletFeatures;
+}
+/** The part of a connector this needs. `getRoles` is optional on purpose. */
+interface SolanaRolesSource {
+    getRoles?: (session: unknown) => SolanaRoles | null;
+}
+/** The part of a session this needs. */
+interface SessionLike {
+    walletType?: string;
+}
+/**
+ * Why `roles` is null.
+ *
+ * - `no_session` — nothing connected, or the connector has no live session
+ *   for the one the app holds (a restored session before reconnect).
+ * - `not_solana` — the connected wallet is on another namespace. Not an
+ *   error; a Solana panel simply does not apply.
+ * - `unreported` — the connector does not expose `getRoles`. An older
+ *   `@naculus/connector-solana`, or a custom one. The wallet has not said
+ *   what it can do, which is not the same as saying it can do nothing.
+ */
+type SolanaRolesAbsence = "no_session" | "not_solana" | "unreported";
+type SolanaRolesState = {
+    roles: SolanaRoles;
+    absence: null;
+} | {
+    roles: null;
+    absence: SolanaRolesAbsence;
+};
+/**
+ * Read the roles for the session the app holds.
+ *
+ * Synchronous and pure: the connector already recorded what the wallet
+ * declared, so there is nothing to await and no prompt to trigger. Reading
+ * roles must never cost the user an approval dialog.
+ */
+declare function readSolanaRoles(connector: SolanaRolesSource | null | undefined, session: SessionLike | null | undefined): SolanaRolesState;
+
 /**
  * Which chains a session can actually switch to, and what the current one is.
  *
@@ -282,6 +425,148 @@ declare function getResolver(config?: NameResolverConfig): NameResolver;
 /** Test seam: drop the shared instance. */
 declare function __resetResolverForTests(): void;
 
+/** Framework-neutral in-app notification actions and settings persistence. */
+
+interface NotificationSettingsStorage {
+    getItem<T>(key: string): Promise<T | null>;
+    setItem<T>(key: string, value: T): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+declare const NOTIFICATION_SETTINGS_KEY = "naculus_notif_react_settings";
+declare const DEFAULT_NOTIFICATION_SETTINGS: NotificationSettings;
+/** Preserve the existing localStorage adapter and fail-open UI fallback. */
+declare function createNotificationSettingsStorage(): NotificationSettingsStorage;
+declare function loadNotificationSettings(storage: NotificationSettingsStorage): Promise<NotificationSettings | null>;
+declare function saveNotificationSettings(storage: NotificationSettingsStorage, settings: NotificationSettings): void;
+declare function updateNotificationSettings(current: NotificationSettings, update: Partial<NotificationSettings>): NotificationSettings;
+declare function channelsUpdate(channels: string[]): Partial<NotificationSettings>;
+declare function mutedChainSettings(settings: NotificationSettings, chainId: string, muted: boolean): Partial<NotificationSettings>;
+declare function createNotification(item: Omit<NotificationItem, "id" | "timestamp">): NotificationItem;
+declare function addInAppNotification(channel: InAppChannel, item: Omit<NotificationItem, "id" | "timestamp">): void;
+/** InAppChannel has no remove-one method; preserve its clear/replay behavior. */
+declare function clearOneInAppNotification(channel: InAppChannel, id: string): Promise<NotificationItem[]>;
+
+/**
+ * Destination-address checks shared by the React hook and the Vue composable.
+ *
+ * Syntactic only. `"ok"` means none of these checks found anything wrong —
+ * not that the recipient is who the user thinks. This cannot see an
+ * address-poisoning lookalike, a contract that will not release the funds,
+ * or a known-malicious destination. Labelling that "safe" once put a green
+ * tick beside a scammer's address; the level is deliberately not "safe".
+ */
+type AddressValidationLevel = "ok" | "warning" | "blocked";
+/** Machine-readable reason; the framework layer maps it to a user string. */
+type DestinationIssue = "empty" | "invalid_format" | "zero_address" | "burn_address";
+interface DestinationValidation {
+    isValid: boolean;
+    level: AddressValidationLevel;
+    issue: DestinationIssue | null;
+}
+/**
+ * Burn heuristic kept from the React hook: known sinks plus any well-formed
+ * address containing "dead". Stricter than connect-core's prefix-only
+ * `isBurnAddress`; unifying the two is a connect-lib change.
+ */
+declare function isBurnDestination(address: string): boolean;
+declare function validateDestination(address: string): DestinationValidation;
+/**
+ * The bare `0x…` account from either a CAIP-10 id (`eip155:1:0x…`) or a plain
+ * hex address; null when it is neither. Hooks and composables should not each
+ * carry their own copy of this split.
+ */
+declare function bareEvmAddress(account: string | null | undefined): `0x${string}` | null;
+
+/**
+ * Chain-abstraction (routing) domain types and the few decisions the React
+ * hooks and Vue composables share. The hooks inject the actual quote /
+ * compare / execute functions; nothing here talks to a network.
+ */
+interface RouteQuote {
+    routeId: string;
+    provider: string;
+    netReceiveFormatted: string;
+    toTokenSymbol: string;
+}
+interface RouteQuoteOptions {
+    sortBy?: "cost" | "time" | "balance";
+    maxSlippage?: number;
+}
+interface RouteQuoteInput {
+    fromChain: string;
+    toChain: string;
+    fromToken: string;
+    toToken?: string;
+    amount: string;
+    options?: RouteQuoteOptions;
+}
+type GetRouteQuotes = (from: string, to: string, token: string, amount: string, options?: RouteQuoteOptions, toToken?: string) => Promise<RouteQuote[]>;
+/**
+ * `BigInt()` throws on anything that is not a decimal integer — "1.5", "abc",
+ * "1e18" — so a user typing into an amount field must not reach it. Only a
+ * positive base-unit integer is a quotable amount.
+ */
+declare function isPositiveIntegerAmount(amount: string): boolean;
+/** True when every field a quote needs is present and the amount is quotable. */
+declare function isQuotableInput(input: RouteQuoteInput): boolean;
+interface CostComparison {
+    chain: string;
+    chainName: string;
+    totalCost: string;
+    gasCost: string;
+    estimatedTimeMs: number;
+}
+type CostComparisonOperation = "send_erc20" | "swap" | "bridge" | (string & {});
+interface CostComparisonOptions {
+    amount?: string;
+    token?: string;
+    [key: string]: unknown;
+}
+interface CompareCostsInput {
+    operation: CostComparisonOperation;
+    chains: string[];
+    options?: CostComparisonOptions;
+}
+type CompareCosts = (operation: string, chains: string[], options?: CostComparisonOptions) => Promise<CostComparison[]>;
+/**
+ * Value key for a compare-costs input. `chains` is an array and `options` an
+ * object; keying on identity re-fired the fetch on every render/reactive tick
+ * for a caller writing the natural inline literal — an unbounded loop against
+ * a cost API.
+ */
+declare function compareCostsKey(input: CompareCostsInput): string;
+interface ExecutableQuote {
+    routeId: string;
+    provider: string;
+    totalCost?: bigint;
+    estimatedTimeMs?: number;
+    toChain?: string;
+}
+interface ExecuteRouteResult {
+    fromTxHash: string;
+    toTxHash?: string;
+}
+interface ExecuteRouteOptions {
+    timeoutMs?: number;
+    gasLimit?: bigint;
+}
+interface ExecuteRouteError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type ExecuteRoute = (quote: ExecutableQuote, recipient: string, options?: ExecuteRouteOptions) => Promise<ExecuteRouteResult>;
+/**
+ * Recipient check before a cross-chain execution. An empty recipient is wrong
+ * on every chain. Beyond that the destination namespace decides: when the
+ * quote names `toChain`, the address is validated for that namespace; when it
+ * does not, this returns null and the executor decides, rather than rejecting
+ * a valid non-EVM address on a guess.
+ */
+declare function validateRouteRecipient(quote: ExecutableQuote | null | undefined, recipient: string): ExecuteRouteError | null;
+/** Normalise whatever an executor threw into the hook's error shape. */
+declare function toExecuteRouteError(cause: unknown): ExecuteRouteError;
+
 declare function withTimeout<T>(promise: Promise<T>, ms: number, label?: string): Promise<T>;
 interface RetryOptions {
     maxRetries: number;
@@ -322,4 +607,4 @@ type Web3Action = {
 declare const initialWeb3State: Web3State;
 declare function web3Reducer(state: Web3State, action: Web3Action): Web3State;
 
-export { type ChainInfo, type ConnectionStatus, type DecimalsCache, type RetryOptions, type TokenIdentity, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, chainNamespace, chainNumber, chainsForNamespace, createDecimalsCache, decodeRevertReason, describeChain, eip155ChainIdToNumber, getResolver, initialWeb3State, isEvmChainId, normalizeEip155ChainId, readDecimals, resolveChain, resolveEvmChainId, resolveRevertReason, toChainSwitchError, toEip155Accounts, toViemChain, tokenChainMismatch, tokenKey, web3Reducer, withRetry, withTimeout, writeDecimals };
+export { type AddressValidationLevel, type AtomicSupport, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, type DecimalsCache, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SolanaIdentity, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSigner, type SolanaWalletFeatures, type TokenIdentity, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, atomicSupportFor, bareEvmAddress, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createNotification, createNotificationSettingsStorage, decodeRevertReason, describeChain, eip155ChainIdToNumber, getResolver, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, readDecimals, readSolanaRoles, resolveChain, resolveEvmChainId, resolveRevertReason, saveNotificationSettings, selectChainCapabilities, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Namespace, UniversalWalletSession, TokenConfig, WalletError, WalletErrorCode, NameResolverConfig, NameResolver } from '@naculus/connect-core';
+import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem } from '@naculus/connect-core';
 
 /**
  * The types the framework-neutral half of appkit is built on.
@@ -42,6 +42,149 @@ interface Web3State {
     error: Error | null;
 }
 
+/**
+ * EIP-5792 capability answers, normalised once.
+ *
+ * Deciding how to execute before sending is the whole point of
+ * `wallet_getCapabilities`, and the reasoning that turns a raw answer into
+ * that decision is not React's. It lived inside the React hook, which meant a
+ * Vue composable could only get it by copying — and a second copy of "absence
+ * is not a denial" is exactly the copy that drifts back into `false`.
+ */
+
+/**
+ * Whether a wallet can execute a batch atomically.
+ *
+ * Three values, not two. A wallet that does not implement
+ * `wallet_getCapabilities` has not said no — it has said nothing, and EIP-5792
+ * is explicit that absence is not a denial. Collapsing that into `false` sends
+ * every such wallet down the sequential path, which is the one where an
+ * approve can land and the swap it was for can fail.
+ */
+type AtomicSupport = "supported" | "unsupported" | "unknown";
+interface ChainCapabilities {
+    /** CAIP-2 chain this describes. */
+    chainId: string;
+    atomic: AtomicSupport;
+    /** Largest batch the wallet will accept, when it says. */
+    maxBatchSize?: number;
+    /** The raw entry, for capabilities this SDK does not model. */
+    raw: WalletCapabilities;
+}
+/**
+ * Turn a wallet's raw answer into per-chain entries.
+ *
+ * Entries that are not objects are dropped rather than coerced: a wallet
+ * answering `null` for a chain has said nothing about it, and inventing an
+ * `"unsupported"` there would be the same mistake as reading absence as denial.
+ */
+declare function normalizeCapabilities(raw: Record<string, unknown> | null | undefined): Record<string, ChainCapabilities>;
+/**
+ * Find the entry for a chain, by CAIP-2 or by the hex form.
+ *
+ * Connectors normalise keys to CAIP-2, but a wallet answering in raw hex
+ * through a custom connector should still be found rather than reported as
+ * "unknown" next to an entry that is sitting right there.
+ */
+declare function selectChainCapabilities(capabilities: Record<string, ChainCapabilities> | null | undefined, chainId: string | null | undefined): ChainCapabilities | null;
+/**
+ * Atomic support for a chain.
+ *
+ * `"unknown"` covers every case where we have not been told: no query yet, a
+ * wallet without the method, a failed query, one still in flight. A caller
+ * choosing between an atomic and a sequential path needs that distinction, not
+ * a confident `false`.
+ */
+declare function atomicSupportFor(capabilities: Record<string, ChainCapabilities> | null | undefined, chainId: string | null | undefined): AtomicSupport;
+
+/**
+ * Solana signer roles, read once for both frameworks.
+ *
+ * `@naculus/connector-solana` splits a connected wallet into `identity`,
+ * `signer` and `payer`, each `null` when the wallet declared it cannot fill
+ * that job. That answer is the connector's. What this module owns is the part
+ * a UI has to decide before it can show anything: *why* there is no answer —
+ * because nothing is connected, because the connected wallet is not Solana,
+ * or because the connector predates the roles API and has not said. Those are
+ * three different screens, and a hook that hands back one `null` for all of
+ * them makes every consumer rediscover the distinction.
+ */
+/** Which account this is, with no ability to sign for it. */
+interface SolanaIdentity {
+    /** Base58 public key. */
+    readonly address: string;
+    /** CAIP-2 chain this account is being used on. */
+    readonly chain: string;
+}
+/** An account that will contribute a signature without submitting anything. */
+interface SolanaSigner extends SolanaIdentity {
+    signMessage?: (message: Uint8Array) => Promise<Uint8Array>;
+    signTransaction: (transaction: Uint8Array) => Promise<Uint8Array>;
+    /** Absent, not throwing, when the wallet has no batch feature. */
+    signAllTransactions?: (transactions: Uint8Array[]) => Promise<Uint8Array[]>;
+}
+/** An account that signs and broadcasts through the wallet's own RPC. */
+interface SolanaPayer extends SolanaIdentity {
+    /** Returns the base58 transaction signature the cluster accepted. */
+    signAndSendTransaction: (transaction: Uint8Array) => Promise<string>;
+}
+/** What the wallet declared, recorded at discovery. Two-state on purpose. */
+interface SolanaWalletFeatures {
+    signMessage: boolean;
+    signTransaction: boolean;
+    signAllTransactions: boolean;
+    signAndSendTransaction: boolean;
+}
+/**
+ * The roles a connected account can fill.
+ *
+ * Structurally identical to `SolanaRoles` in `@naculus/connector-solana`,
+ * declared here rather than imported because this package depends only on
+ * `@naculus/connect-core`, and the connector's own declaration is what its
+ * `getRoles` returns — a value of that type satisfies this one unchanged.
+ */
+interface SolanaRoles {
+    identity: SolanaIdentity;
+    signer: SolanaSigner | null;
+    payer: SolanaPayer | null;
+    features: SolanaWalletFeatures;
+}
+/** The part of a connector this needs. `getRoles` is optional on purpose. */
+interface SolanaRolesSource {
+    getRoles?: (session: unknown) => SolanaRoles | null;
+}
+/** The part of a session this needs. */
+interface SessionLike {
+    walletType?: string;
+}
+/**
+ * Why `roles` is null.
+ *
+ * - `no_session` — nothing connected, or the connector has no live session
+ *   for the one the app holds (a restored session before reconnect).
+ * - `not_solana` — the connected wallet is on another namespace. Not an
+ *   error; a Solana panel simply does not apply.
+ * - `unreported` — the connector does not expose `getRoles`. An older
+ *   `@naculus/connector-solana`, or a custom one. The wallet has not said
+ *   what it can do, which is not the same as saying it can do nothing.
+ */
+type SolanaRolesAbsence = "no_session" | "not_solana" | "unreported";
+type SolanaRolesState = {
+    roles: SolanaRoles;
+    absence: null;
+} | {
+    roles: null;
+    absence: SolanaRolesAbsence;
+};
+/**
+ * Read the roles for the session the app holds.
+ *
+ * Synchronous and pure: the connector already recorded what the wallet
+ * declared, so there is nothing to await and no prompt to trigger. Reading
+ * roles must never cost the user an approval dialog.
+ */
+declare function readSolanaRoles(connector: SolanaRolesSource | null | undefined, session: SessionLike | null | undefined): SolanaRolesState;
+
 /**
  * Which chains a session can actually switch to, and what the current one is.
  *
@@ -282,6 +425,148 @@ declare function getResolver(config?: NameResolverConfig): NameResolver;
 /** Test seam: drop the shared instance. */
 declare function __resetResolverForTests(): void;
 
+/** Framework-neutral in-app notification actions and settings persistence. */
+
+interface NotificationSettingsStorage {
+    getItem<T>(key: string): Promise<T | null>;
+    setItem<T>(key: string, value: T): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+declare const NOTIFICATION_SETTINGS_KEY = "naculus_notif_react_settings";
+declare const DEFAULT_NOTIFICATION_SETTINGS: NotificationSettings;
+/** Preserve the existing localStorage adapter and fail-open UI fallback. */
+declare function createNotificationSettingsStorage(): NotificationSettingsStorage;
+declare function loadNotificationSettings(storage: NotificationSettingsStorage): Promise<NotificationSettings | null>;
+declare function saveNotificationSettings(storage: NotificationSettingsStorage, settings: NotificationSettings): void;
+declare function updateNotificationSettings(current: NotificationSettings, update: Partial<NotificationSettings>): NotificationSettings;
+declare function channelsUpdate(channels: string[]): Partial<NotificationSettings>;
+declare function mutedChainSettings(settings: NotificationSettings, chainId: string, muted: boolean): Partial<NotificationSettings>;
+declare function createNotification(item: Omit<NotificationItem, "id" | "timestamp">): NotificationItem;
+declare function addInAppNotification(channel: InAppChannel, item: Omit<NotificationItem, "id" | "timestamp">): void;
+/** InAppChannel has no remove-one method; preserve its clear/replay behavior. */
+declare function clearOneInAppNotification(channel: InAppChannel, id: string): Promise<NotificationItem[]>;
+
+/**
+ * Destination-address checks shared by the React hook and the Vue composable.
+ *
+ * Syntactic only. `"ok"` means none of these checks found anything wrong —
+ * not that the recipient is who the user thinks. This cannot see an
+ * address-poisoning lookalike, a contract that will not release the funds,
+ * or a known-malicious destination. Labelling that "safe" once put a green
+ * tick beside a scammer's address; the level is deliberately not "safe".
+ */
+type AddressValidationLevel = "ok" | "warning" | "blocked";
+/** Machine-readable reason; the framework layer maps it to a user string. */
+type DestinationIssue = "empty" | "invalid_format" | "zero_address" | "burn_address";
+interface DestinationValidation {
+    isValid: boolean;
+    level: AddressValidationLevel;
+    issue: DestinationIssue | null;
+}
+/**
+ * Burn heuristic kept from the React hook: known sinks plus any well-formed
+ * address containing "dead". Stricter than connect-core's prefix-only
+ * `isBurnAddress`; unifying the two is a connect-lib change.
+ */
+declare function isBurnDestination(address: string): boolean;
+declare function validateDestination(address: string): DestinationValidation;
+/**
+ * The bare `0x…` account from either a CAIP-10 id (`eip155:1:0x…`) or a plain
+ * hex address; null when it is neither. Hooks and composables should not each
+ * carry their own copy of this split.
+ */
+declare function bareEvmAddress(account: string | null | undefined): `0x${string}` | null;
+
+/**
+ * Chain-abstraction (routing) domain types and the few decisions the React
+ * hooks and Vue composables share. The hooks inject the actual quote /
+ * compare / execute functions; nothing here talks to a network.
+ */
+interface RouteQuote {
+    routeId: string;
+    provider: string;
+    netReceiveFormatted: string;
+    toTokenSymbol: string;
+}
+interface RouteQuoteOptions {
+    sortBy?: "cost" | "time" | "balance";
+    maxSlippage?: number;
+}
+interface RouteQuoteInput {
+    fromChain: string;
+    toChain: string;
+    fromToken: string;
+    toToken?: string;
+    amount: string;
+    options?: RouteQuoteOptions;
+}
+type GetRouteQuotes = (from: string, to: string, token: string, amount: string, options?: RouteQuoteOptions, toToken?: string) => Promise<RouteQuote[]>;
+/**
+ * `BigInt()` throws on anything that is not a decimal integer — "1.5", "abc",
+ * "1e18" — so a user typing into an amount field must not reach it. Only a
+ * positive base-unit integer is a quotable amount.
+ */
+declare function isPositiveIntegerAmount(amount: string): boolean;
+/** True when every field a quote needs is present and the amount is quotable. */
+declare function isQuotableInput(input: RouteQuoteInput): boolean;
+interface CostComparison {
+    chain: string;
+    chainName: string;
+    totalCost: string;
+    gasCost: string;
+    estimatedTimeMs: number;
+}
+type CostComparisonOperation = "send_erc20" | "swap" | "bridge" | (string & {});
+interface CostComparisonOptions {
+    amount?: string;
+    token?: string;
+    [key: string]: unknown;
+}
+interface CompareCostsInput {
+    operation: CostComparisonOperation;
+    chains: string[];
+    options?: CostComparisonOptions;
+}
+type CompareCosts = (operation: string, chains: string[], options?: CostComparisonOptions) => Promise<CostComparison[]>;
+/**
+ * Value key for a compare-costs input. `chains` is an array and `options` an
+ * object; keying on identity re-fired the fetch on every render/reactive tick
+ * for a caller writing the natural inline literal — an unbounded loop against
+ * a cost API.
+ */
+declare function compareCostsKey(input: CompareCostsInput): string;
+interface ExecutableQuote {
+    routeId: string;
+    provider: string;
+    totalCost?: bigint;
+    estimatedTimeMs?: number;
+    toChain?: string;
+}
+interface ExecuteRouteResult {
+    fromTxHash: string;
+    toTxHash?: string;
+}
+interface ExecuteRouteOptions {
+    timeoutMs?: number;
+    gasLimit?: bigint;
+}
+interface ExecuteRouteError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type ExecuteRoute = (quote: ExecutableQuote, recipient: string, options?: ExecuteRouteOptions) => Promise<ExecuteRouteResult>;
+/**
+ * Recipient check before a cross-chain execution. An empty recipient is wrong
+ * on every chain. Beyond that the destination namespace decides: when the
+ * quote names `toChain`, the address is validated for that namespace; when it
+ * does not, this returns null and the executor decides, rather than rejecting
+ * a valid non-EVM address on a guess.
+ */
+declare function validateRouteRecipient(quote: ExecutableQuote | null | undefined, recipient: string): ExecuteRouteError | null;
+/** Normalise whatever an executor threw into the hook's error shape. */
+declare function toExecuteRouteError(cause: unknown): ExecuteRouteError;
+
 declare function withTimeout<T>(promise: Promise<T>, ms: number, label?: string): Promise<T>;
 interface RetryOptions {
     maxRetries: number;
@@ -322,4 +607,4 @@ type Web3Action = {
 declare const initialWeb3State: Web3State;
 declare function web3Reducer(state: Web3State, action: Web3Action): Web3State;
 
-export { type ChainInfo, type ConnectionStatus, type DecimalsCache, type RetryOptions, type TokenIdentity, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, chainNamespace, chainNumber, chainsForNamespace, createDecimalsCache, decodeRevertReason, describeChain, eip155ChainIdToNumber, getResolver, initialWeb3State, isEvmChainId, normalizeEip155ChainId, readDecimals, resolveChain, resolveEvmChainId, resolveRevertReason, toChainSwitchError, toEip155Accounts, toViemChain, tokenChainMismatch, tokenKey, web3Reducer, withRetry, withTimeout, writeDecimals };
+export { type AddressValidationLevel, type AtomicSupport, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, type DecimalsCache, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SolanaIdentity, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSigner, type SolanaWalletFeatures, type TokenIdentity, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, atomicSupportFor, bareEvmAddress, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createNotification, createNotificationSettingsStorage, decodeRevertReason, describeChain, eip155ChainIdToNumber, getResolver, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, readDecimals, readSolanaRoles, resolveChain, resolveEvmChainId, resolveRevertReason, saveNotificationSettings, selectChainCapabilities, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };