@coinbase/cdp-core 0.0.98 → 0.0.99

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

@@ -1,3 +1,48 @@
+/**
+ * Wraps an async operation to handle MFA verification automatically.
+ *
+ * This function performs a pre-check to see if the user is enrolled in MFA
+ * but not currently verified. If so, it triggers the registered MFA verification
+ * handler and waits for the user to complete MFA before executing the operation.
+ *
+ * If the operation fails with an `mfa_required` error from the API, it will also
+ * trigger the MFA handler and retry the operation after successful verification.
+ *
+ * @param operation - The async operation to wrap.
+ * @returns The result of the operation.
+ * @internal
+ */
 export declare function withMfa<T>(operation: () => Promise<T>): Promise<T>;
+/**
+ * Checks if the next MFA-protected action will require MFA verification.
+ *
+ * Returns true if the user is enrolled in MFA but hasn't verified recently
+ * (within the configured verification window). When true, calling an
+ * MFA-protected action will trigger the registered MFA verification handler.
+ *
+ * Use this to pre-warn users or show UI hints before they start a sensitive flow.
+ *
+ * @returns True if MFA verification will be required for the next sensitive action.
+ *
+ * @example
+ * ```typescript
+ * import { isMfaRequired, signEvmHash } from '@coinbase/cdp-core';
+ * async function handleSign() {
+ *   // prompt mfa before calling the sign hash function
+ *   if (isMfaRequired()) {
+ *     await ensureMfaVerified(); // User will be prompted
+ *   }
+ *   await signEvmHash({ ... }); // MFA handled automatically by withMfa
+ * }
+ * ```
+ */
 export declare function isMfaRequired(): boolean;
+/**
+ * Ensures MFA is verified before proceeding.
+ * If the user is enrolled in MFA but not verified, triggers the MFA verification flow.
+ *
+ * @returns A Promise that resolves when MFA is verified (or if not required).
+ * @throws Error if MFA is required but no handler is registered.
+ * @internal
+ */
 export declare function ensureMfaVerified(): Promise<void>;

package/dist/types/mocks/config.d.ts

@@ -1,2 +1,13 @@
 import { Config } from '../types.js';
+/**
+ * Creates a mock config. Defaults to:
+ * - projectId: "some-project-id"
+ * - useMock: false
+ * - ethereum: {
+ *    createOnLogin: "eoa"
+ *  }
+ *
+ * @param options - The options for the config.
+ * @returns The mock config.
+ */
 export declare function createConfig(options?: Partial<Config>): Config;

package/dist/types/mocks/mockAuthManager.d.ts

@@ -1,27 +1,113 @@
 import { AuthState, IAuthManager } from '../auth/types.js';
 import { OnAuthStateChangeFn, User } from '../types.js';
+/**
+ * Mock implementation of the auth manager.
+ * Provides a simulated authentication experience for testing and development.
+ */
 export declare class MockAuthManager implements IAuthManager {
     private authState;
     private authStateChangeCallback;
+    /**
+     * Initializes the mock auth manager.
+     *
+     * @param _projectId - The project ID (unused in mock implementation).
+     */
     constructor(_projectId: string);
+    /**
+     * Awaitable method whose promise only resolves when the auth manager is ready to be used.
+     *
+     * @returns A promise that resolves when the auth manager is ready to be used.
+     */
     ensureInitialized(): Promise<void>;
+    /**
+     * Gets the current user, or null if there is no user signed in.
+     *
+     * @returns The current mock user if signed in, null otherwise.
+     */
     getUser(): User | null;
+    /**
+     * Returns whether the user is signed in - i.e., whether there is an unexpired
+     * access token and user.
+     *
+     * @returns True if the mock user is signed in and token is not expired, false otherwise.
+     */
     isSignedIn(): Promise<boolean>;
+    /**
+     * Signs out the user, clearing all authentication state.
+     * In the mock implementation, this simply clears the local auth state.
+     */
     signOut(): Promise<void>;
+    /**
+     * Sets a callback to be called when the auth state changes.
+     * The callback is immediately called with the current auth state.
+     *
+     * @param callback - The function to call when the auth state changes.
+     *                  Will be called with the current user or null.
+     */
     addAuthStateChangeCallback(callback: OnAuthStateChangeFn): void;
+    /**
+     * Gets the access token. For mock, this always returns a valid token if signed in.
+     * If the current token is expired, it will be refreshed automatically.
+     *
+     * @param options - The options for getting the token.
+     * @param options.forceRefresh - Whether to force a refresh of the token.
+     * @returns The mock access token if signed in, null otherwise.
+     */
     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 currentlly registered wallet secret ID.
+     *
+     * @returns The wallet secret ID.
+     */
     getWalletSecretId(): Promise<string>;
+    /**
+     * Gets the X-Wallet-Auth header value.
+     *
+     * @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 value.
+     */
     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.
+     * This will trigger the auth state change callback if one is registered.
+     *
+     * @param authState - The new authentication state to set.
+     */
     setAuthState(authState: AuthState): Promise<void>;
+    /**
+     * Clears the authentication state.
+     * This will trigger the auth state change callback if one is registered.
+     */
     clearAuthState(): Promise<void>;
+    /**
+     * Refreshes the mock token.
+     * Only refreshes if there is an existing auth state (user is signed in).
+     * Sets a new mock token with a 24-hour expiration.
+     *
+     * @private
+     */
     private refreshToken;
 }

