Class: Peddler::API

Inherits:
Object
  • Object
show all
Defined in:
lib/peddler/api.rb,
sig/peddler/api.rbs

Overview

Wraps an Amazon Selling Partner API (SP-API)

Direct Known Subclasses

Peddler::APIs::AmazonWarehousingAndDistribution20240509, Peddler::APIs::AplusContent20201101, Peddler::APIs::ApplicationIntegrations20240401, Peddler::APIs::ApplicationManagement20231130, Peddler::APIs::CatalogItems20201201, Peddler::APIs::CatalogItems20220401, Peddler::APIs::CatalogItemsV0, Peddler::APIs::CustomerFeedback20240601, Peddler::APIs::DataKiosk20231115, Peddler::APIs::DeliveryByAmazon20220701, Peddler::APIs::EasyShip20220323, Peddler::APIs::ExternalFulfillmentInventory20240911, Peddler::APIs::ExternalFulfillmentReturns20240911, Peddler::APIs::ExternalFulfillmentShipments20240911, Peddler::APIs::FBAInboundEligibilityV1, Peddler::APIs::FBAInventoryV1, Peddler::APIs::Feeds20210630, Peddler::APIs::Finances20240619, Peddler::APIs::FinancesInvoices20260625, Peddler::APIs::FinancesV0, Peddler::APIs::FulfillmentInbound20240320, Peddler::APIs::FulfillmentInboundV0, Peddler::APIs::FulfillmentOutbound20200701, Peddler::APIs::FulfillmentOutbound20260704, Peddler::APIs::Invoices20240619, Peddler::APIs::ListingsItems20200901, Peddler::APIs::ListingsItems20210801, Peddler::APIs::ListingsRestrictions20210801, Peddler::APIs::MerchantFulfillmentV0, Peddler::APIs::MessagingV1, Peddler::APIs::NotificationsV1, Peddler::APIs::Orders20260101, Peddler::APIs::OrdersV0, Peddler::APIs::ProductFeesV0, Peddler::APIs::ProductPricing20220501, Peddler::APIs::ProductPricingV0, Peddler::APIs::ProductTypeDefinitions20200901, Peddler::APIs::Replenishment20221107, Peddler::APIs::Reports20210630, Peddler::APIs::SalesV1, Peddler::APIs::SellerWallet20240301, Peddler::APIs::SellersV1, Peddler::APIs::ServicesV1, Peddler::APIs::ShipmentInvoicingV0, Peddler::APIs::ShippingV1, Peddler::APIs::ShippingV2, Peddler::APIs::SolicitationsV1, Peddler::APIs::SupplySources20200701, Peddler::APIs::Tokens20210301, Peddler::APIs::Tracking20260130, Peddler::APIs::Transfers20240601, Peddler::APIs::Uploads20201101, Peddler::APIs::Vehicles20241101, Peddler::APIs::VendorDirectFulfillmentInventoryV1, Peddler::APIs::VendorDirectFulfillmentOrders20211228, Peddler::APIs::VendorDirectFulfillmentOrdersV1, Peddler::APIs::VendorDirectFulfillmentPaymentsV1, Peddler::APIs::VendorDirectFulfillmentSandboxTestData20211028, Peddler::APIs::VendorDirectFulfillmentShipping20211228, Peddler::APIs::VendorDirectFulfillmentShippingV1, Peddler::APIs::VendorDirectFulfillmentTransactions20211228, Peddler::APIs::VendorDirectFulfillmentTransactionsV1, Peddler::APIs::VendorInvoicesV1, Peddler::APIs::VendorOrdersV1, Peddler::APIs::VendorShipmentsV1, Peddler::APIs::VendorTransactionStatusV1

Defined Under Namespace

Classes: CannotSandbox, MustSandbox

Constant Summary collapse

TRANSIENT_STATUSES =

Returns:

  • (Array[Integer]) 
[429, 500, 502, 503, 504].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(aws_region, access_token, retries: 0, http: HTTP::Client.new, base_url: nil) ⇒ API

Returns a new instance of API.

Parameters:

  • aws_region (String) —

    The AWS region to use for the endpoint

  • access_token (String) —

    The access token for authentication

  • retries (Integer) (defaults to: 0) —

    The number of retries if throttled (default: 0)

  • http (HTTP::Client) (defaults to: HTTP::Client.new) —

    HTTP client

  • base_url (String, nil) (defaults to: nil) —

    Custom base URL to override the Amazon endpoint

  • retries: (Integer) (defaults to: 0)
  • http: (HTTP::Client) (defaults to: HTTP::Client.new)
  • base_url: (String, nil) (defaults to: nil) 


