hcp 1.4.0 → 3.0.0

data/lib/hcp/collections/leads.rb

@@ -0,0 +1,25 @@
+module Hcp
+  # The leads of one location: who asked a Housecall Pro user for work, before there is a job.
+  class Leads < Company::Leads
+    # @param client [Client] how to reach Housecall Pro as the location.
+    def initialize(client:)
+      @client = client
+    end
+
+    # Opens a lead, and a customer with it, on Housecall Pro. A lead has no title of its own, so
+    # the description heads the note and the notes follow it.
+    # @return [Lead] lead as Housecall Pro filed it, with its customer's ID beside it.
+    def create(name:, surname:, phone:, email:, address:, description:, notes:, source:)
+      customer = { first_name: name, last_name: surname, email: email, mobile_number: phone,
+                   lead_source: source, }
+      body = { customer: customer.compact_blank, address: address, lead_source: source,
+               note: [ description, notes ].compact_blank.join("\n"), }
+      Lead.new node: @client.post('leads', body.compact_blank), client: @client
+    end
+
+    # Reaches the network for nothing: the lead is named, and moved once it is asked to be.
+    # @param id [String] ID Housecall Pro files the lead under.
+    # @return [Lead] the lead, able to move through the pipeline.
+    def find(id) = Lead.new node: { id: id }, client: @client
+  end
+end

data/lib/hcp/collections/technicians.rb

@@ -0,0 +1,23 @@
+module Hcp
+  # The employees of one location, walked a page at a time. Housecall Pro lists the active
+  # ones and no others, so a crew that has left the business is not among them.
+  class Technicians < Company::Collection
+    # Employees a page: the most Housecall Pro answers with, and more than it refuses.
+    PAGE = 200
+
+    # @param client [Client] how to reach Housecall Pro as the location.
+    def initialize(client:)
+      @client = client
+    end
+
+    # Nothing is read until the walk starts, and a page only once the one before it runs out.
+    # @yield [Technician] each employee, in the order Housecall Pro lists them.
+    def each
+      (1..).each do |page|
+        body = @client.get 'employees', page: page, page_size: PAGE
+        body.fetch('employees').each { |node| yield Technician.new node: node }
+        break if page >= body.fetch('total_pages')
+      end
+    end
+  end
+end

data/lib/hcp/collections/visits.rb

@@ -0,0 +1,80 @@
+module Hcp
+  # The visits of one location: the appointments Housecall Pro files inside jobs, and the slot
+  # it files on each estimate. They are read off the work booked across a window, a page of it
+  # at a time, and each kind costs a list of its own.
+  class Visits < Company::Visits
+    # @param client [Client] how to reach Housecall Pro as the location.
+    # @param from [Time, nil] the moment the window opens, or nothing for every visit there was.
+    # @param to [Time, nil] the moment the window closes, or nothing for every visit to come.
+    # @param technician [Company::Technician, nil] whose work to ask for, or nothing for all.
+    # @param jobs [Boolean] whether to read the stops of jobs.
+    # @param leads [Boolean] whether to read the stops of estimates.
+    def initialize(client:, from: nil, to: nil, technician: nil, jobs: true, leads: true)
+      @client = client
+      @from = from
+      @to = to
+      @technician = technician
+      @jobs = jobs
+      @leads = leads
+    end
+
+    # @param from [Time, nil] the moment the window opens, or nothing for every visit there was.
+    # @param to [Time, nil] the moment the window closes, or nothing for every visit to come.
+    # @return [Visits] the same list, narrowed to the visits booked to start between the two.
+    def between(from, to) = with from: from, to: to
+
+    # Housecall Pro narrows both lists by who is assigned to the work, so the window is asked
+    # for as this technician's; a job's stop is the whole crew's until somebody is dispatched
+    # to it, so the stops they are not on are let go once the work comes back.
+    # @param technician [Company::Technician] whoever the work is booked for.
+    # @return [Company::Selection] the same list, narrowed to the stops they are booked for.
+    def assigned_to(technician)
+      theirs = with technician: technician
+      Company::Selection.new(collection: theirs) do |visit|
+        visit.technicians.any? { |each| each.id == technician.id }
+      end
+    end
+
+    # @return [Visits] the same list, read off the jobs alone: one request rather than two.
+    def for_jobs = with leads: false
+
+    # @return [Visits] the same list, read off the estimates alone: one request rather than two.
+    def for_leads = with jobs: false
+
+    # Work booked across the window carries every stop in it, so each list is read once and
+    # what was called off keeps its stops to itself.
+    # @yield [Visit] each visit in the window, the jobs' stops before the estimates'.
+    def each(&)
+      jobs.each { |job| stops job, & } if @jobs
+      estimates.each { |estimate| stops estimate, & } if @leads
+    end
+
+  private
+
+    def with(**changed)
+      self.class.new(**{ client: @client, from: @from, to: @to, technician: @technician,
+                         jobs: @jobs, leads: @leads }.merge(changed))
+    end
+
+    def stops(work)
+      return if work.canceled?
+
+      work.visits.each { |visit| yield visit if window.cover? visit.starts_at }
+    end
+
+    def window = @from..@to
+
+    def crew = { employee_ids: (@technician && [ @technician.id ]) }
+
+    def jobs
+      bounds = { scheduled_end_min: @from&.utc&.iso8601, scheduled_start_max: @to&.utc&.iso8601 }
+      params = bounds.merge(crew).compact.merge expand: [ 'appointments' ]
+      Jobs.new client: @client, params: params
+    end
+
+    def estimates
+      bounds = { scheduled_start_min: @from&.utc&.iso8601, scheduled_start_max: @to&.utc&.iso8601 }
+      Estimates.new client: @client, params: bounds.merge(crew).compact
+    end
+  end
+end