package/dist/types/mocks/mockOAuthManager.d.ts

@@ -1,12 +1,40 @@
 import { IOAuthManager } from '../auth/types.js';
 import { OAuthFlowState, OnOAuthStateChangeFn } from '../types.js';
+/**
+ * Mock implementation of the auth manager.
+ * Provides a simulated authentication experience for testing and development.
+ */
 export declare class MockOAuthManager implements IOAuthManager {
     private oauthFlowState;
     private oauthStateChangeCallbacks;
+    /**
+     * Initializes the mock OAuth manager.
+     */
     constructor();
+    /**
+     * Gets the current user, or null if there is no user signed in.
+     *
+     * @returns The current mock user if signed in, null otherwise.
+     */
     getOAuthFlowState(): Promise<OAuthFlowState | null>;
+    /**
+     * Sets the OAuth flow state.
+     *
+     * @param oauthFlowState - The OAuth flow state to set.
+     */
     setOAuthFlowState(oauthFlowState: OAuthFlowState): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * Clears the OAuth flow state.
+     */
     clearOAuthFlowState(): Promise<void>;
+    /**
+     * Awaitable method whose promise only resolves when the OAuth manager is ready to be used.
+     */
     handleOAuthCode(): Promise<void>;
 }

package/dist/types/mocks/user.d.ts

@@ -1,5 +1,35 @@
 import { User } from '../types.js';
 export declare const mockAddress: `0x${string}`;
 export declare const mockUser: User;
+/**
+ * Returns the current mock user.
+ *
+ * @returns The current mock user.
+ */
 export declare const getCurrentUser: () => Promise<User | null>;
+/**
+ * Helper function to create a mock user with support for overrides.
+ *
+ * @param overrides - The overrides to apply to the mock user.
+ * @returns The mock user with the overrides applied.
+ *
+ * @example
+ * ```typescript
+ * const user = createUser({
+ *   evmAccountObjects: [{ address: "0x1234567890123456789012345678901234567890", createdAt: "2024-01-01T00:00:00Z" }],
+ *   evmAccounts: ["0x1234567890123456789012345678901234567890"],
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const user = createUser({
+ *   authenticationMethods: {
+ *     sms: {
+ *       phoneNumber: "+12055555555",
+ *       type: "sms",
+ *     },
+ *   },
+ * });
+ */
 export declare function createUser(overrides?: Partial<User>): User;

package/dist/types/platform/native/appleAuthRegistry.d.ts

@@ -1,5 +1,28 @@
 import { AppleNativeCredential } from '../types.js';
+/**
+ * Function signature for the native Apple Sign In provider.
+ * This is the contract that @coinbase/cdp-react-native must fulfill
+ * when registering itself with the core SDK.
+ */
 export type AppleAuthProvider = () => Promise<AppleNativeCredential>;
+/**
+ * Registers a native Apple Sign In provider with the core SDK.
+ * Called by @coinbase/cdp-react-native to provide the expo-apple-authentication
+ * implementation, keeping expo-apple-authentication out of core's dependency graph.
+ *
+ * @param provider - A function that triggers the native Apple Sign In sheet and
+ *   returns the resulting credential.
+ */
 export declare function registerAppleAuthProvider(provider: AppleAuthProvider): void;
