jbr 3.13.0 → 5.0.0

data/lib/graphql/client.rb

@@ -28,20 +28,15 @@ module GraphQL
 
   private
 
-    # Refused over cost where the endpoint names the code for it, or prices the query above
-    # what it says was left. Anything else is a refusal of the query itself.
     def refusal_for(body)
       cost = body['extensions'].to_h['cost'].to_h
       available = cost['throttleStatus'].to_h['currentlyAvailable']
       coded = body['errors'].any? { |error| error.to_h.dig('extensions', 'code') == 'THROTTLED' }
       priced = available && cost['requestedQueryCost'].to_f > available.to_f
 
-      coded || priced ? Throttled.new(refusal(body), cost) : Error.new(refusal(body))
+      (coded || priced ? Throttled : Error).new refusal(body), data: body['data']
     end
 
-    # What the endpoint refused, and — where it priced the refusal — what the query would have
-    # cost against what was available. `Throttled` on its own leaves a caller unable to tell a
-    # query too big to ever run from a bucket that a moment would have refilled.
     def refusal(body)
       message = body['errors'].map { |error| error['message'] }.join '; '
       cost = body['extensions'].to_h['cost'].to_h
@@ -51,6 +46,7 @@ module GraphQL
       "#{message} (cost #{cost['requestedQueryCost']}, #{status['currentlyAvailable']} of " \
         "#{status['maximumAvailable']} available, restoring #{status['restoreRate']}/s)"
     end
+
     def request_headers
       { 'Authorization' => "Bearer #{@token}", 'Content-Type' => 'application/json' }.merge @headers
     end

data/lib/graphql/error.rb

@@ -1,5 +1,15 @@
 module GraphQL
   # An error raised when a GraphQL request fails.
   class Error < StandardError
+    # @param message [String] what the API said went wrong.
+    # @param data [Hash, nil] what it answered alongside, where it answered anything: an API that
+    #   refuses one field of a query and fulfils the rest sends both at once.
+    def initialize(message = nil, data: nil)
+      super message
+      @data = data
+    end
+
+    # @return [Hash, nil] what came back beside the refusal, nil where nothing did.
+    attr_reader :data
   end
 end

data/lib/graphql/throttled.rb

@@ -3,14 +3,5 @@ module GraphQL
   # itself. Worth telling apart: the same query is answered once the budget it is priced
   # against has refilled.
   class Throttled < Error
-    # @param message [String] what the endpoint said, with the numbers it said it with.
-    # @param cost [Hash] what it priced the query at, and the budget it priced it against.
-    def initialize(message, cost = {})
-      super message
-      @cost = cost
-    end
-
-    # @return [Hash] those numbers, in the endpoint's own words.
-    attr_reader :cost
   end
 end

data/lib/jbr/account.rb

@@ -1,23 +1,56 @@
 module Jbr
-  # The Jobber account a set of credentials belongs to.
-  class Account < Resource
-    # The query that reads the account behind the current credentials.
-    FIND = <<~GRAPHQL
-      { account { id name phone } }
-    GRAPHQL
+  # Credentials for one Jobber account, and the gateway to all they read or write.
+  class Account < Company::Account
+    include Querying, Refreshing
+    extend Authorizing
 
-    # @return [String, nil] the account ID.
-    def id = node['id']
+    # The query that reads the business behind the credentials, by the keys the vocabulary reads.
+    BUSINESS = "{ account { #{Company::Business.node_keys.join ' '} } }"
 
-    # @return [String, nil] what the business calls itself.
-    def name = node['name']
+    # Answers from {Jbr.mock} instead of Jobber once an app under test has touched it.
+    # @param credentials [Hash] see {#initialize}.
+    # @return [Account] credentials, mocked where the app asked for that.
+    def self.new(credentials = {})
+      Jbr.mocked? && self == Account ? Mock::Account.new(credentials) : super
+    end
 
-    # @return [String, nil] the number the business is reached on, as Jobber holds it.
-    def phone = node['phone']
+    # @param credentials [Hash] the tokens, their expiry, the account, when it went bad, and
+    #   the `store:` these are kept in, where processes share them. See {Refreshing}.
+    def initialize(credentials = {})
+      @access_token = credentials[:access_token]
+      @refresh_token = credentials[:refresh_token]
+      @expires_at = credentials[:expires_at]
+      @invalid_at = credentials[:invalid_at]
+      @account_id = credentials[:account_id]
+      @store = credentials[:store]
+    end
 
-  private
+    # 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
 
