jbr 3.12.0 → 4.0.0

data/lib/jbr/mock/quotes.rb

@@ -0,0 +1,7 @@
+module Jbr
+  # The one quote an app under test asked {Jbr.mock} to answer with.
+  class Mock::Quotes
+    # @return [Mock::Quote, nil] quote the app named, whatever ID is asked for.
+    def find(_id) = (Mock::Quote.new node: Jbr.mock.quote if Jbr.mock.quote)
+  end
+end

data/lib/jbr/mock/visit.rb

@@ -1,23 +1,7 @@
 module Jbr
-  # A visit that reads from {Jbr.mock} instead of Jobber.
+  # A visit an app under test listed, keyed by the vocabulary's names rather than Jobber's.
   class Mock::Visit < Visit
-    # @return [Object, nil] the values the app asked for.
-    def id = @node[:id]
-
-    def title = @node[:title]
-
-    def job_id = @node[:job_id]
-
-    def client = Mock::Client.new(node: @node.fetch(:client, {}))
-
-    def property = Mock::Property.new(node: @node.fetch(:property, {}))
-
-    def all_day? = @node[:all_day]
-
-    def client_confirmed? = @node[:client_confirmed]
-
-    def starts_at = @node[:starts_at]
-
-    def ends_at = @node[:ends_at]
+    # The mock spells every key as the reader is named.
+    def self.keys = {}
   end
 end

data/lib/jbr/mock/visits.rb

@@ -2,17 +2,21 @@ module Jbr
   # The visits an app under test asked {Jbr.mock} to answer with. Only the walk is mocked:
   # narrowing a list, and reading it as records or as IDs, is the same code a real one runs.
   class Mock::Visits < Visits
-    # @return [Mock::Visit] the visit the app listed under that ID.
-    def find(id) = Mock::Visit.new node: listed(id)
+    # @param id [String] ID the app filed the visit under.
+    # @return [Mock::Visit, nil] visit the app listed under that ID, nil where it listed none.
+    def find(id)
+      node = Jbr.mock.visits.to_a.find { |visit| visit[:id] == id }
+      Mock::Visit.new node: node if node
+    end
 
   private
 
     def walk(_statement)
-      Enumerator.new { |yielder| selected.each { |it| yielder << Mock::Visit.new(node: it) } }
+      Enumerator.new do |yielder|
+        selected.each { |node| yielder << Mock::Visit.new(node: node) }
+      end
     end
 
     def selected = Jbr.mock.visits.select { |visit| scheduled? visit[:starts_at] }
-
-    def listed(id) = Jbr.mock.visits.to_a.find { |visit| visit[:id] == id }.to_h
   end
 end

data/lib/jbr/mock.rb

@@ -1,8 +1,21 @@
 module Jbr
-  # What an app under test wants Jobber to answer.
+  # What an app under test wants Jobber to answer, by the vocabulary's names.
   class Mock
-    # The canned answers, each read by the matching Mock resource.
-    attr_accessor :account, :quote, :job, :invoice, :request, :visits, :jobs, :oauth_url,
+    # The canned answers, each read by the matching mock collection.
+    attr_accessor :business, :quote, :job, :invoice, :lead, :jobs, :visits, :oauth_url,
       :oauth_error
   end
+
+  class << self
+    # Touching it once turns every account over to its mock counterpart.
+    # @return [Mock] answers this process gives, created on first use.
+    def mock = @mock ||= Mock.new
+
+    # @return [Boolean] whether an app under test has switched Jobber off.
+    def mocked? = !@mock.nil?
+
+    # Set to nil, hands the accounts back to Jobber.
+    # @return [Mock, nil] answers this process gives.
+    attr_writer :mock
+  end
 end

data/lib/jbr/phone.rb

@@ -4,20 +4,17 @@ module Jbr
     # 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.
+    # The primary number first, then one that takes texts, then the rest as filed; the first
+    # of them that can be dialed is the one.
+    # @param phones [Array<Hash>, nil] numbers as Jobber answered them.
+    # @return [String, nil] 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
+      ranked.lazy.filter_map { |phone, _| Company::Phone.from phone['normalizedPhoneNumber'] }.first
     end
   end
 end

