jbr 1.2.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68463c13bcdbb8a69d415d79426415cab50a27d805c96132859c0301e3eab8b2
-  data.tar.gz: f134a69e00d4cf3a6b0382701a05c81de434f5a246555d8f8955c97512806ced
+  metadata.gz: 6938d7f413fe243d95247911154afacb7ec9098710f784b9032bbf5bf3d60e37
+  data.tar.gz: 7b1b8c0f7b3b339ec96dd1f3343b75528a2a78755c752a0f779218746953b541
 SHA512:
-  metadata.gz: ba24574d4b690e6b22019414dd17c0a63ab07f5f7239667da987fc6f6b0f7c0b809ca863b64e52e62408c2f887c18c591450499d949c01cb3b805fbd29ed90eb
-  data.tar.gz: 40bd20b0fbe0315613a2fd883ceb906f48f5e088ac53b1bc631a453c795a0bc71a0a4c0dc7f59fd8ca91611707055cb877adecfbefeceb41224204d3045d2c3f
+  metadata.gz: 9f4b95151294dc8d1119bc51d5fe63544ca66a0d7073b65e1de0e6b315e9d7cffea572d21567aa05c94a9df5692e0460aa454f531e1a86967209b6e3f81c2d11
+  data.tar.gz: f1b7ed20d0eddab211e5a0ca5a68fbf6bfd25762ba20ccde8d76349e6a1fa986bc6dbc3cc062cced2947a8617fdd69cec3e33dcf8031158c24294fd0f8aaaff2

data/.rubocop.yml