-    # Read once and remembered, whichever of the three is asked for first.
-    def node = @node = @node.presence || @oauth.query(FIND).fetch('account', {})
+    # @return [String, nil] ID of the account these credentials reach.
+    attr_accessor :account_id
+
+    # @return [Company::Business] business the credentials belong to, read from Jobber.
+    def business = Company::Business.new node: query(BUSINESS).fetch('account', {})
+
+    # @return [Jobs] jobs of the business.
+    def jobs = Jobs.new account: self
+
+    # @return [Visits] visits of the business.
+    def visits = Visits.new account: self
+
+    # @return [Technicians] users of the business.
+    # @note Needs the Users scope, without which Jobber refuses the query rather than the field.
+    def technicians = Technicians.new account: self
+
+    # @return [Quotes] quotes of the business, which Jobber alone lists.
+    def quotes = Quotes.new account: self
+
+    # @return [Leads] leads of the business.
+    def leads = Leads.new account: self
+
+    # @return [Invoices] invoices of the business, which Jobber alone answers for.
+    def invoices = Invoices.new account: self
   end
 end

data/lib/jbr/authorizing.rb

@@ -0,0 +1,43 @@
+module Jbr
+  # What the account class does before there are credentials: sends a Jobber user to authorize
+  # the app, and trades the code they come back with for a first set.
+  module Authorizing
+    # Where a Jobber user authorizes the app.
+    AUTHORIZE = 'https://api.getjobber.com/api/oauth/authorize'
+
+    # @param code [String] code Jobber sent to the redirect URI.
+    # @param redirect_uri [String] URI the code came back to.
+    # @return [Account] credentials for the account that authorized the app, its ID learned.
+    # @raise [Error] where Jobber will not take the code.
+    def create(code:, redirect_uri:)
+      credentials = post code: code, redirect_uri: redirect_uri, grant_type: 'authorization_code'
+      new(credentials).tap { |account| account.account_id = account.business.id }
+    end
+
+    # @param redirect_uri [String] where Jobber sends the user back to.
+    # @param state [String] what the app recognizes them by when they come back.
+    # @return [String] URL a Jobber user authorizes the app on.
+    def url_for(redirect_uri:, state:)
+      return Jbr.mock.oauth_url if Jbr.mocked?
+
+      uri = URI AUTHORIZE
+      uri.query = URI.encode_www_form redirect_uri: redirect_uri, state: state,
+        response_type: 'code', client_id: client_id
+      uri.to_s
+    end
+
+    # @return [String, nil] client ID the app is registered with Jobber as.
+    def client_id = ENV['JOBBER_CLIENT_ID']
+
+    # @return [String, nil] client secret the app proves itself to Jobber with.
+    def client_secret = ENV['JOBBER_CLIENT_SECRET']
+
+    # @param params [Hash] grant to exchange: a code, or a refresh token.
+    # @return [Hash] tokens Jobber answered, and the moment the access one expires.
+    def post(params = {})
+      return Mock::Account.post params if Jbr.mocked?
+
+      Token.post params.merge(client_id: client_id, client_secret: client_secret)
+    end
+  end
+end

data/lib/jbr/booking.rb

@@ -0,0 +1,56 @@
+module Jbr
+  # What a list of visits writes. Jobber files the stop booked to go and look at work as an
+  # assessment on the request it is opened with, so one mutation files the lead, the hour and
+  # the crew, and answers the stop as Jobber stored it rather than as it was asked for.
+  module Booking
+    # The mutation that opens a request with an assessment booked on it.
+    CREATE = <<~GRAPHQL
+      mutation($input: RequestCreateInput!) {
+        requestCreate(input: $input) {
+          request { id client { id } assessment { id title startAt endAt allDay } }
+          userErrors { message }
+        }
+      }
+    GRAPHQL
+
+    # Books a stop against the client answering to the phone and the property at the address,
+    # opening either where Jobber has none. Jobber has no source for a request, so that one is
+    # dropped, and it takes the hour in the technician's own words, so `starts_at:` must know
+    # the zone it is in: a bare Time names no zone and is refused.
+    # @return [Visit] stop as Jobber booked it, naming the lead it was booked against.
+    def create(name:, surname:, phone:, email:, address:, description:, notes:, source:,
+      starts_at:, ends_at:, technicians:)
+      booking = schedule starts_at, ends_at, technicians
+      customer = Customers.new(account: @account).find_or_create_by phone: phone, name: name,
+        surname: surname, email: email, address: address
+      property = Locations.new(account: @account).find_or_create_for customer, address
+      booked @account.query(CREATE, variables: { input: {
+        clientId: customer.id, propertyId: property, title: description,
+        assessment: { instructions: notes, schedule: booking },
+      } })
+    end
+
+  private
+
+    def booked(output)
+      request = output.dig 'requestCreate', 'request'
+      lead = { 'id' => request['id'], 'client' => request['client'] }
+      Visit.new node: request.fetch('assessment').merge('request' => lead)
+    end
+
+    def schedule(starts_at, ends_at, technicians)
+      { startAt: moment(starts_at), endAt: (moment(ends_at) if ends_at),
+        teamMemberIdsToAssign: technicians.map(&:id) }.compact
+    end
+
+    def moment(at)
+      { date: at.strftime('%Y-%m-%d'), time: at.strftime('%H:%M:%S'), timezone: zone_of(at) }
+    end
+
+    def zone_of(at)
+      return at.time_zone.tzinfo.name if at.respond_to? :time_zone
+
+      raise Error, "Jobber books #{at} in a named zone: hand over a Time.zone moment, not a Time"
+    end
+  end
+end

