jbr 3.5.0 → 3.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f0002106d5864e3b0224d1a454f67813be100c2fca6abd411417f81ac913e53
-  data.tar.gz: 1e7998f2402eea55768b060ddc4057a7d513c29741b419fa5ade852caaf71a7a
+  metadata.gz: b8ab569aab529193190b37620954eb2e95db5ac39ccb2a085a7caa2b6cf66981
+  data.tar.gz: 4d331b9c225a2d0fb8a978f166985f416528a23eac283c4afb31924aecf7bc8b
 SHA512:
-  metadata.gz: 6b7ce3628d2828f50173f6e41bccf9e6cb3dd2c9197dc7bcf0b30e814f49e5e27db25641835e0b8c174cd9c6e6e96daae74b16c3f532e67cf7fb6b45f466035c
-  data.tar.gz: 1cf960b5042097b943e62dd9ced8ab0e4adf0a084f8ca6143ea48b38c9e2510fae13b21d0576c9165916af7a85d587726d6ed34875c34a32bbe019c83632f662
+  metadata.gz: fbe6e4b68d03262584a83279ca00eff9a4a5886413498d5db6cbec643e070d12a863188914e95c87a9365fe8f7aa419796c4238824d3346847fdbbd71960c74e
+  data.tar.gz: c0a9624a47f0c4f3706acdabf95bab82cb9d6e2deef035e88edb08daa89d4cdb686bf6489ea6e3c5fcd5b67dcc2cae4388ed19d4f6db036144366a6bcf995864

data/CHANGELOG.md

@@ -1,3 +1,35 @@
+## [3.6.1] - 2026-08-17
+
+- [Fix] 3.6.0 shipped without the two files it added, `graphql/throttled` and `jbr/asking`, so
+  requiring the gem raised `LoadError` and nothing worked at all. The gem's file list comes
+  from `git ls-files` and the release commit never added them. 3.6.0 is yanked
+
+## [3.6.0] - 2026-08-17
+
+- [Fix] A refusal for cost the bucket can recover from is waited out and asked again, up to
+  four times, rather than raised. A walk of many pages drains the bucket faster than it
+  refills and gets `Throttled (cost 1885, 1254 of 10000 available, restoring 500/s)` — 631
+  points short of a query the bucket holds five times over. The refusal prices the query, so
+  the throttle already knows the shortfall: 1.26 seconds at 500 a second, and the same
+  question is answered
+- [Change] Only a query costing more than the bucket *ever* holds is given up on, since
+  waiting cannot help it. Where Jobber names no ceiling, one wait is tried rather than the
+  worst assumed
+- [New] `GraphQL::Throttled`, a `GraphQL::Error` for a query refused over what it costs rather
+  than over anything about the query. It never leaves the gem — a caller still sees
+  `Jbr::Error` — but it is what tells the two refusals apart inside it
+- [Change] What credentials do when they ask Jobber something is `Jbr::Asking`, mixed into
+  `Jbr::OAuth`, which was over a hundred lines with the retry in it
+
+## [3.5.1] - 2026-08-17
+
+- [Change] A line item is how many of what, and nothing else. `description` was answered and
+  read out in `to_s` alongside the quantity and the name, and no caller ever wanted it — so it
+  is not asked of Jobber any more, which is a smaller query as well as a smaller class.
+  `quantified` goes with it: it existed only to be the half of `to_s` without a description,
+  and `to_s` is that on its own now. A job's summary is `line_items.to_sentence`, since
+  `to_sentence` reads each line's own string form
+
 ## [3.5.0] - 2026-08-17
 
 - [Fix] A walk of jobs carrying their line items was refused outright: `Throttled`. Jobber

data/README.md

@@ -119,11 +119,9 @@ job.line_items # => an Array of the lines the job is made of
 line = job.line_items.first
 line.quantity # => 3, whole where Jobber's own Float has nothing after the point, and 3.5
               #    where it has: `3 Faucets`, or `3.5 Hours` for what was really billed
-line.quantified # => '3 Bathroom Faucet Installation', how many of what
 line.name # => 'Bathroom Faucet Installation'
