jbr 3.4.0 → 3.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc29abcfab78a836ad4c098926a10986bf90ec1d53a62ddcce2c6e1da47e9772
-  data.tar.gz: 4a807c61b3173205f6e53c47f71bbee28fceaa21930c7f2cb0797663c1e53920
+  metadata.gz: f5c1536ff754171e5bafc8e5501088b0372c673c98e3891786b43da0a69f5c75
+  data.tar.gz: 61bf56b9de47ec4ada6e406967c36240a95351d50a007730ce2506c0d7244864
 SHA512:
-  metadata.gz: 5cabf6ed4fe94c9d71205788acf0fc0464d87fcea88e316c02acf99d509b891df9e24b912ce525053741388591e704106911ec19c3504d30121b01b22a9bcc5e
-  data.tar.gz: 23b0588c84c8042d2b40d396ca34a7c1c34f77d20b566685cdc4ca5f1333d9482ae6779eb310de25f370449b6826b6e1331bc458e58e57e5d4a652dc03442696
+  metadata.gz: 52d0070f75aa56d58874e301c0bb11b8b78fb108ac2327617094f9ee3676302fb8b59dee89942203dc993305356a43165b0fb053ac0257f1cb0f1299949ad5b3
+  data.tar.gz: 73c45d7ed55f796c7e0068eb19c33bc07e0a1ac2359a594b12eca096b43e8bf86058e4f67b3f03877d02e337a87ee81be3efca500df6deb6b9470a175065bdbc

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+## [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
+  prices a query by the page it asks for and prices an *unbounded* connection at its own
+  maximum, so `lineItems` on a page of 40 jobs was charged as though every job carried the
+  largest job's worth of lines. The connection is bounded at 20 now, and a page of jobs is 20
+  rather than 40 — half the page is half the query, and a walk loses nothing by reading twice
+  as many. A job with more than 20 lines is summarized by its first 20
+- [Fix] Jobber's own failures reach a caller as `Jbr::Error`, which is what this gem has
+  always said they would. `GraphQL::Error` was escaping instead, so an app that rescued
+  `Jbr::Error` — as the README tells it to — was not catching a throttle, a 500 or an
+  unreadable answer, and had its own job blow up rather than hearing that Jobber said no
+- [Fix] A refusal for cost says what the cost was: `Throttled (cost 12400, 9500 of 10000
+  available, restoring 500/s)` rather than `Throttled`. Without the numbers there is no
+  telling a query too big to ever run from a bucket that needed another second
+- [Change] A refused query prices the next one. Jobber reports the bucket when it says no as
+  readily as when it answers, and the throttle was only reading it on the way through — so a
+  walk that hit the ceiling then asked again immediately, at the same size, and was refused
+  again
+
 ## [3.4.0] - 2026-08-17
 
 - [New] `line_items` on a job: what the work actually was, where the title is only what

data/README.md

@@ -119,16 +119,15 @@ 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, in the order it holds them and whatever each is
-quantified at. One it holds no quantity for reads as its name alone. Ask for nothing and
-nothing arrives, so `oauth.jobs.first.line_items` is empty where the query never named them.
+Every line Jobber holds is in the list, up to twenty of them, in the order it holds them and
+whatever each is quantified at. One it holds no quantity for reads as its name alone. Ask for
+nothing and nothing arrives, so `oauth.jobs.first.line_items` is empty where the query never
+named them.
 
 ### Invoices
 
@@ -205,6 +204,12 @@ 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.
+
 ### Events
 
 Parse the payload of a Jobber event webhook:

data/lib/graphql/client.rb

@@ -23,13 +23,27 @@ 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)
-      errors = body['errors']
-      raise Error, errors.map { |error| error['message'] }.join('; ') if errors.present?
+      # 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?
       body.fetch('data')
     end
 
   private
+
+    # 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.
+    def refusal(body)
+      message = body['errors'].map { |error| error['message'] }.join '; '
+      cost = body['extensions'].to_h['cost'].to_h
+      status = cost['throttleStatus'].to_h
+      return message if status.empty?
+
+      "#{message} (cost #{cost['requestedQueryCost']}, #{status['currentlyAvailable']} of " \
+        "#{status['maximumAvailable']} available, restoring #{status['restoreRate']}/s)"
+    end
     def request_headers
       { 'Authorization' => "Bearer #{@token}", 'Content-Type' => 'application/json' }.merge @headers
     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/jobs.rb

@@ -29,12 +29,14 @@ module Jbr
 
   private
 
-    # Forty a page, not a hundred: Jobber prices a query by its page size and refuses the
-    # wider one, and what an includes brings back is charged for on top.
+    # 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: 40, after: $after, filter: $filter) {
+          jobs(first: 20, after: $after, filter: $filter) {
             nodes { #{FIELDS} #{selections} }
             pageInfo { hasNextPage endCursor }
           }

data/lib/jbr/line_item.rb

@@ -1,12 +1,16 @@
 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
+    # page of jobs were charged for as though every job had the largest job's worth of them.
+    PAGE = 20
 
     # What to ask for wherever a record lists the lines it is made of.
-    SELECTION = "lineItems { nodes { #{FIELDS.join ' '} } }"
+    SELECTION = "lineItems(first: #{PAGE}) { nodes { #{FIELDS.join ' '} } }"
 
     # @param nodes [Array<Hash>, nil] the lines as Jobber answered them, if it answered any.
     # @return [Array<LineItem>] one per line, in the order Jobber holds them.
@@ -18,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
 
@@ -35,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

@@ -41,6 +41,11 @@ module Jbr
       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.

data/lib/jbr/throttle.rb

@@ -21,7 +21,9 @@ module Jbr
     def read(extensions)
       cost = extensions.to_h['cost'].to_h
       status = cost['throttleStatus'].to_h
-      @cost = cost['actualQueryCost'].to_f
+      # What a refused query would have cost is what it costs: Jobber prices it either way,
+      # and only an answered one reports an actual.
+      @cost = (cost['actualQueryCost'] || cost['requestedQueryCost']).to_f
       @available = status['currentlyAvailable'].to_f
       @restore_rate = status['restoreRate'].to_f
     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.4.0'
+  VERSION = '3.5.1'
 end

data/lib/jbr/visits.rb

@@ -18,12 +18,12 @@ module Jbr
 
   private
 
-    # Forty a page, not a hundred: Jobber prices a query by its page size and refuses the
-    # wider one, and what an includes brings back is charged for on top.
+    # 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: 40, after: $after, filter: $filter) {
+          visits(first: 20, after: $after, filter: $filter) {
             nodes { #{FIELDS} #{selections} }
             pageInfo { hasNextPage endCursor }
           }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.1
 platform: ruby
 authors:
 - Claudio Baccigalupo