data/lib/jbr/collection.rb

@@ -0,0 +1,7 @@
+module Jbr
+  # A list of records read through the credentials, with what it was asked to bring back beside
+  # each record and what it was narrowed to.
+  class Collection < Company::Collection
+    include Reading
+  end
+end

data/lib/jbr/collections/customers.rb

@@ -0,0 +1,54 @@
+module Jbr
+  # The clients on a Jobber account, reached by phone and opened where none answers to it.
+  class Customers < Reader
+    # 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 { #{Location::ADDRESS} } } } }
+        } }
+      }
+    GRAPHQL
+
+    # The mutation that opens a client, with a first property where an address is given.
+    CREATE = <<~GRAPHQL
+      mutation($input: ClientCreateInput!) {
+        clientCreate(input: $input) {
+          client { id clientProperties(first: 1) { nodes { id address { #{Location::ADDRESS} } } } }
+          userErrors { message }
+        }
+      }
+    GRAPHQL
+
+    # Reach the client answering to a number, opening one with the rest where Jobber has none.
+    # @param phone [String] number to match on, and to file a new client under.
+    # @param name [String] what to call them.
+    # @param surname [String, nil] their surname.
+    # @param email [String, nil] address they are written to.
+    # @param address [Hash] any of :street, :city, :state and :zip, the first place on file.
+    # @return [Customer] the client, with the places on their file.
+    def find_or_create_by(phone:, name:, surname:, email:, address:)
+      find_by(phone) || create(phone:, name:, surname:, email:, address:)
+    end
+
+  private
+
+    def find_by(phone)
+      output = @account.query LOOKUP, variables: { searchTerm: phone }
+      recent = output.dig('clientPhones', 'nodes').to_a.max_by do |node|
+        node.dig('client', 'updatedAt') || ''
+      end
+      Customer.new node: recent['client'] if recent
+    end
+
+    def create(phone:, name:, surname:, email:, address:)
+      input = { firstName: name, lastName: surname,
+                phones: [ { number: phone, primary: true } ],
+                emails: ([ { address: email, primary: true } ] if email.present?),
+                properties: ([ { address: Locations.address_from(address) } ] if address.present?),
+      }.compact
+      output = @account.query CREATE, variables: { input: input }
+      Customer.new node: output.dig('clientCreate', 'client')
+    end
+  end
+end

data/lib/jbr/collections/invoices.rb

@@ -0,0 +1,18 @@
+module Jbr
+  # The invoices on a Jobber account, each reached by the ID Jobber files it under.
+  class Invoices < Reader
+    # 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
+
+    # @param id [String] Jobber ID of the invoice.
+    # @return [Invoice, nil] nil when Jobber has no invoice under that ID, or holds it as a draft.
+    def find(id)
+      node = @account.query(FIND, variables: { id: id })['invoice']
+      Invoice.new node: node if node && node['invoiceStatus'] != 'draft'
+    end
+  end
+end

data/lib/jbr/{jobs.rb → collections/jobs.rb}

@@ -1,30 +1,30 @@
 module Jbr
   # The jobs on a Jobber account, oldest first, walked a page at a time.
-  class Jobs < Resource
+  class Jobs < Collection
     include Includable, Listable
 
-    # 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 ' \
+    # What a job answers with wherever one is read, before anything it was asked to bring back
+    # with it. Written by hand where the vocabulary's keys would not do: the quote nests.
+    FIELDS = 'id title instructions total createdAt startAt completedAt ' \
              'quote { id amounts { total } }'
 
     # 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.
+    # @param id [String] 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']
+      node = @account.query(one, variables: { id: id })['job']
       Job.new node: node if node
     end
 
   private
 
-    def page = paged "#{FIELDS} #{selections}", PAGE
+    def page = paged row(FIELDS), PAGE
 
     def one
       <<~GRAPHQL
         query($id: EncodedId!) {
-          job(id: $id) { #{FIELDS} #{selections} }
+          job(id: $id) { #{row FIELDS} }
         }
       GRAPHQL
     end

data/lib/jbr/collections/leads.rb

@@ -0,0 +1,30 @@
+module Jbr
+  # The requests on a Jobber account's board: work somebody asked the business for.
+  class Leads < Company::Leads
+    # The mutation that opens a request against a client and a property.
+    CREATE = <<~GRAPHQL
+      mutation($input: RequestCreateInput!) {
+        requestCreate(input: $input) { request { id client { id } } userErrors { message } }
+      }
+    GRAPHQL
+
+    # @param account [Account] credentials to reach Jobber with.
+    def initialize(account:)
+      @account = account
+    end
+
+    # Files a request against the client answering to the phone and the property at the address,
+    # opening either where Jobber has none. The description is the request's title and the
+    # notes its instructions; Jobber has no source for a request, so that one is dropped.
+    # @return [Lead] the request, and the client it was opened against.
+    def create(name:, surname:, phone:, email:, address:, description:, notes:, source:)
+      customer = Customers.new(account: @account).find_or_create_by phone: phone,
+        name: name, surname: surname, email: email, address: address
+      location_id = Locations.new(account: @account).find_or_create_for customer, address
+      input = { clientId: customer.id, propertyId: location_id, title: description,
+                assessment: { instructions: notes }, }
+      output = @account.query CREATE, variables: { input: input }
+      Lead.new node: output.dig('requestCreate', 'request')
+    end
+  end
+end

data/lib/jbr/collections/locations.rb

@@ -0,0 +1,47 @@
+module Jbr
+  # The properties on a client's file, and the one a request is opened at.
+  class Locations < Reader
+    # The mutation that adds a property to a client already on file.
+    CREATE = <<~GRAPHQL
+      mutation($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 address as Jobber takes it, without the fields a caller left blank.
+    # @param fields [Hash] any of :street, :city, :state and :zip.
+    # @return [Hash] address, by Jobber's names.
+    def self.address_from(fields)
+      FIELDS.to_h { |jobber, ours| [ jobber, fields[ours] ] }.compact_blank
+    end
+
+    # Reach the property at an address on a client's file, adding one where none matches.
+    # @param customer [Customer] whose file, with the places already on it.
+    # @param address [Hash] any of :street, :city, :state and :zip.
+    # @return [String, nil] ID of the property, or nil where Jobber declined to add one.
+    def find_or_create_for(customer, address)
+      wanted = self.class.address_from address
+      match = customer.locations.find { |location| same_address? wanted, location }
+      match ? match.id : create(customer.id, wanted)
+    end
+
+  private
+
+    def create(client_id, address)
+      output = @account.query CREATE, variables: {
+        clientId: client_id, input: { properties: [ { address: address } ] },
+      }
+      output.dig 'propertyCreate', 'properties', 0, 'id'
+    end
+
+    def same_address?(wanted, location)
+      wanted[:street1] == location.street && wanted[:postalCode] == location.zip
+    end
+  end
+end

data/lib/jbr/collections/quotes.rb

@@ -0,0 +1,18 @@
+module Jbr
+  # The quotes on a Jobber account, each reached by the ID Jobber files it under.
+  class Quotes < Reader
+    # The query that reads one quote, what it comes to, and the request it came from.
+    FIND = <<~GRAPHQL
+      query($id: EncodedId!) {
+        quote(id: $id) { id amounts { total } request { id } }
+      }
+    GRAPHQL
+
+    # @param id [String] Jobber ID of the quote.
+    # @return [Quote, nil] nil when Jobber has no quote under that ID.
+    def find(id)
+      node = @account.query(FIND, variables: { id: id })['quote']
+      Quote.new node: node if node
+    end
+  end
+end

data/lib/jbr/collections/technicians.rb

@@ -0,0 +1,17 @@
+module Jbr
+  # The users on a Jobber account, walked a page at a time. Reading one at all needs the Users
+  # scope; narrowing a list to one does not.
+  class Technicians < Collection
+    include Listable
+
+  private
+
+    def page = paged Technician::FIELDS, PAGE
+
+    def field = 'users'
+
+    def filtered = 'UsersFilterAttributes'
+
+    def item(node) = Technician.new node: node
+  end
+end

data/lib/jbr/collections/visits.rb

@@ -0,0 +1,61 @@
+module Jbr
+  # The visits on a Jobber account: the stops of its jobs, and the assessments booked to go and
+  # look at work before there is a job. Jobber files both as scheduled items and refuses to list
+  # one without a window, so a list nothing narrowed has none to give and says so.
+  class Visits < Company::Visits
+    include Reading, Scheduled, Includable, Listable, Booking
+
+    # How far an open end reaches. Jobber's window takes two moments and no nil, so a caller
+    # who named no end gets a year of one, which is a schedule rather than an archive.
+    HORIZON = 1.year
+
+    # @param from [Time, nil] the moment the window opens, or nothing for as far back as there is.
+    # @param to [Time, nil] the moment the window closes, or nothing for as far ahead as there is.
+    # @return [Visits] the same list, narrowed to what the window holds.
+    def between(from, to)
+      now = Time.now
+      narrowed occursWithin: { startAt: (from || now - HORIZON).iso8601,
+                               endAt: (to || now + HORIZON).iso8601 },
+        includeUnassigned: true, includeUnscheduled: false
+    end
+
+    # Jobber narrows a schedule by who is on it, so the technician joins the window in the one
+    # filter and nobody else's work is answered, paged or paid for.
+    # @param technician [Company::Technician] whoever the work is booked for.
+    # @return [Visits] the same list, narrowed to what they are booked for.
+    # @note Needs no Users scope: Jobber narrows, and no user is selected to do it.
+    def assigned_to(technician) = narrowed(assignedTo: [ technician.id ])
+
+    # @return [Visits] the same list, narrowed to the stops of jobs, by Jobber rather than here.
+    def for_jobs = narrowed(scheduleItemType: 'VISIT')
+
+    # @return [Visits] the same list, narrowed to the assessments, by Jobber rather than here.
+    def for_leads = narrowed(scheduleItemType: 'ASSESSMENT')
+
+    # @yield [Visit] each visit in the window, oldest first.
+    def each(&)
+      windowed
+      super
+    end
+
+    # @return [Array<String>] every ID in the window, every page of them read.
+    def ids
+      windowed
+      super
+    end
+
+  private
+
+    def windowed
+      return if @filter&.key? :occursWithin
+
+      raise Error, 'A Jobber schedule is read by the window: ask between, upcoming or past'
+    end
+
+    def page = paged row(fields), PAGE
+
+    def field = 'scheduledItems'
+
+    def filtered = 'ScheduledItemsFilterAttributes!'
+  end
+end

data/lib/jbr/error.rb

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

data/lib/jbr/errors/throttled.rb

@@ -0,0 +1,6 @@
+module Jbr
+  # Jobber refusing a query over what it costs rather than over anything about the query. The
+  # bucket it is priced against refills, so the same question asked later is answered; the
+  # numbers it was refused with stay in the message.
+  Throttled = Class.new Company::Throttled
+end

data/lib/jbr/includable.rb

@@ -2,26 +2,28 @@ 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, :line_items, :property, or
-    #   property: :client for the client whose file the place sits on.
-    # @return [Resource] the same list, asking Jobber for those too.
+    # @param names [Array<Symbol, Hash>] :lines, :technicians, :location, or location: :customer
+    #   for whose place it is.
+    # @return [Collection] the same list, asking Jobber for those too.
+    # @note :technicians needs the Users scope, which refuses the whole query where it is unticked.
     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)
+      self.class.new account: @account, includes: @includes.merge(named), filter: @filter
     end
 
   private
 
-    # What the includes ask Jobber for, in its own words.
+    def row(fields) = [ fields, selections ].compact_blank.join ' '
+
     def selections = @includes.map { |name, nested| selection_of name, nested }.join ' '
 
     def selection_of(name, nested)
       case name
-        when :client then Cliental::SELECTION
-        when :line_items then LineItem::SELECTION
-        when :property then Properted.selection client: nested == :client
+        when :lines then Line::SELECTION
+        when :technicians then Technician::SELECTION
+        when :location then Location.selection customer: nested == :customer
       end
     end
   end