hcp 1.2.3 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d1ffc074c8306b8bf82153790c5e205a5c3ee758606baac77e16fa79097a4f8
-  data.tar.gz: 8414015f07d86c48e63fbeca9afc743462377618519314bff6f342528f9e42dd
+  metadata.gz: 6efa69ce3e07caf79d11e344137caf623856a6c4ea62bdda98730d852df80e5e
+  data.tar.gz: 10296089173df4f01acca8945fe39cdff3fdaa28f789730fe402b3322624a338
 SHA512:
-  metadata.gz: f4b405e43222fc579c7fb54d33bd791270ed9eb283641fe26b59dd1ccfa2b269b3d3adac3f3e51ebb81cef1f0e36da3dd7492c9a06d152e7ee5568eaed64029b
-  data.tar.gz: d6e498e41fe664170557f5a802a94b64fd84391609f6f06c6694663347bc1d5a5e6bfd65f0da9c4ef8b9582a1dace4a92e3983787741589381aaaf757c937fef
+  metadata.gz: 82f25858ff585025ee7f1efbd8d099114b18a07f2cac3fc8f2f20d4967b8fe46d68f61d5b922d7ebb80146645fb6d47aa4788df96feae706c8310e99c8992098
+  data.tar.gz: 0333e25614ba5be270978f6b5022ca27e2e4b1ead840e4804aa73b1287f57b5cbc8ee25bf8aa065061abb5e194c069ec62751e9ce281c8c665d9857bcc2578c4

data/.yardopts

@@ -0,0 +1,5 @@
+--readme README.md
+--markup markdown
+--no-private
+lib/hcp/resource.rb
+lib/**/*.rb

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [Unreleased]
+
+## [1.3.0] - 2026-08-25
+
+- [Feature] Read customers, estimates, jobs and job appointments as an Active Record relation:
+  `Hcp::Job.all`, `.where`, `.order`, `.limit`, `.includes`, `.find`, `.count` and `.first`,
+  walked lazily a page at a time.
+- [Feature] Set the API key once, with `Hcp.key` or `HCP_KEY`, and pass `company_id:` per call.
+- [Feature] Narrow a list by a range — `where(scheduled_at: ..2.days.ago)` — and refuse a
+  condition, an order or an expansion Housecall Pro does not take, which it answers by
+  ignoring rather than by refusing.
+- [Feature] Raise `Hcp::NotFound` where Housecall Pro has no such record, and
+  `Hcp::TooManyRequests`, carrying `reset_at`, where it refuses one for rate. Both descend
+  from `Hcp::Error`, so an existing rescue still catches them.
+- [Breaking change] `Hcp::Lead#lead_for`, `#customer_for` and `#uri` are now private, and
+  neither `Hcp::Lead` nor `Hcp::Lead::Pipeline` inherits from `Hcp::Resource`, which is now a
+  record rather than a holder of credentials. Nothing documented ever called them.
+
+## [1.2.4] - 2026-06-17
+
+- [Fix] Set event.type when params is nil
+
 ## [1.2.3] - 2026-06-15
 
 - [New] Parse estimate_id for :estimate_sent event

data/README.md

@@ -1,20 +1,133 @@
 # The Housecall Pro API Ruby client
 
-## Available methods
+Every method in this gem is one Housecall Pro endpoint. Where Housecall Pro has no endpoint,
+this gem has no method — so a resource answers `update` only where Housecall Pro takes a `PUT`,
+and a job, which it takes none for, answers none.
 
