@coinbase/cdp-sdk 1.1.2 → 1.3.0

package/client/solana/solana.types.ts

@@ -0,0 +1,114 @@
+import {
+  OpenApiSolanaMethods,
+  SolanaAccount as OpenAPISolanaAccount,
+} from "../../openapi-client/index.js";
+/**
+ * The SolanaClient type, where all OpenApiSolanaMethods methods are wrapped.
+ */
+export type SolanaClientInterface = Omit<
+  typeof OpenApiSolanaMethods,
+  | "createSolanaAccount" // mapped to createAccount
+  | "getSolanaAccount" // mapped to getAccount
+  | "getSolanaAccountByName" // mapped to getAccount
+  | "listSolanaAccounts" // mapped to listAccounts
+  | "requestSolanaFaucet" // mapped to requestFaucet
+  | "signSolanaMessage" // mapped to signMessage
+  | "signSolanaTransaction" // mapped to signTransaction
+> & {
+  createAccount: (options: CreateAccountOptions) => Promise<Account>;
+  getAccount: (options: GetAccountOptions) => Promise<Account>;
+  listAccounts: (options: ListAccountsOptions) => Promise<ListAccountsResult>;
+  requestFaucet: (options: RequestFaucetOptions) => Promise<SignatureResult>;
+  signMessage: (options: SignMessageOptions) => Promise<SignatureResult>;
+  signTransaction: (options: SignTransactionOptions) => Promise<SignatureResult>;
+};
+/**
+ * A Solana account.
+ */
+export type Account = OpenAPISolanaAccount;
+
+/**
+ * Options for creating a Solana account.
+ */
+export interface CreateAccountOptions {
+  /** The name of the account. */
+  name?: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for getting a Solana account.
+ */
+export interface GetAccountOptions {
+  /** The address of the account. */
+  address?: string;
+  /** The name of the account. */
+  name?: string;
+}
+
+/**
+ * Options for listing Solana accounts.
+ */
+export interface ListAccountsOptions {
+  /** The page size. */
+  pageSize?: number;
+  /** The page token. */
+  pageToken?: string;
+}
+
+/**
+ * The result of listing Solana accounts.
+ */
+export interface ListAccountsResult {
+  /** The accounts. */
+  accounts: Account[];
+  /**
+   * The token for the next page of accounts, if any.
+   */
+  nextPageToken?: string;
+}
+
+/**
+ * Options for requesting funds from a Solana faucet.
+ */
+export interface RequestFaucetOptions {
+  /** The address of the account. */
+  address: string;
+  /** The token to request funds for. */
+  token: "sol" | "usdc";
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for signing a Solana message.
+ */
+export interface SignMessageOptions {
+  /** The address of the account. */
+  address: string;
+  /** The message to sign. */
+  message: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * Options for signing a Solana transaction.
+ */
+export interface SignTransactionOptions {
+  /** The address of the account. */
+  address: string;
+  /** The base64 encoded transaction to sign. */
+  transaction: string;
+  /** The idempotency key. */
+  idempotencyKey?: string;
+}
+
+/**
+ * A Solana signature result.
+ */
+export interface SignatureResult {
+  /** The signature. */
+  signature: string;
+}

package/constants.ts

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

package/errors.ts

@@ -0,0 +1,17 @@
+/**
+ * TimeoutError is thrown when an operation times out.
+ */
+export class TimeoutError extends Error {
+  /**
+   * Initializes a new TimeoutError instance.
+   *
+   * @param message - The error message.
+   */
+  constructor(message: string = "Timeout Error") {
+    super(message);
+    this.name = "TimeoutError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, TimeoutError);
+    }
+  }
+}

package/index.ts

@@ -0,0 +1,4 @@
+import "./analytics.js";
+
+export { CdpClient } from "./client/cdp.js";
+export type { EvmServerAccount, EvmSmartAccount } from "./accounts/types.js";

package/openapi-client/cdpApiClient.ts

@@ -0,0 +1,221 @@
+// eslint-disable-next-line import/no-named-as-default
+import Axios, { AxiosInstance, AxiosRequestConfig } from "axios";
+
+import { withAuth } from "../auth/hooks/axios/index.js";
+import { ERROR_DOCS_PAGE_URL } from "../constants.js";
+import {
+  isOpenAPIError,
+  APIError,
+  HttpErrorType,
+  UnknownApiError,
+  UnknownError,
+} from "./errors.js";
+
+/**
+ * The options for the CDP API.
+ */
+export type CdpOptions = {
+  /**
+   * The API key ID or the legacy API key name.
+   *
+   * Examples:
+   *  ID format: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+   *  Legacy name format: 'organizations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/apiKeys/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+   */
+  apiKeyId: string;
+
+  /**
+   * The API key secret, using the Ed25519 or legacy EC key format.
+   *
+   * Examples:
+   *  Ed25519 key: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=='
+   *  EC key: '-----BEGIN EC PRIVATE KEY-----\n...\n...\n...==\n-----END EC PRIVATE KEY-----\n'
+   */
+  apiKeySecret: string;
+
+  /** The Wallet Secret. Only needed if calling certain Wallet APIs. */
+  walletSecret?: string;
+
+  /** If true, logs API requests and responses to the console. */
+  debugging?: boolean;
+
+  /** The base path for the API. */
+  basePath?: string;
+
+  /** The source for the API request, used for analytics. Defaults to `typescript-client`. */
+  source?: string;
+
+  /** The version of the source for the API request, used for analytics. */
+  sourceVersion?: string;
+
+  /** Optional expiration time in seconds (defaults to 120) */
+  expiresIn?: number;
+};
+
+let axiosInstance: AxiosInstance;
+
+/**
+ * Configures the CDP client with the given options.
+ *
+ * @param {CdpOptions} options - The CDP options.
+ */
+export const configure = (options: CdpOptions) => {
+  axiosInstance = Axios.create({
+    baseURL: options.basePath || "https://api.cdp.coinbase.com/platform",
+  });
+
+  axiosInstance = withAuth(axiosInstance, {
+    apiKeyId: options.apiKeyId,
+    apiKeySecret: options.apiKeySecret,
+    source: options.source || "sdk-openapi-client",
+    sourceVersion: options.sourceVersion,
+    walletSecret: options.walletSecret,
+    expiresIn: options.expiresIn,
+    debug: options.debugging,
+  });
+};
+
+/**
+ * Adds an idempotency key to request config if provided
+ *
+ * @param config - The Axios request configuration.
+ * @param idempotencyKey - The idempotency key.
+ * @returns The Axios request configuration with the idempotency key.
+ */
+const addIdempotencyKey = (
+  config: AxiosRequestConfig,
+  idempotencyKey?: string,
+): AxiosRequestConfig => {
+  if (!idempotencyKey) {
+    return config;
+  }
+
+  return {
+    ...config,
+    headers: {
+      ...(config.headers || {}),
+      "X-Idempotency-Key": idempotencyKey,
+    },
+  };
+};
+
+/**
+ * Mutates the given Axios request configuration to add the CDP API key signature
+ * to the request headers.
+ *
+ * @param {AxiosRequestConfig} config - The Axios request configuration.
+ * @param idempotencyKey - The idempotency key.
+ * @returns {Promise<T>} A promise that resolves to the response data.
+ * @throws {APIError} If the request fails.
+ */
+export const cdpApiClient = async <T>(
+  config: AxiosRequestConfig,
+  idempotencyKey?: string,
+): Promise<T> => {
+  validateCall(config);
+
+  // Add idempotency key to the request headers if provided
+  const configWithIdempotencyKey = addIdempotencyKey(config, idempotencyKey);
+
+  try {
+    const response = await axiosInstance(configWithIdempotencyKey);
+    return response.data as T;
+  } catch (error) {
+    // eslint-disable-next-line import/no-named-as-default-member
+    if (Axios.isAxiosError(error) && !error.response) {
+      throw new UnknownApiError(
+        HttpErrorType.unknown,
+        error.cause instanceof Error ? error.cause.message : error.message,
+        error.cause,
+      );
+    }
+
+    // eslint-disable-next-line import/no-named-as-default-member
+    if (Axios.isAxiosError(error) && error.response) {
+      if (isOpenAPIError(error.response.data)) {
+        throw new APIError(
+          error.response.status,
+          error.response.data.errorType,
+          error.response.data.errorMessage,
+          error.response.data.correlationId,
+          error.response.data.errorLink,
+          error.cause,
+        );
+      } else {
+        const statusCode = error.response.status;
+        switch (statusCode) {
+          case 401:
+            throw new APIError(
+              statusCode,
+              HttpErrorType.unauthorized,
+              "Unauthorized.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}#unauthorized`,
+              error.cause,
+            );
+          case 404:
+            throw new APIError(
+              statusCode,
+              HttpErrorType.not_found,
+              "API not found.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}#not_found`,
+              error.cause,
+            );
+          case 502:
+            throw new APIError(
+              statusCode,
+              HttpErrorType.bad_gateway,
+              "Bad gateway.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}`,
+              error.cause,
+            );
+          case 503:
+            throw new APIError(
+              statusCode,
+              HttpErrorType.service_unavailable,
+              "Service unavailable. Please try again later.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}`,
+              error.cause,
+            );
+          default:
+            throw new APIError(
+              statusCode,
+              HttpErrorType.unexpected_error,
+              "An unexpected error occurred.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}`,
+              error.cause,
+            );
+        }
+      }
+    }
+
+    throw new UnknownError(
+      "Something went wrong. Please reach out at https://discord.com/channels/1220414409550336183/1271495764580896789 for help.",
+      error instanceof Error ? error : undefined,
+    );
+  }
+};
+
+/**
+ * Validates the call to the cdpApiClient.
+ *
+ * @param {AxiosRequestConfig} config - The Axios request configuration.
+ * @throws {Error} If the call is not valid.
+ */
+const validateCall = (config: AxiosRequestConfig) => {
+  if (!axiosInstance.getUri() || axiosInstance.getUri() === "") {
+    throw new Error("CDP client URI not configured. Call configure() first.");
+  }
+
+  if (!config.url || config.url === "") {
+    throw new Error("AxiosRequestConfig URL is empty. This should never happen.");
+  }
+
+  if (!config.method || config.method === "") {
+    throw new Error("AxiosRequestConfig method is empty. This should never happen.");
+  }
+};

package/openapi-client/errors.ts

@@ -0,0 +1,132 @@
+import {
+  Error as OpenAPIError,
+  ErrorType as OpenAPIErrorType,
+} from "./generated/coinbaseDeveloperPlatformAPIs.schemas.js";
+
+export const HttpErrorType = {
+  unexpected_error: "unexpected_error",
+  unauthorized: "unauthorized",
+  not_found: "not_found",
+  bad_gateway: "bad_gateway",
+  service_unavailable: "service_unavailable",
+  unknown: "unknown",
+} as const;
+
+export type HttpErrorType = (typeof HttpErrorType)[keyof typeof HttpErrorType];
+
+/**
+ * Extended error codes that include both OpenAPI errors and network errors
+ */
+export type APIErrorType = OpenAPIErrorType | HttpErrorType;
+
+/**
+ * Extended API error that encompasses both OpenAPI errors and other API-related errors
+ */
+export class APIError extends Error {
+  statusCode: number;
+  errorType: APIErrorType;
+  errorMessage: string;
+  correlationId?: string;
+  errorLink?: string;
+
+  /**
+   * Constructor for the APIError class
+   *
+   * @param statusCode - The HTTP status code
+   * @param errorType - The type of error
+   * @param errorMessage - The error message
+   * @param correlationId - The correlation ID
+   * @param errorLink - URL to documentation about this error
+   * @param cause - The cause of the error
+   */
+  constructor(
+    statusCode: number,
+    errorType: APIErrorType,
+    errorMessage: string,
+    correlationId?: string,
+    errorLink?: string,
+    cause?: Error,
+  ) {
+    super(errorMessage, { cause });
+    this.name = "APIError";
+    this.statusCode = statusCode;
+    this.errorType = errorType;
+    this.errorMessage = errorMessage;
+
+    // Only set correlationId if it's defined
+    if (correlationId !== undefined) {
+      this.correlationId = correlationId;
+    }
+
+    // Only set errorLink if it's defined
+    if (errorLink !== undefined) {
+      this.errorLink = errorLink;
+    }
+  }
+
+  /**
+   * Convert the error to a JSON object, excluding undefined properties
+   *
+   * @returns The error as a JSON object
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      statusCode: this.statusCode,
+      errorType: this.errorType,
+      errorMessage: this.errorMessage,
+      ...(this.correlationId && { correlationId: this.correlationId }),
+      ...(this.errorLink && { errorLink: this.errorLink }),
+    };
+  }
+}
+
+/**
+ * Error thrown when an Axios request is made but no response is received
+ */
+export class UnknownApiError extends APIError {
+  /**
+   * Constructor for the UnknownApiError class
+   *
+   * @param errorType - The type of error
+   * @param errorMessage - The error message
+   * @param cause - The cause of the error
+   */
+  constructor(errorType: APIErrorType, errorMessage: string, cause?: Error) {
+    super(0, errorType, errorMessage, undefined, undefined, cause);
+    this.name = "UnknownApiError";
+  }
+}
+
+/**
+ * Error thrown when an error is not known
+ */
+export class UnknownError extends Error {
+  /**
+   * Constructor for the UnknownError class
+   *
+   * @param message - The error message
+   * @param cause - The cause of the error
+   */
+  constructor(message: string, cause?: Error) {
+    super(message, { cause });
+    this.name = "UnknownError";
+  }
+}
+
+/**
+ * Type guard to check if an object is an OpenAPIError
+ *
+ * @param obj - The object to check
+ * @returns True if the object is an OpenAPIError
+ */
+export function isOpenAPIError(obj: unknown): obj is OpenAPIError {
+  return (
+    obj !== null &&
+    typeof obj === "object" &&
+    "errorType" in obj &&
+    typeof (obj as OpenAPIError).errorType === "string" &&
+    "errorMessage" in obj &&
+    typeof (obj as OpenAPIError).errorMessage === "string"
+  );
+}