company 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed1f293ece38ef16d7b40c90e465a8c95dd66e4f722af9d01cff87cb78a2e793
-  data.tar.gz: b6c0d21d97439455d1cb50c751c3e8f8e4af13e406a0765d3b2f3f66c962c7c8
+  metadata.gz: 49d635d99039ba1f2dd9e2fc68794b7430b49890b9ccfdacd34c420ed7d38e6d
+  data.tar.gz: 0d4e6da3fae824c5db9af413d5be87b94db532c336bccd1194896381eb5245cd
 SHA512:
-  metadata.gz: e337b418dee3bd35743e33a601624f51d1c8d438add6ddf90f1c692f23cf62c46b311010f92f33c39d94e0e3942e040f3709d80e2e6a6be45e91d4134ecd6243
-  data.tar.gz: 8d355dff05b2ddcb6447ab5f9eadd10e0129e51a2cfcc835a8d3801f2ea73bbec4fffed090fc2ed133ff888fb6da1a2e60cd547726afd33cc8999e7b42bf72da
+  metadata.gz: '0524899dee91ba36a54f37ca834cd770e27a202ae3b65e79efc7aeb9bb889697184ec186724a62c015f589a51e27c866aad7ef27c8dfebc3f67b62fbd491aa86'
+  data.tar.gz: ff4a532ba721b64b33bab772235c17c5f3ea2bdc15622c4cd9bd4e7b3ef9d361c15862cecc9f667b4d9b84f28f8fe8f4cae6d0b2f96c7dff828c562906479028

data/CHANGELOG.md

@@ -5,6 +5,40 @@ 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
+  platform that charges for what a row carries answers it by asking for more; one that hands a
+  record over whole has nothing to ask for and answers the same list. Either way a caller names
+  what it reads without knowing which kind of platform it is talking to, which a caller sharing
+  one code path across two of them could not do before
+* [Feature] `Company::Visit#location`, where the stop is. A schedule is read to know who is
+  where and when, so a visit says where without being asked what it was booked for, and a
+  caller no longer reaches through `visit.job` for an address -- which a stop booked against a
+  lead, or an hour blocked out against nothing, could never answer. `job` and `lead` say why a
+  visit exists and either may be absent; `location` may be too, for booked time that is nowhere
+
 ## 2.0.0 - 2026-09-15
 
 * [Breaking change] `Company::Selection` takes the rule to keep records by as a block rather

data/README.md

@@ -79,12 +79,14 @@ visit.description                        # => 'Service appointment'
 visit.starts_at                          # => 2026-09-10 01:00:00 UTC
 visit.ends_at                            # => 2026-09-10 02:00:00 UTC
 visit.anytime?                           # => false
-visit.job                                # => job, or nil where the stop is a lead's
-visit.lead                               # => lead, or nil where the stop is a job's
+visit.location                           # => #<Acme::Location>, or nil where it is nowhere
+visit.job                                # => job, or nil where no job was booked for it
+visit.lead                               # => lead, or nil where no lead was booked for it
 visit.technicians                        # => [#<Acme::Technician>, ...]
 
 visits.for_jobs                          # => only the stops of jobs
 visits.for_leads                         # => only the stops of leads
+visits.includes(location: :customer)     # => the same list, whatever the platform charges
 
 booked = account.visits.create name: 'Jane', surname: 'Qi', phone: '5555555666',
   email: 'jane@example.com', address: { street: '100 Acme Circle', zip: '98920' },
@@ -98,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'
@@ -114,12 +120,25 @@ far as it goes or narrowed: to a window measured from now, to the technician the
 booked for, or to one kind of stop. The narrowings compose in any order, so one technician's
 week reads the same whichever is asked for first.
 
-A visit is any booked time, not only work that is already a job. A stop to look at something
-nobody has priced yet -- Jobber calls it an assessment, Housecall Pro an estimate -- is a visit
-that names a `lead` and no `job`, and it occupies the technician's day exactly as a job's stop
-does. `quote` stays the price, which is the other half of what Housecall Pro files as one
+A visit is any booked time: somebody is somewhere for an hour. That is what a schedule is read
+for -- who is where, and when -- so a visit says where it is without being asked what it was
+booked for, and a caller never reaches through a job to find an address.
+
+`job` and `lead` answer *why*, and either may be absent. A stop to look at something nobody has
+priced yet -- Jobber calls it an assessment, Housecall Pro an estimate -- names a `lead` and no
+`job`. An hour blocked out on a calendar names neither, and occupies the technician's day just
+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
@@ -143,8 +162,10 @@ end
 
 `Company::Business.node_keys` then answers `[:id, :name, :phone_number]`: exactly what to ask
 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. `assigned_to`, `for_jobs` and
-`for_leads` a gem leaves out still answer: `Company::Selection` walks the list and lets through
+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. `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
 runs every reader through it, `test/company/acme_test.rb`, reads as a tutorial.

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

@@ -20,11 +20,18 @@ module Company
       between within && now - within, now
     end
 
+    # What to bring back beside each record, for a platform that charges for the asking. One
+    # that answers a record whole has nothing to ask for and answers the same list, so a caller
+    # names what it reads without knowing which kind of platform it is talking to.
+    # @param names [Array<Symbol, Hash>] what to read beside each record, as the gem names them.
+    # @return [Collection] the same list, bringing those back where that costs anything.
+    def includes(*names) = self
+
     # 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/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/visit.rb

@@ -1,6 +1,6 @@
 module Company
-  # One stop of a job, or of a lead where the work is still being looked at: when somebody is
-  # booked to be somewhere, and what they are booked for.
+  # Booked time: somebody is somewhere for an hour. Where it is, who is going and when are what
+  # a visit is for; the job or the lead it was booked against says why, and either may be absent.
   class Visit < Resource
     # What every visit reads, by the vocabulary's names.
     def self.attributes = %i[id description starts_at ends_at anytime]
@@ -17,10 +17,15 @@ module Company
     # @return [Boolean, nil] whether the visit may happen any time that day rather than at an hour.
     def anytime? = attribute :anytime
 
-    # @return [Job, nil] job the stop belongs to, nil where the stop is a lead's.
+    # A stop says where it is without being asked what it was booked for, so a caller reading a
+    # schedule never has to reach through a job to find an address.
+    # @return [Location, nil] where the work happens, nil where the stop is booked nowhere.
+    def location = record Location, :location
+
+    # @return [Job, nil] job the stop belongs to, nil where no job was booked for it.
     def job = record Job, :job
 
-    # @return [Lead, nil] lead the stop belongs to, nil where the stop is a job's.
+    # @return [Lead, nil] lead the stop belongs to, nil where no lead was booked for it.
     def lead = record Lead, :lead
 
     # @return [Array<Technician>] whoever the stop is booked for, where the platform names them.

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.0.0'
+  VERSION = '3.0.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.0.0
+  version: 3.0.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