hcp 1.4.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eda96bf4ffa8ef77fdb696d95c2f47bed39b593ef075051ae40c5fe5f2e64c8
-  data.tar.gz: 52b938c9001e14231015447cc203d7ea72899a4ef982d58aa2f41ce88cf99c66
+  metadata.gz: 796d536211d1039f154af0ea0340de4e814d9cf86c9009e60af68670dbc16cda
+  data.tar.gz: cd18b17cc8e162a750c998f5d554835d6982d75a7b417c4d60dc26dcfda9106a
 SHA512:
-  metadata.gz: 68b998e5fcaaf1656ea9fef6d11a8dff91c4a7a46a4f5b87c3d681dac2f99b4a10b4eae8cb2b115c2f272ce100667cfed87c83700fdd778380c2370ea877f8e9
-  data.tar.gz: 694e677888b6b317779b07f11f9f8644ac1b8e68fd8643b2a3bd300057cb43c1a696c05d844ed25f4310a0eba465824c33ea459ba73b341f3eeb1378ee3c349c
+  metadata.gz: 1a6302bcfa3722c31caae3cc45d2bfb7d30c60895869c6a03fcc8d7851db99be8ad7f1b460d704f51a268e11fe2a78fef2e351186f9617f312d0ae759d0043e2
+  data.tar.gz: 65d2d60980d7386121a6f411f591398741fda04298a42d39102666b530ebd5239c4cfbe4297ea98d9d99721c2719505674440360551269352a52e0f2d69fceb3

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,80 @@
 ## [Unreleased]
 
+## [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
+  `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,43 @@ 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.
+
+- `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

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,163 @@ gem install hcp
 Or, in a Gemfile, pinned to the current major:
 
 ```ruby
-gem 'hcp', '~> 1.4'
+gem 'hcp', '~> 3.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:
-
-```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
-```
+`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.
 
-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.
+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.
 
-## Reading
+## Leads
 
-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:
+Opening a lead opens its customer with it, and hands back what Housecall Pro filed both under:
 
 ```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
+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
 ```
 
-A condition written as a range is sent as the two ends Housecall Pro takes, and an end left
-open is left out:
+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
-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
+account.leads.find('lea_1').update status_name: 'Won'
 ```
 
-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`.
+## Jobs
 
-Nothing comes back unasked. `includes` asks for what Housecall Pro otherwise leaves out:
+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::Job.includes(:appointments).limit 20
+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
 ```
 
-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:
+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::Job.where bogus: 1
-# => Hcp::Error: bogus is not one of: scheduled_at, ends_at, customer_id, ...
-```
+## Visits
 
-### What each resource reads
+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
-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)
+account.visits.upcoming(2.weeks).each do |visit|
+  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
 ```
 
-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`:
+The two cost a list each, so a caller that wants one kind asks for it and spends one request:
 
 ```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.visits.upcoming(2.weeks).for_jobs  # => only the appointments, one request
+account.visits.upcoming(2.weeks).for_leads # => only the estimates' slots, one request
 ```
 
-`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.
-
-`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:
-
-```ruby
-Hcp::Company.current.locations.map(&:name)
-# => ['Acme Handyman HQ', 'Acme Handyman East', 'Acme Handyman of Springfield', …]
-```
+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.
 
-Each location's `id` is what `company_id:` takes, here and everywhere else:
+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.
 
-```ruby
-Hcp::Company.current company_id: location.id
-```
+`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.
 
-## Booking windows
+## The schedule
 
-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.
+The crew are Housecall Pro's employees, and the active ones are walked a page at a time:
 
 ```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
+account.technicians.each do |technician|
+  technician.id, technician.name, technician.surname
+end
 ```
 
-Each window says when it opens, when it closes, and whether it is free:
+One technician's week is the visits in it narrowed to them, which is how a schedule reads:
 
 ```ruby
-free = Hcp::BookingWindow.all(days: 3).select(&:available?)
-free.map { |window| [ window.starts_at, window.ends_at ] }
+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
 ```
 
-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.
+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.
 
-## Errors
+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.
 
-Everything descends from `Hcp::Error`, so one rescue still catches the lot.
+## Errors
 
-```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,25 @@
+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 [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
+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/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/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