hcp 2.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49b3c65ad4efe2c4a1d58b08001acdeaad85d0a67d3d7c22e53596f1e6e47378
-  data.tar.gz: 9e7aaf1f8095223ddcf3d8d3bffe8f04e0478573c4adaf3f6c7bfb843d782359
+  metadata.gz: 4d401d8b087f9b1c05637aaad2f69c6f343ff3d8d50809c02d1b12f6d3fa2889
+  data.tar.gz: e58432a01d9530029c912b92451c9e94101dd8de0982ca072fb540572d14cbfb
 SHA512:
-  metadata.gz: be5b0a3350884a96232554a0b3f44539a5aca0bec65ee4d42fdc6ca332a75d69159ca03ada11a422eacd8711d352b0e6f4119ec48b16a7388f7d1fc9a9e6913d
-  data.tar.gz: b0f80e696be5103618a7a63e056b2fc14747374f925da2003799be4bac9d4a84c274f21ef41457c0e6865ee968d955bee9043d5d5a13dd3cffe5bd1d11be2dd9
+  metadata.gz: 9254b6d9c951494705a671b09484a8bef8586ca085e5a75b3101e66811179cdadd1239e6dd3598d80b9aa097bc0b6a9e7deb982351abc74c48de6f224a7320d8
+  data.tar.gz: 0afdf26a35fa1a7c36e8862d272e39590b02f1d7462393bc972379c6a51a32d7f210c02ff9a0788ef0b973bb02259063d489503abc2bbab43ddfe487b1fe5fc1

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 ## [Unreleased]
 
+## [3.0.1] - 2026-09-15
+
+- [Fix] `visit.anytime?` answers false on an estimate's slot rather than nil. Housecall Pro
+  books an estimate for an hour and has no anytime to answer with, so the slot named none --
+  and a caller storing what a visit reads had a nil where it expected a yes or a no.
+
+## [3.0.0] - 2026-09-15
+
+- [Breaking change] The vocabulary is `company` 2.1: a `Company::Selection` takes its rule as a
+  block, a visit answers a lead as well as a job, and it says where it is. The pin is `~> 2.1`.
+
+- [Breaking change] `account.visits` is every stop booked, not only a job's: an estimate is
+  work still being looked at, so its slot is a visit too, and the list now reads `/jobs` and
+  `/estimates` rather than `/jobs` alone. `visit.job` is nil on an estimate's slot and
+  `visit.lead` is the `Hcp::Estimate`; `visit.description` is nil there, Housecall Pro giving
+  an estimate no words of its own. A caller that wants what it had before asks
+  `account.visits.for_jobs`, which is the one request it always was, and `for_leads` is the
+  estimates alone.
+
+- [Feature] `Hcp::Estimate`, a `Company::Lead`: `id`, `customer`, `location`, `technicians` and
+  the one slot it is booked for. Housecall Pro expands an estimate with `attachments` and not
+  with appointments, so the estimate's own `schedule` is the slot and answers to its ID.
+
+- [Feature] `Hcp::Visit#location`, where the stop is: an appointment has no address of its own
+  and takes the job's, an estimate's slot takes the estimate's. Both nodes are read in full
+  already, so it costs nothing and is always there.
+
+- [Feature] `Hcp::Visit#lead`, and `technicians` reading an estimate's `assigned_employees`
+  where a job's stop reads its dispatch.
+
+- [Feature] `account.technicians` walks the location's employees a page at a time, each an
+  `Hcp::Technician` reading `id`, `name` off `first_name` and `surname` off `last_name`.
+
+- [Feature] `job.technicians` is the crew a job is assigned to, and `visit.technicians` whoever
+  an appointment was dispatched to -- or, where it was dispatched to nobody, the job's whole
+  crew, which is how Housecall Pro draws it.
+
+- [Feature] `account.visits.between(from, to).assigned_to(technician)` is one technician's
+  week. The window goes to Housecall Pro as `employee_ids`, so only their jobs come back, and
+  the stops of those jobs they are not on are let go as the jobs arrive.
+
 ## [2.0.0] - 2026-09-09
 
 - [Breaking change] The key is one account's: `Hcp::Account.new(key:, company_id:)`, a

data/CLAUDE.md

@@ -42,6 +42,27 @@ documented shape. What has been found so far:
   `Estimate not found` for an option's, so an option is found by listing
   `GET /estimates?customer_id=` and searching the options. Probed live 2026-09-09.
 
