|
| 1 | +# Selling Partner API JavaScript client library for Node.js (v18 or later) |
| 2 | + |
| 3 | +## About this library |
| 4 | +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. |
| 5 | +1. Login with Amazon (LWA) helper that does OAuth token refresh flow. |
| 6 | +2. This library takes care of HTTP communication with SP-API endpoints with a help of [superagent](https://www.npmjs.com/package/superagent), so you can call SP-API by just calling a right method of library that corresponds to SP-API operation. |
| 7 | +3. 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. |
| 8 | +4. SP-API operaitons to handle restricted data are categorized as ["Restricted Operations"](https://developer-docs.amazon.com/sp-api/lang-ja_JP/docs/tokens-api-use-case-guide#restricted-operations), which requires ["Restricted Data Token" (RDT)](https://developer-docs.amazon.com/sp-api/lang-ja_JP/docs/authorization-with-the-restricted-data-token) 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. |
| 9 | + |
| 10 | +## Installation and Generating SDK |
| 11 | +Please note this library doesn't include SDK. You need to generate SDK with the template and script files included in this library. |
| 12 | +### Prerequisites for SDK Generation |
| 13 | +* Java version 7 or higher |
| 14 | +* swagger-codegen-cli (swagger-codegen-cli-2.4.29) is recommended. |
| 15 | + * Download swagger-codegen-cli JAR file and store it. You will need its path later when generating SDK. |
| 16 | +* Node.js v18 or higher. |
| 17 | + |
| 18 | +__CAUTION__: Please be aware that there are two major known issues with the latest JavaScript client library. |
| 19 | +1. 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. |
| 20 | +2. 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" |
| 21 | + |
| 22 | +### Download swagger-codegen-cli JAR file |
| 23 | +We use `swagger-codegen-cli` executable JAR file. You can download it by the following command. |
| 24 | +```bash |
| 25 | +$ wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.29/swagger-codegen-cli-2.4.29.jar |
| 26 | +``` |
| 27 | +### Installing dependencies |
| 28 | +Change the directory to `<package root>/src`. Run the following command to install dependencies in Node.js environment. |
| 29 | +```bash |
| 30 | +$ npm install |
| 31 | +``` |
| 32 | + |
| 33 | +### Download API models and Generate SDK |
| 34 | +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. |
| 35 | +Run this script as the command line below. |
| 36 | +```bash |
| 37 | +$ ./generate-js-sdk.sh -j <your path to swagger-codegen-cli-2.4.X.jar> |
| 38 | +``` |
| 39 | + |
| 40 | +You will find `models` directory and `sdk` directory under the package root.<br> |
| 41 | +* `models`: directory contains API models cloned from SP-API GitHub. |
| 42 | +* `sdk`: directory contains generated JavaScript SDK. |
| 43 | + |
| 44 | +### Modify Merchant Fulfillment API model file to avoid error during SDK generation |
| 45 | +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. |
| 46 | +``` |
| 47 | +"AvailableFormatOptionsForLabel": { |
| 48 | + "$ref": "#/definitions/AvailableFormatOptionsForLabelList" |
| 49 | +}, |
| 50 | +``` |
| 51 | +Since this part causes a fatal error in SDK generation for JavaScript, please replace this part with the following snipet. |
| 52 | +``` |
| 53 | +"AvailableFormatOptionsForLabel": { |
| 54 | + "type": "array", |
| 55 | + "description": "The available label formats.", |
| 56 | + "items": { |
| 57 | + "$ref": "#/definitions/LabelFormatOption" |
| 58 | + } |
| 59 | +}, |
| 60 | +``` |
| 61 | +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. |
| 62 | +```bash |
| 63 | +$ ./generate-js-sdk.sh -j ~/devbin/swagger-codegen-cli-2.4.29.jar |
| 64 | +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. |
| 65 | + |
| 66 | +``` |
| 67 | +With the correct modification in `merchantFulfillmentV0.json`, you should be able to find generated SDK for Merchant Fulfillment API. |
| 68 | + |
| 69 | +### How to run tests |
| 70 | +This library contains a sample programs in `sample_node_app` directory under the packagte root.<br>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. |
| 71 | +```javascript |
| 72 | +export const AppConfig = { |
| 73 | + lwaClientId: "< LWA client ID >", |
| 74 | + lwaClientSecret: "< LWA client secret >", |
| 75 | + lwaRefreshToken: "< LWA refresh token >", |
| 76 | + endpoint: "https://sandbox.sellingpartnerapi-na.amazon.com", |
| 77 | +} |
| 78 | +``` |
| 79 | +After you save `app.config.mjs` file, you can run the sample program`. |
| 80 | +```bash |
| 81 | +$ npm run test |
| 82 | +``` |
| 83 | +--- |
| 84 | +## How to use SDK |
| 85 | +### Calling SP-API operation with LWA credentials |
| 86 | +```javascript |
| 87 | +import { SellersApi, ApiClient as SellersApiClient } from '../../sdk/src/sellers/index.js'; |
| 88 | + |
| 89 | +const sellerApiClient = new SellersApiClient("https://sellingpartnerapi-na.amazon.com"); |
| 90 | +const sellerApi = new SellersApi(sellerApiClient); |
| 91 | +sellerApiClient.enableAutoRetrievalAccessToken("<client ID>", "<client secret>", "<refresh token>"); |
| 92 | +const participations = await sellerApi.getMarketplaceParticipations(); |
| 93 | +``` |
| 94 | +### Calling RDT-required SP-API operation with LWA credentials |
| 95 | +```javascript |
| 96 | +import { OrdersV0Api, ApiClient as OrdersApiClient } from '../../sdk/src/ordersV0/index.js'; |
| 97 | + |
| 98 | +const ordersApiClient = new OrdersApiClient("https://sellingpartnerapi-fe.amazon.com"); |
| 99 | +ordersApiClient.enableAutoRetrievalRestrictedDataToken("<client ID>", |
| 100 | + "<client secret>", "<refresh token>", ["buyerInfo", "shippingAddress"]); |
| 101 | +const ordersApi = new OrdersV0Api(ordersApiClient); |
| 102 | +const order = await ordersApi.getOrder("<order ID to retrieve>"); |
| 103 | +``` |
| 104 | +### Calling SP-API with access token |
| 105 | +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. |
| 106 | +```javascript |
| 107 | +import { SellersApi, ApiClient as SellersApiClient } from '../../sdk/src/sellers/index.js'; |
| 108 | + |
| 109 | +const sellerApiClient = new SellersApiClient("https://sellingpartnerapi-fe.amazon.com"); |
| 110 | +const sellerApi = new SellersApi(sellerApiClient); |
| 111 | +sellerApiClient.applyXAmzAccessTokenToRequest("<access token you retrieve yourself>"); |
| 112 | +const participations = await sellerApi.getMarketplaceParticipations(); |
| 113 | +``` |
| 114 | +### LWA Token refresh helper |
| 115 | +The following code shows how to use `LwaAuthClient` to execute token refresh flow. |
| 116 | +```javascript |
| 117 | +import { LwaAuthClient } from "<path to helper/LwaAuthClient.mjs>"; |
| 118 | + |
| 119 | +const lwaClient = new LwaAuthClient("<client ID>", "<client secret>", "<refresh token>"); |
| 120 | +const accessToken = await lwaClient.getAccessToken(); |
| 121 | +``` |
0 commit comments