jbr 3.7.1 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28dde29d20aa9063e6e24e2226d81bf69ec7593ba99efd8a6f335d9fd83c8a10
-  data.tar.gz: 106b0db3001c4aa10c6ef449d4204c6ad2e4574494b6033e7eadf1d13f3ccc59
+  metadata.gz: de01eb560b5d6366142d35901817eae421a30ccebf31aeede4cacb2e97720cd3
+  data.tar.gz: 1a613711f19080da2368d9b2d38d2e9fff372dbd4e37126b2bc06e9d4c9a9493
 SHA512:
-  metadata.gz: 49a59576a7951bc00a29f4ec861576be2e28e448e53c1be2911dd094ebea9a7715a5e98eb34a2d208538ee63a8bd83b402f71b461e390d38aeb7a8885b816bd1
-  data.tar.gz: d20c5ee0c9ddb0927649b884c45f84b7d7e97e315c54a2fd29c779a1b51c3f3691b5417d79e2dc4297d86f4795966703eb3462794ad0f867a0392cc9e9e4411d
+  metadata.gz: 9b8fc6971e3cbe48eecf5025cb7f5b9beb9e7490a0b7a6830b0a22eb9b4c98fbe3c066686866dff576de01bfc0e10f16050c6bd1002b929bd18940dfeeccd137
+  data.tar.gz: 2cbdcb7fd7bd995bf7450784afdb08d59acce2c0ea788f3192a1c62aabaf00251497bfb8ff6efa57a932d96a15735dbaa9bdc4e846824679521056e7a3129e33

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [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
+  branch for the OAuth 2 `invalid_grant` in a JSON body, guarded by a rescue for a body that
+  would not parse — and every failure body Jobber has ever been seen to send is prose, so the
+  rescue was the path and the branch it protected had never once been taken. Both are gone
+
 ## [3.7.1] - 2026-08-17
 
 - [Fix] A refresh token Jobber will not take gives the credentials up, as it always should

data/README.md

@@ -67,11 +67,11 @@ Revoke credentials:
 oauth.delete
 ```
 
-Credentials go bad only when Jobber says so of the grant itself: the `invalid_grant` it names,
-or the 401 it answers a refresh token it will not take. Either sets `invalid_at` and answers
-queries with nothing. Anything else that goes wrong raises `Jbr::Error` instead — a 500, a rate
-limit, and the 401 Jobber answers an app whose own client id and secret are wrong, which is
-every account's grant at once rather than this one's:
+Credentials go bad only when Jobber says so of the grant itself — `The provided refresh token
+is not valid.` — which sets `invalid_at` and answers queries with nothing. Anything else that
+goes wrong raises `Jbr::Error` instead: a 500, a rate limit, and the 401 Jobber answers an app
+whose own client id and secret are wrong, which is every account's grant at once rather than
+this one's:
 
 ```ruby
 oauth.invalid_at # => 2026-08-13 11:02:41, or nil while the credentials are good
@@ -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/token.rb

@@ -4,12 +4,10 @@ module Jbr
     # Where a grant is exchanged.
     URL = 'https://api.getjobber.com/api/oauth/token'
 
-    # What Jobber calls a grant that is no good, in the OAuth 2 word for it.
-    REFUSAL = 'invalid_grant'
-
-    # And what it calls one in the prose it answers a refresh token with instead. Specific to
-    # the token rather than to the app, which is the whole reason for reading the body.
-    REFUSAL_TEXT = /refresh token is not valid/
+    # What Jobber says of a grant it will not take, in the prose it answers with. About the
+    # token rather than about the app, which is what tells it from the 401 a wrong client id and
+    # secret get — and that one is every account at once rather than this one.
+    REFUSAL = /refresh token is not valid/
 
     # Trade a grant for credentials.
     # @param params [Hash] the grant, and the app making the exchange.
@@ -18,7 +16,7 @@ module Jbr
     # @return [Hash] the tokens, and the moment the access one expires.
     def self.post(params = {})
       response = Net::HTTP.post_form URI(URL), params
-      raise Refused, response.body if refused? response
+      raise Refused, response.body if REFUSAL.match? response.body
       raise Error, response.body unless response.is_a? Net::HTTPSuccess
 
       output = JSON.parse response.body
@@ -26,22 +24,5 @@ module Jbr
         expires_at: (Time.now + output.fetch('expires_in', 3600).to_i),
       }
     end
-
-    # Refused where Jobber turns the grant down rather than failing to answer about it: it names
-    # the word, or it names the token. Never the status on its own — Jobber answers 401 to a
-    # refresh token it will not take and 401 to an app whose own credentials are wrong, and
-    # acting on the second as though it were the first would disconnect every account at once.
-    def self.refused?(response)
-      return false if response.is_a? Net::HTTPSuccess
-
-      coded_refusal?(response.body) || REFUSAL_TEXT.match?(response.body.to_s)
-    end
-
-    def self.coded_refusal?(body)
-      JSON.parse(body)['error'] == REFUSAL
-    rescue JSON::ParserError
-      false
-    end
-    private_class_method :refused?, :coded_refusal?
   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.1'
+  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.1
+  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