refactor: enhance API documentation and improve code organization (#425)

- Updated JSDoc comments to include `@memberof` annotations for better clarity on class methods.
- Removed unnecessary entries from .gitignore and improved organization.
- Deleted obsolete test file for the Access API, streamlining the test suite.
- Corrected typos in test descriptions for consistency and clarity.
- Improved error handling and response processing across various API clients.

These changes aim to enhance maintainability and readability of the codebase while ensuring accurate documentation for developers.

Author: armando-rodriguez-cko

.gitignore

@@ -50,10 +50,8 @@ out
 /dist/
 .tmp.*
 
-.github/skills/
+.github/skills
 
 docs/
-*_REVIEW.md
 
-swagger-spec.json
 swagger.*

src/api/access/access.js

@@ -1,44 +1,46 @@
-import { determineError } from '../../services/errors.js';
-import { createAccessToken } from '../../services/http.js';
-
-/**
- * Class dealing with the access api
- *
- * @export
- * @class Access
- */
-export default class Access {
-    constructor(config) {
-        this.config = config;
-    }
-
-    /**
-     * Request an access token
-     *
-     * @param {Object} body Access object body.
-     * @return {Promise<Object>} A promise to the Access response.
-     */
-    async request(body) {
-        try {
-            const response = await createAccessToken(this.config, this.config.httpClient, body);
-            return await response.json;
-        } catch (err) {
-            throw await determineError(err);
-        }
-    }
-
-    /**
-     * Update the access details in the config.
-     *
-     * @param {Object} body Access response body.
-     * @return {void}
-     */
-    updateAccessToken(body) {
-        this.config.access = {
-            token: body.access_token,
-            type: body.token_type,
-            scope: body.scope,
-            expires: new Date(new Date().getTime() + body.expires_in),
-        };
-    }
-}
+import { determineError } from '../../services/errors.js';
+import { createAccessToken } from '../../services/http.js';
+
+/**
+ * Class dealing with the access api
+ *
+ * @export
+ * @class Access
+ */
+export default class Access {
+    constructor(config) {
+        this.config = config;
+    }
+
+    /**
+     * Request an access token
+     *
+     * @memberof Access
+     * @param {Object} body Access object body.
+     * @return {Promise<Object>} A promise to the Access response.
+     */
+    async request(body) {
+        try {
+            const response = await createAccessToken(this.config, this.config.httpClient, body);
+            return await response.json;
+        } catch (err) {
+            throw await determineError(err);
+        }
+    }
+
+    /**
+     * Update the access details in the config.
+     *
+     * @memberof Access
+     * @param {Object} body Access response body.
+     * @return {void}
+     */
+    updateAccessToken(body) {
+        this.config.access = {
+            token: body.access_token,
+            type: body.token_type,
+            scope: body.scope,
+            expires: new Date(new Date().getTime() + body.expires_in),
+        };
+    }
+}

src/api/apple-pay/apple-pay.js

@@ -1,87 +1,90 @@
-import { determineError } from '../../services/errors.js';
-import { post } from '../../services/http.js';
-
-/**
- * Class dealing with the Apple Pay api
- *
- * @export
- * @class Apple Pay
- */
-export default class ApplePay {
-    constructor(config) {
-        this.config = config;
-    }
-
-    /**
-     * Upload a payment processing certificate.
-     * This will allow you to start processing payments via Apple Pay.
-     *
-     * @param {Object} body Apple Pay certificate request.
-     * @param {string} body.content The payment processing certificate content.
-     * @return {Promise<Object>} A promise to the Apple Pay certificate response.
-     */
-    async upload(body) {
-        try {
-            const response = await post(
-                this.config.httpClient,
-                `${this.config.host}/applepay/certificates`,
-                this.config,
-                this.config.pk,
-                body
-            );
-            return await response.json;
-        } catch (err) {
-            throw await determineError(err);
-        }
-    }
-
-    /**
-     * Generate a certificate signing request.
-     * You'll need to upload this to your Apple Developer account to download a payment processing certificate.
-     *
-     * @param {Object} body Apple Pay signing request (optional).
-     * @param {string} [body.protocol_version] The protocol version (ec_v1 or rsa_v1). Default: ec_v1.
-     * @return {Promise<Object>} A promise to the Apple Pay signing request response.
-     */
-    async generate(body) {
-        try {
-            const response = await post(
-                this.config.httpClient,
-                `${this.config.host}/applepay/signing-requests`,
-                this.config,
-                this.config.pk,
-                body
-            );
-            return await response.json;
-        } catch (err) {
-            throw await determineError(err);
-        }
-    }
-
-    /**
-     * Enroll a domain to the Apple Pay Service.
-     * Requires OAuth authentication with scope: vault:apme-enrollment
-     *
-     * @param {Object} body Apple Pay enrollment request.
-     * @param {string} body.domain The domain to enroll (e.g., 'https://example.com').
-     * @return {Promise<void>} A promise that resolves when enrollment is successful (204 No Content).
-     */
-    async enroll(body) {
-        try {
-            const response = await post(
-                this.config.httpClient,
-                `${this.config.host}/applepay/enrollments`,
-                this.config,
-                null,
-                body
-            );
-            // 204 No Content - return undefined
-            if (response.status === 204) {
-                return undefined;
-            }
-            return await response.json;
-        } catch (err) {
-            throw await determineError(err);
-        }
-    }
-}
+import { determineError } from '../../services/errors.js';
+import { post } from '../../services/http.js';
+
+/**
+ * Class dealing with the Apple Pay api
+ *
+ * @export
+ * @class Apple Pay
+ */
+export default class ApplePay {
+    constructor(config) {
+        this.config = config;
+    }
+
+    /**
+     * Upload a payment processing certificate.
+     * This will allow you to start processing payments via Apple Pay.
+     *
+     * @memberof ApplePay
+     * @param {Object} body Apple Pay certificate request.
+     * @param {string} body.content The payment processing certificate content.
+     * @return {Promise<Object>} A promise to the Apple Pay certificate response.
+     */
+    async upload(body) {
+        try {
+            const response = await post(
+                this.config.httpClient,
+                `${this.config.host}/applepay/certificates`,
+                this.config,
+                this.config.pk,
+                body
+            );
+            return await response.json;
+        } catch (err) {
+            throw await determineError(err);
+        }
+    }
+
+    /**
+     * Generate a certificate signing request.
+     * You'll need to upload this to your Apple Developer account to download a payment processing certificate.
+     *
+     * @memberof ApplePay
+     * @param {Object} body Apple Pay signing request (optional).
+     * @param {string} [body.protocol_version] The protocol version (ec_v1 or rsa_v1). Default: ec_v1.
+     * @return {Promise<Object>} A promise to the Apple Pay signing request response.
+     */
+    async generate(body) {
+        try {
+            const response = await post(
+                this.config.httpClient,
+                `${this.config.host}/applepay/signing-requests`,
+                this.config,
+                this.config.pk,
+                body
+            );
+            return await response.json;
+        } catch (err) {
+            throw await determineError(err);
+        }
+    }
+
+    /**
+     * Enroll a domain to the Apple Pay Service.
+     * Requires OAuth authentication with scope: vault:apme-enrollment
+     *
+     * @memberof ApplePay
+     * @param {Object} body Apple Pay enrollment request.
+     * @param {string} body.domain The domain to enroll (e.g., 'https://example.com').
+     * @return {Promise<void>} A promise that resolves when enrollment is successful (204 No Content).
+     */
+    async enroll(body) {
+        try {
+            const response = await post(
+                this.config.httpClient,
+                `${this.config.host}/applepay/enrollments`,
+                this.config,
+                null,
+                body
+            );
+            // 204 No Content - return undefined
+            if (response.status === 204) {
+                return undefined;
+            }
+            return await response.json;
+        } catch (err) {
+            throw await determineError(err);
+        }
+    }
+}

src/api/card-metadata/card-metadata.js

@@ -1,36 +1,37 @@
-import { determineError } from '../../services/errors.js';
-import { post } from '../../services/http.js';
-
-/**
- * Class dealing with the /metadata/card endpoint
- *
- * @export
- * @class CardMetadata
- */
-export default class CardMetadata {
-    constructor(config) {
-        this.config = config;
-    }
-
-    /**
-     * Returns a single metadata record for the card specified by the Primary Account Number (PAN),
-     * Bank Identification Number (BIN), token, or instrument supplied.
-     *
-     * @param {Object} body Card Metadata request body.
-     * @return {Promise<Object>} A promise to the add Card Metadata response.
-     */
-    async get(body) {
-        try {
-            const response = await post(
-                this.config.httpClient,
-                `${this.config.host}/metadata/card`,
-                this.config,
-                this.config.sk,
-                body
-            );
-            return await response.json;
-        } catch (err) {
-            throw await determineError(err);
-        }
-    }
-}
+import { determineError } from '../../services/errors.js';
+import { post } from '../../services/http.js';
+
+/**
+ * Class dealing with the /metadata/card endpoint
+ *
+ * @export
+ * @class CardMetadata
+ */
+export default class CardMetadata {
+    constructor(config) {
+        this.config = config;
+    }
+
+    /**
+     * Returns a single metadata record for the card specified by the Primary Account Number (PAN),
+     * Bank Identification Number (BIN), token, or instrument supplied.
+     *
+     * @memberof CardMetadata
+     * @param {Object} body Card Metadata request body.
+     * @return {Promise<Object>} A promise to the Card Metadata response.
+     */
+    async get(body) {
+        try {
+            const response = await post(
+                this.config.httpClient,
+                `${this.config.host}/metadata/card`,
+                this.config,
+                this.config.sk,
+                body
+            );
+            return await response.json;
+        } catch (err) {
+            throw await determineError(err);
+        }
+    }
+}