hcp 1.3.0 → 2.0.0

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,9 +0,0 @@
-module Hcp
-  class << self
-    # The Housecall Pro API key every request is read with.
-    attr_writer :key
-
-    # @return [String, nil] the key this module was given, or the one the environment carries.
-    def key = @key || ENV['HCP_KEY']
-  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,23 +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
-
-    # @return [Float, nil] how far north the address is, where Housecall Pro placed it.
-    attribute :latitude
-
-    # @return [Float, nil] how far east the address is, where Housecall Pro placed it.
-    attribute :longitude
-
-    # @return [Symbol, nil] :billing or :service.
-    def type = @node['type']&.to_sym
-  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