hcp 1.4.0 → 2.0.0

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

@@ -1,73 +1,58 @@
 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 [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/visit.rb

@@ -0,0 +1,21 @@
+module Hcp
+  # One stop of a job, which Housecall Pro calls an appointment: it happens where the job does
+  # and says what the job 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] appointment as Housecall Pro answered it under the job's schedule.
+    # @param job [Job] job the appointment sits under.
+    def initialize(node: {}, job:)
+      super node: node
+      @job = job
+    end
+
+    # @return [Job] job the stop belongs to, which came with it.
+    attr_reader :job
+
+    # @return [String, nil] what the job is called: an appointment has no words of its own.
+    def description = @job.description
+  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 = '2.0.0'
 end

data/lib/hcp.rb

@@ -1,60 +1,37 @@
 require 'bigdecimal'
-require 'date'
 require 'json'
 require 'net/http'
 require 'time'
 
 # Only the Active Support files whose methods are used, rather than the whole of it: a name
-# Housecall Pro holds nothing for arrives as readily empty as null, its queries carry arrays
-# in the bracketed form `to_query` writes, and a key handed to one thread stays on it.
+# Housecall Pro holds nothing for arrives as readily empty as null, and a query is written the
+# way `to_query` writes one.
 require 'active_support/core_ext/enumerable'
 require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/object/to_query'
-require 'active_support/isolated_execution_state'
+
+# The vocabulary the account answers in.
+require 'company'
 
 require 'hcp/version'
 require 'hcp/error'
-require 'hcp/errors/not_found'
-require 'hcp/errors/too_many_requests'
-require 'hcp/key'
+require 'hcp/errors/throttled'
 
-# Answer before Request, which reads one, and Filter before Relation, which writes them.
+# Answer before Client, which reads one, and Client before everything that talks through it.
 require 'hcp/answer'
-require 'hcp/request'
-require 'hcp/filter'
-require 'hcp/concerns/chainable'
-require 'hcp/relation'
-require 'hcp/concerns/queryable'
-require 'hcp/resource'
-
-# Every concern before the records including it, and Schedule before Scheduled, which reads one.
-require 'hcp/concerns/named'
-require 'hcp/concerns/timestamped'
-require 'hcp/concerns/statused'
-require 'hcp/resources/schedule'
-require 'hcp/concerns/scheduled'
+require 'hcp/client'
+require 'hcp/resources/business'
+require 'hcp/resources/lead'
+require 'hcp/collections/leads'
 
-require 'hcp/resources/address'
-require 'hcp/resources/booking_window'
-require 'hcp/resources/company'
-require 'hcp/resources/employee'
-require 'hcp/resources/line_item'
-require 'hcp/resources/note'
+# Every record before the one that reads it beside itself, and the job before its list.
 require 'hcp/resources/customer'
-
-# A job before the collections named under it, which its constant has to exist for.
+require 'hcp/resources/location'
+require 'hcp/resources/line'
+require 'hcp/resources/quote'
+require 'hcp/resources/visit'
 require 'hcp/resources/job'
-require 'hcp/resources/job/appointment'
-require 'hcp/resources/job/invoice'
-
-require 'hcp/resources/estimate'
-require 'hcp/resources/estimate/option'
-
-# After Company, which is what a key opens.
-require 'hcp/access'
-
-require 'hcp/concerns/keyed'
-require 'hcp/lead'
-require 'hcp/lead/pipeline'
-
+require 'hcp/collections/jobs'
+require 'hcp/collections/visits'
+require 'hcp/account'
 require 'hcp/event'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hcp
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: company
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -120,39 +134,23 @@ files:
 - LICENSE.txt
 - README.md
 - lib/hcp.rb
-- lib/hcp/access.rb
+- lib/hcp/account.rb
 - lib/hcp/answer.rb
-- lib/hcp/concerns/chainable.rb
-- lib/hcp/concerns/keyed.rb
-- lib/hcp/concerns/named.rb
-- lib/hcp/concerns/queryable.rb
-- lib/hcp/concerns/scheduled.rb
-- lib/hcp/concerns/statused.rb
-- lib/hcp/concerns/timestamped.rb
+- lib/hcp/client.rb
+- lib/hcp/collections/jobs.rb
+- lib/hcp/collections/leads.rb
+- lib/hcp/collections/visits.rb
 - lib/hcp/error.rb
-- lib/hcp/errors/not_found.rb
-- lib/hcp/errors/too_many_requests.rb
+- lib/hcp/errors/throttled.rb
 - lib/hcp/event.rb
-- lib/hcp/filter.rb
-- lib/hcp/key.rb
-- lib/hcp/lead.rb
-- lib/hcp/lead/pipeline.rb
-- lib/hcp/relation.rb
-- lib/hcp/request.rb
-- lib/hcp/resource.rb
-- lib/hcp/resources/address.rb
-- lib/hcp/resources/booking_window.rb
-- lib/hcp/resources/company.rb
+- lib/hcp/resources/business.rb
 - lib/hcp/resources/customer.rb
-- lib/hcp/resources/employee.rb
-- lib/hcp/resources/estimate.rb
-- lib/hcp/resources/estimate/option.rb
 - lib/hcp/resources/job.rb
-- lib/hcp/resources/job/appointment.rb
-- lib/hcp/resources/job/invoice.rb
-- lib/hcp/resources/line_item.rb
-- lib/hcp/resources/note.rb
-- lib/hcp/resources/schedule.rb
+- lib/hcp/resources/lead.rb
+- lib/hcp/resources/line.rb
+- lib/hcp/resources/location.rb
+- lib/hcp/resources/quote.rb
+- lib/hcp/resources/visit.rb
 - lib/hcp/version.rb
 homepage: https://github.com/claudiob/hcp
 licenses:

data/lib/hcp/access.rb

@@ -1,12 +0,0 @@
-module Hcp
-  # What a key opens: the account it belongs to, read as one of its locations.
-  class Access
-    # @param company_id [String, nil] the location to read as, where the account has several.
-    def initialize(company_id: nil)
-      @company_id = company_id
-    end
-
-    # @return [Company] the account the key belongs to, as the location it is read as.
-    def account = Company.current company_id: @company_id
-  end
-end

data/lib/hcp/concerns/chainable.rb

@@ -1,39 +0,0 @@
-module Hcp
-  # Extends a list with the chaining that narrows, orders and cuts it.
-  module Chainable
-    # A condition Housecall Pro does not take is one it ignores, answering the whole account
-    # rather than a page of it, so an unknown one is refused here where it can still be named.
-    # @return [Relation] the same list, narrowed by these conditions.
-    def where(**conditions)
-      only conditions.keys, @type.filters.keys
-      narrowed conditions: @conditions.merge(conditions)
-    end
-
-    # @return [Relation] the same list, in this order.
-    def order(**sorts)
-      only sorts.keys, @type.sorts
-      narrowed sorts: sorts
-    end
-
-    # @return [Relation] the same list, stopping after this many records.
-    def limit(count) = narrowed limit: count
-
-    # @return [Relation] the same list, asking Housecall Pro for these beside each record.
-    def includes(*names)
-      only names, @type.expands
-      narrowed expands: @expands | names
-    end
-
-  private
-
-    def only(names, allowed)
-      unknown = names - allowed
-      raise Error, "#{unknown.first} is not one of: #{allowed.join ', '}" if unknown.any?
-    end
-
-    def narrowed(conditions: @conditions, sorts: @sorts, limit: @limit, expands: @expands)
-      Relation.new type: @type, path: @path, company_id: @company_id, conditions: conditions,
-        sorts: sorts, limit: limit, expands: expands
-    end
-  end
-end

data/lib/hcp/concerns/keyed.rb

@@ -1,14 +0,0 @@
-module Hcp
-  # Extends a class handed its own key, as everything was before the key became global.
-  module Keyed
-  private
-
-    def headers
-      {
-        'Authorization' => "Token #{@key}",
-        'Content-Type' => 'application/json',
-        'X-Company-Id' => @company_id,
-      }.compact
-    end
-  end
-end

data/lib/hcp/concerns/named.rb

@@ -1,7 +0,0 @@
-module Hcp
-  # Extends a record Housecall Pro holds a person's names for.
-  module Named
-    # @return [String] what they are called, by whichever of their names Housecall Pro holds.
-    def name = [ @node['first_name'], @node['last_name'] ].compact_blank.join ' '
-  end
-end

data/lib/hcp/concerns/queryable.rb

@@ -1,41 +0,0 @@
-module Hcp
-  # Extends a resource with the entry points that read a list of it, or one record.
-  module Queryable
-    # @param company_id [String, nil] the location to read as, where the account has several.
-    # @return [Relation] every record of this kind the location holds.
-    def all(company_id: nil) = Relation.new type: self, company_id: company_id
-
-    # @return [Relation] the records matching these conditions.
-    def where(company_id: nil, **conditions) = all(company_id: company_id).where(**conditions)
-
-    # @return [Relation] the records in this order.
-    def order(company_id: nil, **sorts) = all(company_id: company_id).order(**sorts)
-
-    # @return [Relation] at most this many records.
-    def limit(count, company_id: nil) = all(company_id: company_id).limit(count)
-
-    # @return [Relation] the records, with these brought back beside each of them.
-    def includes(*names, company_id: nil) = all(company_id: company_id).includes(*names)
-
-    # @return [Integer] how many records of this kind the location holds.
-    def count(company_id: nil) = all(company_id: company_id).count
-
-    # @return [Resource, nil] the first record, or nil where the location holds none.
-    def first(company_id: nil) = all(company_id: company_id).first
-
-    # @return [Resource] the record Housecall Pro files under this ID.
-    def find(id, company_id: nil) = all(company_id: company_id).find(id)
-
-    # @return [Hash] what a list of these may be narrowed by.
-    def filters = self::FILTERS
-
-    # @return [Array<Symbol>] the conditions Housecall Pro takes more than one of.
-    def many = self::MANY
-
-    # @return [Array<Symbol>] what Housecall Pro will put a list of these in order of.
-    def sorts = self::SORTS
-
-    # @return [Array<Symbol>] what these bring back beside themselves where asked to.
-    def expands = self::EXPANDS
-  end
-end

data/lib/hcp/concerns/scheduled.rb

@@ -1,16 +0,0 @@
-module Hcp
-  # Extends a record Housecall Pro books work for and stamps as the work happens.
-  module Scheduled
-    # @return [Schedule, nil] when the work is booked for.
-    def schedule = record Schedule, 'schedule'
-
-    # @return [Time, nil] when the pro said they were on their way.
-    def on_my_way_at = time 'work_timestamps', 'on_my_way_at'
-
-    # @return [Time, nil] when the work started.
-    def started_at = time 'work_timestamps', 'started_at'
-
-    # @return [Time, nil] when the work was finished.
-    def completed_at = time 'work_timestamps', 'completed_at'
-  end
-end

data/lib/hcp/concerns/statused.rb

@@ -1,23 +0,0 @@
-module Hcp
-  # Extends a record Housecall Pro moves through a workflow.
-  module Statused
-    # Housecall Pro narrows a list by one set of words and answers with another, so a caller
-    # who filters by :in_progress reads :in_progress back rather than 'in progress'.
-    STATUSES = {
-      'needs scheduling' => :unscheduled,
-      'scheduled' => :scheduled,
-      'in progress' => :in_progress,
-      'complete rated' => :completed,
-      'complete unrated' => :completed,
-      'user canceled' => :canceled,
-      'pro canceled' => :canceled,
-    }
-
-    # @return [Symbol, nil] where Housecall Pro files the record in its own workflow.
-    def work_status = STATUSES[@node['work_status']]
-
-    # A rating is not a status, so it reads beside one rather than inside it.
-    # @return [Boolean] whether the customer rated the work.
-    def rated? = @node['work_status'] == 'complete rated'
-  end
-end

data/lib/hcp/concerns/timestamped.rb

@@ -1,10 +0,0 @@
-module Hcp
-  # Extends a record Housecall Pro stamps with when it was opened and last changed.
-  module Timestamped
-    # @return [Time, nil] when the record was opened.
-    def created_at = time 'created_at'
-
-    # @return [Time, nil] when the record last changed.
-    def updated_at = time 'updated_at'
-  end
-end

data/lib/hcp/errors/not_found.rb

@@ -1,4 +0,0 @@
-module Hcp
-  # Raised where Housecall Pro has no record under the ID it was asked for.
-  NotFound = Class.new Error
-end