hcp 3.1.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c2323d80d7ca73d0e62b6cef443bd2e40b803495df3ed0ad0d05fac2b5eb186
-  data.tar.gz: d908b99bcf637800fbc1bf0bc17bb777d06338e1ca51ae999981405ae717a59b
+  metadata.gz: 6452e662bc00ffd31b8fa21a935de8c1b4ef9d4779a87668ce4f6b4c4585b3b0
+  data.tar.gz: e9e8e77e53671ef7e822f2116d32a231ab6f71901de418bdd8643acd46232de5
 SHA512:
-  metadata.gz: a93a05b7b4b3b0785661ab9104ac0a0ec88a4d18e43331fd49414c4ad8388e379806a01425250d5e862c2015b76101747c0a4d2e139d67b9ee139a7871d078fe
-  data.tar.gz: '0759b4af994c2ef83c40abc10b7730b9e49350d3ceb8a74fa7f9be43cf373094b0056bfd35644b69a77bb04328176d9bd3994cadba1dabcc4f01abbf1054ff7f'
+  metadata.gz: 4b03d7602db5e603bd0b0ba03c9031fb93f29bece4d5984a460f0fb4f79b5d7a740de189c4c0d281919650f39f5bf84e4019d8cc5988630114aaec5a59fdab45
+  data.tar.gz: 38068b949e79d8c8c26bbfe07f5c75546f4f11964a4ec9259eaab168df458423be6eac7575a070ed7cb91b0a529d3a11d22b6f2d2605decf7ea39d25847ad0c4

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [4.0.0] - 2026-09-16
+
+- [Breaking change] The vocabulary is `company` 3.0: `assigned_to` is `of`, so
+  `account.visits.of(technician)` is what `account.visits.assigned_to(technician)` was. The pin
+  is `~> 3.0`.
+
+- [Feature] `account.windows`, the free time of the location: every stretch nobody is booked
+  for, read off `GET /company/schedule_availability/booking_windows`. Housecall Pro works it out
+  for itself -- it holds the hours the business keeps, the notice it needs, the padding it
+  leaves around a job and the calendar blocked out -- so this asks rather than reckons, and an
+  hour held is already taken off.
+
+- [Feature] Housecall Pro answers a week as a row of short windows, each open or not. The open
+  ones that run together are joined back into the stretch they came from, so a window is as long
+  as the pro is free rather than as long as their booking page happens to offer. What to cut it
+  into is the caller's, where an offer is being made.
+
+- [Note] `start_date`, `show_for_days` and `employee_ids` all narrow this list, so one person's
+  week is one request -- unlike `/events`, which accepts the same words and ignores them. An
+  account with nothing open answers a bare list rather than the usual object, and both shapes
+  are read.
+
 ## [3.1.0] - 2026-09-16
 
 - [Feature] `account.visits` covers the time blocked out around the work, which Housecall Pro

data/README.md

@@ -147,7 +147,7 @@ One technician's week is the visits in it narrowed to them, which is how a sched
 
 ```ruby
 monday = Date.today.beginning_of_week.in_time_zone
-account.visits.between(monday, monday + 1.week).assigned_to(technician).each do |visit|
+account.visits.between(monday, monday + 1.week).of(technician).each do |visit|
   visit.starts_at, visit.ends_at, visit.job.location.street
 end
 ```
@@ -159,6 +159,24 @@ dispatched to some of its crew or to none of it, so a stop dispatched to nobody
 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.
 
+The other half of that week is the hours they are *not* out, which Housecall Pro works out for
+itself and answers whole:
+
+```ruby
+account.windows.between(monday, monday + 1.week).of(technician).each do |window|
+  window.starts_at, window.ends_at
+end
+```
+
+It holds the hours the business keeps, the notice it needs, the padding it leaves around a job
+and the time blocked out on the calendar, so this asks rather than reckons and the holds are
+already taken off. It answers a week as a row of short windows, each open or not; the open ones
+that run together are one stretch and are joined back into it, so a window is as long as the pro
+is free rather than as long as their booking page happens to offer.
+
+`start_date`, `show_for_days` and `employee_ids` all narrow, so a week for one person is the one
+request -- unlike `/events`, which accepts the same words and ignores them.
+
 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.

data/lib/hcp/account.rb

@@ -16,6 +16,9 @@ module Hcp
     # @return [Visits] visits of the location, read off its jobs.
     def visits = Visits.new client: @client
 
+    # @return [Windows] free time of the location, as Housecall Pro works it out.
+    def windows = Windows.new client: @client
+
     # @return [Technicians] employees of the location, walked a page at a time.
     def technicians = Technicians.new client: @client
 