data/lib/hcp/error.rb

@@ -1,4 +1,4 @@
 module Hcp
   # Raised where Housecall Pro would not answer.
-  Error = Class.new StandardError
+  Error = Class.new Company::Error
 end

data/lib/hcp/errors/throttled.rb

@@ -0,0 +1,4 @@
+module Hcp
+  # Raised where Housecall Pro refuses a request for rate, and answers it again a little later.
+  Throttled = Class.new Company::Throttled
+end

data/lib/hcp/event.rb

@@ -8,13 +8,10 @@ module Hcp
     TIMESTAMP_HEADER = 'Api-Timestamp'
 
     # @param params [Hash] the payload for an event webhook.
-    def initialize(params = {})
+    def initialize(params)
       @params = params
     end
 
-    # @return [Symbol] the type of event, e.g.: :lead_converted, :job_created, :invoice_sent.
-    def type = @params.fetch(:event, '').gsub('.', '_').to_sym
-
     # @return [String] unique identifier of the lead in a :lead_converted event.
     def lead_id = @params.dig :lead, :id
 
@@ -50,10 +47,8 @@ module Hcp
 
   private
 
-    # @return [Hash] the latest conversion, applies to 'lead.converted' events.
     def conversion = @params.dig(:lead, :conversions).last
 
-    # @return [Symbol] the type of resource affected by the event, can be :lead or :job.
     def resource_type = @params[:event].split('.').first.to_sym
   end
 end

data/lib/hcp/resources/business.rb

@@ -0,0 +1,11 @@
+module Hcp
+  # The business behind a key: the account, or one location of a franchise.
+  class Business < Company::Business
+    # The node keys Housecall Pro spells otherwise than the vocabulary.
+    def self.keys = { phone: :phone_number }
+
+  private
+
+    def below = records Business, :locations
+  end
+end

data/lib/hcp/resources/customer.rb

@@ -1,52 +1,16 @@
 module Hcp
   # Whoever the work is for.
-  class Customer < Resource
-    extend Queryable
-    include Named, Timestamped
+  class Customer < Company::Customer
+    # The node keys Housecall Pro spells otherwise than the vocabulary.
+    def self.keys = { name: :first_name, surname: :last_name }
 
-    # A customer is narrowed by one free-text search rather than by named fields.
-    FILTERS = { q: %i[q], location_ids: %i[location_ids] }
+    # The numbers Housecall Pro holds for a customer, the one they are reached on first.
+    NUMBERS = %i[mobile_number home_number work_number]
 
