jbr 3.1.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97dff097405bb45eb1ac6048e9ce131d6905f19221e1e910ccff1f533ede76ed
-  data.tar.gz: 2cf46317599aa7146b73fa734441a0c995749692cea4565bcc6646b80fff478c
+  metadata.gz: 074fba6db0300fd967935b1996f1791016e216aa49ef829e771f56340400af1f
+  data.tar.gz: c8433c006174ab91d76db6a331268c325a90ff4f049f179c5adf46acd9716487
 SHA512:
-  metadata.gz: 6fc99f2dbaa979073811af9382023b10acde8182e89ded303876876f92e54bcbce9f2ee732917003571823aa2b3127b8f960ad912f88ab53935e8041022b3f4a
-  data.tar.gz: 656ca93656a1702f226d9f8aa4ed12e7e0d31f01a1ac4cda426096ec7eea48e30e5b2977ccbc113a5dfa21fdb6084009b400caae836f23335a4bd28a4626511d
+  metadata.gz: 1d3e116c317b973a9600af44e3fd02466e360321f08b4e1c696c2e214854b91b8318c45a8ffdb7c50f6f880bf07e6388bf060d33f54ad58b60b2ead27aab535d
+  data.tar.gz: 28ee328df69a90a166cfaa4ed6ee0b22fad572c7bca8defb501afba0b3054c652b17741df883f4be32b0bd33ca7253a4a7e5872564b2f636f02d459323a7693c

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [3.3.0] - 2026-08-13
+
+- [Fix] Credentials are given up only when Jobber says the grant itself is no good. Any
+  refusal at all used to set `invalid_at` -- a 500, a rate limit, an unreadable body -- so
+  a moment of trouble at Jobber's end read as a dead token, and an app acting on that could
+  revoke one that still worked. Only an `invalid_grant` Jobber names counts now; everything
+  else raises `Jbr::Error` for the caller to retry, which is what trouble deserves
+- [New] `Jbr::Refused`, a `Jbr::Error` for the grant being no good rather than for the
+  answer failing to arrive. Rescue it to tell the two apart
+- [Change] The token endpoint moved to `Jbr::Token`. `Jbr::OAuth.post` still answers it
+  unchanged, and so do `Jbr::OAuth.client_id` and `Jbr::OAuth.client_secret`
+
+## [3.2.0] - 2026-08-13
+
+- [New] Wait rather than be refused. Jobber holds an app to two limits at once -- 2,500
+  requests every five minutes, and a bucket of query cost that drains as it is asked --
+  and a walk of many pages could reach either. Every request now spaces itself 0.12s from
+  the one before, which is the count spread evenly over the window, and reads the bucket
+  Jobber reports beside the data to wait longer where the next page cannot be paid for.
+  A request that follows no other waits for nothing, so a single lookup is as quick as it
+  was: only a walk long enough to be a problem is slowed, and only as much as it must be
+
 ## [3.1.0] - 2026-08-13
 
 - [Fix] An answer Jobber left empty now reads as no answer rather than as an empty string.

data/README.md

@@ -41,6 +41,16 @@ Revoke credentials:
 oauth.delete
 ```
 
+Credentials go bad only when Jobber says so. A refused refresh — the `invalid_grant` Jobber
+names — sets `invalid_at` and answers queries with nothing. Anything else that goes wrong,
+including a 500 or a rate limit, raises `Jbr::Error` instead, because a token that may still
+work is worth more than a tidy failure:
+
+```ruby
+oauth.invalid_at # => 2026-08-13 11:02:41, or nil while the credentials are good
+oauth.query '{ ok }' # => {} once they are refused, raises Jbr::Error where Jobber had trouble
+```
+
 ### Requests
 
 Create a Jobber request, finding or creating a Client with a matching phone number:
@@ -76,7 +86,8 @@ job.completed_at # => 2026-05-18 11:36:13
 
 Or walk the account's jobs, oldest first. Jobber is asked for a page at a time, and only
 once the page before it runs out, so `first` costs one request where `to_a` costs as many
-as the account has pages:
+as the account has pages. A walk paces itself, so a long one is never refused: see
+[Rate limits](#rate-limits).
 
 ```ruby
 jobs = oauth.jobs # => an Enumerable of every job, nothing fetched yet
