jbr 3.13.0 → 5.0.0

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/technician.rb

@@ -0,0 +1,19 @@
+module Jbr
+  # A person the business sends out, whom Jobber calls a user and whose name is a node of its
+  # own rather than two fields, so the vocabulary's keys would not fetch it.
+  class Technician < Company::Technician
+    # What Jobber answers a user with.
+    FIELDS = 'id name { first last }'
+
+    # What to ask for wherever a scheduled item names who it is booked for: ten, which is more
+    # than a stop is ever booked for. An app never granted the Users scope has the whole query
+    # refused rather than this field left empty, so nothing asks for it unbidden.
+    SELECTION = "assignedUsers(first: 10) { nodes { #{FIELDS} } }"
+
+    # @return [String, nil] what they go by: a given name.
+    def name = @node.dig :name, :first
+
+    # @return [String, nil] their surname.
+    def surname = @node.dig :name, :last
+  end
+end

data/lib/jbr/resources/visit.rb

@@ -0,0 +1,30 @@
+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
+
+    # Jobber calls the lead a request, and hangs the assessment booked to look at the work off
+    # it; a stop of a job names no request and a stop of a lead names no job.
+    # @return [Lead, nil] lead the stop belongs to, nil where the stop is a job's.
+    def lead = record Lead, :request
+
+    # Jobber hangs the property off each kind of scheduled item rather than off what they
+    # share, so it is asked for inside each and read back under Jobber's own name for it.
+    # @return [Location, nil] where the stop happens, where the query asked and Jobber has one.
+    def location = record Location, :property
+
+    # @return [Array<Technician>] whoever the stop is booked for, where the query asked.
+    def technicians = @node.dig(:assignedUsers, :nodes).to_a.map { Technician.new node: it }
+  end
+end

data/lib/jbr/scheduled.rb

@@ -0,0 +1,36 @@
+module Jbr
+  # What Jobber files as a scheduled item, and how a list of them is asked for. Which kinds count
+  # as booked time lives here, and so does the awkward part: a scheduled item names no property
+  # and no job, so where a stop is and what it was booked for hang off each kind rather than off
+  # what they share, and are selected inside the fragments.
+  module Scheduled
+    # What every kind answers with. Jobber has four of them -- a visit, an assessment, an event
+    # and a task -- and every one is an hour somebody is out, so no kind is read past. A reminder
+    # is named by the filter's enum but implements nothing here, and cannot come back.
+    SHARED = 'id title startAt endAt allDay'
+
+  private
+
+    def fields
+      [ SHARED, kind('Visit', 'clientConfirmed job { id }'),
+        kind('Assessment', 'clientConfirmed request { id }') ].join ' '
+    end
+
+    def kind(name, own) = "... on #{name} { #{[ own, located ].compact_blank.join ' '} }"
+
+    # Included before Includable so this is found first: a location asked for is selected inside
+    # each kind's fragment by `kind`, and must not also be appended to what they share, where
+    # Jobber has no property to answer with.
+    def selection_of(name, nested)
+      return if name == :location
+
+      super
+    end
+
+    def located
+      Location.selection customer: @includes[:location] == :customer if @includes.key? :location
+    end
+
+    def item(node) = Visit.new node: node
+  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.13.0'
+  VERSION = '5.0.0'
 end

data/lib/jbr.rb

@@ -1,68 +1,68 @@
 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. Two
+# more files of it: an address is sent without the fields a caller left blank, and a window
+# with no end reaches a year out.
+require 'company'
 require 'active_support/core_ext/enumerable'
-require 'active_support/core_ext/array/conversions'
+require 'active_support/core_ext/integer/time'
 
 require 'graphql/error'
 require 'graphql/unauthorized'
 require 'graphql/throttled'
 require 'graphql/client'
 
-require 'jbr/mock'
-
-require 'jbr/url'
+require 'jbr/version'
+require 'jbr/logger'
 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/querying'
+require 'jbr/authorizing'
+require 'jbr/mock'
+
+# 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/cliental'
-require 'jbr/named'
-require 'jbr/resource'
-require 'jbr/request'
-require 'jbr/oauth'
+require 'jbr/resources/customer'
+require 'jbr/resources/location'
+require 'jbr/resources/line'
+require 'jbr/resources/job'
+require 'jbr/resources/technician'
+require 'jbr/resources/visit'
+require 'jbr/resources/quote'
+require 'jbr/resources/invoice'
+require 'jbr/resources/lead'
 
