jbr 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c3baeab4ed52ddaf9e86a1086b34b84da47a9bce32a46e05036145dc1c9ca86
-  data.tar.gz: e0c89dd53a6e64a15bba3b748b1689f2cc063030ba64ed13b18364d1768a6f99
+  metadata.gz: c2e03e9b80223954e92497d75f84d2f6be78f23fadcbcfd7d82ba95e83ebacec
+  data.tar.gz: aac7754bb691e5b45ec8284a289eceacfc9afc961cbb71e6ffedc2f92a5fd2a9
 SHA512:
-  metadata.gz: cd207ad99f2769ae55bcf2a4f5b149118bafa49f6638d18a4e4a9661ff5729cb1fd1398b67af68cfb17dd251a851b46a350835621a34ed3f888f3676e774d621
-  data.tar.gz: d8dc7694dff3aa8ef51480ab51500c94903cf0118f6d075e9b8ada9fae761dcb7f91f133a9eb7ee4894c33a18fab59645ae138ccd4aec367fa5c0ccbf50c0a9f
+  metadata.gz: 1a962bbdc7d20e9549fb10d55a5c52ddb1de7ce7c92a9da20e61162f040a8b2da35c2c6daa545c4ef67e36b04eec0085fa03faddf10db6435674390c20ddacde
+  data.tar.gz: e565f59d6f14284fd3919a048f770e060588be06850d225947b4552d88b1201ea7149afec5fe733f57d78afaa1809ea762f62377a7596729917381ecd7d65e7f

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [2.2.0] - 2026-08-07
+
+- [New] Carry the client a visit is for -- id, first name, last name, phone and email --
+  and the ID of the property it happens at, so an app can file a visit against the people
+  and places it already knows
+
+## [2.1.0] - 2026-08-07
+
+- [New] Fetch the visits an account has scheduled from now on, with oauth.visits.upcoming.
+  Each carries its job, its times, whether it takes the whole day, whether the client
+  confirmed it, and the address of the property it happens at, in the same fields
+  Jbr::Property takes. It answers an Enumerator, so a page is read only once the one
+  before it runs out
+- [New] Read a property's latitude and longitude, beside its street rather than under a
+  hash of their own. Every query that reads a property asks for them
+
 ## [2.0.0] - 2026-08-07
 
 - [Fix] Require nothing but the standard library: to_query, present?, pluck,

data/README.md

@@ -86,6 +86,29 @@ invoice.issued_at # => 2026-05-22 12:12:53
 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:
+
+```ruby
+visits = oauth.visits.upcoming # => an Enumerator, nothing fetched yet
+visit = visits.first
+visit.id # => 'Z2lkOi8vS'
+visit.title # => 'Furnace tune-up'
+visit.job_id # => 'Z2lkOi8vS'
+visit.property_id # => 'Z2lkOi8vS'
+visit.client # => { id: 'Z2lkOi8vS', first_name: 'Jane', last_name: 'Doe',
+             #      phone: '5553335555', email: 'jane@example.com' }
+visit.address # => { street: '1 Main St', city: 'Raleigh', state: 'NC', zip: '27601',
+              #      latitude: 35.77, longitude: -78.63 }
+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
+```
+
 ### Events
 
 Parse the payload of a Jobber event webhook:
