@coinbase/cdp-core 0.0.97 → 0.0.99

package/dist/types/eip1193/handlers/smart-account/handlePersonalSign.d.ts

@@ -1,3 +1,11 @@
 import { PersonalSignRequest, ProviderStoreInstance } from '../../types.js';
 import { Hex } from 'ox/Hex';
+/**
+ * Handle personal_sign request.
+ * Signs a message using the user's primary account.
+ *
+ * @param params - The parameters array containing [message, address].
+ * @param store - The provider store instance.
+ * @returns The signature of the message.
+ */
 export declare function handlePersonalSign(params: PersonalSignRequest["params"], store: ProviderStoreInstance): Promise<Hex>;

package/dist/types/eip1193/handlers/smart-account/handleRequestAccounts.d.ts

@@ -1,4 +1,14 @@
 import { EventEmitter } from '../../eventEmitter.js';
 import { ProviderStoreInstance } from '../../types.js';
 import { Address } from 'ox/Address';
+/**
+ * Handle eth_requestAccounts request.
+ * This should prompt the user to connect their wallet.
+ * For now, we just return the current accounts.
+ *
+ * @param eventEmitter - The event emitter to emit the connect event on.
+ * @param store - The provider store instance.
+ *
+ * @returns The list of account addresses.
+ */
 export declare function handleRequestAccounts(eventEmitter: EventEmitter, store: ProviderStoreInstance): Promise<Address[]>;

package/dist/types/eip1193/handlers/smart-account/handleSendCalls.d.ts

@@ -1,3 +1,10 @@
 import { ProviderStoreInstance, SendCallsRequest } from '../../types.js';
 import { Hex } from 'ox/Hex';
+/**
+ * Handles sending one or more calls to the specified Ethereum chain
+ *
+ * @param params - provider.request params
+ * @param store - the provider store instance
+ * @returns The user operation hash.
+ */
 export declare function handleSendCalls(params: SendCallsRequest["params"], store: ProviderStoreInstance): Promise<Hex>;

package/dist/types/eip1193/handlers/smart-account/handleSendTransaction.d.ts

@@ -1,4 +1,13 @@
 import { SendTransactionRequest, ProviderStoreInstance } from '../../types.js';
 import { Hex } from 'ox/Hex';
 import { Transport } from 'viem';
+/**
+ * Handle eth_sendTransaction request.
+ * Sends a transaction using the user's primary account.
+ *
+ * @param params - The parameters array containing [transaction].
+ * @param store - The provider store instance.
+ * @param transports - The transports for the provider.
+ * @returns The transaction hash.
+ */
 export declare function handleSendTransaction(params: SendTransactionRequest["params"], store: ProviderStoreInstance, transports: Record<number, Transport>): Promise<Hex>;

package/dist/types/eip1193/handlers/smart-account/handleSignTypedData.d.ts

@@ -1,3 +1,11 @@
 import { ProviderStoreInstance, SignTypedDataRequest } from '../../types.js';
 import { Hex } from 'ox/Hex';
+/**
+ * Handle eth_signTypedData_v4 request.
+ * Signs EIP-712 typed data using the user's primary account.
+ *
+ * @param params - The parameters array containing [address, typedData].
+ * @param store - The provider store instance.
+ * @returns The signature of the typed data.
+ */
 export declare function handleSignTypedData(params: SignTypedDataRequest["params"], store: ProviderStoreInstance): Promise<Hex>;

package/dist/types/eip1193/handlers/types.d.ts

@@ -2,6 +2,9 @@ import { EvmAddress, Hex } from '../../types.js';
 import { EventEmitter } from '../eventEmitter.js';
 import { ProviderStoreInstance, PersonalSignRequest, SendTransactionRequest, SignTypedDataRequest, EthSignRequest, SwitchEthereumChainRequest, SendCallsRequest, GetCallsStatusRequest } from '../types.js';
 import { Transport } from 'viem';
