hcp 1.4.0 → 2.0.0

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

data/lib/hcp/resource.rb

@@ -1,58 +0,0 @@
-module Hcp
-  # A record as Housecall Pro answered it.
-  class Resource
-    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
-
-    # 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

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

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

@@ -1,42 +0,0 @@
-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/employee.rb

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

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

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

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

@@ -1,21 +0,0 @@
-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/line_item.rb

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

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

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