jbr 4.0.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 955de83498d3d68359199efa3e7b2d54bef89040000e80085969f4577e14d80d
-  data.tar.gz: 925c1785457c527ce3ad9dfe677a386327e70155f9895cccca6b51c278be758f
+  metadata.gz: cabf4447471fd3556e99cc05251c04a201f6329864d98d0650ba8506ff1dcc0a
+  data.tar.gz: 8149a10d060f9c265c82a482a53c3eb5646fcb744e41bd8ee136a4eb6b3b3cc5
 SHA512:
-  metadata.gz: 61ae3885b2ab939a53f5d27088957c7b230f55e6708440e603c8dafed5b369ef75e8430dcce5635d32962652f7bd3a6dea706f84f8ad7c46d45e865e242fff9a
-  data.tar.gz: 3945c08a563f06b43b3fd35f9aa579fa14ebeee8bc8468196a74f1cc4a38092dd429dbdfca118920f3a2f3a07e202ac9ac8a447409f9eeb042e826787d57abc8
+  metadata.gz: 770c8fe0d7556995d4484c51953aeb009f06046910d07a7153f1d40a302be2f65a510becbe5bf523375e927367bfe37acde4bc71382e4fe8807f14e0b9cb9c74
+  data.tar.gz: 4e479fa10591e9bee8d2cc1c30a79355329d1233410dde79f48a0d094944366ff61bcc6b4e9d582eed4f1bdab27d8b4a2650a8d3f04ac2f2611ad42eca515b56

data/CHANGELOG.md

@@ -1,5 +1,111 @@
 ## [Unreleased]
 
+## [6.0.0] - 2026-09-16
+
+- [Breaking change] The vocabulary is `company` 3.0: `assigned_to` is `of`, so
+  `account.visits.of(technician)` is what `account.visits.assigned_to(technician)` was. Jobber
+  still narrows it in the one filter, and it still needs no Users scope. The pin is `~> 3.0`.
+
+- [Note] `account.windows` -- the free time of a business -- raises `NotImplementedError` here,
+  and will until Jobber exposes the hours a business keeps. It does not today: the schema was
+  enumerated looking, and there is no `BusinessHours`, `WorkingHours`, `Shift` or `Weekday` type
+  of any kind, while `OnlineBookingConfiguration` is four fields and none of them is an hour.
+
+- [Note] Every setting around those hours is there, on `requestSettings`:
+  `intervalDurationMinutes` is the grain, `earliestAvailabilityMinutes` the notice,
+  `bufferDurationMinutes` the padding either side of a job, `efficientSchedulingType` and
+  `maxDriveTimeMinutes` whether travel counts. A caller can work free time out from those and
+  the visits. Read them off the form that books, not the one marked default, whose
+  `bookingType` may be `NONE`.
+
+## [5.0.0] - 2026-09-15
+
+- [Feature] A scope the app was never granted no longer raises. Jobber answers `An object of
+  type User was hidden due to permissions` and hides the object rather than the query, so
+  whatever came back beside it is kept: `account.technicians` answers `[]`, and a week asked
+  for with `includes(:technicians)` answers the week with nobody on it. `Jbr.logger` takes the
+  line saying which type to tick the scope for -- standard error until an app points it
+  somewhere better. Jobber codes this refusal not at all, so the words are the only signal, and
+  only those words are carried on from: anything else raises, an empty list being a poor place
+  to hide a fault.
+
+- [Breaking change] `account.visits.find` is gone. A visit arrives from the walk carrying
+  everything it reads, so looking one up again was a request spent to learn nothing -- and it
+  answered a job's stop alone, quietly finding nothing for an assessment, an event or a task.
+  `Enumerable#find` is what the name means on a list of visits now.
+
+- [Feature] `visit.location`, where a stop is, through `includes(:location)`. Jobber hangs the
+  property off each kind of scheduled item rather than off what they share, so it is selected
+  inside the fragments; a caller reading a schedule no longer reaches through `visit.job` for an
+  address, which a stop booked against a lead never had.
+
+- [Fix] A window asks for unassigned work and not for unscheduled. `schedulingAspects: [ALL]`
+  means both, so a windowed list came back carrying requests nobody had booked -- no start, no
+  end, in no window. `includeUnassigned: true` with `includeUnscheduled: false` asks for exactly
+  the half that is booked, verified against an account holding plenty of each.
+
+- [Breaking change] An event or a task is a visit. They occupy a pro exactly as a job's stop does
+  and were being read past unread. Jobber's scheduled item has exactly four kinds -- visit,
+  assessment, event, task -- so nothing is filtered out now; a reminder is named by the filter's
+  enum but is not a scheduled item and cannot come back. `visit.job` and `visit.lead` are nil on
+  an event, and `visit.location` may be: Jobber gives an event a property, and not always.
+
+- [Breaking change] The vocabulary is `company` 2.1: a `Company::Selection` takes its rule as a
+  block, a visit answers a lead as well as a job, and it says where it is. The pin is `~> 2.1`.
+
+- [Feature] The README says which Developer Center object each reader needs ticked. Jobber
+  files a visit under Scheduled Items -- one object covering visits, assessments, tasks and
+  calendar events -- and there is no Visits scope of its own.
+
+- [Feature] `account.visits.create` books a stop to go and look at work nobody has priced. It
+  takes the words `leads.create` takes plus `starts_at:`, `ends_at:` and `technicians:`, opens
+  the client and the property where Jobber has none, and files all of it in the one
+  `requestCreate`: Jobber hangs the assessment off the request it opens with it. What comes
+  back is the assessment Jobber stored, naming the request as its lead. Jobber has no source
+  for a request, so `source:` is dropped, and `ends_at:` may be nil for a stop booked to a day.
+
+  A mocked booking refuses a bare `Time` the same way, so a suite cannot pass on one Jobber
+  would not take. `starts_at:` must know its zone. Jobber takes a date, a local time and the zone they are in,
+  not a moment in UTC, and a bare `Time` names an offset rather than a zone -- so one is
+  refused, with `Jbr::Error`, before a client is opened.
+
+- [Breaking change] `account.visits` is every stop booked, not only a job's. Jobber calls the
+  stop booked to look at work before there is a job an assessment and hangs it off the request,
+  so `visit.lead` answers that request and `visit.job` is nil there; `for_jobs` and `for_leads`
+  narrow to one kind, by Jobber rather than here. The list is read from `scheduledItems` rather
+  than `visits`, which has three consequences worth reading twice:
+
+  - **A schedule is read by the window.** `scheduledItems` takes a required `occursWithin`, so
+    `account.visits` with nothing narrowing it raises `Jbr::Error` where it used to walk every
+    visit there was.
+  - **An open end reaches a year.** `occursWithin` takes two moments and no nil, so
+    `upcoming` and `past` with no duration are bounded at a year rather than left open.
+  - **Unassigned work is in.** `scheduledItems` answers assigned work only unless told
+    otherwise, so `includeUnassigned: true` is always sent. A list that did not send it would
+    quietly drop every stop nobody is on yet.
+
+  `account.visits.find` still answers a stop of a job alone: Jobber files an assessment under a
+  lookup of its own and this gem does not reach for it. Events, tasks and reminders share the
+  list and are read past, Jobber's filter taking one kind and not two.
+
+- [Feature] `account.technicians` walks the account's users a page at a time, each a
+  `Jbr::Technician` reading `id`, `name` and `surname` off the `name` node Jobber answers a
+  user with. Reading one needs the Users scope, which an app granted before this
+  release does not have: Jobber refuses a query selecting a user outright rather than leaving
+  the field empty, so an app that asks for a technician re-authorizes first.
+
+- [Feature] `visit.technicians` is whoever a visit is booked for, and `includes(:technicians)`
+  is what asks for them -- nothing brings them back unbidden, for the scope above and because
+  Jobber prices them on every row that carries them.
+
+- [Feature] `account.visits.between(from, to).assigned_to(technician)` is one technician's
+  week. `VisitFilterAttributes` takes an `assignedTo`, so the technician joins the window in
+  the one filter Jobber is sent: nobody else's visits are answered, paged or paid for, and the
+  crew is not read unless `includes(:technicians)` asks, which means `assigned_to` needs no
+  Users scope. Both narrowings land in the same filter, so either order asks the same
+  thing. `Jbr.mock.technicians` mocks the crew, and a mocked visit takes a `technicians:` of
+  its own.
+
 ## [4.0.0] - 2026-09-09
 
 - [Breaking change] `Jbr::Account` is the gateway, and reads in the vocabulary the `company` gem

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 'jbr', '~> 4.0'
+    gem 'jbr', '~> 5.0'
 
 Semantic Versioning promises that `~> major.minor` never crosses a breaking change, so the pin