+/**
+ * Interface for all available handler methods
+ */
 export interface ProviderHandlers {
     eth_accounts: () => Promise<EvmAddress[]>;
     eth_requestAccounts: (eventEmitter: EventEmitter, store: ProviderStoreInstance) => Promise<EvmAddress[]>;

package/dist/types/eip1193/types.d.ts

@@ -2,31 +2,68 @@ import { Call, Chain, Transport } from 'viem';
 import { Mutate, StoreApi } from 'zustand';
 import { EvmAddress, Hex, User } from '../types.js';
 import * as ox_Provider from "ox/Provider";
+/**
+ * Config parameters for the CDP embedded wallet 1193 provider.
+ *
+ * Note: The transports are currently only used for non-Base transactions. For non-Base transactions,
+ * the provider internally signs the transaction via the CDP APIs and broadcasts it via the provided
+ * transports, whereas for Base transactions the CDP API both signs and broadcasts the transaction.
+ *
+ * @template chains The tuple of supported chains
+ * @property {chains} chains - The chains to support
+ * @property {Record<chains[number]["id"], Transport>} transports - The transports to use for each chain
+ * @property {boolean} [announceProvider] - Whether to announce the provider to the wallet
+ */
 export type CDPEmbeddedWalletConfig<chains extends readonly [Chain, ...Chain[]] = readonly [Chain, ...Chain[]]> = {
     chains: chains;
     transports: Record<chains[number]["id"], Transport>;
     announceProvider?: boolean;
 };
+/**
+ * EIP-1193 Provider interface - we likely will extend this in the future.
+ */
 export type EIP1193Provider = ox_Provider.Provider;
+/**
+ * A type representing a CDP embedded wallet, for now is just a provider + cleanup function
+ */
 export type CDPEmbeddedWallet = {
     provider: EIP1193Provider;
 };
+/**
+ *
+ */
 export type EIP1193RequestFunctionType = ox_Provider.Provider;
+/**
+ * A request to the eth_accounts method.
+ */
 export type AccountsRequest = {
     method: "eth_accounts";
     params: [];
 };
+/**
+ * A request to the eth_requestAccounts method.
+ */
 export type RequestAccountsRequest = {
     method: "eth_requestAccounts";
     params: [];
 };
+/**
+ * Message type for personal_sign - can be a string or raw format
+ */
 export type PersonalSignMessage = string | {
     raw: `0x${string}` | Uint8Array;
 };
+/**
+ * A request to the personal_sign method.
+ */
 export type PersonalSignRequest = {
     method: "personal_sign";
     params: [PersonalSignMessage, `0x${string}`];
 };
+/**
+ * Transaction parameters for the eth_sendTransaction method.
+ *
+ */
 export type SendTransactionRequestParams = [
     {
         chainId?: `0x${string}`;
@@ -41,32 +78,53 @@ export type SendTransactionRequestParams = [
         type?: "eip1559";
     }
 ];
+/**
+ * A request to the eth_sendTransaction method.
+ */
 export type SendTransactionRequest = {
     method: "eth_sendTransaction";
     params: SendTransactionRequestParams;
 };
+/**
+ * A request to the eth_signTypedData_v4 method.
+ */
 export type SignTypedDataRequest = {
     method: "eth_signTypedData_v4";
     params: [EvmAddress, string];
 };
+/**
+ * A request to the eth_sign method.
+ */
 export type EthSignRequest = {
     method: "eth_sign";
     params: [Hex, EvmAddress];
 };
+/**
+ * A request to the eth_chainId method.
+ */
 export type ChainIdRequest = {
     method: "eth_chainId";
     params: [];
 };
+/**
+ * A request to the disconnect the wallet
+ */
 export type WalletDisconnectRequest = {
     method: "wallet_disconnect";
     params: [];
 };
+/**
+ * A request to switch to the specified Ethereum chain
+ */
 export type SwitchEthereumChainRequest = {
     method: "wallet_switchEthereumChain";
     params: [{
         chainId: string;
     }];
 };
+/**
+ * Capabilities for wallet_sendCalls
+ */
 export type SendCallsCapabilities = {
     [key: string]: unknown;
     paymasterService?: {
@@ -76,6 +134,9 @@ export type SendCallsCapabilities = {
         value: Hex;
     };
 };
+/**
+ * A request to send one or more calls to the specified Ethereum chain
+ */
 export type SendCallsRequest = {
     method: "wallet_sendCalls";
     params: [{
@@ -83,22 +144,43 @@ export type SendCallsRequest = {
         capabilities?: SendCallsCapabilities;
     }];
 };
+/**
+ * A request to get the status of one or more calls
+ */
 export type GetCallsStatusRequest = {
     method: "wallet_getCallsStatus";
     params: [`0x${string}`];
 };
+/**
+ * A request to get the capabilities of the wallet
+ */
 export type GetCapabilitiesRequest = {
     method: "wallet_getCapabilities";
     params: [];
 };
+/**
+ * A request to the EIP-1193 provider that we can't strongly type
+ */
 export type UnknownRequest = {
     method: string;
     params: unknown[];
 };
+/**
+ * A type representing all supported EIP-1193 requests, strongly typed
+ */
 export type ProviderRequest = AccountsRequest | RequestAccountsRequest | PersonalSignRequest | SendTransactionRequest | SignTypedDataRequest | EthSignRequest | ChainIdRequest | WalletDisconnectRequest | SwitchEthereumChainRequest | SendCallsRequest | GetCallsStatusRequest | GetCapabilitiesRequest;
+/**
+ * A type that makes all properties of an object optional.
+ *
+ * @param T - The type to make partial.
+ * @returns The partial type.
+ */
 export type ExactPartial<T> = {
     [P in keyof T]?: T[P] extends object ? ExactPartial<T[P]> : T[P];
 };
+/**
+ * The attributes/methods representing the state of the provider
+ */
 export type ProviderState = {
     chainId: number;
     setChainId: (chainId: number) => void;
@@ -106,18 +188,35 @@ export type ProviderState = {
     user: User | null;
     setUser: (user: User | null) => void;
 };
+/**
+ * The instance of the Zustand provider store
+ */
 export type ProviderStoreInstance = Mutate<StoreApi<ProviderState>, [
     ["zustand/subscribeWithSelector", never],
     ["zustand/persist", ProviderState]
 ]>;
+/**
+ * The capabilities of the wallet by chainId. If the wallet does not support Smart Account operations on a chain, it will not be included in the object.
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-5792#wallet_getcapabilities
+ */
 export type WalletCapabilities = {
     [chainId: Hex]: {
+        /**
+         * Whether the wallet supports atomic transactions
+         */
         atomic: {
             status: "supported" | "unsupported";
         };
+        /**
+         * Whether the wallet supports paymaster services
+         */
         paymasterService: {
             supported: boolean;
         };
+        /**
+         * Whether the wallet supports data suffix for ERC-8021 attribution
+         */
         dataSuffix: {
             supported: boolean;
         };

package/dist/types/errors.d.ts

@@ -1,19 +1,108 @@
+/**
+ * Error thrown when required native modules are not available in the React Native environment.
+ */
 export declare class ModuleResolutionError extends Error {
+    /**
+     * The name of the missing module.
+     */
     moduleName: string;
+    /**
+     * The API or feature that requires the missing module.
+     */
     requiredFor: string;
+    /**
+     * Creates a new ModuleResolutionError.
+     *
+     * @param moduleName - The name of the missing module.
+     * @param requiredFor - The API or feature that requires the module.
+     * @param message - Optional custom error message.
+     */
     constructor(moduleName: string, requiredFor: string, message?: string);
 }
+/**
+ * Error thrown when input validation fails.
+ */
 export declare class InputValidationError extends Error {
+    /**
+     * Creates a new InputValidationError.
+     *
+     * @param message - The validation error message.
+     */
     constructor(message: string);
 }
+/**
+ * Error thrown when validation fails.
+ */
 export declare class ValidationError extends Error {
+    /**
+     * Creates a new ValidationError.
+     *
+     * @param message - The validation error message.
+     */
     constructor(message: string);
 }
+/**
+ * Error thrown when an internal error occurs.
+ */
 export declare class InternalError extends Error {
+    /**
+     * Creates a new InternalError.
+     *
+     * @param message - The internal error message.
+     */
     constructor(message: string);
 }
-export type MfaErrorCode = "SUPERSEDED" | "CANCELLED" | "LISTENER_REQUIRED";
+/**
+ * Error codes for MFA-related errors.
+ */
+export type MfaErrorCode = 
+/** MFA request was replaced by a newer request. */
+"SUPERSEDED"
+/** MFA verification was cancelled. */
+ | "CANCELLED"
+/** No MFA listener is registered to handle verification. */
+ | "LISTENER_REQUIRED";
+/**
+ * Error thrown when an MFA operation fails.
+ */
 export declare class MfaError extends Error {
+    /**
+     * The error code identifying the type of MFA error.
+     */
     code: MfaErrorCode;
+    /**
+     * Creates a new MfaError.
+     *
+     * @param code - The error code identifying the type of MFA error.
+     * @param message - The error message.
+     */
     constructor(code: MfaErrorCode, message: string);
 }
+/**
+ * Error codes for swap-related errors returned by the backend.
+ */
+export type SwapErrorCode = 
+/** No swap route exists for this token pair and amount. */
+"INSUFFICIENT_LIQUIDITY"
+/** Taker has not approved the Permit2 contract to spend fromToken. */
+ | "INSUFFICIENT_ALLOWANCE"
+/** Taker has insufficient fromToken balance. */
+ | "INSUFFICIENT_BALANCE"
+/** Pre-broadcast simulation predicted a revert. */
+ | "TRANSACTION_SIMULATION_FAILED";
+/**
+ * Error thrown when a swap operation fails with a known, actionable reason.
+ */
+export declare class SwapError extends Error {
+    /**
+     * The error code identifying the type of swap failure.
+     */
+    code: SwapErrorCode;
+    /**
+     * Creates a new SwapError.
+     *
+     * @param code - The error code identifying the type of swap failure.
+     * @param message - The error message.
+     */
+    constructor(code: SwapErrorCode, message: string);
+}

package/dist/types/index.d.ts

@@ -18,11 +18,16 @@ export { getEvmEip7702DelegationOperation, type GetEvmEip7702DelegationOperation
 export { EvmEip7702DelegationNetwork } from '@coinbase/cdp-api-client';
 export type { EvmEip7702DelegationOperation } from '@coinbase/cdp-api-client';
 export { waitForEvmEip7702Delegation, type WaitForEvmEip7702DelegationOptions, } from './actions/waitForEvmEip7702Delegation.js';
+export { createDelegation, type CreateDelegationOptions, type CreateDelegationResult, } from './actions/createDelegation.js';
+export { revokeDelegation, type RevokeDelegationOptions } from './actions/revokeDelegation.js';
 export { createSolanaAccount, type CreateSolanaAccountOptions, } from './actions/createSolanaAccount.js';
 export { sendEvmEoaUsdc, type SendEvmEoaUsdcOptions, type SendEvmEoaUsdcResult, } from './actions/sendEvmEoaUsdc.js';
 export { sendEvmSmartAccountUsdc, type SendEvmSmartAccountUsdcOptions, type SendEvmSmartAccountUsdcResult, } from './actions/sendEvmSmartAccountUsdc.js';
 export { sendSolanaUsdc, type SendSolanaUsdcOptions, type SendSolanaUsdcResult, type SendSolanaUsdcNetwork, } from './actions/sendSolanaUsdc.js';
 export { sendUsdc, type SendUsdcOptions, type SendUsdcResult, type SendUsdcNetwork, } from './actions/sendUsdc.js';
+export { getSwapPrice, type GetSwapPriceOptions, type GetSwapPriceResult, type SwapUnavailableResult, type SwapIssues, } from './actions/getSwapPrice.js';
+export { executeSwap, type ExecuteSwapOptions, type ExecuteSwapResult, type ExecuteEvmEoaSwapResult, type ExecuteEvmSmartSwapResult, } from './actions/executeSwap.js';
+export { EvmSwapsNetwork } from '@coinbase/cdp-api-client';
 export { getMfaConfig, type GetMfaConfigResult } from './actions/getMfaConfig.js';
 export { getProjectConfig, type GetProjectConfigResult } from './actions/getProjectConfig.js';
 export { getMfaConfigState, getProjectConfigState } from './state.js';

package/dist/types/index.native.d.ts

@@ -1,3 +1,8 @@
+/**
+ * React Native platform entry point for the CDP Core SDK.
+ * This entry point automatically registers React Native-specific platform services
+ * and re-exports all core functionality.
+ */
 export * from './core.js';
 export { createSpendPermission, type CreateSpendPermissionOptions, type CreateSpendPermissionResult, } from './actions/createSpendPermission.js';
 export { listSpendPermissions, type ListSpendPermissionsOptions, type ListSpendPermissionsResult, } from './actions/listSpendPermissions.js';
@@ -17,11 +22,16 @@ export { getEvmEip7702DelegationOperation, type GetEvmEip7702DelegationOperation
 export { EvmEip7702DelegationNetwork } from '@coinbase/cdp-api-client';
 export type { EvmEip7702DelegationOperation } from '@coinbase/cdp-api-client';
 export { waitForEvmEip7702Delegation, type WaitForEvmEip7702DelegationOptions, } from './actions/waitForEvmEip7702Delegation.js';
+export { createDelegation, type CreateDelegationOptions, type CreateDelegationResult, } from './actions/createDelegation.js';
+export { revokeDelegation, type RevokeDelegationOptions } from './actions/revokeDelegation.js';
 export { createSolanaAccount } from './actions/createSolanaAccount.js';
 export { sendEvmEoaUsdc, type SendEvmEoaUsdcOptions, type SendEvmEoaUsdcResult, } from './actions/sendEvmEoaUsdc.js';
 export { sendEvmSmartAccountUsdc, type SendEvmSmartAccountUsdcOptions, type SendEvmSmartAccountUsdcResult, } from './actions/sendEvmSmartAccountUsdc.js';
 export { sendSolanaUsdc, type SendSolanaUsdcOptions, type SendSolanaUsdcResult, type SendSolanaUsdcNetwork, } from './actions/sendSolanaUsdc.js';
 export { sendUsdc, type SendUsdcOptions, type SendUsdcResult, type SendUsdcNetwork, } from './actions/sendUsdc.js';
+export { getSwapPrice, type GetSwapPriceOptions, type GetSwapPriceResult, type SwapUnavailableResult, type SwapIssues, } from './actions/getSwapPrice.js';
+export { executeSwap, type ExecuteSwapOptions, type ExecuteSwapResult, type ExecuteEvmEoaSwapResult, type ExecuteEvmSmartSwapResult, } from './actions/executeSwap.js';
+export { EvmSwapsNetwork } from '@coinbase/cdp-api-client';
 export { getMfaConfig, type GetMfaConfigResult } from './actions/getMfaConfig.js';
 export { getProjectConfig, type GetProjectConfigResult } from './actions/getProjectConfig.js';
 export { getMfaConfigState, getProjectConfigState } from './state.js';
@@ -46,4 +56,5 @@ export { getConfig } from './state.js';
 export { toTransactionSigner } from './solana-kit/toTransactionSigner.js';
 export { registerAttestationModule, type NativeAttestationModule, } from './platform/native/attestationRegistry.js';
 export { registerAppleAuthProvider, type AppleAuthProvider, } from './platform/native/appleAuthRegistry.js';
+export { registerDeviceInfoModule, type NativeDeviceInfoModule, } from './platform/native/deviceInfoRegistry.js';
 export { type AppleNativeCredential } from './platform/types.js';

package/dist/types/index.web.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Web platform entry point for the CDP Core SDK.
+ * This entry point automatically registers web-specific platform services
+ * and re-exports all core functionality.
+ */
 export * from './core.js';
 export { createSpendPermission, type CreateSpendPermissionOptions, type CreateSpendPermissionResult, } from './actions/createSpendPermission.js';
 export { listSpendPermissions, type ListSpendPermissionsOptions, type ListSpendPermissionsResult, } from './actions/listSpendPermissions.js';
@@ -17,11 +22,16 @@ export { getEvmEip7702DelegationOperation, type GetEvmEip7702DelegationOperation
 export { EvmEip7702DelegationNetwork } from '@coinbase/cdp-api-client';
 export type { EvmEip7702DelegationOperation } from '@coinbase/cdp-api-client';
 export { waitForEvmEip7702Delegation, type WaitForEvmEip7702DelegationOptions, } from './actions/waitForEvmEip7702Delegation.js';
+export { createDelegation, type CreateDelegationOptions, type CreateDelegationResult, } from './actions/createDelegation.js';
+export { revokeDelegation, type RevokeDelegationOptions } from './actions/revokeDelegation.js';
 export { createSolanaAccount } from './actions/createSolanaAccount.js';
 export { sendEvmEoaUsdc, type SendEvmEoaUsdcOptions, type SendEvmEoaUsdcResult, } from './actions/sendEvmEoaUsdc.js';
 export { sendEvmSmartAccountUsdc, type SendEvmSmartAccountUsdcOptions, type SendEvmSmartAccountUsdcResult, } from './actions/sendEvmSmartAccountUsdc.js';
 export { sendSolanaUsdc, type SendSolanaUsdcOptions, type SendSolanaUsdcResult, type SendSolanaUsdcNetwork, } from './actions/sendSolanaUsdc.js';
 export { sendUsdc, type SendUsdcOptions, type SendUsdcResult, type SendUsdcNetwork, } from './actions/sendUsdc.js';
+export { getSwapPrice, type GetSwapPriceOptions, type GetSwapPriceResult, type SwapUnavailableResult, type SwapIssues, } from './actions/getSwapPrice.js';
+export { executeSwap, type ExecuteSwapOptions, type ExecuteSwapResult, type ExecuteEvmEoaSwapResult, type ExecuteEvmSmartSwapResult, } from './actions/executeSwap.js';
+export { EvmSwapsNetwork } from '@coinbase/cdp-api-client';
 export { getMfaConfig, type GetMfaConfigResult } from './actions/getMfaConfig.js';
 export { getProjectConfig, type GetProjectConfigResult } from './actions/getProjectConfig.js';
 export { getMfaConfigState, getProjectConfigState } from './state.js';

package/dist/types/mfa/protectedActions.d.ts

@@ -1,5 +1,11 @@
 import { createEvmKeyExportIframe, createSolanaKeyExportIframe } from '../actions/createKeyExportIframe.js';
 import { SignEvmHashOptions, SignEvmHashResult, SignEvmTransactionOptions, SignEvmTransactionResult, SignSolanaTransactionOptions, SignSolanaTransactionResult, SendEvmTransactionOptions, SendEvmTransactionResult, SendSolanaTransactionOptions, SendSolanaTransactionResult, SignEvmMessageOptions, SignSolanaMessageOptions, SignSolanaMessageResult, SignEvmTypedDataOptions, SignEvmTypedDataResult, SendUserOperationOptions, SendUserOperationResult, ExportEvmAccountOptions, ExportEvmAccountResult, ExportSolanaAccountOptions, ExportSolanaAccountResult } from '../types.js';
+/**
+ * Map of MFA-protected functions to ensure type safety.
+ * If a function is renamed, the import will fail and this file won't compile.
+ *
+ * @internal
+ */
 export declare const MFA_PROTECTED_FUNCTIONS: {
     readonly signEvmHash: (options: SignEvmHashOptions) => Promise< SignEvmHashResult>;
     readonly signEvmTransaction: (options: SignEvmTransactionOptions) => Promise< SignEvmTransactionResult>;
@@ -15,6 +21,41 @@ export declare const MFA_PROTECTED_FUNCTIONS: {
     readonly createEvmKeyExportIframe: typeof createEvmKeyExportIframe;
     readonly createSolanaKeyExportIframe: typeof createSolanaKeyExportIframe;
 };
+/**
+ * List of action names that require MFA verification when the user is enrolled.
+ *
+ * These actions involve sensitive operations like signing transactions,
+ * sending funds, or exporting private keys.
+ *
+ * @example
+ * ```typescript
+ * import { MFA_PROTECTED_ACTIONS } from '@coinbase/cdp-core';
+ *
+ * console.log(MFA_PROTECTED_ACTIONS);
+ * // ['signEvmHash', 'signEvmTransaction', 'signSolanaTransaction', ...]
+ * ```
+ */
 export declare const MFA_PROTECTED_ACTIONS: MfaProtectedAction[];
+/**
+ * Type representing the name of an MFA-protected action.
+ */
 export type MfaProtectedAction = keyof typeof MFA_PROTECTED_FUNCTIONS;
+/**
+ * Checks if an action name is MFA-protected.
+ *
+ * MFA-protected actions require MFA verification when the user is enrolled in MFA.
+ * Use this to show visual indicators (like a lock icon) on sensitive action buttons.
+ *
+ * @param actionName - The name of the action to check.
+ * @returns True if the action requires MFA when the user is enrolled.
+ *
+ * @example
+ * ```typescript
+ * import { isMfaProtectedAction } from '@coinbase/cdp-core';
+ *
+ * if (isMfaProtectedAction('signEvmTransaction')) {
+ *   // Show lock icon on button
+ * }
+ * ```
+ */
 export declare function isMfaProtectedAction(actionName: string): actionName is MfaProtectedAction;

package/dist/types/mfa/state.d.ts

@@ -1,15 +1,110 @@
 import { MfaMethod } from '@coinbase/cdp-api-client';
+/**
+ * Context passed to the MFA verification handler when MFA is required.
+ */
 export type MfaVerificationContext = {
+    /** The MFA methods the user has enrolled in. */
     methods: MfaMethod[];
 };
+/**
+ * Listener function called when MFA verification is required.
+ * The consumer should show their custom MFA UI and call initiateMfaVerification/submitMfaVerification.
+ */
 export type MfaListener = (context: MfaVerificationContext) => void;
+/**
+ * Options for registering an MFA listener.
+ */
 export type MfaListenerOptions = {
+    /**
+     * Optional DOM element that defines the scope for this handler.
+     * When provided, this handler will only respond to MFA triggers
+     * that originate from within this element (e.g., button clicks inside a container).
+     * Handlers without a scope act as global handlers.
+     */
     scope?: HTMLElement;
 };
+/**
+ * Registers an MFA verification listener.
+ *
+ * Listeners can be global (no scope) or scoped to a specific DOM element.
+ * The event bubbles up from the trigger element through the DOM:
+ * - Scoped listeners listen on their container and catch events from within
+ * - Global listeners listen on document and catch anything that bubbles up
+ *
+ * @param {MfaListener} listener - The listener function to call when MFA is required.
+ * @param {MfaListenerOptions} [options] - Optional configuration including scope element.
+ * @returns {() => void} A function to unregister the listener.
+ *
+ * @example
+ * ```typescript
+ * // Global listener (responds to any MFA trigger not handled by a scoped listener)
+ * const unregisterGlobal = registerMfaListener(({ methods }) => {
+ *   openMfaModal(methods);
+ * });
+ *
+ * // Scoped listener (only responds to triggers inside the container)
+ * const container = document.getElementById('my-flow');
+ * if (container) {
+ *   const unregisterScoped = registerMfaListener(
+ *     ({ methods }) => showInlineMfa(methods),
+ *     { scope: container }
+ *   );
+ *   // Later, when done:
+ *   unregisterScoped();
+ * }
+ *
+ * // Clean up global listener when done:
+ * unregisterGlobal();
+ * ```
+ */
 export declare const registerMfaListener: (listener: MfaListener, options?: MfaListenerOptions) => (() => void);
+/**
+ * Checks if any MFA listeners are registered.
+ *
+ * @returns {boolean} True if at least one listener is registered, false otherwise.
+ */
 export declare const hasRegisteredMfaListeners: () => boolean;
+/**
+ * Triggers the MFA verification flow and returns a Promise that resolves
+ * when MFA is successfully completed.
+ *
+ * Dispatches a custom DOM event from the trigger element that bubbles up.
+ * Scoped handlers catch events from within their container.
+ * Global handlers catch anything that bubbles to document.
+ *
+ * If no handlers are registered, this is a no-op and resolves immediately.
+ * Use `hasRegisteredMfaListeners()` to check before calling if needed.
+ *
+ * @param {MfaMethod[]} methods - The MFA methods available for verification.
+ * @returns {Promise<void>} A Promise that resolves when MFA is complete.
+ * @internal
+ */
 export declare const triggerMfaVerification: (methods: MfaMethod[]) => Promise<void>;
+/**
+ * Resolves the pending MFA verification Promise.
+ * Called internally after successful MFA submission.
+ *
+ * @internal
+ */
 export declare const resolvePendingMfaVerification: () => void;
+/**
+ * Rejects the pending MFA verification Promise.
+ * Called when the user cancels MFA or an error occurs.
+ *
+ * @param error - The error to reject the pending MFA verification with.
+ * @internal
+ */
 export declare const rejectPendingMfaVerification: (error: Error) => void;
+/**
+ * Checks if there's a pending MFA verification.
+ *
+ * @returns {boolean} True if there's a pending MFA verification, false otherwise.
+ * @internal
+ */
 export declare const hasPendingMfaVerification: () => boolean;
+/**
+ * Resets all MFA state. This is primarily used for testing.
+ *
+ * @internal
+ */
 export declare const resetMfaState: () => void;