jbr 3.7.2 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e017275cf5a3a41647f3817608327ddf8fa909c2fdf25e1f8c2a43ee1ad3b044
-  data.tar.gz: 1d01c835b75bd16cd21b8d4e658644520cc065c0659b1f394f105e02775b8f69
+  metadata.gz: 815b57ea81f9bda41efb8b7d09a0767224763b895126a3ee56acabab6266b3fc
+  data.tar.gz: 127a174761ddb6bc0cc00cb34ffd9e49044152d575f3f5e4f42a030f222023a5
 SHA512:
-  metadata.gz: 89e55dd309b839918c67d79ee4c761d28cacb3f2c0dba30daa996354b0a22c4436aa52928dbfb7208df62609073157f77e42f7349943f4f58a2910dea1f43f00
-  data.tar.gz: 2cd3bf9d534e4fbb349debe3643aad4a62982e5780e27e558214594ffe9d536413bc5e8d837976d832422011b5da9be146bd9998492f6c33d99011274c213ef5
+  metadata.gz: 3be4d269a045c6d9e0629a27922697f93c102259eee21762fcef02b0e5257f1b4ebd05e56812faa47e41b68a94ea440624c02621eaa95a4449db42dda94d62f4
+  data.tar.gz: d34a6393d787cb20628cf4a18e0c63ffe63bdecaa3cf00e7e84016f8423fca125567549cda5ced525770b07d6354103be476c00d54b21b936e6769a728efe8b8

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