-takes every 4.x release and stops short of 5.0.
+takes every 5.x release and stops short of 6.0.
 
 ## Available methods
 
@@ -104,6 +104,50 @@ account.query '{ ok }' # => {} once they are refused, raises Jbr::Error where Jo
 The app's own client ID and secret are read from `JOBBER_CLIENT_ID` and `JOBBER_CLIENT_SECRET`
 in the environment, and `Jbr::Account.client_secret` answers the one to check a webhook with.
 
+### Scopes
+
+Jobber has no scope parameter: an app is granted what its Developer Center page ticks, and a
+query selecting anything it was not granted is refused whole rather than answered with the one
+field empty. So a scope left unticked is not a nil somewhere, it is every query that touches it
+failing. What each reader here needs:
+
+| What a caller asks for | Object to tick |
+| --- | --- |
+| `account.jobs`, `job.lines` | Jobs |
+| `job.location`, `location.customer`, `visit.job` | Jobs and Clients |
+| `account.visits`, `of` | Scheduled Items |
+| `account.technicians`, `visit.technicians`, `includes(:technicians)` | Users |
+| `account.quotes` | Quotes |
+| `account.invoices` | Invoices |
+| `account.leads.create` | Requests and Clients, both writing |
+
+Jobber files a visit under **Scheduled Items**, which is one object covering visits,
+assessments, tasks and calendar events -- so there is no scope to add for the kinds of booked
+time this gem does not read yet.
+
+`of` is the one worth knowing: narrowing to a technician needs no Users, because
+Jobber does the narrowing and no user is ever selected. Reading *who* is on a visit is what
+needs it.
+
+The mapping above is read off what each query selects, not published by Jobber, so an app that
+is refused has one more object to tick than this table knows about. The names are the ones the
+Developer Center shows beside the checkboxes.
+
+An app that asks for what it was never granted is not left broken. Jobber answers
+`An object of type User was hidden due to permissions` and hides the object, so a reader added
+after an account authorized would otherwise take down every query carrying it:
+
+```ruby
+Jbr.logger = Rails.logger # standard error until an app names somewhere better
+account.technicians.to_a # => [], with a line in the log naming the type to tick the scope for
+account.visits.upcoming(1.week).includes(:technicians).to_a # => the week, with nobody on it
+```
+
+What Jobber hides is the object and not the query, so whatever came back beside it is kept: a
+list that asked for one thing too many still answers everything else it asked for. Jobber codes
+this refusal not at all, so the words are the only signal there is -- and only those words are
+carried on from. Anything else still raises: an empty list is a poor place to hide a fault.
+
 ### Leads
 
 File a request on the account's board, against the client answering to the phone and the
@@ -200,22 +244,133 @@ invoice.fulfilled_at # => 2026-05-22 14:32:53, when the job was finished, or the
 
 ### Visits
 