-Initialize and create a Lead:
+This release reads. Writing — beyond the leads that were here before it — comes next.
+
+## How to install
+
+```sh
+gem install hcp
+```
+
+Or, in a Gemfile, pinned to the current major:
 
 ```ruby
-lead = Hcp::Lead.new key:, company_id:
-lead.create name: 'Alice', phone: '8008008000', email: 'alice@example.com',
-  address: { street: '7111 Melrose Ave', city: 'Los Angeles', state: 'CA', zip: '90046' },
-  note: 'Very interested in buying', source: 'The Lead Generator'
-````
+gem 'hcp', '~> 1.3'
+```
+
+`~> major.minor` means `bundle update` never crosses a breaking change.
+
+## The key, and the location
+
+Set the key once. Left unset, the gem reads `HCP_KEY` from the environment:
+
+```ruby
+Hcp.key = ENV['HCP_KEY']
+```
+
+An account with more than one location passes `company_id:` per call, since one process may
+serve several:
+
+```ruby
+Hcp::Job.find id, company_id: company_id
+Hcp::Job.all(company_id: company_id).where(work_status: :scheduled)
+```
+
+## Reading
+
+A list is walked lazily, a page read only once the one before it runs out, so asking for three
+records costs one request rather than all of them:
+
+```ruby
+Hcp::Job.all
+Hcp::Job.find id
+Hcp::Job.limit 50
+Hcp::Job.order updated_at: :desc
+Hcp::Job.where scheduled_at: ..2.days.ago
+Hcp::Job.where(customer_id: id).order(created_at: :asc).limit 10
+Hcp::Job.all.count
+```
+
+A condition written as a range is sent as the two ends Housecall Pro takes, and an end left
+open is left out:
+
+```ruby
+Hcp::Job.where scheduled_at: 2.days.ago..    # scheduled_start_min
+Hcp::Job.where scheduled_at: ..2.days.ago    # scheduled_start_max
+Hcp::Job.where scheduled_at: 1.week.ago..Time.now
+```
+
+Housecall Pro narrows a list by one set of words and answers with another, so this gem speaks
+the narrower's words on both sides: `where(work_status: :in_progress)` and `job.work_status`
+both say `:in_progress`.
+
+Nothing comes back unasked. `includes` asks for what Housecall Pro otherwise leaves out:
 
-Change the status of a lead in the pipeline:
+```ruby
+Hcp::Job.includes(:appointments).limit 20
+```
+
+A condition, an order or an expansion Housecall Pro does not take is refused here rather than
+sent — it answers an unknown condition by ignoring it and handing back the whole account:
+
+```ruby
+Hcp::Job.where bogus: 1
+# => Hcp::Error: bogus is not one of: scheduled_at, ends_at, customer_id, ...
+```
+
+### What each resource reads
+
+```ruby
+job = Hcp::Job.find id
+job.description, job.work_status, job.total_amount, job.invoice_number
+job.customer.name, job.address.city, job.assigned_employees, job.notes, job.tags
+job.schedule.starts_at, job.schedule.time_zone, job.completed_at
+job.appointments, job.line_items, job.invoices
+
+customer = Hcp::Customer.where(q: 'Ada').first
+customer.name, customer.email, customer.phone, customer.kind, customer.addresses
+
+estimate = Hcp::Estimate.find id
+estimate.estimate_number, estimate.options.map(&:total_amount)
+```
+
+Housecall Pro counts money in cents; this gem reads it in dollars, as a `BigDecimal`.
+
+## Errors
+
+Everything descends from `Hcp::Error`, so one rescue still catches the lot.
+
+```ruby
+Hcp::NotFound         # Housecall Pro has no record under that ID
+Hcp::TooManyRequests  # refused for rate; #reset_at says when it lifts
+```
+
+Nothing here sleeps. A caller told to come back later has a queue that can bring the whole job
+back, which is worth more than a worker asleep holding a connection open.
+
+## Leads
+
+Opening a lead, and moving one through the pipeline, are unchanged:
 
 ```ruby
+lead = Hcp::Lead.new key:, company_id:
+lead.create name: 'Ada', phone: '5550000001', email: 'ada@example.com',
+  address: { street: '1 Example Street', city: 'Springfield', state: 'CA', zip: '90210' },
+  note: 'Very interested in buying', source: 'The Lead Generator'
+
 pipeline = Hcp::Lead::Pipeline.new id:, key:, company_id:
 pipeline.update status_name: 'Won'
 ```
 
+## Webhooks
+
+`Hcp::Event` reads a webhook payload, and reaches the network for nothing:
+
+```ruby
+event = Hcp::Event.new params
+event.type            # :job_scheduled
+event.job_id, event.customer_id, event.scheduled_at, event.invoice_amount
+```

data/lib/hcp/answer.rb