+- `employee_ids` narrows both `/jobs` and `/estimates` by assigned pro, and `/estimates` takes
+  the same `scheduled_start_min`/`scheduled_start_max` window as `/jobs`. Over one year on a
+  real account: 15 jobs to 5, and 40 estimates to 2. Worth writing down because the spec gives
+  the parameter no description at all on `/jobs` -- only the `/estimates` twin documents it.
+  `GET /employees` answers `first_name` and `last_name`. Probed live 2026-09-15.
+
+Read off the spec but **not probed**, so treat as claims rather than findings:
+
+- `GET /estimates`' `expand` enum is `attachments` alone -- there is no `appointments` on an
+  estimate, so its `schedule` is the one slot it occupies. Its `work_status` carries `canceled`.
+- `GET /routes` is the only endpoint that groups a day's work, and is unusable as one: it takes
+  a single `date` and `per_page` rather than a range, refuses a Company API Key, and answers
+  `event_ids` and `estimate_ids` as bare strings, so the times still cost `/events` and
+  `/estimates`.
+- `GET /events` -- time blocked out on the calendar -- takes no date and no employee filter at
+  all, so a week of it can only be paged in full. Its `recurrence_rule` is not expanded.
+- `POST /estimates` takes `customer_id`, not a customer, so booking one needs `GET /customers`
+  (search by `q`) and `POST /customers` first. The arrival window is spelled three ways:
+  `arrival_window_in_minutes` on create, `arrival_window_minutes` on an appointment,
+  `arrival_window` on a schedule read back.
+
 A company-scoped key refuses `X-Company-Id` with a 401 on every endpoint, so the header can only
 be exercised with an application key. `GET /company` answers `locations` only to the latter, and
 nests: a location holds locations of its own, several levels deep.

data/README.md

@@ -13,7 +13,7 @@ gem install hcp
 Or, in a Gemfile, pinned to the current major:
 
 ```ruby
-gem 'hcp', '~> 2.0'
+gem 'hcp', '~> 3.0'
 ```
 
 `~> major.minor` means `bundle update` never crosses a breaking change.
@@ -84,18 +84,74 @@ A customer's `name` is their first name, or the business's where a person has no
 
 ## Visits
 
-Housecall Pro calls a visit an appointment and files it inside a job, so the visits booked to
-start within a window are read off the jobs booked across it, a page of jobs at a time, each
-saying what its job says and carrying it. A job called off keeps its visits to itself, and a
-list nothing narrows walks every job there was.
+A visit is any booked time, and Housecall Pro books it two ways. Work already won is a job,
+and Housecall Pro calls its stops appointments and files them inside it. Work still being
+looked at is an estimate, which it schedules the same way but hangs no appointments under, so
+an estimate holds the one slot. Both are read off the work booked across the window, a page of
+it at a time; work called off keeps its stops to itself, and a list nothing narrows walks
+every job and estimate there was.
 
 ```ruby
 account.visits.upcoming(2.weeks).each do |visit|
-  visit.id, visit.description, visit.starts_at, visit.ends_at, visit.anytime?
-  visit.job              # => the Hcp::Job the stop belongs to, its location and customer along
+  visit.id, visit.starts_at, visit.ends_at, visit.anytime?
+  visit.description      # => what the job is called, or nil: an estimate has no words of its own
+  visit.location         # => where the stop is, whatever it was booked for
+  visit.job              # => the Hcp::Job the stop belongs to, or nil where an estimate does
+  visit.lead             # => the Hcp::Estimate it belongs to, or nil where a job does
+  visit.technicians      # => the Hcp::Technicians the stop is booked for
 end
 ```
 
+The two cost a list each, so a caller that wants one kind asks for it and spends one request:
+
+```ruby
+account.visits.upcoming(2.weeks).for_jobs  # => only the appointments, one request
+account.visits.upcoming(2.weeks).for_leads # => only the estimates' slots, one request
+```
+
+A stop says where it is without being asked what it was booked for: an appointment has no
+address of its own and takes the job's, and an estimate's slot takes the estimate's. A caller
+reading a schedule never reaches through `visit.job` for an address.
+
+An estimate reads as the lead it is -- `id`, `customer`, `location` -- because its other half,
+the price, is already `Hcp::Quote`: Housecall Pro files the visit and the prices as one record
+and the vocabulary reads them as two.
+
+`account.visits.create` is named by the vocabulary and not answered here yet; it raises
+`NotImplementedError`. Booking one means `POST /estimates`, which takes a `customer_id` rather
+than a customer, so it needs `GET /customers` and `POST /customers` first, and all three want
+probing before they are written against.
+
+## The schedule
+
+The crew are Housecall Pro's employees, and the active ones are walked a page at a time:
+
+```ruby
+account.technicians.each do |technician|
+  technician.id, technician.name, technician.surname
+end
+```
+
+One technician's week is the visits in it narrowed to them, which is how a schedule reads:
+
+```ruby
+monday = Date.today.beginning_of_week.in_time_zone
+account.visits.between(monday, monday + 1.week).assigned_to(technician).each do |visit|
+  visit.starts_at, visit.ends_at, visit.job.location.street
+end
+```
+
+Housecall Pro narrows both lists by who is assigned to the work, so the window is asked for as
+that technician's and nobody else's comes back -- verified against a real account, where a year
+of work went from 15 jobs to 5 and from 40 estimates to 2. It narrows no further: a job's appointments are
+dispatched to some of its crew or to none of it, so a stop dispatched to nobody is the whole
+crew's, and the stops the technician is not on are let go once the jobs arrive. Asking for the
+week and asking for the technician narrow the same list, in either order.
+
+What Housecall Pro schedules elsewhere is still not here: time blocked out on the calendar is
+filed under `/events`, which takes no date and no employee to narrow by, so a week of it cannot
+be asked for -- only paged in full.
+
 ## Errors
 
 Everything descends from `Hcp::Error`, which descends from `Company::Error`, so one rescue

