drs

README

Amazon Dash Replenishment Service SDK for Go

This library serves as a simple SDK for the Amazon Dash Replenishment Service. While trying to integrate with DRS, no official SDK existed. Given the small footprint of the API, a quick SDK was started until an official SDK is released.

NOTE This SDK exists as a temporary solution until an official SDK is released from Amazon or a community-standard SDK is developed. This SDK supports V2 of the DRS API.

Installing

You can simply install the package:

go get github.com/kevineaton/drs-sdk

Or if you are using dep:

dep ensure -add github.com/kevineaton/drs-sdk

Usage

First, there are some optional environment variables (with hopefully sane defaults):

DRS_SDK_ENV is the environment the SDK is running in; defaults to development which turns on logging

DRS_SDK_ROOT_URL is the root URL for the DRS service, defaults to https://dash-replenishment-service-na.amazon.com/

Most calls require at a minimum the deviceToken which is the access token for the device obtained from Login With Amazon / DRS. The scope needed is dash:replenish. Refreshing this token is not the responsibility of this library.

Testing

Testing can be tricky, as you don't want to make actual network calls with user data. Therefore, in the endpoints.go file where we setup the supported endpoints, we also have a MockGood field which holds JSON of what the call should return based upon the V2 docs found here.

When testing, if the auth token is set to TEST, the mock data will be used instead.

Since we are mocking the calls, some of the code is tougher to test, so code coverage will likely never be 100%.

To run the tests, run

go test

For coverage in HTML format, run

go test -coverprofile=coverage.out && go tool cover -html=coverage.out

The coverage is notably lower than ideal, which may cause concerns. However, most of the uncovered calls would be calls directly to Amazon, which we cannot easily mock in success conditions, that are malformed. Feel free to check the results of the coverage report to see what exactly isn't covered and make a determination if that is acceptable to you. This library is currently being used in production.

Contributing

Pull Requests are welcome! See our CONTRIBUTING.md file for more information.

Third-party Libraries

The following libraries are used in this project. We thank the creators and maintainers for making our lives easier!

Resty

Logrus

Testify

Mapstructure

Endpoints Implemented

Subscription Info API Docs

Deregistration API Docs

Device Status API Docs

Slot Status API Docs

Get Order Info API Docs

Replenish API Docs

Cancel Test Order API Docs

Documentation

Overview

Package drs provides a very basic and simple API for working with V2 of the Amazon Dash Replenishment Services For more information, check the README file at https://github.com/kevineaton/drs-sdk

Most of the functions will require a deviceToken. This is the DRS Access Token retrieved after the user signs up for DRS, most often through LWA. The token will need to be managed and refreshed. At the time of this library's creation, it needed to be refreshed at least once an hour. This library does not handle that responsibility.

Index

• func DeregisterDevice(deviceToken string) (bool, error)
• func ReportSlotStatus(deviceToken string, slotID string, status *SlotStatus) (bool, error)
• func UpdateDeviceStatus(deviceToken string, lastStatus string) (bool, error)
• type APIError
  • func (e *APIError) Error() string
• type ConfigStruct
  • func ConfigSetup() *ConfigStruct
• type OrderInfoData
  • func GetOrderInfo(deviceToken, instanceID string) (*OrderInfoData, error)
• type OrderItem
• type ProductInfoListItem
• type ReplenishResult
  • func ReplenishSlot(deviceToken, slotID string) (*ReplenishResult, error)
• type Slot
• type SlotOrderStatus
• type SlotOrderStatuses
  • func CancelTestOrder(deviceToken, slotID string) (*SlotOrderStatuses, error)
• type SlotStatus
• type SubscriptionInfo
  • func GetSubscriptionInfo(deviceToken string) (*SubscriptionInfo, error)

Functions

func DeregisterDevice

func DeregisterDevice(deviceToken string) (bool, error)

DeregisterDevice sends a request to DRS requesting that the device is deregistered from the service

func ReportSlotStatus

func ReportSlotStatus(deviceToken string, slotID string, status *SlotStatus) (bool, error)

ReportSlotStatus reports a slot status to Amazon. See the SlotStatus struct for information about the parameters

func UpdateDeviceStatus

func UpdateDeviceStatus(deviceToken string, lastStatus string) (bool, error)

UpdateDeviceStatus updates the device status. According to the docs, you will want to call this at least once every 24 hours.

If lastStatus is an empty string, we will replace it with the current timestamp in ISO8601

Types

type APIError

type APIError struct {
	Code int
	Data interface{}
}

