[WIP] Init wallet class

.eslintrc.json

@@ -3,7 +3,8 @@
   "extends": [
     "eslint:recommended",
     "plugin:@typescript-eslint/recommended",
-    "plugin:prettier/recommended"
+    "plugin:prettier/recommended",
+    "plugin:jsdoc/recommended"
   ],
   "plugins": ["@typescript-eslint", "prettier"],
   "env": {
@@ -16,7 +17,34 @@
   },
   "rules": {
     "multiline-comment-style": ["error", "starred-block"],
-    "prettier/prettier": "error"
+    "prettier/prettier": "error",
+    "jsdoc/tag-lines": ["error", "any", { "startLines": 1 }],
+    "jsdoc/check-alignment": "error",
+    "jsdoc/no-undefined-types": "off",
+    "jsdoc/check-param-names": "error",
+    "jsdoc/check-tag-names": "error",
+    "jsdoc/check-types": "error",
+    "jsdoc/implements-on-classes": "error",
+    "jsdoc/require-description": "error",
+    "jsdoc/require-jsdoc": [
+      "error",
+      {
+        "require": {
+          "FunctionDeclaration": true,
+          "MethodDefinition": true,
+          "ClassDeclaration": true,
+          "ArrowFunctionExpression": false,
+          "FunctionExpression": false
+        }
+      }
+    ],
+    "jsdoc/require-param": "error",
+    "jsdoc/require-param-description": "error",
+    "jsdoc/require-param-type": "off",
+    "jsdoc/require-returns": "error",
+    "jsdoc/require-returns-description": "error",
+    "jsdoc/require-returns-type": "off",
+    "jsdoc/require-hyphen-before-param-description": ["error", "always"]
   },
-  "ignorePatterns": ["src/**/__tests__/**", "src/**/*.test.ts"]
+  "ignorePatterns": ["src/**/__tests__/**", "src/**/*.test.ts", "src/client/**"]
 }

package.json

@@ -7,8 +7,8 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "lint": "eslint -c .eslintrc.json src/**/*.ts",
-    "lint-fix": "eslint -c .eslintrc.json src/**/*.ts --fix",
+    "lint": "eslint -c .eslintrc.json src/coinbase/*.ts",
+    "lint-fix": "eslint -c .eslintrc.json src/coinbase/*.ts --fix",
     "format": "prettier -c .prettierrc --write \"**/*.{ts,js,cjs,json,md}\"",
     "format-check": "prettier -c .prettierrc --check \"**/*.{ts,js,cjs,json,md}\"",
     "check": "tsc --noEmit",
@@ -39,6 +39,7 @@
     "axios-mock-adapter": "^1.22.0",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-jsdoc": "^48.2.5",
     "eslint-plugin-prettier": "^5.1.3",
     "jest": "^29.7.0",
     "mock-fs": "^5.2.0",

src/coinbase/address.ts

@@ -1,22 +1,23 @@
 import { Address as AddressModel } from "../client";
 import { InternalError } from "./errors";
 import { FaucetTransaction } from "./faucet_transaction";
