jbr 2.4.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 131ece92fb051e64674afcd8e0066a126c83cd4502b7ea570795e2f6a456aaf6
-  data.tar.gz: d56615c6a47fab3de06ecebf672ade7f355e2338e263ff23577faea1b3dd744d
+  metadata.gz: 97dff097405bb45eb1ac6048e9ce131d6905f19221e1e910ccff1f533ede76ed
+  data.tar.gz: 2cf46317599aa7146b73fa734441a0c995749692cea4565bcc6646b80fff478c
 SHA512:
-  metadata.gz: 12e0d034ad5a76d89bf9d8ded9b84bd5790197e34a709404c551f9b75d9d697dcaec066db7f9bd05283bb17fabbee9a5b1239f29b5ed90bb025141f47b9db88a
-  data.tar.gz: 1c3b8eff188c1a4ade48f273c6ec575bfe57a9906da717b8fba10237e3722317f04fc1bacbb333b06b2df4753e3dcf3c5e5d203a2d970908136d55098f3009d9
+  metadata.gz: 6fc99f2dbaa979073811af9382023b10acde8182e89ded303876876f92e54bcbce9f2ee732917003571823aa2b3127b8f960ad912f88ab53935e8041022b3f4a
+  data.tar.gz: 656ca93656a1702f226d9f8aa4ed12e7e0d31f01a1ac4cda426096ec7eea48e30e5b2977ccbc113a5dfa21fdb6084009b400caae836f23335a4bd28a4626511d

data/CHANGELOG.md

@@ -1,3 +1,46 @@
+## [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
+  one record: each is an Enumerable of every visit or job on the account, oldest first, read
+  a page at a time only as far as it is walked. `oauth.visits.upcoming` still answers the
+  ones dated from now on, `.past` answers the ones dated before now, and both split the
+  schedule at the moment they are asked rather than per page, so nothing crosses the
+  boundary unseen. `oauth.jobs.find(id)` is unchanged
+- [Breaking change] A visit or a job answers `client` and `property` as objects rather than
+  hashes: `visit.client.phone` and `visit.property.street` where `visit.client[:phone]` and
+  `visit.property[:street]` used to read. A property answers `client` too, so the person a
+  place sits on the file of comes back with the place
+- [Breaking change] Nothing nested is fetched unless it is asked for. Chain `includes` the
+  way Active Record does -- `oauth.visits.includes(:client, property: :client)` -- and only
+  what it names is added to the query. Jobber prices a query by what it brings back, so a
+  caller who wants the visit alone is no longer charged for the client and the place
+- [New] Fetch jobs the way visits are fetched. A job carries `name`, `title`,
+  `instructions`, `status`, `total`, `quote_id`, `quote_total`, `created_at`, `scheduled_at`
+  and `completed_at`, and its client and property come back with `includes`. `name` is the
+  title, or the ID Jobber files the job under where nobody titled it, so it is never nil
+- [New] A client answers `name`: their first name, or the name of the business where the
+  client is a business. Jobber files nobody without one or the other, so it is never nil.
+  `first_name`, `last_name`, `company_name`, `email` and `phone` read individually
+- [New] Mock the jobs an account has with `Jbr.mock.jobs`, beside `Jbr.mock.visits`
+
 ## [2.4.0] - 2026-08-08
 
 - [Breaking change] A visit answers `property` -- the ID Jobber files the place under, beside

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
 
@@ -63,7 +64,7 @@ quote.request_id # => 'Z2lkOi8vSm9iYmVyL'
 
 ### Jobs
 
-Fetch a job from Jobber:
+Fetch a job from Jobber by the ID it is filed under:
 
 ```ruby
 job = oauth.jobs.find 'Njc5MTk5'
@@ -73,6 +74,25 @@ job.scheduled_at # => 2026-05-14 23:02:52
 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:
+
+```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
+
+job = jobs.first
+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'
+job.total # => 260.0
+job.quote_total # => 240.0
+job.created_at # => 2026-05-10 09:15:00
+```
+
 ### Invoices
 
 Fetch a non-draft invoice from Jobber:
@@ -88,27 +108,52 @@ invoice.completed_at # => 2026-05-22 14:32:53
 
 ### Visits
 
-Fetch the visits scheduled from now on, 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:
+Walk the account's visits, oldest first, the same way as its jobs:
 
 ```ruby