-    # The conditions Housecall Pro takes more than one of, and refuses one of.
-    MANY = %i[location_ids]
+    # @return [String, nil] first name, or the business's name where a person has none.
+    def name = super.presence || attribute(:company).presence
 
-    # What Housecall Pro will put a list of customers in order of.
-    SORTS = %i[created_at updated_at]
-
-    # What a customer brings back beside themselves where they are asked to.
-    EXPANDS = %i[attachments do_not_service]
-
-    # Where Housecall Pro keeps them.
-    def self.path = 'customers'
-
-    # What Housecall Pro calls a page of them.
-    def self.key = 'customers'
-
-    attribute :first_name
-    attribute :last_name
-    attribute :email
-
-    # @return [String, nil] the business the customer is, where they are one.
-    attribute :company
-
-    # @return [String, nil] where the customer came from.
-    attribute :lead_source
-
-
-    # Housecall Pro holds three numbers, and a caller wants whichever one there is.
-    # @return [String, nil] the number the customer is reached on first.
-    def phone = @node['mobile_number'] || @node['home_number'] || @node['work_number']
-
-    # @return [Symbol, nil] :homeowner, or whatever else Housecall Pro takes the customer for.
-    def kind = @node['kind']&.to_sym
-
-    # @return [Boolean] whether the customer agreed to hear from the pro.
-    def notifications_enabled? = @node['notifications_enabled']
-
-    # @return [Array<String>] what the customer is tagged with.
-    def tags = Array(@node['tags'])
-
-    # @return [Relation] every address the customer is billed or served at.
-    def addresses = nested Address, 'addresses'
+    # @return [String, nil] ten digits they are reached on, nil where none can be dialed.
+    def phone = NUMBERS.lazy.filter_map { |number| Company::Phone.from @node[number] }.first
   end
 end

data/lib/hcp/resources/estimate.rb

@@ -1,49 +1,43 @@
 module Hcp
-  # Work a Housecall Pro user offered to do, priced as one option or several.
-  class Estimate < Resource
-    extend Queryable
-    include Scheduled, Statused, Timestamped
-
-    # What a list of estimates may be narrowed by, against the parameters Housecall Pro takes.
-    FILTERS = {
-      scheduled_at: %i[scheduled_start_min scheduled_start_max],
-      ends_at: %i[scheduled_end_min scheduled_end_max],
-      customer_id: %i[customer_id],
-      employee_ids: %i[employee_ids],
-      work_status: %i[work_status],
-      location_ids: %i[location_ids],
-    }
-
-    # The conditions Housecall Pro takes more than one of, and refuses one of.
-    MANY = %i[employee_ids work_status location_ids]
-
-    # What Housecall Pro will put a list of estimates in order of.
-    SORTS = %i[created_at updated_at id]
-
-    # What an estimate brings back beside itself where it is asked to.
-    EXPANDS = %i[attachments]
-
-    # Where Housecall Pro keeps them.
-    def self.path = 'estimates'
-
-    # What Housecall Pro calls a page of them.
-    def self.key = 'estimates'
-
-    attribute :estimate_number
-
-    # @return [String, nil] where the work came from.
-    attribute :lead_source
-
-    # @return [Customer, nil] whose estimate it is.
-    def customer = record Customer, 'customer'
-
-    # @return [Address, nil] where the work would happen.
-    def address = record Address, 'address'
-
-    # @return [Array<Employee>] the pros the estimate is assigned to.
-    def assigned_employees = records Employee, 'assigned_employees'
-
-    # @return [Array<Estimate::Option>] what the customer was offered, priced.
-    def options = records Estimate::Option, 'options'
+  # Work a Housecall Pro user was asked to look at and price, which the vocabulary reads as the
+  # lead it is: a stop to go and see it, before there is a job. Housecall Pro schedules it the
+  # way it schedules a job but hangs no appointments under it, so it holds the one slot.
+  class Estimate < Company::Lead
+    # @return [Customer, nil] customer the estimate was opened for.
+    def customer = record Customer, :customer
+
+    # Housecall Pro files the address and the customer side by side, the way it does on a job.
+    # @return [Location, nil] where the work would happen, nil where it is booked nowhere.
+    def location
+      address = @node[:address]
+      Location.new node: address.merge(customer: @node[:customer]) if address[:id].present?
+    end
+
+    # @return [Array<Technician>] employees the estimate is assigned to.
+    def technicians = records Technician, :assigned_employees
+
+    # Housecall Pro gives an estimate no words of its own: what it says is said by its options.
+    # @return [nil] nothing, so a stop of one goes undescribed.
+    def description = nil
+
+    # Housecall Pro files no ID on the slot, there being only ever the one, so it answers to
+    # the estimate's own.
+    # @return [Array<Visit>] the one slot the estimate is booked for, empty where it has none.
+    def visits
+      booked = @node.dig :schedule, :scheduled_start
+      return [] if booked.blank?
+
+      [ Visit.new(node: slot, lead: self) ]
+    end
+
+    # @return [Boolean] whether the customer or the pro called the estimate off.
+    def canceled? = attribute(:work_status).to_s.end_with? 'canceled'
+
+  private
+
+    def slot
+      { id: id, start_time: @node.dig(:schedule, :scheduled_start),
+        end_time: @node.dig(:schedule, :scheduled_end) }
+    end
   end
 end

