@coinbase/cdp-sdk 1.25.0 → 1.27.0

package/analytics.ts

@@ -1,6 +1,7 @@
 import md5 from "md5";
 
-import { APIError, HttpErrorType } from "./openapi-client/errors.js";
+import { UserInputValidationError } from "./errors.js";
+import { APIError, NetworkError } from "./openapi-client/errors.js";
 import { version } from "./version.js";
 
 /**
@@ -25,7 +26,29 @@ type ErrorEventData = {
   name: "error";
 };
 
-type EventData = ErrorEventData;
+/**
+ * The data in an action event
+ */
+type ActionEventData = {
+  /**
+   * The operation being performed, e.g. "transfer", "swap", "fund", "requestFaucet"
+   */
+  action: string;
+  /**
+   * The account type, e.g. "evm-server", "evm-smart", "solana"
+   */
+  accountType?: "evm_server" | "evm_smart" | "solana";
+  /**
+   * Additional properties specific to the action
+   */
+  properties?: Record<string, unknown>;
+  /**
+   * The name of the event
+   */
+  name: "action";
+};
+
+type EventData = ErrorEventData | ActionEventData;
 
 // This is a public client id for the analytics service
 const publicClientId = "54f2ee2fb3d2b901a829940d70fbfc13";
@@ -35,6 +58,7 @@ export const Analytics = {
   wrapClassWithErrorTracking,
   wrapObjectMethodsWithErrorTracking,
   sendEvent,
+  trackAction,
 };
 
 /**
@@ -44,7 +68,11 @@ export const Analytics = {
  * @returns Promise that resolves when the event is sent
  */
 async function sendEvent(event: EventData): Promise<void> {
-  if (process.env.DISABLE_CDP_ERROR_REPORTING === "true") {
+  if (event.name === "error" && process.env.DISABLE_CDP_ERROR_REPORTING === "true") {
+    return;
+  }
+
+  if (event.name !== "error" && process.env.DISABLE_CDP_USAGE_TRACKING === "true") {
     return;
   }
 
@@ -89,6 +117,39 @@ async function sendEvent(event: EventData): Promise<void> {
   });
 }
 
