hcp 1.2.4 → 1.4.0

data/lib/hcp/lead.rb

@@ -1,6 +1,9 @@
 module Hcp
-  class Lead < Resource
-    attr_reader :customer_id
+  # Somebody who asked a Housecall Pro user for work, before there is a job.
+  class Lead
+    include Keyed
+
+    attr_reader :id, :customer_id
 
     def initialize(id: nil, customer_id: nil, key:, company_id:)
       @id = id
@@ -9,6 +12,8 @@ module Hcp
       @customer_id = customer_id
     end
 
+    # Opens the lead on Housecall Pro, and keeps what it filed the lead and customer under.
+    # @param params [Hash] :name, :email, :phone, :address, :note and :source.
     def create(params = {})
       response = Net::HTTP.post uri, lead_for(params).to_json, headers
       raise Error, response.body unless response.is_a? Net::HTTPSuccess
@@ -18,10 +23,12 @@ module Hcp
       raise Error, error
     end
 
+  private
+
     def lead_for(params = {})
       {
         customer: customer_for(params), address: params[:address],
-        lead_source: params[:source], note: params[:note]
+        lead_source: params[:source], note: params[:note],
       }.compact_blank
     end
 

data/lib/hcp/relation.rb

@@ -0,0 +1,76 @@
+module Hcp
+  # Every record of one kind a Housecall Pro account holds, walked a page at a time.
+  class Relation
+    include Chainable, Enumerable
+
+    # Records a page: the most Housecall Pro answers with, and more than it refuses.
+    PAGE = 200
+
+    # @param type [Class] what each record is read as.
+    # @param path [String] where Housecall Pro keeps them, under the host.
+    # @param company_id [String, nil] the location to read them as.
+    def initialize(type:, path: nil, company_id: nil, conditions: {}, sorts: {}, limit: nil,
+      expands: [])
+      @type = type
+      @path = path || type.path
+      @company_id = company_id
+      @conditions = conditions
+      @sorts = sorts
+      @limit = limit
+      @expands = expands
+    end
+
+    # Nothing is read until the walk starts, and a page only once the one before it runs out.
+    # @return [Enumerator, Relation] every record the list holds, or the list once walked.
+    def each(&block)
+      return walk unless block
+
+      walk.each(&block)
+      self
+    end
+
+    # Shadows Enumerable#find the way Active Record does: a record is reached by the ID
+    # Housecall Pro files it under, not by asking every record whether it is the one.
+    # @param id [String] the Housecall Pro ID.
+    # @return [Resource] the record, raising Hcp::NotFound where there is none.
+    def find(id) = record_for read("#{@path}/#{id}")
+
+    # A page of one carries the total beside it, so this is one small read however long the
+    # list is.
+    # @return [Integer] how many records the list holds.
+    def count = @count ||= [ read(@path, page_size: 1)['total_items'], @limit ].compact.min
+
+  private
+
+    def walk
+      Enumerator.new do |yielder|
+        seen = 0
+        (1..).each do |page|
+          body = read @path, page: page, page_size: [ @limit, PAGE ].compact.min
+          body.fetch(@type.key).each do |node|
+            yielder << record_for(node)
+            break if (seen += 1) == @limit
+          end
+          break if seen == @limit || page >= body.fetch('total_pages', page)
+        end
+      end
+    end
+
+    def read(path, paging = {})
+      Request.new(path: path, params: params.merge(paging), company_id: @company_id).body
+    end
+
+    def params
+      @conditions.flat_map { |name, value| filter(name, value).to_a }.to_h.
+        merge sort_by: @sorts.keys.first, sort_direction: @sorts.values.first,
+          expand: @expands.presence
+    end
+
+    def filter(name, value)
+      bounds = @type.filters.fetch name
+      Filter.new(bounds: bounds, value: @type.many.include?(name) ? Array(value) : value).params
+    end
+
+    def record_for(node) = @type.new node: node, company_id: @company_id
+  end
+end

data/lib/hcp/request.rb

@@ -0,0 +1,31 @@
+module Hcp
+  # One read from Housecall Pro.
+  class Request
+    # Where Housecall Pro answers.
+    HOST = 'https://api.housecallpro.com'
+
+    # @param path [String] what to read, under the host.
+    # @param params [Hash] the query to read it with.
+    # @param company_id [String, nil] the location to read it as.
+    def initialize(path:, params: {}, company_id: nil)
+      @path = path
+      @params = params
+      @company_id = company_id
+    end
+
+    # @return [Hash] what Housecall Pro answered.
+    def body = Answer.new(Net::HTTP.get_response(uri, headers)).body
+
+  private
+
+    def uri = URI [ "#{HOST}/#{@path}", @params.compact.to_query ].compact_blank.join '?'
+
+    def headers
+      {
+        'Authorization' => "Token #{Hcp.key}",
+        'Content-Type' => 'application/json',
+        'X-Company-Id' => @company_id,
+      }.compact
+    end
+  end
+end