data/lib/hcp/resources/job.rb

@@ -1,73 +1,62 @@
 module Hcp
   # Work a Housecall Pro user accepted: what it is, who it is for, and what it comes to.
-  class Job < Resource
-    extend Queryable
-    include Scheduled, Statused, Timestamped
-
-    # What a list of jobs may be narrowed by, against the parameters Housecall Pro takes.
-    FILTERS = {
-      scheduled_at: %i[scheduled_start_min scheduled_start_max],
-      ends_at: %i[scheduled_end_min scheduled_end_max],
-      customer_id: %i[customer_id],
-      employee_ids: %i[employee_ids],
-      work_status: %i[work_status],
-      location_ids: %i[location_ids],
-    }
-
-    # The conditions Housecall Pro takes more than one of, and refuses one of.
-    MANY = %i[employee_ids work_status location_ids]
-
-    # What Housecall Pro will put a list of jobs in order of.
-    SORTS = %i[created_at updated_at invoice_number id description work_status]
-
-    # What a job brings back beside itself where it is asked to.
-    EXPANDS = %i[attachments appointments]
-
-    # Where Housecall Pro keeps them.
-    def self.path = 'jobs'
-
-    # What Housecall Pro calls a page of them.
-    def self.key = 'jobs'
-
-    attribute :invoice_number
-    attribute :description
-    attribute :lead_source
-
-    # @return [String, nil] the ID of the estimate the job was won with.
-    attribute :original_estimate_id
-
-    amount :subtotal
-    amount :total_amount
-    amount :outstanding_balance
-
-    # @return [Time, nil] when the job was locked against further changes.
-    timestamp :locked_at
-
-    # @return [Time, nil] when the customer canceled the job.
-    timestamp :canceled_at
-
-    # @return [Array<String>] what the job is tagged with.
-    def tags = Array(@node['tags'])
-
-    # @return [Customer, nil] whose job it is.
-    def customer = record Customer, 'customer'
-
-    # @return [Address, nil] where the work happens.
-    def address = record Address, 'address'
-
-    # @return [Array<Note>] what the pros wrote on the job.
-    def notes = records Note, 'notes'
-
-    # @return [Array<Employee>] the pros the job is assigned to.
-    def assigned_employees = records Employee, 'assigned_employees'
-
-    # @return [Relation] the visits the job is booked for.
-    def appointments = nested Job::Appointment, 'appointments'
-
-    # @return [Relation] what the job is billed as.
-    def line_items = nested LineItem, 'line_items'
-
-    # @return [Relation] the invoices raised for the job.
-    def invoices = nested Job::Invoice, 'invoices'
+  class Job < Company::Job
+    # The node keys Housecall Pro spells otherwise than the vocabulary.
+    def self.keys = { amount: :total_amount }
+
+    # Housecall Pro nests when the work is booked and when it was done, and files the address
+    # and the customer side by side; the node is read flat, the way the vocabulary reads one.
+    # @param node [Hash] job as Housecall Pro answered it.
+    # @param client [Client] how to reach Housecall Pro for what the job holds elsewhere.
+    def initialize(node: {}, client:)
+      node = node.with_indifferent_access
+      super node: node.merge(scheduled_at: node.dig(:schedule, :scheduled_start),
+        completed_at: node.dig(:work_timestamps, :completed_at), location: location_from(node))
+      @client = client
+    end
+
+    # Housecall Pro files the notes on a job one by one, which read as a list, one to a line.
+    # @return [String, nil] every note's content, `- ` before each, nil where none was written.
+    def notes = Array(super).map { |note| "- #{note[:content]}" }.join("\n").presence
+
+    # Housecall Pro counts in cents, and a caller reads dollars.
+    # @return [BigDecimal, nil] what the job comes to.
+    def amount = (cents = super) && cents / 100
+
+    # Housecall Pro files a job's lines under their own endpoint rather than beside the job,
+    # so they are read once, on the first ask.
+    # @return [Array<Line>] lines the job is billed as.
+    def lines
+      @lines ||= @client.get("jobs/#{id}/line_items").fetch('data').map { Line.new node: it }
+    end
+
+    # @return [Location, nil] where the work happens, nil where the job is booked nowhere.
+    def location = record Location, :location
+
+    # Housecall Pro nests the appointments under the schedule, and only where the list was
+    # asked to bring them.
+    # @return [Array<Visit>] stops the job is booked as, empty where none came back.
+    def visits = Array(@node.dig :schedule, :appointments).map { Visit.new node: it, job: self }
+
+    # @return [Array<Technician>] employees the job is assigned to, empty where it is assigned
+    #   to nobody.
+    def technicians = records Technician, :assigned_employees
+
+    # @return [Boolean] whether the customer or the pro called the job off.
+    def canceled? = attribute(:work_status).to_s.end_with? 'canceled'
+
+    # Housecall Pro names the estimate option a job was created from beside the job, and the
+    # option is priced among the customer's estimates, so the quote takes the customer along.
+    # @return [Quote, nil] option the job was won with, nil where it was won without one.
+    def quote
+      option_id = @node[:original_estimate_id]
+      Quote.new node: { id: option_id, customer: @node[:customer] }, client: @client if option_id
+    end
+
+  private
+
+    def location_from(node)
+      node[:address].merge customer: node[:customer] if node.dig(:address, :id).present?
+    end
   end
 end