@@ -145,6 +168,18 @@ Mock successfully fetching a job:
 Jbr.mock.job = { id: 'job-01', quote_id: 'quote-01', scheduled_at: Date.tomorrow.noon }
 ```
 
+### Visits
+
+Mock successfully fetching upcoming visits:
+
+```ruby
+Jbr.mock.visits = [ { id: 'visit-01', title: 'Furnace tune-up', job_id: 'job-01',
+  property_id: 'property-01', 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 } ]
+```
+
 ### Invoices
 
 Mock successfully fetching an invoice:

data/lib/jbr/client.rb

@@ -5,7 +5,7 @@ module Jbr
     LOOKUP = <<~GRAPHQL
       query($searchTerm: String!) {
         clientPhones(first: 1, searchTerm: $searchTerm) { nodes {
-          client { id updatedAt clientProperties { nodes { id address { street1 city province postalCode } }} }
+          client { id updatedAt clientProperties { nodes { id address { #{Property::SELECTION} } }} }
         } }
       }
     GRAPHQL

data/lib/jbr/mock/oauth.rb

@@ -7,6 +7,7 @@ module Jbr
     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)
 
     # Revoking a mocked token asks nobody.
     def delete; end

data/lib/jbr/mock/visit.rb

@@ -0,0 +1,32 @@
+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]
+
+    def title = @node[:title]
+
+    def job_id = @node[:job_id]
+
+    def property_id = @node[:property_id]
+
+    def client = @node.fetch :client, {}
+
+    def address = @node.fetch :address, {}
+
+    def all_day? = @node[:all_day]
+
+    def client_confirmed? = @node[:client_confirmed]
+
+    def starts_at = @node[:starts_at]
+
+    def ends_at = @node[:ends_at]
+  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, :oauth_url, :oauth_error
+    attr_accessor :quote, :job, :invoice, :request, :visits, :oauth_url, :oauth_error
   end
 end

data/lib/jbr/oauth.rb

@@ -1,6 +1,5 @@
 module Jbr
-  # Credentials for one Jobber account, and the gateway to everything read or written
-  # with them. An expired access token is refreshed and the call retried once.
+  # Credentials for one Jobber account, and the gateway to all they read or write.
   class OAuth
     # The mutation that revokes the app on the account.
     DISCONNECT_MUTATION = <<~GRAPHQL
@@ -33,6 +32,7 @@ module Jbr
     def jobs = Job.new oauth: self
     def quotes = Quote.new oauth: self
     def requests = Request.new oauth: self
+    def visits = Visit.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/property.rb

@@ -14,6 +14,12 @@ module Jbr
     # What Jobber calls each address field, against what a caller passes.
     FIELDS = { street1: :street, city: :city, province: :state, postalCode: :zip }
 
+    # The two Jobber tucks inside the address and a property carries beside the street.
+    COORDINATES = %i[latitude longitude]
+
+    # The address as Jobber answers it, asked for wherever a property is read.
+    SELECTION = "#{FIELDS.keys.join ' '} coordinates { #{COORDINATES.join ' '} }"
+
     # 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.
@@ -26,6 +32,17 @@ module Jbr
       FIELDS.to_h { |jobber, ours| [ jobber, fields[ours] ] }.compact
     end
 
+    # The fields a caller reads, from the address as Jobber holds it.
+    # @param address [Hash, nil] the address Jobber answered, if it answered one.
+    # @return [Hash] any of :street, :city, :state, :zip, :latitude and :longitude,
+    #   without the ones Jobber left out.
+    def self.fields_from(address)
+      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
+    end
+
     # Reach the property at an address, adding one when none of the client's matches.
     # @param client_id [String] the client the property belongs to.
     # @param address [Hash] the fields the work happens at.

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.0.0'
+  VERSION = '2.2.0'
 end

data/lib/jbr/visit.rb

@@ -0,0 +1,96 @@
+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,
+      phone: :phone, 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 ' '} }
+            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']
+
+    # @return [String, nil] what the visit is called.
+    def title = @node['title']
+
+    # @return [String, nil] the ID of the job the visit belongs to.
+    def job_id = @node.dig 'job', 'id'
+
+    # @return [Boolean, nil] whether the visit takes the whole day rather than an hour of it.
+    def all_day? = @node['allDay']
+
+    # @return [Boolean, nil] whether the client has confirmed the visit.
+    def client_confirmed? = @node['clientConfirmed']
+
+    # @return [String, nil] the ID of the property the work happens at.
+    def property_id = @node.dig 'property', 'id'
+
+    # 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
+      CLIENT_FIELDS.to_h { |jobber, ours| [ ours, @node.dig('client', jobber.to_s) ] }.compact
+    end
+
+    # Where the work happens, in the fields {Property} carries.
+    # @return [Hash] any of :street, :city, :state, :zip, :latitude and :longitude.
+    def address = Property.fields_from @node.dig('property', 'address')
+
+    # @return [Time, nil] the visit start time
+    def starts_at
+      Time.iso8601(@node['startAt']) if @node['startAt']
+    end
+
+    # @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
+  end
+end

data/lib/jbr.rb

@@ -14,11 +14,13 @@ require 'jbr/request'
 require 'jbr/oauth'
 
 require 'jbr/account'
+# Property comes before Client and Visit: their queries read its fields as they load.
+require 'jbr/property'
 require 'jbr/client'
 require 'jbr/invoice'
 require 'jbr/job'
-require 'jbr/property'
 require 'jbr/quote'
+require 'jbr/visit'
 
 require 'jbr/mock/oauth'
 require 'jbr/mock/quote'
@@ -27,6 +29,7 @@ require 'jbr/mock/invoice'
 require 'jbr/mock/request'
 require 'jbr/mock/account'
 require 'jbr/mock/url'
+require 'jbr/mock/visit'
 
 require 'jbr/mocking'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -108,6 +108,7 @@ files:
 - lib/jbr/mock/quote.rb
 - lib/jbr/mock/request.rb
 - lib/jbr/mock/url.rb
+- lib/jbr/mock/visit.rb
 - lib/jbr/mocking.rb
 - lib/jbr/oauth.rb
 - lib/jbr/property.rb
@@ -116,6 +117,7 @@ files:
 - lib/jbr/resource.rb
 - lib/jbr/url.rb
 - lib/jbr/version.rb
+- lib/jbr/visit.rb
 homepage: https://github.com/HouseAccountEng/jbr
 licenses:
 - MIT