data/lib/hcp/collections/visits.rb

@@ -31,7 +31,7 @@ module Hcp
     # to it, so the stops they are not on are let go once the work comes back.
     # @param technician [Company::Technician] whoever the work is booked for.
     # @return [Company::Selection] the same list, narrowed to the stops they are booked for.
-    def assigned_to(technician)
+    def of(technician)
       theirs = with technician: technician
       Company::Selection.new(collection: theirs) do |visit|
         visit.technicians.any? { |each| each.id == technician.id }

data/lib/hcp/collections/windows.rb

@@ -0,0 +1,74 @@
+module Hcp
+  # The free time of one location, which Housecall Pro works out for itself: it holds the hours
+  # the business keeps, the notice it needs and the padding it leaves around a job, and answers
+  # which stretches of a week are still open. So this asks rather than reckons, and the hours
+  # blocked out on the calendar are already taken off.
+  class Windows < Company::Windows
+    # How far ahead to ask where nothing named an end. Housecall Pro's own default, and a week
+    # is what a schedule is read by.
+    DAYS = 7
+
+    # @param client [Client] how to reach Housecall Pro as the location.
+    # @param technician [Company::Technician, nil] whose free time to ask for, or nothing for
+    #   whether anybody at all is free.
+    # @param from [Time, nil] the moment the window opens, or nothing for the first day open.
+    # @param to [Time, nil] the moment the window closes, or nothing for a week of it.
+    def initialize(client:, technician: nil, from: nil, to: nil)
+      @client = client
+      @technician = technician
+      @from = from
+      @to = to
+    end
+
+    # @param from [Time, nil] the moment the window opens, or nothing for the first day open.
+    # @param to [Time, nil] the moment the window closes, or nothing for a week of it.
+    # @return [Windows] the same list, narrowed to the free time between the two.
+    def between(from, to) = with(from: from, to: to)
+
+    # Housecall Pro narrows free time by who it is free for, so the technician joins the window
+    # in the one request and nobody else's hours are answered or paid for.
+    # @param technician [Company::Technician] whose free time to answer.
+    # @return [Windows] the same list, as that technician's alone.
+    def of(technician) = with(technician: technician)
+
+    # Housecall Pro answers a week as a row of short windows, each open or not. Consecutive open
+    # ones are one stretch of free time and are joined back into it, so what comes out is as long
+    # as the pro is actually free rather than as long as their booking page happens to offer.
+    # @yield [Company::Window] each stretch nobody is booked for, earliest first.
+    def each
+      joined(open).each do |from, to|
+        yield Company::Window.new node: { starts_at: from, ends_at: to }
+      end
+    end
+
+  private
+
+    def open = answered.select { it['available'] }.map { [ it['start_time'], it['end_time'] ] }
+
+    def joined(windows)
+      windows.each_with_object [] do |(from, to), stretches|
+        carries_on = stretches.last && stretches.last[1] == from
+        carries_on ? stretches.last[1] = to : stretches << [ from, to ]
+      end
+    end
+
+    # An account with nothing open answers a bare list rather than the usual object, so the
+    # windows are taken out of whichever shape came back.
+    def answered
+      body = @client.get 'company/schedule_availability/booking_windows', params
+      body.is_a?(Array) ? body : body.fetch('booking_windows', [])
+    end
+
+    def params
+      { start_date: @from&.utc&.strftime('%Y-%m-%dT%H:%M:%S'), show_for_days: days,
+        employee_ids: (@technician && [ @technician.id ]), }.compact
+    end
+
+    def days = (@to && @from) ? ((@to - @from) / 1.day).ceil : DAYS
+
+    def with(**changed)
+      self.class.new(**{ client: @client, technician: @technician, from: @from,
+                         to: @to, }.merge(changed))
+    end
+  end
+end

data/lib/hcp/version.rb

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

data/lib/hcp.rb

@@ -45,6 +45,7 @@ require 'hcp/collections/jobs'
 require 'hcp/collections/estimates'
 require 'hcp/collections/occurrences'
 require 'hcp/collections/visits'
+require 'hcp/collections/windows'
 require 'hcp/collections/technicians'
 require 'hcp/account'
 require 'hcp/event'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hcp
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: ice_cube
   requirement: !ruby/object:Gem::Requirement
@@ -157,6 +157,7 @@ files:
 - lib/hcp/collections/occurrences.rb
 - lib/hcp/collections/technicians.rb
 - lib/hcp/collections/visits.rb
+- lib/hcp/collections/windows.rb
 - lib/hcp/error.rb
 - lib/hcp/errors/throttled.rb
 - lib/hcp/event.rb