company 0.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e465582abe5e308b1726c5ef497f03eb8186b9ff1b0a4952c8ff0aefc9489f7
-  data.tar.gz: e8597b7ad24485d5d4283fe4e89d3d2a575b21a54a6daf918036f21e12d81e64
+  metadata.gz: ed1f293ece38ef16d7b40c90e465a8c95dd66e4f722af9d01cff87cb78a2e793
+  data.tar.gz: b6c0d21d97439455d1cb50c751c3e8f8e4af13e406a0765d3b2f3f66c962c7c8
 SHA512:
-  metadata.gz: 9acc31b2a77ddc5ad521ac5c976bdb430439aec207918e52a5c3b03f4e6a070514f572f127713d8ac500d65ac634a9415e5c95227f31a6d35e15e41c67be6fe2
-  data.tar.gz: 5cbb020caabbc13e12b3535c4539de61c7c20b7a618de3f89283a67864a0e0051ba0f4720aff78ea6e8450658c2d2f72c33f954f5bab2eee84e139ee2c32fe52
+  metadata.gz: e337b418dee3bd35743e33a601624f51d1c8d438add6ddf90f1c692f23cf62c46b311010f92f33c39d94e0e3942e040f3709d80e2e6a6be45e91d4134ecd6243
+  data.tar.gz: 8d355dff05b2ddcb6447ab5f9eadd10e0129e51a2cfcc835a8d3801f2ea73bbec4fffed090fc2ed133ff888fb6da1a2e60cd547726afd33cc8999e7b42bf72da

data/CHANGELOG.md

@@ -5,7 +5,66 @@ 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).
 
-## [Unreleased]
+## 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
+  and answers `business`, `jobs`, `visits` and `leads` as its platform
+  offers them; a reader left out raises `NotImplementedError` naming the gem and the reader
+* [Feature] `Company::Collection`, what a list of an account's records is: `Enumerable`, and
+  narrowed to a window measured from now by `upcoming(within)` and `past(within)`, both built
+  on the `between(from, to)` a gem answers; `ids` walks it for the IDs unless a gem knows a
+  cheaper way
+* [Feature] `Company::Leads`, what files a lead: `create` takes the same words on every
+  platform -- name, surname, phone, email, address, description, notes, source -- and a gem
+  drops what its platform has no field for
+* [Feature] `Company::Business` -- id, name, phone, subsidiaries -- who the credentials belong to.
+  The subsidiaries are the business itself and then every business under it at any depth,
+  flat, so the list is never empty; a gem whose platform nests them answers the ones directly
+  under it from the private `below`
+* [Feature] `Company::Lead` -- id, customer -- and `Company::Quote` -- id, amount
+* [Feature] `Company::Job` -- id, quote, description, notes, created_at, scheduled_at,
+  completed_at, amount, lines, location. The moments answer as Times however the platform
+  wrote them and the amounts as dollars in a BigDecimal
+* [Feature] `Company::Line` -- id, name, description, quantity, amount -- a whole quantity read
+  whole
+* [Feature] `Company::Visit` -- id, description, starts_at, ends_at, anytime?, job
+* [Feature] `Company::Location` -- id, street, city, zip, latitude, longitude, customer -- and
+  `Company::Customer` -- id, name, surname, email, phone
+* [Feature] A record reads the node its platform answered under either kind of key; a kind
+  names its attributes, a subclass names under `.keys` the node keys its platform spells
+  otherwise -- `{ phone: :phone_number }` -- and `node_keys` answers them through the map, so
+  a gem builds its query from what the vocabulary reads
+* [Feature] A phone answers as the ten digits a North American number is, however the platform
+  wrote it, and as nil where none is held or none can be dialed
+* [Feature] `Company::Error`, what every error a platform gem raises descends from, and
+  `Company::Throttled`, what a platform raises where it holds a request to a rate and answers
+  the same question a little later
+
+The draft that had `Company` included the way `Enumerable` is, answering `read`, with an
+`Account` record and a `Company::Mock`, never shipped.
 
 ## 0.1.0 - 2026-08-28
 

data/README.md

@@ -1,6 +1,9 @@
 # Company
 
