hcp 1.4.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eda96bf4ffa8ef77fdb696d95c2f47bed39b593ef075051ae40c5fe5f2e64c8
-  data.tar.gz: 52b938c9001e14231015447cc203d7ea72899a4ef982d58aa2f41ce88cf99c66
+  metadata.gz: 49b3c65ad4efe2c4a1d58b08001acdeaad85d0a67d3d7c22e53596f1e6e47378
+  data.tar.gz: 9e7aaf1f8095223ddcf3d8d3bffe8f04e0478573c4adaf3f6c7bfb843d782359
 SHA512:
-  metadata.gz: 68b998e5fcaaf1656ea9fef6d11a8dff91c4a7a46a4f5b87c3d681dac2f99b4a10b4eae8cb2b115c2f272ce100667cfed87c83700fdd778380c2370ea877f8e9
-  data.tar.gz: 694e677888b6b317779b07f11f9f8644ac1b8e68fd8643b2a3bd300057cb43c1a696c05d844ed25f4310a0eba465824c33ea459ba73b341f3eeb1378ee3c349c
+  metadata.gz: be5b0a3350884a96232554a0b3f44539a5aca0bec65ee4d42fdc6ca332a75d69159ca03ada11a422eacd8711d352b0e6f4119ec48b16a7388f7d1fc9a9e6913d
+  data.tar.gz: b0f80e696be5103618a7a63e056b2fc14747374f925da2003799be4bac9d4a84c274f21ef41457c0e6865ee968d955bee9043d5d5a13dd3cffe5bd1d11be2dd9

data/.yardopts

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

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 ## [Unreleased]
 
+## [2.0.0] - 2026-09-09
+
+- [Breaking change] The key is one account's: `Hcp::Account.new(key:, company_id:)`, a
+  `Company::Account`, answers `business` and `leads`. `Hcp.key`, `Hcp.with_key`, `Hcp::Access`
+  and `HCP_KEY` go.
+
+- [Breaking change] `Hcp::Company` is `Hcp::Business`, a `Company::Business`: `id`, `name`,
+  `phone` as ten digits and `subsidiaries`, which was `locations` and which the vocabulary
+  now lists off the locations Housecall Pro nests. `website`, `time_zone`,
+  `logo_url`, `support_email`, `arrival_window`, `address` and `zip_codes` go.
+
+- [Breaking change] `Hcp::Lead.new(key:, company_id:).create` is `account.leads.create`, which
+  takes the vocabulary's words -- `name:`, `surname:`, `phone:`, `email:`, `address:`,
+  `description:`, `notes:`, `source:`, the description heading the note -- and answers the lead; `Hcp::Lead::Pipeline` is
+  `account.leads.find(id).update(status_name:)`. Writes go through the same plumbing as reads,
+  so a refusal is read the three ways Housecall Pro writes one.
+
+- [Breaking change] Gone, unread by any caller: `Relation`, `Chainable`, `Queryable`, `Filter`,
+  `Job`, `Job::Appointment`, `Job::Invoice`, `Estimate`, `Estimate::Option`, `Customer`,
+  `Employee`, `Schedule`, `Note`, `LineItem`, `Address`, `BookingWindow`, `Hcp::NotFound` --
+  a 404 raises `Hcp::Error` -- `Hcp::TooManyRequests#reset_at` and `Hcp::Event#type`.
+
+- [Breaking change] `Hcp::TooManyRequests` is `Hcp::Throttled`, a `Company::Throttled` rather
+  than an `Hcp::Error`, so one rescue retries a refusal for rate from any platform.
+
+- [Feature] `account.jobs.past(within)` walks the jobs booked to start in the window a page at a
+  time, each an `Hcp::Job` reading in the vocabulary: `scheduled_at` and `completed_at` off the
+  nested schedule and timestamps, `notes` listed one to a line,
+  `amount` in dollars off the cents, `quote` the estimate option
+  the job was created from -- its `amount` the option's total, found once among the customer's
+  estimates --
+  `location` with its `customer` beside it, and `lines` read once off the job's own endpoint.
+
+- [Feature] `account.visits.upcoming(within)` walks the visits booked to start in the window,
+  which Housecall Pro calls appointments and files inside jobs: the jobs booked across the
+  window are read with their appointments, a canceled job's are skipped, and each `Hcp::Visit`
+  answers `starts_at`, `ends_at`, `anytime?`, its job's `description` and the `job` itself.
+
+- [Feature] `Hcp::Error` descends from `Company::Error`, so one rescue covers every platform.
+
 ## [1.4.0] - 2026-08-28
 
 - [Feature] Read as a key for one block, on one thread: `Hcp.with_key(key, company_id:)`,