data/lib/hcp/account.rb

@@ -16,6 +16,9 @@ module Hcp
     # @return [Visits] visits of the location, read off its jobs.
     def visits = Visits.new client: @client
 
+    # @return [Technicians] employees of the location, walked a page at a time.
+    def technicians = Technicians.new client: @client
+
     # @return [Leads] leads of the location, to open and to move.
     def leads = Leads.new client: @client
   end

data/lib/hcp/collections/estimates.rb

@@ -0,0 +1,22 @@
+module Hcp
+  # The estimates of one location, walked a page at a time. Housecall Pro narrows them by the
+  # same words it narrows jobs by, so a window and a crew cost what they cost on a job.
+  class Estimates < Company::Collection
+    # @param client [Client] how to reach Housecall Pro as the location.
+    # @param params [Hash] what the list is narrowed to, as Housecall Pro filters estimates.
+    def initialize(client:, params: {})
+      @client = client
+      @params = params
+    end
+
+    # Nothing is read until the walk starts, and a page only once the one before it runs out.
+    # @yield [Estimate] each estimate in the window, in the order Housecall Pro lists them.
+    def each
+      (1..).each do |page|
+        body = @client.get 'estimates', @params.merge(page: page, page_size: Jobs::PAGE)
+        body.fetch('estimates').each { |node| yield Estimate.new node: node }
+        break if page >= body.fetch('total_pages')
+      end
+    end
+  end
+end

data/lib/hcp/collections/technicians.rb

@@ -0,0 +1,23 @@
+module Hcp
+  # The employees of one location, walked a page at a time. Housecall Pro lists the active
+  # ones and no others, so a crew that has left the business is not among them.
+  class Technicians < Company::Collection
+    # Employees a page: the most Housecall Pro answers with, and more than it refuses.
+    PAGE = 200
+
+    # @param client [Client] how to reach Housecall Pro as the location.
+    def initialize(client:)
+      @client = client
+    end
+
+    # Nothing is read until the walk starts, and a page only once the one before it runs out.
+    # @yield [Technician] each employee, in the order Housecall Pro lists them.
+    def each
+      (1..).each do |page|
+        body = @client.get 'employees', page: page, page_size: PAGE
+        body.fetch('employees').each { |node| yield Technician.new node: node }
+        break if page >= body.fetch('total_pages')
+      end
+    end
+  end
+end

data/lib/hcp/collections/visits.rb

@@ -1,39 +1,80 @@
 module Hcp
-  # The visits of one location, which Housecall Pro calls appointments and files inside jobs:
-  # they are read off the jobs booked across a window, a page of jobs at a time.
-  class Visits < Company::Collection
+  # The visits of one location: the appointments Housecall Pro files inside jobs, and the slot
+  # it files on each estimate. They are read off the work booked across a window, a page of it
+  # at a time, and each kind costs a list of its own.
+  class Visits < Company::Visits
     # @param client [Client] how to reach Housecall Pro as the location.
     # @param from [Time, nil] the moment the window opens, or nothing for every visit there was.
     # @param to [Time, nil] the moment the window closes, or nothing for every visit to come.
-    def initialize(client:, from: nil, to: nil)
+    # @param technician [Company::Technician, nil] whose work to ask for, or nothing for all.
+    # @param jobs [Boolean] whether to read the stops of jobs.
+    # @param leads [Boolean] whether to read the stops of estimates.
+    def initialize(client:, from: nil, to: nil, technician: nil, jobs: true, leads: true)
       @client = client
       @from = from
       @to = to