-Any company
+One vocabulary for the records a field-service business keeps, whichever platform keeps them.
+An account opens the business behind a set of credentials and the jobs, visits and leads it
+holds; a gem that speaks to one platform subclasses `Company::Account` and the kinds it answers
+for, and every reader is named here, once.
 
 ## How to install
 
@@ -10,16 +13,152 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the `Gemfile`:
 
-    gem 'company', '~> 0.1.0'
+    gem 'company', '~> 2.0'
 
-Below 1.0 the pin names the patch as well as the minor, so `bundle update` stops short of
-`0.2.0`. Semantic Versioning lets a `0.x` release break whatever it likes, and only promises
-otherwise once the major is real -- at which point the pin loosens to `~> 1.0`.
+Semantic Versioning promises that `~> major.minor` never crosses a breaking change, so the pin
+takes every 2.x release and stops short of 3.0.
+
+## How it reads
+
+Given a gem that answers the vocabulary -- call it Acme -- a caller never learns how Acme's
+platform spells a field, pages a list or counts its money:
+
+```ruby
+account = Acme::Account.new credentials  # => #<Acme::Account>
+
+business = account.business              # => #<Acme::Business>
+business.id                              # => '42'
+business.name                            # => 'Acme, Inc.'
+business.phone                           # => '5555555555'
+business.subsidiaries                    # => [#<Acme::Business>, ...]
+
+jobs = account.jobs.past(3.months)       # => #<Acme::Jobs>
+jobs.ids                                 # => ['j1', 'j2', ...]
+
+job = jobs.first
+job.id                                   # => 'j1'
+job.description                          # => 'Repair'
+job.notes                                # => 'Ring twice'
+job.created_at                           # => 2026-09-03 06:00:00 UTC
+job.scheduled_at                         # => 2026-09-10 01:00:00 UTC
+job.completed_at                         # => nil
+job.amount                               # => 19.99
+
+quote = job.quote                        # => #<Acme::Quote>, or nil where the job was won without one
+quote.id                                 # => 'q1'
+quote.amount                             # => 24.99
+
+line = job.lines.first                   # => #<Acme::Line>
+line.id                                  # => 'l1'
+line.name                                # => 'Labor'
+line.description                         # => 'Hours to fix the issue'
+line.quantity                            # => 1.5
+line.amount                              # => 24.99
+
+location = job.location                  # => #<Acme::Location>
+location.id                              # => 'a1'
+location.street                          # => '100 Acme Circle'
+location.city                            # => 'Springfield'
+location.zip                             # => '98920'
+location.latitude                        # => 45.2335
+location.longitude                       # => -9.1234
+
+customer = location.customer             # => #<Acme::Customer>
+customer.id                              # => 'c1'
+customer.name                            # => 'Jane'
+customer.surname                         # => 'Qi'
+customer.email                           # => 'jane@example.com'
+customer.phone                           # => '5555555666'
+
+visits = account.visits.upcoming(1.day)  # => #<Acme::Visits>, stops of jobs and of leads
+visits.ids                               # => ['v1', 'v2', ...]
+
+visit = visits.first                     # => #<Acme::Visit>
+visit.id                                 # => 'v1'
+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.technicians                        # => [#<Acme::Technician>, ...]
+
+visits.for_jobs                          # => only the stops of jobs
+visits.for_leads                         # => only the stops of leads
+
+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' },
+  description: 'Repair', notes: 'Estimate $20–$30', source: 'Website'
+lead.id                                  # => 'd1'
+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, 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, 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
+record.
+
+## Answering as a gem
+
+A gem subclasses `Company::Account` and answers the readers its platform offers, and subclasses
+a kind wherever its platform spells a key otherwise than the vocabulary:
+
+```ruby
+class Acme::Account < Company::Account
+  def business = Business.new node: read('company')
+  def jobs = Jobs.new account: self
+end
+
+class Acme::Business < Company::Business
+  def self.keys = { phone: :phone_number }
+end
+
+class Acme::Jobs < Company::Collection
+  def each = ...                     # walk the platform's pages, yielding a Job each
+  def between(from, to) = ...        # the same list, narrowed to what starts between the two
+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
+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
+
+Every error a gem raises descends from `Company::Error`, so one rescue catches the lot, and one
+for a request held to a rate from `Company::Throttled`, so one retry covers every platform.
 
 ## Development
 
 `bin/setup` gets a clone working, `bin/console` opens a prompt with the library loaded, and
