hcp 3.0.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d401d8b087f9b1c05637aaad2f69c6f343ff3d8d50809c02d1b12f6d3fa2889
-  data.tar.gz: e58432a01d9530029c912b92451c9e94101dd8de0982ca072fb540572d14cbfb
+  metadata.gz: 6452e662bc00ffd31b8fa21a935de8c1b4ef9d4779a87668ce4f6b4c4585b3b0
+  data.tar.gz: e9e8e77e53671ef7e822f2116d32a231ab6f71901de418bdd8643acd46232de5
 SHA512:
-  metadata.gz: 9254b6d9c951494705a671b09484a8bef8586ca085e5a75b3101e66811179cdadd1239e6dd3598d80b9aa097bc0b6a9e7deb982351abc74c48de6f224a7320d8
-  data.tar.gz: 0afdf26a35fa1a7c36e8862d272e39590b02f1d7462393bc972379c6a51a32d7f210c02ff9a0788ef0b973bb02259063d489503abc2bbab43ddfe487b1fe5fc1
+  metadata.gz: 4b03d7602db5e603bd0b0ba03c9031fb93f29bece4d5984a460f0fb4f79b5d7a740de189c4c0d281919650f39f5bf84e4019d8cc5988630114aaec5a59fdab45
+  data.tar.gz: 38068b949e79d8c8c26bbfe07f5c75546f4f11964a4ec9259eaab168df458423be6eac7575a070ed7cb91b0a529d3a11d22b6f2d2605decf7ea39d25847ad0c4

data/CHANGELOG.md

@@ -1,5 +1,56 @@
 ## [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
+  files as events: a hold, a day off, an hour that is simply not free. It occupies a pro
+  exactly as a stop does, and Jobber has answered with it all along, so a schedule read through
+  this gem now says the same thing as one read through `jbr`. Each reads as a `Hcp::Occurrence`
+  standing on no job and no lead, and a caller that wants what it had before asks `for_jobs`.
+
+- [Feature] An event that repeats is stored by Housecall Pro once, as the hour it first takes
+  and the iCalendar rule it repeats by, so the hours after that are worked out here -- in the
+  time zone the event is kept in, so an hour that holds at ten in the morning still holds at
+  ten once the clocks have gone back rather than sliding to nine. `ice_cube` walks the rule;
+  it is a new runtime dependency, and the reason not to hand-roll one is that rule, DST and
+  month-end clamping together are where a hand-rolled walk quietly goes wrong.
+
+- [Feature] An hour answers to the event's ID and the moment it starts -- `evt_1@2026-09-18T14:15:00Z`
+  -- there being one ID for the whole rule and nothing else to tell two of its hours apart.
+
+- [Note] Housecall Pro narrows events by nothing. `/events` accepts `scheduled_start_min`,
+  `scheduled_start_max` and `employee_ids[]` and ignores all three, answering with the same
+  total every time, so a week is read by sweeping every page at 200 a page and keeping what the
+  week holds. On an account with 2,877 events that is 15 requests, which a nightly walk can
+  afford and a caller that only wants the stops of work should not pay: `for_jobs` and
+  `for_leads` now leave the sweep unasked.
+
+- [Note] An event carries an address but no ID for it, and leaves it empty on all but a
+  handful, so `visit.location` is nil on blocked-out time -- as it is in Jobber, where an event
+  carries no property either.
+
 ## [3.0.1] - 2026-09-15
 
 - [Fix] `visit.anytime?` answers false on an estimate's slot rather than nil. Housecall Pro

data/README.md

@@ -96,13 +96,24 @@ 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.job              # => the Hcp::Job the stop belongs to, nil on an estimate or an event
+  visit.lead             # => the Hcp::Estimate it belongs to, nil on a job or an event
   visit.technicians      # => the Hcp::Technicians the stop is booked for
 end
 ```
 
-The two cost a list each, so a caller that wants one kind asks for it and spends one request:
+Time blocked out around the work counts as booked too, and Housecall Pro files it as an event:
+a hold, a day off, an hour that is simply not free. An event that repeats is stored once, as the
+hour it first takes and the iCalendar rule it repeats by, so the hours after that are worked out
+here rather than read -- in the time zone the event is kept in, so an hour that holds at ten in
+the morning still holds at ten once the clocks have gone back. Each one reads as a visit
+standing on no job and no lead, and answers to the event's ID and the moment it starts, there
+being one ID for the whole rule.
+
+Housecall Pro narrows events by nothing -- it accepts a window and a crew on `/events` and
+ignores both -- so a week of them is read by sweeping every page and keeping what the week
+holds. That is the one expensive part of the list, and the one way to be spared it is to ask
+for the stops of work alone:
 
 ```ruby
 account.visits.upcoming(2.weeks).for_jobs  # => only the appointments, one request