data/CLAUDE.md

@@ -25,18 +25,22 @@ The authoritative OpenAPI spec is at
 docs.housecallpro.com renders it client-side, so fetching that HTML gets nothing worth reading.
 
 **The spec disagrees with the live API.** Send a real request before writing code against a
-documented shape. Six disagreements found so far, each of which would have shipped a bug:
+documented shape. What has been found so far:
 
-- `page_size` is capped at 200. The spec publishes no maximum.
+- A refusal comes back three ways -- `{"error":{"message":…}}`, `{"error":"…"}` and `{"message":…}`.
+  The spec describes only the first.
+- `PUT /pipeline/statuses` is answered with an empty body.
 - `GET /jobs/{id}/line_items` answers `{"object":"list","data":[…]}`, not the documented
   `{url, data}`.
-- A refusal comes back three ways — `{"error":{"message":…}}`, `{"error":"…"}` and `{"message":…}`.
-  The spec describes only the first.
-- An unknown filter is **ignored, not refused**, so a typo answers the whole account rather than a
-  page of it. This is why the gem checks condition names itself.
-- `GET /company` answers `default_arrival_window` as an integer. The spec publishes it as a string.
-- `GET /company` stamps an address's `latitude` and `longitude` as **strings**, where
-  `GET /customers/{id}/addresses` answers the same fields as numbers.
+- `page_size` is capped at 200. The spec publishes no maximum.
+- A job answers `schedule.appointments` only with `expand[]=appointments`, and `expand` must be
+  sent as an array: a bare string is refused. A job's `scheduled_start` and `scheduled_end`
+  are computed from its appointments, so a job booked across a window carries every
+  appointment in it. An appointment has no address of its own.
+- A job's `original_estimate_id` is the ID of the estimate **option** it was created from, an
+  `est_` ID. `GET /estimates/{id}` takes the estimate's own `csr_` ID and answers
+  `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.
 
 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

data/README.md

@@ -1,10 +1,8 @@
 # The Housecall Pro API Ruby client
 
-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.
-
-This release reads. Writing — beyond the leads that were here before it — comes next.
+The Housecall Pro API, answered in the vocabulary of the [company](https://github.com/claudiob/company)
+gem: a key opens an account, the account answers the business it belongs to, its leads and its
+jobs, and nothing else. Where a caller reads nothing, this gem has no method.
 
 ## How to install
 
@@ -15,187 +13,107 @@ gem install hcp
 Or, in a Gemfile, pinned to the current major:
 
 ```ruby
-gem 'hcp', '~> 1.4'
+gem 'hcp', '~> 2.0'
 ```
 
 `~> major.minor` means `bundle update` never crosses a breaking change.
 
-## The key, and the location
+## The account
 
-Set the key once. Left unset, the gem reads `HCP_KEY` from the environment:
+An account is a key, acting as one location where the key opens several:
 
 ```ruby
-Hcp.key = ENV['HCP_KEY']
+account = Hcp::Account.new key: 'the-api-key'
+account = Hcp::Account.new key: 'the-api-key', company_id: 'loc_1'
 ```
 
-A process serving several accounts hands each thread its own key for as long as a block runs,
-and is handed back the account that key opens:
+`company_id:` is sent as `X-Company-Id`. The account a key belongs to refuses the header, so it
+is only sent where a location is named.
 
-```ruby
-Hcp.with_key(key, company_id: location_id) do |access|
-  access.account.name  # the location, as `Hcp::Company.current` would read it
-  Hcp::Job.limit 10    # every read inside the block is this key's
-end
-```
-
-Neither thread sees the other's key, and the one set before the block comes back after it.
-
-An account with more than one location passes `company_id:` per call, since one process may
-serve several:
+## The business
 
 ```ruby
