company 1.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae0aefa370989a019e2e09cc7b18c0eab239914cdc106a4fbea78dddb9941baf
-  data.tar.gz: d43aae90b600142a52a959f1e718ea22426d61efd72c5cbc859bd7a03cc7edae
+  metadata.gz: 0b4dad8d6bba939008a26107865489bc6aeb9a055d8cb73e58ae7b92c012521a
+  data.tar.gz: e0b15dbe81ec83a130beaac19d666f2d182476f20d7890f918e79d44afa8c847
 SHA512:
-  metadata.gz: 014dca594934dcf80080b7ca2ebccc6bcb4cfcfe7fe35cda73368dad8cca899f990f4dd77d00e0dfae67f3d5d8d23bee12416c0391d35ea0e9e7ebf975875589
-  data.tar.gz: 1e6d83ff533ee4ac149fb29bed71fe64be5464b383a0d33fa2e7cd8b5a1ac6a17956fab91074c97f5f18bf6474d4406b265488077a622e9f1feb37282cd911bc
+  metadata.gz: 8f20e43463498126a030dc4afb64c7ed1b12c7372329e15ba222acec3217005d919f2c054e2d0da1da797e961ef725f6bbc4580a9b765eb023dc2a555e650d62
+  data.tar.gz: 43dcfc1ecd909109e2169ba2ac419961a0cfce5a8b3bfe9c334a18569db501c9932adbb0152c427c293036721839826702a794d3064f7f3db32e65b793533bae

data/CHANGELOG.md

@@ -5,6 +5,42 @@ 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
+  than a technician, so one class answers `assigned_to`, `for_jobs` and `for_leads`. A gem
+  building one by hand passes a block where it passed `technician:`
+* [Feature] `Company::Technician` -- id, name, surname -- a person the business sends out, and
+  `Company::Account#technicians`, the crew of the business
+* [Feature] `Company::Visit#technicians`, whoever the stop is booked for
+* [Feature] `Company::Collection#assigned_to(technician)`, the same list narrowed to what one
+  technician is on. A gem answers it where its platform can put the question to the server;
+  where none can, `Company::Selection` walks the list and keeps what the technician turns out
+  to be on, so a week of one person's timeslots reads the same on every platform. Narrowing by
+  technician and narrowing to a window commute
+* [Feature] `Company::Visit#lead`, the lead a stop belongs to where it belongs to no job. A
+  visit is any booked time now, not only a job's: the stop to look at work nobody has priced
+  -- an assessment on Jobber, an estimate on Housecall Pro -- names a `lead` and no `job`, and
+  occupies a technician's day the same way. `Company::Quote` still means the price
+* [Feature] `Company::Lead#location`, where the work would happen, so a stop booked against a
+  lead says where to go the way a job's stop does
+* [Feature] `Company::Visits`, what a gem's list of visits subclasses: `create` books a stop
+  against a lead, taking the words `Leads#create` takes plus `starts_at:`, `ends_at:` and
+  `technicians:`, and `for_jobs` and `for_leads` narrow the list to one kind of stop
+
 ## 1.0.0 - 2026-09-09
 
 * [Feature] `Company::Account`, the gateway a set of credentials opens: a gem subclasses it

data/README.md

@@ -13,10 +13,10 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the `Gemfile`:
 
-    gem 'company', '~> 1.0'
+    gem 'company', '~> 2.0'
 
 Semantic Versioning promises that `~> major.minor` never crosses a breaking change, so the pin
-takes every 1.x release and stops short of 2.0.
+takes every 2.x release and stops short of 3.0.
 
 ## How it reads
 
@@ -70,7 +70,7 @@ customer.surname                         # => 'Qi'
 customer.email                           # => 'jane@example.com'
 customer.phone                           # => '5555555666'
 
-visits = account.visits.upcoming(1.day)  # => #<Acme::Visits>
+visits = account.visits.upcoming(1.day)  # => #<Acme::Visits>, stops of jobs and of leads
 visits.ids                               # => ['v1', 'v2', ...]
 
 visit = visits.first                     # => #<Acme::Visit>
