@coinbase/cdp-sdk 1.1.2 → 1.2.0

package/openapi-client/cdpApiClient.ts

@@ -0,0 +1,214 @@
+// eslint-disable-next-line import/no-named-as-default
+import Axios, { AxiosInstance, AxiosRequestConfig, HttpStatusCode } from "axios";
+
+import { APIError, isOpenAPIError, HttpErrorType } from "./errors.js";
+import { withAuth } from "../auth/hooks/axios/index.js";
+import { ERROR_DOCS_PAGE_URL } from "../constants.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) {
+      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,
+        );
+      } else {
+        const statusCode = error.response.status;
+        switch (statusCode) {
+          case 401:
+            throw new APIError(
+              statusCode,
+              HttpErrorType.unauthorized,
+              "Unauthorized.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}#unauthorized`,
+            );
+          case 404:
+            throw new APIError(
+              statusCode,
+              HttpErrorType.not_found,
+              "API not found.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}#not_found`,
+            );
+          case 502:
+            throw new APIError(
+              statusCode,
+              HttpErrorType.bad_gateway,
+              "Bad gateway.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}`,
+            );
+          case 503:
+            throw new APIError(
+              statusCode,
+              HttpErrorType.service_unavailable,
+              "Service unavailable. Please try again later.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}`,
+            );
+          default:
+            throw new APIError(
+              statusCode,
+              HttpErrorType.unexpected_error,
+              "An unexpected error occurred.",
+              undefined,
+              `${ERROR_DOCS_PAGE_URL}`,
+            );
+        }
+      }
+      // eslint-disable-next-line import/no-named-as-default-member
+    } else if (Axios.isAxiosError(error) && error.request) {
+      throw new APIError(
+        HttpStatusCode.ServiceUnavailable,
+        HttpErrorType.service_unavailable,
+        "Network error, unable to reach the service.",
+        undefined,
+        `${ERROR_DOCS_PAGE_URL}`,
+      );
+    } else {
+      throw new APIError(
+        HttpStatusCode.InternalServerError,
+        HttpErrorType.unexpected_error,
+        error instanceof Error
+          ? error.message
+          : `An unexpected error occurred: ${JSON.stringify(error, Object.getOwnPropertyNames(error))}`,
+        undefined,
+        `${ERROR_DOCS_PAGE_URL}`,
+      );
+    }
+  }
+};
+
+/**
+ * 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,96 @@
+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",
+} 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
+   */
+  constructor(
+    statusCode: number,
+    errorType: APIErrorType,
+    errorMessage: string,
+    correlationId?: string,
+    errorLink?: string,
+  ) {
+    super(errorMessage);
+    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 }),
+    };
+  }
+}
+
+/**
+ * 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"
+  );
+}