-Hcp::Job.find id, company_id: company_id
-Hcp::Job.all(company_id: company_id).where(work_status: :scheduled)
+business = account.business
+business.id, business.name
+business.phone        # => '5555550100', ten digits however Housecall Pro wrote them, or nil
+business.subsidiaries # => the business itself first, then every location under it, flat
 ```
 
-`Hcp::Company.current.locations` is where those IDs come from.
-
-## Reading
+Housecall Pro answers a franchise as a tree several levels deep; `subsidiaries` reads it flat
+and is never empty, and each `id` in it is what `company_id:` takes.
 
-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:
-
-```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, ...
-```
+## Leads
 
-### What each resource reads
+Opening a lead opens its customer with it, and hands back what Housecall Pro filed both under:
 
 ```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)
+lead = account.leads.create name: 'Ada', surname: 'Lovelace', phone: '5550000001',
+  email: 'ada@example.com', description: 'Fix the sink', notes: 'Very interested in buying',
+  address: { street: '1 Example Street', city: 'Springfield', state: 'CA', zip: '90210' },
+  source: 'The Lead Generator'
+lead.id, lead.customer.id
 ```
 
-Housecall Pro counts money in cents; this gem reads it in dollars, as a `BigDecimal`.
-
-## The company
-
-The account the key belongs to. There is no list of companies to narrow and no ID to look one
-up by — a key reads its own account and nothing else — so it is read with `current` rather than
-with `find` or `where`:
+Moving a lead through the pipeline names the status as the account names it; a name the
+account has no status for raises `Hcp::Error`:
 
 ```ruby
-company = Hcp::Company.current
-company.name, company.phone, company.support_email, company.website, company.logo_url
-company.time_zone, company.arrival_window, company.address.city, company.zip_codes
+account.leads.find('lea_1').update status_name: 'Won'
 ```
 
-`arrival_window` is how many minutes wide a customer's window is by default, and `zip_codes`
-are the ones the account will travel to.
+## Jobs
 
-`locations` is never empty: it is the account itself, 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 however deep Housecall Pro nests it:
+The jobs booked to start within a window are walked a page at a time, each read flat and in
+dollars however Housecall Pro nested it or counted it:
 
 ```ruby
-Hcp::Company.current.locations.map(&:name)
-# => ['Acme Handyman HQ', 'Acme Handyman East', 'Acme Handyman of Springfield', …]
-```
-
-Each location's `id` is what `company_id:` takes, here and everywhere else:
-
-```ruby
-Hcp::Company.current company_id: location.id
+account.jobs.past(4.weeks).each do |job|
+  job.id, job.description, job.created_at, job.scheduled_at, job.completed_at
+  job.notes             # => "- Gate code 1234\n- Dog in the yard", one to a line
+  job.amount            # => 330.0, dollars as a BigDecimal, where Housecall Pro said 33000
+  job.quote             # => an Hcp::Quote, the estimate option the job was created from, or nil
+  job.quote.amount      # => that option's total in dollars, found among the customer's estimates
+  job.location          # => an Hcp::Location, or nil where the job is booked nowhere
+  job.location.customer # => an Hcp::Customer: id, name, surname, email, phone
+  job.lines             # => Hcp::Line, read off the job's own line_items endpoint on first ask
+end
 ```
 
-## Booking windows
-
-When the account is free to be booked into, as its Online Booking settings answer it. Housecall
-Pro hands this list back whole rather than a page at a time, so it comes back as an `Array`
-rather than as a relation — there is nothing left to narrow, order or cut afterwards.
+A customer's `name` is their first name, or the business's where a person has none, and their
+`phone` is the first of the mobile, home and work numbers that can be dialed.
 
-```ruby
-Hcp::BookingWindow.all
-Hcp::BookingWindow.all starts_at: Date.tomorrow, days: 14
-Hcp::BookingWindow.all employee_ids: [ employee.id ]
-Hcp::BookingWindow.all service_id: id, minutes: 90
-```
+## Visits
 
-Each window says when it opens, when it closes, and whether it is free:
+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.
 
 ```ruby
