Latest Version: 1.1.1
This library allows your agent code to work with the Amazon Dash Replenishment Service (DRS) via its REST API.
This version of the library supports the following functionality:
You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.
To include this library in your project, add
#require "AmazonDRS.agent.lib.nut:1.1.1"
at the top of your agent code.
Before using the library you need to have:
The library requires a Refresh Token to be able to call the Amazon DRS API. The Refresh Token can be acquired with login(). It can also be acquired in any other application-specific way and then passed to the class instance via setRefreshToken().
Every time you call login() or setRefreshToken(), the library starts to use a new Refresh Token.
The login() method provides the following authentication flow:
You can read more about authentication here and here.
Note The Refresh Token must be passed in to the library every time the agent restarts. If you don't want to go through the above authentication steps again, save the Token in the agent's persistent storage and set it with setRefreshToken() after each agent restart. Please see the provided example for more details.
For testing purposes, Amazon DRS allows you to submit test orders. Test orders are those made by a DRS device authenticated as a test device.
As such, login() has a parameter, testDevice, which takes a boolean value indicating whether the device is a test device. However, if you set a Refresh Token manually with setRefreshToken(), only you know whether this token was obtained for testing purposes.
Only test orders can be canceled with cancelTestOrder().
DRS devices exist in either one of two states:
Non-live (Pre-production) Devices These are devices are devices that are created in the DRS developer portal but have not yet passed Amazon certification and have not launched to customers. You can still edit your device in the developer portal for device details, ASIN list details, etc.
Live Devices These are devices that have been fully certified and put into production. Live devices cannot be edited.
If your device is non-live, you must pass true as the nonLiveDevice parameter’s argument when calling login(). However, if you set a Refresh Token manually with setRefreshToken(), only you know whether this token was obtained for a live device.
All requests that are made to the Amazon platform occur asynchronously. Every method that sends a request has an optional parameter which takes a callback function that will be executed when the operation is completed, whether successfully or not. The callback’s parameters are listed in the corresponding method description, but every callback has at least one parameter, error. If error is 0, the operation has been executed successfully. Otherwise, error is a non-zero error code.
Error codes are integers which specify a concrete error which occurred during an operation.
| Error Code | Description |
|---|---|
| 0 | No error |
| 1-99 | Internal errors of the HTTP API |
| 100-999 | HTTP error codes from Amazon server. See methods' descriptions for more information |
| 1000 | The client is not authenticated. For example, the Refresh Token is invalid or not set |
| 1001 | The login() method has already been called |
| 1010 | General error |
This method returns a new AmazonDRS instance.
| Parameter | Type | Required | Description |
|---|---|---|---|
| clientId | String | Yes | The Client ID of your LWA Security Profile. For more information, please see the Amazon documentation |
| clientSecret | String | Yes | The Client Secret of your LWA Security Profile. For information, please see the Amazon documentation |
This method allows you to authenticate the agent with Amazon and retrieve the required security tokens. The method automatically sets the obtained tokens to be used for DRS API calls, so you do not need to call setRefreshToken() after login(). For more information, please read the authentication section.
You may re-call this method only after the previous call has finished. The call is considered to be finished only when the authentication flow described in the authentication section above is completed or an error occurred. Authentication should be performed before making any DRS-related requests.
This method uses the Rocky library, so it requires an instance of Rocky.
By default, the login endpoint's route is "/". Please do not redefine the endpoint used by this method in your application code.
| Parameter | Type | Required | Description |
|---|---|---|---|
| rocky | Rocky instance | Yes | An instance of the Rocky library |
| deviceModel | String | Yes | For information, please see the Amazon documentation |
| deviceSerial | String | Yes | For information, please see the Amazon documentation |
| onAuthenticated | Function | Optional | Callback called when the operation is completed or an error occurs. See below |
| route | String | Optional | The login endpoint's route. Default: "/" |
| testDevice | Boolean | Optional | true if it is a test device; false by default. For more information, please see the Amazon documentation and the Test Orders section |
| nonLiveDevice | Boolean | Optional | true if it is a non-live (pre-production) device; false by default. For more information, please see the Amazon documentation (the point about the should_include_non_live flag) and the Non-live devices section |
| Parameter | Type | Description |
|---|---|---|
| error | Integer | 0 if the authentication is successful, otherwise an error code. Possible HTTP error codes are listed here |
| response | Table | Key-value table with the response provided by Amazon server. May be null. For information on the response format, please see the Amazon documentation. May also contain error details described here and here |
Nothing. The outcome of the operation may be obtained via the onAuthenticated callback, if specified.
#require "Rocky.class.nut:2.0.2"
#require "AmazonDRS.agent.lib.nut:1.1.1"
const AMAZON_DRS_CLIENT_ID = "<YOUR_AMAZON_CLIENT_ID>";
const AMAZON_DRS_CLIENT_SECRET = "<YOUR_AMAZON_CLIENT_SECRET>";
const AMAZON_DRS_DEVICE_MODEL = "<YOUR_AMAZON_DEVICE_MODEL>";
const AMAZON_DRS_DEVICE_SERIAL = "<YOUR_AMAZON_DEVICE_SERIAL>";
testDevice <- true;
nonLiveDevice <- true;
loginRoute <- "/login";
function onAuthenticated(error, response) {
if (error != 0) {
server.error("Authentication error: code = " + error + " response = " + http.jsonencode(response));
return;
}
server.log("Successfully authenticated!");
}
client <- AmazonDRS(AMAZON_DRS_CLIENT_ID, AMAZON_DRS_CLIENT_SECRET);
rocky <- Rocky();
client.login(rocky,
AMAZON_DRS_DEVICE_MODEL,
AMAZON_DRS_DEVICE_SERIAL,
onAuthenticated.bindenv(this),
loginRoute,
testDevice,
nonLiveDevice);
This method allows you to set a Refresh Token manually. For more information, please see the authentication section.
Either this method or login() should be called and authentication should be established before making any DRS-related requests.
| Parameter | Type | Required | Description |
|---|---|---|---|
| refreshToken | String | Yes | A Refresh Token used to acquire an Access Token and refresh it when it has expired |
Nothing.
#require "AmazonDRS.agent.lib.nut:1.1.1"
const AMAZON_DRS_CLIENT_ID = "<YOUR_AMAZON_CLIENT_ID>";
const AMAZON_DRS_CLIENT_SECRET = "<YOUR_AMAZON_CLIENT_SECRET>";
const AMAZON_DRS_REFRESH_TOKEN = "<YOUR_AMAZON_VALID_REFRESH_TOKEN>";
client <- AmazonDRS(AMAZON_DRS_CLIENT_ID, AMAZON_DRS_CLIENT_SECRET);
client.setRefreshToken(AMAZON_DRS_REFRESH_TOKEN);
The method returns a string with the Refresh Token, or null if it has not been set.
String — The Refresh Token, or null.
This method places an order for a device/slot combination. For more information, please see the Amazon DRS documentation.
| Parameter | Type | Required | Description |
|---|---|---|---|
| slotId | String | Yes | The ID of a slot used to place an order |
| onReplenished | Function | Optional | Callback function called when the operation is completed or an error occurs |
| Parameter | Data Type | Description |
|---|---|---|
| error | Integer | 0 if the replenishment is successful, otherwise an error code. Possible HTTP error codes are listed here |
| response | Table | Key-value table with the response provided by Amazon server. May be null. For information on the response format, please see the Amazon documentation. May also contain error details described here |
Nothing. The result of the operation may be obtained via the onReplenished callback, if specified.
const AMAZON_DRS_SLOT_ID = "<YOUR_AMAZON_SLOT_ID>";
function onReplenished(error, response) {
if (error != 0) {
server.error("Error replenishing: code = " + error + " response = " + http.jsonencode(response));
return;
}
server.log("An order has been placed. Response from server: " + http.jsonencode(response));
}
// It is supposed that the client has been authenticated with either login() method or setRefreshToken() method
client.replenish(AMAZON_DRS_SLOT_ID, onReplenished.bindenv(this));
This method cancels test orders for one or all slots in the device. For more information, please see the Amazon DRS documentation.
The method can only be used for the orders made by a test device. The library does not check if your device authenticated as a test device, so you are responsible for this check. For more information, please see the Test Orders section.
| Parameter | Type | Required | Description |
|---|---|---|---|
| slotId | String | Optional | The ID of the slot to be canceled. If not specified or null, test orders for all slots in the device will be canceled |
| onCanceled | Function | Optional | Callback function called when the operation is completed or an error occurs |
| Parameter | Data Type | Description |
|---|---|---|
| error | Integer | 0 if the cancelation is successful, otherwise an error code. Possible HTTP error codes are listed here |
| response | Table | Key-value table with the response provided by Amazon server. May be null. For information on the response format, please see the Amazon documentation. May also contain error details |
Nothing. The result of the operation may be obtained via the onCanceled callback, if specified.
const AMAZON_DRS_SLOT_ID = "<YOUR_AMAZON_SLOT_ID>";
function onCanceled(error, response) {
if (error != 0) {
server.error("Error canceling: code = " + error + " response = " + http.jsonencode(response));
return;
}
server.log("The order has been canceled. Response from server: " + http.jsonencode(response));
}
// It is supposed that client has been authenticated with either login() method or setRefreshToken() method
// as a test DRS device
client.cancelTestOrder(AMAZON_DRS_SLOT_ID, onCanceled.bindenv(this));
This method enables (value is true) or disables (value is false) the library debug output, including error logging. It is disabled by default.
Nothing.
Working examples are provided in the examples directory.
The following example shows proper usage of login(), setRefreshToken() and getRefreshToken() methods. It saves the Refresh Token in server-side persistent storage and then loads it to the library on each agent restart. This saves the user from having to set up their device every time.
#require "Rocky.class.nut:2.0.2"
#require "AmazonDRS.agent.lib.nut:1.1.1"
const AMAZON_DRS_CLIENT_ID = "<YOUR_AMAZON_CLIENT_ID>";
const AMAZON_DRS_CLIENT_SECRET = "<YOUR_AMAZON_CLIENT_SECRET>";
const AMAZON_DRS_DEVICE_MODEL = "<YOUR_AMAZON_DEVICE_MODEL>";
const AMAZON_DRS_DEVICE_SERIAL = "<YOUR_AMAZON_DEVICE_SERIAL>";
function getStoredRefreshToken() {
local persist = server.load();
local amazonDRS = {};
if ("amazonDRS" in persist) amazonDRS = persist.amazonDRS;
if ("refreshToken" in amazonDRS) {
server.log("Refresh Token found!");
return amazonDRS.refreshToken;
}
return null;
}
client <- AmazonDRS(AMAZON_DRS_CLIENT_ID, AMAZON_DRS_CLIENT_SECRET);
refreshToken <- getStoredRefreshToken();
if (refreshToken != null) {
client.setRefreshToken(refreshToken);
} else {
function onAuthenticated(error, response) {
if (error != 0) {
server.error("Error authenticating: code = " + error + " response = " + http.jsonencode(response));
return;
}
refreshToken = client.getRefreshToken();
client.setRefreshToken(refreshToken);
local persist = server.load();
persist.amazonDRS <- { "refreshToken" : refreshToken };
server.save(persist);
server.log("Successfully authenticated!");
server.log("Refresh Token saved!");
}
local testDevice = true;
rocky <- Rocky();
client.login(rocky,
AMAZON_DRS_DEVICE_MODEL,
AMAZON_DRS_DEVICE_SERIAL,
onAuthenticated.bindenv(this),
null,
testDevice);
server.log("Log in please!");
}
The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.
| Version | Source Code | Notes |
|---|---|---|
| 1.0.0 | GitHub | Initial release |
| 1.1.0 | GitHub | Added support for the "should_include_non_live" flag |
| 1.1.1 | GitHub | Added static VERSION variable; testing-related changes |
This library is licensed under the MIT License.