-import { AddressClient } from "./types";
+import { AddressAPIClient } from "./types";
 
 /**
- * Class representing an Address in the Coinbase SDK.
+ * A representation of a blockchain address, which is a user-controlled account on a network.
  */
 export class Address {
   private model: AddressModel;
-  private client: AddressClient;
+  private client: AddressAPIClient;
 
   /**
-   * Creates an instance of Address.
+   * Initializes a new Address instance.
+   *
    * @param {AddressModel} model - The address model data.
-   * @param {AddressClient} client - The API client to interact with address-related endpoints.
+   * @param {AddressAPIClient} client - The API client to interact with address-related endpoints.
    * @throws {InternalError} If the model or client is empty.
    */
-  constructor(model: AddressModel, client: AddressClient) {
+  constructor(model: AddressModel, client: AddressAPIClient) {
     if (!model) {
       throw new InternalError("Address model cannot be empty");
     }
@@ -29,48 +30,50 @@ export class Address {
 
   /**
    * Requests faucet funds for the address.
+   * Only supported on testnet networks.
+   *
    * @returns {Promise<FaucetTransaction>} The faucet transaction object.
    * @throws {InternalError} If the request does not return a transaction hash.
    * @throws {Error} If the request fails.
    */
   async faucet(): Promise<FaucetTransaction> {
-    try {
-      const response = await this.client.requestFaucetFunds(
-        this.model.wallet_id,
-        this.model.address_id,
-      );
-      return new FaucetTransaction(response.data);
-    } catch (e) {
-      throw new Error(`Failed to request faucet funds`);
-    }
+    const response = await this.client.requestFaucetFunds(
+      this.model.wallet_id,
+      this.model.address_id,
+    );
+    return new FaucetTransaction(response.data);
   }
 
   /**
-   * Gets the address ID.
+   * Returns the address ID.
+   *
    * @returns {string} The address ID.
    */
   public getId(): string {
     return this.model.address_id;
   }
 
   /**
-   * Gets the network ID.
+   * Returns the network ID.
+   *
    * @returns {string} The network ID.
    */
   public getNetworkId(): string {
     return this.model.network_id;
   }
 
   /**
-   * Gets the public key.
+   * Returns the public key.
+   *
    * @returns {string} The public key.
    */
   public getPublicKey(): string {
     return this.model.public_key;
   }
 
   /**
-   * Gets the wallet ID.
+   * Returns the wallet ID.
+   *
    * @returns {string} The wallet ID.
    */
   public getWalletId(): string {
@@ -79,6 +82,7 @@ export class Address {
 
   /**
    * Returns a string representation of the address.
+   *
    * @returns {string} A string representing the address.
    */
   public toString(): string {

src/coinbase/api_error.ts

@@ -0,0 +1,134 @@
+/* eslint-disable jsdoc/require-jsdoc */
+import { AxiosError } from "axios";
+import { InternalError } from "./errors";
+
+/**
+ * The API error response type.
+ */
+type APIErrorResponseType = {
+  code: string;
+  message: string;
+};
+
+/**
+ * A wrapper for API errors to provide more context.
+ */
+export class APIError extends AxiosError {
+  httpCode: number | null;
+  apiCode: string | null;
+  apiMessage: string | null;
+
+  /**
+   * Initializes a new APIError object.
+   *
+   * @class
+   * @param {AxiosError} error - The Axios error.
+   */
+  constructor(error) {
+    super();
+    this.name = this.constructor.name;
+    this.httpCode = error.response ? error.response.status : null;
+    this.apiCode = null;
+    this.apiMessage = null;
+
+    if (error.response && error.response.data) {
+      const body = error.response.data;
+      this.apiCode = body.code;
+      this.apiMessage = body.message;
+    }
+  }
+
+  /**
+   * Creates a specific APIError based on the API error code.
+   *
+   * @param {AxiosError} error - The underlying error object.
+   * @returns {APIError} A specific APIError instance.
+   */
+  static fromError(error: AxiosError) {
+    const apiError = new APIError(error);
+    if (!error.response || !error.response.data) {
+      return apiError;
+    }
+
+    const body = error?.response?.data as APIErrorResponseType;
+    switch (body?.code) {
+      case "unimplemented":
+        return new UnimplementedError(error);
+      case "unauthorized":
+        return new UnauthorizedError(error);
+      case "internal":
+        return new InternalError(error.message);
+      case "not_found":
+        return new NotFoundError(error);
+      case "invalid_wallet_id":
+        return new InvalidWalletIDError(error);
+      case "invalid_address_id":
+        return new InvalidAddressIDError(error);
+      case "invalid_wallet":
+        return new InvalidWalletError(error);
+      case "invalid_address":
+        return new InvalidAddressError(error);
+      case "invalid_amount":
+        return new InvalidAmountError(error);
+      case "invalid_transfer_id":
+        return new InvalidTransferIDError(error);
+      case "invalid_page_token":
+        return new InvalidPageError(error);
+      case "invalid_page_limit":
+        return new InvalidLimitError(error);
+      case "already_exists":
+        return new AlreadyExistsError(error);
+      case "malformed_request":
+        return new MalformedRequestError(error);
+      case "unsupported_asset":
+        return new UnsupportedAssetError(error);
+      case "invalid_asset_id":
+        return new InvalidAssetIDError(error);
+      case "invalid_destination":
+        return new InvalidDestinationError(error);
+      case "invalid_network_id":
+        return new InvalidNetworkIDError(error);
+      case "resource_exhausted":
+        return new ResourceExhaustedError(error);
+      case "faucet_limit_reached":
+        return new FaucetLimitReachedError(error);
+      case "invalid_signed_payload":
+        return new InvalidSignedPayloadError(error);
+      case "invalid_transfer_status":
+        return new InvalidTransferStatusError(error);
+      default:
+        return apiError;
+    }
+  }
+
+  /**
+   * Returns a String representation of the APIError.
+   *
+   * @returns {string} a String representation of the APIError
+   */
+  toString() {
+    return `APIError{httpCode: ${this.httpCode}, apiCode: ${this.apiCode}, apiMessage: ${this.apiMessage}}`;
+  }
+}
+
+export class UnimplementedError extends APIError {}
+export class UnauthorizedError extends APIError {}
+export class NotFoundError extends APIError {}
+export class InvalidWalletIDError extends APIError {}
+export class InvalidAddressIDError extends APIError {}
+export class InvalidWalletError extends APIError {}
+export class InvalidAddressError extends APIError {}
+export class InvalidAmountError extends APIError {}
+export class InvalidTransferIDError extends APIError {}
+export class InvalidPageError extends APIError {}
+export class InvalidLimitError extends APIError {}
+export class AlreadyExistsError extends APIError {}
+export class MalformedRequestError extends APIError {}
+export class UnsupportedAssetError extends APIError {}
+export class InvalidAssetIDError extends APIError {}
+export class InvalidDestinationError extends APIError {}
+export class InvalidNetworkIDError extends APIError {}
+export class ResourceExhaustedError extends APIError {}
+export class FaucetLimitReachedError extends APIError {}
+export class InvalidSignedPayloadError extends APIError {}
+export class InvalidTransferStatusError extends APIError {}

src/coinbase/authenticator.ts

@@ -5,14 +5,16 @@ import { InvalidAPIKeyFormat } from "./errors";
 const pemHeader = "-----BEGIN EC PRIVATE KEY-----";
 const pemFooter = "-----END EC PRIVATE KEY-----";
 
-/* A class that builds JWTs for authenticating with the Coinbase Platform APIs. */
+/**
+ * A class that builds JWTs for authenticating with the Coinbase Platform APIs.
+ */
 export class CoinbaseAuthenticator {
   private apiKey: string;
   private privateKey: string;
 
   /**
    * Initializes the Authenticator.
-   * @constructor
+   *
    * @param {string} apiKey - The API key name.
    * @param {string} privateKey - The private key associated with the API key.
    */
@@ -23,6 +25,7 @@ export class CoinbaseAuthenticator {
 
   /**
    * Middleware to intercept requests and add JWT to Authorization header.
+   *
    * @param {InternalAxiosRequestConfig} config - The request configuration.
    * @param {boolean} debugging - Flag to enable debugging.
    * @returns {Promise<InternalAxiosRequestConfig>} The request configuration with the Authorization header added.
@@ -44,6 +47,7 @@ export class CoinbaseAuthenticator {
 
   /**
    * Builds the JWT for the given API endpoint URL.
+   *
    * @param {string} url - URL of the API endpoint.
    * @param {string} method - HTTP method of the request.
    * @returns {Promise<string>} JWT token.
@@ -93,6 +97,7 @@ export class CoinbaseAuthenticator {
 
   /**
    * Extracts the PEM key from the given private key string.
+   *
    * @param {string} privateKeyString - The private key string.
    * @returns {string} The PEM key.
    * @throws {InvalidAPIKeyFormat} If the private key string is not in the correct format.
@@ -109,6 +114,7 @@ export class CoinbaseAuthenticator {
 
   /**
    * Generates a random nonce for the JWT.
+   *
    * @returns {string} The generated nonce.
    */
   private nonce(): string {