+      @technician = technician
+      @jobs = jobs
+      @leads = leads
     end
 
     # @param from [Time, nil] the moment the window opens, or nothing for every visit there was.
     # @param to [Time, nil] the moment the window closes, or nothing for every visit to come.
     # @return [Visits] the same list, narrowed to the visits booked to start between the two.
-    def between(from, to) = self.class.new(client: @client, from: from, to: to)
+    def between(from, to) = with from: from, to: to
 
-    # A job booked across the window carries every visit in it, so the jobs are read once and
-    # a canceled job's visits are left where they are.
-    # @yield [Visit] each visit in the window, in the order Housecall Pro lists them.
-    def each
-      jobs.each do |job|
-        next if job.canceled?
-
-        job.visits.each { |visit| yield visit if window.cover? visit.starts_at }
+    # Housecall Pro narrows both lists by who is assigned to the work, so the window is asked
+    # for as this technician's; a job's stop is the whole crew's until somebody is dispatched
+    # to it, so the stops they are not on are let go once the work comes back.
+    # @param technician [Company::Technician] whoever the work is booked for.
+    # @return [Company::Selection] the same list, narrowed to the stops they are booked for.
+    def assigned_to(technician)
+      theirs = with technician: technician
+      Company::Selection.new(collection: theirs) do |visit|
+        visit.technicians.any? { |each| each.id == technician.id }
       end
     end
 
+    # @return [Visits] the same list, read off the jobs alone: one request rather than two.
+    def for_jobs = with leads: false
+
+    # @return [Visits] the same list, read off the estimates alone: one request rather than two.
+    def for_leads = with jobs: false
+
+    # Work booked across the window carries every stop in it, so each list is read once and
+    # what was called off keeps its stops to itself.
+    # @yield [Visit] each visit in the window, the jobs' stops before the estimates'.
+    def each(&)
+      jobs.each { |job| stops job, & } if @jobs
+      estimates.each { |estimate| stops estimate, & } if @leads
+    end
+
   private
 
+    def with(**changed)
+      self.class.new(**{ client: @client, from: @from, to: @to, technician: @technician,
+                         jobs: @jobs, leads: @leads }.merge(changed))
+    end
+
+    def stops(work)
+      return if work.canceled?
+
+      work.visits.each { |visit| yield visit if window.cover? visit.starts_at }
+    end
+
     def window = @from..@to
 
+    def crew = { employee_ids: (@technician && [ @technician.id ]) }
+
     def jobs
       bounds = { scheduled_end_min: @from&.utc&.iso8601, scheduled_start_max: @to&.utc&.iso8601 }
-      Jobs.new client: @client, params: bounds.compact.merge(expand: [ 'appointments' ])
+      params = bounds.merge(crew).compact.merge expand: [ 'appointments' ]
+      Jobs.new client: @client, params: params
+    end
+
+    def estimates
+      bounds = { scheduled_start_min: @from&.utc&.iso8601, scheduled_start_max: @to&.utc&.iso8601 }
+      Estimates.new client: @client, params: bounds.merge(crew).compact
     end
   end
 end

data/lib/hcp/resources/estimate.rb

@@ -0,0 +1,43 @@
+module Hcp
+  # Work a Housecall Pro user was asked to look at and price, which the vocabulary reads as the
+  # lead it is: a stop to go and see it, before there is a job. Housecall Pro schedules it the
+  # way it schedules a job but hangs no appointments under it, so it holds the one slot.
+  class Estimate < Company::Lead
+    # @return [Customer, nil] customer the estimate was opened for.
+    def customer = record Customer, :customer
+
+    # Housecall Pro files the address and the customer side by side, the way it does on a job.
+    # @return [Location, nil] where the work would happen, nil where it is booked nowhere.
+    def location
+      address = @node[:address]
+      Location.new node: address.merge(customer: @node[:customer]) if address[:id].present?
+    end
+
+    # @return [Array<Technician>] employees the estimate is assigned to.
+    def technicians = records Technician, :assigned_employees
+
+    # Housecall Pro gives an estimate no words of its own: what it says is said by its options.
+    # @return [nil] nothing, so a stop of one goes undescribed.
+    def description = nil
+
+    # Housecall Pro files no ID on the slot, there being only ever the one, so it answers to the
+    # estimate's own, and books it for an hour rather than for any time in a day.
+    # @return [Array<Visit>] the one slot the estimate is booked for, empty where it has none.
+    def visits
+      booked = @node.dig :schedule, :scheduled_start
+      return [] if booked.blank?
+
+      [ Visit.new(node: slot, lead: self) ]
+    end
+
+    # @return [Boolean] whether the customer or the pro called the estimate off.
+    def canceled? = attribute(:work_status).to_s.end_with? 'canceled'
+
+  private
+
+    def slot
+      { id: id, anytime: false, start_time: @node.dig(:schedule, :scheduled_start),
+        end_time: @node.dig(:schedule, :scheduled_end) }
+    end
+  end
+end