-line.description # => 'Professional installation of a new bathroom faucet'
-line.to_s # => '3 Bathroom Faucet Installation (Professional installation of a new bathroom
-          #     faucet)', and without the parenthesis where nobody described it
+line.to_s # => '3 Bathroom Faucet Installation', how many of what, and the name alone where
+          #    Jobber holds no quantity for the line
 ```
 
 Every line Jobber holds is in the list, up to twenty of them, in the order it holds them and
@@ -206,11 +204,19 @@ done about either — every request waits for itself:
 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.
 
-Where Jobber refuses for cost anyway, the `Jbr::Error` raised says what the query would have
-cost against what was available — `Throttled (cost 12400, 9500 of 10000 available, restoring
-500/s)` — so a query too big to ever run reads apart from a bucket that needed a moment. Every
-connection this gem asks for is bounded, because Jobber prices an unbounded one at its own
-maximum: twenty lines to a job, and twenty jobs or visits to a page.
+Where Jobber refuses anyway, the refusal says what the query would have cost against what was
+available, and what happens next follows from those two numbers:
+
+```
+Throttled (cost 1885, 1254 of 10000 available, restoring 500/s)
+```
+
+631 points short of a query the bucket holds five times over, so the shortfall is waited out —
+1.26 seconds at 500 a second — and the same question asked again, up to four times. Only a
+query costing more than the bucket *ever* holds is given up on, since no wait would help it;
+that one arrives as a `Jbr::Error` carrying the line above. Every connection this 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.
 
 ### Events
 

data/lib/graphql/client.rb

@@ -26,12 +26,24 @@ module GraphQL
       # Before the refusal, not after it: an endpoint that reports what it will still answer
       # reports it when it says no, which is when a caller most needs to know.
       yield body['extensions'] if block_given?
-      raise Error, refusal(body) if body['errors'].present?
+      raise refusal_for(body), refusal(body) if body['errors'].present?
       body.fetch('data')
     end
 
   private
 
+    # Refused for cost, or refused for the query. An endpoint that priced the query above what
+    # was left says so by naming the code, and says it again in the two numbers it reports —
+    # either is enough, since only one of them is documented and only one has been seen.
+    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 : Error
+    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 only needed a moment.

data/lib/graphql/throttled.rb

@@ -0,0 +1,6 @@
+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 may be answered a moment later.
+  class Throttled < Error
+  end
+end

data/lib/jbr/asking.rb

@@ -0,0 +1,40 @@
+module Jbr
+  # What credentials do when they ask Jobber something: pace the request against both limits
+  # Jobber holds an app to, wait out a refusal it can recover from, and refresh a token that
+  # went stale on the way.
+  module Asking
+    # How many times a query refused for cost is asked again. Once is the answer where the
+    # bucket only had to refill, since the wait is worked out to cover exactly the shortfall.
+    # The rest are for a bucket the whole app shares: another process may drain it again while
+    # this one waits, and each attempt costs only the seconds Jobber says it needs.
+    ATTEMPTS = 4
+
+    # 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: {})
+      attempts = 0
+      begin
+        throttle.wait
+        client.query(statement, variables: variables) { |extensions| throttle.read extensions }
+      rescue GraphQL::Unauthorized
+        refresh ? retry : {}
+      rescue GraphQL::Throttled => error
+        # The refusal priced the query, so the throttle now knows the shortfall and `wait` at
+        # the top of the retry sits out exactly that. Only a query costing more than the bucket
+        # ever holds is hopeless; the rest is a walk that asked a moment too early.
+        raise Error, error.message unless throttle.affordable? && (attempts += 1) < ATTEMPTS
+
+        retry
+      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
+        # up instead of hearing that Jobber would not answer.
+        raise Error, error.message
+      end
+    end
+
+  private
+
+    def throttle = @throttle ||= Throttle.new
+  end
+end

data/lib/jbr/job.rb

@@ -10,11 +10,11 @@ module Jbr
     def instructions = @node['instructions']
 
     # What the job's lines add up to, each as how many of what: `3 Faucet install and 2 Valve
-    # change`. The lines say what the work was where a title only says what it was called, so
-    # this reads better than one — and falls back to {#name} where the job has no lines, or
-    # where the query never asked for them. Never nil and never empty.
-    # @return [String] the lines as a sentence, or the title, or the ID.
-    def summary = line_items.map(&:quantified).to_sentence.presence || name
+    # change` — `to_sentence` reading each line's own string form. The lines say what the work
+    # was where a title only says what it was called, so this reads better than one, and falls
+    # back to {#name} where the job has no lines or the query never asked for them.
+    # @return [String] the lines as a sentence, or the title, or the ID. Never nil, never empty.
+    def summary = line_items.to_sentence.presence || name
 
     # @return [String, nil] where Jobber files the job in its own workflow.
     def status = @node['jobStatus']