data/lib/jbr/querying.rb

@@ -0,0 +1,57 @@
+module Jbr
+  # What credentials do with a statement: post it to Jobber, refresh a stale token once, and
+  # raise every refusal as a {Error} so a caller rescues one class.
+  module Querying
+    # Where every query and mutation is posted.
+    ENDPOINT = 'https://api.getjobber.com/api/graphql'
+
+    # The version of the schema every statement is written against.
+    HEADERS = { 'X-JOBBER-GRAPHQL-VERSION' => '2026-04-22' }
+
+    # The mutation that revokes the app on the account.
+    DISCONNECT = <<~GRAPHQL
+      mutation Disconnect {
+        appDisconnect {
+          app { name author }
+          userErrors { message }
+        }
+      }
+    GRAPHQL
+
+    # Nothing here ever sleeps: where Jobber holds the app to a limit it says so, and a caller
+    # asking from a background job has a queue that will bring the whole job back later.
+    # @param statement [String] query or mutation to run.
+    # @param variables [Hash] what the statement takes.
+    # @return [Hash] data Jobber answered, or empty when the credentials are dead.
+    # @raise [Throttled] where Jobber refused the statement for what it costs.
+    # @raise [Error] where Jobber refused the statement, or took a mutation and would not act.
+    def query(statement, variables: {})
+      data = client.query statement, variables: variables
+      refusals = user_errors(data).map { |error| error['message'] }
+      raise Error, refusals.join('; ') if refusals.any?
+
+      data
+    rescue GraphQL::Unauthorized
+      refresh ? retry : {}
+    rescue GraphQL::Throttled => error
+      raise Throttled, error.message
+    rescue GraphQL::Error => error
+      raise Error, error.message
+    end
+
+    # Revoke the credentials on the account. Dead ones have nothing left to revoke.
+    def delete
+      client.query DISCONNECT
+    rescue GraphQL::Unauthorized
+    end
+
+  private
+
+    def client = GraphQL::Client.new endpoint: ENDPOINT, token: @access_token, headers: HEADERS
+
+    def user_errors(data)
+      fields = data.each_value.select { |field| field.is_a? Hash }
+      fields.flat_map { |field| Array(field['userErrors']) }
+    end
+  end
+end

data/lib/jbr/reader.rb

@@ -0,0 +1,9 @@
+module Jbr
+  # What every kind reached through the credentials shares: the credentials.
+  class Reader
+    # @param account [Account] credentials to reach Jobber with.
+    def initialize(account:)
+      @account = account
+    end
+  end
+end

data/lib/jbr/refreshing.rb

@@ -5,18 +5,12 @@ module Jbr
   module Refreshing
   private
 
-    # With no store there is nobody to compare against: refresh, and leave what we end up
-    # holding for the caller to persist.
     def refresh
       return exchange unless @store
 
       @store.exclusively { |stored| renew stored }
     end
 
-    # Under the store's lock, holding what it says right now. A token that is no longer the one
-    # we tried is one somebody else has already replaced, and adopting it asks Jobber nothing —
-    # which is what keeps a queue of workers from refreshing a hundred times over, each with a
-    # refresh token the first of them has already spent.
     def renew(stored)
       return adopt stored if stored[:access_token] != @access_token
 
@@ -37,8 +31,6 @@ module Jbr
       true
     end
 
-    # Refused while holding the freshest refresh token there is, so the grant itself is dead
-    # rather than our copy being behind.
     def refused
       @invalid_at = Time.now
       @store&.write self

data/lib/jbr/resources/customer.rb

