jbr 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97dff097405bb45eb1ac6048e9ce131d6905f19221e1e910ccff1f533ede76ed
-  data.tar.gz: 2cf46317599aa7146b73fa734441a0c995749692cea4565bcc6646b80fff478c
+  metadata.gz: d1028c7784920b94426d3c9d52a29232cdb4b8426baf5abe11cbcfe64d9f854f
+  data.tar.gz: d27d31e838ea1fd1c2c3035abf3e21635955039febc8a481bb514a8bd8e9fb9d
 SHA512:
-  metadata.gz: 6fc99f2dbaa979073811af9382023b10acde8182e89ded303876876f92e54bcbce9f2ee732917003571823aa2b3127b8f960ad912f88ab53935e8041022b3f4a
-  data.tar.gz: 656ca93656a1702f226d9f8aa4ed12e7e0d31f01a1ac4cda426096ec7eea48e30e5b2977ccbc113a5dfa21fdb6084009b400caae836f23335a4bd28a4626511d
+  metadata.gz: 74d582435245e0aebf5975748e2ba86e5e53f1190a4f4007d1b50e514df47816082f82a8cdf41b8bd9529e63fe25219035005335ed56708b857ba6aabfdbcb4e
+  data.tar.gz: 6977198a4d12a410b0c2b8ef2aa0cda829a43ec5fda670ce7d9dbcd13301ac2ef3da55b605d4a6ab7e3017839a115c9f757a6a4ae6d86522f4fa584151cb4f12

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [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

@@ -76,7 +76,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 +155,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,8 +64,7 @@ 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,
@@ -80,6 +78,8 @@ module Jbr
 
   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]

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/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.2.0'
 end

data/lib/jbr.rb

@@ -21,6 +21,7 @@ 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.2.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -139,6 +139,7 @@ files:
 - lib/jbr/quote.rb
 - lib/jbr/request.rb
 - lib/jbr/resource.rb
+- lib/jbr/throttle.rb
 - lib/jbr/url.rb
 - lib/jbr/version.rb
 - lib/jbr/visit.rb