+/**
+ * Track an action being performed
+ *
+ * @param params - The parameters for tracking an action
+ * @param params.action - The action being performed
+ * @param params.accountType - The type of account
+ * @param params.properties - Additional properties
+ */
+function trackAction(params: {
+  action: string;
+  accountType?: "evm_server" | "evm_smart" | "solana";
+  properties?: Record<string, unknown>;
+}): void {
+  if (
+    params.properties?.network &&
+    typeof params.properties.network === "string" &&
+    params.properties.network.startsWith("http")
+  ) {
+    const url = new URL(params.properties.network);
+    params.properties.customRpcHost = url.hostname;
+    params.properties.network = "custom";
+  }
+
+  sendEvent({
+    action: params.action,
+    accountType: params.accountType,
+    properties: params.properties,
+    name: "action",
+  }).catch(() => {
+    // ignore error
+  });
+}
+
 /**
  * Wraps all methods of a class with error tracking.
  *
@@ -184,7 +245,15 @@ function shouldTrackError(error: unknown): boolean {
     return false;
   }
 
-  if (error instanceof APIError && error.errorType !== HttpErrorType.unexpected_error) {
+  if (error instanceof UserInputValidationError) {
+    return false;
+  }
+
+  if (error instanceof NetworkError) {
+    return true;
+  }
+
+  if (error instanceof APIError && error.errorType !== "unexpected_error") {
     return false;
   }
 

package/auth/utils/jwt.ts

@@ -2,6 +2,7 @@ import { SignJWT, importPKCS8, importJWK, JWTPayload } from "jose";
 import { getRandomValues } from "uncrypto";
 
 import { authHash } from "./hash.js";
+import { UserInputValidationError } from "../../errors.js";
 import { sortKeys } from "../../utils/sortKeys.js";
 import { InvalidWalletSecretFormatError, UndefinedWalletSecretError } from "../errors.js";
 
@@ -164,7 +165,9 @@ export async function generateJwt(options: JwtOptions): Promise<string> {
       randomNonce,
     );
   } else {
-    throw new Error("Invalid key format - must be either PEM EC key or base64 Ed25519 key");
+    throw new UserInputValidationError(
+      "Invalid key format - must be either PEM EC key or base64 Ed25519 key",
+    );
   }
 }
 
@@ -306,7 +309,7 @@ async function buildEdwardsJWT(
     // Decode the base64 key (expecting 64 bytes: 32 for seed + 32 for public key)
     const decoded = Buffer.from(privateKey, "base64");
     if (decoded.length !== 64) {
-      throw new Error("Invalid Ed25519 key length");
+      throw new UserInputValidationError("Invalid Ed25519 key length");
     }
 
     const seed = decoded.subarray(0, 32);

package/client/cdp.ts

@@ -121,8 +121,14 @@ For more information, see: https://github.com/coinbase/cdp-sdk/blob/main/typescr
       sourceVersion: version,
     });
 
-    if (process.env.DISABLE_CDP_ERROR_REPORTING !== "true") {
+    if (
+      process.env.DISABLE_CDP_ERROR_REPORTING !== "true" ||
+      process.env.DISABLE_CDP_USAGE_TRACKING !== "true"
+    ) {
       Analytics.identifier = apiKeyId;
+    }
+
+    if (process.env.DISABLE_CDP_ERROR_REPORTING !== "true") {
       Analytics.wrapClassWithErrorTracking(CdpClient);
       Analytics.wrapClassWithErrorTracking(EvmClient);
       Analytics.wrapClassWithErrorTracking(SolanaClient);

package/client/evm/evm.ts

@@ -62,6 +62,7 @@ import {
 } from "../../actions/evm/waitForUserOperation.js";
 import { Analytics } from "../../analytics.js";
 import { ImportAccountPublicRSAKey } from "../../constants.js";
+import { UserInputValidationError } from "../../errors.js";
 import { APIError } from "../../openapi-client/errors.js";
 import {
   CdpOpenApiClient,
@@ -114,6 +115,11 @@ export class EvmClient implements EvmClientInterface {
    *          ```
    */
   async createAccount(options: CreateServerAccountOptions = {}): Promise<ServerAccount> {
+    Analytics.trackAction({
+      action: "create_account",
+      accountType: "evm_server",
+    });
+
     const openApiAccount = await CdpOpenApiClient.createEvmAccount(
       {
         name: options.name,
@@ -174,6 +180,11 @@ export class EvmClient implements EvmClientInterface {
    *          ```
    */
   async importAccount(options: ImportServerAccountOptions): Promise<ServerAccount> {
+    Analytics.trackAction({
+      action: "import_account",
+      accountType: "evm_server",
+    });
+
     const encryptionPublicKey = options.encryptionPublicKey || ImportAccountPublicRSAKey;
 
     const privateKeyHex = options.privateKey.startsWith("0x")
@@ -181,7 +192,7 @@ export class EvmClient implements EvmClientInterface {
       : options.privateKey;
 
     if (!/^[0-9a-fA-F]+$/.test(privateKeyHex)) {
-      throw new Error("Private key must be a valid hexadecimal string");
+      throw new UserInputValidationError("Private key must be a valid hexadecimal string");
     }
 
     try {
@@ -245,6 +256,11 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async exportAccount(options: ExportServerAccountOptions): Promise<string> {
+    Analytics.trackAction({
+      action: "export_account",
+      accountType: "evm_server",
+    });
+
     const { publicKey, privateKey } = await generateExportEncryptionKeyPair();
 
     const { encryptedPrivateKey } = await (async () => {
@@ -268,7 +284,7 @@ export class EvmClient implements EvmClientInterface {
         );
       }
 
-      throw new Error("Either address or name must be provided");
+      throw new UserInputValidationError("Either address or name must be provided");
     })();
 
     return decryptWithPrivateKey(privateKey, encryptedPrivateKey);
@@ -320,6 +336,11 @@ export class EvmClient implements EvmClientInterface {
    *          ```
    */
   async createSmartAccount(options: CreateSmartAccountOptions): Promise<SmartAccount> {
+    Analytics.trackAction({
+      action: "create_smart_account",
+      accountType: "evm_smart",
+    });
+
     const openApiSmartAccount = await CdpOpenApiClient.createEvmSmartAccount(
       {
         owners: [options.owner.address],
@@ -364,6 +385,11 @@ export class EvmClient implements EvmClientInterface {
    *          ```
    */
   async getAccount(options: GetServerAccountOptions): Promise<ServerAccount> {
+    Analytics.trackAction({
+      action: "get_account",
+      accountType: "evm_server",
+    });
+
     const openApiAccount = await (() => {
       if (options.address) {
         return CdpOpenApiClient.getEvmAccount(options.address);
@@ -373,7 +399,7 @@ export class EvmClient implements EvmClientInterface {
         return CdpOpenApiClient.getEvmAccountByName(options.name);
       }
 
-      throw new Error("Either address or name must be provided");
+      throw new UserInputValidationError("Either address or name must be provided");
     })();
 
     const account = toEvmServerAccount(CdpOpenApiClient, {
@@ -408,13 +434,17 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async getSmartAccount(options: GetSmartAccountOptions): Promise<SmartAccount> {
+    Analytics.trackAction({
+      action: "get_smart_account",
+    });
+
     const openApiSmartAccount = await (async () => {
       if (options.address) {
         return CdpOpenApiClient.getEvmSmartAccount(options.address);
       } else if (options.name) {
         return CdpOpenApiClient.getEvmSmartAccountByName(options.name);
       }
-      throw new Error("Either address or name must be provided");
+      throw new UserInputValidationError("Either address or name must be provided");
     })();
 
     const smartAccount = toEvmSmartAccount(CdpOpenApiClient, {
@@ -443,6 +473,11 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async getOrCreateAccount(options: GetOrCreateServerAccountOptions): Promise<ServerAccount> {
+    Analytics.trackAction({
+      action: "get_or_create_account",
+      accountType: "evm_server",
+    });
+
     try {
       const account = await this.getAccount(options);
       return account;
@@ -463,7 +498,6 @@ export class EvmClient implements EvmClientInterface {
           throw error;
         }
       }
-
       throw error;
     }
   }
@@ -488,6 +522,11 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async getOrCreateSmartAccount(options: GetOrCreateSmartAccountOptions): Promise<SmartAccount> {
+    Analytics.trackAction({
+      action: "get_or_create_smart_account",
+      accountType: "evm_smart",
+    });
+
     try {
       const account = await this.getSmartAccount(options);
       return account;
@@ -508,7 +547,6 @@ export class EvmClient implements EvmClientInterface {
           throw error;
         }
       }
-
       throw error;
     }
   }
@@ -534,6 +572,13 @@ export class EvmClient implements EvmClientInterface {
   async getSwapPrice(
     options: GetSwapPriceOptions,
   ): Promise<GetSwapPriceResult | SwapUnavailableResult> {
+    Analytics.trackAction({
+      action: "get_swap_price",
+      properties: {
+        network: options.network,
+      },
+    });
+
     return getSwapPrice(CdpOpenApiClient, options);
   }
 
@@ -558,6 +603,13 @@ export class EvmClient implements EvmClientInterface {
   async createSwapQuote(
     options: CreateSwapQuoteOptions,
   ): Promise<CreateSwapQuoteResult | SwapUnavailableResult> {
+    Analytics.trackAction({
+      action: "create_swap_quote",
+      properties: {
+        network: options.network,
+      },
+    });
+
     return createSwapQuote(CdpOpenApiClient, options);
   }
 
@@ -579,6 +631,10 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async getUserOperation(options: GetUserOperationOptions): Promise<UserOperation> {
+    Analytics.trackAction({
+      action: "get_user_operation",
+    });
+
     return getUserOperation(CdpOpenApiClient, options);
   }
 
@@ -607,6 +663,11 @@ export class EvmClient implements EvmClientInterface {
    *          ```
    */
   async listAccounts(options: ListServerAccountsOptions = {}): Promise<ListServerAccountResult> {
+    Analytics.trackAction({
+      action: "list_accounts",
+      accountType: "evm_server",
+    });
+
     const ethAccounts = await CdpOpenApiClient.listEvmAccounts({
       pageSize: options.pageSize,
       pageToken: options.pageToken,
@@ -661,6 +722,13 @@ export class EvmClient implements EvmClientInterface {
    * }
    */
   async listTokenBalances(options: ListTokenBalancesOptions): Promise<ListTokenBalancesResult> {
+    Analytics.trackAction({
+      action: "list_token_balances",
+      properties: {
+        network: options.network,
+      },
+    });
+
     return listTokenBalances(CdpOpenApiClient, options);
   }
 
@@ -686,8 +754,13 @@ export class EvmClient implements EvmClientInterface {
    *          while (page.nextPageToken) {
    *            page = await cdp.evm.listSmartAccounts({ pageToken: page.nextPageToken });
    *          }
+   *          ```
    */
   async listSmartAccounts(options: ListSmartAccountsOptions = {}): Promise<ListSmartAccountResult> {
+    Analytics.trackAction({
+      action: "list_smart_accounts",
+    });
+
     const smartAccounts = await CdpOpenApiClient.listEvmSmartAccounts({
       pageSize: options.pageSize,
       pageToken: options.pageToken,
@@ -731,6 +804,13 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async prepareUserOperation(options: PrepareUserOperationOptions): Promise<UserOperation> {
+    Analytics.trackAction({
+      action: "prepare_user_operation",
+      properties: {
+        network: options.network,
+      },
+    });
+
     const userOp = await CdpOpenApiClient.prepareUserOperation(options.smartAccount.address, {
       network: options.network,
       calls: options.calls.map(call => ({
@@ -774,6 +854,13 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async requestFaucet(options: RequestFaucetOptions): Promise<RequestFaucetResult> {
+    Analytics.trackAction({
+      action: "request_faucet",
+      properties: {
+        network: options.network,
+      },
+    });
+
     return requestFaucet(CdpOpenApiClient, options);
   }
 
@@ -824,6 +911,13 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async sendTransaction(options: SendTransactionOptions): Promise<TransactionResult> {
+    Analytics.trackAction({
+      action: "send_transaction",
+      properties: {
+        network: options.network,
+      },
+    });
+
     return sendTransaction(CdpOpenApiClient, options);
   }
 
@@ -858,6 +952,13 @@ export class EvmClient implements EvmClientInterface {
   async sendUserOperation(
     options: SendUserOperationOptions<unknown[]>,
   ): Promise<SendUserOperationReturnType> {
+    Analytics.trackAction({
+      action: "send_user_operation",
+      properties: {
+        network: options.network,
+      },
+    });
+
     return sendUserOperation(CdpOpenApiClient, {
       smartAccount: options.smartAccount,
       network: options.network,
@@ -889,6 +990,10 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async signHash(options: SignHashOptions): Promise<SignatureResult> {
+    Analytics.trackAction({
+      action: "sign_hash",
+    });
+
     const signature = await CdpOpenApiClient.signEvmHash(
       options.address,
       {
@@ -924,6 +1029,10 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async signMessage(options: SignMessageOptions): Promise<SignatureResult> {
+    Analytics.trackAction({
+      action: "sign_message",
+    });
+
     const signature = await CdpOpenApiClient.signEvmMessage(
       options.address,
       {
@@ -983,6 +1092,10 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async signTypedData(options: SignTypedDataOptions): Promise<SignatureResult> {
+    Analytics.trackAction({
+      action: "sign_typed_data",
+    });
+
     const { domain, message, primaryType } = options;
     const types = {
       EIP712Domain: getTypesForEIP712Domain({ domain }),
@@ -1038,6 +1151,10 @@ export class EvmClient implements EvmClientInterface {
    * ```
    */
   async signTransaction(options: SignTransactionOptions): Promise<SignatureResult> {
+    Analytics.trackAction({
+      action: "sign_transaction",
+    });
+
     const signature = await CdpOpenApiClient.signEvmTransaction(
       options.address,
       {
@@ -1093,6 +1210,10 @@ export class EvmClient implements EvmClientInterface {
    *          ```
    */
   async updateAccount(options: UpdateEvmAccountOptions): Promise<ServerAccount> {
+    Analytics.trackAction({
+      action: "update_account",
+    });
+
     const openApiAccount = await CdpOpenApiClient.updateEvmAccount(
       options.address,
       options.update,
@@ -1121,6 +1242,10 @@ export class EvmClient implements EvmClientInterface {
    * @returns A promise that resolves to the updated account.
    */
   async updateSmartAccount(options: UpdateEvmSmartAccountOptions): Promise<SmartAccount> {
+    Analytics.trackAction({
+      action: "update_smart_account",
+    });
+
     const openApiSmartAccount = await CdpOpenApiClient.updateEvmSmartAccount(
       options.address,
       options.update,
@@ -1172,6 +1297,10 @@ export class EvmClient implements EvmClientInterface {
   async waitForUserOperation(
     options: WaitForUserOperationOptions,
   ): Promise<WaitForUserOperationReturnType> {
+    Analytics.trackAction({
+      action: "wait_for_user_operation",
+    });
+
     return waitForUserOperation(CdpOpenApiClient, {
       ...options,
     });

package/client/policies/policies.ts

@@ -7,6 +7,7 @@ import {
   DeletePolicyOptions,
   UpdatePolicyOptions,
 } from "./policies.types.js";
+import { Analytics } from "../../analytics.js";
 import {
   CdpOpenApiClient,
   CreatePolicyBody,
@@ -57,6 +58,13 @@ export class PoliciesClient implements PoliciesClientInterface {
    *          ```
    */
   async listPolicies(options: ListPoliciesOptions = {}): Promise<ListPoliciesResult> {
+    Analytics.trackAction({
+      action: "list_policies",
+      properties: {
+        scope: options.scope,
+      },
+    });
+
     return CdpOpenApiClient.listPolicies(options) as Promise<ListPoliciesResult>;
   }
 
@@ -129,10 +137,18 @@ export class PoliciesClient implements PoliciesClientInterface {
    *          ```
    */
   async createPolicy(options: CreatePolicyOptions): Promise<Policy> {
+    Analytics.trackAction({
+      action: "create_policy",
+      properties: {
+        scope: options.policy.scope,
+      },
+    });
+
     CreatePolicyBodySchema.parse(options.policy);
     return CdpOpenApiClient.createPolicy(
       // There are arbitrary differences between the abitype Abi and the openapi Abi
       options.policy as CreatePolicyBody,
+
       options.idempotencyKey,
     ) as Promise<Policy>;
   }
@@ -156,6 +172,10 @@ export class PoliciesClient implements PoliciesClientInterface {
    *          ```
    */
   async getPolicyById(options: GetPolicyByIdOptions): Promise<Policy> {
+    Analytics.trackAction({
+      action: "get_policy_by_id",
+    });
+
     return CdpOpenApiClient.getPolicyById(options.id) as Promise<Policy>;
   }
 
@@ -188,6 +208,10 @@ export class PoliciesClient implements PoliciesClientInterface {
    *          ```
    */
   async deletePolicy(options: DeletePolicyOptions): Promise<void> {
+    Analytics.trackAction({
+      action: "delete_policy",
+    });
+
     return CdpOpenApiClient.deletePolicy(options.id, options.idempotencyKey);
   }
 
@@ -244,6 +268,10 @@ export class PoliciesClient implements PoliciesClientInterface {
    *          ```
    */
   async updatePolicy(options: UpdatePolicyOptions): Promise<Policy> {
+    Analytics.trackAction({
+      action: "update_policy",
+    });
+
     UpdatePolicyBodySchema.parse(options.policy);
     return CdpOpenApiClient.updatePolicy(
       options.id,