data/lib/hcp/resource.rb

@@ -1,15 +1,58 @@
 module Hcp
+  # A record as Housecall Pro answered it.
   class Resource
-    attr_reader :id
+    class << self
+      # Declares a reader for what Housecall Pro answers under a name.
+      # @!macro [attach] attribute
+      #   @!method $1
+      #   @return [String, nil] the $1, as Housecall Pro answers it.
+      def attribute(name, key = name) = define_method(name) { @node[key.to_s] }
+
+      # Declares a reader for a moment Housecall Pro stamps.
+      # @!macro [attach] timestamp
+      #   @!method $1
+      #   @return [Time, nil] the moment Housecall Pro answers as $1.
+      def timestamp(name, key = name) = define_method(name) { time key.to_s }
+
+      # Declares a reader for a sum Housecall Pro counts in cents.
+      # @!macro [attach] amount
+      #   @!method $1
+      #   @return [BigDecimal, nil] the $1, which Housecall Pro counts in cents.
+      def amount(name, key = name) = define_method(name) { money key.to_s }
+    end
+
+    # @param node [Hash] the record as Housecall Pro answered it.
+    # @param company_id [String, nil] the location it was read as.
+    def initialize(node: {}, company_id: nil)
+      @node = node
+      @company_id = company_id
+    end
+
+    # @return [String] the ID Housecall Pro files the record under.
+    def id = @node['id']
 
   private
 
-    def headers
-      {
-        'Authorization' => "Token #{@key}",
-        'Content-Type' => 'application/json',
-        'X-Company-Id' => @company_id,
-      }.compact
+    # Built from the record's own path rather than its class, so a nested collection sits
+    # under its parent however deep Housecall Pro put it.
+    def nested(type, segment)
+      Relation.new type: type, path: "#{path}/#{segment}", company_id: @company_id
+    end
+
+    def path = "#{self.class.path}/#{id}"
+
+    def time(*keys)
+      value = @node.dig(*keys)
+      Time.iso8601 value if value.present?
+    end
+
+    # Housecall Pro counts money in cents, and a caller reads it in dollars.
+    def money(key) = (BigDecimal(@node[key].to_s) / 100 if @node[key])
+
+    def record(type, key) = (type.new node: @node[key], company_id: @company_id if @node[key])
+
+    def records(type, key)
+      Array(@node[key]).map { |node| type.new node: node, company_id: @company_id }
     end
   end
 end

data/lib/hcp/resources/address.rb

@@ -0,0 +1,24 @@
+module Hcp
+  # Where a customer is billed, or where the work happens.
+  class Address < Resource
+    # What Housecall Pro calls a page of a customer's addresses.
+    def self.key = 'addresses'
+
+    attribute :street
+    attribute :street_line_2
+    attribute :city
+    attribute :state
+    attribute :zip
+    attribute :country
+
+    # Housecall Pro answers these as numbers under a customer and as strings under the company.
+    # @return [Float, nil] how far north the address is, where Housecall Pro placed it.
+    def latitude = @node['latitude']&.to_f
+
+    # @return [Float, nil] how far east the address is, where Housecall Pro placed it.
+    def longitude = @node['longitude']&.to_f
+
+    # @return [Symbol, nil] :billing or :service.
+    def type = @node['type']&.to_sym
+  end
+end

data/lib/hcp/resources/booking_window.rb