34
35
36
37
38
39
40
41
 
# File 'lib/peddler/api.rb', line 34

def initialize(aws_region, access_token, retries: 0, http: HTTP::Client.new, base_url: nil)
  @endpoint = Endpoint.find(aws_region)
  @access_token = access_token
  @retries = retries
  @http = http
  @sandbox = false
  @base_url = parse_base_url(base_url)
end

Instance Attribute Details

#access_token ⇒ String (readonly)

Returns:

  • (String) 


18
19
20
 
# File 'lib/peddler/api.rb', line 18

def access_token
  @access_token
end

#base_url ⇒ URI::HTTP? (readonly)

Returns Custom backend the client points at, if overridden. Only the scheme, host, and port are used; any path is ignored.

Returns:

  • (URI::HTTP, nil) —

    Custom backend the client points at, if overridden. Only the scheme, host, and port are used; any path is ignored.



27
28
29
 
# File 'lib/peddler/api.rb', line 27

def base_url
  @base_url
end

#endpoint ⇒ Peddler::Endpoint (readonly)

Returns:



15
16
17
 
# File 'lib/peddler/api.rb', line 15

def endpoint
  @endpoint
end

#retries ⇒ Integer (readonly)

Number of retries if throttled (default: 0)

Returns:

  • (Integer) 


23
24
25
 
# File 'lib/peddler/api.rb', line 23

def retries
  @retries
end

Instance Method Details

#cannot_sandbox! ⇒ void

This method returns an undefined value.

Raises:



141
142
143
144
145
 
# File 'lib/peddler/api.rb', line 141

def cannot_sandbox!
  return if base_url

  raise CannotSandbox, "cannot run in a sandbox" if sandbox?
end

#delete(path, rate_limit: nil, parser: nil, **options) ⇒ Response

Parameters:

  • path (String)
  • rate_limit: (Float, nil) (defaults to: nil)
  • parser: (Object) (defaults to: nil)
  • (Object)

Returns:



120
121
122
 
# File 'lib/peddler/api.rb', line 120

def delete(path, rate_limit: nil, parser: nil, **options)
  request(:delete, path, rate_limit:, parser:, **options)
end

#endpoint_uri ⇒ URI::HTTP

Returns:

  • (URI::HTTP) 


44
45
46
47
48
 
# File 'lib/peddler/api.rb', line 44

def endpoint_uri
  return base_url.dup if base_url

  sandbox? ? endpoint.sandbox : endpoint.production
end

#get(path, rate_limit: nil, parser: nil, **options) ⇒ Response

Parameters:

  • path (String)
  • rate_limit: (Float, nil) (defaults to: nil)
  • parser: (Object) (defaults to: nil)
  • (Object)

Returns:



108
109
110
 
# File 'lib/peddler/api.rb', line 108

def get(path, rate_limit: nil, parser: nil, **options)
  request(:get, path, rate_limit:, parser:, **options)
end

#host_header ⇒ String

Returns:

  • (String) 


153
154
155
156
157
 
# File 'lib/peddler/api.rb', line 153

def host_header
  uri = endpoint_uri
  host = uri.host.to_s
  uri.port == uri.default_port ? host : "#{host}:#{uri.port}"
end

#http(rate_limit: nil) ⇒ HTTP::Session

Parameters:

  • rate_limit: (Float, nil) (defaults to: nil)

Returns:

  • (HTTP::Session)

See Also:



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/peddler/api.rb', line 69

def http(rate_limit: nil)
  # @type var client: untyped
  client = @http.headers(
    "Host" => host_header,
    "User-Agent" => user_agent,
    "X-Amz-Access-Token" => access_token,
    "X-Amz-Date" => timestamp,
  )

  return client if retries.zero?

  on_retry = ->(_req, _err, res) {
    Thread.current[:peddler_last_retry_status] = res&.status
  }

  delay = ->(iteration) {
    last_status = Thread.current[:peddler_last_retry_status]

    if last_status == 429 && rate_limit
      # Rate-limit-aware exponential backoff with jitter if throttled
      # @see https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
      initial_delay = sandbox? ? 0.2 : 1.0 / rate_limit
      (initial_delay * (2.0**(iteration - 1))) + (rand * 0.1)
    else
      # Standard backoff for network errors and 5xx
      (2.0**(iteration - 1)) - 1 + rand
    end
  }

  client.retriable(
    tries: retries + 1,
    delay: delay,
    on_retry: on_retry,
    retry_statuses: TRANSIENT_STATUSES,
  )