-Walk the account's visits, oldest first, the same way as its jobs, or reach one by ID:
+A visit is any booked time: somebody is out somewhere for an hour. A stop of a job is one. So is
+an *assessment*, the stop booked to go and look at work before there is a job, which Jobber hangs
+off the request -- the lead. So is an event or a task, an hour blocked out against nothing at all.
+All of them are scheduled items, all of them mean the pro is not free, and all are read from one
+list. Jobber has exactly four kinds -- a visit, an assessment, an event and a task -- so none is
+read past. A reminder is named by the filter's enum and is not a scheduled item at all, so it
+cannot come back.
+
+Where a stop is, is asked for: Jobber hangs the property off each kind rather than off what they
+share, and prices it per row, so `includes(:location)` is what turns it on.
 
 ```ruby
 account.visits.upcoming(3.months) # => only as far ahead as three months
 account.visits.upcoming.ids # => %w[Z2lkOi8vS ...], every page of them, and nothing else
 
-visit = account.visits.find 'Z2lkOi8vS'
+visit = account.visits.upcoming(1.week).first
 visit.id # => 'Z2lkOi8vS'
 visit.description # => 'Furnace tune-up', or nil where nobody titled it
 visit.starts_at # => 2026-08-09 14:00:00
 visit.ends_at # => 2026-08-09 16:00:00
 visit.anytime? # => false
 visit.confirmed? # => true, which Jobber alone asks a client
-visit.job.id # => 'Z2lkOi8vSm9i', the job the stop belongs to, where it happens and for whom
+visit.location # => where the stop is, where `includes(:location)` asked
+visit.job # => the job the stop belongs to, or nil where no job was booked for it
+visit.lead # => the request it was booked against, or nil where no lead was booked for it
+```
+
+Either kind alone is one question rather than two, asked of Jobber rather than sifted here:
+
+```ruby
+account.visits.upcoming(1.week).for_jobs  # => only the stops of jobs
+account.visits.upcoming(1.week).for_leads # => only the assessments
+```
+
+**A schedule is read by the window.** Jobber will not list a scheduled item without one, so
+`account.visits` with nothing narrowing it raises rather than walking every visit there ever
+was. `between`, `upcoming` and `past` all supply one. Jobber's window also takes two moments
+and no nil, so `upcoming` and `past` with no duration -- which on a list of jobs means as far
+as there is -- reach a year here, and no further.
+
+Book one to go and look at work nobody has priced, against the client answering to the phone
+and the property at the address, opening either where Jobber has none:
+
+```ruby
+monday = Time.find_zone('America/New_York').local(2026, 9, 21, 13)
+visit = account.visits.create name: 'Jane', surname: 'Doe', phone: '5553335555',
+  email: 'jane@example.com', address: { street: '1 Main St', city: 'Newark', zip: '07102' },
+  description: 'Look at the roof', notes: 'Ring twice', source: 'Website',
+  starts_at: monday, ends_at: monday + 1.hour, technicians: [technician]
+
+visit.id # => 'Z2lkOi8vSm9iYmVyL0Fzc2Vzc21lbnQv', the assessment Jobber filed
+visit.lead.id # => 'Z2lkOi8vSm9iYmVyL1JlcXVlc3Qv', the request it hangs off
+```
+
+One mutation files the lead, the hour and the crew, and what comes back is what Jobber stored
+rather than what it was asked for. Jobber has no source for a request, so `source:` is dropped.
+`ends_at:` may be nil, for a stop booked to a day rather than an hour.
+
+**`starts_at:` has to know its zone.** Jobber books in the words of whoever is going -- a date,
+a local time, and the zone they are in -- rather than the moment in UTC those come to. A bare
+`Time` names an offset, and an offset is not a zone: the same one stands for several, and none
+of them says when the clocks go back. So hand over a `Time.zone` moment; a `Time` is refused
+before anything is opened.
+
+### The schedule
+
+Jobber calls a technician a user, and reading one needs the Users scope. Without it
+Jobber refuses the whole query rather than the one field, so nothing asks who is on a visit
+unless a caller does. Narrowing *to* a technician needs no such scope -- only reading one back:
+
+```ruby
+technician = account.technicians.first
+technician.id, technician.name, technician.surname # => 'Z2lkOi8vVXNlc', 'Grace', 'Hopper'
+
+account.visits.includes(:technicians).upcoming.first.technicians # => [#<Jbr::Technician>, ...]
+```
+
+One technician's week is the visits in it narrowed to them:
+
+```ruby
+monday = Date.today.beginning_of_week.in_time_zone
+account.visits.between(monday, monday + 1.week).of(technician).each do |visit|
+  visit.starts_at, visit.ends_at, visit.job.id
+end
 ```
 
+Jobber narrows a list of visits by who is on it, so `of` puts the technician into the
+same filter as the window: nobody else's visits are answered, paged or paid for, and the crew
+is not read at all unless `includes(:technicians)` asks. The two narrowings land in the one
+filter, so a caller may ask for the week and the technician in either order.
+
+`of` therefore needs no Users scope. Reading *who* is on a visit does.
+
+## What Jobber cannot say
+
+`account.windows` -- the free time of a business, which the vocabulary names -- raises
+`NotImplementedError` here, and will go on doing so until Jobber exposes the hours a business
+keeps.
+
+It does not today. The whole schema was enumerated looking for it: there is no `BusinessHours`,
+`WorkingHours`, `OperatingHours`, `Shift`, `Weekday` or `DayOfWeek` type of any kind, and
+`OnlineBookingConfiguration` is four fields -- whether bookings are on, the URL, the embed
+script, the id. Jobber's own booking page must know the hours; the API does not say them.
+
+What it does say is every setting around them, on `requestSettings`:
+`intervalDurationMinutes` is the grain an offer is cut to, `earliestAvailabilityMinutes` the
+notice the business needs, `bufferDurationMinutes` the padding left either side of a job, and
+`efficientSchedulingType` with `maxDriveTimeMinutes` whether travel is counted as well. Read
+those beside the visits and a caller can work free time out for itself -- which is what the
+missing reader would have done. Take the settings from the form that books, not the one marked
+default: the default form may be a request form, whose `bookingType` is `NONE`.
+
+Raising is deliberate 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 the business
+altogether, with nothing in a log and no page looking wrong.
+
+A visit is still not all Jobber schedules. A task, an event and the two kinds of reminder sit
+on the same calendar and are read past unread, because Jobber's filter takes one kind and not
+two, so both the kinds that are visits are asked for and the rest let go as they arrive.
+
+One thing worth knowing about that list: `scheduledItems` answers assigned work only unless it
+is told otherwise, so every window carries `includeUnassigned: true` -- without it a week is
+quietly missing every stop nobody has been put on yet. It carries `includeUnscheduled: false`
+in the same breath, because asking for unassigned work through `schedulingAspects: [ALL]` is
+answered with unscheduled work as well: requests filed and never booked, with no hour to
+occupy and no place in any window.
+
 ### Locations and customers
 
 Jobber prices a query by what it brings back, so nothing nested comes back unless it is