@@ -0,0 +1,35 @@
+module Hcp
+  # What Housecall Pro answered: the body it carries, or the refusal it stands for.
+  class Answer
+    # The header Housecall Pro names the epoch a rate limit lifts at.
+    RESET_HEADER = 'RateLimit-Reset'
+
+    # @param response [Net::HTTPResponse] what Housecall Pro sent back.
+    def initialize(response)
+      @response = response
+    end
+
+    # @return [Hash] the record or page Housecall Pro answered with.
+    def body
+      case @response
+        when Net::HTTPSuccess then parsed
+        when Net::HTTPNotFound then raise NotFound, message
+        when Net::HTTPTooManyRequests then raise TooManyRequests.new(message, reset_at)
+        else raise Error, message
+      end
+    end
+
+  private
+
+    # Housecall Pro writes a refusal three ways: the message under an `error`, the message as
+    # the `error`, and the message on its own.
+    def message
+      error = parsed['error'] || parsed['message']
+      error.is_a?(Hash) ? error['message'] : error
+    end
+
+    def reset_at = (Time.at Integer(@response[RESET_HEADER]) if @response[RESET_HEADER])
+
+    def parsed = @parsed ||= JSON(@response.body)
+  end
+end

data/lib/hcp/concerns/chainable.rb

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

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

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

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

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

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

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

@@ -1,3 +1,4 @@
 module Hcp
+  # Raised where Housecall Pro would not answer.
   Error = Class.new StandardError
 end

data/lib/hcp/errors/not_found.rb

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

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

@@ -1,4 +1,5 @@
 module Hcp
+  # What Housecall Pro sent a webhook to say, read without reaching the network.
   class Event
     # @see https://docs.housecallpro.com/docs/housecall-public-api/46e9e1be07621-webhooks
     SIGNATURE_HEADER = 'Api-Signature'
@@ -12,7 +13,7 @@ module Hcp
     end
 
     # @return [Symbol] the type of event, e.g.: :lead_converted, :job_created, :invoice_sent.
-    def type = @params[:event].gsub('.', '_').to_sym
+    def type = @params.fetch(:event, '').gsub('.', '_').to_sym
 
     # @return [String] unique identifier of the lead in a :lead_converted event.
     def lead_id = @params.dig :lead, :id

data/lib/hcp/filter.rb

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

@@ -0,0 +1,9 @@
+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,15 +1,18 @@
 module Hcp
-  class Lead::Pipeline < Resource
+  # 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
-      raise Error, "Status #{status_name} not found for lead #{@id}" unless status
-
       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

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,23 @@
+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/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.3'
+  VERSION = '1.3.0'
 end

data/lib/hcp.rb

@@ -1,13 +1,53 @@
-# frozen_string_literal: true
-
+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, and its queries carry
+# arrays in the bracketed form `to_query` writes.
 require 'active_support/core_ext/enumerable'
 require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/object/to_query'
 
+require 'hcp/version'
 require 'hcp/error'
+require 'hcp/errors/not_found'
+require 'hcp/errors/too_many_requests'
+require 'hcp/key'
+
+# Answer before Request, which reads one, and Filter before Relation, which writes them.
+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/resources/address'
+require 'hcp/resources/employee'
+require 'hcp/resources/line_item'
+require 'hcp/resources/note'
+require 'hcp/resources/customer'
+
+# A job before the collections named under it, which its constant has to exist for.
+require 'hcp/resources/job'
+require 'hcp/resources/job/appointment'
+require 'hcp/resources/job/invoice'
+
+require 'hcp/resources/estimate'
+require 'hcp/resources/estimate/option'
+
+require 'hcp/concerns/keyed'
 require 'hcp/lead'
 require 'hcp/lead/pipeline'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hcp
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.3.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -23,6 +23,90 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails-omakase
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Housecall Pro API
 email:
 - claudiob@users.noreply.github.com
@@ -30,23 +114,49 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - lib/hcp.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/error.rb
+- lib/hcp/errors/not_found.rb
+- lib/hcp/errors/too_many_requests.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/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/version.rb
 homepage: https://github.com/claudiob/hcp
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/claudiob/hcp
-  source_code_uri: https://github.com/claudiob/hcp
-  changelog_uri: https://github.com/claudiob/hcp
+  changelog_uri: https://github.com/claudiob/hcp/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/hcp
 rdoc_options: []
 require_paths:
 - lib