@coinbase/cdp-core 0.0.97 → 0.0.99

package/dist/types/actions/signInWithSms.d.ts

@@ -1,2 +1,14 @@
 import { SignInWithSmsOptions, SignInWithSmsResult } from '../types.js';
+/**
+ * Initiates the sign in flow with a phone number via SMS.
+ *
+ * @param options - The options for the sign in.
+ * @example
+ * ```typescript lines
+ * const result = await signInWithSms({
+ *   phoneNumber: "+14155552671"
+ * });
+ * ```
+ * @returns The result of the sign in.
+ */
 export declare const signInWithSms: (options: SignInWithSmsOptions) => Promise<SignInWithSmsResult>;

package/dist/types/actions/signOut.d.ts

@@ -1 +1,9 @@
+/**
+ * Signs out the end user, clearing all authentication state.
+ *
+ * @example
+ * ```typescript lines
+ * await signOut();
+ * ```
+ */
 export declare const signOut: () => Promise<void>;

package/dist/types/actions/signSolanaMessage.d.ts

@@ -1,2 +1,22 @@
 import { SignSolanaMessageOptions, SignSolanaMessageResult } from '../types.js';
+/**
+ * Signs a message with a Solana account.
+ *
+ * @param options - The options for the signing.
+ * @param options.solanaAccount - The Solana account to sign the message with. Found on the user object of the signed in user.
+ * @param options.message - The message to sign (base64 encoded).
+ * @example
+ * ```typescript lines
+ * const user = await getCurrentUser();
+ * const solanaAccount = user?.solanaAccountObjects[0]?.address;
+ *
+ * const message = Buffer.from("Hello, Solana!", "utf8").toString("base64");
+ * const result = await signSolanaMessage({
+ *   solanaAccount,
+ *   message // Base64 encoded message to sign
+ * });
+ *
+ * ```
+ * @returns The result of the signing.
+ */
 export declare const signSolanaMessage: (options: SignSolanaMessageOptions) => Promise<SignSolanaMessageResult>;

package/dist/types/actions/signSolanaTransaction.d.ts

@@ -1,2 +1,20 @@
 import { SignSolanaTransactionOptions, SignSolanaTransactionResult } from '../types.js';
+/**
+ * Signs a Solana transaction.
+ *
+ * @param options - The options for the signing.
+ * @param options.solanaAccount - The Solana account to sign the transaction with. Found on the user object of the signed in user.
+ * @param options.transaction - The base64 encoded transaction to sign.
+ * @example
+ * ```typescript lines
+ * const user = await getCurrentUser();
+ * const solanaAccount = user?.solanaAccountObjects[0]?.address;
+ *
+ * const result = await signSolanaTransaction({
+ *   solanaAccount,
+ *   transaction: "base64-encoded-transaction"
+ * });
+ * ```
+ * @returns The result of the signing.
+ */
 export declare const signSolanaTransaction: (options: SignSolanaTransactionOptions) => Promise<SignSolanaTransactionResult>;

package/dist/types/actions/submitMfaEnrollment.d.ts

@@ -1,11 +1,48 @@
 import { MfaMethod } from '@coinbase/cdp-api-client';
 import { User } from '../types.js';