@@ -0,0 +1,23 @@
+module Jbr
+  # A person the business works for, who Jobber calls a client.
+  class Customer < Company::Customer
+    # The node keys Jobber spells otherwise than the vocabulary.
+    def self.keys = { name: :firstName, surname: :lastName }
+
+    # What Jobber calls each flat field of a client. The phones nest: see {Phone}.
+    FIELDS = 'id firstName lastName companyName email'
+
+    # What to ask for wherever a record names its client.
+    SELECTION = "client { #{FIELDS} #{Phone::SELECTION} }"
+
+    # Jobber files nobody without one name or the other, so there is always one to call them.
+    # @return [String, nil] first name, or the business's name where a person has none.
+    def name = super.presence || attribute(:companyName).presence
+
+    # @return [String, nil] ten digits they are reached on, nil where none can be dialed.
+    def phone = Phone.from @node[:phones]
+
+    # @return [Array<Location>] places on their file, where the query asked for them.
+    def locations = @node.dig(:clientProperties, :nodes).to_a.map { |node| Location.new node: node }
+  end
+end

data/lib/jbr/resources/invoice.rb

@@ -0,0 +1,29 @@
+module Jbr
+  # A bill the business issued for finished work, which Jobber alone answers for.
+  class Invoice < Company::Resource
+    # What every invoice reads.
+    def self.attributes = %i[id amount completed_at issued_at]
+
+    # The node keys Jobber spells otherwise than the readers.
+    def self.keys = { amount: :total, issued_at: :issuedDate }
+
+    # Jobber lists the jobs an invoice bills, and one it bills one.
+    # @return [Job, nil] job the invoice bills, where Jobber listed one.
+    def job
+      node = @node.dig :jobs, :nodes, 0
+      Job.new node: node if node
+    end
+
+    # @return [BigDecimal, nil] what the invoice comes to, in dollars.
+    def amount = decimal :amount
+
+    # @return [Time, nil] moment the billed work was finished, or the bill issued where undated.
+    def fulfilled_at = completed_at || issued_at
+
+  private
+
+    def completed_at = job&.completed_at
+
+    def issued_at = time :issued_at
+  end
+end

data/lib/jbr/resources/job.rb

@@ -0,0 +1,20 @@
+module Jbr
+  # Work the business accepted and scheduled.
+  class Job < Company::Job
+    # The node keys Jobber spells otherwise than the vocabulary.
+    def self.keys
+      { description: :title, notes: :instructions, created_at: :createdAt,
+        scheduled_at: :startAt, completed_at: :completedAt, amount: :total, }
+    end
+
+    # @return [Quote, nil] quote the job was won with, where Jobber filed one beside it.
+    def quote = record Quote, :quote
+
+    # @return [Array<Line>] lines the job is made of, empty where the query never asked for
+    #   them: a page costs what it carries, so nothing nested arrives unasked.
+    def lines = @node.dig(:lineItems, :nodes).to_a.map { |node| Line.new node: node }
+
+    # @return [Location, nil] where the work happens, where it came back beside the job.
+    def location = record Location, :property
+  end
+end

data/lib/jbr/resources/lead.rb

@@ -0,0 +1,7 @@
+module Jbr
+  # Somebody who asked the business for work, which Jobber files as a request.
+  class Lead < Company::Lead
+    # @return [Customer, nil] client the request was opened against.
+    def customer = record Customer, :client
+  end
+end

data/lib/jbr/resources/line.rb

@@ -0,0 +1,15 @@
+module Jbr
+  # One line of the work a job is made of.
+  class Line < Company::Line
+    # The node keys Jobber spells otherwise than the vocabulary.
+    def self.keys = { amount: :totalPrice }
+
+    # The most lines to read off one record. Bounded because Jobber prices a connection by the
+    # page it is asked for and prices an unbounded one at its own maximum, so the lines of a
+    # page of jobs were charged for as though every job had the largest job's worth of them.
+    PAGE = 20
+
+    # What to ask for wherever a record lists the lines it is made of.
+    SELECTION = "lineItems(first: #{PAGE}) { nodes { #{node_keys.join ' '} } }"
+  end
+end

data/lib/jbr/resources/location.rb

