jbr 2.1.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6938d7f413fe243d95247911154afacb7ec9098710f784b9032bbf5bf3d60e37
-  data.tar.gz: 7b1b8c0f7b3b339ec96dd1f3343b75528a2a78755c752a0f779218746953b541
+  metadata.gz: 3bfdb96b9790f402fd9176cc2acbe42fec07d4a23e9b06b7f217297e2bfb6fcd
+  data.tar.gz: a09d5f78a7c996a1e6bf912b09ba1ee30c4f6805ac40b626848e79bb544104bd
 SHA512:
-  metadata.gz: 9f4b95151294dc8d1119bc51d5fe63544ca66a0d7073b65e1de0e6b315e9d7cffea572d21567aa05c94a9df5692e0460aa454f531e1a86967209b6e3f81c2d11
-  data.tar.gz: f1b7ed20d0eddab211e5a0ca5a68fbf6bfd25762ba20ccde8d76349e6a1fa986bc6dbc3cc062cced2947a8617fdd69cec3e33dcf8031158c24294fd0f8aaaff2
+  metadata.gz: 941d93dd184d08aadfd4b4c454bed5945e28b9bd2600b8e3798515656286c4806effa7995d06f47fa37d43974925c629cb77c13528dd21264cbf1e77e2e8717d
+  data.tar.gz: 4b31eb73766e34a1aa60d9d7f0b0c4725257cb90f8e2ea1d28792b65fec581b30b43b03878c11328edd7e96cb0fef11b5e0b0a1fab827133fe12b2e69d17c436

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [2.3.0] - 2026-08-07
+
+- [Breaking change] A client's phone is the number Jobber holds as reachable rather than
+  the string on the record: the primary before the rest, one that takes texts before one
+  that does not, and the first of those the North American plan recognizes, ten digits
+  without the country code. A client with no such number now answers nil
+
+## [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.

data/README.md

@@ -98,6 +98,10 @@ 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' }
+             # phone is the reachable North American number, ten digits, or nil
 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
@@ -171,6 +175,7 @@ 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 } ]

data/lib/jbr/mock/visit.rb

@@ -15,6 +15,10 @@ module Jbr
 
     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]

data/lib/jbr/phone.rb

@@ -0,0 +1,23 @@
+module Jbr
+  # The numbers on a client's file, and which of them the client is reached on.
+  class Phone
+    # What Jobber is asked for wherever a client is read: the number, and what ranks it.
+    SELECTION = 'phones { normalizedPhoneNumber smsAllowed primary }'
+
+    # Ten digits whose area code and exchange open with 2 through 9, behind the E.164 +1.
+    NORTH_AMERICAN = /\A\+1([2-9]\d{2}[2-9]\d{6})\z/
+
+    # The number to reach a client on, without its country code.
+    # @param phones [Array<Hash>, nil] the numbers as Jobber answered them.
+    # @return [String, nil] the ten digits to call, or nil where none can be dialed.
+    def self.from(phones)
+      # The index breaks a tie because sort_by does not: two equally ranked numbers would
+      # otherwise swap between runs, and the client would answer a different phone each time.
+      ranked = Array(phones).each_with_index.sort_by do |phone, index|
+        [ phone['primary'] ? 0 : 1, phone['smsAllowed'] ? 0 : 1, index ]
+      end
+      numbers = ranked.lazy.map { |phone, _| phone['normalizedPhoneNumber'].to_s }
+      numbers.filter_map { |number| number[NORTH_AMERICAN, 1] }.first
+    end
+  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.1.0'
+  VERSION = '2.3.0'
 end

data/lib/jbr/visit.rb

@@ -1,6 +1,9 @@
 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
@@ -9,7 +12,8 @@ module Jbr
           nodes {
             id title startAt endAt allDay clientConfirmed
             job { id }
-            property { address { #{Property::SELECTION} } }
+            client { #{CLIENT_FIELDS.keys.join ' '} #{Phone::SELECTION} }
+            property { id address { #{Property::SELECTION} } }
           }
           pageInfo { hasNextPage endCursor }
         }
@@ -47,6 +51,16 @@ module Jbr
     # @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
+      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.
     # @return [Hash] any of :street, :city, :state, :zip, :latitude and :longitude.
     def address = Property.fields_from @node.dig('property', 'address')

data/lib/jbr.rb

@@ -14,7 +14,8 @@ require 'jbr/request'
 require 'jbr/oauth'
 
 require 'jbr/account'
-# Property comes before Client and Visit: their queries read its fields as they load.
+# Phone and Property come before Client and Visit: their queries read these as they load.
+require 'jbr/phone'
 require 'jbr/property'
 require 'jbr/client'
 require 'jbr/invoice'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -111,6 +111,7 @@ files:
 - lib/jbr/mock/visit.rb
 - lib/jbr/mocking.rb
 - lib/jbr/oauth.rb
+- lib/jbr/phone.rb
 - lib/jbr/property.rb
 - lib/jbr/quote.rb
 - lib/jbr/request.rb