@@ -260,7 +415,10 @@ decision belongs to whoever called: from a background job, letting it fail so th
 it back is better than a worker asleep holding a transaction open.
 
 Every connection the gem asks for is bounded, to keep a query on the affordable side of that:
-twenty lines to a job, and twenty jobs or visits to a page.
+twenty lines to a job, ten technicians to a visit, and twenty jobs, visits or technicians to a
+page, whichever kinds the page holds. Who is on a visit is priced on top of every row that
+carries it, so `includes(:technicians)` costs more per page -- which is why narrowing to one
+technician does not use it.
 
 `ids` is the cheap way to walk an account. It asks for the ID and nothing else, which prices
 a row at a fraction of a record and buys a hundred of them to a page. Reach for it where each
@@ -360,9 +518,22 @@ Jbr.mock.visits = [ { id: 'visit-01', description: 'Furnace tune-up',
   location: { id: 'property-01', street: '1 Main St',
     customer: { id: 'client-01', name: 'Jane' } },
   starts_at: Date.tomorrow.noon, ends_at: Date.tomorrow.end_of_day,
-  anytime: false, confirmed: true } ]
+  anytime: false, confirmed: true,
+  technicians: [ { id: 'user-01', name: 'Grace', surname: 'Hopper' } ] } ]
 ```
 
+### Technicians
+
+Mock the crew the account has:
+
+```ruby
+Jbr.mock.technicians = [ { id: 'user-01', name: 'Grace', surname: 'Hopper' } ]
+```
+
+A mocked `visits.create` reaches nobody and answers the hour and the crew it was handed, with
+`Jbr.mock.lead` for the lead it hangs off. It refuses a moment naming no zone exactly as Jobber
+does, so a suite cannot pass on a booking that could not be made.
+
 ### Invoices
 
 Mock successfully fetching an invoice:

data/lib/graphql/client.rb

@@ -34,7 +34,7 @@ module GraphQL
       coded = body['errors'].any? { |error| error.to_h.dig('extensions', 'code') == 'THROTTLED' }
       priced = available && cost['requestedQueryCost'].to_f > available.to_f
 
-      (coded || priced ? Throttled : Error).new refusal(body)
+      (coded || priced ? Throttled : Error).new refusal(body), data: body['data']
     end
 
     def refusal(body)

data/lib/graphql/error.rb

@@ -1,5 +1,15 @@
 module GraphQL
   # An error raised when a GraphQL request fails.
   class Error < StandardError
+    # @param message [String] what the API said went wrong.
+    # @param data [Hash, nil] what it answered alongside, where it answered anything: an API that
+    #   refuses one field of a query and fulfils the rest sends both at once.
+    def initialize(message = nil, data: nil)
+      super message
+      @data = data
+    end
+
+    # @return [Hash, nil] what came back beside the refusal, nil where nothing did.
+    attr_reader :data
   end
 end

data/lib/jbr/account.rb

@@ -40,6 +40,10 @@ module Jbr
     # @return [Visits] visits of the business.
     def visits = Visits.new account: self
 
+    # @return [Technicians] users of the business.
+    # @note Needs the Users scope, without which Jobber refuses the query rather than the field.
+    def technicians = Technicians.new account: self
+
     # @return [Quotes] quotes of the business, which Jobber alone lists.
     def quotes = Quotes.new account: self
 

data/lib/jbr/booking.rb

@@ -0,0 +1,56 @@
+module Jbr
+  # What a list of visits writes. Jobber files the stop booked to go and look at work as an
+  # assessment on the request it is opened with, so one mutation files the lead, the hour and
+  # the crew, and answers the stop as Jobber stored it rather than as it was asked for.
+  module Booking
+    # The mutation that opens a request with an assessment booked on it.
+    CREATE = <<~GRAPHQL
+      mutation($input: RequestCreateInput!) {
+        requestCreate(input: $input) {
+          request { id client { id } assessment { id title startAt endAt allDay } }
+          userErrors { message }
+        }
+      }
+    GRAPHQL
+
+    # Books a stop against the client answering to the phone and the property at the address,
+    # opening either where Jobber has none. Jobber has no source for a request, so that one is
+    # dropped, and it takes the hour in the technician's own words, so `starts_at:` must know
+    # the zone it is in: a bare Time names no zone and is refused.
+    # @return [Visit] stop as Jobber booked it, naming the lead it was booked against.
+    def create(name:, surname:, phone:, email:, address:, description:, notes:, source:,
+      starts_at:, ends_at:, technicians:)
+      booking = schedule starts_at, ends_at, technicians
+      customer = Customers.new(account: @account).find_or_create_by phone: phone, name: name,
+        surname: surname, email: email, address: address
+      property = Locations.new(account: @account).find_or_create_for customer, address
+      booked @account.query(CREATE, variables: { input: {
+        clientId: customer.id, propertyId: property, title: description,
+        assessment: { instructions: notes, schedule: booking },
+      } })
+    end
+
+  private
+
+    def booked(output)
+      request = output.dig 'requestCreate', 'request'
+      lead = { 'id' => request['id'], 'client' => request['client'] }
+      Visit.new node: request.fetch('assessment').merge('request' => lead)
+    end
+
+    def schedule(starts_at, ends_at, technicians)
+      { startAt: moment(starts_at), endAt: (moment(ends_at) if ends_at),
+        teamMemberIdsToAssign: technicians.map(&:id) }.compact
+    end
+
+    def moment(at)
+      { date: at.strftime('%Y-%m-%d'), time: at.strftime('%H:%M:%S'), timezone: zone_of(at) }
+    end
+
+    def zone_of(at)
+      return at.time_zone.tzinfo.name if at.respond_to? :time_zone
+
+      raise Error, "Jobber books #{at} in a named zone: hand over a Time.zone moment, not a Time"
+    end
+  end
+end

data/lib/jbr/collection.rb

@@ -2,13 +2,6 @@ module Jbr
   # A list of records read through the credentials, with what it was asked to bring back beside
   # each record and what it was narrowed to.
   class Collection < Company::Collection
-    # @param account [Account] credentials to reach Jobber with.
-    # @param includes [Hash] what to bring back beside each record, by name.
-    # @param filter [Hash, nil] what the list was narrowed to, in the shape Jobber filters by.
-    def initialize(account:, includes: {}, filter: nil)
-      @account = account
-      @includes = includes
-      @filter = filter
-    end
+    include Reading
   end
 end

data/lib/jbr/collections/jobs.rb

@@ -19,12 +19,12 @@ module Jbr
 
   private
 
-    def page = paged "#{FIELDS} #{selections}", PAGE
+    def page = paged row(FIELDS), PAGE
 
     def one
       <<~GRAPHQL
         query($id: EncodedId!) {
-          job(id: $id) { #{FIELDS} #{selections} }
+          job(id: $id) { #{row FIELDS} }
         }
       GRAPHQL
     end

data/lib/jbr/collections/technicians.rb

@@ -0,0 +1,17 @@
+module Jbr
+  # The users on a Jobber account, walked a page at a time. Reading one at all needs the Users
+  # scope; narrowing a list to one does not.
+  class Technicians < Collection
+    include Listable
+
+  private
+
+    def page = paged Technician::FIELDS, PAGE
+
+    def field = 'users'
+
+    def filtered = 'UsersFilterAttributes'
+
+    def item(node) = Technician.new node: node
+  end
+end

data/lib/jbr/collections/visits.rb

@@ -1,36 +1,61 @@
 module Jbr
-  # The visits on a Jobber account, oldest first, walked a page at a time.
-  class Visits < Collection
-    include Listable
-
-    # What a visit answers with: the keys the vocabulary reads, and the job it belongs to.
-    FIELDS = "#{Visit.node_keys.join ' '} job { id }"
-
-    # Shadows Enumerable#find on purpose, the way jobs do: a visit is reached by the ID Jobber
-    # files it under, not by asking every visit on the account whether it is the one.
-    # @param id [String] Jobber ID of the visit.
-    # @return [Visit, nil] nil when Jobber has no visit under that ID.
-    def find(id)
-      node = @account.query(one, variables: { id: id })['visit']
-      Visit.new node: node if node
+  # The visits on a Jobber account: the stops of its jobs, and the assessments booked to go and
+  # look at work before there is a job. Jobber files both as scheduled items and refuses to list
+  # one without a window, so a list nothing narrowed has none to give and says so.
+  class Visits < Company::Visits
+    include Reading, Scheduled, Includable, Listable, Booking
+
+    # How far an open end reaches. Jobber's window takes two moments and no nil, so a caller
+    # who named no end gets a year of one, which is a schedule rather than an archive.
+    HORIZON = 1.year
+
+    # @param from [Time, nil] the moment the window opens, or nothing for as far back as there is.
+    # @param to [Time, nil] the moment the window closes, or nothing for as far ahead as there is.
+    # @return [Visits] the same list, narrowed to what the window holds.
+    def between(from, to)
+      now = Time.now
+      narrowed occursWithin: { startAt: (from || now - HORIZON).iso8601,
+                               endAt: (to || now + HORIZON).iso8601 },
+        includeUnassigned: true, includeUnscheduled: false
+    end
+
+    # Jobber narrows a schedule by who is on it, so the technician joins the window in the one
+    # filter and nobody else's work is answered, paged or paid for.
+    # @param technician [Company::Technician] whoever the work is booked for.
+    # @return [Visits] the same list, narrowed to what they are booked for.
+    # @note Needs no Users scope: Jobber narrows, and no user is selected to do it.
+    def of(technician) = narrowed(assignedTo: [ technician.id ])
+
+    # @return [Visits] the same list, narrowed to the stops of jobs, by Jobber rather than here.
+    def for_jobs = narrowed(scheduleItemType: 'VISIT')
+
+    # @return [Visits] the same list, narrowed to the assessments, by Jobber rather than here.
+    def for_leads = narrowed(scheduleItemType: 'ASSESSMENT')
+
+    # @yield [Visit] each visit in the window, oldest first.
+    def each(&)
+      windowed
+      super
+    end
+
+    # @return [Array<String>] every ID in the window, every page of them read.
+    def ids
+      windowed
+      super
     end
 
   private
 
-    def page = paged FIELDS, PAGE
+    def windowed
+      return if @filter&.key? :occursWithin
 
-    def one
-      <<~GRAPHQL
-        query($id: EncodedId!) {
-          visit(id: $id) { #{FIELDS} }
-        }
-      GRAPHQL
+      raise Error, 'A Jobber schedule is read by the window: ask between, upcoming or past'
     end
 
-    def field = 'visits'
+    def page = paged row(fields), PAGE
 
-    def filtered = 'VisitFilterAttributes'
+    def field = 'scheduledItems'
 
-    def item(node) = Visit.new node: node
+    def filtered = 'ScheduledItemsFilterAttributes!'
   end
 end

data/lib/jbr/includable.rb

@@ -2,9 +2,10 @@ module Jbr
   # Extends a list of records with the chaining that says what to bring back beside them.
   # Nothing extra comes back unasked: a page costs what it carries.
   module Includable
-    # @param names [Array<Symbol, Hash>] :lines, :location, or location: :customer for whose
-    #   place it is.
+    # @param names [Array<Symbol, Hash>] :lines, :technicians, :location, or location: :customer
+    #   for whose place it is.
     # @return [Collection] the same list, asking Jobber for those too.
+    # @note :technicians needs the Users scope, which refuses the whole query where it is unticked.
     def includes(*names)
       named = names.each_with_object({}) do |name, all|
         name.is_a?(Hash) ? all.merge!(name) : all[name] = nil
@@ -14,11 +15,14 @@ module Jbr
 
   private
 
+    def row(fields) = [ fields, selections ].compact_blank.join ' '
+
     def selections = @includes.map { |name, nested| selection_of name, nested }.join ' '
 
     def selection_of(name, nested)
       case name
         when :lines then Line::SELECTION
+        when :technicians then Technician::SELECTION
         when :location then Location.selection customer: nested == :customer
       end
     end

data/lib/jbr/listable.rb

@@ -22,10 +22,7 @@ module Jbr
     # @param from [Time, nil] the moment the window opens, or nothing for as far back as it goes.
     # @param to [Time, nil] the moment the window closes, or nothing for as far ahead as it goes.
     # @return [Collection] the same list, narrowed to what starts between the two.
-    def between(from, to)
-      bounds = { after: from&.iso8601, before: to&.iso8601 }.compact
-      self.class.new account: @account, includes: @includes, filter: { startAt: bounds }
-    end
+    def between(from, to) = narrowed(startAt: { after: from&.iso8601, before: to&.iso8601 }.compact)
 
     # The ID Jobber files each record under, and nothing else about it: the cheapest question
     # an account can be walked with, and the one to ask where every record is then read on its
@@ -35,10 +32,17 @@ module Jbr
 
   private
 
+    # Every narrowing lands in the one filter Jobber takes, so asking for a week and asking for
+    # a technician compose whichever way round a caller writes them.
+    def narrowed(**more)
+      self.class.new account: @account, includes: @includes, filter: @filter.to_h.merge(more)
+    end
+
     def scheduled?(at)
-      return true unless @filter
+      bounds = @filter&.dig :startAt
+      return true unless bounds
 
-      after, before = @filter[:startAt].values_at :after, :before
+      after, before = bounds.values_at :after, :before
       return before.nil? unless at
 
       (after.nil? || at >= Time.iso8601(after)) && (before.nil? || at <= Time.iso8601(before))

data/lib/jbr/logger.rb

@@ -0,0 +1,13 @@
+require 'logger'
+
+module Jbr
+  class << self
+    # Where this gem says what it could not do, for the things it carries on from rather than
+    # raises. An app with a log of its own points this at it.
+    # @return [Logger] somewhere to write, standard error until an app names somewhere better.
+    def logger = @logger ||= Logger.new($stderr)
+
+    # @return [Logger] where to write.
+    attr_writer :logger
+  end
+end

data/lib/jbr/mock/account.rb

@@ -11,6 +11,9 @@ module Jbr
     # @return [Mock::Visits] visits the app listed.
     def visits = Mock::Visits.new account: self
 
+    # @return [Mock::Technicians] technicians the app listed.
+    def technicians = Mock::Technicians.new account: self
+
     # @return [Mock::Quotes] the one quote the app named.
     def quotes = Mock::Quotes.new
 

data/lib/jbr/mock/technicians.rb

@@ -0,0 +1,12 @@
+module Jbr
+  # The technicians an app under test asked {Jbr.mock} to answer with.
+  class Mock::Technicians < Technicians
+  private
+
+    def walk(_statement)
+      Enumerator.new do |yielder|
+        Jbr.mock.technicians.to_a.each { |node| yielder << Company::Technician.new(node: node) }
+      end
+    end
+  end
+end

data/lib/jbr/mock/visit.rb

@@ -3,5 +3,14 @@ module Jbr
   class Mock::Visit < Visit
     # The mock spells every key as the reader is named.
     def self.keys = {}
+
+    # @return [Array<Company::Technician>] whoever the app said the visit is booked for.
+    def technicians = records Company::Technician, :technicians
+
+    # @return [Company::Lead, nil] lead the app said the visit was booked against.
+    def lead = record Company::Lead, :lead
+
+    # @return [Company::Location, nil] where the app said the visit is.
+    def location = record Company::Location, :location
   end
 end

data/lib/jbr/mock/visits.rb

@@ -1,12 +1,16 @@
 module Jbr
   # The visits an app under test asked {Jbr.mock} to answer with. Only the walk is mocked:
-  # narrowing a list, and reading it as records or as IDs, is the same code a real one runs.
+  # narrowing a list, and reading it as records or as IDs, is the same code a real one runs,
+  # so a list nothing narrowed refuses here exactly as Jobber refuses it.
   class Mock::Visits < Visits
-    # @param id [String] ID the app filed the visit under.
-    # @return [Mock::Visit, nil] visit the app listed under that ID, nil where it listed none.
-    def find(id)
-      node = Jbr.mock.visits.to_a.find { |visit| visit[:id] == id }
-      Mock::Visit.new node: node if node
+    # Jobber will not book a moment that names no zone, so neither will this: an app whose
+    # tests pass a bare Time would otherwise only learn of it in production.
+    # @return [Mock::Visit] stop the app listed as its lead, booked for the hour asked for.
+    def create(starts_at:, ends_at:, technicians:, **)
+      zone_of starts_at
+      Mock::Visit.new node: { id: 'visit-01', starts_at: starts_at, ends_at: ends_at,
+                              technicians: technicians.map { |each| { id: each.id } },
+                              lead: Jbr.mock.lead.to_h, }
     end
 
   private
@@ -17,6 +21,31 @@ module Jbr
       end
     end
 
-    def selected = Jbr.mock.visits.select { |visit| scheduled? visit[:starts_at] }
+    def selected
+      Jbr.mock.visits.select do |visit|
+        scheduled?(visit[:starts_at]) && assigned?(visit) && kind?(visit)
+      end
+    end
+
+    def scheduled?(at)
+      window = @filter&.dig :occursWithin
+      return true unless window && at
+
+      at >= Time.iso8601(window[:startAt]) && at <= Time.iso8601(window[:endAt])
+    end
+
+    def assigned?(visit)
+      wanted = @filter&.dig :assignedTo
+      return true unless wanted
+
+      Array(visit[:technicians]).any? { |technician| wanted.include? technician[:id] }
+    end
+
+    def kind?(visit)
+      kind = @filter&.dig :scheduleItemType
+      return true unless kind
+
+      kind == 'VISIT' ? !visit[:job].nil? : !visit[:lead].nil?
+    end
   end
 end

data/lib/jbr/mock.rb

@@ -2,8 +2,8 @@ module Jbr
   # What an app under test wants Jobber to answer, by the vocabulary's names.
   class Mock
     # The canned answers, each read by the matching mock collection.
-    attr_accessor :business, :quote, :job, :invoice, :lead, :jobs, :visits, :oauth_url,
-      :oauth_error
+    attr_accessor :business, :quote, :job, :invoice, :lead, :jobs, :visits, :technicians,
+      :oauth_url, :oauth_error
   end
 
   class << self

data/lib/jbr/querying.rb

@@ -8,6 +8,12 @@ module Jbr
     # The version of the schema every statement is written against.
     HEADERS = { 'X-JOBBER-GRAPHQL-VERSION' => '2026-04-22' }
 
+    # How Jobber says the grant does not cover what was asked for: `An object of type User was
+    # hidden due to permissions`. It codes this one not at all, so the words are the only signal
+    # there is, and it names the type in them. An app granted its scopes before a reader existed
+    # would break on every query carrying that reader; this way it carries on a field short.
+    HIDDEN = /hidden due to permissions/
+
     # The mutation that revokes the app on the account.
     DISCONNECT = <<~GRAPHQL
       mutation Disconnect {
@@ -22,7 +28,8 @@ module Jbr
     # asking from a background job has a queue that will bring the whole job back later.
     # @param statement [String] query or mutation to run.
     # @param variables [Hash] what the statement takes.
-    # @return [Hash] data Jobber answered, or empty when the credentials are dead.
+    # @return [Hash] data Jobber answered: empty where the credentials are dead, and short of
+    #   whatever the grant does not cover, which Jobber hides rather than answers.
     # @raise [Throttled] where Jobber refused the statement for what it costs.
     # @raise [Error] where Jobber refused the statement, or took a mutation and would not act.
     def query(statement, variables: {})
@@ -36,7 +43,11 @@ module Jbr
     rescue GraphQL::Throttled => error
       raise Throttled, error.message
     rescue GraphQL::Error => error
-      raise Error, error.message
+      raise Error, error.message unless error.message.match? HIDDEN
+
+      Jbr.logger.warn 'Jobber hid what this app is not granted. Tick the scope for the type it ' \
+                      "names and have the account authorize again. #{error.message}"
+      error.data.to_h
     end
 
     # Revoke the credentials on the account. Dead ones have nothing left to revoke.

data/lib/jbr/reading.rb

@@ -0,0 +1,15 @@
+module Jbr
+  # What a list read through the credentials holds: what to reach Jobber with, what to bring
+  # back beside each record, and what the list was narrowed to. A list of visits answers the
+  # vocabulary's own {Company::Visits} rather than {Collection}, so the three live here.
+  module Reading
+    # @param account [Account] credentials to reach Jobber with.
+    # @param includes [Hash] what to bring back beside each record, by name.
+    # @param filter [Hash, nil] what the list was narrowed to, in the shape Jobber filters by.
+    def initialize(account:, includes: {}, filter: nil)
+      @account = account
+      @includes = includes
+      @filter = filter
+    end
+  end
+end

data/lib/jbr/resources/technician.rb

@@ -0,0 +1,19 @@
+module Jbr
+  # A person the business sends out, whom Jobber calls a user and whose name is a node of its
+  # own rather than two fields, so the vocabulary's keys would not fetch it.
+  class Technician < Company::Technician
+    # What Jobber answers a user with.
+    FIELDS = 'id name { first last }'
+
+    # What to ask for wherever a scheduled item names who it is booked for: ten, which is more
+    # than a stop is ever booked for. An app never granted the Users scope has the whole query
+    # refused rather than this field left empty, so nothing asks for it unbidden.
+    SELECTION = "assignedUsers(first: 10) { nodes { #{FIELDS} } }"
+
+    # @return [String, nil] what they go by: a given name.
+    def name = @node.dig :name, :first
+
+    # @return [String, nil] their surname.
+    def surname = @node.dig :name, :last
+  end
+end

data/lib/jbr/resources/visit.rb

@@ -13,5 +13,18 @@ module Jbr
 
     # @return [Boolean, nil] whether the client confirmed the visit.
     def confirmed? = attribute :confirmed
+
+    # Jobber calls the lead a request, and hangs the assessment booked to look at the work off
+    # it; a stop of a job names no request and a stop of a lead names no job.
+    # @return [Lead, nil] lead the stop belongs to, nil where the stop is a job's.
+    def lead = record Lead, :request
+
+    # Jobber hangs the property off each kind of scheduled item rather than off what they
+    # share, so it is asked for inside each and read back under Jobber's own name for it.
+    # @return [Location, nil] where the stop happens, where the query asked and Jobber has one.
+    def location = record Location, :property
+
+    # @return [Array<Technician>] whoever the stop is booked for, where the query asked.
+    def technicians = @node.dig(:assignedUsers, :nodes).to_a.map { Technician.new node: it }
   end
 end

data/lib/jbr/scheduled.rb

@@ -0,0 +1,36 @@
+module Jbr
+  # What Jobber files as a scheduled item, and how a list of them is asked for. Which kinds count
+  # as booked time lives here, and so does the awkward part: a scheduled item names no property
+  # and no job, so where a stop is and what it was booked for hang off each kind rather than off
+  # what they share, and are selected inside the fragments.
+  module Scheduled
+    # What every kind answers with. Jobber has four of them -- a visit, an assessment, an event
+    # and a task -- and every one is an hour somebody is out, so no kind is read past. A reminder
+    # is named by the filter's enum but implements nothing here, and cannot come back.
+    SHARED = 'id title startAt endAt allDay'
+
+  private
+
+    def fields
+      [ SHARED, kind('Visit', 'clientConfirmed job { id }'),
+        kind('Assessment', 'clientConfirmed request { id }') ].join ' '
+    end
+
+    def kind(name, own) = "... on #{name} { #{[ own, located ].compact_blank.join ' '} }"
+
+    # Included before Includable so this is found first: a location asked for is selected inside
+    # each kind's fragment by `kind`, and must not also be appended to what they share, where
+    # Jobber has no property to answer with.
+    def selection_of(name, nested)
+      return if name == :location
+
+      super
+    end
+
+    def located
+      Location.selection customer: @includes[:location] == :customer if @includes.key? :location
+    end
+
+    def item(node) = Visit.new node: node
+  end
+end

data/lib/jbr/version.rb

@@ -1,5 +1,5 @@
 # A Ruby client for the Jobber API.
 module Jbr
   # The version of this gem.
-  VERSION = '4.0.0'
+  VERSION = '6.0.0'
 end

data/lib/jbr.rb

@@ -1,10 +1,12 @@
 require 'json'
 require 'net/http'
 
-# The vocabulary every record here answers in, and the Active Support it brings along. One
-# more file of it: an address is sent without the fields a caller left blank.
+# The vocabulary every record here answers in, and the Active Support it brings along. Two
+# more files of it: an address is sent without the fields a caller left blank, and a window
+# with no end reaches a year out.
 require 'company'
 require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/integer/time'
 
 require 'graphql/error'
 require 'graphql/unauthorized'
@@ -12,6 +14,7 @@ require 'graphql/throttled'
 require 'graphql/client'
 
 require 'jbr/version'
+require 'jbr/logger'
 require 'jbr/error'
 require 'jbr/errors/refused'
 require 'jbr/errors/throttled'
@@ -28,17 +31,22 @@ require 'jbr/resources/customer'
 require 'jbr/resources/location'
 require 'jbr/resources/line'
 require 'jbr/resources/job'
+require 'jbr/resources/technician'
 require 'jbr/resources/visit'
 require 'jbr/resources/quote'
 require 'jbr/resources/invoice'
 require 'jbr/resources/lead'
 
 require 'jbr/reader'
+require 'jbr/reading'
 require 'jbr/collection'
 require 'jbr/includable'
 require 'jbr/listable'
+require 'jbr/scheduled'
+require 'jbr/booking'
 require 'jbr/collections/jobs'
 require 'jbr/collections/visits'
+require 'jbr/collections/technicians'
 require 'jbr/collections/quotes'
 require 'jbr/collections/invoices'
 require 'jbr/collections/customers'
@@ -49,6 +57,7 @@ require 'jbr/account'
 require 'jbr/mock/jobs'
 require 'jbr/mock/visit'
 require 'jbr/mock/visits'
+require 'jbr/mock/technicians'
 require 'jbr/mock/quote'
 require 'jbr/mock/quotes'
 require 'jbr/mock/invoice'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 6.0.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -125,6 +125,7 @@ files:
 - lib/jbr.rb
 - lib/jbr/account.rb
 - lib/jbr/authorizing.rb
+- lib/jbr/booking.rb
 - lib/jbr/collection.rb
 - lib/jbr/collections/customers.rb
 - lib/jbr/collections/invoices.rb
@@ -132,6 +133,7 @@ files:
 - lib/jbr/collections/leads.rb
 - lib/jbr/collections/locations.rb
 - lib/jbr/collections/quotes.rb
+- lib/jbr/collections/technicians.rb
 - lib/jbr/collections/visits.rb
 - lib/jbr/error.rb
 - lib/jbr/errors/refused.rb
@@ -139,6 +141,7 @@ files:
 - lib/jbr/event.rb
 - lib/jbr/includable.rb
 - lib/jbr/listable.rb
+- lib/jbr/logger.rb
 - lib/jbr/mock.rb
 - lib/jbr/mock/account.rb
 - lib/jbr/mock/invoice.rb
@@ -147,11 +150,13 @@ files:
 - lib/jbr/mock/leads.rb
 - lib/jbr/mock/quote.rb
 - lib/jbr/mock/quotes.rb
+- lib/jbr/mock/technicians.rb
 - lib/jbr/mock/visit.rb
 - lib/jbr/mock/visits.rb
 - lib/jbr/phone.rb
 - lib/jbr/querying.rb
 - lib/jbr/reader.rb
+- lib/jbr/reading.rb
 - lib/jbr/refreshing.rb
 - lib/jbr/resources/customer.rb
 - lib/jbr/resources/invoice.rb
@@ -160,7 +165,9 @@ files:
 - lib/jbr/resources/line.rb
 - lib/jbr/resources/location.rb
 - lib/jbr/resources/quote.rb
+- lib/jbr/resources/technician.rb
 - lib/jbr/resources/visit.rb
+- lib/jbr/scheduled.rb
 - lib/jbr/token.rb
 - lib/jbr/version.rb
 homepage: https://github.com/HouseAccountEng/jbr