28f5a337d6 | ||
---|---|---|
.. | ||
src | ||
README.md | ||
package-lock.json | ||
package.json |
README.md
Selling Partner API JavaScript client library for Node.js (v18 or later)
About this library
This library is to help SP-API developers to create an app in JavaScript on Node.js easier than calling HTTP endpoints directly. This library comes with the following features.
- Login with Amazon (LWA) helper that does OAuth token refresh flow.
- This library takes care of HTTP communication with SP-API endpoints with a help of superagent, so you can call SP-API by just calling a right method of library that corresponds to SP-API operation.
- Calling SP-API requires non-standard
x-amz-access-token
HTTP request header in request. The SDK generated by this library supports to include this header with token value you specify. - SP-API operaitons to handle restricted data are categorized as "Restricted Operations", which requires "Restricted Data Token" (RDT) instead of access token for tighter security. Calling restricted operation involves two seprate steps, one of wihch is calling Tokens API to retrieve RDT and the other of which is calling protected operation with RDT. This library helps to compbine these two steps into single library call.
Installation and Generating SDK
Please note this library doesn't include SDK. You need to generate SDK with the template and script files included in this library.
Prerequisites for SDK Generation
- Java version 7 or higher
- swagger-codegen-cli (swagger-codegen-cli-2.4.29) is recommended.
- Download swagger-codegen-cli JAR file and store it. You will need its path later when generating SDK.
- Node.js v18 or higher.
CAUTION: Please be aware that there are two major known issues with the latest JavaScript client library.
- If you use swagger-codegen-cli newer than 2.4.29 (such as 2.4.30 or 3.x), there is a known compatibility issue with SP-API models that makes generating SDK fail. We recommend that you use swagger-codegen-cli-2.4.29 specifically.
- Swagger codegen tool fails to generate SDK for "Merchant Fulfillment V0 API." For workaround, you need to modify a part of the API model file "merchantFulfillmentV0.json"
Download swagger-codegen-cli JAR file
We use swagger-codegen-cli
executable JAR file. You can download it by the following command.
$ wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.29/swagger-codegen-cli-2.4.29.jar
Installing dependencies
Change the directory to <package root>/src
. Run the following command to install dependencies in Node.js environment.
$ npm install
Download API models and Generate SDK
Go to <package root>/src
directory which is under the package root. In this directory you should be able to find generate-js-sdk.sh
shell script file.
Run this script as the command line below.
$ ./generate-js-sdk.sh -j <your path to swagger-codegen-cli-2.4.X.jar>
You will find models
directory and sdk
directory under the package root.
models
: directory contains API models cloned from SP-API GitHub.sdk
: directory contains generated JavaScript SDK.
Modify Merchant Fulfillment API model file to avoid error during SDK generation
If you want to call Merchant Fulfillment API with the generated SDK, you need to follow this instruction. There is an fatal known issue in generating Merchant Fulfillment API library. If downloading API models is successful, you should be able to find merchantFulfillmentV0.json
file In <package root>/models/merchant-fulfillment-api-model
directory. Open this file with an editor and find the following part.
"AvailableFormatOptionsForLabel": {
"$ref": "#/definitions/AvailableFormatOptionsForLabelList"
},
Since this part causes a fatal error in SDK generation for JavaScript, please replace this part with the following snipet.
"AvailableFormatOptionsForLabel": {
"type": "array",
"description": "The available label formats.",
"items": {
"$ref": "#/definitions/LabelFormatOption"
}
},
After modification, please run the shell script (generate-js-sdk.sh
) again but you should type 'n' to the prompt that asks whether to download models again.
$ ./generate-js-sdk.sh -j ~/devbin/swagger-codegen-cli-2.4.29.jar
Found <package root>/models already exists. Would you like to delete all the files under '<package root>/models' and clone again? [y/n]: n # answer 'n' otherwise modification will be overwritten.
With the correct modification in merchantFulfillmentV0.json
, you should be able to find generated SDK for Merchant Fulfillment API.
How to run tests
This library contains a sample programs in sample_node_app
directory under the packagte root.
In order to run the program, you need to have LWA credential information saved in the file and name it app.config.mjs
and put it <package root>/src
directory. Because client secret and refresh token shouldn't be exposed, you must make sure that you don't commit this file to the repository.
export const AppConfig = {
lwaClientId: "< LWA client ID >",
lwaClientSecret: "< LWA client secret >",
lwaRefreshToken: "< LWA refresh token >",
endpoint: "https://sandbox.sellingpartnerapi-na.amazon.com",
}
After you save app.config.mjs
file, you can run the sample program`.
$ npm run test
How to use SDK
Calling SP-API operation with LWA credentials
import { SellersApi, ApiClient as SellersApiClient } from '../../sdk/src/sellers/index.js';
const sellerApiClient = new SellersApiClient("https://sellingpartnerapi-na.amazon.com");
const sellerApi = new SellersApi(sellerApiClient);
sellerApiClient.enableAutoRetrievalAccessToken("<client ID>", "<client secret>", "<refresh token>");
const participations = await sellerApi.getMarketplaceParticipations();
Calling RDT-required SP-API operation with LWA credentials
import { OrdersV0Api, ApiClient as OrdersApiClient } from '../../sdk/src/ordersV0/index.js';
const ordersApiClient = new OrdersApiClient("https://sellingpartnerapi-fe.amazon.com");
ordersApiClient.enableAutoRetrievalRestrictedDataToken("<client ID>",
"<client secret>", "<refresh token>", ["buyerInfo", "shippingAddress"]);
const ordersApi = new OrdersV0Api(ordersApiClient);
const order = await ordersApi.getOrder("<order ID to retrieve>");
Calling SP-API with access token
In case you manage LWA token refresh flow, you can explicitly use the access token you got yourself for your SP-API call as follows.
import { SellersApi, ApiClient as SellersApiClient } from '../../sdk/src/sellers/index.js';
const sellerApiClient = new SellersApiClient("https://sellingpartnerapi-fe.amazon.com");
const sellerApi = new SellersApi(sellerApiClient);
sellerApiClient.applyXAmzAccessTokenToRequest("<access token you retrieve yourself>");
const participations = await sellerApi.getMarketplaceParticipations();
LWA Token refresh helper
The following code shows how to use LwaAuthClient
to execute token refresh flow.
import { LwaAuthClient } from "<path to helper/LwaAuthClient.mjs>";
const lwaClient = new LwaAuthClient("<client ID>", "<client secret>", "<refresh token>");
const accessToken = await lwaClient.getAccessToken();