hcp 4.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6452e662bc00ffd31b8fa21a935de8c1b4ef9d4779a87668ce4f6b4c4585b3b0
-  data.tar.gz: e9e8e77e53671ef7e822f2116d32a231ab6f71901de418bdd8643acd46232de5
+  metadata.gz: c68dd1ad565d18c93e6682c1e8d75598f3ef742d93c3e477c6a1bdd82f840fec
+  data.tar.gz: fe27f4cc519612a192baf591a5cabc458ea1d3e56ff5c4837ec6ad17a923c96d
 SHA512:
-  metadata.gz: 4b03d7602db5e603bd0b0ba03c9031fb93f29bece4d5984a460f0fb4f79b5d7a740de189c4c0d281919650f39f5bf84e4019d8cc5988630114aaec5a59fdab45
-  data.tar.gz: 38068b949e79d8c8c26bbfe07f5c75546f4f11964a4ec9259eaab168df458423be6eac7575a070ed7cb91b0a529d3a11d22b6f2d2605decf7ea39d25847ad0c4
+  metadata.gz: 2c83f06540c5cb55fbc276c8c8c565e52626ab5371fc4711b9a19332155fbc708faf9d8e9f7bf872c1f754410460a9b7a4c6e97dfd1c197fdd6705640907c3df
+  data.tar.gz: 66439b6015456b0110de1635c912f3c10827b77d850baeb9d49e12db49da012bc8be7962b705daed05885a7453ad7ef877a18b6c58e8983eb8b23cf844b0dc55

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## [Unreleased]
 
+## [5.0.0] - 2026-09-17
+
+- [Breaking change] The vocabulary is `company` 4.0: `of` takes the ID Housecall Pro files a
+  technician under rather than the technician, so `account.visits.of(technician.id)` is what
+  `account.visits.of(technician)` was, and the same for `account.windows`. The pin is `~> 4.0`.
+
+- [Note] The ID is the whole of what this gem ever narrowed by -- `employee_ids` on both lists,
+  and a comparison on the walk -- and taking it plainly is what stops a caller handing over a
+  record of its own whose `id` is not the one Housecall Pro knows. That has already happened
+  once, and Housecall Pro answered with everybody's free time rather than one person's.
+
+## [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

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).of(technician).each do |visit|
+account.visits.between(monday, monday + 1.week).of(technician.id).each do |visit|
   visit.starts_at, visit.ends_at, visit.job.location.street
 end
 ```
@@ -163,7 +167,7 @@ The other half of that week is the hours they are *not* out, which Housecall Pro
 itself and answers whole:
 
 ```ruby
-account.windows.between(monday, monday + 1.week).of(technician).each do |window|
+account.windows.between(monday, monday + 1.week).of(technician.id).each do |window|
   window.starts_at, window.ends_at
 end
 ```

data/lib/hcp/collections/visits.rb

@@ -6,7 +6,7 @@ module Hcp
     # @param client [Client] how to reach Housecall Pro as the location.
     # @param from [Time, nil] the moment the window opens, or nothing for every visit there was.
     # @param to [Time, nil] the moment the window closes, or nothing for every visit to come.
-    # @param technician [Company::Technician, nil] whose work to ask for, or nothing for all.
+    # @param technician [String, nil] ID of 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.
     # @param events [Boolean] whether to read the hours blocked out around them.
@@ -29,12 +29,12 @@ module Hcp
     # Housecall Pro narrows both lists by who is assigned to the work, so the window is asked
     # for as this technician's; a job's stop is the whole crew's until somebody is dispatched
     # 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 of(technician)
-      theirs = with technician: technician
+    # @param id [String] ID Housecall Pro files whoever the work is booked for under.
+    # @return [Company::Selection] the same list, narrowed to the visits they are booked for.
+    def of(id)
+      theirs = with technician: id
       Company::Selection.new(collection: theirs) do |visit|
-        visit.technicians.any? { |each| each.id == technician.id }
+        visit.technicians.any? { |technician| technician.id == id }
       end
     end
 
@@ -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
@@ -71,7 +75,7 @@ module Hcp
 
     def window = @from..@to
 
-    def crew = { employee_ids: (@technician && [ @technician.id ]) }
+    def crew = { employee_ids: (@technician && [ @technician ]) }
 
     def jobs
       bounds = { scheduled_end_min: @from&.utc&.iso8601, scheduled_start_max: @to&.utc&.iso8601 }

data/lib/hcp/collections/windows.rb

@@ -9,8 +9,8 @@ module Hcp
     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 technician [String, nil] ID of 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)
@@ -27,9 +27,9 @@ module Hcp
 
     # 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.
+    # @param id [String] ID Housecall Pro files whoever is free under.
     # @return [Windows] the same list, as that technician's alone.
-    def of(technician) = with(technician: technician)
+    def of(id) = with(technician: id)
 
     # 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
@@ -61,7 +61,7 @@ module Hcp
 
     def params
       { start_date: @from&.utc&.strftime('%Y-%m-%dT%H:%M:%S'), show_for_days: days,
-        employee_ids: (@technician && [ @technician.id ]), }.compact
+        employee_ids: (@technician && [ @technician ]), }.compact
     end
 
     def days = (@to && @from) ? ((@to - @from) / 1.day).ceil : DAYS

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 = '4.0.0'
+  VERSION = '5.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hcp
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: ice_cube
   requirement: !ruby/object:Gem::Requirement