-require 'jbr/account'
-# Property comes before Client and Visit: their queries read its fields as they load.
-require 'jbr/property'
-require 'jbr/properted'
+require 'jbr/reader'
+require 'jbr/reading'
+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/scheduled'
+require 'jbr/booking'
+require 'jbr/collections/jobs'
+require 'jbr/collections/visits'
+require 'jbr/collections/technicians'
+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/technicians'
+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.13.0
+  version: 5.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: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -110,48 +124,52 @@ 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/booking.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/technicians.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/logger.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/technicians.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/reading.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/technician.rb
+- lib/jbr/resources/visit.rb
+- lib/jbr/scheduled.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

data/lib/jbr/client.rb

@@ -1,98 +0,0 @@
-module Jbr
-  # A person a Jobber user works for, and the property the work happens at.
-  class Client < Resource
-    # 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 { #{Property::SELECTION} } }} }
-        } }
-      }
-    GRAPHQL
-
-    # 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 } } }
-          userErrors { message }
-        }
-      }
-    GRAPHQL
-
-    # @return [String, nil] the property the work happens at.
-    attr_reader :property_id
-
-    # @return [String, nil] what the client is called.
-    def first_name = @node['firstName']
-
-    def last_name = @node['lastName']
-
-    # @return [String, nil] the business the client is, where the client is a business.
-    def company_name = @node['companyName']
-
-    # Jobber files nobody without one name or the other, so there is always one to call them.
-    # @return [String, nil] the person's first name, or the business's name. Never empty.
-    def name = first_name.presence || company_name.presence
-
-    # @return [String, nil] the address to write to.
-    def email = @node['email']
-
-    # The number to reach them on, without its country code.
-    # @return [String, nil] ten digits, or nil where Jobber holds none we can dial.
-    def phone = Phone.from(@node['phones'])
-
-    # Create a client instance with the provided attributes.
-    # @return [Client] itself
-    # @param params [Hash] the attributes of the client
-    # @option params [String] :first_name the client’s first name
-    # @option params [String] :last_name the client’s last name
-    # @option params [String] :phone the client’s phone number
-    # @option params [<String, nil>] :email the client’s email address
-    def create_with(params = {})
-      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
-    end
-
-  private
-
-    def find_by_phone(phone)
-      output = @oauth.query LOOKUP, variables: { searchTerm: phone }
-      recent = (output.dig('clientPhones', 'nodes') || []).max_by do |clients|
-        clients.dig('client', 'updatedAt') || ''
-      end
-      return unless recent
-
-      @id = recent.dig 'client', 'id'
-      @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
-
-    def create
-      output = @oauth.query CREATE, variables: { input: input }
-      @id = output.dig 'clientCreate', 'client', 'id'
-
-      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: Property.address_from(address) } ] if address.present?),
-        phones: [ { number: @create_params[:phone], primary: true } ],
-        emails: ([ { address: email, primary: true } ] if email.present?),
-      }.compact
-    end
-  end
-end

data/lib/jbr/cliental.rb

@@ -1,14 +0,0 @@
-module Jbr
-  # Extends a record that names the client the work is for: a visit, a job, a property,
-  # anything Jobber files under somebody.
-  module Cliental
-    # What Jobber calls each field of that client.
-    FIELDS = %w[id firstName lastName companyName email]
-
-    # What to ask for wherever a record names its client.
-    SELECTION = "client { #{FIELDS.join ' '} #{Phone::SELECTION} }"
-
-    # @return [Client] who the work is for.
-    def client = Client.new node: @node.fetch('client', {})
-  end
-end

data/lib/jbr/invoice.rb

@@ -1,43 +0,0 @@
-module Jbr
-  # A bill a Jobber user issued for finished work.
-  class Invoice < Resource
-    # 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']
-      return if invoice['invoiceStatus'].eql? 'draft'
-
-      @id = invoice['id']
-      @total = invoice['total']
-      @issued_at = invoice['issuedDate']
-
-      job = invoice.dig('jobs', 'nodes', 0) || {}
-      @job_id = job['id']
-      @completed_at = job['completedAt']
-
-      self
-    end
-
-    # @return [Date] the invoice issued time
-    def issued_at
-      Time.iso8601(@issued_at) if @issued_at
-    end
-
-    # @return [Time] the job completed time
-    def completed_at
-      Time.iso8601(@completed_at) if @completed_at
-    end
-  end
-end

