company 2.1.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b4dad8d6bba939008a26107865489bc6aeb9a055d8cb73e58ae7b92c012521a
-  data.tar.gz: e0b15dbe81ec83a130beaac19d666f2d182476f20d7890f918e79d44afa8c847
+  metadata.gz: 25ecca18513633e93192c25059e8b94701440313c7d2c57c507cc82737bca5c7
+  data.tar.gz: 7dafceaf23f066daf45ab29d79de66a829843a0d70f2cfbd958e3b0d6a6c53e7
 SHA512:
-  metadata.gz: 8f20e43463498126a030dc4afb64c7ed1b12c7372329e15ba222acec3217005d919f2c054e2d0da1da797e961ef725f6bbc4580a9b765eb023dc2a555e650d62
-  data.tar.gz: 43dcfc1ecd909109e2169ba2ac419961a0cfce5a8b3bfe9c334a18569db501c9932adbb0152c427c293036721839826702a794d3064f7f3db32e65b793533bae
+  metadata.gz: 515ccd1ff8052f0d2ae739c6c86eeb5ab1d21b6324cae13dd83a1dc0e4793a99d30f117380efcb893e95f512993261370b542f73025c85e475f76e96b93ae16d
+  data.tar.gz: 5c91bb934528ac9e0cd8d392b2b16e9aff925ac97730f45af02930b5c2316a77a09c17c685c7a4b4b95527b42f3d60cdf1158ca071e073c347c07757a24d5b54