@@ -0,0 +1,31 @@
+module Jbr
+  # Where work happens, which Jobber calls a property: one address on a client's file.
+  class Location < Company::Location
+    # The node keys Jobber spells otherwise than the vocabulary.
+    def self.keys = { street: :street1, zip: :postalCode }
+
+    # The address as Jobber answers it, the coordinates tucked inside.
+    ADDRESS = 'street1 city postalCode coordinates { latitude longitude }'
+
+    # What to ask for wherever a record names the place the work happens at.
+    # @param customer [Boolean] whether whose place it is comes back beside it, which spares a
+    #   second query for somebody Jobber already knows the place belongs to.
+    # @return [String] selection of a property.
+    def self.selection(customer: false)
+      [ 'property { id address {', ADDRESS, '}', (Customer::SELECTION if customer), '}' ].
+        compact.join ' '
+    end
+
+    # Jobber answers a field it holds nothing for with an empty string as readily as with
+    # null, and the two arrive as the same nothing.
+    # @param node [Hash] property as Jobber answered it, the address and its coordinates nested.
+    def initialize(node: {})
+      node = node.with_indifferent_access
+      address, coordinates = node[:address].to_h, node.dig(:address, :coordinates).to_h
+      super node: node.merge(address, coordinates).compact_blank
+    end
+
+    # @return [Customer, nil] whose place it is, where they came back beside the location.
+    def customer = record Customer, :client
+  end
+end

data/lib/jbr/resources/quote.rb

@@ -0,0 +1,15 @@
+module Jbr
+  # A price the business sent to answer a lead, which Jobber calls a request.
+  class Quote < Company::Quote
+    # Jobber alone files the request a quote answers beside it; the vocabulary knows no such link.
+    # @return [Lead, nil] request the quote answers, where Jobber filed one beside it.
+    def lead = record Lead, :request
+
+    # Jobber files the total among the quote's amounts.
+    # @return [BigDecimal, nil] what the quote comes to, in dollars.
+    def amount
+      total = @node.dig :amounts, :total
+      BigDecimal total.to_s if total.present?
+    end
+  end
+end

data/lib/jbr/resources/visit.rb

@@ -0,0 +1,17 @@
+module Jbr
+  # One stop of a job: when the work is scheduled to happen, where the job does.
+  class Visit < Company::Visit
+    # What every visit reads: the vocabulary's names, and whether the client confirmed it,
+    # which Jobber alone asks.
+    def self.attributes = super + %i[confirmed]
+
+    # The node keys Jobber spells otherwise than the vocabulary.
+    def self.keys
+      { description: :title, starts_at: :startAt, ends_at: :endAt, anytime: :allDay,
+        confirmed: :clientConfirmed, }
+    end
+
+    # @return [Boolean, nil] whether the client confirmed the visit.
+    def confirmed? = attribute :confirmed
+  end
+end

data/lib/jbr/version.rb

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

data/lib/jbr.rb

@@ -1,68 +1,59 @@
 require 'json'
 require 'net/http'
 
-# Only the three Active Support files whose methods are used, rather than the whole of it:
-# Jobber answers a field it holds nothing for with an empty string as readily as with null,
-# and a caller who validates presence needs those to arrive as the same nothing. The third is
-# for the sentence a job's lines read as.
-require 'active_support/core_ext/object/blank'
+# The vocabulary every record here answers in, and the Active Support it brings along. One
+# more file of it: an address is sent without the fields a caller left blank.
+require 'company'
 require 'active_support/core_ext/enumerable'
-require 'active_support/core_ext/array/conversions'
 
 require 'graphql/error'
 require 'graphql/unauthorized'
 require 'graphql/throttled'
 require 'graphql/client'
 
-require 'jbr/mock'
-
-require 'jbr/url'
+require 'jbr/version'
 require 'jbr/error'
-require 'jbr/refused'
-require 'jbr/retriable'
+require 'jbr/errors/refused'
+require 'jbr/errors/throttled'
 require 'jbr/token'
 require 'jbr/refreshing'
-# 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/querying'
+require 'jbr/authorizing'
+require 'jbr/mock'
 
-require 'jbr/account'
-# Property comes before Client and Visit: their queries read its fields as they load.
-require 'jbr/property'
-require 'jbr/properted'
+# Phone before Customer, and Location before Customers: what each asks Jobber for is built as
+# it loads. Every record before the collection that reads it, for the same reason.
+require 'jbr/phone'
+require 'jbr/resources/customer'
+require 'jbr/resources/location'
+require 'jbr/resources/line'
+require 'jbr/resources/job'
+require 'jbr/resources/visit'
+require 'jbr/resources/quote'
+require 'jbr/resources/invoice'
+require 'jbr/resources/lead'
+
+require 'jbr/reader'
+require 'jbr/collection'
 require 'jbr/includable'
 require 'jbr/listable'