-`bundle exec rake` runs the suite and the linter -- which is what CI runs too.
+`bundle exec rake` runs the suite, the linter and the two size limits -- which is what CI runs
+too.
 
 ## Reference
 

data/lib/company/account.rb

@@ -0,0 +1,25 @@
+module Company
+  # The gateway a set of credentials opens on a platform: the business they belong to and the
+  # records it holds. A gem subclasses it and answers what its platform offers; a reader it
+  # leaves out raises NotImplementedError, and the leads it leaves out refuse to file one.
+  class Account
+    # @return [Business] business the credentials belong to.
+    def business = unanswered :business
+
+    # @return [Collection] jobs of the business, each a {Job}; a platform may also `find` one.
+    def jobs = unanswered :jobs
+
+    # @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
+
+  private
+
+    def unanswered(name) = raise NotImplementedError, "#{self.class} does not answer #{name}"
+  end
+end

data/lib/company/collection.rb

@@ -0,0 +1,37 @@
+module Company
+  # A list of records an account holds, walked however the platform pages it and narrowed to a
+  # 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
+
+    # Both ends are measured from one moment, so nothing slides between them.
+    # @param within [ActiveSupport::Duration, nil] how far ahead to look, or as far as there is.
+    # @return [Collection] the same list, narrowed to what starts from now on.
+    def upcoming(within = nil)
+      now = Time.now
+      between now, within && now + within
+    end
+
+    # @param within [ActiveSupport::Duration, nil] how far back to look, or as far as there is.
+    # @return [Collection] the same list, narrowed to what started before now.
+    def past(within = nil)
+      now = Time.now
+      between within && now - within, now
+    end
+
+    # 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)
+  end
+end

data/lib/company/collections/leads.rb

@@ -0,0 +1,18 @@
+module Company
+  # The leads of a business: who asked it for work, before there is a job. A gem answers
+  # `create` with the lead its platform filed, dropping what the platform has no field for.
+  class Leads
+    # @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.
+    # @return [Lead] the lead as the platform filed it.
+    def create(name:, surname:, phone:, email:, address:, description:, notes:, source:)
+      raise NotImplementedError, "#{self.class} does not file a lead"
+    end
+  end
+end

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/error.rb

@@ -0,0 +1,5 @@
+module Company
+  # What every error a company raises descends from, so one rescue still catches the lot.
+  class Error < StandardError
+  end
+end

data/lib/company/errors/throttled.rb

@@ -0,0 +1,6 @@
+module Company
+  # Raised where a platform holds a request to a rate: the same question asked a little later
+  # is answered. Nothing here sleeps; a caller with a queue brings the whole job back.
+  class Throttled < Error
+  end
+end

data/lib/company/phone.rb

@@ -0,0 +1,14 @@
+module Company
+  # The ten digits a North American number is, whatever punctuation it arrived wearing.
+  class Phone
+    # Ten digits whose area code and exchange open with 2 through 9.
+    NANP = /\A[2-9]\d{2}[2-9]\d{6}\z/
+
+    # @param number [String, nil] number as the platform holds it.
+    # @return [String, nil] ten digits to dial, or nil where none is held or none can be dialed.
+    def self.from(number)
+      digits = number.to_s.delete('^0-9').delete_prefix '1'
+      digits if NANP.match? digits
+    end
+  end
+end

data/lib/company/resource.rb