@@ -136,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
 ```
@@ -148,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/occurrences.rb

@@ -0,0 +1,72 @@
+module Hcp
+  # The blocked-out time of one location: the hours Housecall Pro files as events rather than as
+  # work. It narrows events by nothing -- neither a window nor a crew, both of which it accepts
+  # and ignores -- so the only way to read a week of them is to sweep every page and keep what
+  # the week holds. An event that repeats is stored once, as the hour it first takes and the
+  # iCalendar rule it repeats by, so every hour after that is worked out here rather than read.
+  class Occurrences < Company::Collection
+    # How far an open end reaches. A rule that repeats forever has no last hour to walk to, so a
+    # caller who named no end gets a year of them, which is a schedule rather than an eternity.
+    HORIZON = 1.year
+
+    # @param client [Client] how to reach Housecall Pro as the location.
+    # @param from [Time, nil] the moment the window opens, or nothing for from now on.
+    # @param to [Time, nil] the moment the window closes, or nothing for a year of it.
+    def initialize(client:, from: nil, to: nil)
+      @client = client
+      @from = from
+      @to = to
+    end
+
+    # @param from [Time, nil] the moment the window opens, or nothing for from now on.
+    # @param to [Time, nil] the moment the window closes, or nothing for a year of it.
+    # @return [Occurrences] the same list, narrowed to the hours taken between the two.
+    def between(from, to) = self.class.new(client: @client, from: from, to: to)
+
+    # Nothing is read until the walk starts, and a page only once the one before it runs out.
+    # @yield [Occurrence] each stretch blocked out in the window, event by event.
+    def each
+      events { |event| hours_of(event).each { |node| yield Occurrence.new node: node } }
+    end
+
+  private
+
+    def events
+      (1..).each do |page|
+        body = @client.get 'events', page: page, page_size: Jobs::PAGE
+        body.fetch('events').each { |node| yield node }
+        break if page >= body.fetch('total_pages')
+      end
+    end
+
+    def hours_of(event)
+      schedule = event.fetch 'schedule'
+      first = Time.iso8601 schedule.fetch('start_time')
+      length = Time.iso8601(schedule.fetch('end_time')) - first
+      starts(event['recurrence_rule'], first, schedule['time_zone']).map do |moment|
+        event.merge 'id' => "#{event['id']}@#{moment.utc.iso8601}",
+          'start_time' => moment.utc.iso8601, 'end_time' => (moment + length).utc.iso8601
+      end
+    end
+
+    # An hour is repeated in the time zone the event is kept in rather than in UTC, so a rule
+    # that says ten in the morning still says ten once the clocks have gone back.
+    def starts(rule, first, zone)
+      return [ first ].select { |moment| window.cover? moment } if rule.blank?
+
+      repeated rule, first.in_time_zone(zone || 'UTC')
+    end
+
+    def repeated(rule, first)
+      schedule = IceCube::Schedule.new first
+      schedule.add_recurrence_rule IceCube::Rule.from_ical(rule)
+      schedule.occurrences_between opens, closes
+    end
+
+    def window = opens..closes
+
+    def opens = @from || Time.now
+
+    def closes = @to || opens + HORIZON
+  end
+end

data/lib/hcp/collections/visits.rb

@@ -9,13 +9,16 @@ module Hcp
     # @param technician [Company::Technician, nil] whose work to ask for, or nothing for all.
     # @param jobs [Boolean] whether to read the stops of jobs.
     # @param leads [Boolean] whether to read the stops of estimates.
-    def initialize(client:, from: nil, to: nil, technician: nil, jobs: true, leads: true)
+    # @param events [Boolean] whether to read the hours blocked out around them.
+    def initialize(client:, from: nil, to: nil, technician: nil, jobs: true, leads: true,
+      events: true)
       @client = client
       @from = from
       @to = to
       @technician = technician
       @jobs = jobs
       @leads = leads
+      @events = events
     end
 
     # @param from [Time, nil] the moment the window opens, or nothing for every visit there was.
@@ -28,34 +31,38 @@ 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 }
       end
     end
 
-    # @return [Visits] the same list, read off the jobs alone: one request rather than two.
-    def for_jobs = with leads: false
+    # @return [Visits] the same list, read off the jobs alone: one request rather than many.
+    def for_jobs = with(leads: false, events: false)
 
-    # @return [Visits] the same list, read off the estimates alone: one request rather than two.
-    def for_leads = with jobs: false
+    # @return [Visits] the same list, read off the estimates alone: one request rather than many.
+    def for_leads = with(jobs: false, 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 [Visit] each visit in the window, the jobs' stops before the estimates'.
+    # @yield [Company::Visit] each visit in the window, the work's stops before the hours
+    #   blocked out around them.
     def each(&)
       jobs.each { |job| stops job, & } if @jobs
       estimates.each { |estimate| stops estimate, & } if @leads
+      occurrences.each(&) if @events
     end
 
   private
 
     def with(**changed)
       self.class.new(**{ client: @client, from: @from, to: @to, technician: @technician,
-                         jobs: @jobs, leads: @leads }.merge(changed))
+                         jobs: @jobs, leads: @leads, events: @events, }.merge(changed))
     end
 
+    def occurrences = Occurrences.new(client: @client, from: @from, to: @to)
+
     def stops(work)
       return if work.canceled?
 

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/resources/estimate.rb

@@ -37,7 +37,7 @@ module Hcp
 
     def slot
       { id: id, anytime: false, start_time: @node.dig(:schedule, :scheduled_start),
-        end_time: @node.dig(:schedule, :scheduled_end) }
+        end_time: @node.dig(:schedule, :scheduled_end), }
     end
   end
 end

data/lib/hcp/resources/occurrence.rb

@@ -0,0 +1,21 @@
+module Hcp
+  # One stretch of blocked-out time: what a Housecall Pro event takes, once where the event
+  # happens once and once for every hour its rule lands on where it repeats. Housecall Pro files
+  # one ID for the whole rule rather than one per hour, so an hour answers to the event's ID and
+  # the moment it starts, which is the one thing telling two hours of the same event apart.
+  class Occurrence < Company::Visit
+    # The node keys Housecall Pro spells otherwise than the vocabulary.
+    def self.keys
+      { description: :name, anytime: :all_day, starts_at: :start_time, ends_at: :end_time }
+    end
+
+    # Housecall Pro files an address on an event but no ID for it, and leaves it empty on all
+    # but a handful, so there is nothing to file a place under: blocked-out time stands nowhere,
+    # as it does in Jobber, where an event carries no property either.
+    # @return [nil] nothing, so an hour blocked out is booked at no address.
+    def location = nil
+
+    # @return [Array<Technician>] whoever the hour is blocked out for.
+    def technicians = records Technician, :assigned_employees
+  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.0.1'
+  VERSION = '4.0.0'
 end

data/lib/hcp.rb

@@ -7,8 +7,15 @@ require 'time'
 # Housecall Pro holds nothing for arrives as readily empty as null, and a query is written the
 # way `to_query` writes one.
 require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/integer/time'
+require 'active_support/core_ext/numeric/time'
 require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/object/to_query'
+require 'active_support/core_ext/time/zones'
+
+# An event repeats by an iCalendar rule, which is walked rather than parsed here: an hour that
+# holds at ten in the morning either side of the clocks going back is not worth rewriting.
+require 'ice_cube'
 
 # The vocabulary the account answers in.
 require 'company'
@@ -31,11 +38,14 @@ require 'hcp/resources/location'
 require 'hcp/resources/line'
 require 'hcp/resources/quote'
 require 'hcp/resources/visit'
+require 'hcp/resources/occurrence'
 require 'hcp/resources/job'
 require 'hcp/resources/estimate'
 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.0.1
+  version: 4.0.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -29,14 +29,28 @@ 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
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -140,8 +154,10 @@ files:
 - lib/hcp/collections/estimates.rb
 - lib/hcp/collections/jobs.rb
 - lib/hcp/collections/leads.rb
+- 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
@@ -152,6 +168,7 @@ files:
 - lib/hcp/resources/lead.rb
 - lib/hcp/resources/line.rb
 - lib/hcp/resources/location.rb
+- lib/hcp/resources/occurrence.rb
 - lib/hcp/resources/quote.rb
 - lib/hcp/resources/technician.rb
 - lib/hcp/resources/visit.rb