jbr 3.7.2 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e017275cf5a3a41647f3817608327ddf8fa909c2fdf25e1f8c2a43ee1ad3b044
-  data.tar.gz: 1d01c835b75bd16cd21b8d4e658644520cc065c0659b1f394f105e02775b8f69
+  metadata.gz: de01eb560b5d6366142d35901817eae421a30ccebf31aeede4cacb2e97720cd3
+  data.tar.gz: 1a613711f19080da2368d9b2d38d2e9fff372dbd4e37126b2bc06e9d4c9a9493
 SHA512:
-  metadata.gz: 89e55dd309b839918c67d79ee4c761d28cacb3f2c0dba30daa996354b0a22c4436aa52928dbfb7208df62609073157f77e42f7349943f4f58a2910dea1f43f00
-  data.tar.gz: 2cd3bf9d534e4fbb349debe3643aad4a62982e5780e27e558214594ffe9d536413bc5e8d837976d832422011b5da9be146bd9998492f6c33d99011274c213ef5
+  metadata.gz: 9b8fc6971e3cbe48eecf5025cb7f5b9beb9e7490a0b7a6830b0a22eb9b4c98fbe3c066686866dff576de01bfc0e10f16050c6bd1002b929bd18940dfeeccd137
+  data.tar.gz: 2cbdcb7fd7bd995bf7450784afdb08d59acce2c0ea788f3192a1c62aabaf00251497bfb8ff6efa57a932d96a15735dbaa9bdc4e846824679521056e7a3129e33

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [3.8.0] - 2026-08-18
+
+- [New] `Jbr::Retriable`, a `Jbr::Error` for a query Jobber refused over what it costs rather
+  than over anything about the query. Every refusal read alike before, so an app had nothing to
+  branch on: the one worth asking again a moment later looked exactly like the one that will
+  say the same thing forever. It carries what Jobber reported it with — `cost`, `available`,
+  `maximum` and `restore_rate` — so a caller can tell a bucket that needed a second from a
+  query too big to ever fit in it
+
 ## [3.7.2] - 2026-08-17
 
 - [Change] Jobber's token endpoint answers in prose, so that is all this reads. 3.7.1 kept a

data/README.md