@@ -0,0 +1,52 @@
+module Hcp
+  # A slot the account's online booking settings leave open for work to be booked into.
+  class BookingWindow < Resource
+    # How Housecall Pro writes the moment a range is looked at from.
+    STAMP = '%Y-%m-%dT%H:%M:%S'
+
+    class << self
+      # Where Housecall Pro keeps them.
+      def path = 'company/schedule_availability/booking_windows'
+
+      # What Housecall Pro calls a list of them.
+      def key = 'booking_windows'
+
+      # Housecall Pro answers these whole rather than a page at a time, so they are read in one
+      # request rather than walked, and there is no list left to narrow, order or cut.
+      # @param starts_at [Date, Time, nil] where to look from; the next day holding a free
+      #   window where left out.
+      # @param days [Integer, nil] how many days of the schedule to look at; seven where left out.
+      # @param minutes [Integer, nil] how wide to cut each window; the service's own duration,
+      #   or thirty minutes, where left out.
+      # @param service_id [String, nil] the service whose assigned pros to look at.
+      # @param price_form_id [String, nil] the price form whose assigned pros to look at.
+      # @param employee_ids [Array<String>, nil] the pros to look at, rather than all of them.
+      # @param company_id [String, nil] the location to read as, where the account has several.
+      # @return [Array<BookingWindow>] every window in the range, free and taken alike.
+      def all(starts_at: nil, days: nil, minutes: nil, service_id: nil, price_form_id: nil,
+        employee_ids: nil, company_id: nil)
+        params = { start_date: stamp(starts_at), show_for_days: days, service_id: service_id,
+          service_duration: minutes, price_form_id: price_form_id, employee_ids: employee_ids, }
+        read(params, company_id).fetch(key).
+          map { |node| new node: node, company_id: company_id }
+      end
+
+    private
+
+      def stamp(value) = value&.strftime(STAMP)
+
+      def read(params, company_id)
+        Request.new(path: path, params: params, company_id: company_id).body
+      end
+    end
+
+    # @return [Time, nil] when the window opens.
+    timestamp :starts_at, :start_time
+
+    # @return [Time, nil] when the window closes.
+    timestamp :ends_at, :end_time
+
+    # @return [Boolean] whether the account is free to take work in the window.
+    def available? = @node['available']
+  end
+end

data/lib/hcp/resources/company.rb

@@ -0,0 +1,42 @@
+module Hcp
+  # The account a key belongs to, and the settings every job it holds is booked under.
+  class Company < Resource
+    # Where Housecall Pro keeps it.
+    def self.path = 'company'
+
+    # The only company a key can read is its own, so there is no list and no ID to find one by.
+    # @param company_id [String, nil] the location to read as, where the account has several.
+    # @return [Company] the account, as the location it was read as.
+    def self.current(company_id: nil)
+      node = Request.new(path: path, company_id: company_id).body
+      new node: node, company_id: company_id
+    end
+
+    attribute :name
+    attribute :website
+    attribute :time_zone
+
+    # @return [String, nil] where the account's logo is served from.
+    attribute :logo_url
+
+    # @return [String, nil] the number the account is reached on.
+    attribute :phone, :phone_number
+
+    # @return [String, nil] the address a customer's reply goes to.
+    attribute :support_email
+
+    # @return [Integer, nil] how many minutes wide the window a customer is given is, by default.
+    attribute :arrival_window, :default_arrival_window
+
+    # @return [Address, nil] where the account is run from.
+    def address = record Address, 'address'
+
+    # @return [Array<String>] the ZIP codes the account will travel to.
+    def zip_codes = Array(@node.dig('service_areas_data', 'zip_codes'))
+
+    # Itself first, then every location under it at any depth, in the order Housecall Pro
+    # lists them: a single company is its own one location, and a franchise reads flat.
+    # @return [Array<Company>] the locations whose IDs `company_id:` takes, this one included.
+    def locations = [ self, *records(Company, 'locations').flat_map(&:locations) ]
+  end
+end

data/lib/hcp/resources/customer.rb

@@ -0,0 +1,52 @@
+module Hcp
+  # Whoever the work is for.
+  class Customer < Resource
+    extend Queryable
+    include Named, Timestamped
+
+    # A customer is narrowed by one free-text search rather than by named fields.
+    FILTERS = { q: %i[q], location_ids: %i[location_ids] }
+
+    # The conditions Housecall Pro takes more than one of, and refuses one of.
+    MANY = %i[location_ids]
+
+    # 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'
+  end
+end

data/lib/hcp/resources/employee.rb

@@ -0,0 +1,12 @@
+module Hcp
+  # A pro on a Housecall Pro account.
+  class Employee < Resource
+    include Named, Timestamped
+
+    attribute :email
+    attribute :role
+
+    # @return [String, nil] the number the pro is reached on.
+    attribute :phone, :mobile_number
+  end
+end

data/lib/hcp/resources/estimate/option.rb

