jbr 3.2.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1028c7784920b94426d3c9d52a29232cdb4b8426baf5abe11cbcfe64d9f854f
-  data.tar.gz: d27d31e838ea1fd1c2c3035abf3e21635955039febc8a481bb514a8bd8e9fb9d
+  metadata.gz: dc29abcfab78a836ad4c098926a10986bf90ec1d53a62ddcce2c6e1da47e9772
+  data.tar.gz: 4a807c61b3173205f6e53c47f71bbee28fceaa21930c7f2cb0797663c1e53920
 SHA512:
-  metadata.gz: 74d582435245e0aebf5975748e2ba86e5e53f1190a4f4007d1b50e514df47816082f82a8cdf41b8bd9529e63fe25219035005335ed56708b857ba6aabfdbcb4e
-  data.tar.gz: 6977198a4d12a410b0c2b8ef2aa0cda829a43ec5fda670ce7d9dbcd13301ac2ef3da55b605d4a6ab7e3017839a115c9f757a6a4ae6d86522f4fa584151cb4f12
+  metadata.gz: 5cabf6ed4fe94c9d71205788acf0fc0464d87fcea88e316c02acf99d509b891df9e24b912ce525053741388591e704106911ec19c3504d30121b01b22a9bcc5e
+  data.tar.gz: 23b0588c84c8042d2b40d396ca34a7c1c34f77d20b566685cdc4ca5f1333d9482ae6779eb310de25f370449b6826b6e1331bc458e58e57e5d4a652dc03442696

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+## [3.4.0] - 2026-08-17
+
+- [New] `line_items` on a job: what the work actually was, where the title is only what
+  somebody called it. Each is a `Jbr::LineItem` answering `quantity`, `name` and
+  `description`, and reading as `3 Bathroom Faucet Installation (Professional installation
+  of a new bathroom faucet)` — without the parenthesis where nobody described it, and as the
+  name alone where Jobber holds no quantity either. `quantified` is the first half of that on
+  its own, how many of what. A quantity reads whole where Jobber's own Float has nothing
+  after the point and keeps its fraction where it has, so a line is `3 Faucets` or `3.5
+  Hours` as billed. Every line Jobber holds is answered, in the order it holds them
+- [New] `includes(:line_items)`, which is how they are asked for. Nothing nested arrives
+  unasked, so the import walks that never read a line item pay nothing for them
+- [New] `summary` on a job: its lines as a sentence of how many of what, `3 Bathroom Faucet
+  Installation and 2 Change Toilet Valve`. What the work was, where `title` is only what
+  somebody called it — and `name` again where the job has no lines, or where the query never
+  asked for them, so it is never nil and never empty
+
+## [3.3.0] - 2026-08-13
+
+- [Fix] Credentials are given up only when Jobber says the grant itself is no good. Any
+  refusal at all used to set `invalid_at` -- a 500, a rate limit, an unreadable body -- so
+  a moment of trouble at Jobber's end read as a dead token, and an app acting on that could
+  revoke one that still worked. Only an `invalid_grant` Jobber names counts now; everything
+  else raises `Jbr::Error` for the caller to retry, which is what trouble deserves
+- [New] `Jbr::Refused`, a `Jbr::Error` for the grant being no good rather than for the
+  answer failing to arrive. Rescue it to tell the two apart
+- [Change] The token endpoint moved to `Jbr::Token`. `Jbr::OAuth.post` still answers it
+  unchanged, and so do `Jbr::OAuth.client_id` and `Jbr::OAuth.client_secret`
+
 ## [3.2.0] - 2026-08-13
 
 - [New] Wait rather than be refused. Jobber holds an app to two limits at once -- 2,500

data/README.md

@@ -41,6 +41,16 @@ Revoke credentials:
 oauth.delete
 ```
 
+Credentials go bad only when Jobber says so. A refused refresh — the `invalid_grant` Jobber
+names — sets `invalid_at` and answers queries with nothing. Anything else that goes wrong,
+including a 500 or a rate limit, raises `Jbr::Error` instead, because a token that may still
+work is worth more than a tidy failure:
+
+```ruby
+oauth.invalid_at # => 2026-08-13 11:02:41, or nil while the credentials are good
+oauth.query '{ ok }' # => {} once they are refused, raises Jbr::Error where Jobber had trouble
+```
+
 ### Requests
 
 Create a Jobber request, finding or creating a Client with a matching phone number:
@@ -94,6 +104,32 @@ job.quote_total # => 240.0
 job.created_at # => 2026-05-10 09:15:00
 ```
 
+### Line items
+
+What the work actually was, where the title is only what somebody called it. Asked for the
+same way as anything nested, since a page costs what it carries:
+
+```ruby
+job = oauth.jobs.includes(:line_items).find 'Njc5MTk5'
+
+job.summary # => '3 Bathroom Faucet Installation and 2 Change Toilet Valve', the lines as a
+            #    sentence of how many of what. Falls back to #name where there are none
+
+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
+```
+
+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.
+
 ### Invoices
 
 Fetch a non-draft invoice from Jobber:
@@ -239,6 +275,18 @@ Jbr.mock.jobs = [ { id: 'job-01', title: 'Furnace tune-up', status: 'archived',
     client: { id: 'client-01', company_name: 'Acme Property Management' } } } ]
 ```
 
+Mock the lines a job is made of, under the job that is made of them:
+
+```ruby
+Jbr.mock.jobs = [ { id: 'job-01', line_items: [
+  { quantity: 3.0, name: 'Bathroom Faucet Installation',
+    description: 'Professional installation of a new bathroom faucet' },
+  { quantity: 2.0, name: 'Change Toilet Valve' } ] } ]
+
+oauth.jobs.past.first.summary
+# => '3 Bathroom Faucet Installation and 2 Change Toilet Valve'
+```
+
 ### Visits
 
 Mock the visits the account has:

data/lib/jbr/includable.rb

@@ -2,8 +2,8 @@ module Jbr
   # Extends a list of records with the chaining that says what to bring back beside them.
   # Nothing extra comes back unasked: a page costs what it carries.
   module Includable
-    # @param names [Array<Symbol, Hash>] :client, :property, or property: :client for the
-    #   client whose file the place sits on.
+    # @param names [Array<Symbol, Hash>] :client, :line_items, :property, or
+    #   property: :client for the client whose file the place sits on.
     # @return [Resource] the same list, asking Jobber for those too.
     def includes(*names)
       named = names.each_with_object({}) do |name, all|
@@ -20,6 +20,7 @@ module Jbr
     def selection_of(name, nested)
       case name
         when :client then Cliental::SELECTION
+        when :line_items then LineItem::SELECTION
         when :property then Properted.selection client: nested == :client
       end
     end

data/lib/jbr/itemized.rb

@@ -0,0 +1,9 @@
+module Jbr
+  # Extends a record Jobber itemizes: a job, whose lines say what the work actually was
+  # where the title only says what somebody called it.
+  module Itemized
+    # @return [Array<LineItem>] the lines the record is made of, empty where the query never
+    #   asked for them — a page costs what it carries, so nothing nested arrives unasked.
+    def line_items = LineItem.from @node.dig('lineItems', 'nodes')
+  end
+end

data/lib/jbr/job.rb

@@ -1,7 +1,7 @@
 module Jbr
   # Work a Jobber user accepted and scheduled.
   class Job < Resource
-    include Cliental, Named, Properted
+    include Cliental, Itemized, Named, Properted
 
     # @return [String, nil] what the job is called, where whoever opened it named it.
     def title = @node['title']
@@ -9,6 +9,13 @@ module Jbr
     # @return [String, nil] what the work is, in the words whoever opened the job wrote.
     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
+
     # @return [String, nil] where Jobber files the job in its own workflow.
     def status = @node['jobStatus']
 

data/lib/jbr/line_item.rb

@@ -0,0 +1,41 @@
+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.
+  class LineItem < Resource
+    # What Jobber calls each field of a line.
+    FIELDS = %w[quantity name description]
+
+    # What to ask for wherever a record lists the lines it is made of.
+    SELECTION = "lineItems { 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.
+    def self.from(nodes) = nodes.to_a.map { |node| new node: node }
+
+    # @return [Integer, Float, nil] how many of it the job is for.
+    def quantity = whole @node['quantity']
+
+    # @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 ' '
+
+  private
+
+    # Jobber answers every quantity as a Float, and a whole one reads as an Integer:
+    # `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/job.rb

@@ -22,6 +22,8 @@ module Jbr
 
     def property = Mock::Property.new(node: @node.fetch(:property, {}))
 
+    def line_items = Mock::LineItem.from(@node.fetch(:line_items, []))
+
     def scheduled_at = @node[:scheduled_at]
 
     def completed_at = @node[:completed_at]

data/lib/jbr/mock/line_item.rb

@@ -0,0 +1,12 @@
+module Jbr
+  # A line of a job that reads from {Jbr.mock} instead of Jobber.
+  class Mock::LineItem < LineItem
+    # @return [Object, nil] the values the app asked for. The quantity is still read whole,
+    #   so an app that mocks `3.0` of a thing sees the `3` a page would show.
+    def quantity = whole @node[:quantity]
+
+    def name = @node[:name]
+
+    def description = @node[:description]
+  end
+end

data/lib/jbr/oauth.rb

@@ -66,14 +66,7 @@ module Jbr
 
     # 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,