-# LineItem before Itemized, and both before Job: the lines a job is made of are asked for
-# by a constant the include reads as it loads.
-require 'jbr/line_item'
-require 'jbr/itemized'
-require 'jbr/client'
-require 'jbr/invoice'
-require 'jbr/job'
-require 'jbr/jobs'
-require 'jbr/quote'
-require 'jbr/visit'
-require 'jbr/visits'
+require 'jbr/collections/jobs'
+require 'jbr/collections/visits'
+require 'jbr/collections/quotes'
+require 'jbr/collections/invoices'
+require 'jbr/collections/customers'
+require 'jbr/collections/locations'
+require 'jbr/collections/leads'
+require 'jbr/account'
 
-require 'jbr/mock/oauth'
-require 'jbr/mock/client'
-require 'jbr/mock/property'
-require 'jbr/mock/quote'
-require 'jbr/mock/line_item'
-require 'jbr/mock/job'
 require 'jbr/mock/jobs'
-require 'jbr/mock/invoice'
-require 'jbr/mock/request'
-require 'jbr/mock/account'
-require 'jbr/mock/url'
 require 'jbr/mock/visit'
 require 'jbr/mock/visits'
-
-require 'jbr/mocking'
+require 'jbr/mock/quote'
+require 'jbr/mock/quotes'
+require 'jbr/mock/invoice'
+require 'jbr/mock/invoices'
+require 'jbr/mock/leads'
+require 'jbr/mock/account'
 
 require 'jbr/event'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 3.12.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: company
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -110,48 +124,45 @@ files:
 - lib/graphql/unauthorized.rb
 - lib/jbr.rb
 - lib/jbr/account.rb
-- lib/jbr/client.rb
-- lib/jbr/cliental.rb
+- lib/jbr/authorizing.rb
+- lib/jbr/collection.rb
+- lib/jbr/collections/customers.rb
+- lib/jbr/collections/invoices.rb
+- lib/jbr/collections/jobs.rb
+- lib/jbr/collections/leads.rb
+- lib/jbr/collections/locations.rb
+- lib/jbr/collections/quotes.rb
+- lib/jbr/collections/visits.rb
 - lib/jbr/error.rb
+- lib/jbr/errors/refused.rb
+- lib/jbr/errors/throttled.rb
 - lib/jbr/event.rb
 - lib/jbr/includable.rb
-- lib/jbr/invoice.rb
-- lib/jbr/itemized.rb
-- lib/jbr/job.rb
-- lib/jbr/jobs.rb
-- lib/jbr/line_item.rb
 - lib/jbr/listable.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/invoices.rb
 - lib/jbr/mock/jobs.rb
-- lib/jbr/mock/line_item.rb
-- lib/jbr/mock/oauth.rb
-- lib/jbr/mock/property.rb
+- lib/jbr/mock/leads.rb
 - lib/jbr/mock/quote.rb
-- lib/jbr/mock/request.rb
-- lib/jbr/mock/url.rb
+- lib/jbr/mock/quotes.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/querying.rb
+- lib/jbr/reader.rb
 - lib/jbr/refreshing.rb
-- lib/jbr/refused.rb
-- lib/jbr/request.rb
-- lib/jbr/resource.rb
-- lib/jbr/retriable.rb
+- lib/jbr/resources/customer.rb
+- lib/jbr/resources/invoice.rb
+- lib/jbr/resources/job.rb
+- lib/jbr/resources/lead.rb
+- lib/jbr/resources/line.rb
+- lib/jbr/resources/location.rb
+- lib/jbr/resources/quote.rb
+- lib/jbr/resources/visit.rb
 - lib/jbr/token.rb
-- lib/jbr/url.rb
 - lib/jbr/version.rb
-- lib/jbr/visit.rb
-- lib/jbr/visits.rb
 homepage: https://github.com/HouseAccountEng/jbr
 licenses:
 - MIT