@@ -79,7 +79,29 @@ 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
+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' },
+  description: 'Repair', notes: 'Estimate $20-$30', source: 'Website',
+  starts_at: 1.day.from_now, ends_at: 1.day.from_now + 1.hour, technicians: [technician]
+booked.lead                              # => #<Acme::Lead>, opened with the stop
+booked.lead.location                     # => #<Acme::Location>, where to go
+
+technician = account.technicians.first   # => #<Acme::Technician>
+technician.id                            # => 't1'
+technician.name                          # => 'Grace'
+technician.surname                       # => 'Hopper'
+
+week = account.visits.between(monday, sunday).assigned_to(technician)
+week.ids                                 # => ['v1', 'v2', ...]
 
 lead = account.leads.create name: 'Jane', surname: 'Qi', phone: '5555555666',
   email: 'jane@example.com', address: { street: '100 Acme Circle', zip: '98920' },
@@ -90,7 +112,19 @@ lead.customer                            # => #<Acme::Customer>
 
 A moment reads as a `Time`, an amount as dollars in a `BigDecimal`, a phone as the ten digits to
 dial, and a field the platform holds nothing for as nil. A list is walked a page at a time, as
-far as it goes or narrowed to a window measured from now.
+far as it goes or narrowed: to a window measured from now, to the technician the records are
+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: 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
 
@@ -115,7 +149,12 @@ 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. The least a gem writes is under `test/acme`, and the test that
+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.
 
 ## Errors

data/lib/company/account.rb

@@ -9,9 +9,12 @@ module Company
     # @return [Collection] jobs of the business, each a {Job}; a platform may also `find` one.
     def jobs = unanswered :jobs
 
-    # @return [Collection] visits of the business, each a {Visit}; a platform may also `find` one.
+    # @return [Visits] visits of the business, each a {Visit}; a platform may also `find` one.
     def visits = unanswered :visits
 
+    # @return [Collection] technicians of the business, each a {Technician}.
+    def technicians = unanswered :technicians
+
     # @return [Leads] leads of the business: `create` files one, where the platform takes leads.
     def leads = Leads.new
 

data/lib/company/collection.rb

@@ -1,7 +1,7 @@
 module Company
   # A list of records an account holds, walked however the platform pages it and narrowed to a
-  # window measured from now. A gem answers `each`, and `between` with the same list narrowed
-  # to what starts between two moments, either one open.
+  # window measured from now, or to one technician. A gem answers `each`, and `between` with
+  # the same list narrowed to what starts between two moments, either one open.
   class Collection
     include Enumerable
 
@@ -20,6 +20,23 @@ 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)
+      Selection.new(collection: self) do |record|
+        record.technicians.any? { |each| each.id == technician.id }
+      end
+    end
+
     # @return [Array<String>] ID of every record, the list walked; a platform with a cheaper
     #   way to ask answers it that way instead.
     def ids = map(&:id)

data/lib/company/collections/visits.rb

@@ -0,0 +1,32 @@
+module Company
+  # The visits of a business: every stop somebody is booked for, of a job or of a lead where
+  # the work is still being looked at. A gem answers `create` where its platform books a stop
+  # against a lead, and `for_jobs` or `for_leads` where it can ask its platform for one kind
+  # alone; where it cannot, the list is walked and the other kind let go.
+  class Visits < Collection
+    # Books a stop to look at work nobody has priced yet, opening the customer and whatever the
+    # platform hangs the stop off wherever it has none.
+    # @param name [String] given name of who asked, or the business's where a person has none.
+    # @param surname [String, nil] their surname.
+    # @param phone [String, nil] number they are reached on.
+    # @param email [String, nil] address they are written to.
+    # @param address [Hash, nil] where the work would happen: :street, :city, :state and :zip.
+    # @param description [String] what the work is called.
+    # @param notes [String, nil] what else was said about it.
+    # @param source [String, nil] where the lead came from, as the business names its sources.
+    # @param starts_at [Time] moment somebody is booked to arrive.
+    # @param ends_at [Time, nil] moment they are booked to leave, or nothing for the platform's.
+    # @param technicians [Array<Technician>] whoever is booked to go.
+    # @return [Visit] stop as the platform booked it.
+    def create(name:, surname:, phone:, email:, address:, description:, notes:, source:,
+      starts_at:, ends_at:, technicians:)
+      raise NotImplementedError, "#{self.class} does not book a visit"
+    end
+
+    # @return [Collection] the same list, narrowed to the stops of jobs.
+    def for_jobs = Selection.new(collection: self, &:job)
+
+    # @return [Collection] the same list, narrowed to the stops of leads.
+    def for_leads = Selection.new(collection: self, &:lead)
+  end
+end

