@amazon-sp-api-release/amazon-sp-api-sdk-js 1.0.0-rc6 → 1.0.0-rc8

package/README.md

@@ -49,42 +49,39 @@ Add the following line to the `dependencies` in your `package.json` file:
 
 In order to call one of the APIs included in the Selling Partner API, you need to:
 1. Configure credentials (Note: Use your individual credentials for `clientId`, `clientSecret` and `refreshToken`)
-2. Retrieve `accessToken` using our `LwaAuthClient` helper (Be aware for some APIs, you will need extra step to get `RDT Token`)
+2. Enable auto `accessToken` retrievel using our built in ApiClient function OR retrieve `accessToken` using our `LwaAuthClient` helper (Be aware for some APIs, you will need extra step to get `RDT Token`)
 2. Create an instance for a specific API and API client, then apply `accessToken` to it.
-3. Call an operation
+3. Call an API operation
 
 For an example, refer to the following sample code for connecting to Sellers API:
 
 ```javascript
-import { LwaAuthClient } from '@amazon-sp-api-release/amazon-sp-api-sdk-js';
-
 import {
   SellersSpApi
 } from '@amazon-sp-api-release/amazon-sp-api-sdk-js';
 
-(async () => {
-  const lwaClient = new LwaAuthClient(
-    '<YOUR_CLIENT_ID>',
-    '<YOUR_CLIENT_SECRET>',
-    '<YOUR_REFRESH_TOKEN>'
-  );
-  const sellerApiClient = new SellersSpApi.ApiClient(
-    'https://sellingpartnerapi-na.amazon.com'
-  );
-
-  const sellerApi = new SellersSpApi.SellersApi(sellerApiClient);
-  sellerApiClient.applyXAmzAccessTokenToRequest(
-    await lwaClient.getAccessToken()
-  );
-  const participations = await sellerApi.getMarketplaceParticipations();
-  console.log(
-    JSON.stringify(participations, null, '  ') +
-      '\n**********************************'
-  );
-})();
+async function getMarketplaceParticipations() {
+  try {
+      //Configure Sellers ApiClient
+      const sellersApiClient = new SellersSpApi.ApiClient(AppConfig.spApiNAEndpoint);
+      sellersApiClient.enableAutoRetrievalAccessToken('<YOUR_CLIENT_ID>','<YOUR_CLIENT_SECRET>', '<YOUR_REFRESH_TOKEN>' null);
+      const sellersApi = new SellersSpApi.SellersApi(sellersApiClient);
+      
+      //Call GetMarkerplaceParticipations API
+      const participations = await sellersApi.getMarketplaceParticipations();
+      console.log(
+        JSON.stringify(participations, null, ' ') + 
+          '\n**********************************'
+      )
+  } catch (error) {
+      console.error('Exception when calling getMarketplaceParticipations API', error.message);
+  }
+}
+
+getMarketplaceParticipations();
 ```
 
-Alternatively, you can go to `@amazon-sp-api-release/amazon-sp-api-sdk-js/sample-node-app` and copy over and modify `index.js` and `app.config.mjs` files and give them a try.
+Alternatively, you can go to `@amazon-sp-api-release/amazon-sp-api-sdk-js/sample-node-app` and copy over and modify `index.js` and `app.config.mjs` files and give them a try. You can see multiple API operation call sampleswith various way of retrieving token, as well how to set up rate limiter and retry logic when making API calls.
 
 ##### Additional Note: 
 This Amazon Selling Partner API JavaScript SDK is fully compatible with ECMAScript modules (ESM). You can use modern ES6+ import/export syntax as demonstrated in the example code:

package/helper/DefaultRateLimitFetcher.mjs

@@ -0,0 +1,59 @@
+import { parse } from 'yaml';
+import { readFile } from 'fs/promises';
+import { RateLimitConfiguration } from './RateLimitConfiguration.mjs';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { join } from 'path';
+
+export class DefaultRateLimitFetcher {
+
+    #defaultRateLimitMap;
+
+    constructor() {
+        this.#defaultRateLimitMap = null;
+    }
+
+    // Initialize the configuration by loading the YAML file
+    async init() {
+        const fileName = fileURLToPath(import.meta.url);
+        const dirName = dirname(fileName);
+        try {
+            const fileContents = await readFile(join(dirName, 'rate-limits.yml'), 'utf8');            
+            this.#defaultRateLimitMap = parse(fileContents);
+        } catch (error) {
+            this.#defaultRateLimitMap = {};
+            throw new error('Error loading rate-limits.yml:', error);
+        }
+    }
+
+    getLimit(operation) {
+        const burst = this.getValue(operation, 1);
+        const rateLimitPermit = this.getValue(operation, 0) / this.getValue(operation, 2);
+        return new RateLimitConfiguration(rateLimitPermit, burst);
+    }
+
+    getValue(operation, position) {
+        if (this.#defaultRateLimitMap && 
+            this.#defaultRateLimitMap[operation] && 
+            position < this.#defaultRateLimitMap[operation].length) {
+            return this.#defaultRateLimitMap[operation][position];
+        }
+        return 1;
+    }
+
+    // Singleton implementation
+    static #instance = null;
+
+    static async create() {
+        const instance = new DefaultRateLimitFetcher();
+        await instance.init();
+        return instance;
+    }
+
+    static async getInstance() {
+        if (!DefaultRateLimitFetcher.#instance) {
+            DefaultRateLimitFetcher.#instance = await DefaultRateLimitFetcher.create();
+        }
+        return DefaultRateLimitFetcher.#instance;
+    }
+}