@@ -154,6 +165,20 @@ visit.property.client.name # => whoever the place sits on the file of
 Ask for nothing and nothing arrives: `oauth.visits.first.client.name` is nil where the
 query never named a client.
 
+### Rate limits
+
+Jobber holds an app to two limits at once: 2,500 requests every five minutes, and a bucket
+of query cost that drains as it is asked and refills at a rate it reports. Nothing has to be
+done about either — every request waits for itself:
+
+- It spaces itself 0.12 seconds from the request before, which is 2,500 spread evenly over
+  five minutes.
+- It reads `extensions.cost` off each answer, and where the bucket can no longer pay for a
+  page like the last one, it waits for the shortfall to refill at Jobber's own restore rate.
+
+A request that follows no other waits for nothing, so a single `find` is as quick as it ever
+was. Only a walk long enough to be a problem is slowed, and only by as much as it must be.
+
 ### Events
 
 Parse the payload of a Jobber event webhook:

data/lib/graphql/client.rb

@@ -16,6 +16,7 @@ module GraphQL
 
     # @param query [String] the GraphQL query string.
     # @param variables [Hash] the variables to interpolate into the query.
+    # @yield [Hash] the `extensions` the endpoint answered beside the data, where it did.
     # @return [Hash] the `data` portion of the GraphQL response.
     def query(query, variables: {})
       response = Net::HTTP.post @endpoint, { query:, variables: }.to_json, request_headers
@@ -24,6 +25,7 @@ module GraphQL
       body = JSON.parse(response.body)
       errors = body['errors']
       raise Error, errors.map { |error| error['message'] }.join('; ') if errors.present?
+      yield body['extensions'] if block_given?
       body.fetch('data')
     end
 

data/lib/jbr/oauth.rb

@@ -34,12 +34,11 @@ module Jbr
     def requests = Request.new oauth: self
     def visits = Visits.new oauth: self
 
-    # Run a statement, refreshing the access token once if Jobber says it expired.
-    # @param statement [String] the query or mutation to run.
-    # @param variables [Hash] the variables it interpolates.
+    # Run a statement, waiting for what Jobber will still answer and refreshing a stale token.
     # @return [Hash] the data Jobber answered, or empty when the credentials are dead.
     def query(statement, variables: {})
-      client.query statement, variables: variables
+      throttle.wait
+      client.query(statement, variables: variables) { |extensions| throttle.read extensions }
     rescue GraphQL::Unauthorized
       refresh ? retry : {}
     end
@@ -65,27 +64,21 @@ module Jbr
     # @return [String, nil] The client secret to interact with the API.
     def self.client_secret = ENV['JOBBER_CLIENT_SECRET']
 
-    # Exchange a code or a refresh token for credentials. Public because #refresh
-    # reaches it through self.class, which a private class method forbids.
+    # Exchange a code or a refresh token for credentials.
     def self.post(params = {})
-      uri = URI 'https://api.getjobber.com/api/oauth/token'
-      response = Net::HTTP.post_form uri,
-        params.merge(client_id: client_id, client_secret: client_secret)
-      raise Error, response.body unless response.is_a? Net::HTTPSuccess
-      output = JSON.parse(response.body)
-      { access_token: output['access_token'], refresh_token: output['refresh_token'],
-        expires_at: (Time.now + output.fetch('expires_in', 3600).to_i),
-      }
+      Token.post params.merge(client_id: client_id, client_secret: client_secret)
     end
 
   private
 
+    def throttle = @throttle ||= Throttle.new
+
     def refresh
       output = self.class.post refresh_token: @refresh_token, grant_type: 'refresh_token'
       @access_token = output[:access_token]
       @refresh_token = output[:refresh_token]
       @expires_at = output[:expires_at]
-    rescue Error => e
+    rescue Refused
       @invalid_at = Time.now
       false
     end

data/lib/jbr/refused.rb