data/lib/company/resources/lead.rb

@@ -6,5 +6,8 @@ module Company
 
     # @return [Customer, nil] customer the lead was filed for, where they came back beside it.
     def customer = record Customer, :customer
+
+    # @return [Location, nil] where the work would happen, where the platform named it.
+    def location = record Location, :location
   end
 end

data/lib/company/resources/technician.rb

@@ -0,0 +1,13 @@
+module Company
+  # A person the business sends out: whoever a visit is booked for.
+  class Technician < Resource
+    # What every technician reads, by the vocabulary's names.
+    def self.attributes = %i[id name surname]
+
+    # @return [String, nil] what they go by: a given name.
+    def name = attribute :name
+
+    # @return [String, nil] their surname.
+    def surname = attribute :surname
+  end
+end

data/lib/company/resources/visit.rb

@@ -1,5 +1,6 @@
 module Company
-  # One stop of a job: when the work is scheduled to happen, where the job does.
+  # 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]
@@ -16,7 +17,18 @@ 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, where it came back beside the visit.
+    # 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 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.
+    def technicians = records Technician, :technicians
   end
 end

data/lib/company/selection.rb

@@ -0,0 +1,22 @@
+module Company
+  # A list narrowed by something the platform could not be asked to narrow by: the list it came
+  # from is walked as it was, and only what the rule keeps comes through.
+  class Selection < Collection
+    # @param collection [Collection] list to walk.
+    # @yield [Resource] each record of it, to keep or to let go.
+    def initialize(collection:, &kept)
+      @collection = collection
+      @kept = kept
+    end
+
+    # @yield [Resource] each record the rule kept, in the order the list answered it.
+    def each
+      @collection.each { |record| yield record if @kept.call record }
+    end
+
+    # @param from [Time, nil] moment the window opens, or nothing for as far back as it goes.
+    # @param to [Time, nil] moment the window closes, or nothing for as far ahead as it goes.
+    # @return [Selection] the same rule, over the list narrowed to the window.
+    def between(from, to) = self.class.new(collection: @collection.between(from, to), &@kept)
+  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 = '1.0.0'
+  VERSION = '2.1.0'
 end

data/lib/company.rb

@@ -17,10 +17,13 @@ require 'company/errors/throttled'
 require 'company/phone'
 require 'company/resource'
 require 'company/collection'
+require 'company/selection'
 require 'company/collections/leads'
+require 'company/collections/visits'
 require 'company/account'
 require 'company/resources/business'
 require 'company/resources/customer'
+require 'company/resources/technician'
 require 'company/resources/location'
 require 'company/resources/line'
 require 'company/resources/lead'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: company
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -38,6 +38,7 @@ files:
 - lib/company/account.rb
 - lib/company/collection.rb
 - lib/company/collections/leads.rb
+- lib/company/collections/visits.rb
 - lib/company/error.rb
 - lib/company/errors/throttled.rb
 - lib/company/phone.rb
@@ -49,7 +50,9 @@ files:
 - lib/company/resources/line.rb
 - lib/company/resources/location.rb
 - lib/company/resources/quote.rb
+- lib/company/resources/technician.rb
 - lib/company/resources/visit.rb
+- lib/company/selection.rb
 - lib/company/version.rb
 homepage: https://github.com/claudiob/company
 licenses: