@coinbase/cdp-core 0.0.97 → 0.0.99

package/dist/native-types/actions/initiateMfaEnrollment.d.ts

@@ -1,21 +1,82 @@
+/**
+ * Request parameters for initiating TOTP MFA enrollment.
+ */
 export type InitiateTotpMfaOptions = {
+    /** The MFA method to use. */
     mfaMethod: "totp";
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Request parameters for initiating SMS MFA enrollment.
+ */
 export type InitiateSmsMfaOptions = {
+    /** The MFA method to use. */
     mfaMethod: "sms";
+    /**
+     * Phone number in E.164 format (e.g., +14155552671).
+     * You can use any phone number for SMS MFA, even if it differs from your SMS authentication phone number.
+     */
     phoneNumber: string;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Request parameters for initiating MFA operations.
+ */
 export type InitiateMfaOptions = InitiateTotpMfaOptions | InitiateSmsMfaOptions;
+/**
+ * Result of TOTP MFA enrollment initiation.
+ */
 export type InitiateTotpMfaResult = {
+    /** The MFA method that was initiated. */
     method: "totp";
+    /** The otpauth:// URL for the authenticator app (for QR code generation). */
     authUrl: string;
+    /** The base32-encoded TOTP secret (for manual entry). */
     secret: string;
 };
+/**
+ * Result of SMS MFA enrollment initiation.
+ */
 export type InitiateSmsMfaResult = {
+    /** The MFA method that was initiated. */
     method: "sms";
+    /** Indicates SMS was sent successfully. */
     success: boolean;
 };
+/**
+ * Result of initiateMfaEnrollment.
+ */
 export type InitiateMfaEnrollmentResult = InitiateTotpMfaResult | InitiateSmsMfaResult;
+/**
+ * Initiates MFA enrollment for an end user.
+ *
+ * For TOTP, this generates a TOTP secret and returns an otpauth:// URL that can be scanned
+ * with an authenticator app like Google Authenticator. The secret must be verified within
+ * 5 minutes by calling submitMfaEnrollment.
+ *
+ * For SMS, this sends a 6-digit OTP code to the provided phone number. The OTP code must
+ * be verified within 5 minutes. You can use any phone number for SMS MFA, even if it differs
+ * from your SMS authentication phone number.
+ *
+ * @param options - The options for initiating MFA enrollment.
+ * @example
+ * ```typescript lines
+ * // TOTP enrollment
+ * const totpResult = await initiateMfaEnrollment({ mfaMethod: "totp" });
+ * // Display totpResult.authUrl as QR code or provide totpResult.secret for manual entry
+ * console.log("Scan this QR code:", totpResult.authUrl);
+ * console.log("Or enter this secret manually:", totpResult.secret);
+ *
+ * // SMS enrollment
+ * const smsResult = await initiateMfaEnrollment({
+ *   mfaMethod: "sms",
+ *   phoneNumber: "+14155552671"
+ * });
+ * console.log("SMS sent:", smsResult.success);
+ * // User receives SMS with 6-digit code
+ * ```
+ * @returns The result containing enrollment details specific to the method.
+ */
 export declare const initiateMfaEnrollment: (options: InitiateMfaOptions) => Promise<InitiateMfaEnrollmentResult>;

package/dist/native-types/actions/initiateMfaVerification.d.ts

@@ -1,6 +1,33 @@
 import { MfaMethod } from '@coinbase/cdp-api-client';
+/**
+ * Request parameters for initiating MFA verification.
+ */
 export type InitiateMfaVerificationOptions = {
+    /** The MFA method to verify ("totp" or "sms"). */
     mfaMethod: MfaMethod;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Initiates an MFA verification flow for operations requiring MFA.
+ * This endpoint should be called when a user attempts a sensitive operation
+ * (like transaction signing) but doesn't have a valid MFA-verified session.
+ *
+ * For TOTP, this prepares a verification session.
+ * For SMS, this sends a 6-digit OTP code to the user's enrolled phone number.
+ *
+ * @param options - The options for initiating MFA verification.
+ * @param options.mfaMethod - The MFA method to verify ("totp" or "sms").
+ * @example
+ * ```typescript lines
+ * // TOTP verification
+ * await initiateMfaVerification({ mfaMethod: "totp" });
+ * // Prompt user for code from authenticator app
+ *
+ * // SMS verification
+ * await initiateMfaVerification({ mfaMethod: "sms" });
+ * // SMS sent to user's phone - prompt for code
+ * ```
+ * @returns A promise that resolves if MFA initiation is successful.
+ */
 export declare const initiateMfaVerification: (options: InitiateMfaVerificationOptions) => Promise<void>;

package/dist/native-types/actions/isSignedIn.d.ts

@@ -1 +1,13 @@
+/**
+ * Returns whether the user is currently signed in.
+ *
+ * @example
+ * ```typescript lines
+ * const signedIn = await isSignedIn();
+ * if (signedIn) {
+ *   console.log("User is signed in");
+ * }
+ * ```
+ * @returns Whether the user is currently signed in.
+ */
 export declare const isSignedIn: () => Promise<boolean>;

package/dist/native-types/actions/linkApple.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Links an Apple account to the current user.
+ *
+ * @param options - Optional options for the link operation.
+ * @param options.idempotencyKey - Optional idempotency key for safe retries.
+ * @returns The result of the link Apple initiation.
+ */
 export declare function linkApple(options?: {
     idempotencyKey?: string;
 }): Promise<void>;

package/dist/native-types/actions/linkEmail.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Links an email account to the current user.
+ *
+ * @param email - The email address to link.
+ * @param options - Optional options for the link operation.
+ * @param options.idempotencyKey - Optional idempotency key for safe retries.
+ * @returns The result of the link email initiation.
+ */
 export declare function linkEmail(email: string, options?: {
     idempotencyKey?: string;
 }): Promise<{

package/dist/native-types/actions/linkGoogle.d.ts

@@ -1 +1,6 @@
+/**
+ * Links a Google account to the current user.
+ *
+ * @returns The result of the link Google initiation.
+ */
 export declare function linkGoogle(): Promise<void>;

package/dist/native-types/actions/linkOAuth.d.ts

@@ -1,4 +1,12 @@
 import { OAuth2ProviderType } from '@coinbase/cdp-api-client';
+/**
+ * Links an OAuth account to the current user.
+ *
+ * @param providerType - The OAuth provider type (e.g., "google", "apple", "x", "telegram").
+ * @param options - Optional options for the link operation.
+ * @param options.idempotencyKey - Optional idempotency key for safe retries.
+ * @returns The result of the link OAuth initiation.
+ */
 export declare function linkOAuth(providerType: OAuth2ProviderType, options?: {
     idempotencyKey?: string;
 }): Promise<void>;

package/dist/native-types/actions/linkSms.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Links a SMS account to the current user.
+ *
+ * @param phoneNumber - The phone number to link.
+ * @param options - Optional options for the link operation.
+ * @param options.idempotencyKey - Optional idempotency key for safe retries.
+ * @returns The result of the link SMS initiation.
+ */
 export declare function linkSms(phoneNumber: string, options?: {
     idempotencyKey?: string;
 }): Promise<{

package/dist/native-types/actions/linkTelegram.d.ts

@@ -1 +1,6 @@
+/**
+ * Links a Telegram account to the current user.
+ *
+ * @returns The result of the link Telegram initiation.
+ */
 export declare function linkTelegram(): Promise<void>;

package/dist/native-types/actions/listSpendPermissions.d.ts

@@ -1,14 +1,46 @@
 import { SpendPermissionNetwork, SpendPermissionResponseObject } from '@coinbase/cdp-api-client';
 import { EvmAddress } from '../types.js';
+/**
+ * Input for listing spend permissions.
+ */
 export type ListSpendPermissionsOptions = {
+    /** The EVM Smart Account to list spend permissions for. */
     evmSmartAccount: EvmAddress;
+    /** The network to list spend permissions from. */
     network: SpendPermissionNetwork;
+    /** The number of spend permissions to return per page. */
     pageSize?: number;
+    /** The token for the next page of spend permissions. */
     pageToken?: string;
 };
+/**
+ * Result of listSpendPermissions.
+ */
 export type ListSpendPermissionsResult = {
+    /** The list of spend permissions. */
     spendPermissions: SpendPermissionResponseObject[];
+    /** Whether there are more results available. */
     hasNextPage: boolean;
+    /** The token for the next page (if any). */
     nextPageToken?: string;
 };
+/**
+ * Lists spend permissions for the user's EVM Smart Account.
+ *
+ * @param options - The options for listing spend permissions.
+ * @example
+ * ```typescript lines
+ * const result = await listSpendPermissions({
+ *   evmSmartAccount: "0x1234...",
+ *   network: "base-sepolia",
+ *   pageSize: 10
+ * });
+ *
+ * console.log("Found", result.spendPermissions.length, "spend permissions");
+ * for (const permission of result.spendPermissions) {
+ *   console.log("Permission:", permission.permissionHash, "Revoked:", permission.revoked);
+ * }
+ * ```
+ * @returns The result of the spend permissions listing.
+ */
 export declare const listSpendPermissions: (options: ListSpendPermissionsOptions) => Promise<ListSpendPermissionsResult>;

package/dist/native-types/actions/onAuthStateChange.d.ts

@@ -1,2 +1,18 @@
 import { OnAuthStateChangeFn } from '../types.js';
+/**
+ * Sets a callback function to be called when the authentication state changes,
+ * i.e. when a user signs in or out.
+ *
+ * @example
+ * ```typescript lines
+ * onAuthStateChange(async (user) => {
+ *   if (user) {
+ *     console.log("User signed in:", user.userId);
+ *   } else {
+ *     console.log("User signed out");
+ *   }
+ * });
+ * ```
+ * @param callback - The callback function to be called when the authentication state changes.
+ */
 export declare const onAuthStateChange: (callback: OnAuthStateChangeFn) => void;

package/dist/native-types/actions/onOAuthStateChange.d.ts

@@ -1,2 +1,8 @@
 import { OnOAuthStateChangeFn } from '../types.js';
+/**
+ * Sets a callback function to be called when the OAuth flow state changes,
+ * i.e. when a user signs in with OAuth.
+ *
+ * @param callback - The callback function to be called when the OAuth flow state changes.
+ */
 export declare const onOAuthStateChange: (callback: OnOAuthStateChangeFn) => void;

package/dist/native-types/actions/recordMfaEnrollmentPrompted.d.ts

@@ -1,5 +1,23 @@
 import { RecordMfaEnrollmentPrompted200 } from '@coinbase/cdp-api-client';
+/**
+ * Result of recordMfaEnrollmentPrompted.
+ */
 export type RecordMfaEnrollmentPromptedResult = RecordMfaEnrollmentPrompted200;
+/**
+ * Records that the end user was prompted for MFA enrollment.
+ * This endpoint should be called when the user is shown the MFA enrollment prompt,
+ * regardless of whether they choose to enroll or skip. This helps track when users
+ * were last offered the opportunity to enroll in MFA.
+ *
+ * @example
+ * ```typescript lines
+ * const result = await recordMfaEnrollmentPrompted();
+ * console.log("MFA enrollment prompt recorded at:", result.enrollmentPromptedAt);
+ * ```
+ * @param options - Optional options for the operation.
+ * @param options.idempotencyKey - Optional idempotency key for safe retries.
+ * @returns The result containing the timestamp when enrollment was prompted.
+ */
 export declare const recordMfaEnrollmentPrompted: (options?: {
     idempotencyKey?: string;
 }) => Promise<RecordMfaEnrollmentPromptedResult>;

package/dist/native-types/actions/revokeDelegation.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Options for revoking all active delegations for an end user.
+ */
+export type RevokeDelegationOptions = {
+    /** Optional idempotency key for safe retries. */
+    idempotencyKey?: string;
+};
+/**
+ * Revokes all active delegations for the current end user.
+ * This operation can be performed by the end user themselves or by a developer using their API key.
+ *
+ * @param options - Optional options for revoking the delegation.
+ * @returns A promise that resolves when all active delegations have been revoked.
+ * @throws Error if the user is not signed in.
+ */
+export declare function revokeDelegation(options?: RevokeDelegationOptions): Promise<void>;

package/dist/native-types/actions/revokeSpendPermission.d.ts

@@ -1,14 +1,48 @@
 import { SpendPermissionNetwork } from '@coinbase/cdp-api-client';
 import { EvmAddress, Hex } from '../types.js';
+/**
+ * Input for revoking a spend permission.
+ */
 export type RevokeSpendPermissionOptions = {
+    /** The EVM Smart Account to revoke the spend permission for. */
     evmSmartAccount: EvmAddress;
+    /** The network to revoke the spend permission on. */
     network: SpendPermissionNetwork;
+    /** The hash of the spend permission to revoke. */
     permissionHash: string;
+    /**
+     * Whether to use the CDP Paymaster for the user operation.
+     *
+     * Only available on Base. Enabled by default on Base Sepolia.
+     */
     useCdpPaymaster?: boolean;
+    /** The URL of the paymaster to use for the user operation. */
     paymasterUrl?: string;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Result of revokeSpendPermission.
+ */
 export type RevokeSpendPermissionResult = {
+    /** The user operation hash. */
     userOperationHash: Hex;
 };
+/**
+ * Revokes a spend permission for the user's EVM Smart Account.
+ *
+ * @param options - The options for revoking the spend permission.
+ * @example
+ * ```typescript lines
+ * const result = await revokeSpendPermission({
+ *   evmSmartAccount: "0x1234...",
+ *   network: "base-sepolia",
+ *   permissionHash: "0x5678...",
+ *   useCdpPaymaster: true
+ * });
+ *
+ * console.log("User Operation Hash:", result.userOperationHash);
+ * ```
+ * @returns The result of the spend permission revocation.
+ */
 export declare const revokeSpendPermission: (options: RevokeSpendPermissionOptions) => Promise<RevokeSpendPermissionResult>;

package/dist/native-types/actions/sendEvmEoaUsdc.d.ts

@@ -1,13 +1,45 @@
 import { EvmAddress, SendEvmUsdcNetwork } from '../types.js';
 import { Hex } from 'viem';
+/** Request parameters for sending EVM USDC from an EOA account. */
 export type SendEvmEoaUsdcOptions = {
+    /** The EVM EOA account to send USDC from. */
     evmAccount: EvmAddress;
+    /** The recipient address. */
     to: EvmAddress;
+    /** The amount of USDC to send in human-readable format (e.g., "1.50" for 1.5 USDC). */
     amount: string;
+    /** The network to send USDC on. */
     network: SendEvmUsdcNetwork;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/** Result of sendEvmEoaUsdc. */
 export type SendEvmEoaUsdcResult = {
+    /** The transaction hash. */
     transactionHash: Hex;
 };
+/**
+ * Sends USDC on an EVM network from an EOA (Externally Owned Account).
+ *
+ * @param options - The options for sending USDC.
+ * @param options.evmAccount - The EVM EOA account to send USDC from. Found on the user object of the signed in user.
+ * @param options.to - The recipient address.
+ * @param options.amount - The amount of USDC to send in human-readable format (e.g., "1.50" for 1.5 USDC).
+ * @param options.network - The network to send USDC on.
+ * @example
+ * ```typescript
+ * const user = await getCurrentUser();
+ * const evmAccount = user?.evmAccountObjects[0]?.address;
+ *
+ * const result = await sendEvmEoaUsdc({
+ *   evmAccount,
+ *   to: "0x1234567890123456789012345678901234567890",
+ *   amount: "25.50",
+ *   network: "base-sepolia",
+ * });
+ *
+ * console.log("Transaction Hash:", result.transactionHash);
+ * ```
+ * @returns The result of sending USDC.
+ */
 export declare const sendEvmEoaUsdc: (options: SendEvmEoaUsdcOptions) => Promise<SendEvmEoaUsdcResult>;

package/dist/native-types/actions/sendEvmSmartAccountUsdc.d.ts

@@ -1,15 +1,52 @@
 import { EvmAddress, SendEvmUsdcNetwork } from '../types.js';
 import { Hex } from 'viem';
+/** Request parameters for sending EVM USDC from a Smart Account. */
 export type SendEvmSmartAccountUsdcOptions = {
+    /** The EVM Smart Account to send USDC from. */
     evmSmartAccount: EvmAddress;
+    /** The recipient address. */
     to: EvmAddress;
+    /** The amount of USDC to send in human-readable format (e.g., "1.50" for 1.5 USDC). */
     amount: string;
+    /** The network to send USDC on. */
     network: SendEvmUsdcNetwork;
+    /** Whether to use CDP Paymaster to sponsor gas fees. */
     useCdpPaymaster?: boolean;
+    /** Optional custom Paymaster URL to use for gas sponsorship. */
     paymasterUrl?: string;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/** Result of sendEvmSmartAccountUsdc. */
 export type SendEvmSmartAccountUsdcResult = {
+    /** The user operation hash. */
     userOpHash: Hex;
 };
+/**
+ * Sends USDC on an EVM network from a Smart Account.
+ *
+ * @param options - The options for sending USDC.
+ * @param options.evmSmartAccount - The EVM Smart Account to send USDC from. Found on the user object of the signed in user.
+ * @param options.to - The recipient address.
+ * @param options.amount - The amount of USDC to send in human-readable format (e.g., "1.50" for 1.5 USDC).
+ * @param options.network - The network to send USDC on.
+ * @param options.useCdpPaymaster - Whether to use CDP Paymaster to sponsor gas fees.
+ * @param options.paymasterUrl - Optional custom Paymaster URL to use for gas sponsorship.
+ * @example
+ * ```typescript
+ * const user = await getCurrentUser();
+ * const evmSmartAccount = user?.evmSmartAccountObjects[0]?.address;
+ *
+ * const result = await sendEvmSmartAccountUsdc({
+ *   evmSmartAccount,
+ *   to: "0x1234567890123456789012345678901234567890",
+ *   amount: "10.00",
+ *   network: "base-sepolia",
+ *   useCdpPaymaster: true, // Optional: sponsor gas fees
+ * });
+ *
+ * console.log("User Operation Hash:", result.userOpHash);
+ * ```
+ * @returns The result of sending USDC.
+ */
 export declare const sendEvmSmartAccountUsdc: (options: SendEvmSmartAccountUsdcOptions) => Promise<SendEvmSmartAccountUsdcResult>;

package/dist/native-types/actions/sendEvmTransaction.d.ts

@@ -1,2 +1,32 @@
 import { SendEvmTransactionOptions, SendEvmTransactionResult } from '../types.js';
+/**
+ * Sends an EVM transaction.
+ *
+ * @param options - The options for the sending.
+ * @param options.evmAccount - The EVM account to send the transaction with. Found on the user object of the signed in user.
+ * @param options.network - The network to send the transaction on.
+ * @param options.transaction - The transaction to send.
+ * @example
+ * ```typescript lines
+ * const user = await getCurrentUser();
+ * const evmAccount = user?.evmAccountObjects[0]?.address;
+ *
+ * const result = await sendEvmTransaction({
+ *   evmAccount,
+ *   network: "base-sepolia",
+ *   transaction: {
+ *     to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ *     value: 100000000000000n, // 0.0001 ETH in wei
+ *     nonce: 0,
+ *     gas: 21000n,
+ *     maxFeePerGas: 30000000000n,
+ *     maxPriorityFeePerGas: 1000000000n,
+ *     chainId: 84532, // Base Sepolia
+ *     type: "eip1559",
+ *   }
+ * });
+ *
+ * ```
+ * @returns The transaction hash of the sent transaction.
+ */
 export declare const sendEvmTransaction: (options: SendEvmTransactionOptions) => Promise<SendEvmTransactionResult>;

package/dist/native-types/actions/sendSolanaTransaction.d.ts

@@ -1,2 +1,8 @@
 import { SendSolanaTransactionOptions, SendSolanaTransactionResult } from '../types.js';
+/**
+ * Send a Solana transaction.
+ *
+ * @param options - The options for sending the Solana transaction.
+ * @returns The transaction signature.
+ */
 export declare const sendSolanaTransaction: (options: SendSolanaTransactionOptions) => Promise<SendSolanaTransactionResult>;

package/dist/native-types/actions/sendSolanaUsdc.d.ts

@@ -1,14 +1,75 @@
 import { SolanaAddress } from '../types.js';
+/**
+ * The Solana network to send USDC on.
+ */
 export type SendSolanaUsdcNetwork = "solana" | "solana-devnet";
+/** Request parameters for sending Solana USDC. */
 export type SendSolanaUsdcOptions = {
+    /** The Solana account to send USDC from. */
     solanaAccount: SolanaAddress;
+    /** The recipient address (base58 encoded). */
     to: SolanaAddress;
+    /** The amount of USDC to send in human-readable format (e.g., "1.50" for 1.5 USDC). */
     amount: string;
+    /** The network to send USDC on. */
     network: SendSolanaUsdcNetwork;
+    /**
+     * Whether to automatically create an Associated Token Account (ATA) for the recipient if it doesn't exist.
+     *
+     * @default false
+     *
+     * **Important**: Creating an ATA requires ~0.002 SOL (~$0.20) for rent exemption, which the sender pays.
+     *
+     * - Set to `true` if you want to ensure the transaction succeeds by creating the recipient's ATA if needed
+     * - Set to `false` (default) to only send if the recipient already has a USDC token account
+     *
+     * If `false` and the recipient doesn't have an ATA, the transaction will fail with a clear error message.
+     */
     createRecipientAta?: boolean;
+    /** Whether transaction fees should be sponsored by CDP. When true, CDP sponsors the transaction fee. */
+    useCdpSponsor?: boolean;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/** Result of sendSolanaUsdc. */
 export type SendSolanaUsdcResult = {
+    /** The transaction signature. */
     transactionSignature: string;
 };
+/**
+ * Sends USDC on the Solana network.
+ *
+ * @param options - The options for sending USDC.
+ * @param options.solanaAccount - The Solana account to send USDC from. Found on the user object of the signed in user.
+ * @param options.to - The recipient address (base58 encoded).
+ * @param options.amount - The amount of USDC to send in human-readable format (e.g., "1.50" for 1.5 USDC).
+ * @param options.network - The network to send USDC on.
+ * @param options.createRecipientAta - Whether to automatically create an Associated Token Account (ATA) for the recipient if it doesn't exist. Defaults to false.
+ * @param options.useCdpSponsor - Whether transaction fees should be sponsored by CDP. When true, CDP sponsors the transaction fee.
+ * @example
+ * ```typescript
+ * const user = await getCurrentUser();
+ * const solanaAccount = user?.solanaAccountObjects[0]?.address;
+ *
+ * // Send to recipient with existing USDC account (default behavior)
+ * const result = await sendSolanaUsdc({
+ *   solanaAccount,
+ *   to: "ExXhNkgYf6efh7YyqDRVxPZuzafobao1A74drUdp8trd",
+ *   amount: "10.00",
+ *   network: "solana-devnet",
+ * });
+ *
+ * // Or explicitly create recipient's ATA if needed (~0.002 SOL cost)
+ * const resultWithAta = await sendSolanaUsdc({
+ *   solanaAccount,
+ *   to: "ExXhNkgYf6efh7YyqDRVxPZuzafobao1A74drUdp8trd",
+ *   amount: "10.00",
+ *   network: "solana-devnet",
+ *   createRecipientAta: true, // Sender pays for recipient's ATA creation
+ * });
+ *
+ * console.log("Transaction Signature:", result.transactionSignature);
+ * ```
+ * @returns The result of sending USDC.
+ */
 export declare const sendSolanaUsdc: (options: SendSolanaUsdcOptions) => Promise<SendSolanaUsdcResult>;