amazon-ads 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01b624dd728e5d50d55c9d199671a1730ce61c260210d0d13c2173241edc297e
-  data.tar.gz: 6a8cc4aa441d12b1c12905fbec987935c82807b2495a520e0d304830c36ceadc
+  metadata.gz: 5e6d25250dfeb3f930a2c3253a1f0ed8da99226ba0d5290948b8e3ca8cfba483
+  data.tar.gz: 073acd8350a1446de8ea3a2ec207491506d3c996ffbad5d444b4bec2c77e2b7e
 SHA512:
-  metadata.gz: 8afd9e71ec2e8006cf99de7f66bc202cbc8589fbe9809a591d42a7948ed032dfad3d7b1d2d9c536548643de93a15824e6fa94724424e2d0c76c5ace11610387e
-  data.tar.gz: 6cca951e838bf718be509b0f0882ef54c4e6ee8d2955d25982f0ab9d6a595e08535b4f3ed63f17b84103fef1a3f813c23d282e6e34f253afbbbe688bbcaab061
+  metadata.gz: ed62d0a64d560078cd3ca2d3d564e5cac7ae3e1da59ba00766fd4f0701b362d89980e879347e91f2ac5049176769580d9ce8cdc0e796770fdd24180a527023b4
+  data.tar.gz: 4e083231e7f90868aa5207b124f8affc757b452b8ce77d03319f83945822fa754e7e7b0286e9fb1b4271db327780b61b59746ef86dae28ba5fe4fcd44b6c91cc

data/README.md

@@ -54,6 +54,30 @@ campaigns = AmazonAds::Campaigns.new(
 campaigns.list_campaigns
 ```
 
+## Error handling
+
+Responses with a 4xx or 5xx status raise `AmazonAds::Error`, which carries the full response:
+
+```ruby
+begin
+  campaigns.list_campaigns
+rescue AmazonAds::Error => e
+  e.status         # 400
+  e.response.body  # Amazon's error document
+end
+```
+
+The error supports pattern matching on status:
+
+```ruby
+case error
+in status: 429 then backoff
+in status: 500..599 then retry
+end
+```
+
+Network failures (`HTTP::ConnectionError`, `HTTP::TimeoutError`) raise as-is, whether or not retries are configured.
+
 ## Development
 
 See [AGENTS.md](AGENTS.md).

data/lib/amazon_ads/api.rb

@@ -49,13 +49,9 @@ module AmazonAds
         .headers(default_headers)
         .use(:auto_inflate)
 
-      if retries.zero?
-        client.use(:raise_error)
-      else
-        client
-          .use(raise_error: { ignore: [429] })
-          .retriable(tries: retries + 1, retry_statuses: [429])
-      end
+      return client if retries.zero?
+
+      client.retriable(tries: retries + 1, retry_statuses: [429])
     end
 
     private
@@ -64,7 +60,17 @@ module AmazonAds
     def request(method, path, **options)
       url = endpoint
       url.path = path
-      http.request(method, url.to_s, **options)
+      response = http.request(method, url.to_s, **options)
+      raise Error.build(response) if response.code >= 400
+
+      response
+    rescue HTTP::OutOfRetriesError => e
+      response = e.response
+      raise Error.build(response) if response
+
+      # No response means a transport error; re-raise as if never retried
+      cause = e.cause #: Exception
+      raise cause
     end
 
     #: () -> Hash[String, String]

data/lib/amazon_ads/error.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "http"
+
+module AmazonAds
+  # Raised when the API or LWA responds with a 4xx or 5xx
+  class Error < StandardError
+    # The failed response
+    attr_reader :response #: HTTP::Response?
+
+    #: (HTTP::Response) -> Error
+    def self.build(response)
+      response.flush # memoize the body while the connection is still readable
+      new(response.status.to_s, response)
+    end
+
+    #: (?String?, ?HTTP::Response?) -> void
+    def initialize(msg = nil, response = nil)
+      @response = response
+      super(msg)
+    end
+
+    #: () -> Integer?
+    def status
+      response&.status&.code
+    end
+
+    # Supports pattern matching on status
+    #
+    #   case error
+    #   in status: 429 then backoff
+    #   in status: 500..599 then retry
+    #   end
+    #
+    #: (Array[Symbol]?) -> Hash[Symbol, untyped]
+    def deconstruct_keys(keys)
+      hash = { status: status }
+      keys ? hash.slice(*keys) : hash
+    end
+  end
+end

data/lib/amazon_ads/lwa.rb

@@ -26,16 +26,14 @@ module AmazonAds
     # Requests a fresh access token from LWA
     #: () -> Hash[String, untyped]
     def request
-      http.post(URL, form: params).parse
+      response = @http.post(URL, form: params)
+      raise Error.build(response) if response.code >= 400
+
+      response.parse
     end
 
     private
 
-    #: () -> HTTP::Client
-    def http
-      @http.use(:raise_error)
-    end
-
     #: () -> Hash[Symbol, String]
     def params
       {

data/lib/amazon_ads/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AmazonAds
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amazon-ads
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Hakan Ensari
@@ -83,6 +83,7 @@ files:
 - lib/amazon_ads/apis/recommendations.rb
 - lib/amazon_ads/apis/reporting.rb
 - lib/amazon_ads/apis/targets.rb
+- lib/amazon_ads/error.rb
 - lib/amazon_ads/lwa.rb
 - lib/amazon_ads/version.rb
 homepage: https://github.com/lineofflight/amazon-ads-ruby