hcp 1.2.4 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ec3ea9703ad89514d477bc3b528fc079de9af904756490ff231b0ff95a64997
-  data.tar.gz: 25eb97c540c18e24bb03ea1b5f184bb1015561e0157cff181c3e505f00398b9e
+  metadata.gz: 7eda96bf4ffa8ef77fdb696d95c2f47bed39b593ef075051ae40c5fe5f2e64c8
+  data.tar.gz: 52b938c9001e14231015447cc203d7ea72899a4ef982d58aa2f41ce88cf99c66
 SHA512:
-  metadata.gz: d550e97fd0b9f6e04f911f66d893d710aee670ee99b1ad013776a4321c0d2e4581705f520eb2852bfb09f9c4c15810023744dea3537fe940c49fecc94e4f1eed
-  data.tar.gz: 6e840c9d60179aa8983c663467174b268f620802e5318956603aa2b83972e9afa24280389e75aee909c319d3b5001cf40d9a5b39fe3be43649eb092befbd2b95
+  metadata.gz: 68b998e5fcaaf1656ea9fef6d11a8dff91c4a7a46a4f5b87c3d681dac2f99b4a10b4eae8cb2b115c2f272ce100667cfed87c83700fdd778380c2370ea877f8e9
+  data.tar.gz: 694e677888b6b317779b07f11f9f8644ac1b8e68fd8643b2a3bd300057cb43c1a696c05d844ed25f4310a0eba465824c33ea459ba73b341f3eeb1378ee3c349c

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,44 @@
+## [Unreleased]
+
+## [1.4.0] - 2026-08-28
+
+- [Feature] Read as a key for one block, on one thread: `Hcp.with_key(key, company_id:)`,
+  which hands the block an `Hcp::Access` answering `account`. A process serving several
+  accounts held them all on one `Hcp.key`, so two threads could read each other's; a key
+  handed to a block is the thread's alone, and the one set before it comes back after.
+
+- [Feature] Read the account a key belongs to: `Hcp::Company.current`, taking `company_id:`.
+  There is no list of companies and no ID to find one by, so it is `current` rather than
+  `find` or `where`. `locations` is the account itself and then every location under it at
+  any depth, flat, so it is never empty; each ID is what `company_id:` takes everywhere else.
+
+- [Fix] `Hcp::Address#latitude` and `#longitude` answer a `Float` whichever endpoint they were
+  read from. Housecall Pro stamps them as numbers under a customer and as strings under the
+  company, and the gem documented `Float` while handing back whatever arrived.
+
+- [Feature] Read when the account is free to be booked into: `Hcp::BookingWindow.all`, taking
+  `starts_at:`, `days:`, `minutes:`, `service_id:`, `price_form_id:` and `employee_ids:`.
+  Housecall Pro answers this list whole rather than a page at a time, so it comes back as an
+  `Array` rather than as a relation.
+
+## [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.
+- [Fix] `require 'hcp'` defines `Hcp::VERSION`, which until now was only set as a side effect
+  of Bundler evaluating the gemspec.
+- [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

data/CLAUDE.md

@@ -0,0 +1,43 @@
+# hcp
+
+A Ruby client for the Housecall Pro API.
+
+## Follow the coding guidelines
+
+https://raw.githubusercontent.com/HouseAccountEng/guidelines/refs/heads/main/STYLE.md
+
+Read them before writing, not after review. They are stricter than this code alone suggests: one
+line of comment above every public declaration and none above a private one, no metaprogramming
+except on an explicit instruction, no method that nothing calls, no rescue for an error that has
+never happened, and a cap of 100 lines to a file and 50 Ruby files to a folder — both enforced by
+`bundle exec rake`, which is the gate for everything here.
+
+Two rules are easy to miss and expensive to undo: a commit message carries no trailer naming its
+author, and a CHANGELOG entry says which of fix, feature or breaking change it is, because that is
+what picks the version.
+
+## Probe the API rather than trust its spec
+
+The authoritative OpenAPI spec is at
+
+    https://stoplight.io/api/v1/projects/housecallpro/housecall-public-api/nodes/reference/housecall.v1.yaml
+
+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:
+
+- `page_size` is capped at 200. The spec publishes no maximum.
+- `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.
+
+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

@@ -1,20 +1,201 @@
 # 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.4'
+```
+
+`~> 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']
+```
+
+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
+```
+
+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:
+
+```ruby
+Hcp::Job.find id, company_id: company_id
+Hcp::Job.all(company_id: company_id).where(work_status: :scheduled)
+```
+
+`Hcp::Company.current.locations` is where those IDs come from.
+
+## 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:
+
+```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`.
+
+## 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`:
+
+```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
+```
+
+`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.
 
-Change the status of a lead in the pipeline:
+`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', …]
+```
+
+Each location's `id` is what `company_id:` takes, here and everywhere else:
+
+```ruby
+Hcp::Company.current company_id: location.id
+```
+
+## 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.
+
+```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
+```
+
+Each window says when it opens, when it closes, and whether it is free:
+
+```ruby
+free = Hcp::BookingWindow.all(days: 3).select(&:available?)
+free.map { |window| [ window.starts_at, window.ends_at ] }
+```
+
+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
+```
+
+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/access.rb

@@ -0,0 +1,12 @@
+module Hcp
+  # What a key opens: the account it belongs to, read as one of its locations.
+  class Access
+    # @param company_id [String, nil] the location to read as, where the account has several.
+    def initialize(company_id: nil)
+      @company_id = company_id
+    end
+
+    # @return [Company] the account the key belongs to, as the location it is read as.
+    def account = Company.current company_id: @company_id
+  end
+end

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'

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,24 @@
+module Hcp
+  class << self
+    # The Housecall Pro API key every request is read with, where a thread holds none of its own.
+    attr_writer :key
+
+    # @return [String, nil] the key this thread was handed, the one this module was given, or
+    #   the one the environment carries.
+    def key = ActiveSupport::IsolatedExecutionState[:hcp_key] || @key || ENV['HCP_KEY']
+
+    # Reads as this key for the block, on this thread alone, so a process serving several
+    # accounts can hold a key on every thread without any of them seeing another's.
+    # @param key [String] the key to read with.
+    # @param company_id [String, nil] the location to read as, where the account has several.
+    # @yieldparam access [Access] the account the key opens.
+    # @return [Object] what the block answered.
+    def with_key(key, company_id: nil)
+      previous = ActiveSupport::IsolatedExecutionState[:hcp_key]
+      ActiveSupport::IsolatedExecutionState[:hcp_key] = key
+      yield Access.new(company_id: company_id)
+    ensure
+      ActiveSupport::IsolatedExecutionState[:hcp_key] = previous
+    end
+  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