-        params.merge(client_id: client_id, client_secret: client_secret)
-      raise Error, response.body unless response.is_a? Net::HTTPSuccess
-      output = JSON.parse(response.body)
-      { access_token: output['access_token'], refresh_token: output['refresh_token'],
-        expires_at: (Time.now + output.fetch('expires_in', 3600).to_i),
-      }
+      Token.post params.merge(client_id: client_id, client_secret: client_secret)
     end
 
   private
@@ -85,7 +78,7 @@ module Jbr
       @access_token = output[:access_token]
       @refresh_token = output[:refresh_token]
       @expires_at = output[:expires_at]
-    rescue Error => e
+    rescue Refused
       @invalid_at = Time.now
       false
     end

data/lib/jbr/refused.rb

@@ -0,0 +1,5 @@
+module Jbr
+  # Jobber refusing the grant itself, rather than failing to answer about it. The first is a
+  # token that will never work again; the second may be a moment of trouble at their end.
+  Refused = Class.new Error
+end

data/lib/jbr/token.rb

@@ -0,0 +1,35 @@
+module Jbr
+  # The endpoint that trades an authorization code or a refresh token for credentials.
+  class Token
+    # Where a grant is exchanged.
+    URL = 'https://api.getjobber.com/api/oauth/token'
+
+    # What Jobber calls a grant that is no good, in the OAuth 2 word for it.
+    REFUSAL = 'invalid_grant'
+
+    # Trade a grant for credentials.
+    # @param params [Hash] the grant, and the app making the exchange.
+    # @raise [Refused] where Jobber says the grant itself is no good.
+    # @raise [Error] where Jobber could not answer about it.
+    # @return [Hash] the tokens, and the moment the access one expires.
+    def self.post(params = {})
+      response = Net::HTTP.post_form URI(URL), params
+      raise Refused, response.body if refused? response
+      raise Error, response.body unless response.is_a? Net::HTTPSuccess
+
+      output = JSON.parse response.body
+      { access_token: output['access_token'], refresh_token: output['refresh_token'],
+        expires_at: (Time.now + output.fetch('expires_in', 3600).to_i),
+      }
+    end
+
+    def self.refused?(response)
+      return false if response.is_a? Net::HTTPSuccess
+
+      JSON.parse(response.body)['error'] == REFUSAL
+    rescue JSON::ParserError
+      false
+    end
+    private_class_method :refused?
+  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.2.0'
+  VERSION = '3.4.0'
 end

data/lib/jbr.rb

@@ -1,11 +1,13 @@
 require 'json'
 require 'net/http'
 
-# Only the two Active Support files whose methods are used, rather than the whole of it:
+# Only the three 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.
+# and a caller who validates presence needs those to arrive as the same nothing. The third is
+# for the sentence a job's lines read as.
 require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/array/conversions'
 
 require 'graphql/error'
 require 'graphql/unauthorized'
@@ -15,6 +17,8 @@ require 'jbr/mock'
 
 require 'jbr/url'
 require 'jbr/error'
+require 'jbr/refused'
+require 'jbr/token'
 # Phone before Cliental, and Cliental before the records that include it: what each asks
 # Jobber for about a client is built as they load.
 require 'jbr/phone'
@@ -30,6 +34,10 @@ require 'jbr/account'
 require 'jbr/property'
 require 'jbr/properted'
 require 'jbr/includable'
+# 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'
+require 'jbr/itemized'
 require 'jbr/client'
 require 'jbr/invoice'
 require 'jbr/job'
@@ -42,6 +50,7 @@ require 'jbr/mock/oauth'
 require 'jbr/mock/client'
 require 'jbr/mock/property'
 require 'jbr/mock/quote'
+require 'jbr/mock/line_item'
 require 'jbr/mock/job'
 require 'jbr/mock/jobs'
 require 'jbr/mock/invoice'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -115,14 +115,17 @@ files:
 - lib/jbr/event.rb
 - lib/jbr/includable.rb
 - lib/jbr/invoice.rb
+- lib/jbr/itemized.rb
 - lib/jbr/job.rb
 - lib/jbr/jobs.rb
+- lib/jbr/line_item.rb
 - lib/jbr/mock.rb
 - lib/jbr/mock/account.rb
 - lib/jbr/mock/client.rb
 - lib/jbr/mock/invoice.rb
 - lib/jbr/mock/job.rb
 - lib/jbr/mock/jobs.rb
+- lib/jbr/mock/line_item.rb
 - lib/jbr/mock/oauth.rb
 - lib/jbr/mock/property.rb
 - lib/jbr/mock/quote.rb
@@ -137,9 +140,11 @@ files:
 - lib/jbr/properted.rb
 - lib/jbr/property.rb
 - lib/jbr/quote.rb
+- lib/jbr/refused.rb
 - lib/jbr/request.rb
 - lib/jbr/resource.rb
 - lib/jbr/throttle.rb
+- lib/jbr/token.rb
 - lib/jbr/url.rb
 - lib/jbr/version.rb
 - lib/jbr/visit.rb