+/**
+ * Request parameters for submitMfaEnrollment.
+ */
 export type SubmitMfaEnrollmentOptions = {
     mfaMethod: MfaMethod;
+    /** The 6-digit MFA code from the authenticator app (TOTP) or from SMS. */
     mfaCode: string;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Result of submitMfaEnrollment.
+ */
 export type SubmitMfaEnrollmentResult = {
+    /** The updated user with MFA enrollment. */
     user: User;
 };
+/**
+ * Submits an MFA code to complete the enrollment process.
+ * On success, the MFA configuration is persisted to the end user.
+ *
+ * For TOTP, this validates the code from the user's authenticator app.
+ * For SMS, this validates the code received via text message.
+ *
+ * @param options - The options for the submission.
+ * @param options.mfaMethod - The MFA method being enrolled ("totp" or "sms").
+ * @param options.mfaCode - The 6-digit MFA code from the authenticator app (TOTP) or from SMS.
+ * @example
+ * ```typescript lines
+ * // TOTP enrollment
+ * const totpResult = await submitMfaEnrollment({
+ *   mfaMethod: "totp",
+ *   mfaCode: "123456"
+ * });
+ *
+ * // SMS enrollment
+ * const smsResult = await submitMfaEnrollment({
+ *   mfaMethod: "sms",
+ *   mfaCode: "654321"
+ * });
+ *
+ * console.log("MFA enrolled for user:", smsResult.user.userId);
+ * ```
+ * @returns The result containing the updated user.
+ */
 export declare const submitMfaEnrollment: (options: SubmitMfaEnrollmentOptions) => Promise<SubmitMfaEnrollmentResult>;

package/dist/types/actions/submitMfaVerification.d.ts

@@ -1,7 +1,37 @@
 import { MfaMethod } from '@coinbase/cdp-api-client';
+/**
+ * Request parameters for submitMfaVerification.
+ */
 export type SubmitMfaVerificationOptions = {
     mfaMethod: MfaMethod;
+    /** The 6-digit MFA code from the authenticator app (TOTP) or from SMS. */
     mfaCode: string;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Submits an MFA code to complete the verification process.
+ *
+ * After successful verification, any pending operation that was waiting for MFA
+ * will automatically continue.
+ *
+ * @param options - The options for the verification.
+ * @param options.mfaMethod - The MFA method being verified ("totp" or "sms").
+ * @param options.mfaCode - The 6-digit MFA code from the authenticator app (TOTP) or from SMS.
+ * @example
+ * ```typescript lines
+ * // TOTP verification
+ * await submitMfaVerification({
+ *   mfaMethod: "totp",
+ *   mfaCode: "123456"
+ * });
+ *
+ * // SMS verification
+ * await submitMfaVerification({
+ *   mfaMethod: "sms",
+ *   mfaCode: "654321"
+ * });
+ * ```
+ * @returns A promise that resolves if MFA verification is successful.
+ */
 export declare const submitMfaVerification: (options: SubmitMfaVerificationOptions) => Promise<void>;

package/dist/types/actions/verifyEmailOTP.d.ts

@@ -1,2 +1,15 @@
 import { VerifyEmailOTPOptions, VerifyEmailOTPResult } from '../types.js';
+/**
+ * Verifies the one-time password (OTP) for the sign in flow with an email.
+ *
+ * @param options - The options for the verification.
+ * @example
+ * ```typescript lines
+ * const result = await verifyEmailOTP({
+ *   flowId: "flow-id-from-signInWithEmail",
+ *   otp: "123456" // The OTP received in email
+ * });
+ * ```
+ * @returns The result of the verification.
+ */
 export declare const verifyEmailOTP: (options: VerifyEmailOTPOptions) => Promise<VerifyEmailOTPResult>;

package/dist/types/actions/verifyOAuth.d.ts

@@ -1,2 +1,38 @@
 import { VerifyOAuthOptions, VerifyOAuthResult } from '../types.js';
+/**
+ * Verifies the OAuth code for the sign in flow with a OAuth provider.
+ *
+ * @param options - The options for the verification.
+ * @returns The result of the verification.
+ *
+ * @example
+ * ```typescript lines
+ * // Google
+ * const result = await verifyOAuth({
+ *   flowId: "flow-id-from-signInWithGoogle",
+ *   code: "123456", // The OAuth code received from the OAuth provider
+ *   providerType: "google",
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript lines
+ * // Apple
+ * const result = await verifyOAuth({
+ *   flowId: "flow-id-from-signInWithApple",
+ *   code: "123456", // The OAuth code received from the OAuth provider
+ *   providerType: "apple",
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript lines
+ * // X
+ * const result = await verifyOAuth({
+ *   flowId: "flow-id-from-signInWithX",
+ *   code: "123456", // The OAuth code received from the OAuth provider
+ *   providerType: "x",
+ * });
+ * ```
+ */
 export declare const verifyOAuth: (options: VerifyOAuthOptions) => Promise<VerifyOAuthResult>;

package/dist/types/actions/verifySmsOTP.d.ts

@@ -1,2 +1,15 @@
 import { VerifySmsOTPOptions, VerifySmsOTPResult } from '../types.js';
+/**
+ * Verifies the one-time password (OTP) for the sign in flow with a phone number via SMS.
+ *
+ * @param options - The options for the verification.
+ * @example
+ * ```typescript lines
+ * const result = await verifySmsOTP({
+ *   flowId: "flow-id-from-signInWithSms",
+ *   otp: "123456" // The OTP received in SMS
+ * });
+ * ```
+ * @returns The result of the verification.
+ */
 export declare const verifySmsOTP: (options: VerifySmsOTPOptions) => Promise<VerifySmsOTPResult>;

package/dist/types/actions/verifyTelegramOAuth.d.ts

@@ -1,2 +1,8 @@
 import { VerifyOAuthResult, VerifyTelegramOAuthOptions } from '../types.js';
+/**
+ * Verifies a Telegram OAuth authentication by calling the verifyOAuthEndUserIdentity endpoint.
+ *
+ * @param options - The options containing the flowId and Telegram auth data from the popup.
+ * @returns The result of the verification.
+ */
 export declare const verifyTelegramOAuth: (options: VerifyTelegramOAuthOptions) => Promise<VerifyOAuthResult>;

package/dist/types/actions/waitForEvmEip7702Delegation.d.ts

@@ -1,7 +1,41 @@
 import { EvmEip7702DelegationOperation } from '@coinbase/cdp-api-client';
+/**
+ * Options for waiting for an EIP-7702 delegation operation to complete.
+ */
 export type WaitForEvmEip7702DelegationOptions = {
+    /** The unique identifier for the delegation operation returned by createEvmEip7702Delegation. */
     delegationOperationId: string;
+    /**
+     * Polling interval in milliseconds.
+     *
+     * @default 2000
+     */
     intervalMs?: number;
+    /**
+     * Maximum time to wait in milliseconds before giving up.
+     *
+     * @default 120000 (2 minutes)
+     */
     timeoutMs?: number;
 };
+/**
+ * Polls the EIP-7702 delegation operation status until it reaches COMPLETED, FAILED, or the timeout is reached.
+ *
+ * @param options - Options for the delegation operation to check and polling behavior.
+ * @returns The delegation operation on COMPLETED; false on timeout.
+ * @throws Error if the operation status is FAILED.
+ *
+ * @example
+ * ```ts
+ * const result = await waitForEvmEip7702Delegation({
+ *   delegationOperationId: 'op-123',
+ *   timeoutMs: 60_000,
+ * });
+ * if (result) {
+ *   console.log('Delegation completed:', result.transactionHash);
+ * } else {
+ *   console.log('Timed out');
+ * }
+ * ```
+ */
 export declare function waitForEvmEip7702Delegation(options: WaitForEvmEip7702DelegationOptions): Promise<EvmEip7702DelegationOperation | false>;

package/dist/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/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/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/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/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;