-free = Hcp::BookingWindow.all(days: 3).select(&:available?)
-free.map { |window| [ window.starts_at, window.ends_at ] }
+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
+end
 ```
 
-Left out, `starts_at` is the next day holding a free window and `days` is seven. A window is
-cut to the service's own duration where `service_id` names one, to `minutes` where that is
-given, and to thirty minutes otherwise.
-
 ## 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
-```
+Everything descends from `Hcp::Error`, which descends from `Company::Error`, so one rescue
+still catches the lot. `Hcp::Throttled`, a `Company::Throttled`, is a refusal for rate, so one
+retry covers every platform.
 
 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:
+`Hcp::Event` reads a webhook payload, and reaches the network for nothing. The signature and
+timestamp headers Housecall Pro signs one with are `Hcp::Event::SIGNATURE_HEADER` and
+`Hcp::Event::TIMESTAMP_HEADER`.
 
 ```ruby
 event = Hcp::Event.new params
-event.type            # :job_scheduled
-event.job_id, event.customer_id, event.scheduled_at, event.invoice_amount
+event.lead_id, event.customer_id, event.conversion_type, event.conversion_id
+event.job_id, event.estimate_id, event.scheduled_at, event.completed_at
+event.invoice_id, event.invoice_job_id, event.invoice_amount
 ```

data/lib/hcp/account.rb

@@ -0,0 +1,22 @@
+module Hcp
+  # The Housecall Pro account a key opens, acting as one of its locations.
+  class Account < Company::Account
+    # @param key [String] API key.
+    # @param company_id [String, nil] location to act as, where the account has several.
+    def initialize(key:, company_id: nil)
+      @client = Client.new key: key, company_id: company_id
+    end
+
+    # @return [Business] business the key belongs to, as the location it acts as.
+    def business = Business.new node: @client.get('company')
+
+    # @return [Jobs] jobs of the location, walked a page at a time.
+    def jobs = Jobs.new client: @client
+
+    # @return [Visits] visits of the location, read off its jobs.
+    def visits = Visits.new client: @client
+
+    # @return [Leads] leads of the location, to open and to move.
+    def leads = Leads.new client: @client
+  end
+end

data/lib/hcp/answer.rb

@@ -1,35 +1,27 @@
 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.
+    # @return [Hash, nil] record Housecall Pro answered with, or nothing where it sent none.
     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)
+        when Net::HTTPTooManyRequests then raise Throttled, message
         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)
+    def parsed = @parsed ||= (JSON @response.body if @response.body.present?)
   end
 end

data/lib/hcp/client.rb

@@ -0,0 +1,41 @@
+module Hcp
+  # Every request to Housecall Pro, made with one key as one location.
+  class Client
+    # Where Housecall Pro answers.
+    HOST = 'https://api.housecallpro.com'
+
+    # @param key [String] API key every request is made with.
+    # @param company_id [String, nil] location to act as, where the account has several.
+    def initialize(key:, company_id: nil)
+      @key = key
+      @company_id = company_id
+    end
+
+    # @return [Hash] record Housecall Pro answered with.
+    def get(path, query = {}) = answer { Net::HTTP.get_response uri(path, query), headers }
+
+    # @return [Hash] record Housecall Pro opened.
+    def post(path, body) = answer { Net::HTTP.post uri(path), body.to_json, headers }
+
+    # @return [Hash, nil] what Housecall Pro answered, where it answered anything.
+    def put(path, body) = answer { Net::HTTP.put uri(path), body.to_json, headers }
+
+  private
+
+    def answer
+      Answer.new(yield).body
+    rescue Errno::ECONNREFUSED => error
+      raise Error, error
+    end
+
+    def uri(path, query = {}) = URI [ "#{HOST}/#{path}", query.to_query ].compact_blank.join('?')
+
+    def headers
+      {
+        'Authorization' => "Token #{@key}",
+        'Content-Type' => 'application/json',
+        'X-Company-Id' => @company_id,
+      }.compact
+    end
+  end
+end

data/lib/hcp/collections/jobs.rb