@@ -0,0 +1,42 @@
+module Company
+  # What every record shares: the node the platform answered it as. Built by the gem that read
+  # it, never by a caller.
+  class Resource
+    # The node keys the platform spells otherwise than the vocabulary, by the reader they
+    # answer: `{ phone: :phone_number }` reads {Business#phone} off `phone_number`. A gem
+    # declares its own; a reader left out reads the key of its own name.
+    # @return [Hash] reader-to-key exceptions, empty where every name is its key.
+    def self.keys = {}
+
+    # The keys a platform is expected to answer a node with: each attribute the kind reads,
+    # through {.keys}, so a gem asks its platform for exactly these and writes none by hand.
+    # @return [Array<Symbol>] node keys, in the order the attributes are read.
+    def self.node_keys = attributes.map { |name| keys.fetch name, name }
+
+    # @param node [Hash] record as the platform answered it, under either kind of key.
+    def initialize(node: {})
+      @node = node.with_indifferent_access
+    end
+
+    # @return [String] ID the platform files the record under.
+    def id = attribute :id
+
+  private
+
+    def attribute(name) = @node[self.class.keys.fetch(name, name)]
+
+    def time(name)
+      value = attribute name
+      value.is_a?(String) ? (Time.iso8601 value if value.present?) : value
+    end
+
+    def decimal(name)
+      value = attribute name
+      BigDecimal value.to_s if value.present?
+    end
+
+    def record(type, key) = (type.new node: @node[key] if @node[key])
+
+    def records(type, key) = Array(@node[key]).map { |each| type.new node: each }
+  end
+end

data/lib/company/resources/business.rb

@@ -0,0 +1,24 @@
+module Company
+  # Who the account belongs to: the one business behind a set of credentials.
+  class Business < Resource
+    # What every business reads, by the vocabulary's names.
+    def self.attributes = %i[id name phone]
+
+    # @return [String] business name.
+    def name = attribute :name
+
+    # @return [String, nil] ten digits the business is reached on, nil where none can be dialed.
+    def phone = Phone.from attribute(:phone)
+
+    # Itself first, then every business under it at any depth, in the order the platform lists
+    # them: a business on its own is its own one subsidiary, and a franchise reads flat. A gem
+    # whose platform nests businesses answers the ones directly under this one from the private
+    # `below`; the rest inherit none.
+    # @return [Array<Business>] businesses an account may act as, this one included.
+    def subsidiaries = [ self, *below.flat_map(&:subsidiaries) ]
+
+  private
+
+    def below = []
+  end
+end

data/lib/company/resources/customer.rb

@@ -0,0 +1,19 @@
+module Company
+  # A person the business works for.
+  class Customer < Resource
+    # What every customer reads, by the vocabulary's names.
+    def self.attributes = %i[id name surname email phone]
+
+    # @return [String, nil] what they go by: a given name, or a business's where a person has none.
+    def name = attribute :name
+
+    # @return [String, nil] their surname.
+    def surname = attribute :surname
+
+    # @return [String, nil] address they are written to.
+    def email = attribute :email
+
+    # @return [String, nil] ten digits they are reached on, nil where none can be dialed.
+    def phone = Phone.from attribute(:phone)
+  end
+end

data/lib/company/resources/job.rb

@@ -0,0 +1,34 @@
+module Company
+  # Work the business accepted and scheduled.
+  class Job < Resource
+    # What every job reads, by the vocabulary's names.
+    def self.attributes = %i[id description notes created_at scheduled_at completed_at amount]
+
+    # @return [String, nil] what the work is called, in the words of whoever opened the job.
+    def description = attribute :description
+
+    # @return [String, nil] what was written on the job for the crew to mind.
+    def notes = attribute :notes
+
+    # @return [Time] moment the job was opened.
+    def created_at = time :created_at
+
+    # @return [Time, nil] moment the work is booked for.
+    def scheduled_at = time :scheduled_at
+
+    # @return [Time, nil] moment the work was finished.
+    def completed_at = time :completed_at
+
+    # @return [BigDecimal, nil] what the job comes to, in dollars.
+    def amount = decimal :amount
+
+    # @return [Quote, nil] quote the job was won with, where it came back beside the job.
+    def quote = record Quote, :quote
+
+    # @return [Array<Line>] lines the work is billed as, empty where none came back.
+    def lines = records Line, :lines
+
+    # @return [Location, nil] where the work happens, where it came back beside the job.
+    def location = record Location, :location
+  end
+end

data/lib/company/resources/lead.rb

@@ -0,0 +1,13 @@
+module Company
+  # Somebody who asked the business for work and is not a customer yet.
+  class Lead < Resource
+    # What every lead reads, by the vocabulary's names.
+    def self.attributes = %i[id]
+
+    # @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/line.rb