data/lib/hcp/resources/lead.rb

@@ -0,0 +1,26 @@
+module Hcp
+  # Somebody who asked a Housecall Pro user for work, and where they sit in the pipeline.
+  class Lead < Company::Lead
+    # @param node [Hash] lead as Housecall Pro answered it.
+    # @param client [Client] how to reach Housecall Pro as the lead's location.
+    def initialize(node: {}, client:)
+      super node: node
+      @client = client
+    end
+
+    # Moves the lead to the status going by this name. Housecall Pro moves a lead by status ID
+    # and names them only by their words, so the status is looked up first.
+    # @param status_name [String] status as the account names it, such as 'Won'.
+    def update(status_name:)
+      status = statuses.find { |each| each['name'] == status_name } || unknown(status_name)
+      @client.put 'pipeline/statuses',
+        resource_type: 'lead', resource_id: id, status_id: status['id']
+    end
+
+  private
+
+    def statuses = @client.get('pipeline/statuses', resource_type: 'lead').fetch 'statuses'
+
+    def unknown(name) = raise Error, "Status #{name} not found for lead #{id}"
+  end
+end

data/lib/hcp/resources/line.rb

@@ -0,0 +1,8 @@
+module Hcp
+  # One line of what a job comes to.
+  class Line < Company::Line
+    # Housecall Pro counts in cents, and a caller reads dollars.
+    # @return [BigDecimal, nil] what the line comes to.
+    def amount = (cents = super) && cents / 100
+  end
+end

data/lib/hcp/resources/location.rb