data/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 For more information about changelogs, check [Keep a Changelog](http://keepachangelog.com) and
 [Vandamme](http://tech-angels.github.io/vandamme).
 
+## 3.0.0 - 2026-09-16
+
+- [Breaking change] `Collection#assigned_to` is `Collection#of`. It read as it should on booked
+  time -- a visit is assigned to somebody -- and as it should not on free time, nobody being
+  assigned to an hour they are not working. `account.visits.of(technician)` and
+  `account.windows.of(technician)` both read as the possessive they are.
+
+- [Feature] `account.windows`, a `Company::Windows` of `Company::Window`: the free time of a
+  business, every stretch somebody could be sent out in, over the window asked for. A window
+  reads `starts_at` and `ends_at` and nothing else -- it names no work and nobody going, a list
+  of them having been narrowed to one technician already.
+
+- [Feature] A window is as long as it is, rather than cut into slots of a fixed size. Only the
+  caller making an offer knows how long the pieces it offers need to be, and a stretch stored
+  whole can still be cut, where one already cut cannot be put back together.
+
+- [Note] A platform that does not work free time out for itself raises `NotImplementedError`
+  from `windows`, and `Company::Windows#of` does the same, rather than answering with none. An
+  empty week and a fully booked one are the same shape, so a caller reading none as none would
+  quietly stop offering that business at all -- with nothing in a log and no page looking wrong.
+
 ## 2.1.0 - 2026-09-15
 
 * [Feature] `Company::Collection#includes(*names)`, what to bring back beside each record. A

data/README.md

@@ -100,9 +100,13 @@ technician.id                            # => 't1'
 technician.name                          # => 'Grace'
 technician.surname                       # => 'Hopper'
 
-week = account.visits.between(monday, sunday).assigned_to(technician)
+week = account.visits.between(monday, sunday).of(technician)
 week.ids                                 # => ['v1', 'v2', ...]
 
+free = account.windows.between(monday, sunday).of(technician)
+free.first.starts_at                     # => 2026-09-16 13:00:00 UTC
+free.first.ends_at                       # => 2026-09-16 17:00:00 UTC
+
 lead = account.leads.create name: 'Jane', surname: 'Qi', phone: '5555555666',
   email: 'jane@example.com', address: { street: '100 Acme Circle', zip: '98920' },
   description: 'Repair', notes: 'Estimate $20–$30', source: 'Website'
@@ -126,6 +130,15 @@ priced yet -- Jobber calls it an assessment, Housecall Pro an estimate -- names
 the same. `quote` stays the price, which is the other half of what Housecall Pro files as one
 record.
 
+A window is the other half of the same question: not the hours somebody is out, but the ones
+they are not. It names no work and nobody going, a list of them having been narrowed to one
+technician already, and it is as long as it is -- cut it into offerable pieces where an offer is
+being made, since only the caller making one knows how long it needs them to be.
+
+A platform that does not work free time out for itself answers `windows` with
+`NotImplementedError` rather than with none. An empty week and a fully booked one are the same
+shape, so a caller reading none as none would quietly stop offering that business at all.
+
 ## Answering as a gem
 
 A gem subclasses `Company::Account` and answers the readers its platform offers, and subclasses
@@ -151,7 +164,7 @@ end
 the platform for. A reader the gem leaves out raises `NotImplementedError` naming the gem; leads
 it leaves out refuse to file one, and so do the visits. `includes` a gem leaves out answers the
 same list: a platform that hands a record over whole has nothing to bring back beside it, so a
-caller names what it reads without knowing which kind of platform it is talking to. `assigned_to`,
+caller names what it reads without knowing which kind of platform it is talking to. `of`,
 `for_jobs` and `for_leads` a gem leaves out still answer: `Company::Selection` walks the list and lets through
 what the rule keeps, so only a platform that can put the question to its server writes the
 method, and only to save the requests the walk would spend. The least a gem writes is under `test/acme`, and the test that

data/lib/company/account.rb

@@ -15,6 +15,9 @@ module Company
     # @return [Collection] technicians of the business, each a {Technician}.
     def technicians = unanswered :technicians
 
+    # @return [Windows] free time of the business, each a {Window}, where the platform works it out.
+    def windows = unanswered :windows
+
     # @return [Leads] leads of the business: `create` files one, where the platform takes leads.
     def leads = Leads.new
 

data/lib/company/collection.rb

@@ -30,8 +30,8 @@ module Company
     # A platform that can ask its server for one technician's work narrows the list there; one
     # that cannot walks the list and keeps what the technician turns out to be on.
     # @param technician [Technician] whoever the work is booked for.
-    # @return [Collection] the same list, narrowed to what they are assigned to.
-    def assigned_to(technician)
+    # @return [Collection] the same list, narrowed to theirs.
+    def of(technician)
       Selection.new(collection: self) do |record|
         record.technicians.any? { |each| each.id == technician.id }
       end

data/lib/company/collections/visits.rb

@@ -28,5 +28,11 @@ module Company
 
     # @return [Collection] the same list, narrowed to the stops of leads.
     def for_leads = Selection.new(collection: self, &:lead)
+
+    # Booked time a platform can say something about: the stops of jobs and of leads together,
+    # without the hours blocked out around them, which name no work and cost a list of their own
+    # on a platform that files them apart.
+    # @return [Collection] the same list, narrowed to the stops of work of either kind.
+    def for_work = Selection.new(collection: self) { |visit| visit.job || visit.lead }
   end
 end

data/lib/company/collections/windows.rb

@@ -0,0 +1,16 @@
+module Company
+  # The free time of a business: every stretch somebody could be sent out in, over the window
+  # asked for. A platform that works it out answers this; one that does not know when its
+  # business is open cannot, and says so rather than answering with none, an empty list being
+  # the same shape as a fully booked week.
+  class Windows < Collection
+    # A window names nobody, a list of them having been narrowed to one technician already, so
+    # there is nothing here to walk and keep: only the platform can tell one person's free time
+    # from another's.
+    # @param technician [Technician] whose free time to answer.
+    # @return [Windows] the same list, as that technician's alone.
+    def of(technician)
+      raise NotImplementedError, "#{self.class} does not answer one technician's windows"
+    end
+  end
+end

data/lib/company/resources/window.rb

@@ -0,0 +1,16 @@
+module Company
+  # Free time: a stretch nobody is booked for, which somebody could be sent out in. It names no
+  # work and nobody going, a list of them having been asked for one technician already, and it
+  # is as long as it is -- cut it into offerable pieces where an offer is being made, since only
+  # the caller making one knows how long it needs them to be.
+  class Window < Resource
+    # What every window reads, by the vocabulary's names.
+    def self.attributes = %i[starts_at ends_at]
+
+    # @return [Time] moment the free stretch opens.
+    def starts_at = time :starts_at
+
+    # @return [Time] moment the free stretch closes.
+    def ends_at = time :ends_at
+  end
+end

data/lib/company/version.rb

@@ -1,5 +1,5 @@
 # The vocabulary two platform gems share: an account opens a business and the records it holds.
 module Company
   # The version of this gem, as RubyGems knows it.
-  VERSION = '2.1.0'
+  VERSION = '3.1.0'
 end

data/lib/company.rb

@@ -20,6 +20,7 @@ require 'company/collection'
 require 'company/selection'
 require 'company/collections/leads'
 require 'company/collections/visits'
+require 'company/collections/windows'
 require 'company/account'
 require 'company/resources/business'
 require 'company/resources/customer'
@@ -29,4 +30,5 @@ require 'company/resources/line'
 require 'company/resources/lead'
 require 'company/resources/quote'
 require 'company/resources/visit'
+require 'company/resources/window'
 require 'company/resources/job'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: company
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -39,6 +39,7 @@ files:
 - lib/company/collection.rb
 - lib/company/collections/leads.rb
 - lib/company/collections/visits.rb
+- lib/company/collections/windows.rb
 - lib/company/error.rb
 - lib/company/errors/throttled.rb
 - lib/company/phone.rb
@@ -52,6 +53,7 @@ files:
 - lib/company/resources/quote.rb
 - lib/company/resources/technician.rb
 - lib/company/resources/visit.rb
+- lib/company/resources/window.rb
 - lib/company/selection.rb
 - lib/company/version.rb
 homepage: https://github.com/claudiob/company