company 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed1f293ece38ef16d7b40c90e465a8c95dd66e4f722af9d01cff87cb78a2e793
-  data.tar.gz: b6c0d21d97439455d1cb50c751c3e8f8e4af13e406a0765d3b2f3f66c962c7c8
+  metadata.gz: 0b4dad8d6bba939008a26107865489bc6aeb9a055d8cb73e58ae7b92c012521a
+  data.tar.gz: e0b15dbe81ec83a130beaac19d666f2d182476f20d7890f918e79d44afa8c847
 SHA512:
-  metadata.gz: e337b418dee3bd35743e33a601624f51d1c8d438add6ddf90f1c692f23cf62c46b311010f92f33c39d94e0e3942e040f3709d80e2e6a6be45e91d4134ecd6243
-  data.tar.gz: 8d355dff05b2ddcb6447ab5f9eadd10e0129e51a2cfcc835a8d3801f2ea73bbec4fffed090fc2ed133ff888fb6da1a2e60cd547726afd33cc8999e7b42bf72da
+  metadata.gz: 8f20e43463498126a030dc4afb64c7ed1b12c7372329e15ba222acec3217005d919f2c054e2d0da1da797e961ef725f6bbc4580a9b765eb023dc2a555e650d62
+  data.tar.gz: 43dcfc1ecd909109e2169ba2ac419961a0cfce5a8b3bfe9c334a18569db501c9932adbb0152c427c293036721839826702a794d3064f7f3db32e65b793533bae

data/CHANGELOG.md

@@ -5,6 +5,19 @@ 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).
 
+## 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' },
@@ -114,10 +116,14 @@ 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.
 
 ## Answering as a gem
@@ -143,8 +149,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. `assigned_to`,
+`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/collection.rb

@@ -20,6 +20,13 @@ 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.

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/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 = '2.1.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: company
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Claudio Baccigalupo