@@ -0,0 +1,26 @@
+module Hcp
+  # One of the things a customer was offered on an estimate, priced on its own.
+  class Estimate::Option < Resource
+    include Timestamped
+
+    attribute :name
+    attribute :option_number
+
+    # @return [String, nil] whether the customer has answered, and how.
+    attribute :approval_status
+
+    # @return [String, nil] where Housecall Pro files the option in its own workflow.
+    attribute :status
+
+    # @return [String, nil] what the pro said when they sent it.
+    attribute :message_from_pro
+
+    amount :total_amount
+
+    # @return [Array<String>] what the option is tagged with.
+    def tags = Array(@node['tags'])
+
+    # @return [Array<Note>] what the pros wrote on the option.
+    def notes = records Note, 'notes'
+  end
+end

data/lib/hcp/resources/estimate.rb

@@ -0,0 +1,49 @@
+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'
+  end
+end

data/lib/hcp/resources/job/appointment.rb

@@ -0,0 +1,22 @@
+module Hcp
+  # One visit a job is booked for, where the work takes more than a single trip.
+  class Job::Appointment < Resource
+    # What Housecall Pro calls a list of them.
+    def self.key = 'appointments'
+
+    # @return [Time, nil] when the visit is booked to start.
+    timestamp :starts_at, :start_time
+
+    # @return [Time, nil] when the visit is booked to end.
+    timestamp :ends_at, :end_time
+
+    # @return [Integer, nil] how many minutes wide the arrival window is.
+    attribute :arrival_window, :arrival_window_minutes
+
+    # @return [Boolean] whether the visit is booked for a day rather than for a time.
+    def anytime? = @node['anytime']
+
+    # @return [Array<String>] the IDs of the pros sent on the visit.
+    def dispatched_employee_ids = Array(@node['dispatched_employees_ids'])
+  end
+end

data/lib/hcp/resources/job/invoice.rb

@@ -0,0 +1,21 @@
+module Hcp
+  # A bill raised for a job.
+  class Job::Invoice < Resource
+    # What Housecall Pro calls a list of them.
+    def self.key = 'invoices'
+
+    attribute :invoice_number
+
+    # @return [String, nil] where Housecall Pro files the invoice in its own workflow.
+    attribute :status
+
+    amount :amount
+    amount :due_amount
+
+    # @return [Time, nil] when the invoice was sent.
+    timestamp :sent_at
+
+    # @return [Time, nil] when the invoice was paid.
+    timestamp :paid_at
+  end
+end

data/lib/hcp/resources/job.rb

@@ -0,0 +1,73 @@
+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'
+  end
+end

data/lib/hcp/resources/line_item.rb

@@ -0,0 +1,20 @@
+module Hcp
+  # One line of what a job or an estimate option comes to.
+  class LineItem < Resource
+    # Housecall Pro answers a job's line items under `data` rather than under their own name.
+    def self.key = 'data'
+
+    attribute :name
+    attribute :description
+
+    # @return [Float, nil] how many of it, to two decimal places.
+    attribute :quantity
+
+    amount :unit_price
+    amount :unit_cost
+    amount :amount
+
+    # @return [Symbol, nil] :materials, :labor, or one of the gratuities and discounts.
+    def kind = @node['kind']&.tr(' ', '_')&.to_sym
+  end
+end

data/lib/hcp/resources/note.rb

@@ -0,0 +1,6 @@
+module Hcp
+  # Something a pro wrote on a job or on an estimate option.
+  class Note < Resource
+    attribute :content
+  end
+end

data/lib/hcp/resources/schedule.rb

@@ -0,0 +1,21 @@
+module Hcp
+  # When work is booked for, and how long a window the customer was given.
+  class Schedule < Resource
+    # @return [Time, nil] when the work is booked to start.
+    timestamp :starts_at, :scheduled_start
+
+    # @return [Time, nil] when the work is booked to end.
+    timestamp :ends_at, :scheduled_end
+
+    # @return [String, nil] the IANA zone to show a customer a time in.
+    attribute :time_zone
+
+    # @return [Integer, nil] how many minutes wide the arrival window is.
+    attribute :arrival_window
+
+    # Housecall Pro leaves these out unless a list was asked to bring them back, so a job read
+    # without `includes(:appointments)` has none of them rather than none at all.
+    # @return [Array<Job::Appointment>] the visits the work is booked for.
+    def appointments = records Job::Appointment, 'appointments'
+  end
+end

data/lib/hcp/version.rb

@@ -1,7 +1,5 @@
-# frozen_string_literal: true
-
 # Ruby client for the Housecall Pro API.
 module Hcp
   # Current version of the gem.
-  VERSION = '1.2.4'
+  VERSION = '1.4.0'
 end