package/helper/LwaAuthClient.mjs

@@ -1,31 +1,39 @@
 import superagent from 'superagent';
 
 export class LwaAuthClient {
-    #clientId = null;
-    #clientSecret = null;
-    #refreshToken = null;
-    #accessToken = null;
-    #accessTokenExpiry = null;
+    /**
+    * Private variable to store LWA credential and refresh token.
+    * @type {Object<String, String>}
+    */
+    #lwaClientInfo = {};
+
+    /**
+    * Private variable to cache access token that is retrieved by auto-retrieval.
+    * @type {Map<String, {String, Number}> | null}
+    */
+    #cachedTokenMap = null;
+    
     /**
     * Constructs a new LwaAuthClient. 
     * @class
     * @param {String} clientId LWA client ID. Get this value from SP-API Developer Portal.
     * @param {String} clientSecret LWA client secret. Get this value from SP-API Developer Portal.
-    * @param {String} refreshToken LWA refresh token. Get this value from SP-API Developer Portal.
+    * @param {String|null} refreshToken LWA refresh token. Get this value from SP-API Developer Portal.
+    * @param {String|null} scope LWA scope(s) for grantless operations
     */
-    constructor(clientId, clientSecret, refreshToken) {
+    constructor(clientId, clientSecret, refreshToken = null, scope = null) {
         if (!clientId || typeof clientId !== 'string') {
             throw new Error(`invalid clientId.`);
         }
         if (!clientSecret || typeof clientSecret !== 'string') {
             throw new Error(`invalid clientSecret`);
         }
-        if (!refreshToken || typeof refreshToken !== 'string') {
-            throw new Error(`invalid refreshToken`);
+        if ((!refreshToken && !scope) || (refreshToken && scope)) {
+            throw new Error(`Either refreshToken or scope must be defined`);
         }
-        this.#clientId = clientId;
-        this.#clientSecret = clientSecret;
-        this.#refreshToken = refreshToken;
+        this.#lwaClientInfo = {
+            clientId, clientSecret, refreshToken, scope
+        };
     }
 
     /**
@@ -33,17 +41,30 @@ export class LwaAuthClient {
     * @returns {Promise<String>} LWA access token.
     */
     async getAccessToken() {
-        if (this.#accessToken && this.#accessToken && this.#accessTokenExpiry > Date.now()) {
-            console.log(`LWA access token already exists and is valid. ${this.#accessTokenExpiry}`);
-            return Promise.resolve(this.#accessToken);
+        const key = JSON.stringify(this.#lwaClientInfo);
+        
+        if (this.#cachedTokenMap) {
+            const cachedTokenItem = this.#cachedTokenMap.get(key);
+
+            if (cachedTokenItem) {
+                const cachedToken = cachedTokenItem.cachedToken;
+                const cachedTokenExpiration = cachedTokenItem.cachedTokenExpiration;
+                //Adjustment in milliseconds (60s) to avoid using nearly expired tokens
+                const adjustedExpiryTime = cachedTokenExpiration - 60000;
+                if (adjustedExpiryTime > Date.now()) {
+                    return Promise.resolve(cachedToken); 
+                } else {
+                    this.#cachedTokenMap.delete(key);
+                }
+            }            
         }
-        const token = await this.#doRefresh();
-        if (!token || !token.access_token) {
-            throw new Error(`Failed to refresh LWA token.`);
+
+        const res = await this.#doRefresh();
+        if (!this.#cachedTokenMap) {
+            this.#cachedTokenMap = new Map();
         }
-        this.#accessToken = token.access_token;
-        this.#accessTokenExpiry = new Date().getTime() + (token.expires_in * 1000);
-        return this.#accessToken;
+        this.#cachedTokenMap.set(key, {cachedToken: res.access_token, cachedTokenExpiration: Date.now() + res.expires_in * 1000});
+        return res.access_token;
     }
 
     /**
@@ -51,9 +72,22 @@ export class LwaAuthClient {
      * @returns {Promise<Object>} LWA token response.
      */
     #doRefresh = async () => {
+        let requestBody = null;
+        if (this.#lwaClientInfo.scope) {
+            //grantless operations
+            requestBody = `grant_type=client_credentials&client_id=${this.#lwaClientInfo.clientId}&client_secret=${this.#lwaClientInfo.clientSecret}&scope=${this.#lwaClientInfo.scope}`;
+        } else {
+            requestBody = `grant_type=refresh_token&refresh_token=${this.#lwaClientInfo.refreshToken}&client_id=${this.#lwaClientInfo.clientId}&client_secret=${this.#lwaClientInfo.clientSecret}`;
+        }
         const res = await superagent.post('https://api.amazon.com/auth/o2/token')
-            .send(`grant_type=refresh_token&refresh_token=${this.#refreshToken}&client_id=${this.#clientId}&client_secret=${this.#clientSecret}`)
+            .send(requestBody)
             .set("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");
         return res.body;
     }
+
+    clearCachedTokenMap() {
+        if (this.#cachedTokenMap) {
+            this.#cachedTokenMap.clear();
+        }
+    }    
 }

package/helper/RateLimitConfiguration.mjs

@@ -0,0 +1,53 @@
+export class RateLimitConfiguration {
+    /**
+     * RateLimiter Permit: requests per second
+     * @type {number}
+     * @private
+     */
+    #rateLimitPermit;
+
+    /**
+     * Burst value
+     * @type {number}
+     * @private
+     */
+    #burstRequests;
+
+    /**
+     * 
+     * @param {number} rateLimitPermit rate limit in requests/second
+     * @param {number} burstRequests number of busrt requests allowed
+     */
+    constructor(rateLimitPermit, burstRequests) {
+        this.#rateLimitPermit = rateLimitPermit;
+        this.#burstRequests = burstRequests;
+    }
+
+    /**
+     * @returns {number}
+     */
+    getRateLimitPermit() {
+        return this.#rateLimitPermit;
+    }
+
+    /**
+     * @param {number} rateLimitPermit
+     */
+    setRateLimitPermit(rateLimitPermit) {
+        this.#rateLimitPermit = rateLimitPermit;
+    }
+
+    /**
+     * @returns {number}
+     */
+    getBurstRequests() {
+        return this.#burstRequests;
+    }
+
+    /**
+     * @param {number} burstRequests
+     */
+    setBurstRequests(burstRequests) {
+        this.#burstRequests = burstRequests;
+    }
+}

package/helper/ScopeConstants.mjs

@@ -0,0 +1,8 @@
+/**
+ * LWA Scope Constants
+ */
+export class ScopeConstants {
+    static SCOPE_NOTIFICATION_API = 'sellingpartnerapi::notifications';
+    static SCOPE_MIGRATION_API = 'sellingpartnerapi::migration';
+    static SCOPE_APPLICATION_MANAGEMENT_API = 'sellingpartnerapi::client_credential:rotation';
+}

package/helper/SuperagentRateLimiter.mjs

@@ -0,0 +1,51 @@
+import Bottleneck from 'bottleneck';
+import { RateLimitConfiguration } from "./RateLimitConfiguration.mjs";
+
+export class SuperagentRateLimiter {
+    /** @type {Bottleneck} */
+    #limiter;
+
+    /**
+     * @param {RateLimitConfiguration} config 
+     */
+    constructor(config) {
+        if (!config.getRateLimitPermit() || !config.getBurstRequests()) {
+            throw new Error("Invalid parameter for RateLimitConfiguration");
+        }
+
+        const rateLimit = config.getRateLimitPermit();
+        const burstRequests = config.getBurstRequests();
+        
+        //Math.floor to handle special case for ShipmentInvoiceApi API
+        const refreshAmount = rateLimit < 1 ? 1 : Math.floor(rateLimit);
+        const refreshInterval = rateLimit < 1 ? Math.ceil(1/rateLimit) * 1000 : 1000;
+
+        this.#limiter = new Bottleneck({
+            reservoir: burstRequests,  // Initial capacity
+            reservoirRefreshAmount: refreshAmount, // How many tokens to add during each refresh
+            reservoirRefreshInterval: refreshInterval, // Refresh interval in milliseconds
+            maxConcurrent: burstRequests // Maximum number of requests running at the same time
+        });
+          
+    }
+
+    /**
+     * Creates a Superagent plugin that implements rate limiting
+     * @returns {function} Superagent plugin
+     */
+    getPlugin() {
+        return (request) => {
+            // Add rate limiting before the request is sent
+            request.on('request', async () => {
+                try {
+                    // Schedule the request
+                    await this.#limiter.schedule(async () => {
+                        return Promise.resolve();
+                    });
+                } catch (error) {
+                    throw new Error(`Rate limit exceed error: ${error.message}`);
+                }
+            });
+        };
+    }
+}