+/**
+ * Retrieves the registered Apple Sign In provider.
+ *
+ * @returns The registered provider, or null if none has been registered.
+ */
 export declare function getAppleAuthProvider(): AppleAuthProvider | null;
+/**
+ * Clears the registered Apple Sign In provider.
+ *
+ * @internal
+ */
 export declare function clearAppleAuthProvider(): void;

package/dist/types/platform/native/attestation.d.ts

@@ -1,2 +1,18 @@
 import { PlatformAttestation } from '../types.js';
+/**
+ * React Native platform implementation of device attestation.
+ * Uses cdp-app-attest module for iOS App Attest and Android Play Integrity.
+ *
+ * Platform Flows:
+ * - iOS: One-time attestation exchange (stores public key on backend) → per-request assertions
+ * - Android: No attestation exchange → per-request Play Integrity tokens
+ *
+ * iOS Flow:
+ * 1. attest(challenge) - Generate key + attestation, exchange with backend to register public key
+ * 2. generateAssertion(clientData) - Create signed assertions for sensitive requests
+ *
+ * Android Flow:
+ * 1. generateAssertion(clientData) - Generate fresh Play Integrity token per request
+ * 2. No attestation exchange needed - backend validates tokens with Google
+ */
 export declare const nativeAttestation: PlatformAttestation;

package/dist/types/platform/native/attestationRegistry.d.ts