APIError represents an error from the API and SDK. It implements Error() and contains additional data such as Code and Data. Code represents, in most cases, the HTTP status code. Data will be filled with information that depends on the context of the usage.

func (*APIError) Error

func (e *APIError) Error() string

type ConfigStruct

type ConfigStruct struct {
	Environment string
	RootURL     string
}

ConfigStruct holds the various configuration options

var Config *ConfigStruct

Config is the global configuration object that holds global configuration settings

func ConfigSetup

func ConfigSetup() *ConfigStruct

ConfigSetup sets up the config struct with data from the environment

type OrderInfoData

type OrderInfoData struct {
	InstanceID string      `json:"instanceId"`
	OrderItems []OrderItem `json:"orderItems"`
}

OrderInfoData represents a single order a slot

func GetOrderInfo

func GetOrderInfo(deviceToken, instanceID string) (*OrderInfoData, error)

GetOrderInfo gets the information regarding an order identified by its instanceId

type OrderItem

type OrderItem struct {
	ASIN                 string `json:"asin"`
	ExpectedDeliveryDate string `json:"expectedDeliveryDate"`
	Quantity             int    `json:"quantity"`
	SlotID               string `json:"slotID"`
	Status               string `json:"status"`
}

OrderItem represents a single order item in an order information call

type ProductInfoListItem

type ProductInfoListItem struct {
	ASIN     string `json:"asin"`
	Quantity int    `json:"quantity"`
	Unit     string `json:"unit"`
}

ProductInfoListItem represents a single ASIN in the subscription

type ReplenishResult

type ReplenishResult struct {
	EventInstanceID string `json:"eventInstanceId"`
	DetailCode      string `json:"detailCode"`
}

ReplenishResult represents the end result of a request to replenish a slot

func ReplenishSlot

func ReplenishSlot(deviceToken, slotID string) (*ReplenishResult, error)

ReplenishSlot asks Amazon to submit an order to replenish a specific slot for the device

type Slot

type Slot struct {
	ProductInfoList []ProductInfoListItem `json:"productInfoList"`
	Subscribed      bool                  `json:"subscribed"`
}

Slot represents a DRS Slot and it's subscription status

type SlotOrderStatus

type SlotOrderStatus struct {
	OrderStatus string `json:"orderStatus"`
	SlotID      string `json:"slotId"`
}

SlotOrderStatus represents a single slot and the status of order on that slot

type SlotOrderStatuses

type SlotOrderStatuses struct {
	SlotOrderStatuses []SlotOrderStatus `json:"slotOrderStatuses"`
}

SlotOrderStatuses is a container to hold a slice of SlotOrderStatuses returned after cancelling a test order

func CancelTestOrder

func CancelTestOrder(deviceToken, slotID string) (*SlotOrderStatuses, error)

CancelTestOrder cancels a test order on a slot for a device. Note that only test orders can be cancelled. An order for a real device must be cancelled through the Amazon account of the user and is not exposed by the DRS API

type SlotStatus

type SlotStatus struct {
	// ExpectedReplenishmentDate is the expected product replenishment date in
	// ISO 8601 format
	ExpectedReplenishmentDate string `json:"expectedReplenishmentDate"`
	// RemainingQuantityInUnit is the emaining quantity of the container
	// (in the unit of measurement provided during DeviceCapabilitiesGroup creation)
	RemainingQuantityInUnit float64 `json:"remainingQuantityInUnit"`
	// OriginalQuantityInUnit is the total quantity of product the container
	// had when it was full (in the unit of measurement that you provided
	// during DeviceCapabilitiesGroup creation)
	OriginalQuantityInUnit float64 `json:"originalQuantityInUnit"`
	// TotalQuantityOnHand is the total quantity of product on hand, but not
	// loaded into the device (if known)
	TotalQuantityOnHand float64 `json:"totalQuantityOnHand"`
	//	LastUseDate is the last time that product was consumed from a given
	// slot in ISO 8601 format
	LastUseDate string `json:"lastUseDate"`
}

SlotStatus represents the current status of the slot of a device and needs to be reported to Amazon at least on a daily basis.

type SubscriptionInfo

type SubscriptionInfo struct {
	Slots map[string]Slot `json:"slotsSubscriptionStatus"`
}

SubscriptionInfo holds the results of the Subscription Information call. The Slots are a map of strings to Slot data

func GetSubscriptionInfo

func GetSubscriptionInfo(deviceToken string) (*SubscriptionInfo, error)

GetSubscriptionInfo gets the subscription information from DRS for the passed in device token