hcp 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 796d536211d1039f154af0ea0340de4e814d9cf86c9009e60af68670dbc16cda
-  data.tar.gz: cd18b17cc8e162a750c998f5d554835d6982d75a7b417c4d60dc26dcfda9106a
+  metadata.gz: 3c2323d80d7ca73d0e62b6cef443bd2e40b803495df3ed0ad0d05fac2b5eb186
+  data.tar.gz: d908b99bcf637800fbc1bf0bc17bb777d06338e1ca51ae999981405ae717a59b
 SHA512:
-  metadata.gz: 1a6302bcfa3722c31caae3cc45d2bfb7d30c60895869c6a03fcc8d7851db99be8ad7f1b460d704f51a268e11fe2a78fef2e351186f9617f312d0ae759d0043e2
-  data.tar.gz: 65d2d60980d7386121a6f411f591398741fda04298a42d39102666b530ebd5239c4cfbe4297ea98d9d99721c2719505674440360551269352a52e0f2d69fceb3
+  metadata.gz: a93a05b7b4b3b0785661ab9104ac0a0ec88a4d18e43331fd49414c4ad8388e379806a01425250d5e862c2015b76101747c0a4d2e139d67b9ee139a7871d078fe
+  data.tar.gz: '0759b4af994c2ef83c40abc10b7730b9e49350d3ceb8a74fa7f9be43cf373094b0056bfd35644b69a77bb04328176d9bd3994cadba1dabcc4f01abbf1054ff7f'

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 ## [Unreleased]
 
+## [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
+  books an estimate for an hour and has no anytime to answer with, so the slot named none --
+  and a caller storing what a visit reads had a nil where it expected a yes or a no.
+
 ## [3.0.0] - 2026-09-15
 
 - [Breaking change] The vocabulary is `company` 2.1: a `Company::Selection` takes its rule as a

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

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.
@@ -35,27 +38,31 @@ module Hcp
       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/resources/estimate.rb

@@ -20,8 +20,8 @@ module Hcp
     # @return [nil] nothing, so a stop of one goes undescribed.
     def description = nil
 
-    # Housecall Pro files no ID on the slot, there being only ever the one, so it answers to
-    # the estimate's own.
+    # Housecall Pro files no ID on the slot, there being only ever the one, so it answers to the
+    # estimate's own, and books it for an hour rather than for any time in a day.
     # @return [Array<Visit>] the one slot the estimate is booked for, empty where it has none.
     def visits
       booked = @node.dig :schedule, :scheduled_start
@@ -36,8 +36,8 @@ module Hcp
   private
 
     def slot
-      { id: id, start_time: @node.dig(:schedule, :scheduled_start),
-        end_time: @node.dig(:schedule, :scheduled_end) }
+      { id: id, anytime: false, start_time: @node.dig(:schedule, :scheduled_start),
+        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.0'
+  VERSION = '3.1.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,10 +38,12 @@ 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/technicians'
 require 'hcp/account'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hcp
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.1'
+- !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,6 +154,7 @@ 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/error.rb
@@ -152,6 +167,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