-visits = oauth.visits.upcoming # => an Enumerator, nothing fetched yet
+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
+
 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.property # => { id: 'Z2lkOi8vS', street: '1 Main St', city: 'Raleigh',
-               #      state: 'NC', zip: '27601', latitude: 35.77, longitude: -78.63 }
-visit.client # => { id: 'Z2lkOi8vS', first_name: 'Jane', last_name: 'Doe',
-             #      phone: '5553335555', email: 'jane@example.com' }
-             # phone is the reachable North American number, ten digits, or nil
 visit.starts_at # => 2026-08-09 14:00:00
 visit.ends_at # => 2026-08-09 16:00:00
 visit.all_day? # => false
 visit.client_confirmed? # => true
 ```
 
+### Clients and properties
+
+Jobber prices a query by what it brings back, so nothing nested comes back unless it is
+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.
+                  # 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
+visit.client.email # => 'jane@example.com'
+visit.client.phone # => '5553335555', the reachable North American number, or nil
+
+visit.property.id # => 'Z2lkOi8vS'
+visit.property.street # => '1 Main St'
+visit.property.city # => 'Raleigh'
+visit.property.zip # => '27601'
+visit.property.address # => { street: '1 Main St', city: 'Raleigh', state: 'NC',
+                       #      zip: '27601', latitude: 35.77, longitude: -78.63 }
+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.
+
 ### Events
 
 Parse the payload of a Jobber event webhook:
@@ -162,21 +207,32 @@ Jbr.mock.quote = { id: 'quote-01', request_id: 'request-01' }
 
 ### Jobs
 
-Mock successfully fetching a job:
+Mock successfully fetching a job by ID:
 
 ```ruby
 Jbr.mock.job = { id: 'job-01', quote_id: 'quote-01', scheduled_at: Date.tomorrow.noon }
 ```
 
+Mock the jobs the account has. The mock dates nothing it was handed: what answers to
+`past` and to `upcoming` is whatever `scheduled_at` the app gave each one:
+
+```ruby
+Jbr.mock.jobs = [ { id: 'job-01', title: 'Furnace tune-up', status: 'archived',
+  total: 260.0, quote_total: 240.0, created_at: Date.yesterday.noon,
+  scheduled_at: Date.yesterday.noon, completed_at: Date.today.noon,
+  property: { id: 'property-01', street: '1 Main St',
+    client: { id: 'client-01', company_name: 'Acme Property Management' } } } ]
+```
+
 ### Visits
 
-Mock successfully fetching upcoming visits:
+Mock the visits the account has:
 
 ```ruby
 Jbr.mock.visits = [ { id: 'visit-01', title: 'Furnace tune-up', job_id: 'job-01',
-  property: { id: 'property-01', street: '1 Main St' },
+  property: { id: 'property-01', street: '1 Main St',
+    client: { id: 'client-01', first_name: 'Jane' } },
   client: { id: 'client-01', first_name: 'Jane' },
-  address: { street: '1 Main St', city: 'Raleigh', state: 'NC', zip: '27601' },
   starts_at: Date.tomorrow.noon, ends_at: Date.tomorrow.end_of_day,
   all_day: false, client_confirmed: true } ]
 ```

data/lib/graphql/client.rb

@@ -22,8 +22,8 @@ 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('; ') unless errors.empty?
+      errors = body['errors']
+      raise Error, errors.map { |error| error['message'] }.join('; ') if errors.present?
       body.fetch('data')
     end
 

data/lib/jbr/client.rb

@@ -23,6 +23,25 @@ module Jbr
     # @return [String, nil] the property the work happens at.
     attr_reader :property_id
 
+    # @return [String, nil] what the client is called.
+    def first_name = @node['firstName']
+
+    def last_name = @node['lastName']
+
+    # @return [String, nil] the business the client is, where the client is a business.
+    def company_name = @node['companyName']
+
+    # Jobber files nobody without one name or the other, so there is always one to call them.
+    # @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']
+
+    # The number to reach them on, without its country code.
+    # @return [String, nil] ten digits, or nil where Jobber holds none we can dial.
+    def phone = Phone.from(@node['phones'])
+
     # Create a client instance with the provided attributes.
     # @return [Client] itself
     # @param params [Hash] the attributes of the client
@@ -70,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/cliental.rb

@@ -0,0 +1,14 @@
+module Jbr
+  # Extends a record that names the client the work is for: a visit, a job, a property,
+  # anything Jobber files under somebody.
+  module Cliental
+    # What Jobber calls each field of that client.
+    FIELDS = %w[id firstName lastName companyName email]
+
+    # What to ask for wherever a record names its client.
+    SELECTION = "client { #{FIELDS.join ' '} #{Phone::SELECTION} }"
+
+    # @return [Client] who the work is for.
+    def client = Client.new node: @node.fetch('client', {})
+  end
+end

data/lib/jbr/includable.rb

@@ -0,0 +1,27 @@
+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.
+    # @return [Resource] the same list, asking Jobber for those too.
+    def includes(*names)
+      named = names.each_with_object({}) do |name, all|
+        name.is_a?(Hash) ? all.merge!(name) : all[name] = nil
+      end
+      self.class.new oauth: @oauth, includes: @includes.merge(named)
+    end
+
+  private
+
+    # What the includes ask Jobber for, in its own words.
+    def selections = @includes.map { |name, nested| selection_of name, nested }.join ' '
+
+    def selection_of(name, nested)
+      case name
+        when :client then Cliental::SELECTION
+        when :property then Properted.selection client: nested == :client
+      end
+    end
+  end
+end

data/lib/jbr/job.rb

@@ -1,37 +1,33 @@
 module Jbr
   # Work a Jobber user accepted and scheduled.
   class Job < Resource
-    # The query that reads one job, its quote and its two timestamps.
-    FIND = <<~GRAPHQL
-      query($id: EncodedId!) {
-        job(id: $id) { id quote { id } startAt completedAt }
-      }
-    GRAPHQL
+    include Cliental, Named, Properted
+
+    # @return [String, nil] what the job is called, where whoever opened it named it.
+    def title = @node['title']
+
+    # @return [String, nil] what the work is, in the words whoever opened the job wrote.
+    def instructions = @node['instructions']
+
+    # @return [String, nil] where Jobber files the job in its own workflow.
+    def status = @node['jobStatus']
 
     # @return [String, nil] the ID of the quote the job was won with.
-    attr_reader :quote_id
-
-    # @param id [String] the Jobber ID of the job.
-    # @return [Job, nil] itself, or nil when Jobber has no such job.
-    def find(id)
-      output = @oauth.query FIND, variables: { id: id  }
-      return unless job = output['job']
-
-      @id = job['id']
-      @quote_id = job.dig 'quote', 'id'
-      @scheduled_at = job['startAt']
-      @completed_at = job['completedAt']
-      self
-    end
-
-    # @return [Time] the job scheduled time
-    def scheduled_at
-      Time.iso8601(@scheduled_at) if @scheduled_at
-    end
-
-    # @return [Time] the job completed time
-    def completed_at
-      Time.iso8601(@completed_at) if @completed_at
-    end
+    def quote_id = @node.dig 'quote', 'id'
+
+    # @return [Float, nil] what the job comes to.
+    def total = @node['total']
+
+    # @return [Float, nil] what the quote the job was won with came to.
+    def quote_total = @node.dig 'quote', 'amounts', 'total'
+
+    # @return [Time, nil] the job opening time
+    def created_at = time 'createdAt'
+
+    # @return [Time, nil] the job scheduled time
+    def scheduled_at = time 'startAt'
+
+    # @return [Time, nil] the job completed time
+    def completed_at = time 'completedAt'
   end
 end

data/lib/jbr/jobs.rb

@@ -0,0 +1,57 @@
+module Jbr
+  # The jobs on a Jobber account, oldest first, walked a page at a time.
+  class Jobs < Resource
+    include Enumerable, Includable
+
+    # 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.
+    # @return [Job, nil] nil when Jobber has no job under that ID.
+    def find(id)
+      node = @oauth.query(one, variables: { id: id })['job']
+      Job.new node: node if node
+    end
+
+  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.
+    def page
+      <<~GRAPHQL
+        query($after: String, $filter: JobFilterAttributes) {
+          jobs(first: 40, after: $after, filter: $filter) {
+            nodes { #{FIELDS} #{selections} }
+            pageInfo { hasNextPage endCursor }
+          }
+        }
+      GRAPHQL
+    end
+
+    def one
+      <<~GRAPHQL
+        query($id: EncodedId!) {
+          job(id: $id) { #{FIELDS} #{selections} }
+        }
+      GRAPHQL
+    end
+
+    def field = 'jobs'
+
+    def item(node) = Job.new node: node
+  end
+end

data/lib/jbr/mock/client.rb

@@ -0,0 +1,17 @@
+module Jbr
+  # A client that reads from {Jbr.mock} instead of Jobber.
+  class Mock::Client < Client
+    # @return [Object, nil] the values the app asked for.
+    def id = @node[:id]
+
+    def first_name = @node[:first_name]
+
+    def last_name = @node[:last_name]
+
+    def company_name = @node[:company_name]
+
+    def email = @node[:email]
+
+    def phone = @node[:phone]
+  end
+end

data/lib/jbr/mock/job.rb

@@ -1,17 +1,29 @@
 module Jbr
   # A job that reads from {Jbr.mock} instead of Jobber.
   class Mock::Job < Job
-    # @return [Mock::Job] itself, carrying the mocked IDs.
-    def find(_)
-      @id = Jbr.mock.job[:id]
-      @quote_id = Jbr.mock.job[:quote_id]
+    # @return [Object, nil] the values the app asked for.
+    def id = @node[:id]
 
-      self
-    end
+    def title = @node[:title]
 
-    # @return [Time, nil] the times the app asked for.
-    def scheduled_at = Jbr.mock.job[:scheduled_at]
+    def instructions = @node[:instructions]
 
-    def completed_at = Jbr.mock.job[:completed_at]
+    def status = @node[:status]
+
+    def quote_id = @node[:quote_id]
+
+    def total = @node[:total]
+
+    def quote_total = @node[:quote_total]
+
+    def created_at = @node[:created_at]
+
+    def client = Mock::Client.new(node: @node.fetch(:client, {}))
+
+    def property = Mock::Property.new(node: @node.fetch(:property, {}))
+
+    def scheduled_at = @node[:scheduled_at]
+
+    def completed_at = @node[:completed_at]
   end
 end

data/lib/jbr/mock/jobs.rb

@@ -0,0 +1,24 @@
+module Jbr
+  # The jobs an app under test asked {Jbr.mock} to answer with.
+  class Mock::Jobs < Jobs
+    # @return [Mock::Job] the one job the app named, whatever ID is asked for.
+    def find(_) = Mock::Job.new node: 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 }
+
+    # @return [Enumerator<Mock::Job>] those it dated before now.
+    def past = mocked Jbr.mock.jobs.select { |job| started? job }
+
+  private
+
+    def mocked(jobs)
+      Enumerator.new { |yielder| jobs.each { |job| yielder << Mock::Job.new(node: job) } }
+    end
+
+    def started?(job) = job[:scheduled_at] ? job[:scheduled_at] <= Time.now : false
+  end
+end

data/lib/jbr/mock/oauth.rb

@@ -3,11 +3,11 @@ module Jbr
   class Mock::OAuth < OAuth
     # The mocked resources these credentials read and write.
     def invoices = Mock::Invoice.new(oauth: self)
-    def jobs = Mock::Job.new(oauth: self)
+    def jobs = Mock::Jobs.new(oauth: self)
     def quotes = Mock::Quote.new(oauth: self)
     def requests = Mock::Request.new(oauth: self)
     def account = Mock::Account.new oauth: self
-    def visits = Mock::Visit.new(oauth: self)
+    def visits = Mock::Visits.new(oauth: self)
 
     # Revoking a mocked token asks nobody.
     def delete; end

data/lib/jbr/mock/property.rb

@@ -0,0 +1,15 @@
+module Jbr
+  # A property that reads from {Jbr.mock} instead of Jobber.
+  class Mock::Property < Property
+    # @return [Object, nil] the values the app asked for.
+    def id = @node[:id]
+
+    def street = @node[:street]
+
+    def city = @node[:city]
+
+    def zip = @node[:zip]
+
+    def client = Mock::Client.new(node: @node.fetch(:client, {}))
+  end
+end

data/lib/jbr/mock/visit.rb

@@ -1,13 +1,6 @@
 module Jbr
   # A visit that reads from {Jbr.mock} instead of Jobber.
   class Mock::Visit < Visit
-    # @return [Enumerator<Mock::Visit>] the visits the app asked for.
-    def upcoming
-      Enumerator.new do |yielder|
-        Jbr.mock.visits.each { |visit| yielder << self.class.new(oauth: @oauth, node: visit) }
-      end
-    end
-
     # @return [Object, nil] the values the app asked for.
     def id = @node[:id]
 
@@ -15,9 +8,9 @@ module Jbr
 
     def job_id = @node[:job_id]
 
-    def client = @node.fetch :client, {}
+    def client = Mock::Client.new(node: @node.fetch(:client, {}))
 
-    def property = @node.fetch :property, {}
+    def property = Mock::Property.new(node: @node.fetch(:property, {}))
 
     def all_day? = @node[:all_day]
 

data/lib/jbr/mock/visits.rb

@@ -0,0 +1,21 @@
+module Jbr
+  # The visits an app under test asked {Jbr.mock} to answer with.
+  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 }
+
+  private
+
+    def mocked(visits)
+      Enumerator.new { |yielder| visits.each { |visit| yielder << Mock::Visit.new(node: visit) } }
+    end
+
+    def started?(visit) = visit[:starts_at] ? visit[:starts_at] <= Time.now : false
+  end
+end

data/lib/jbr/mock.rb

@@ -2,6 +2,6 @@ module Jbr
   # What an app under test wants Jobber to answer.
   class Mock
     # The canned answers, each read by the matching Mock resource.
-    attr_accessor :quote, :job, :invoice, :request, :visits, :oauth_url, :oauth_error
+    attr_accessor :quote, :job, :invoice, :request, :visits, :jobs, :oauth_url, :oauth_error
   end
 end

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

@@ -29,10 +29,10 @@ module Jbr
     def account = Account.new oauth: self
     def clients = Client.new oauth: self
     def invoices = Invoice.new oauth: self
-    def jobs = Job.new oauth: self
+    def jobs = Jobs.new oauth: self
     def quotes = Quote.new oauth: self
     def requests = Request.new oauth: self
-    def visits = Visit.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.

data/lib/jbr/properted.rb

@@ -0,0 +1,17 @@
+module Jbr
+  # Extends a record that stands at a property: a visit, a job, anything Jobber files
+  # somewhere.
+  module Properted
+    # What to ask for where a record names the place the work happens at.
+    # @param client [Boolean] whether the place's own client comes back with it, which spares
+    #   a second query for somebody Jobber already knows the place belongs to.
+    def self.selection(client: false)
+      [ 'property { id address {', Property::SELECTION, '}',
+        (Cliental::SELECTION if client), '}',
+      ].compact.join ' '
+    end
+
+    # @return [Property] where the work happens, and who Jobber holds the place for.
+    def property = Property.new node: @node.fetch('property', {})
+  end
+end

data/lib/jbr/property.rb

@@ -1,6 +1,8 @@
 module Jbr
   # Where the work happens: one address on a client's file.
   class Property < Resource
+    include Cliental
+
     # The mutation that adds a property to a client already on file.
     CREATE = <<~GRAPHQL
       mutation propertyCreateMutation($clientId: EncodedId!, $input: PropertyCreateInput!) {
@@ -20,6 +22,19 @@ module Jbr
     # The address as Jobber answers it, asked for wherever a property is read.
     SELECTION = "#{FIELDS.keys.join ' '} coordinates { #{COORDINATES.join ' '} }"
 
+    # Where the place is, in the fields a caller passes to open one.
+    # @return [Hash] any of :street, :city, :state, :zip, :latitude and :longitude.
+    def address = Property.fields_from @node['address']
+
+    # @return [String, nil] the street the work happens on.
+    def street = address[:street]
+
+    # @return [String, nil] the town the work happens in.
+    def city = address[:city]
+
+    # @return [String, nil] the postal code the work happens in.
+    def zip = address[:zip]
+
     # The fields a match is made on. City and state are written but never matched:
     # Jobber holds whatever was typed, so "NC" and "North Carolina" -- or "Winston Salem"
     # and "Winston-Salem" -- would read as two homes. The ZIP already places the home.
@@ -29,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.
@@ -40,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

@@ -1,12 +1,46 @@
 module Jbr
-  # What every Jobber resource shares: the credentials it is read or written through.
+  # 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.
   class Resource
-    # @param oauth [OAuth] the credentials to reach Jobber with.
-    def initialize(oauth:)
+    # @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: {})
       @oauth = oauth
+      @node = node
+      @id = node['id']
+      @includes = includes
     end
 
-    # @return [String, nil] the Jobber ID, once the resource has been read or created.
+    # @return [String, nil] the Jobber ID, from the node it came in or once one was created.
     attr_reader :id
+
+  private
+
+    # @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/version.rb

@@ -1,5 +1,5 @@
 # A Ruby client for the Jobber API.
 module Jbr
   # The version of this gem.
-  VERSION = '2.4.0'
+  VERSION = '3.1.0'
 end

data/lib/jbr/visit.rb

@@ -1,43 +1,7 @@
 module Jbr
   # One stop at a property: when the work on a job is scheduled to happen.
   class Visit < Resource
-    # What Jobber calls each field of the client the work is for, against what a caller reads.
-    CLIENT_FIELDS = { id: :id, firstName: :first_name, lastName: :last_name, email: :email }
-
-    # The query that reads a page of visits starting after a moment, oldest first. Forty a
-    # page, not a hundred: Jobber prices a query by its page size and refuses the wider one.
-    UPCOMING = <<~GRAPHQL
-      query($after: String, $from: ISO8601DateTime!) {
-        visits(first: 40, after: $after, filter: { startAt: { after: $from } }) {
-          nodes {
-            id title startAt endAt allDay clientConfirmed
-            job { id }
-            client { #{CLIENT_FIELDS.keys.join ' '} #{Phone::SELECTION} }
-            property { id address { #{Property::SELECTION} } }
-          }
-          pageInfo { hasNextPage endCursor }
-        }
-      }
-    GRAPHQL
-
-    # @param oauth [OAuth] the credentials to reach Jobber with.
-    # @param node [Hash] the visit as Jobber answered it.
-    def initialize(oauth:, node: {})
-      super oauth: oauth
-      @node = node
-    end
-
-    # The visits scheduled from now on, oldest first. Nothing is read until the enumerator
-    # is walked, and a page is read only once the one before it runs out.
-    # @return [Enumerator<Visit>] the account's upcoming visits.
-    def upcoming
-      Enumerator.new do |yielder|
-        nodes.each { |node| yielder << self.class.new(oauth: @oauth, node: node) }
-      end
-    end
-
-    # @return [String, nil] the Jobber ID of the visit.
-    def id = @node['id']
+    include Cliental, Named, Properted
 
     # @return [String, nil] what the visit is called.
     def title = @node['title']
@@ -51,46 +15,10 @@ module Jbr
     # @return [Boolean, nil] whether the client has confirmed the visit.
     def client_confirmed? = @node['clientConfirmed']
 
-    # Who the work is for, in the fields a client is created with.
-    # @return [Hash] any of :id, :first_name, :last_name, :phone and :email.
-    def client
-      fields = CLIENT_FIELDS.to_h { |jobber, ours| [ ours, @node.dig('client', jobber.to_s) ] }
-      fields.merge(phone: Phone.from(@node.dig('client', 'phones'))).compact
-    end
-
-    # Where the work happens, in the fields {Property} carries, under the ID Jobber files
-    # it by -- the shape {#client} answers in, so both read the same way.
-    # @return [Hash] any of :id, :street, :city, :state, :zip, :latitude and :longitude.
-    def property
-      fields = Property.fields_from @node.dig('property', 'address')
-      { id: @node.dig('property', 'id') }.merge fields
-    end
-
     # @return [Time, nil] the visit start time
-    def starts_at
-      Time.iso8601(@node['startAt']) if @node['startAt']
-    end
+    def starts_at = time 'startAt'
 
     # @return [Time, nil] the visit end time
-    def ends_at
-      Time.iso8601(@node['endAt']) if @node['endAt']
-    end
-
-  private
-
-    # The moment is stamped once, before the first page: read per page, it would slide
-    # forward and drop a visit that started while the pages were being walked.
-    def nodes
-      Enumerator.new do |yielder|
-        from, after = Time.now.iso8601, nil
-        loop do
-          page = @oauth.query(UPCOMING, variables: { after: after, from: from }).fetch 'visits', {}
-          page.fetch('nodes', []).each { |node| yielder << node }
-          break unless page.dig 'pageInfo', 'hasNextPage'
-
-          after = page.dig 'pageInfo', 'endCursor'
-        end
-      end
-    end
+    def ends_at = time 'endAt'
   end
 end

data/lib/jbr/visits.rb

@@ -0,0 +1,38 @@
+module Jbr
+  # The visits on a Jobber account, oldest first, walked a page at a time.
+  class Visits < Resource
+    include Enumerable, Includable
+
+    # 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
+
+  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.
+    def page
+      <<~GRAPHQL
+        query($after: String, $filter: VisitFilterAttributes) {
+          visits(first: 40, after: $after, filter: $filter) {
+            nodes { #{FIELDS} #{selections} }
+            pageInfo { hasNextPage endCursor }
+          }
+        }
+      GRAPHQL
+    end
+
+    def field = 'visits'
+
+    def item(node) = Visit.new node: node
+  end
+end

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'
@@ -9,28 +15,40 @@ require 'jbr/mock'
 
 require 'jbr/url'
 require 'jbr/error'
+# 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'
+require 'jbr/cliental'
+require 'jbr/named'
 require 'jbr/resource'
 require 'jbr/request'
 require 'jbr/oauth'
 
 require 'jbr/account'
-# Phone and Property come before Client and Visit: their queries read these as they load.
-require 'jbr/phone'
+# Property comes before Client and Visit: their queries read its fields as they load.
 require 'jbr/property'
+require 'jbr/properted'
+require 'jbr/includable'
 require 'jbr/client'
 require 'jbr/invoice'
 require 'jbr/job'
+require 'jbr/jobs'
 require 'jbr/quote'
 require 'jbr/visit'
+require 'jbr/visits'
 
 require 'jbr/mock/oauth'
+require 'jbr/mock/client'
+require 'jbr/mock/property'
 require 'jbr/mock/quote'
 require 'jbr/mock/job'
+require 'jbr/mock/jobs'
 require 'jbr/mock/invoice'
 require 'jbr/mock/request'
 require 'jbr/mock/account'
 require 'jbr/mock/url'
 require 'jbr/mock/visit'
+require 'jbr/mock/visits'
 
 require 'jbr/mocking'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 3.1.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
@@ -96,22 +110,31 @@ files:
 - lib/jbr.rb
 - lib/jbr/account.rb
 - lib/jbr/client.rb
+- lib/jbr/cliental.rb
 - lib/jbr/error.rb
 - lib/jbr/event.rb
+- lib/jbr/includable.rb
 - lib/jbr/invoice.rb
 - lib/jbr/job.rb
+- lib/jbr/jobs.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/oauth.rb
+- lib/jbr/mock/property.rb
 - lib/jbr/mock/quote.rb
 - lib/jbr/mock/request.rb
 - lib/jbr/mock/url.rb
 - 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
 - lib/jbr/property.rb
 - lib/jbr/quote.rb
 - lib/jbr/request.rb
@@ -119,6 +142,7 @@ files:
 - lib/jbr/url.rb
 - lib/jbr/version.rb
 - lib/jbr/visit.rb
+- lib/jbr/visits.rb
 homepage: https://github.com/HouseAccountEng/jbr
 licenses:
 - MIT