@@ -0,0 +1,59 @@
+# Omakase Ruby styling for Rails
+inherit_gem: { rubocop-rails-omakase: rubocop.yml }
+
+# The omakase base disables whole departments and re-enables a chosen subset, so
+# every cop it does not name needs an explicit 'Enabled: true' below.
+
+AllCops:
+  # Adopt every cop a new release brings, rather than pinning to today's set
+  NewCops: enable
+  # An extension we decline is declined in this file, not merely ignored
+  SuggestExtensions: false
+
+# We never freeze a string, so the magic comment has nothing to say
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: never
+
+# The cop demands '.freeze' on string constants and cannot skip them
+Style/MutableConstant:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Layout/CaseIndentation:
+  EnforcedStyle: end
+  IndentOneStep: true
+
+# 'private' sits at the level of 'class', so it reads as a divider
+Layout/AccessModifierIndentation:
+  Enabled: true
+  EnforcedStyle: outdent
+
+# One 'include' statement carries the list, split only when it will not fit
+Style/MixinGrouping:
+  Enabled: true
+  EnforcedStyle: grouped
+
+Layout/LineLength:
+  Enabled: true
+  Max: 100
+
+# Omit parentheses on a call's arguments, keeping the inner ones parsing needs -- except
+# where the call IS the condition, after 'if', 'unless', 'while', 'until' or in a ternary,
+# which keeps them so the reader sees where the argument ends and the branch begins.
+# 'omit_parentheses' has no option for that exception and an inline disable costs three
+# lines per site, so the cop is declined and the rule held in review.
+Style/MethodCallWithArgsParentheses:
+  Enabled: false

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [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,
+  stringify_keys and Time.current were ActiveSupport calls the gemspec never declared,
+  so `require 'jbr'` raised outside Rails
+- [Fix] Reuse the property already on a client's file instead of adding a duplicate on
+  every request: the lookup read the address as `street`, while the comparison built it
+  as `street1`, so it never matched. The match is made on street and ZIP; city and state
+  are written but not matched, since Jobber holds whatever was typed
+- [Fix] Client#create no longer raises when Jobber answers without clientProperties
+- [Feature] Test every line, with SimpleCov failing the suite below 100% coverage
+- [Change] Extract Jbr::Property from Jbr::Client
+- [Change] Remove the unused Jbr::Configuration class
+
 ## [1.2.0] - 2026-06-09
 
 - [New] Create a Property with a Request if needed

data/README.md

@@ -1,5 +1,7 @@
 # Jobber API Ruby client
 
+A client for the Jobber GraphQL API. It needs nothing but the standard library.
+
 ## Available methods
 
 ### Credentials
@@ -9,6 +11,7 @@ Generate the URL for Jobber users to authorize the app:
 ```ruby
 url = Jbr.oauth_url_for redirect_uri:, state:
 url # => 'https://api.getjobber.com/api/oauth/authorize?state=...&redirect_uri=...'
+```
 
 Create credentials with a code and a redirect URI:
 
@@ -19,17 +22,17 @@ oauth = Jbr.create_oauth code:, redirect_uri:
 Initialize with existing credentials:
 
 ```ruby
-oauth = Jbr.oauth_for access_token:, refresh_token, expires_at:, account_id:
+oauth = Jbr.oauth_for access_token:, refresh_token:, expires_at:, account_id:
 ```
 
 Access OAuth attributes:
 
-```
+```ruby
 oauth.access_token # => 'eyJhbGciOiJIUzI1NiJ'
 oauth.refresh_token # => 'ea02775958c5fca28d'
 oauth.expires_at # => 2026-05-22 14:32:53
 oauth.account_id # => 'Z2lkOi8vSm9iYmV'
-````
+```
 
 Revoke credentials:
 
@@ -83,6 +86,26 @@ 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.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:
@@ -90,8 +113,8 @@ Parse the payload of a Jobber event webhook:
 ```ruby
 event = Jbr::Event.new data: { webHookEvent: { topic: 'JOB_CREATE', appId: 'app-1',
   accountId: 'account-1', itemId: 'job-1', occurredAt: '2026-05-22T15:46:33Z' } }
-event.account_id = 'account-1
-event.item_id = 'job-1
+event.account_id # => 'account-1'
+event.item_id # => 'job-1'
 ```
 
 ## Available mocks
@@ -115,7 +138,7 @@ Jbr.mock.oauth_error = 'Flow rejected'
 Mock a custom redirect URL:
 
 ```ruby
-Jbr.mock.oauth_url_for = 'https://example.com'
+Jbr.mock.oauth_url = 'https://example.com'
 ```
 
 ### Requests
@@ -142,6 +165,17 @@ 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',
+  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/graphql/client.rb

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

data/lib/jbr/account.rb

@@ -1,9 +1,12 @@
 module Jbr
+  # The Jobber account a set of credentials belongs to.
   class Account < Resource
-    FIND = <<~GRAPHQL.freeze
+    # The query that reads the account behind the current credentials.
+    FIND = <<~GRAPHQL
       { account { id } }
     GRAPHQL
 
+    # @return [String] the account ID, read once and remembered.
     def id
       @id ||= @oauth.query(FIND).dig 'account', 'id'
     end

data/lib/jbr/client.rb

@@ -1,14 +1,17 @@
 module Jbr
+  # A person a Jobber user works for, and the property the work happens at.
   class Client < Resource
-    LOOKUP = <<~GRAPHQL.freeze
+    # The query that finds a client by phone, with the properties already on file.
+    LOOKUP = <<~GRAPHQL
       query($searchTerm: String!) {
         clientPhones(first: 1, searchTerm: $searchTerm) { nodes {
-          client { id updatedAt clientProperties { nodes { id address { street city province postalCode } }} }
+          client { id updatedAt clientProperties { nodes { id address { #{Property::SELECTION} } }} }
         } }
       }
     GRAPHQL
 
-    CREATE = <<~GRAPHQL.freeze
+    # The mutation that opens a client, with a first property when an address is given.
+    CREATE = <<~GRAPHQL
       mutation($input: ClientCreateInput!) {
         clientCreate(input: $input) {
           client { id clientProperties(first: 1) { nodes { id } } }
@@ -17,15 +20,7 @@ module Jbr
       }
     GRAPHQL
 
-    CREATE_PROPERTY = <<~GRAPHQL.freeze
-      mutation propertyCreateMutation($clientId: EncodedId!, $input: PropertyCreateInput!) {
-        propertyCreate(clientId: $clientId, input: $input) {
-          properties { id }
-          userErrors { message }
-        }
-      }
-    GRAPHQL
-
+    # @return [String, nil] the property the work happens at.
     attr_reader :property_id
 
     # Create a client instance with the provided attributes.
@@ -39,6 +34,9 @@ module Jbr
       self.tap { @create_params = params }
     end
 
+    # Reach the client behind a phone number, opening one if Jobber has none.
+    # @param phone [String] the number to match on.
+    # @return [Client] itself.
     def find_or_create_by(phone:)
       find_by_phone(phone) || create
       self
@@ -54,17 +52,9 @@ module Jbr
       return unless recent
 
       @id = recent.dig 'client', 'id'
-
-      properties = recent.dig('client', 'clientProperties', 'nodes') || []
-      existing_property = properties.find do |property|
-        extract_address_from(@create_params[:address]).stringify_keys == property['address']
-      end
-      @property_id = if existing_property
-        existing_property['id']
-      else
-        property = @oauth.query CREATE_PROPERTY, variables: { clientId: @id, input: { properties: [ { address: extract_address_from(@create_params[:address]) }] } }
-        (property&.dig('propertyCreate', 'properties')&.first || {})['id']
-      end
+      @property_id = Property.new(oauth: @oauth).find_or_create_for client_id: @id,
+        address: @create_params[:address],
+        existing: recent.dig('client', 'clientProperties', 'nodes') || []
       true
     end
 
@@ -72,24 +62,20 @@ module Jbr
       output = @oauth.query CREATE, variables: { input: input }
       @id = output.dig 'clientCreate', 'client', 'id'
 
-      properties = output.dig 'clientCreate', 'client', 'clientProperties', 'nodes'
+      properties = output.dig('clientCreate', 'client', 'clientProperties', 'nodes') || []
       @property_id = (properties.first || {})['id']
     end
 
     def input
+      address, email = @create_params[:address], @create_params[:email]
       { firstName: @create_params[:first_name],
         lastName: @create_params[:last_name],
-        properties: ([{ address: extract_address_from(@create_params[:address]) }] if @create_params[:address].present?),
-        phones: [{ number: @create_params[:phone], primary: true }],
-        emails: ([{ address: @create_params[:email], primary: true }] if @create_params[:email].present?)
+        properties: ([ { address: Property.address_from(address) } ] if present?(address)),
+        phones: [ { number: @create_params[:phone], primary: true } ],
+        emails: ([ { address: email, primary: true } ] if present?(email)),
       }.compact
     end
 
-    def extract_address_from(fields = {})
-      {
-        street1: fields[:street], city: fields[:city],
-        province: fields[:state], postalCode: fields[:zip]
-      }.compact
-    end
+    def present?(value) = !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
   end
 end

data/lib/jbr/error.rb

@@ -1,3 +1,4 @@
 module Jbr
+  # An error raised when Jobber refuses a request.
   Error = Class.new StandardError
 end

data/lib/jbr/event.rb

@@ -1,4 +1,5 @@
 module Jbr
+  # One webhook Jobber posted, and the signature header it arrives under.
   class Event
     # @see https://developer.getjobber.com/docs/using_jobbers_api/setting_up_webhooks
     SIGNATURE_HEADER = 'X-Jobber-Hmac-SHA256'

data/lib/jbr/invoice.rb

@@ -1,14 +1,19 @@
 module Jbr
+  # A bill a Jobber user issued for finished work.
   class Invoice < Resource
-    FIND = <<~GRAPHQL.freeze
+    # The query that reads one invoice, its total, its date and the job it bills.
+    FIND = <<~GRAPHQL
       query($id: EncodedId!) {
         invoice(id: $id) { id total invoiceStatus issuedDate
           jobs { nodes { id completedAt } } }
       }
     GRAPHQL
 
+    # @return [String, nil] the ID of the job billed, and the amount as Jobber writes it.
     attr_reader :job_id, :total
 
+    # @param id [String] the Jobber ID of the invoice.
+    # @return [Invoice, nil] itself, or nil when the invoice is missing or still a draft.
     def find(id)
       output = @oauth.query FIND, variables: { id: id  }
       return unless invoice = output['invoice']

data/lib/jbr/job.rb

@@ -1,13 +1,18 @@
 module Jbr
+  # Work a Jobber user accepted and scheduled.
   class Job < Resource
-    FIND = <<~GRAPHQL.freeze
+    # 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
 
+    # @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']

data/lib/jbr/mock/account.rb

@@ -1,5 +1,7 @@
 module Jbr
+  # The one account every mocked set of credentials belongs to.
   class Mock::Account < Account
+    # @return [String] the mocked account ID.
     def id = 'account-01'
   end
 end

data/lib/jbr/mock/invoice.rb

@@ -1,5 +1,7 @@
 module Jbr
+  # An invoice that reads from {Jbr.mock} instead of Jobber.
   class Mock::Invoice < Invoice
+    # @return [Mock::Invoice] itself, carrying the mocked IDs and total.
     def find(_)
       @id = Jbr.mock.invoice[:id]
       @job_id = Jbr.mock.invoice[:job_id]
@@ -8,6 +10,7 @@ module Jbr
       self
     end
 
+    # @return [Time, nil] the dates the app asked for.
     def issued_at = Jbr.mock.invoice[:issued_at]
 
     def completed_at = Jbr.mock.invoice[:completed_at]

data/lib/jbr/mock/job.rb

@@ -1,5 +1,7 @@
 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]
@@ -7,6 +9,7 @@ module Jbr
       self
     end
 
+    # @return [Time, nil] the times the app asked for.
     def scheduled_at = Jbr.mock.job[:scheduled_at]
 
     def completed_at = Jbr.mock.job[:completed_at]

data/lib/jbr/mock/oauth.rb

@@ -1,19 +1,22 @@
 module Jbr
+  # Credentials that answer from {Jbr.mock} instead of Jobber.
   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 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
 
-  private
-
+    # @return [Hash] canned credentials, unless the app asked for a refusal.
     def self.post(_)
       raise Error, Jbr.mock.oauth_error if Jbr.mock.oauth_error
 
-      { access_token: 'mock-token', refresh_token: 'mock-token', expires_at: (Time.current + 3600) }
+      { access_token: 'mock-token', refresh_token: 'mock-token', expires_at: (Time.now + 3600) }
     end
   end
 end

data/lib/jbr/mock/quote.rb

@@ -1,5 +1,7 @@
 module Jbr
+  # A quote that reads from {Jbr.mock} instead of Jobber.
   class Mock::Quote < Quote
+    # @return [Mock::Quote] itself, carrying the mocked IDs.
     def find(_)
       @id = Jbr.mock.quote[:id]
       @request_id = Jbr.mock.quote[:request_id]

data/lib/jbr/mock/request.rb

@@ -1,5 +1,7 @@
 module Jbr
+  # A request that records what {Jbr.mock} was told to answer.
   class Mock::Request < Request
+    # @return [Mock::Request] itself, carrying the mocked IDs.
     def create(_)
       @id = Jbr.mock.request[:id]
       @client_id = Jbr.mock.request[:client_id]

data/lib/jbr/mock/url.rb

@@ -1,5 +1,7 @@
 module Jbr
+  # The authorize URL an app under test asked for.
   class Mock::URL < URL
+    # @return [String] whatever {Jbr.mock} was told to answer.
     def self.for(_)
       Jbr.mock.oauth_url
     end

data/lib/jbr/mock/visit.rb

@@ -0,0 +1,28 @@
+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 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

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

data/lib/jbr/mocking.rb

@@ -1,21 +1,30 @@
 module Jbr
+  # The switch an app under test throws to answer Jobber without a network. Touching
+  # {#mock} once turns every entry point below over to its Mock counterpart.
   module Mocking
+    # @return [Mock] the answers this process gives, created on first use.
     def mock
       @mock ||= Jbr::Mock.new
     end
 
+    # @param params [Hash] the +code+ and +redirect_uri+ to exchange.
+    # @return [OAuth] credentials for the account that authorized the app.
     def create_oauth(params = {})
-      (@mock ? Mock::OAuth : OAuth).create **params
+      (@mock ? Mock::OAuth : OAuth).create(**params)
     end
 
+    # @param params [Hash] the +redirect_uri+ and +state+ to come back with.
+    # @return [String] the URL a Jobber user authorizes the app on.
     def oauth_url_for(params = {})
-      (@mock ? Mock::URL : URL).for **params
+      (@mock ? Mock::URL : URL).for(**params)
     end
 
+    # @param params [Hash] credentials already on file.
+    # @return [OAuth] those credentials, ready to read and write with.
     def oauth_for(params = {})
-      (@mock ? Mock::OAuth : OAuth).new params
+      (@mock ? Mock::OAuth : OAuth).new(params)
     end
   end
 
   extend Mocking
-end
+end

data/lib/jbr/oauth.rb

@@ -1,6 +1,8 @@
 module Jbr
+  # Credentials for one Jobber account, and the gateway to all they read or write.
   class OAuth
-    DISCONNECT_MUTATION = <<~GRAPHQL.freeze
+    # The mutation that revokes the app on the account.
+    DISCONNECT_MUTATION = <<~GRAPHQL
       mutation Disconnect {
         appDisconnect {
           app { name author }
@@ -9,6 +11,7 @@ module Jbr
       }
     GRAPHQL
 
+    # @param credentials [Hash] the tokens, their expiry, the account and when it went bad.
     def initialize(credentials = {})
       @access_token = credentials[:access_token]
       @refresh_token = credentials[:refresh_token]
@@ -17,19 +20,27 @@ module Jbr
       @invalid_at = credentials[:invalid_at]
     end
 
+    # The credentials as Jobber last gave them, plus the moment a refusal to refresh landed.
     attr_reader :access_token, :refresh_token, :expires_at, :invalid_at
+    # @return [String, nil] the account these credentials reach.
     attr_accessor :account_id
 
+    # The resources these credentials read and write.
     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 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.
+    # @param variables [Hash] the variables it interpolates.
+    # @return [Hash] the data Jobber answered, or empty when the credentials are dead.
     def query(statement, variables: {})
       client.query statement, variables: variables
-    rescue GraphQL::Unauthorized => e
+    rescue GraphQL::Unauthorized
       refresh ? retry : {}
     end
 
@@ -39,6 +50,10 @@ module Jbr
     rescue GraphQL::Unauthorized => e
     end
 
+    # Exchange an authorization code for credentials, then learn their account.
+    # @param code [String] the code Jobber sent to the redirect URI.
+    # @param redirect_uri [String] the URI the code came back to.
+    # @return [OAuth] the new credentials.
     def self.create(code:, redirect_uri:)
       credentials = post code: code, redirect_uri: redirect_uri, grant_type: 'authorization_code'
       new(credentials).tap { |oauth| oauth.account_id = oauth.account.id }
@@ -50,6 +65,19 @@ module Jbr
     # @return [String, nil] The client secret to interact with the API.
     def self.client_secret = ENV['JOBBER_CLIENT_SECRET']
 
+    # Exchange a code or a refresh token for credentials. Public because #refresh
+    # reaches it through self.class, which a private class method forbids.
+    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),
+      }
+    end
+
   private
 
     def refresh
@@ -58,21 +86,13 @@ module Jbr
       @refresh_token = output[:refresh_token]
       @expires_at = output[:expires_at]
     rescue Error => e
-      @invalid_at = Time.current
+      @invalid_at = Time.now
       false
     end
 
-    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.current + output.fetch('expires_in', 3600).to_i) }
-    end
-
     def client
-      GraphQL::Client.new endpoint: 'https://api.getjobber.com/api/graphql', token: @access_token, headers: headers
+      GraphQL::Client.new endpoint: 'https://api.getjobber.com/api/graphql',
+        token: @access_token, headers: headers
     end
 
     def headers = { 'X-JOBBER-GRAPHQL-VERSION' => '2026-04-22' }

data/lib/jbr/property.rb

@@ -0,0 +1,72 @@
+module Jbr
+  # Where the work happens: one address on a client's file.
+  class Property < Resource
+    # The mutation that adds a property to a client already on file.
+    CREATE = <<~GRAPHQL
+      mutation propertyCreateMutation($clientId: EncodedId!, $input: PropertyCreateInput!) {
+        propertyCreate(clientId: $clientId, input: $input) {
+          properties { id }
+          userErrors { message }
+        }
+      }
+    GRAPHQL
+
+    # 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.
+    MATCHED = %i[street1 postalCode]
+
+    # The address as Jobber takes it, from the fields a caller passes.
+    # @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
+    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.
+    # @param existing [Array<Hash>] the properties already on the client's file.
+    # @return [String, nil] the property ID.
+    def find_or_create_for(client_id:, address:, existing: [])
+      wanted = self.class.address_from address
+      match = existing.find { |property| same_address? wanted, property['address'] }
+      return match['id'] if match
+
+      output = @oauth.query CREATE, variables: {
+        clientId: client_id, input: { properties: [ { address: wanted } ] },
+      }
+      (output&.dig('propertyCreate', 'properties')&.first || {})['id']
+    end
+
+  private
+
+    # Field by field, because Jobber answers every field it was asked for, nil included,
+    # while a caller's address carries only what they had -- an absent field and a nil
+    # one are the same address. All of {MATCHED} has to agree: a home with no street
+    # parsed must not match the one house on the client's file that does have one.
+    def same_address?(wanted, address)
+      MATCHED.all? { |field| wanted[field] == (address || {})[field.to_s] }
+    end
+  end
+end

data/lib/jbr/quote.rb

@@ -1,13 +1,18 @@
 module Jbr
+  # A price a Jobber user sent to their client.
   class Quote < Resource
-    FIND = <<~GRAPHQL.freeze
+    # The query that reads one quote and the request it came from.
+    FIND = <<~GRAPHQL
       query($id: EncodedId!) {
         quote(id: $id) { id request { id } }
       }
     GRAPHQL
 
+    # @return [String, nil] the ID of the request the quote answers.
     attr_reader :request_id
 
+    # @param id [String] the Jobber ID of the quote.
+    # @return [Quote, nil] itself, or nil when Jobber has no such quote.
     def find(id)
       output = @oauth.query FIND, variables: { id: id  }
       return unless quote = output['quote']

data/lib/jbr/request.rb

@@ -1,11 +1,14 @@
 module Jbr
+  # A lead on a Jobber user's board: work someone asked them for.
   class Request < Resource
-    CREATE = <<~GRAPHQL.freeze
+    # The mutation that opens a request against a client and a property.
+    CREATE = <<~GRAPHQL
       mutation($input: RequestCreateInput!) {
         requestCreate(input: $input) { request { id property { id } } userErrors { message } }
       }
     GRAPHQL
 
+    # @return [String, nil] the client the request was opened against.
     attr_reader :client_id
 
     # Create a lead in Jobber associated to a new or existing client, matched by phone.
@@ -24,7 +27,7 @@ module Jbr
 
       input = {
         clientId: @client_id, title: params[:title], propertyId: @property_id,
-        assessment: { instructions: params[:instructions] }
+        assessment: { instructions: params[:instructions] },
       }
       output = @oauth.query CREATE, variables: { input: input }
       @id = output.dig 'requestCreate', 'request', 'id'

data/lib/jbr/resource.rb

@@ -1,9 +1,12 @@
 module Jbr
+  # What every Jobber resource shares: the credentials it is read or written through.
   class Resource
+    # @param oauth [OAuth] the credentials to reach Jobber with.
     def initialize(oauth:)
       @oauth = oauth
     end
 
+    # @return [String, nil] the Jobber ID, once the resource has been read or created.
     attr_reader :id
   end
 end

data/lib/jbr/url.rb

@@ -1,13 +1,16 @@
 module Jbr
+  # The page a Jobber user authorizes the app on.
   class URL
+    # @param params [Hash] the +redirect_uri+ and +state+ to come back with.
+    # @return [String] the URL to send the user to.
     def self.for(params = {})
       uri = URI 'https://api.getjobber.com/api/oauth/authorize'
-      uri.query ||= params.merge(response_type: 'code', client_id: client_id).to_query
+      uri.query = URI.encode_www_form params.merge(response_type: 'code', client_id: client_id)
       uri.to_s
     end
 
-  private
-
+    # @return [String, nil] the client ID of the app being authorized.
     def self.client_id = ENV['JOBBER_CLIENT_ID']
+    private_class_method :client_id
   end
 end

data/lib/jbr/version.rb

@@ -1,5 +1,5 @@
-# frozen_string_literal: true
-
+# A Ruby client for the Jobber API.
 module Jbr
-  VERSION = '1.2.0'
+  # The version of this gem.
+  VERSION = '2.1.0'
 end

data/lib/jbr/visit.rb

@@ -0,0 +1,81 @@
+module Jbr
+  # One stop at a property: when the work on a job is scheduled to happen.
+  class Visit < Resource
+    # 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 }
+            property { 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']
+
+    # 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

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require 'json'
 require 'net/http'
 
@@ -16,10 +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/quote'
+require 'jbr/visit'
 
 require 'jbr/mock/oauth'
 require 'jbr/mock/quote'
@@ -28,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,14 +1,84 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails-omakase
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Jobber API
 email:
 - claudiob@users.noreply.github.com
@@ -16,6 +86,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".rubocop.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -25,7 +96,6 @@ files:
 - lib/jbr.rb
 - lib/jbr/account.rb
 - lib/jbr/client.rb
-- lib/jbr/configuration.rb
 - lib/jbr/error.rb
 - lib/jbr/event.rb
 - lib/jbr/invoice.rb
@@ -38,13 +108,16 @@ 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
 - lib/jbr/quote.rb
 - lib/jbr/request.rb
 - lib/jbr/resource.rb
 - lib/jbr/url.rb
 - lib/jbr/version.rb
+- lib/jbr/visit.rb
 homepage: https://github.com/HouseAccountEng/jbr
 licenses:
 - MIT

data/lib/jbr/configuration.rb

@@ -1,5 +0,0 @@
-module Jbr
-  class Configuration
-    attr_accessor :mock_account, :mock_request, :mock_auth, :mock_auth_error, :mock_disconnect, :mock_invoice, :mock_job, :mock_quote, :mock_redirect_url
-  end
-end