@@ -0,0 +1,25 @@
+module Company
+  # One line of a document: how many of a thing, what it is called, and what it comes to.
+  class Line < Resource
+    # What every line reads, by the vocabulary's names.
+    def self.attributes = %i[id name description quantity amount]
+
+    # @return [String, nil] what the line is called.
+    def name = attribute :name
+
+    # @return [String, nil] what the line says beyond what it is called.
+    def description = attribute :description
+
+    # A whole quantity reads as an Integer -- `3 Faucets` rather than `3.0 Faucets` -- and a
+    # fraction keeps its point, since rounding it would lie about what was billed.
+    # @return [Integer, Float, nil] how many of it the document is for.
+    def quantity = whole attribute(:quantity)
+
+    # @return [BigDecimal, nil] what the line comes to, in dollars.
+    def amount = decimal :amount
+
+  private
+
+    def whole(number) = number && ((number % 1).zero? ? number.to_i : number)
+  end
+end

data/lib/company/resources/location.rb

@@ -0,0 +1,25 @@
+module Company
+  # Where work happens: one address the business drives to.
+  class Location < Resource
+    # What every location reads, by the vocabulary's names.
+    def self.attributes = %i[id street city zip latitude longitude]
+
+    # @return [String, nil] street, number included.
+    def street = attribute :street
+
+    # @return [String, nil] town.
+    def city = attribute :city
+
+    # @return [String, nil] ZIP code.
+    def zip = attribute :zip
+
+    # @return [Numeric, nil] how far north the place is.
+    def latitude = attribute :latitude
+
+    # @return [Numeric, nil] how far east the place is.
+    def longitude = attribute :longitude
+
+    # @return [Customer, nil] whose place it is, where they came back beside the location.
+    def customer = record Customer, :customer
+  end
+end

data/lib/company/resources/quote.rb

@@ -0,0 +1,10 @@
+module Company
+  # A price the business sent a customer, which a job names where it was won with one.
+  class Quote < Resource
+    # What every quote reads, by the vocabulary's names.
+    def self.attributes = %i[id amount]
+
+    # @return [BigDecimal, nil] what the quote comes to, in dollars.
+    def amount = decimal :amount
+  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

@@ -0,0 +1,29 @@
+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.
+  class Visit < Resource
+    # What every visit reads, by the vocabulary's names.
+    def self.attributes = %i[id description starts_at ends_at anytime]
+
+    # @return [String, nil] what the stop is, in the words of whoever booked it.
+    def description = attribute :description
+
+    # @return [Time, nil] moment the visit is booked to start.
+    def starts_at = time :starts_at
+
+    # @return [Time, nil] moment the visit is booked to end.
+    def ends_at = time :ends_at
+
+    # @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.
+    def job = record Job, :job
+
+    # @return [Lead, nil] lead the stop belongs to, nil where the stop is a job's.
+    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,4 +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 = '0.1.0'
+  VERSION = '2.0.0'
 end

data/lib/company.rb

@@ -1,5 +1,32 @@
+require 'bigdecimal'
+require 'time'
+
 require 'company/version'
 
-# The namespace the company gem reserves for what it will hold.
-module Company
-end
+# Only the Active Support files whose methods are used: a name a platform holds nothing for
+# arrives as readily empty as null, a node reads under either kind of key, the lines of a job
+# join into one sentence, and a moment plus a duration is a moment.
+require 'active_support'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/array/conversions'
+require 'active_support/core_ext/numeric/time'
+
+require 'company/error'
+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'
+require 'company/resources/quote'
+require 'company/resources/visit'
+require 'company/resources/job'

metadata

@@ -1,15 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: company
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: A library to expose endpoint for a generic company
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: The records a field-service business holds, whichever platform holds
+  them
 email:
 - claudiob@users.noreply.github.com
 executables: []
@@ -20,6 +35,24 @@ files:
 - LICENSE.txt
 - README.md
 - lib/company.rb
+- 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
+- lib/company/resource.rb
+- lib/company/resources/business.rb
+- lib/company/resources/customer.rb
+- lib/company/resources/job.rb
+- lib/company/resources/lead.rb
+- 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:
@@ -36,7 +69,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3'
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="