hcp 3.1.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c2323d80d7ca73d0e62b6cef443bd2e40b803495df3ed0ad0d05fac2b5eb186
-  data.tar.gz: d908b99bcf637800fbc1bf0bc17bb777d06338e1ca51ae999981405ae717a59b
+  metadata.gz: aad72b55ce034138806c6d68b993d430e7c299960ee14c92e0c59563b5f5bae3
+  data.tar.gz: ba0582ba808d0dbf087eb8a9f6823336e57d6fbc466a1be0f71a9daee38db25b
 SHA512:
-  metadata.gz: a93a05b7b4b3b0785661ab9104ac0a0ec88a4d18e43331fd49414c4ad8388e379806a01425250d5e862c2015b76101747c0a4d2e139d67b9ee139a7871d078fe
-  data.tar.gz: '0759b4af994c2ef83c40abc10b7730b9e49350d3ceb8a74fa7f9be43cf373094b0056bfd35644b69a77bb04328176d9bd3994cadba1dabcc4f01abbf1054ff7f'
+  metadata.gz: da42001d35f67f6aa680b8b2b5f3cbc9ee020b537af8ba126ead44d76257d8f8f881afad501ecbce5c8c5fa7ebf65be59ccfb79f3d16ad2d5af5436288dd3c78
+  data.tar.gz: 680f9463a9f6540f03281fe4013251f83622811cfaff0a53bb1e9c47081720bc99f624be79ba86b0d9ce8031892c40f38cc140cf128711bc0cb0b800793ff4f8

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 ## [Unreleased]
 
+## [4.1.0] - 2026-09-17
+
+- [Feature] `account.visits.for_work`, the stops of jobs and of estimates together and the hours
+  held around them left unread. `/events` narrows by nothing, so reading blocked-out time costs
+  a sweep of every page on top of the two requests the work itself takes -- fifteen of them on
+  an account with 2,877 events. A caller that wants the work and not the holds now says so and
+  is spared them.
+
+- [Note] The vocabulary is `company` 3.1, where `for_work` is named. A platform that answers its
+  whole list at once gets the narrowing for free; this one pushes it down to the requests it
+  does not then make.
+
+## [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

@@ -118,8 +118,12 @@ for the stops of work alone:
 ```ruby
 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
+account.visits.upcoming(2.weeks).for_work  # => both kinds of stop, and no sweep
 ```
 
+`for_work` is the one to ask for where a caller wants the work and not the hours held around it:
+the jobs and the estimates are still read, and the fifteen requests of the sweep are not spent.
+
 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.
@@ -147,7 +151,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 +163,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 }
@@ -44,6 +44,10 @@ module Hcp
     # @return [Visits] the same list, read off the estimates alone: one request rather than many.
     def for_leads = with(jobs: false, events: false)
 
+    # @return [Visits] the same list, read off the work alone: two requests rather than the
+    #   fifteen a sweep of the calendar costs on top of them.
+    def for_work = with(events: false)
+
     # Work booked across the window carries every stop in it, so each list is read once and
     # what was called off keeps its stops to itself.
     # @yield [Company::Visit] each visit in the window, the work's stops before the hours

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.1.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.1.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '3.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '3.1'
 - !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