@@ -0,0 +1,7 @@
+module Hcp
+  # Where the work happens: the address Housecall Pro books a job at.
+  class Location < Company::Location
+    # @return [Customer, nil] whose place it is, as Housecall Pro filed them beside the job.
+    def customer = record Customer, :customer
+  end
+end

data/lib/hcp/resources/quote.rb

@@ -0,0 +1,28 @@
+module Hcp
+  # A price a Housecall Pro user sent, which Housecall Pro calls an estimate option: a job names
+  # the option it was created from, and an estimate holds one option or several.
+  class Quote < Company::Quote
+    # @param node [Hash] option as Housecall Pro named it beside a job: its ID, and the customer.
+    # @param client [Client] how to reach Housecall Pro for the rest of it.
+    def initialize(node: {}, client:)
+      super node: node
+      @client = client
+    end
+
+    # Housecall Pro reads an estimate by its own ID and not by an option's, so the option is
+    # found among the customer's estimates, read once on the first ask.
+    # @return [BigDecimal, nil] what the option comes to in dollars, nil where none is found.
+    def amount = option && BigDecimal(option['total_amount'].to_s) / 100
+
+  private
+
+    def option = options.find { |each| each['id'] == id }
+
+    def options = estimates.flat_map { |estimate| estimate['options'] }
+
+    def estimates
+      @estimates ||= @client.get('estimates', customer_id: @node.dig(:customer, :id),
+        page_size: Jobs::PAGE).fetch 'estimates'
+    end
+  end
+end

data/lib/hcp/resources/technician.rb

@@ -0,0 +1,7 @@
+module Hcp
+  # A person the business sends out, whom Housecall Pro calls an employee.
+  class Technician < Company::Technician
+    # The node keys Housecall Pro spells otherwise than the vocabulary.
+    def self.keys = { name: :first_name, surname: :last_name }
+  end
+end

data/lib/hcp/resources/visit.rb

@@ -0,0 +1,45 @@
+module Hcp
+  # One stop, which Housecall Pro hangs under a job as an appointment and under an estimate as
+  # the estimate's own slot: it happens where the work does and says what the work says.
+  class Visit < Company::Visit
+    # The node keys Housecall Pro spells otherwise than the vocabulary.
+    def self.keys = { starts_at: :start_time, ends_at: :end_time }
+
+    # @param node [Hash] slot as Housecall Pro answered it under the work it belongs to.
+    # @param job [Job, nil] job the slot sits under, nil where an estimate does.
+    # @param lead [Estimate, nil] estimate the slot sits under, nil where a job does.
+    def initialize(node: {}, job: nil, lead: nil)
+      super node: node
+      @job = job
+      @lead = lead
+    end
+
+    # @return [Job, nil] job the stop belongs to, nil where the stop is an estimate's.
+    attr_reader :job
+
+    # @return [Estimate, nil] estimate the stop belongs to, nil where the stop is a job's.
+    attr_reader :lead
+
+    # @return [String, nil] what the work is called: a stop has no words of its own.
+    def description = work.description
+
+    # An appointment has no address of its own and an estimate's slot is the estimate's, so a
+    # stop is where its work is.
+    # @return [Location, nil] where the stop happens, nil where the work is booked nowhere.
+    def location = work.location
+
+    # Housecall Pro dispatches a job's stop to some of its crew, or to none of it, and a stop
+    # dispatched to nobody is the whole crew's. An estimate dispatches nothing and has one crew.
+    # @return [Array<Technician>] whoever the stop is booked for.
+    def technicians = dispatched.presence || work.technicians
+
+  private
+
+    def work = @job || @lead
+
+    def dispatched
+      ids = Array attribute(:dispatched_employees_ids)
+      work.technicians.select { |technician| ids.include? technician.id }
+    end
+  end
+end

data/lib/hcp/version.rb

@@ -1,5 +1,5 @@
-# Ruby client for the Housecall Pro API.
+# The Housecall Pro API, answered in the vocabulary of the company gem.
 module Hcp
-  # Current version of the gem.
-  VERSION = '1.4.0'
+  # The version of this gem, as RubyGems knows it.
+  VERSION = '3.0.0'
 end