@@ -0,0 +1,32 @@
+module Hcp
+  # The jobs of one location, walked a page at a time.
+  class Jobs < Company::Collection
+    # Jobs 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.
+    # @param params [Hash] what the list is narrowed to, as Housecall Pro filters jobs.
+    def initialize(client:, params: {})
+      @client = client
+      @params = params
+    end
+
+    # @param from [Time, nil] the moment the window opens, or nothing for as far back as it goes.
+    # @param to [Time, nil] the moment the window closes, or nothing for as far ahead as it goes.
+    # @return [Jobs] the same list, narrowed to the jobs booked to start between the two.
+    def between(from, to)
+      bounds = { scheduled_start_min: from&.utc&.iso8601, scheduled_start_max: to&.utc&.iso8601 }
+      self.class.new client: @client, params: bounds.compact
+    end
+
+    # Nothing is read until the walk starts, and a page only once the one before it runs out.
+    # @yield [Job] each job in the window, in the order Housecall Pro lists them.
+    def each
+      (1..).each do |page|
+        body = @client.get 'jobs', @params.merge(page: page, page_size: PAGE)
+        body.fetch('jobs').each { |node| yield Job.new node: node, client: @client }
+        break if page >= body.fetch('total_pages')
+      end
+    end
+  end
+end

data/lib/hcp/collections/leads.rb

@@ -0,0 +1,25 @@
+module Hcp
+  # The leads of one location: who asked a Housecall Pro user for work, before there is a job.
+  class Leads < Company::Leads
+    # @param client [Client] how to reach Housecall Pro as the location.
+    def initialize(client:)
+      @client = client
+    end
+
+    # Opens a lead, and a customer with it, on Housecall Pro. A lead has no title of its own, so
+    # the description heads the note and the notes follow it.
+    # @return [Lead] lead as Housecall Pro filed it, with its customer's ID beside it.
+    def create(name:, surname:, phone:, email:, address:, description:, notes:, source:)
+      customer = { first_name: name, last_name: surname, email: email, mobile_number: phone,
+                   lead_source: source, }
+      body = { customer: customer.compact_blank, address: address, lead_source: source,
+               note: [ description, notes ].compact_blank.join("\n"), }
+      Lead.new node: @client.post('leads', body.compact_blank), client: @client
+    end
+
+    # Reaches the network for nothing: the lead is named, and moved once it is asked to be.
+    # @param id [String] ID Housecall Pro files the lead under.
+    # @return [Lead] the lead, able to move through the pipeline.
+    def find(id) = Lead.new node: { id: id }, client: @client
+  end
+end

data/lib/hcp/collections/visits.rb

@@ -0,0 +1,39 @@
+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
+    # @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)
+      @client = client
+      @from = from
+      @to = to
+    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)
+
+    # 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 }
+      end
+    end
+
+  private
+
+    def window = @from..@to
+
+    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' ])
+    end
+  end
+end

data/lib/hcp/error.rb

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

data/lib/hcp/errors/throttled.rb

@@ -0,0 +1,4 @@
+module Hcp
+  # Raised where Housecall Pro refuses a request for rate, and answers it again a little later.
+  Throttled = Class.new Company::Throttled
+end

data/lib/hcp/event.rb

@@ -8,13 +8,10 @@ module Hcp
     TIMESTAMP_HEADER = 'Api-Timestamp'
 
     # @param params [Hash] the payload for an event webhook.
-    def initialize(params = {})
+    def initialize(params)
       @params = params
     end
 
-    # @return [Symbol] the type of event, e.g.: :lead_converted, :job_created, :invoice_sent.
-    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
 
@@ -50,10 +47,8 @@ module Hcp
 
   private
 
-    # @return [Hash] the latest conversion, applies to 'lead.converted' events.
     def conversion = @params.dig(:lead, :conversions).last
 
-    # @return [Symbol] the type of resource affected by the event, can be :lead or :job.
     def resource_type = @params[:event].split('.').first.to_sym
   end
 end

data/lib/hcp/resources/business.rb

@@ -0,0 +1,11 @@
+module Hcp
+  # The business behind a key: the account, or one location of a franchise.
+  class Business < Company::Business
+    # The node keys Housecall Pro spells otherwise than the vocabulary.
+    def self.keys = { phone: :phone_number }
+
+  private
+
+    def below = records Business, :locations
+  end
+end