@@ -1,8 +1,16 @@
+/**
+ * Interface for the raw native attestation module.
+ * This is the contract that @coinbase/cdp-app-attest must fulfill
+ * when registering itself with the core SDK.
+ */
 export interface NativeAttestationModule {
+    /** Check if device attestation is supported. */
     isSupported(): Promise<boolean>;
+    /** Initialize the native module (required for Android Play Integrity). */
     initialize(config?: {
         cloudProjectNumber?: string;
     }): Promise<void>;
+    /** Attest the app with a server-provided challenge (iOS). */
     attest(challenge: string): Promise<{
         ios?: {
             keyId: string;
@@ -10,6 +18,7 @@ export interface NativeAttestationModule {
             bundleId: string;
         };
     }>;
+    /** Generate proof of authenticity for an API request. */
     createAssertion(clientData: string): Promise<{
         ios?: {
             assertion: string;
@@ -19,10 +28,29 @@ export interface NativeAttestationModule {
             integrityToken: string;
         };
     }>;
+    /** Mark attestation as registered with backend (iOS). */
     confirmRegistration(keyId: string): Promise<void>;
+    /** Get the registered key ID, or null if not registered (iOS). */
     getRegisteredKeyId(): Promise<string | null>;
+    /** Clear all attestation state for re-attestation. */
     clearAttestation(): Promise<void>;
 }
+/**
+ * Registers a native attestation module with the core SDK.
+ * Called by @coinbase/cdp-app-attest/register to provide the native implementation.
+ *
+ * @param mod - The native attestation module implementation.
+ */
 export declare function registerAttestationModule(mod: NativeAttestationModule): void;
+/**
+ * Retrieves the registered native attestation module.
+ *
+ * @returns The registered module, or null if none has been registered.
+ */
 export declare function getAttestationModule(): NativeAttestationModule | null;
+/**
+ * Clears the registered native attestation module.
+ *
+ * @internal
+ */
 export declare function clearAttestationModule(): void;

package/dist/types/platform/native/crypto.d.ts

@@ -1,2 +1,6 @@
 import { PlatformCrypto } from '../types.js';
+/**
+ * React Native platform implementation of cryptographic operations.
+ * Uses polyfilled crypto APIs or fallback implementations.
+ */
 export declare const nativeCrypto: PlatformCrypto;

package/dist/types/platform/native/deviceInfo.d.ts

@@ -1,2 +1,5 @@
 import { PlatformDeviceInfo } from '../types.js';
+/**
+ * React Native platform implementation of device information.
+ */
 export declare const nativeDeviceInfo: PlatformDeviceInfo;

package/dist/types/platform/native/deviceInfoRegistry.d.ts

@@ -1,6 +1,30 @@
+/**
+ * Interface for the native device info module.
+ * This is the contract that @coinbase/cdp-react-native must fulfill
+ * when registering itself with the core SDK, keeping react-native-device-info
+ * out of core's dependency graph.
+ */
 export interface NativeDeviceInfoModule {
+    /** Returns the app bundle ID (iOS) or package name (Android). */
     getBundleId(): string;
 }
+/**
+ * Registers a native device info module with the core SDK.
+ * Called by @coinbase/cdp-react-native to provide the react-native-device-info
+ * implementation.
+ *
+ * @param mod - The native device info module implementation.
+ */
 export declare function registerDeviceInfoModule(mod: NativeDeviceInfoModule): void;
+/**
+ * Retrieves the registered native device info module.
+ *
+ * @returns The registered module, or null if none has been registered.
+ */
 export declare function getDeviceInfoModule(): NativeDeviceInfoModule | null;
+/**
+ * Clears the registered native device info module.
+ *
+ * @internal
+ */
 export declare function clearDeviceInfoModule(): void;

package/dist/types/platform/native/secureStorage.d.ts

@@ -1,2 +1,8 @@
 import { PlatformSecureStorage } from '../types.js';
+/**
+ * React Native platform implementation of secure storage operations.
+ * Uses Expo SecureStore for secure persistent storage backed by the device's secure enclave.
+ *
+ * Note: This implementation requires expo-secure-store to be installed as a dependency.
+ */
 export declare const nativeSecureStorage: PlatformSecureStorage;

package/dist/types/platform/native/storage.d.ts

@@ -1,2 +1,9 @@
 import { PlatformStorage } from '../types.js';
+/**
+ * React Native platform implementation of storage operations.
+ * Uses AsyncStorage for persistent storage.
+ *
+ * Note: This implementation requires @react-native-async-storage/async-storage
+ * to be installed as a peer dependency.
+ */
 export declare const nativeStorage: PlatformStorage;

package/dist/types/platform/registry.d.ts

@@ -1,9 +1,70 @@
 import { PlatformServices, PlatformCrypto, PlatformStorage, PlatformOAuth, PlatformAttestation } from './types.js';
+/**
+ * Registers platform-specific services with the dependency injection container.
+ * This should be called once during application initialization, typically by
+ * platform-specific entry points.
+ *
+ * @param services - The platform services to register.
+ * @example
+ * ```typescript
+ * import { webCrypto } from './platform/web/crypto.js';
+ * import { webStorage } from './platform/web/storage.js';
+ *
+ * setPlatformServices({
+ *   crypto: webCrypto,
+ *   storage: webStorage,
+ * });
+ * ```
+ */
 export declare function setPlatformServices(services: PlatformServices): void;
+/**
+ * Retrieves the registered platform services.
+ * Throws an error if services have not been initialized.
+ *
+ * @returns The registered platform services.
+ * @throws Error if platform services have not been initialized.
+ */
 export declare function getPlatformServices(): PlatformServices;
+/**
+ * Convenience function to get platform-specific crypto services.
+ *
+ * @returns The platform crypto services.
+ * @throws Error if platform services have not been initialized.
+ */
 export declare function getPlatformCrypto(): PlatformCrypto;
+/**
+ * Convenience function to get platform-specific storage services.
+ *
+ * @returns The platform storage services.
+ * @throws Error if platform services have not been initialized.
+ */
 export declare function getPlatformStorage(): PlatformStorage;
+/**
+ * Convenience function to get platform-specific OAuth services.
+ *
+ * @returns The platform OAuth services.
+ * @throws Error if platform services have not been initialized.
+ */
 export declare function getPlatformOAuth(): PlatformOAuth;
+/**
+ * Convenience function to get platform-specific attestation services.
+ * Returns undefined if attestation is not available on the current platform.
+ *
+ * @returns The platform attestation services, or undefined if not available.
+ * @throws Error if platform services have not been initialized.
+ */
 export declare function getPlatformAttestation(): PlatformAttestation | undefined;
+/**
+ * Checks if platform services have been initialized.
+ * Useful for conditional logic or testing scenarios.
+ *
+ * @returns True if platform services are initialized, false otherwise.
+ */
 export declare function isPlatformInitialized(): boolean;
+/**
+ * Clears the registered platform services.
+ * This is primarily useful for testing scenarios where you need to reset state.
+ *
+ * @internal
+ */
 export declare function clearPlatformServices(): void;