@@ -0,0 +1,5 @@
+module Jbr
+  # Jobber refusing the grant itself, rather than failing to answer about it. The first is a
+  # token that will never work again; the second may be a moment of trouble at their end.
+  Refused = Class.new Error
+end

data/lib/jbr/throttle.rb

@@ -0,0 +1,42 @@
+module Jbr
+  # How much Jobber will still answer, and how long to wait before asking again. Jobber holds
+  # an app to two limits at once, and this keeps both: a count of requests over a window, and
+  # a bucket of query cost that drains as it is asked and refills at a rate it reports.
+  class Throttle
+    # Jobber answers 2,500 requests every 5 minutes, which is one every 0.12 seconds. Spacing
+    # them is what keeps a walk of many pages under the count, whatever each page costs.
+    SPACING = 300.0 / 2_500
+
+    # @return [Float] the seconds waited, which is zero where nothing was owed.
+    def wait
+      owed = [ spacing_owed, restore_owed ].max
+      sleep owed if owed.positive?
+      @asked_at = Time.now
+      owed
+    end
+
+    # Takes in what the answer said it had left. Jobber reports the bucket beside the data,
+    # so what the next caller may ask for is known before they ask for it.
+    # @param extensions [Hash, nil] the +extensions+ Jobber answered beside the data.
+    def read(extensions)
+      cost = extensions.to_h['cost'].to_h
+      status = cost['throttleStatus'].to_h
+      @cost = cost['actualQueryCost'].to_f
+      @available = status['currentlyAvailable'].to_f
+      @restore_rate = status['restoreRate'].to_f
+    end
+
+  private
+
+    # Nothing is owed to the first caller: a request that follows no other is not too soon.
+    def spacing_owed = (@asked_at ? [ SPACING - (Time.now - @asked_at), 0.0 ].max : 0.0)
+
+    # What the last answer cost is what the next one is taken to cost, since a walk asks the
+    # same query of every page. Where the bucket cannot pay for it, wait for it to refill.
+    def restore_owed
+      return 0.0 unless @restore_rate.to_f.positive? && @available.to_f < @cost.to_f
+
+      (@cost - @available) / @restore_rate
+    end
+  end
+end

data/lib/jbr/token.rb

@@ -0,0 +1,35 @@
+module Jbr
+  # The endpoint that trades an authorization code or a refresh token for credentials.
+  class Token
+    # 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'
+
+    # Trade a grant for credentials.
+    # @param params [Hash] the grant, and the app making the exchange.
+    # @raise [Refused] where Jobber says the grant itself is no good.
+    # @raise [Error] where Jobber could not answer about it.
+    # @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 Error, response.body unless response.is_a? Net::HTTPSuccess
+
+      output = JSON.parse response.body
+      { access_token: output['access_token'], refresh_token: output['refresh_token'],
+        expires_at: (Time.now + output.fetch('expires_in', 3600).to_i),
+      }
+    end
+
+    def self.refused?(response)
+      return false if response.is_a? Net::HTTPSuccess
+
+      JSON.parse(response.body)['error'] == REFUSAL
+    rescue JSON::ParserError
+      false
+    end
+    private_class_method :refused?
+  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.1.0'
+  VERSION = '3.3.0'
 end

data/lib/jbr.rb

@@ -15,12 +15,15 @@ require 'jbr/mock'
 
 require 'jbr/url'
 require 'jbr/error'
+require 'jbr/refused'
+require 'jbr/token'
 # Phone before Cliental, and Cliental before the records that include it: what each asks
 # Jobber for about a client is built as they load.
 require 'jbr/phone'
 require 'jbr/cliental'
 require 'jbr/named'
 require 'jbr/resource'
+require 'jbr/throttle'
 require 'jbr/request'
 require 'jbr/oauth'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -137,8 +137,11 @@ files:
 - lib/jbr/properted.rb
 - lib/jbr/property.rb
 - lib/jbr/quote.rb
+- lib/jbr/refused.rb
 - lib/jbr/request.rb
 - lib/jbr/resource.rb
+- lib/jbr/throttle.rb
+- lib/jbr/token.rb
 - lib/jbr/url.rb
 - lib/jbr/version.rb
 - lib/jbr/visit.rb