@coinbase/cdp-core 0.0.97 → 0.0.99

package/dist/native-types/auth/authManager.d.ts

@@ -1,5 +1,9 @@
 import { AuthState, IAuthManager, WalletSecret } from './types.js';
 import { OnAuthStateChangeFn, User } from '../types.js';
+/**
+ * Manages the authentication state and access token for standard CDP authentication
+ * (email/SMS/OAuth flows).
+ */
 export declare class AuthManager implements IAuthManager {
     protected projectId: string;
     protected authState: AuthState | null;
@@ -7,31 +11,142 @@ export declare class AuthManager implements IAuthManager {
     protected authStateChangeCallbacks: OnAuthStateChangeFn[];
     protected initPromise: Promise<void> | null;
     protected refreshTimeout: ReturnType<typeof setTimeout> | null;
+    private refreshWalletSecretPromise;
+    /**
+     * Initializes the token manager.
+     *
+     * @param projectId - The project ID.
+     */
     constructor(projectId: string);
+    /**
+     * Gets the current user, or null if there is no user signed in.
+     *
+     * @returns The current user.
+     */
     getUser(): User | null;
+    /**
+     * Returns whether the user is signed in - i.e., whether there is an unexpired
+     * access token and user. Attempts to refresh the token if it's expired.
+     *
+     * @returns True if the user is signed in, false otherwise.
+     */
     isSignedIn(): Promise<boolean>;
+    /**
+     * Signs out the user, clearing all authentication state.
+     */
     signOut(): Promise<void>;
+    /**
+     * Adds a callback to be called when the auth state changes.
+     *
+     * @param callback - The function to call when the auth state changes.
+     */
     addAuthStateChangeCallback(callback: OnAuthStateChangeFn): void;
+    /**
+     * Gets the access token, refreshing it if it is expired. Returns null if the user is not
+     * signed in.
+     *
+     * @param options - The options for getting the token.
+     * @param options.forceRefresh - Whether to force a refresh of the token.
+     * @returns The access token.
+     */
     getToken(options?: {
         forceRefresh?: boolean;
     }): Promise<string | null>;
+    /**
+     * Gets the expiration time of the access token, or null if the user is not signed in.
+     *
+     * @returns The expiration time of the access token.
+     */
     getTokenExpiration(): Promise<number | null>;
+    /**
+     * Gets the currently registered wallet secret ID. Rejects if the user is not signed in.
+     *
+     * @returns The wallet secret ID.
+     */
     getWalletSecretId(): Promise<string>;
+    /**
+     * Gets the X-Wallet-Auth header. Rejects if the user is not signed in.
+     *
+     * @param options - The options for the request.
+     * @param options.requestMethod - The HTTP method of the request.
+     * @param options.requestHost - The host of the request.
+     * @param options.requestPath - The path of the request.
+     * @param options.requestData - The data of the request.
+     * @returns The X-Wallet-Auth header.
+     */
     getXWalletAuth(options: {
         requestMethod: string;
         requestHost: string;
         requestPath: string;
         requestData?: Record<string, unknown>;
     }): Promise<string>;
+    /**
+     * Gets the authentication state.
+     *
+     * @returns The authentication state.
+     */
     getAuthState(): AuthState | null;
+    /**
+     * Sets the authentication state.
+     *
+     * @param authState - The authentication state.
+     */
     setAuthState(authState: AuthState): Promise<void>;
+    /**
+     * Clears the authentication state.
+     */
     clearAuthState(): Promise<void>;
+    /**
+     * Ensures the AuthManager is initialized before proceeding.
+     * If initialization is already in progress, waits for it to complete.
+     */
     ensureInitialized(): Promise<void>;
+    /**
+     * Internal async initialization logic.
+     */
     protected _doInitialize(): Promise<void>;
+    /**
+     * Returns whether the token should be refreshed.
+     *
+     * @returns True if the token should be refreshed, false otherwise.
+     */
     protected shouldRefreshToken(): boolean;
+    /**
+     * Refreshes the access token and transitions the auth state accordingly.
+     * If a refresh is already in progress, it will wait for that refresh to complete.
+     * Retries with exponential backoff on transient failures only. Unauthorized error
+     * short-circuit immediately since retrying won't help.
+     *
+     * @param trigger - The trigger for the refresh.
+     *
+     * @returns The new access token.
+     */
     protected refreshAccessToken(trigger?: string): Promise<void>;
+    /**
+     * Schedules a token refresh to occur exactly when shouldRefreshToken() would return true.
+     * Uses the same REFRESH_CREDENTIALS_BUFFER_MS timing as the rest of the auth system.
+     */
     protected scheduleTokenRefresh(): void;
+    /**
+     * Cancels any scheduled token refresh.
+     */
     protected cancelTokenRefresh(): void;
+    /**
+     * Returns whether the wallet secret should be refreshed.
+     *
+     * @returns True if the wallet secret should be refreshed, false otherwise.
+     */
     private shouldRefreshWalletSecret;
+    /**
+     * Refreshes the wallet secret. Assumes the user is signed in.
+     * Concurrent callers share the same in-flight registration to avoid
+     * racing on `this.walletSecret` (e.g. React Strict Mode double-fire).
+     *
+     * @returns A promise that resolves when the wallet secret is registered.
+     */
     private refreshWalletSecret;
+    /**
+     * Internal wallet secret refresh logic.
+     */
+    private _doRefreshWalletSecret;
 }

package/dist/native-types/auth/createAuthManager.d.ts

@@ -1,2 +1,11 @@
 import { IAuthManager } from './types.js';
+/**
+ * Creates the appropriate AuthManager instance based on the configuration.
+ *
+ * - If customAuth.getJwt is provided, returns a CustomAuthManager
+ * - Otherwise, returns an AuthManager for standard CDP authentication
+ *
+ * @param projectId - The project ID.
+ * @returns The appropriate AuthManager instance.
+ */
 export declare function createAuthManager(projectId: string): IAuthManager;

package/dist/native-types/auth/customAuthManager.d.ts

@@ -1,10 +1,56 @@
 import { AuthManager } from './authManager.js';
+/**
+ * The number of milliseconds before the expiration time of credentials
+ * that we should refresh the credentials for custom auth.
+ * This can be any number as long as it's some time in the future
+ * to prevent the wallet secret from being infinitely refreshed.
+ * We use 1 hour as a reasonable default.
+ */
 export declare const CUSTOM_AUTH_REFRESH_BUFFER_MS: number;
+/**
+ * AuthManager for custom authentication flows where JWTs are provided
+ * by an external identity provider via the customAuth.getJwt callback.
+ *
+ * This manager extends AuthManager and overrides key methods to:
+ * - Skip automatic token refresh (tokens are always fresh from the callback)
+ * - Fetch fresh JWTs on each getToken() call via customAuth.getJwt
+ * - Disable scheduled token refresh (not needed for custom auth)
+ */
 export declare class CustomAuthManager extends AuthManager {
+    /**
+     * Signs out the user, clearing all authentication state.
+     * For custom auth, we only clear local state without calling the CDP logout API,
+     * as authentication is managed by the external identity provider.
+     */
     signOut(): Promise<void>;
+    /**
+     * Gets the access token by calling the customAuth.getJwt callback.
+     * Returns null if the user is not signed in.
+     *
+     * @returns The access token from the custom auth provider.
+     */
     getToken(): Promise<string | null>;
+    /**
+     * Internal async initialization logic for custom auth.
+     * No-op for custom auth since tokens are provided via customAuth.getJwt callback.
+     * Unlike standard CDP auth, custom auth doesn't need token refresh or OAuth handling.
+     */
     protected _doInitialize(): Promise<void>;
+    /**
+     * Custom auth always fetches fresh tokens, so never needs to "refresh" in the traditional sense.
+     *
+     * @returns Always false since custom auth doesn't use token refresh logic.
+     */
     protected shouldRefreshToken(): boolean;
+    /**
+     * Custom auth doesn't use CDP's token refresh mechanism.
+     * Tokens are always provided fresh from the customAuth.getJwt callback.
+     * This method should never be called, but we override it as a defensive measure.
+     */
     protected refreshAccessToken(): Promise<void>;
+    /**
+     * Custom auth provides fresh tokens on each request via customAuth.getJwt,
+     * so no scheduled refresh is needed. This method is a no-op for custom auth.
+     */
     protected scheduleTokenRefresh(): void;
 }

package/dist/native-types/auth/oAuthManager.d.ts

@@ -1,11 +1,39 @@
 import { OAuthFlowState, OnOAuthStateChangeFn } from '../types.js';
 import { IOAuthManager } from './types.js';
+/**
+ * Manages the OAuth flow state and related callbacks.
+ */
 export declare class OAuthManager implements IOAuthManager {
     private oauthFlowState;
     private oauthStateChangeCallbacks;
+    /**
+     * Adds a callback to be called when the OAuth state changes.
+     *
+     * @param callback - The function to call when the OAuth state changes.
+     */
     addOAuthStateChangeCallback(callback: OnOAuthStateChangeFn): Promise<void>;
+    /**
+     * Sets the OAuth flow state.
+     *
+     * @param oauthFlowState - The OAuth flow state.
+     */
     setOAuthFlowState(oauthFlowState: OAuthFlowState): Promise<void>;
+    /**
+     * Clears the OAuth flow state.
+     */
     clearOAuthFlowState(): Promise<void>;
+    /**
+     * Gets the OAuth flow state.
+     *
+     * @returns The OAuth flow state.
+     */
     getOAuthFlowState(): Promise<OAuthFlowState | null>;
+    /**
+     * Handles the OAuth code.
+     *
+     * @param url - The URL to handle.
+     * @returns A promise that resolves when the OAuth code is handled.
+     * @throws An error if the URL is required and not provided.
+     */
     handleOAuthCode(url?: string): Promise<void>;
 }

package/dist/native-types/auth/toAuthState.d.ts

@@ -1,6 +1,13 @@
 import { EndUser, EndUserEvmAccount, EndUserEvmSmartAccount, EndUserSolanaAccount, MFAMethods } from '@coinbase/cdp-api-client';
 import { AuthState } from './types.js';
 import { AuthenticationMethods } from '../types.js';
+/**
+ * Transforms an EndUser object from the API into a User object for internal state.
+ * Converts the authentication methods array into a keyed object for easier access.
+ *
+ * @param endUser - The EndUser object from the API response.
+ * @returns The User object for internal state management.
+ */
 export declare const toAuthStateUser: (endUser: EndUser) => {
     userId: string;
     evmAccounts: `0x${string}`[];
@@ -13,4 +20,12 @@ export declare const toAuthStateUser: (endUser: EndUser) => {
     mfaMethods: MFAMethods | undefined;
     lastAuthenticatedAt: string | undefined;
 };
+/**
+ * Returns an AuthState object from the given inputs.
+ *
+ * @param accessToken - The access token
+ * @param expiresAt - The date and time at which the refreshed access token will expire in ISO 8601 format.
+ * @param endUser - The authenticated end user
+ * @returns The AuthState object.
+ */
 export declare const toAuthState: (accessToken: string, expiresAt: string, endUser: EndUser) => AuthState;

package/dist/native-types/auth/types.d.ts

@@ -1,40 +1,121 @@
 import { KeyPair } from '../shared/types.js';
 import { OAuthFlowState, OnAuthStateChangeFn, OnOAuthStateChangeFn, User } from '../types.js';
+/**
+ * The encapsulation of an authentication state.
+ */
 export interface AuthState {
+    /**
+     * The access token.
+     */
     accessToken: string;
+    /**
+     * The Unix timestamp, in milliseconds, of the expiration date of the access token.
+     */
     expiresAt: number;
+    /**
+     * The authenticated user.
+     */
     user: User;
 }
+/**
+ * A temporary wallet secret.
+ */
 export interface WalletSecret {
+    /** The wallet secret ID. */
     walletSecretId: string;
+    /** The underlying key pair. */
     keyPair: KeyPair;
+    /** The Unix timestamp, in milliseconds, of the expiration date of the wallet secret. */
     expiresAt: number;
 }
+/**
+ * Interface for OAuth manager implementations.
+ */
 export interface IOAuthManager {
+    /**
+     * Gets the OAuth flow state.
+     */
     getOAuthFlowState(): Promise<OAuthFlowState | null>;
+    /**
+     * Sets the OAuth flow state.
+     */
     setOAuthFlowState(oauthFlowState: OAuthFlowState): Promise<void>;
+    /**
+     * Adds a callback to be called when the OAuth state changes.
+     */
     addOAuthStateChangeCallback(callback: OnOAuthStateChangeFn): Promise<void>;
+    /**
+     * Clears the OAuth flow state.
+     */
     clearOAuthFlowState(): Promise<void>;
+    /**
+     * Awaitable method whose promise only resolves when the OAuth manager is ready to be used.
+     */
     handleOAuthCode(url?: string): Promise<void>;
 }
+/**
+ * Interface for auth manager implementations.
+ * Defines the public contract that both real and mock implementations must satisfy.
+ */
 export interface IAuthManager {
+    /**
+     * Gets the current user, or null if there is no user signed in.
+     */
     getUser(): User | null;
+    /**
+     * Returns whether the user is signed in.
+     */
     isSignedIn(): Promise<boolean>;
+    /**
+     * Signs out the user, clearing all authentication state.
+     */
     signOut(): Promise<void>;
+    /**
+     * Adds a callback to be called when the auth state changes.
+     */
     addAuthStateChangeCallback(callback: OnAuthStateChangeFn): void;
+    /**
+     * Gets the access token, refreshing if needed, or null if the user is not signed in.
+     *
+     * @param options - The options for getting the token.
+     * @param options.forceRefresh - Whether to force a refresh of the token.
+     */
     getToken(options?: {
         forceRefresh?: boolean;
     }): Promise<string | null>;
+    /**
+     * Gets the expiration time of the access token, or null if the user is not signed in.
+     */
     getTokenExpiration(): Promise<number | null>;
+    /**
+     * Gets the currently registered wallet secret ID, refreshing if needed.
+     *
+     * @returns The wallet secret ID.
+     */
     getWalletSecretId(): Promise<string>;
+    /**
+     * Gets the X-Wallet-Auth header value. Throws an error if the user is not signed in.
+     */
     getXWalletAuth(options: {
         requestMethod: string;
         requestHost: string;
         requestPath: string;
         requestData?: Record<string, unknown>;
     }): Promise<string>;
+    /**
+     * Gets the authentication state.
+     */
     getAuthState(): AuthState | null;
+    /**
+     * Sets the authentication state.
+     */
     setAuthState(authState: AuthState): Promise<void>;
+    /**
+     * Clears the authentication state.
+     */
     clearAuthState(): Promise<void>;
+    /**
+     * Awaitable method whose promise only resolves when the auth manager is ready to be used.
+     */
     ensureInitialized(): Promise<void>;
 }

package/dist/native-types/auth/withAuth.d.ts

@@ -1,10 +1,24 @@
 import { EvmAddress, SolanaAddress, User } from '../types.js';
 import { IAuthManager } from './types.js';
+/**
+ * Returns whether the user is currently signed in.
+ *
+ * @param authManager - The authentication manager.
+ * @returns Whether the user is currently signed in.
+ */
 export declare const isSignedIn: (authManager: IAuthManager) => Promise<boolean>;
 type AuthenticatedFunction<T, R> = (params: T & {
     user: User;
     walletSecretId: string;
 }) => Promise<R>;
+/**
+ * Wraps a function with authentication checks.
+ *
+ * @param options - The options for the function.
+ * @param authManager - The authentication manager.
+ * @param fn - The function to wrap.
+ * @returns The result of the function.
+ */
 export declare function withAuth<T, R>(options: T & ({
     evmAccount: EvmAddress;
 } | {

package/dist/native-types/constants.d.ts

@@ -1 +1,4 @@
+/**
+ * The URL to the Coinbase Developer Platform API error documentation page.
+ */
 export declare const ERROR_DOCS_PAGE_URL = "https://docs.cdp.coinbase.com/api-v2/docs/errors";

package/dist/native-types/eip1193/createCDPEmbeddedWallet.d.ts

@@ -1,3 +1,78 @@
 import { Chain } from 'viem/chains';
 import { CDPEmbeddedWallet, CDPEmbeddedWalletConfig } from './types.js';
+/**
+ * Creates the CDP embedded wallet's 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.
+ * For more information on transports, see [Wagmi's `createConfig` setup](https://wagmi.sh/react/api/createConfig).
+ *
+ * @param _parameters - Configuration parameters for the connector - see {@link CDPEmbeddedWalletConfig}
+ * @returns A CDP embedded wallet instance
+ *
+ * @example
+ * ```typescript lines
+ * import { createCDPEmbeddedWallet, initialize } from "@coinbase/cdp-core";
+ * import { http } from "viem";
+ * import { baseSepolia, sepolia } from "viem/chains";
+ *
+ * // SDK core must be initialized before creating the wallet
+ * await initialize({
+ *   projectId: "your-project-id"
+ * })
+ *
+ * // Create a wallet with multiple chains
+ * const wallet = createCDPEmbeddedWallet({
+ *   chains: [baseSepolia, sepolia],
+ *   transports: {
+ *     [baseSepolia.id]: http(),
+ *     [sepolia.id]: http(),
+ *   },
+ *   announceProvider: true, // Announce the provider to window.ethereum
+ * });
+ *
+ * // The provider can be accessed via the provider property
+ * const provider = wallet.provider;
+ *
+ * // The provider implements the EIP-1193 interface
+ * await provider.request({ method: "eth_requestAccounts" });
+ * ```
+ * @example
+ * ```typescript lines
+ * // Basic usage with default configuration
+ * const wallet = createCDPEmbeddedWallet();
+ * const provider = wallet.provider;
+ *
+ * // Request account access
+ * const accounts = await provider.request({
+ *   method: "eth_requestAccounts"
+ * });
+ *
+ * // Sign a message
+ * const signature = await provider.request({
+ *   method: "personal_sign",
+ *   params: ["Hello, World!", accounts[0]]
+ * });
+ *
+ * // Send a transaction
+ * const txHash = await provider.request({
+ *   method: "eth_sendTransaction",
+ *   params: [{
+ *     from: accounts[0],
+ *     to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
+ *     value: "0x1000000000000000000" // 1 ETH
+ *   }]
+ * });
+ *
+ * // Listen for connection events
+ * provider.on("connect", (connectInfo) => {
+ *   console.log("Connected to chain:", connectInfo.chainId);
+ * });
+ *
+ * provider.on("disconnect", () => {
+ *   console.log("Disconnected from wallet");
+ * });
+ * ```
+ */
 export declare function createCDPEmbeddedWallet<chains extends readonly [Chain, ...Chain[]]>(_parameters: CDPEmbeddedWalletConfig<chains>): CDPEmbeddedWallet;

package/dist/native-types/eip1193/createProvider.d.ts

@@ -1,3 +1,42 @@
 import { EventEmitter } from './eventEmitter.js';
 import { EIP1193Provider, CDPEmbeddedWalletConfig, ProviderStoreInstance } from './types.js';
+/**
+ * Creates an EIP-1193 compatible Ethereum provider for CDP embedded wallets.
+ * This provider wraps the CDP core functionality and provides a standard
+ * Ethereum wallet interface.
+ *
+ * @param eventEmitter - The event emitter to use for provider events
+ * @param store - The Zustand store to use for provider state
+ * @param config - The configuration for this instance of the Provider
+ * @param config.chains - Valid chains for this provider instance
+ * @param config.transports - The RPC transports to use for each chain
+ * @returns An EIP-1193 provider instance
+ * @example
+ * ```typescript lines
+ * import { EventEmitter } from "./eventEmitter.js";
+ * import { create } from "zustand";
+ * import { baseSepolia } from "viem/chains";
+ *
+ * // Create event emitter and store
+ * const eventEmitter = new EventEmitter();
+ * const store = create<ProviderState>()(/* store configuration *\/);
+ *
+ * // Create the provider
+ * const provider = createProvider(eventEmitter, store, {
+ *   chains: [baseSepolia],
+ * });
+ *
+ * // Use the provider
+ * await provider.request({ method: "eth_requestAccounts" });
+ *
+ * // Listen for events
+ * provider.on("connect", (connectInfo) => {
+ *   console.log("Connected to chain:", connectInfo.chainId);
+ * });
+ *
+ * provider.on("chainChanged", (chainId) => {
+ *   console.log("Chain changed to:", chainId);
+ * });
+ * ```
+ */
 export declare function createProvider(eventEmitter: EventEmitter, store: ProviderStoreInstance, config: Pick<CDPEmbeddedWalletConfig, "chains" | "transports">): EIP1193Provider;