data/lib/hcp/resources/job.rb

@@ -38,6 +38,10 @@ module Hcp
     # @return [Array<Visit>] stops the job is booked as, empty where none came back.
     def visits = Array(@node.dig :schedule, :appointments).map { Visit.new node: it, job: self }
 
+    # @return [Array<Technician>] employees the job is assigned to, empty where it is assigned
+    #   to nobody.
+    def technicians = records Technician, :assigned_employees
+
     # @return [Boolean] whether the customer or the pro called the job off.
     def canceled? = attribute(:work_status).to_s.end_with? 'canceled'
 

data/lib/hcp/resources/technician.rb

@@ -0,0 +1,7 @@
+module Hcp
+  # A person the business sends out, whom Housecall Pro calls an employee.
+  class Technician < Company::Technician
+    # The node keys Housecall Pro spells otherwise than the vocabulary.
+    def self.keys = { name: :first_name, surname: :last_name }
+  end
+end

data/lib/hcp/resources/visit.rb

@@ -1,21 +1,45 @@
 module Hcp
-  # One stop of a job, which Housecall Pro calls an appointment: it happens where the job does
-  # and says what the job says.
+  # One stop, which Housecall Pro hangs under a job as an appointment and under an estimate as
+  # the estimate's own slot: it happens where the work does and says what the work says.
   class Visit < Company::Visit
     # The node keys Housecall Pro spells otherwise than the vocabulary.
     def self.keys = { starts_at: :start_time, ends_at: :end_time }
 
-    # @param node [Hash] appointment as Housecall Pro answered it under the job's schedule.
-    # @param job [Job] job the appointment sits under.
-    def initialize(node: {}, job:)
+    # @param node [Hash] slot as Housecall Pro answered it under the work it belongs to.
+    # @param job [Job, nil] job the slot sits under, nil where an estimate does.
+    # @param lead [Estimate, nil] estimate the slot sits under, nil where a job does.
+    def initialize(node: {}, job: nil, lead: nil)
       super node: node
       @job = job
+      @lead = lead
     end
 
-    # @return [Job] job the stop belongs to, which came with it.
+    # @return [Job, nil] job the stop belongs to, nil where the stop is an estimate's.
     attr_reader :job
 
-    # @return [String, nil] what the job is called: an appointment has no words of its own.
-    def description = @job.description
+    # @return [Estimate, nil] estimate the stop belongs to, nil where the stop is a job's.
+    attr_reader :lead
+
+    # @return [String, nil] what the work is called: a stop has no words of its own.
+    def description = work.description
+
+    # An appointment has no address of its own and an estimate's slot is the estimate's, so a
+    # stop is where its work is.
+    # @return [Location, nil] where the stop happens, nil where the work is booked nowhere.
+    def location = work.location
+
+    # Housecall Pro dispatches a job's stop to some of its crew, or to none of it, and a stop
+    # dispatched to nobody is the whole crew's. An estimate dispatches nothing and has one crew.
+    # @return [Array<Technician>] whoever the stop is booked for.
+    def technicians = dispatched.presence || work.technicians
+
+  private
+
+    def work = @job || @lead
+
+    def dispatched
+      ids = Array attribute(:dispatched_employees_ids)
+      work.technicians.select { |technician| ids.include? technician.id }
+    end
   end
 end

data/lib/hcp/version.rb

@@ -1,5 +1,5 @@
 # The Housecall Pro API, answered in the vocabulary of the company gem.
 module Hcp
   # The version of this gem, as RubyGems knows it.
-  VERSION = '2.0.0'
+  VERSION = '3.0.1'
 end

data/lib/hcp.rb

@@ -26,12 +26,16 @@ require 'hcp/collections/leads'
 
 # Every record before the one that reads it beside itself, and the job before its list.
 require 'hcp/resources/customer'
+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/estimate'
 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: 2.0.0
+  version: 3.0.1
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -137,19 +137,23 @@ files:
 - lib/hcp/account.rb
 - lib/hcp/answer.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/throttled.rb
 - lib/hcp/event.rb
 - lib/hcp/resources/business.rb
 - lib/hcp/resources/customer.rb
+- lib/hcp/resources/estimate.rb
 - lib/hcp/resources/job.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