data/lib/jbr/itemized.rb

@@ -1,9 +0,0 @@
-module Jbr
-  # Extends a record Jobber itemizes: a job, whose lines say what the work actually was
-  # where the title only says what somebody called it.
-  module Itemized
-    # @return [Array<LineItem>] the lines the record is made of, empty where the query never
-    #   asked for them — a page costs what it carries, so nothing nested arrives unasked.
-    def line_items = LineItem.from @node.dig('lineItems', 'nodes')
-  end
-end

data/lib/jbr/job.rb

@@ -1,40 +0,0 @@
-module Jbr
-  # Work a Jobber user accepted and scheduled.
-  class Job < Resource
-    include Cliental, Itemized, Named, Properted
-
-    # @return [String, nil] what the job is called, where whoever opened it named it.
-    def title = @node['title']
-
-    # @return [String, nil] what the work is, in the words whoever opened the job wrote.
-    def instructions = @node['instructions']
-
-    # What the job's lines add up to, each as how many of what: `3 Faucet install and 2 Valve
-    # change` — `to_sentence` reading each line's own string form. The lines say what the work
-    # was where a title only says what it was called, so this reads better than one, and falls
-    # back to {#name} where the job has no lines or the query never asked for them.
-    # @return [String] the lines as a sentence, or the title, or the ID. Never nil, never empty.
-    def summary = line_items.to_sentence.presence || name
-
-    # @return [String, nil] where Jobber files the job in its own workflow.
-    def status = @node['jobStatus']
-
-    # @return [String, nil] the ID of the quote the job was won with.
-    def quote_id = @node.dig 'quote', 'id'
-
-    # @return [Float, nil] what the job comes to.
-    def total = @node['total']
-
-    # @return [Float, nil] what the quote the job was won with came to.
-    def quote_total = @node.dig 'quote', 'amounts', 'total'
-
-    # @return [Time, nil] the job opening time
-    def created_at = time 'createdAt'
-
-    # @return [Time, nil] the job scheduled time
-    def scheduled_at = time 'startAt'
-
-    # @return [Time, nil] the job completed time
-    def completed_at = time 'completedAt'
-  end
-end

data/lib/jbr/line_item.rb

@@ -1,44 +0,0 @@
-module Jbr
-  # One line of the work a job is made of: how many of a thing, what it is called,
-  # what it says, and what it comes to.
-  class LineItem < Resource
-    # What Jobber calls each field of a line. The ID reads through {Resource#id}, so an app
-    # can tell a line it has seen before from a new one.
-    FIELDS = %w[id quantity name description 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 { #{FIELDS.join ' '} } }"
-
-    # @param nodes [Array<Hash>, nil] the lines as Jobber answered them, if it answered any.
-    # @return [Array<LineItem>] one per line, in the order Jobber holds them.
-    def self.from(nodes) = nodes.to_a.map { |node| new node: node }
-
-    # @return [Integer, Float, nil] how many of it the job is for.
-    def quantity = whole @node['quantity']
-
-    # @return [String, nil] what the line is called.
-    def name = @node['name']
-
-    # @return [String, nil] what the line says, beyond what it is called.
-    def description = @node['description']
-
-    # @return [Float, nil] what the line comes to — what Jobber calls `totalPrice`.
-    def amount = @node['totalPrice']
-
-    # @return [String] how many of what: `3 Bathroom Faucet Installation`, and the name alone
-    #   where Jobber holds no quantity for the line.
-    def to_s = [ quantity, name ].compact.join ' '
-
-  private
-
-    # Jobber answers every quantity as a Float, and a whole one reads as an Integer:
-    # `3 Faucets` rather than `3.0 Faucets`. A fraction keeps its point — `3.5 Faucets` —
-    # since rounding it would lie about what was billed.
-    def whole(number) = number && ((number % 1).zero? ? number.to_i : number)
-  end
-end

data/lib/jbr/mock/client.rb

@@ -1,17 +0,0 @@
-module Jbr
-  # A client that reads from {Jbr.mock} instead of Jobber.
-  class Mock::Client < Client
-    # @return [Object, nil] the values the app asked for.
-    def id = @node[:id]
-
-    def first_name = @node[:first_name]
-
-    def last_name = @node[:last_name]
-
-    def company_name = @node[:company_name]
-
-    def email = @node[:email]
-
-    def phone = @node[:phone]
-  end
-end