hcp 1.4.0 → 3.0.0

data/lib/hcp.rb

@@ -1,60 +1,41 @@
 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/technician'
+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/estimates'
+require 'hcp/collections/visits'
+require 'hcp/collections/technicians'
+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: 3.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
@@ -120,39 +134,27 @@ 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/estimates.rb
+- lib/hcp/collections/jobs.rb
+- lib/hcp/collections/leads.rb
+- lib/hcp/collections/technicians.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/technician.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

data/lib/hcp/errors/too_many_requests.rb

@@ -1,16 +0,0 @@
-module Hcp
-  # Raised where Housecall Pro refuses a request for rate.
-  class TooManyRequests < Error
-    # @param message [String] what Housecall Pro said.
-    # @param reset_at [Time, nil] when it will answer again.
-    def initialize(message, reset_at)
-      super message
-      @reset_at = reset_at
-    end
-
-    # Nothing here sleeps: a caller with a queue can bring the whole job back, which is worth
-    # more than a worker asleep holding a connection open.
-    # @return [Time, nil] when the limit lifts, where Housecall Pro said.
-    attr_reader :reset_at
-  end
-end

data/lib/hcp/filter.rb

@@ -1,36 +0,0 @@
-module Hcp
-  # One condition a list is narrowed by, as the parameters Housecall Pro takes it as.
-  class Filter
-    # @param bounds [Array<Symbol>] the parameter for each end of a range, or the single one.
-    # @param value [Object] a range, or the one value to match.
-    def initialize(bounds:, value:)
-      @bounds = bounds
-      @value = value
-    end
-
-    # @return [Hash] the parameters to send, without the end the caller left open.
-    def params
-      return { @bounds.first => @value } unless @value.is_a? Range
-
-      refuse
-      low, high = @bounds
-      { low => stamp(@value.begin), high => stamp(@value.end) }.compact
-    end
-
-  private
-
-    # Housecall Pro reads both ends inclusively, so an excluded end would come back anyway.
-    def refuse
-      raise Error, "#{@bounds.first} takes one value, not a range" if @bounds.one?
-      raise Error, "#{@bounds.last} cannot exclude its end" if @value.exclude_end? && @value.end
-    end
-
-    def stamp(value)
-      case value
-        when Time then value.utc.iso8601
-        when Date then value.iso8601
-        else value
-      end
-    end
-  end
-end

data/lib/hcp/key.rb

@@ -1,24 +0,0 @@
-module Hcp
-  class << self
-    # The Housecall Pro API key every request is read with, where a thread holds none of its own.
-    attr_writer :key
-
-    # @return [String, nil] the key this thread was handed, the one this module was given, or
-    #   the one the environment carries.
-    def key = ActiveSupport::IsolatedExecutionState[:hcp_key] || @key || ENV['HCP_KEY']
-
-    # Reads as this key for the block, on this thread alone, so a process serving several
-    # accounts can hold a key on every thread without any of them seeing another's.
-    # @param key [String] the key to read with.
-    # @param company_id [String, nil] the location to read as, where the account has several.
-    # @yieldparam access [Access] the account the key opens.
-    # @return [Object] what the block answered.
-    def with_key(key, company_id: nil)
-      previous = ActiveSupport::IsolatedExecutionState[:hcp_key]
-      ActiveSupport::IsolatedExecutionState[:hcp_key] = key
-      yield Access.new(company_id: company_id)
-    ensure
-      ActiveSupport::IsolatedExecutionState[:hcp_key] = previous
-    end
-  end
-end

data/lib/hcp/lead/pipeline.rb

@@ -1,36 +0,0 @@
-module Hcp
-  # Where a Housecall Pro user files a lead while they are still chasing it.
-  class Lead::Pipeline
-    include Keyed
-
-    def initialize(id: nil, key:, company_id:)
-      @id = id
-      @key = key
-      @company_id = company_id
-    end
-
-    # Moves the lead to the status going by this name.
-    # @param status_name [String] the status as the account names it, such as 'Won'.
-    def update(status_name:)
-      status = find_status_by name: status_name
-      payload = { resource_type: 'lead', resource_id: @id, status_id: status['id'] }.to_json
-      response = Net::HTTP.put uri, payload, headers
-      raise Error, response.body unless response.is_a? Net::HTTPSuccess
-    rescue Errno::ECONNREFUSED => error
-      raise Error, error
-    end
-
-  private
-
-    def find_status_by(name:)
-      body = JSON Net::HTTP.get uri.tap { |url| url.query = 'resource_type=lead' }, headers
-      body['statuses'].find { |status| status['name'] == name } || unknown_status(name: name)
-    end
-
-    def unknown_status(name:)
-      raise Error, "Status #{name} not found for lead #{@id}"
-    end
-
-    def uri = URI 'https://api.housecallpro.com/pipeline/statuses'
-  end
-end

data/lib/hcp/lead.rb

@@ -1,44 +0,0 @@
-module Hcp
-  # 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
-      @key = key
-      @company_id = company_id
-      @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
-      body = JSON response.body
-      @id, @customer_id = body['id'], body.dig('customer', 'id')
-    rescue Errno::ECONNREFUSED => error
-      raise Error, error
-    end
-
-  private
-
-    def lead_for(params = {})
-      {
-        customer: customer_for(params), address: params[:address],
-        lead_source: params[:source], note: params[:note],
-      }.compact_blank
-    end
-
-    def customer_for(params = {})
-      {
-        first_name: params[:name], email: params[:email],
-        mobile_number: params[:phone], lead_source: params[:source],
-      }.compact_blank
-    end
-
-    def uri = URI 'https://api.housecallpro.com/leads'
-  end
-end

data/lib/hcp/relation.rb

@@ -1,76 +0,0 @@
-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

@@ -1,31 +0,0 @@
-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