@@ -228,6 +228,16 @@ what happened, so the caller can decide:
 Throttled (cost 1885, 1254 of 10000 available, restoring 500/s)
 ```
 
+That one is a `Jbr::Retriable`, a `Jbr::Error` for a refusal worth asking again, carrying the
+numbers to decide with:
+
+```ruby
+error.cost # => 1885, what the query was priced at
+error.available # => 1254, what the bucket held when it was asked
+error.maximum # => 10000, what the bucket holds when full — a cost above it never fits
+error.restore_rate # => 500, points a second
+```
+
 That arrives as a `Jbr::Error`. 631 points short of a query the bucket holds five times over,
 which a second would have refilled — worth asking again. A cost above `maximumAvailable` is
 worth nothing but a smaller query. Either way the decision belongs to whoever called: from a

data/lib/graphql/client.rb

@@ -22,12 +22,23 @@ module GraphQL
       raise Unauthorized, response.body if response.code == '401'
       raise Error, response.body unless response.is_a? Net::HTTPSuccess
       body = JSON.parse(response.body)
-      raise Error, refusal(body) if body['errors'].present?
+      raise refusal_for(body) if body['errors'].present?
       body.fetch('data')
     end
 
   private
 
+    # Refused over cost where the endpoint names the code for it, or prices the query above
+    # what it says was left. Anything else is a refusal of the query itself.
+    def refusal_for(body)
+      cost = body['extensions'].to_h['cost'].to_h
+      available = cost['throttleStatus'].to_h['currentlyAvailable']
+      coded = body['errors'].any? { |error| error.to_h.dig('extensions', 'code') == 'THROTTLED' }
+      priced = available && cost['requestedQueryCost'].to_f > available.to_f
+
+      coded || priced ? Throttled.new(refusal(body), cost) : Error.new(refusal(body))
+    end
+
     # What the endpoint refused, and — where it priced the refusal — what the query would have
     # cost against what was available. `Throttled` on its own leaves a caller unable to tell a
     # query too big to ever run from a bucket that a moment would have refilled.

data/lib/graphql/throttled.rb

@@ -0,0 +1,16 @@
+module GraphQL
+  # An endpoint refusing a query for what it costs rather than for anything about the query
+  # itself. Worth telling apart: the same query is answered once the budget it is priced
+  # against has refilled.
+  class Throttled < Error
+    # @param message [String] what the endpoint said, with the numbers it said it with.
+    # @param cost [Hash] what it priced the query at, and the budget it priced it against.
+    def initialize(message, cost = {})
+      super message
+      @cost = cost
+    end
+
+    # @return [Hash] those numbers, in the endpoint's own words.
+    attr_reader :cost
+  end
+end

data/lib/jbr/oauth.rb

@@ -47,6 +47,8 @@ module Jbr
       client.query statement, variables: variables
     rescue GraphQL::Unauthorized
       refresh ? retry : {}
+    rescue GraphQL::Throttled => error
+      raise Retriable.new(error.message, error.cost)
     rescue GraphQL::Error => error
       # The transport's own class never leaves the gem: a caller told to rescue `Jbr::Error`
       # was not catching a throttle, a 500 or an unreadable answer, and had its own job blow

data/lib/jbr/retriable.rb

@@ -0,0 +1,20 @@
+module Jbr
+  # Jobber refusing a query over what it costs rather than over anything about the query. The
+  # bucket it is priced against refills, so the same question asked later is answered.
+  class Retriable < Error
+    # @param message [String] what Jobber said, with the numbers it said it with.
+    # @param cost [Hash] the `requestedQueryCost` and the `throttleStatus` beside it.
+    def initialize(message, cost = {})
+      super message
+      status = cost['throttleStatus'].to_h
+      @cost = cost['requestedQueryCost']
+      @available = status['currentlyAvailable']
+      @maximum = status['maximumAvailable']
+      @restore_rate = status['restoreRate']
+    end
+
+    # What the query would have cost, the budget it was priced against, and how fast that
+    # budget refills. A cost above the maximum is one no waiting will pay for.
+    attr_reader :cost, :available, :maximum, :restore_rate
+  end
+end

data/lib/jbr/version.rb

@@ -1,5 +1,5 @@
 # A Ruby client for the Jobber API.
 module Jbr
   # The version of this gem.
-  VERSION = '3.7.2'
+  VERSION = '3.8.0'
 end

data/lib/jbr.rb

@@ -11,6 +11,7 @@ require 'active_support/core_ext/array/conversions'
 
 require 'graphql/error'
 require 'graphql/unauthorized'
+require 'graphql/throttled'
 require 'graphql/client'
 
 require 'jbr/mock'
@@ -18,6 +19,7 @@ require 'jbr/mock'
 require 'jbr/url'
 require 'jbr/error'
 require 'jbr/refused'
+require 'jbr/retriable'
 require 'jbr/token'
 require 'jbr/refreshing'
 # Phone before Cliental, and Cliental before the records that include it: what each asks

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 3.7.2
+  version: 3.8.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -106,6 +106,7 @@ files:
 - README.md
 - lib/graphql/client.rb
 - lib/graphql/error.rb
+- lib/graphql/throttled.rb
 - lib/graphql/unauthorized.rb
 - lib/jbr.rb
 - lib/jbr/account.rb
@@ -144,6 +145,7 @@ files:
 - lib/jbr/refused.rb
 - lib/jbr/request.rb
 - lib/jbr/resource.rb
+- lib/jbr/retriable.rb
 - lib/jbr/token.rb
 - lib/jbr/url.rb
 - lib/jbr/version.rb