jbr 3.0.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f70cfb9bf360eac2836271beef56dc7b2da9c5f2355b8fb4ac51c39c3573f2e8
-  data.tar.gz: cd50eee427d9a2b985a8eb023b1b1afe99a784574d87c52a019fff90e399da47
+  metadata.gz: d1028c7784920b94426d3c9d52a29232cdb4b8426baf5abe11cbcfe64d9f854f
+  data.tar.gz: d27d31e838ea1fd1c2c3035abf3e21635955039febc8a481bb514a8bd8e9fb9d
 SHA512:
-  metadata.gz: 2ddb2eb5dd395b8840ce9b23c55537b6161248002aa131c2759bebbf0dde6bcdfa1c729eadbad3483aead96a232aa258d77a3afed44351f861ac0cffc4ab5729
-  data.tar.gz: e95678d5a04baa3a9811b261682a6cbf71bc588ca8eb3eb78f9f390b53e0928c42798129705a57e71f4cb6ab46905a3dc520e000219d93dfbf2ad33dfb597157
+  metadata.gz: 74d582435245e0aebf5975748e2ba86e5e53f1190a4f4007d1b50e514df47816082f82a8cdf41b8bd9529e63fe25219035005335ed56708b857ba6aabfdbcb4e
+  data.tar.gz: 6977198a4d12a410b0c2b8ef2aa0cda829a43ec5fda670ce7d9dbcd13301ac2ef3da55b605d4a6ab7e3017839a115c9f757a6a4ae6d86522f4fa584151cb4f12

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [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.
+  `client.name` and `job.name` fall through a blank first name or a blank title instead of
+  handing one back, so a caller that validates presence is not handed `""` to store. A job
+  with no title still answers the ID it is filed under; a client with neither a first name
+  nor a company name answers nil
+- [New] A visit answers `name` as a job does -- its title, or the ID Jobber files it under
+  where nobody titled it. Both read it from `Jbr::Named`, so a record Jobber lets go
+  untitled is named the same way wherever it appears
+- [Fix] A blank address field does not come back from `property.address`, and is not sent
+  when a property is opened. Street, city, state and ZIP are absent rather than empty
+- [Fix] A blank timestamp reads as no time. `Time.iso8601` raises on an empty string, so a
+  visit or job Jobber dated with one used to take the whole walk down with it
+- [Change] Depend on Active Support, for `blank?`, `present?`, `presence` and
+  `compact_blank`. Two of its files are required, not the whole library: telling an empty
+  answer from a missing one was being done by hand, and being done inconsistently
+
 ## [3.0.0] - 2026-08-13
 
 - [Breaking change] `oauth.visits` and `oauth.jobs` answer the whole collection rather than

data/README.md

@@ -1,6 +1,7 @@
 # Jobber API Ruby client
 
-A client for the Jobber GraphQL API. It needs nothing but the standard library.
+A client for the Jobber GraphQL API. It needs the standard library and two files of Active
+Support, to tell a field Jobber answered empty from one it never answered at all.
 
 ## Available methods
 
@@ -75,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
@@ -83,7 +85,7 @@ oauth.jobs.past # => an Enumerator of the ones dated before now
 oauth.jobs.upcoming # => an Enumerator of the ones dated from now on
 
 job = jobs.first
-job.name # => 'Furnace tune-up', or the job's ID where nobody titled it. Never nil
+job.name # => 'Furnace tune-up', or the job's ID where nobody titled it. Never nil or empty
 job.title # => 'Furnace tune-up'
 job.instructions # => 'Ring the doorbell twice'
 job.status # => 'requires_invoicing'
@@ -116,6 +118,7 @@ oauth.visits.past # => an Enumerator of the ones dated before now
 
 visit = visits.first
 visit.id # => 'Z2lkOi8vS'
+visit.name # => 'Furnace tune-up', or the visit's ID where nobody titled it. Never nil or empty
 visit.title # => 'Furnace tune-up'
 visit.job_id # => 'Z2lkOi8vS'
 visit.starts_at # => 2026-08-09 14:00:00
@@ -132,7 +135,8 @@ asked for. Chain `includes` the way Active Record does, on visits or on jobs:
 ```ruby
 visit = oauth.visits.includes(:client, property: :client).upcoming.first
 
-visit.client.name # => 'Jane', or the business's name where the client is a business
+visit.client.name # => 'Jane', or the business's name where the client is a business.
+                  # Never an empty string: a blank first name falls through to the company
 visit.client.first_name # => 'Jane'
 visit.client.last_name # => 'Doe'
 visit.client.company_name # => nil
@@ -151,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,14 +16,16 @@ 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
       raise Unauthorized, response.body if response.code == '401'
       raise Error, response.body unless response.is_a? Net::HTTPSuccess
       body = JSON.parse(response.body)
-      errors = body['errors'] || []
-      raise Error, errors.map { |error| error['message'] }.join('; ') unless errors.empty?
+      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/client.rb

@@ -32,8 +32,8 @@ module Jbr
     def company_name = @node['companyName']
 
     # Jobber files nobody without one name or the other, so there is always one to call them.
-    # @return [String] the person's first name, or the business's name.
-    def name = first_name || company_name
+    # @return [String, nil] the person's first name, or the business's name. Never empty.
+    def name = first_name.presence || company_name.presence
 
     # @return [String, nil] the address to write to.
     def email = @node['email']
@@ -89,12 +89,10 @@ module Jbr
       address, email = @create_params[:address], @create_params[:email]
       { firstName: @create_params[:first_name],
         lastName: @create_params[:last_name],
-        properties: ([ { address: Property.address_from(address) } ] if present?(address)),
+        properties: ([ { address: Property.address_from(address) } ] if address.present?),
         phones: [ { number: @create_params[:phone], primary: true } ],
-        emails: ([ { address: email, primary: true } ] if present?(email)),
+        emails: ([ { address: email, primary: true } ] if email.present?),
       }.compact
     end
-
-    def present?(value) = !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
   end
 end

data/lib/jbr/job.rb

@@ -1,15 +1,11 @@
 module Jbr
   # Work a Jobber user accepted and scheduled.
   class Job < Resource
-    include Cliental, Properted
+    include Cliental, Named, Properted
 
     # @return [String, nil] what the job is called, where whoever opened it named it.
     def title = @node['title']
 
-    # A job goes untitled often enough, and something has to stand in for it on a list.
-    # @return [String] the title, or the ID Jobber files the job under.
-    def name = title || id
-
     # @return [String, nil] what the work is, in the words whoever opened the job wrote.
     def instructions = @node['instructions']
 

data/lib/jbr/named.rb

@@ -0,0 +1,9 @@
+module Jbr
+  # Extends a record Jobber lets go untitled: a visit, a job, anything somebody may have
+  # opened without ever typing a name for it.
+  module Named
+    # Untitled happens often enough, and something has to stand in for it on a list.
+    # @return [String] the title, or the ID Jobber files the record under. Never empty.
+    def name = title.presence || id
+  end
+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/property.rb

@@ -44,7 +44,7 @@ module Jbr
     # @param fields [Hash] any of :street, :city, :state and :zip.
     # @return [Hash] the address, without the fields the caller left out.
     def self.address_from(fields = {})
-      FIELDS.to_h { |jobber, ours| [ jobber, fields[ours] ] }.compact
+      FIELDS.to_h { |jobber, ours| [ jobber, fields[ours] ] }.compact_blank
     end
 
     # The fields a caller reads, from the address as Jobber holds it.
@@ -55,7 +55,7 @@ module Jbr
       address ||= {}
       coordinates = address['coordinates'] || {}
       FIELDS.to_h { |jobber, ours| [ ours, address[jobber.to_s] ] }.
-        merge(COORDINATES.to_h { |ours| [ ours, coordinates[ours.to_s] ] }).compact
+        merge(COORDINATES.to_h { |ours| [ ours, coordinates[ours.to_s] ] }).compact_blank
     end
 
     # Reach the property at an address, adding one when none of the client's matches.

data/lib/jbr/resource.rb

@@ -17,8 +17,9 @@ module Jbr
 
   private
 
-    # @return [Time, nil] what Jobber answered under a key, as a time.
-    def time(key) = (Time.iso8601 @node[key] if @node[key])
+    # @return [Time, nil] what Jobber answered under a key, as a time. An empty answer is no
+    #   answer: Time.iso8601 raises on one, where nothing at all it simply has none of.
+    def time(key) = (Time.iso8601 @node[key] if @node[key].present?)
 
     # Every item a paged query answers, one at a time, a page read only once the one before
     # it runs out. The filter is data: handed none, the query narrows nothing.

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.0.0'
+  VERSION = '3.2.0'
 end

data/lib/jbr/visit.rb

@@ -1,7 +1,7 @@
 module Jbr
   # One stop at a property: when the work on a job is scheduled to happen.
   class Visit < Resource
-    include Cliental, Properted
+    include Cliental, Named, Properted
 
     # @return [String, nil] what the visit is called.
     def title = @node['title']

data/lib/jbr.rb

@@ -1,6 +1,12 @@
 require 'json'
 require 'net/http'
 
+# Only the two Active Support files whose methods are used, rather than the whole of it:
+# Jobber answers a field it holds nothing for with an empty string as readily as with null,
+# and a caller who validates presence needs those to arrive as the same nothing.
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/enumerable'
+
 require 'graphql/error'
 require 'graphql/unauthorized'
 require 'graphql/client'
@@ -13,7 +19,9 @@ require 'jbr/error'
 # 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.0.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -117,6 +131,7 @@ files:
 - lib/jbr/mock/visit.rb
 - lib/jbr/mock/visits.rb
 - lib/jbr/mocking.rb
+- lib/jbr/named.rb
 - lib/jbr/oauth.rb
 - lib/jbr/phone.rb
 - lib/jbr/properted.rb
@@ -124,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