data/lib/jbr/line_item.rb

@@ -1,9 +1,8 @@
 module Jbr
-  # One line of the work a job is made of: how many of a thing, what it is called, and what
-  # doing it involves.
+  # One line of the work a job is made of: how many of a thing, and what it is called.
   class LineItem < Resource
     # What Jobber calls each field of a line.
-    FIELDS = %w[quantity name description]
+    FIELDS = %w[quantity name]
 
     # The most lines to read off one record. Bounded because Jobber prices a connection by the
     # page it is asked for and prices an unbounded one at its own maximum, so the lines of a
@@ -23,16 +22,9 @@ module Jbr
     # @return [String, nil] what the line is called.
     def name = @node['name']
 
-    # @return [String, nil] what doing it involves, in whoever wrote the line's own words.
-    def description = @node['description']
-
     # @return [String] how many of what: `3 Bathroom Faucet Installation`, and the name alone
     #   where Jobber holds no quantity for the line.
-    def quantified = [ quantity, name ].compact.join ' '
-
-    # @return [String] how a line reads: `3 Faucet install (Fits a new faucet)`, and without
-    #   the parenthesis where nobody described it.
-    def to_s = [ quantified, described ].compact.join ' '
+    def to_s = [ quantity, name ].compact.join ' '
 
   private
 
@@ -40,7 +32,5 @@ module Jbr
     # `3 Faucets` rather than `3.0 Faucets`. A fraction keeps its point — `3.5 Faucets` —
     # since rounding it would lie about what was billed.
     def whole(number) = number && ((number % 1).zero? ? number.to_i : number)
-
-    def described = ("(#{description})" if description.present?)
   end
 end

data/lib/jbr/mock/line_item.rb

@@ -6,7 +6,5 @@ module Jbr
     def quantity = whole @node[:quantity]
 
     def name = @node[:name]
-
-    def description = @node[:description]
   end
 end

data/lib/jbr/oauth.rb

@@ -1,6 +1,8 @@
 module Jbr
   # Credentials for one Jobber account, and the gateway to all they read or write.
   class OAuth
+    include Asking
+
     # The mutation that revokes the app on the account.
     DISCONNECT_MUTATION = <<~GRAPHQL
       mutation Disconnect {
@@ -34,20 +36,6 @@ module Jbr
     def requests = Request.new oauth: self
     def visits = Visits.new oauth: self
 
-    # 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: {})
-      throttle.wait
-      client.query(statement, variables: variables) { |extensions| throttle.read extensions }
-    rescue GraphQL::Unauthorized
-      refresh ? retry : {}
-    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
-      # up instead of hearing that Jobber would not answer.
-      raise Error, error.message
-    end
-
     # Delete a token. If the token is invalid, do nothing.
     def delete
       client.query DISCONNECT_MUTATION
@@ -76,8 +64,6 @@ 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

@@ -25,9 +25,17 @@ module Jbr
       # and only an answered one reports an actual.
       @cost = (cost['actualQueryCost'] || cost['requestedQueryCost']).to_f
       @available = status['currentlyAvailable'].to_f
+      @maximum = status['maximumAvailable'].to_f
       @restore_rate = status['restoreRate'].to_f
     end
 
+    # Whether the bucket could ever pay for the query it last priced. A refusal is worth
+    # waiting out where it could: the shortfall refills and the same query goes through. Where
+    # the query costs more than the bucket ever holds, no wait will do — and where Jobber said
+    # nothing about the ceiling, one attempt at waiting is cheaper than assuming the worst.
+    # @return [Boolean] false only where the ceiling is known and the query is over it.
+    def affordable? = !@maximum.to_f.positive? || @cost.to_f <= @maximum
+
   private
 
     # Nothing is owed to the first caller: a request that follows no other is not too soon.

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.5.0'
+  VERSION = '3.6.1'
 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'
@@ -26,6 +27,7 @@ require 'jbr/cliental'
 require 'jbr/named'
 require 'jbr/resource'
 require 'jbr/throttle'
+require 'jbr/asking'
 require 'jbr/request'
 require 'jbr/oauth'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 3.5.0
+  version: 3.6.1
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -106,9 +106,11 @@ 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
+- lib/jbr/asking.rb
 - lib/jbr/client.rb
 - lib/jbr/cliental.rb
 - lib/jbr/error.rb