end

#must_sandbox! ⇒ void

This method returns an undefined value.

Raises:



147
148
149
150
151
 
# File 'lib/peddler/api.rb', line 147

def must_sandbox!
  return if base_url

  raise MustSandbox, "must run in a sandbox" unless sandbox?
end

#parse_base_url(value) ⇒ URI::HTTP?

Parameters:

  • value (String, nil)

Returns:

  • (URI::HTTP, nil) 


159
160
161
162
163
164
165
166
167
168
 
# File 'lib/peddler/api.rb', line 159

def parse_base_url(value)
  return unless value

  uri = URI.parse(value)
  return uri if uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?

  raise ArgumentError, "base_url must be a full http(s) URL, e.g. http://localhost:9001"
rescue URI::InvalidURIError
  raise ArgumentError, "base_url must be a full http(s) URL, e.g. http://localhost:9001"
end

#patch(path, rate_limit: nil, parser: nil, **options) ⇒ Response

Parameters:

  • path (String)
  • rate_limit: (Float, nil) (defaults to: nil)
  • parser: (Object) (defaults to: nil)
  • (Object)

Returns:



124
125
126
 
# File 'lib/peddler/api.rb', line 124

def patch(path, rate_limit: nil, parser: nil, **options)
  request(:patch, path, rate_limit:, parser:, **options)
end

#percent_encode(component) ⇒ String

Parameters:

  • component (String)

Returns:

  • (String) 


178
179
180
 
# File 'lib/peddler/api.rb', line 178

def percent_encode(component)
  URI.encode_uri_component(component)
end

#post(path, rate_limit: nil, parser: nil, **options) ⇒ Response

Parameters:

  • path (String)
  • rate_limit: (Float, nil) (defaults to: nil)
  • parser: (Object) (defaults to: nil)
  • (Object)

Returns:



112
113
114
 
# File 'lib/peddler/api.rb', line 112

def post(path, rate_limit: nil, parser: nil, **options)
  request(:post, path, rate_limit:, parser:, **options)
end

#put(path, rate_limit: nil, parser: nil, **options) ⇒ Response

Parameters:

  • path (String)
  • rate_limit: (Float, nil) (defaults to: nil)
  • parser: (Object) (defaults to: nil)
  • (Object)

Returns:



116
117
118
 
# File 'lib/peddler/api.rb', line 116

def put(path, rate_limit: nil, parser: nil, **options)
  request(:put, path, rate_limit:, parser:, **options)
end

#request(method, path, rate_limit: nil, parser: nil, **options) ⇒ Response

Parameters:

  • method (Symbol)
  • path (String)
  • rate_limit: (Float, nil) (defaults to: nil)
  • parser: (Object) (defaults to: nil)
  • (Object)

Returns:



128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/peddler/api.rb', line 128

def request(method, path, rate_limit: nil, parser: nil, **options)
  options[:json] = options.delete(:body) if options[:body] && !options[:body].is_a?(String)

  uri = endpoint_uri.tap { |u| u.path = path }
  http_response = http(rate_limit:).send(method, uri, **options)

  Response.wrap(http_response, parser:)
rescue HTTP::OutOfRetriesError => e
  raise e unless e.response

  raise Error.build(e.response)
end

#sandbox ⇒ self

Switches to the SP-API sandbox to make test calls

Returns:

  • (self)

Raises:

See Also:



54
55
56
57
58
59
 
# File 'lib/peddler/api.rb', line 54

def sandbox
  raise CannotSandbox, "cannot use sandbox with a custom base_url" if base_url

  @sandbox = true
  self
end

#sandbox? ⇒ Boolean

Returns:

  • (Boolean) 


62
63
64
 
# File 'lib/peddler/api.rb', line 62

def sandbox?
  @sandbox
end

#stringify_array(val) ⇒ String?

Parameters:

  • val (Array[untyped], nil)

Returns:

  • (String, nil) 


182
183
184
 
# File 'lib/peddler/api.rb', line 182

def stringify_array(val)
  val.is_a?(Array) ? val.join(",") : val
end

#timestamp ⇒ String

Returns:

  • (String) 


174
175
176
 
# File 'lib/peddler/api.rb', line 174

def timestamp
  Time.now.utc.strftime("%Y%m%dT%H%M%SZ")
end

#user_agent ⇒ String

Returns:

  • (String) 


170
171
172
 
# File 'lib/peddler/api.rb', line 170

def user_agent
  "Peddler/#{Peddler::VERSION} (Language=Ruby; #{Socket.gethostname})"
end