hcp 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6efa69ce3e07caf79d11e344137caf623856a6c4ea62bdda98730d852df80e5e
-  data.tar.gz: 10296089173df4f01acca8945fe39cdff3fdaa28f789730fe402b3322624a338
+  metadata.gz: 7eda96bf4ffa8ef77fdb696d95c2f47bed39b593ef075051ae40c5fe5f2e64c8
+  data.tar.gz: 52b938c9001e14231015447cc203d7ea72899a4ef982d58aa2f41ce88cf99c66
 SHA512:
-  metadata.gz: 82f25858ff585025ee7f1efbd8d099114b18a07f2cac3fc8f2f20d4967b8fe46d68f61d5b922d7ebb80146645fb6d47aa4788df96feae706c8310e99c8992098
-  data.tar.gz: 0333e25614ba5be270978f6b5022ca27e2e4b1ead840e4804aa73b1287f57b5cbc8ee25bf8aa065061abb5e194c069ec62751e9ce281c8c665d9857bcc2578c4
+  metadata.gz: 68b998e5fcaaf1656ea9fef6d11a8dff91c4a7a46a4f5b87c3d681dac2f99b4a10b4eae8cb2b115c2f272ce100667cfed87c83700fdd778380c2370ea877f8e9
+  data.tar.gz: 694e677888b6b317779b07f11f9f8644ac1b8e68fd8643b2a3bd300057cb43c1a696c05d844ed25f4310a0eba465824c33ea459ba73b341f3eeb1378ee3c349c

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [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:
@@ -12,6 +33,8 @@
 - [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.

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

@@ -15,7 +15,7 @@ gem install hcp
 Or, in a Gemfile, pinned to the current major:
 
 ```ruby
-gem 'hcp', '~> 1.3'
+gem 'hcp', '~> 1.4'
 ```
 
 `~> major.minor` means `bundle update` never crosses a breaking change.
@@ -28,6 +28,18 @@ Set the key once. Left unset, the gem reads `HCP_KEY` from the environment:
 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:
 
@@ -36,6 +48,8 @@ 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
@@ -96,6 +110,60 @@ 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.
+
+`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.

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/key.rb

@@ -1,9 +1,24 @@
 module Hcp
   class << self
-    # The Housecall Pro API key every request is read with.
+    # 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 module was given, or the one the environment carries.
-    def key = @key || ENV['HCP_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/resources/address.rb

@@ -11,11 +11,12 @@ module Hcp
     attribute :zip
     attribute :country
 
+    # Housecall Pro answers these as numbers under a customer and as strings under the company.
     # @return [Float, nil] how far north the address is, where Housecall Pro placed it.
-    attribute :latitude
+    def latitude = @node['latitude']&.to_f
 
     # @return [Float, nil] how far east the address is, where Housecall Pro placed it.
-    attribute :longitude
+    def longitude = @node['longitude']&.to_f
 
     # @return [Symbol, nil] :billing or :service.
     def type = @node['type']&.to_sym

data/lib/hcp/resources/booking_window.rb

@@ -0,0 +1,52 @@
+module Hcp
+  # A slot the account's online booking settings leave open for work to be booked into.
+  class BookingWindow < Resource
+    # How Housecall Pro writes the moment a range is looked at from.
+    STAMP = '%Y-%m-%dT%H:%M:%S'
+
+    class << self
+      # Where Housecall Pro keeps them.
+      def path = 'company/schedule_availability/booking_windows'
+
+      # What Housecall Pro calls a list of them.
+      def key = 'booking_windows'
+
+      # Housecall Pro answers these whole rather than a page at a time, so they are read in one
+      # request rather than walked, and there is no list left to narrow, order or cut.
+      # @param starts_at [Date, Time, nil] where to look from; the next day holding a free
+      #   window where left out.
+      # @param days [Integer, nil] how many days of the schedule to look at; seven where left out.
+      # @param minutes [Integer, nil] how wide to cut each window; the service's own duration,
+      #   or thirty minutes, where left out.
+      # @param service_id [String, nil] the service whose assigned pros to look at.
+      # @param price_form_id [String, nil] the price form whose assigned pros to look at.
+      # @param employee_ids [Array<String>, nil] the pros to look at, rather than all of them.
+      # @param company_id [String, nil] the location to read as, where the account has several.
+      # @return [Array<BookingWindow>] every window in the range, free and taken alike.
+      def all(starts_at: nil, days: nil, minutes: nil, service_id: nil, price_form_id: nil,
+        employee_ids: nil, company_id: nil)
+        params = { start_date: stamp(starts_at), show_for_days: days, service_id: service_id,
+          service_duration: minutes, price_form_id: price_form_id, employee_ids: employee_ids, }
+        read(params, company_id).fetch(key).
+          map { |node| new node: node, company_id: company_id }
+      end
+
+    private
+
+      def stamp(value) = value&.strftime(STAMP)
+
+      def read(params, company_id)
+        Request.new(path: path, params: params, company_id: company_id).body
+      end
+    end
+
+    # @return [Time, nil] when the window opens.
+    timestamp :starts_at, :start_time
+
+    # @return [Time, nil] when the window closes.
+    timestamp :ends_at, :end_time
+
+    # @return [Boolean] whether the account is free to take work in the window.
+    def available? = @node['available']
+  end
+end

data/lib/hcp/resources/company.rb

@@ -0,0 +1,42 @@
+module Hcp
+  # The account a key belongs to, and the settings every job it holds is booked under.
+  class Company < Resource
+    # Where Housecall Pro keeps it.
+    def self.path = 'company'
+
+    # The only company a key can read is its own, so there is no list and no ID to find one by.
+    # @param company_id [String, nil] the location to read as, where the account has several.
+    # @return [Company] the account, as the location it was read as.
+    def self.current(company_id: nil)
+      node = Request.new(path: path, company_id: company_id).body
+      new node: node, company_id: company_id
+    end
+
+    attribute :name
+    attribute :website
+    attribute :time_zone
+
+    # @return [String, nil] where the account's logo is served from.
+    attribute :logo_url
+
+    # @return [String, nil] the number the account is reached on.
+    attribute :phone, :phone_number
+
+    # @return [String, nil] the address a customer's reply goes to.
+    attribute :support_email
+
+    # @return [Integer, nil] how many minutes wide the window a customer is given is, by default.
+    attribute :arrival_window, :default_arrival_window
+
+    # @return [Address, nil] where the account is run from.
+    def address = record Address, 'address'
+
+    # @return [Array<String>] the ZIP codes the account will travel to.
+    def zip_codes = Array(@node.dig('service_areas_data', 'zip_codes'))
+
+    # Itself first, 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.
+    # @return [Array<Company>] the locations whose IDs `company_id:` takes, this one included.
+    def locations = [ self, *records(Company, 'locations').flat_map(&:locations) ]
+  end
+end

data/lib/hcp/version.rb

@@ -1,5 +1,5 @@
 # Ruby client for the Housecall Pro API.
 module Hcp
   # Current version of the gem.
-  VERSION = '1.3.0'
+  VERSION = '1.4.0'
 end

data/lib/hcp.rb

@@ -5,11 +5,12 @@ require 'net/http'
 require 'time'
 
 # Only the Active Support files whose methods are used, rather than the whole of it: a name
-# Housecall Pro holds nothing for arrives as readily empty as null, and its queries carry
-# arrays in the bracketed form `to_query` writes.
+# Housecall Pro holds nothing for arrives as readily empty as null, its queries carry arrays
+# in the bracketed form `to_query` writes, and a key handed to one thread stays on it.
 require 'active_support/core_ext/enumerable'
 require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/object/to_query'
+require 'active_support/isolated_execution_state'
 
 require 'hcp/version'
 require 'hcp/error'
@@ -34,6 +35,8 @@ require 'hcp/resources/schedule'
 require 'hcp/concerns/scheduled'
 
 require 'hcp/resources/address'
+require 'hcp/resources/booking_window'
+require 'hcp/resources/company'
 require 'hcp/resources/employee'
 require 'hcp/resources/line_item'
 require 'hcp/resources/note'
@@ -47,6 +50,9 @@ require 'hcp/resources/job/invoice'
 require 'hcp/resources/estimate'
 require 'hcp/resources/estimate/option'
 
+# After Company, which is what a key opens.
+require 'hcp/access'
+
 require 'hcp/concerns/keyed'
 require 'hcp/lead'
 require 'hcp/lead/pipeline'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hcp
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -116,9 +116,11 @@ extra_rdoc_files: []
 files:
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - lib/hcp.rb
+- lib/hcp/access.rb
 - lib/hcp/answer.rb
 - lib/hcp/concerns/chainable.rb
 - lib/hcp/concerns/keyed.rb
@@ -139,6 +141,8 @@ files:
 - lib/hcp/request.rb
 - lib/hcp/resource.rb
 - lib/hcp/resources/address.rb
+- lib/hcp/resources/booking_window.rb
+- lib/hcp/resources/company.rb
 - lib/hcp/resources/customer.rb
 - lib/hcp/resources/employee.rb
 - lib/hcp/resources/estimate.rb