@@ -113,13 +113,14 @@ 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. A walk paces itself, so a long one is never refused: see
-[Rate limits](#rate-limits).
+as the account has pages. A walk is priced by what its pages carry, and a long one can be
+refused for it: see [Rate limits](#rate-limits).
 
 ```ruby
 jobs = oauth.jobs # => an Enumerable of every job, nothing fetched yet
-oauth.jobs.past # => an Enumerator of the ones dated before now
-oauth.jobs.upcoming # => an Enumerator of the ones dated from now on
+oauth.jobs.past # => the ones dated before now, nothing fetched yet
+oauth.jobs.upcoming # => the ones dated from now on, nothing fetched yet
+oauth.jobs.past.ids # => %w[Z2lkOi8vS ...], every page of them, and nothing else about them
 
 job = jobs.first
 job.name # => 'Furnace tune-up', or the job's ID where nobody titled it. Never nil or empty
@@ -175,8 +176,9 @@ Walk the account's visits, oldest first, the same way as its jobs:
 
 ```ruby
 visits = oauth.visits # => an Enumerable of every visit, nothing fetched yet
-oauth.visits.upcoming # => an Enumerator of the ones dated from now on
-oauth.visits.past # => an Enumerator of the ones dated before now
+oauth.visits.upcoming # => the ones dated from now on, nothing fetched yet
+oauth.visits.past # => the ones dated before now, nothing fetched yet
+oauth.visits.upcoming.ids # => %w[Z2lkOi8vS ...], every page of them, and nothing else
 
 visit = visits.first
 visit.id # => 'Z2lkOi8vS'
@@ -228,6 +230,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
@@ -237,6 +249,15 @@ holding a transaction open.
 Every connection the gem asks for is bounded, to keep a query on the affordable side of that:
 twenty lines to a job, and twenty jobs or visits to a page.
 
+`ids` is the cheap way to walk an account. It asks for the ID and nothing else, which prices
+a row at a fraction of a record and buys a hundred of them to a page — so five times the
+account is read for a fraction of the budget. Reach for it where each record is then read on
+its own with `find`, one background job at a time:
+
+```ruby
+oauth.jobs.past.ids.each { |id| ImportJob.perform_later id }
+```
+
 ### Events
 
 Parse the payload of a Jobber event webhook:

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/jobs.rb

@@ -1,23 +1,13 @@
 module Jbr
   # The jobs on a Jobber account, oldest first, walked a page at a time.
   class Jobs < Resource
-    include Enumerable, Includable
+    include Includable, Listable
 
     # What a job answers with wherever one is read, before anything it was asked to bring
     # back with it.
     FIELDS = 'id title instructions jobStatus total createdAt startAt completedAt ' \
              'quote { id amounts { total } }'
 
-    # Every job on the account, past and future alike. Nothing is read until the walk starts,
-    # and a page is read only once the one before it runs out.
-    def each(&) = walk.each(&)
-
-    # @return [Enumerator<Job>] the jobs scheduled from now on.
-    def upcoming = walk from_now
-
-    # @return [Enumerator<Job>] the jobs that started before now.
-    def past = walk until_now
-
     # Shadows Enumerable#find on purpose, the way Active Record does: a job is reached by the
     # ID Jobber files it under, not by asking every job on the account whether it is the one.
     # @param id [String] the Jobber ID of the job.
@@ -29,20 +19,7 @@ module Jbr
 
   private
 
-    # Twenty a page, not forty and not a hundred: Jobber prices a query by its page size, and
-    # what an includes brings back is charged for on top of every row of it — so a page of jobs
-    # carrying their lines, their property and its client priced past what a bucket holds. Half
-    # the page costs half the query and loses nothing, since a walk simply reads more pages.
-    def page
-      <<~GRAPHQL
-        query($after: String, $filter: JobFilterAttributes) {
-          jobs(first: 20, after: $after, filter: $filter) {
-            nodes { #{FIELDS} #{selections} }
-            pageInfo { hasNextPage endCursor }
-          }
-        }
-      GRAPHQL
-    end
+    def page = paged "#{FIELDS} #{selections}", PAGE
 
     def one
       <<~GRAPHQL
@@ -54,6 +31,8 @@ module Jbr
 
     def field = 'jobs'
 
+    def filtered = 'JobFilterAttributes'
+
     def item(node) = Job.new node: node
   end
 end

data/lib/jbr/listable.rb

@@ -0,0 +1,73 @@
+module Jbr
+  # What a list of records answers, and how much of an account it costs to ask. Jobber prices
+  # a query by the page it asks for and by what every row of that page carries, so a list is
+  # read either as records or as the IDs alone, each with a page sized to what it carries.
+  module Listable
+    include Enumerable
+
+    # Records a page, not forty and not a hundred: what an includes brings back is charged for
+    # on top of every row of it, so a page of jobs carrying their lines, their property and its
+    # client priced past what a bucket holds. Half the page costs half the query and loses
+    # nothing, since a walk simply reads more pages.
+    PAGE = 20
+
+    # IDs a page, which the same budget affords five times over where a row carries one field
+    # and no nesting at all.
+    IDS_PAGE = 100
+
+    # Every record the list is narrowed to, oldest first. Nothing is read until the walk
+    # starts, and a page is read only once the one before it runs out.
+    def each(&) = walk(page).each(&)
+
+    # @return [Listable] the same list, narrowed to what is scheduled from now on.
+    def upcoming = narrowed from_now
+
+    # @return [Listable] the same list, narrowed to what started before now.
+    def past = narrowed until_now
+
+    # The ID Jobber files each record under, and nothing else about it: the cheapest question
+    # an account can be walked with, and the one to ask where every record is then read on its
+    # own through {#find}.
+    # @return [Array<String>] every ID in the list, every page of them read.
+    def ids = walk(ids_page).map(&:id)
+
+  private
+
+    def narrowed(filter) = self.class.new(oauth: @oauth, includes: @includes, filter: filter)
+
+    # The two halves of a schedule, split at the moment they are asked for rather than per
+    # page: read page by page the boundary would slide, and something could cross it unseen.
+    def from_now = { startAt: { after: Time.now.iso8601 } }
+
+    def until_now = { startAt: { before: Time.now.iso8601 } }
+
+    # Every record a paged query answers, one at a time, a page read only once the one before
+    # it runs out. The filter is data: narrowed to nothing, the query narrows nothing.
+    def walk(statement)
+      Enumerator.new do |yielder|
+        after = nil
+        loop do
+          answered = @oauth.query statement, variables: { after: after, filter: @filter }.compact
+          current = answered.fetch field, {}
+          current.fetch('nodes', []).each { |node| yielder << item(node) }
+          break unless current.dig 'pageInfo', 'hasNextPage'
+
+          after = current.dig 'pageInfo', 'endCursor'
+        end
+      end
+    end
+
+    def ids_page = paged 'id', IDS_PAGE
+
+    def paged(fields, size)
+      <<~GRAPHQL
+        query($after: String, $filter: #{filtered}) {
+          #{field}(first: #{size}, after: $after, filter: $filter) {
+            nodes { #{fields} }
+            pageInfo { hasNextPage endCursor }
+          }
+        }
+      GRAPHQL
+    end
+  end
+end

data/lib/jbr/mock/jobs.rb

@@ -1,24 +1,25 @@
 module Jbr
-  # The jobs an app under test asked {Jbr.mock} to answer with.
+  # The jobs an app under test asked {Jbr.mock} to answer with. Only the walk is mocked:
+  # narrowing a list, and reading it as records or as IDs, is the same code a real one runs.
   class Mock::Jobs < Jobs
     # The job filed under that ID where the app listed one, and otherwise the single job it
     # named — which is every app that mocks a lookup without mocking a list.
     # @return [Mock::Job] the job asked for.
     def find(id) = Mock::Job.new node: listed(id) || Jbr.mock.job
 
-    # @return [Enumerator<Mock::Job>] every job the app named.
-    def each(&) = mocked(Jbr.mock.jobs).each(&)
-
-    # @return [Enumerator<Mock::Job>] those it dated from now on, and any it left undated.
-    def upcoming = mocked Jbr.mock.jobs.reject { |job| started? job }
+  private
 
-    # @return [Enumerator<Mock::Job>] those it dated before now.
-    def past = mocked Jbr.mock.jobs.select { |job| started? job }
+    def walk(_statement)
+      Enumerator.new { |yielder| selected.each { |job| yielder << Mock::Job.new(node: job) } }
+    end
 
-  private
+    # The half of the schedule the list was narrowed to, from what the app dated each job.
+    # One it left undated is one nothing has started, so it counts as upcoming.
+    def selected
+      return Jbr.mock.jobs unless @filter
 
-    def mocked(jobs)
-      Enumerator.new { |yielder| jobs.each { |job| yielder << Mock::Job.new(node: job) } }
+      started = @filter.dig(:startAt, :before).present?
+      Jbr.mock.jobs.select { |job| started?(job) == started }
     end
 
     def started?(job) = job[:scheduled_at] ? job[:scheduled_at] <= Time.now : false

data/lib/jbr/mock/visits.rb

@@ -1,22 +1,23 @@
 module Jbr
-  # The visits an app under test asked {Jbr.mock} to answer with.
+  # The visits an app under test asked {Jbr.mock} to answer with. Only the walk is mocked:
+  # narrowing a list, and reading it as records or as IDs, is the same code a real one runs.
   class Mock::Visits < Visits
-    # @return [Enumerator<Mock::Visit>] every visit the app named.
-    def each(&) = mocked(Jbr.mock.visits).each(&)
-
-    # @return [Enumerator<Mock::Visit>] those it dated from now on, and any it left undated.
-    def upcoming = mocked Jbr.mock.visits.reject { |visit| started? visit }
-
-    # @return [Enumerator<Mock::Visit>] those it dated before now.
-    def past = mocked Jbr.mock.visits.select { |visit| started? visit }
-
     # @return [Mock::Visit] the visit the app listed under that ID.
     def find(id) = Mock::Visit.new node: listed(id)
 
   private
 
-    def mocked(visits)
-      Enumerator.new { |yielder| visits.each { |visit| yielder << Mock::Visit.new(node: visit) } }
+    def walk(_statement)
+      Enumerator.new { |yielder| selected.each { |it| yielder << Mock::Visit.new(node: it) } }
+    end
+
+    # The half of the schedule the list was narrowed to, from what the app dated each visit.
+    # One it left undated is one nothing has started, so it counts as upcoming.
+    def selected
+      return Jbr.mock.visits unless @filter
+
+      started = @filter.dig(:startAt, :before).present?
+      Jbr.mock.visits.select { |visit| started?(visit) == started }
     end
 
     def started?(visit) = visit[:starts_at] ? visit[:starts_at] <= Time.now : false

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/resource.rb

@@ -1,15 +1,17 @@
 module Jbr
   # What every Jobber resource shares: the node Jobber answered with, the credentials it was
-  # read through, and the paging that every list of them arrives in.
+  # read through, and what a list of them was asked and narrowed to.
   class Resource
     # @param oauth [OAuth] the credentials to reach Jobber with, where reaching it is needed.
     # @param node [Hash] the record as Jobber answered it.
     # @param includes [Hash] what a list was asked to bring back beside its records.
-    def initialize(oauth: nil, node: {}, includes: {})
+    # @param filter [Hash] what a list was narrowed to, in the shape Jobber filters by.
+    def initialize(oauth: nil, node: {}, includes: {}, filter: nil)
       @oauth = oauth
       @node = node
       @id = node['id']
       @includes = includes
+      @filter = filter
     end
 
     # @return [String, nil] the Jobber ID, from the node it came in or once one was created.
@@ -20,27 +22,5 @@ module Jbr
     # @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.
-    def walk(filter = nil)
-      Enumerator.new do |yielder|
-        after = nil
-        loop do
-          answered = @oauth.query(page, variables: { after: after, filter: filter }.compact)
-          current = answered.fetch field, {}
-          current.fetch('nodes', []).each { |node| yielder << item(node) }
-          break unless current.dig 'pageInfo', 'hasNextPage'
-
-          after = current.dig 'pageInfo', 'endCursor'
-        end
-      end
-    end
-
-    # The two halves of a schedule, split at the moment they are asked for rather than per
-    # page: read page by page the boundary would slide, and something could cross it unseen.
-    def from_now = { startAt: { after: Time.now.iso8601 } }
-
-    def until_now = { startAt: { before: Time.now.iso8601 } }
   end
 end

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.9.0'
 end

data/lib/jbr/visits.rb

@@ -1,21 +1,11 @@
 module Jbr
   # The visits on a Jobber account, oldest first, walked a page at a time.
   class Visits < Resource
-    include Enumerable, Includable
+    include Includable, Listable
 
     # What a visit answers with, before anything it was asked to bring back with it.
     FIELDS = 'id title startAt endAt allDay clientConfirmed job { id }'
 
-    # Every visit on the account, past and future alike. Nothing is read until the walk
-    # starts, and a page is read only once the one before it runs out.
-    def each(&) = walk.each(&)
-
-    # @return [Enumerator<Visit>] the visits scheduled from now on.
-    def upcoming = walk from_now
-
-    # @return [Enumerator<Visit>] the visits that started before now.
-    def past = walk until_now
-
     # Shadows Enumerable#find on purpose, the way jobs do: a visit is reached by the ID Jobber
     # files it under, not by asking every visit on the account whether it is the one.
     # @param id [String] the Jobber ID of the visit.
@@ -27,6 +17,8 @@ module Jbr
 
   private
 
+    def page = paged "#{FIELDS} #{selections}", PAGE
+
     def one
       <<~GRAPHQL
         query($id: EncodedId!) {
@@ -35,21 +27,10 @@ module Jbr
       GRAPHQL
     end
 
-    # Twenty a page, the same as jobs: Jobber prices a query by its page size, and what an
-    # includes brings back is charged for on top of every row of it.
-    def page
-      <<~GRAPHQL
-        query($after: String, $filter: VisitFilterAttributes) {
-          visits(first: 20, after: $after, filter: $filter) {
-            nodes { #{FIELDS} #{selections} }
-            pageInfo { hasNextPage endCursor }
-          }
-        }
-      GRAPHQL
-    end
-
     def field = 'visits'
 
+    def filtered = 'VisitFilterAttributes'
+
     def item(node) = Visit.new node: node
   end
 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
@@ -34,6 +36,7 @@ require 'jbr/account'
 require 'jbr/property'
 require 'jbr/properted'
 require 'jbr/includable'
+require 'jbr/listable'
 # LineItem before Itemized, and both before Job: the lines a job is made of are asked for
 # by a constant the include reads as it loads.
 require 'jbr/line_item'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 3.7.2
+  version: 3.9.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
@@ -119,6 +120,7 @@ files:
 - lib/jbr/job.rb
 - lib/jbr/jobs.rb
 - lib/jbr/line_item.rb
+- lib/jbr/listable.rb
 - lib/jbr/mock.rb
 - lib/jbr/mock/account.rb
 - lib/jbr/mock/client.rb
@@ -144,6 +146,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