jbr 3.13.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eff06d450e1e4c357e208ca25d49eec46229009623dac5fab0d2316784b10ddc
-  data.tar.gz: 85cd26058f5eec17b84f143e61c1d366f2ac7702d44d0cd8b6fb80694041f6d3
+  metadata.gz: 955de83498d3d68359199efa3e7b2d54bef89040000e80085969f4577e14d80d
+  data.tar.gz: 925c1785457c527ce3ad9dfe677a386327e70155f9895cccca6b51c278be758f
 SHA512:
-  metadata.gz: 8cef0ee9b3d02ec476d890d6d34367d896e77ab374fa75f923d77fb6535415c3958c43aefea6ee7512e09606eb75cf92583c8c0ddf79e2ccf7d111b49a858af4
-  data.tar.gz: 1bdaf92404d72cf9ad5abaf26711e9cba47fa0054e1ab1e4b53114bfe0d157ed073959783ef8a23cdf101ac6ea95da798ca0e4723ffb06d907600b3857018aef
+  metadata.gz: 61ae3885b2ab939a53f5d27088957c7b230f55e6708440e603c8dafed5b369ef75e8430dcce5635d32962652f7bd3a6dea706f84f8ad7c46d45e865e242fff9a
+  data.tar.gz: 3945c08a563f06b43b3fd35f9aa579fa14ebeee8bc8468196a74f1cc4a38092dd429dbdfca118920f3a2f3a07e202ac9ac8a447409f9eeb042e826787d57abc8

data/.rubocop.yml

@@ -57,3 +57,8 @@ Layout/LineLength:
 # lines per site, so the cop is declined and the rule held in review.
 Style/MethodCallWithArgsParentheses:
   Enabled: false
+
+# The vocabulary names a keyword for every platform, and one a platform has no field for is
+# taken and dropped rather than left out of the signature
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true

data/CHANGELOG.md

@@ -1,3 +1,54 @@
+## [Unreleased]
+
+## [4.0.0] - 2026-09-09
+
+- [Breaking change] `Jbr::Account` is the gateway, and reads in the vocabulary the `company` gem
+  names. It replaces `Jbr::OAuth` and the `Jbr.oauth_for`, `Jbr.create_oauth` and
+  `Jbr.oauth_url_for` entry points: `Jbr::Account.new credentials`, `Jbr::Account.create code:,
+  redirect_uri:`, `Jbr::Account.url_for redirect_uri:, state:`, and `Jbr::Account.client_secret`.
+  `#account` is `#business`, answering a `Company::Business` whose `phone` is the ten digits to
+  dial rather than the string Jobber holds
+- [Breaking change] `#requests` is `#leads`, and `leads.create` takes its keywords by name
+  as the vocabulary names them (`name:`, `surname:`, `phone:`, `email:`, `address:`,
+  `description:` for the title, `notes:` for the instructions, and a `source:` Jobber has no
+  field for) and
+  answers a `Jbr::Lead` with `id` and `customer` rather than the collection that filed it.
+  `Quote#request_id` is `#lead`, a `Jbr::Lead`; `Invoice#job_id` is `#job`, a `Jbr::Job`;
+  `Invoice#total`, `#issued_at` and `#completed_at` are `#amount`, a `BigDecimal`, and
+  `#fulfilled_at`, the moment the work was finished or the bill issued where the work never was
+- [Breaking change] A job reads `#amount` as a `BigDecimal` where it read `#total` as a Float,
+  answers the quote it was won with as `#quote` -- a `Jbr::Quote` with `id` and `amount`,
+  nil where there was none -- in place of `#quote_id` and `#quote_total`, its title as
+  `#description` and its instructions as `#notes`. `#summary` is gone with `#name`: a caller sums a job up from its lines and
+  its description. `Job#title`, `#status` and `#client`, `Visit#title`, `#name`, `#job_id`
+  and `#client`, are gone, and `Visit#client_confirmed?` is `#confirmed?`, `#all_day?` is `#anytime?`
+- [Breaking change] `includes` takes `:lines`, `:location` and `location: :customer` where it
+  took `:line_items`, `:property`, `:client` and `property: :client`, and only on jobs: a visit
+  happens where its job does, so it answers `#job` and no `#location` or `includes` of its own. A
+  job answers `#lines` and `#location`, and a location `#customer`. `Location#address` and `#state` are gone,
+  as are `Customer#first_name` and `#company_name`: `#name` answers the first name, or the
+  business's name where a person has none. `Jbr::LineItem`, `Jbr::Property`, `Jbr::Client` and
+  `Jbr::Request` are `Jbr::Line`, `Jbr::Location`, `Jbr::Customer` and `Jbr::Lead`
+- [Breaking change] `Jbr.mock` takes `business` and `lead` where it took `account` and `request`,
+  and every slot reads by the vocabulary's keys: `description`, `amount`, `quote`,
+  `lines`, `location`, `customer`, `confirmed`, `lead`, `job`. A mock collection
+  answers the vocabulary's own kinds built from those hashes, so `Jbr::Mock::Job` and its
+  siblings are gone; `Jbr.mock = nil` hands the accounts back to Jobber
+- [Breaking change] `Jbr::Retriable` is `Jbr::Throttled`, a `Company::Throttled` rather than a
+  `Jbr::Error`, so one rescue retries a refusal for rate from any platform; its `#cost`,
+  `#available`, `#maximum` and `#restore_rate` are gone and the numbers stay in the message.
+  `Jbr::Error` descends from `Company::Error`
+- [Fix] An `includes` chained after `past` or `upcoming` keeps the window it was asked on. It
+  used to rebuild the list without the filter, so `account.jobs.past(1.year).includes(:lines)`
+  walked every job the account ever had
+- [Fix] A mutation Jobber takes but will not act on raises `Jbr::Error` with the reasons Jobber
+  gave. It answers those with a 200 and the messages under the mutation's own `userErrors`,
+  which nothing read, so a client Jobber refused to open came back with a nil ID and the
+  request filed against nobody
+- [Change] Every selection Jobber is asked for is generated from the keys the vocabulary reads
+  wherever Jobber's shape is flat, so a kind gaining a reader asks for it without a query
+  written by hand
+
 ## [3.13.0] - 2026-08-31
 
 - [New] `Jbr::LineItem#id`, `#description` and `#amount`, beside the `#quantity` and `#name` a

data/README.md

@@ -1,7 +1,22 @@
 # Jobber API Ruby client
 
-A client for the Jobber GraphQL API. It needs the standard library and two files of Active
-Support, to tell a field Jobber answered empty from one it never answered at all.
+A client for the Jobber GraphQL API, answering in the vocabulary the
+[company](https://github.com/claudiob/company) gem names: an account opens the business its
+credentials belong to and the records the business holds, and each record reads by the same
+names on Jobber as on any other platform.
+
+## How to install
+
+To install on your system, run
+
+    gem install jbr
+
+To use inside a bundled Ruby project, add this line to the `Gemfile`:
+
+    gem 'jbr', '~> 4.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.
 
 ## Available methods
 
@@ -10,28 +25,27 @@ Support, to tell a field Jobber answered empty from one it never answered at all
 Generate the URL for Jobber users to authorize the app:
 
 ```ruby
-url = Jbr.oauth_url_for redirect_uri:, state:
+url = Jbr::Account.url_for redirect_uri:, state:
 url # => 'https://api.getjobber.com/api/oauth/authorize?state=...&redirect_uri=...'
 ```
 
-Create credentials with a code and a redirect URI:
+Create an account with the code Jobber sends back and the URI it sent it to:
 
 ```ruby
-oauth = Jbr.create_oauth code:, redirect_uri:
+account = Jbr::Account.create code:, redirect_uri:
 ```
 
-Initialize with existing credentials:
+Open an account with credentials already on file:
 
 ```ruby
-oauth = Jbr.oauth_for access_token:, refresh_token:, expires_at:, account_id:
+account = Jbr::Account.new access_token:, refresh_token:, expires_at:, account_id:
 ```
 
-Where several processes hold copies of the same credentials — a queue of workers, each
-building its own — hand over a `store:` as well, and only one of them will ever spend the
-refresh token:
+Where several processes hold copies of the same credentials, a queue of workers each building
+its own, hand over a `store:` as well, and only one of them will ever spend the refresh token:
 
 ```ruby
-oauth = Jbr.oauth_for account_id:, invalid_at:, store: credentials
+account = Jbr::Account.new account_id:, invalid_at:, store: credentials
 ```
 
 The store is anything answering two methods. `exclusively` takes whatever lock the app keeps
@@ -39,73 +53,82 @@ over those credentials and yields them *as they are right now*, read inside that
 records the ones Jobber handed back:
 
 ```ruby
-def exclusively = with_lock { yield oauth_params }   # Active Record, in an app that has it
+def exclusively = with_lock { yield tokens }   # Active Record, in an app that has it
 
-def write(oauth) = update oauth: oauth
+def write(account) = update tokens: { access_token: account.access_token, ... }
 ```
 
 An expired access token is then refreshed once. Every other holder takes the lock, finds a
-token that is no longer the one it tried, adopts it, and asks Jobber nothing — where without a
-store each of them would spend a refresh token the first has already spent, and Jobber would
-call every one of those a dead grant.
+token that is no longer the one it tried, adopts it, and asks Jobber nothing. Without a store
+each of them would spend a refresh token the first has already spent, and Jobber would call
+every one of those a dead grant.
 
 `exclusively` has to be exclusive against every **process** sharing the credentials, not just
 every thread: a `Mutex` satisfies this interface and fixes nothing on a fleet of workers.
 
-Access OAuth attributes:
+Read the credentials as Jobber last gave them:
 
 ```ruby
-oauth.access_token # => 'eyJhbGciOiJIUzI1NiJ'
-oauth.refresh_token # => 'ea02775958c5fca28d'
-oauth.expires_at # => 2026-05-22 14:32:53
-oauth.account_id # => 'Z2lkOi8vSm9iYmV'
+account.access_token # => 'eyJhbGciOiJIUzI1NiJ'
+account.refresh_token # => 'ea02775958c5fca28d'
+account.expires_at # => 2026-05-22 14:32:53
+account.account_id # => 'Z2lkOi8vSm9iYmV'
 ```
 
-Read the account they belong to, once, however much of it is asked for:
+Read the business they belong to:
 
 ```ruby
-account = oauth.account
-account.id # => 'Z2lkOi8vSm9iYmV'
-account.name # => 'Acme Plumbing'
-account.phone # => '(704) 459-7540', as Jobber holds it
+business = account.business
+business.id # => 'Z2lkOi8vSm9iYmV'
+business.name # => 'Acme Plumbing'
+business.phone # => '7044597540', the ten digits to dial, or nil where none can be
 ```
 
-Revoke credentials:
+Revoke the credentials:
 
 ```ruby
-oauth.delete
+account.delete
 ```
 
-Credentials go bad only when Jobber says so of the grant itself — `The provided refresh token
-is not valid.` — which sets `invalid_at` and answers queries with nothing. Anything else that
+Credentials go bad only when Jobber says so of the grant itself, `The provided refresh token
+is not valid.`, which sets `invalid_at` and answers queries with nothing. Anything else that
 goes wrong raises `Jbr::Error` instead: a 500, a rate limit, and the 401 Jobber answers an app
 whose own client id and secret are wrong, which is every account's grant at once rather than
 this one's:
 
 ```ruby
-oauth.invalid_at # => 2026-08-13 11:02:41, or nil while the credentials are good
-oauth.query '{ ok }' # => {} once they are refused, raises Jbr::Error where Jobber had trouble
+account.invalid_at # => 2026-08-13 11:02:41, or nil while the credentials are good
+account.query '{ ok }' # => {} once they are refused, raises Jbr::Error where Jobber had trouble
 ```
 
-### Requests
+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.
 
-Create a Jobber request, finding or creating a Client with a matching phone number:
+### Leads
+
+File a request on the account's board, against the client answering to the phone and the
+property at the address, opening either where Jobber has none:
 
 ```ruby
-request = oauth.requests.create first_name: 'Jane', last_name: 'Doe', phone: '5553335555',
-  email: 'jane@example.com', title: 'New Plumber Lead', instructions: 'Needs new faucet'
-request.id # => 'Z2lkOi8vSm9iYmVyL'
-request.client_id # => 'MwMTU0Mg'
+lead = account.leads.create name: 'Jane', surname: 'Doe', phone: '5553335555',
+  email: 'jane@example.com', description: 'New Plumber Lead', notes: 'Needs new faucet',
+  source: nil, # Jobber has no source for a request, so this one is dropped
+  address: { street: '1 Main St', city: 'Raleigh', state: 'NC', zip: '27601' }
+lead.id # => 'Z2lkOi8vSm9iYmVyL'
+lead.customer.id # => 'MwMTU0Mg', the client the request was opened against
 ```
 
+A mutation Jobber takes but will not act on, a phone it calls invalid or an email it already
+holds, raises `Jbr::Error` with what Jobber said.
+
 ### Quotes
 
-Fetch a quote from Jobber:
+Fetch a quote from Jobber, and the lead it answers:
 
 ```ruby
-quote = oauth.quotes.find 'Z2lkOi8vS'
+quote = account.quotes.find 'Z2lkOi8vS'
 quote.id # => 'Z2lkOi8vS'
-quote.request_id # => 'Z2lkOi8vSm9iYmVyL'
+quote.lead.id # => 'Z2lkOi8vSm9iYmVyL', the request the quote answers, or nil where none
 ```
 
 ### Jobs
@@ -113,63 +136,54 @@ quote.request_id # => 'Z2lkOi8vSm9iYmVyL'
 Fetch a job from Jobber by the ID it is filed under:
 
 ```ruby
-job = oauth.jobs.find 'Njc5MTk5'
+job = account.jobs.find 'Njc5MTk5'
 job.id # => 'Z2lkOi8vS'
-job.quote_id # => 'Z2lkOi8vS'
+job.quote.id # => 'Z2lkOi8vS', the quote the job was won with, or nil where none was
+job.quote.amount # => 240.0, in dollars, as a BigDecimal
+job.amount # => 260.0
+job.notes # => 'Ring the doorbell twice', what Jobber calls the instructions
+job.created_at # => 2026-05-10 09:15:00
 job.scheduled_at # => 2026-05-14 23:02:52
 job.completed_at # => 2026-05-18 11:36:13
 ```
 
 Or walk the account's jobs, oldest first. Either half of the schedule takes how much of it
-you meant — a duration, measured from the same now the half is split at — and a walk that
-stops at a boundary reads only the pages up to it. Jobber is asked for a page at a time, and
-only once the page before it runs out, so `first` costs one request where `to_a` costs as many
-as the account has pages. A walk is priced by what its pages carry, and a long one can be
-refused for it: see [Rate limits](#rate-limits).
+you meant, a duration measured from the same now the half is split at, and a walk that stops
+at a boundary reads only the pages up to it. Jobber is asked for a page at a time, and only
+once the page before it runs out, so `first` costs one request where `to_a` costs as many as
+the account has pages. A walk is priced by what its pages carry, and a long one can be refused
+for it: see [Rate limits](#rate-limits).
 
 ```ruby
-jobs = oauth.jobs # => an Enumerable of every job, nothing fetched yet
-oauth.jobs.past # => the ones dated before now, nothing fetched yet
-oauth.jobs.upcoming # => the ones dated from now on, nothing fetched yet
-oauth.jobs.past(1.year) # => only as far back as a year, which is fewer pages to read
-oauth.jobs.past.ids # => %w[Z2lkOi8vS ...], every page of them, and nothing else about them
-
-job = jobs.first
-job.name # => 'Furnace tune-up', or the job's ID where nobody titled it. Never nil or empty
-job.title # => 'Furnace tune-up'
-job.instructions # => 'Ring the doorbell twice'
-job.status # => 'requires_invoicing'
-job.total # => 260.0
-job.quote_total # => 240.0
-job.created_at # => 2026-05-10 09:15:00
+account.jobs # => an Enumerable of every job, nothing fetched yet
+account.jobs.past # => the ones dated before now, nothing fetched yet
+account.jobs.upcoming # => the ones dated from now on, nothing fetched yet
+account.jobs.past(1.year) # => only as far back as a year, which is fewer pages to read
+account.jobs.past.ids # => %w[Z2lkOi8vS ...], every page of them, and nothing else about them
 ```
 
-### Line items
+### Lines
 
 What the work actually was, where the title is only what somebody called it. Asked for the
 same way as anything nested, since a page costs what it carries:
 
 ```ruby
-job = oauth.jobs.includes(:line_items).find 'Njc5MTk5'
+job = account.jobs.includes(:lines).find 'Njc5MTk5'
 
-job.summary # => '3 Bathroom Faucet Installation and 2 Change Toilet Valve', the lines as a
-            #    sentence of how many of what. Falls back to #name where there are none
+job.description # => 'Fix the sink', the title somebody typed on the job
+job.lines.map(&:name) # => ['Bathroom Faucet Installation', 'Change Toilet Valve']
 
-job.line_items # => an Array of the lines the job is made of
-line = job.line_items.first
+line = job.lines.first
+line.id # => 'Njc5MjAw', the ID Jobber files the line by
 line.quantity # => 3, whole where Jobber's own Float has nothing after the point, and 3.5
               #    where it has: `3 Faucets`, or `3.5 Hours` for what was really billed
-line.id # => 'Njc5MjAw', the ID Jobber files the line by
 line.name # => 'Bathroom Faucet Installation'
 line.description # => 'Replace washers and reseat', what the line says beyond its name
-line.amount # => 285.0, what the line comes to -- what Jobber calls totalPrice
-line.to_s # => '3 Bathroom Faucet Installation', how many of what, and the name alone where
-          #    Jobber holds no quantity for the line
+line.amount # => 285.0, what the line comes to, which Jobber calls totalPrice
 ```
 
-Every line Jobber holds is in the list, up to twenty of them, in the order it holds them and
-whatever each is quantified at. One it holds no quantity for reads as its name alone. Ask for
-nothing and nothing arrives, so `oauth.jobs.first.line_items` is empty where the query never
+Every line Jobber holds is in the list, up to twenty of them, in the order it holds them. Ask
+for nothing and nothing arrives, so `account.jobs.first.lines` is empty where the query never
 named them.
 
 ### Invoices
@@ -177,103 +191,83 @@ named them.
 Fetch a non-draft invoice from Jobber:
 
 ```ruby
-invoice = oauth.invoices.find 'MjU3ODA0'
+invoice = account.invoices.find 'MjU3ODA0'
 invoice.id # => 'MjU3ODA0'
-invoice.job_id # => 'Z2lkOi8vS'
-invoice.total # => '40.30'
-invoice.issued_at # => 2026-05-22 12:12:53
-invoice.completed_at # => 2026-05-22 14:32:53
+invoice.job.id # => 'Z2lkOi8vS', the job the invoice bills, or nil where none
+invoice.amount # => 40.30, in dollars, as a BigDecimal
+invoice.fulfilled_at # => 2026-05-22 14:32:53, when the job was finished, or the invoice issued
 ```
 
 ### Visits
 
-Walk the account's visits, oldest first, the same way as its jobs:
+Walk the account's visits, oldest first, the same way as its jobs, or reach one by ID:
 
 ```ruby
-visits = oauth.visits # => an Enumerable of every visit, nothing fetched yet
-oauth.visits.upcoming # => the ones dated from now on, nothing fetched yet
-oauth.visits.past # => the ones dated before now, nothing fetched yet
-oauth.visits.upcoming(3.months) # => only as far ahead as three months
-oauth.visits.upcoming.ids # => %w[Z2lkOi8vS ...], every page of them, and nothing else
+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 = visits.first
+visit = account.visits.find 'Z2lkOi8vS'
 visit.id # => 'Z2lkOi8vS'
-visit.name # => 'Furnace tune-up', or the visit's ID where nobody titled it. Never nil or empty
-visit.title # => 'Furnace tune-up'
-visit.job_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.all_day? # => false
-visit.client_confirmed? # => true
+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
 ```
 
-### Clients and properties
+### Locations and customers
 
 Jobber prices a query by what it brings back, so nothing nested comes back unless it is
-asked for. Chain `includes` the way Active Record does, on visits or on jobs:
+asked for. Chain `includes` the way Active Record does, on jobs; a visit happens where its job
+does, so it names the job and nothing else:
 
 ```ruby
-visit = oauth.visits.includes(:client, property: :client).upcoming.first
-
-visit.client.name # => 'Jane', or the business's name where the client is a business.
-                  # Never an empty string: a blank first name falls through to the company
-visit.client.first_name # => 'Jane'
-visit.client.last_name # => 'Doe'
-visit.client.company_name # => nil
-visit.client.email # => 'jane@example.com'
-visit.client.phone # => '5553335555', the reachable North American number, or nil
-
-visit.property.id # => 'Z2lkOi8vS'
-visit.property.street # => '1 Main St'
-visit.property.city # => 'Raleigh'
-visit.property.zip # => '27601'
-visit.property.latitude # => 35.77
-visit.property.longitude # => -78.63
-visit.property.address # => { street: '1 Main St', city: 'Raleigh', state: 'NC',
-                       #      zip: '27601', latitude: 35.77, longitude: -78.63 }
-visit.property.client.name # => whoever the place sits on the file of
+job = account.jobs.includes(location: :customer).find 'Z2lkOi8vSm9i'
+
+job.location.id # => 'Z2lkOi8vS'
+job.location.street # => '1 Main St'
+job.location.city # => 'Raleigh'
+job.location.zip # => '27601'
+job.location.latitude # => 35.77
+job.location.longitude # => -78.63
+
+job.location.customer.name # => 'Jane', or the business's name where the client is one.
+                           #    Never an empty string: a blank first name falls through
+job.location.customer.surname # => 'Doe'
+job.location.customer.email # => 'jane@example.com'
+job.location.customer.phone # => '5553335555', the ten digits to dial, or nil
 ```
 
-Ask for nothing and nothing arrives: `oauth.visits.first.client.name` is nil where the
-query never named a client.
+Ask for nothing and nothing arrives: `account.jobs.first.location` is nil where the query
+never named one.
 
 ### Rate limits
 
 Jobber holds an app to two limits at once: 2,500 requests every five minutes, and a bucket of
 query cost that drains as it is asked and refills at a rate it reports. This gem does nothing
-about either — it never sleeps, and it never asks a second time. What it does is say exactly
+about either. It never sleeps, and it never asks a second time. What it does is say exactly
 what happened, so the caller can decide:
 
 ```
 Throttled (cost 1885, 1254 of 10000 available, restoring 500/s)
 ```
 
-That one is a `Jbr::Retriable`, a `Jbr::Error` for a refusal worth asking again, carrying the
-numbers to decide with:
-
-```ruby
-error.cost # => 1885, what the query was priced at
-error.available # => 1254, what the bucket held when it was asked
-error.maximum # => 10000, what the bucket holds when full — a cost above it never fits
-error.restore_rate # => 500, points a second
-```
-
-That arrives as a `Jbr::Error`. 631 points short of a query the bucket holds five times over,
-which a second would have refilled — worth asking again. A cost above `maximumAvailable` is
-worth nothing but a smaller query. Either way the decision belongs to whoever called: from a
-background job, letting it fail so the queue brings it back is better than a worker asleep
-holding a transaction open.
+That one is a `Jbr::Throttled`, a `Company::Throttled` for a refusal worth asking again: 631 points
+short of a query the bucket holds five times over, which a second would have refilled. A cost
+above what the bucket holds when full is worth nothing but a smaller query. Either way the
+decision belongs to whoever called: from a background job, letting it fail so the queue brings
+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.
 
 `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 — so five times the
-account is read for a fraction of the budget. Reach for it where each record is then read on
-its own with `find`, one background job at a time:
+a row at a fraction of a record and buys a hundred of them to a page. Reach for it where each
+record is then read on its own with `find`, one background job at a time:
 
 ```ruby
-oauth.jobs.past.ids.each { |id| ImportJob.perform_later id }
+account.jobs.past.ids.each { |id| ImportJob.perform_later id }
 ```
 
 ### Events
@@ -289,7 +283,8 @@ event.item_id # => 'job-1'
 
 ## Available mocks
 
-Use these methods to mock request to Jobber when testing an app:
+Touch `Jbr.mock` once, in an app's test helper, and every `Jbr::Account` answers from it
+instead of Jobber. Each slot takes a Hash by the vocabulary's names.
 
 ### Credentials
 
@@ -305,24 +300,24 @@ Mock an error when creating credentials:
 Jbr.mock.oauth_error = 'Flow rejected'
 ```
 
-Mock a custom redirect URL:
+Mock a custom authorize URL:
 
 ```ruby
 Jbr.mock.oauth_url = 'https://example.com'
 ```
 
-Mock the account the credentials belong to. Left unset, its ID is `account-01`:
+Mock the business the credentials belong to. Left unset, its ID is `account-01`:
 
 ```ruby
-Jbr.mock.account = { id: 'account-01', name: 'Acme Plumbing', phone: '(704) 459-7540' }
+Jbr.mock.business = { id: 'account-01', name: 'Acme Plumbing', phone: '(704) 459-7540' }
 ```
 
-### Requests
+### Leads
 
-Mock successfully creating a request:
+Mock successfully filing a lead:
 
 ```ruby
-Jbr.mock.request = { id: 'request-01', client_id: 'client-01' }
+Jbr.mock.lead = { id: 'request-01', customer: { id: 'client-01' } }
 ```
 
 ### Quotes
@@ -330,7 +325,7 @@ Jbr.mock.request = { id: 'request-01', client_id: 'client-01' }
 Mock successfully fetching a quote:
 
 ```ruby
-Jbr.mock.quote = { id: 'quote-01', request_id: 'request-01' }
+Jbr.mock.quote = { id: 'quote-01', lead: { id: 'request-01' } }
 ```
 
 ### Jobs
@@ -338,43 +333,34 @@ Jbr.mock.quote = { id: 'quote-01', request_id: 'request-01' }
 Mock successfully fetching a job by ID:
 
 ```ruby
-Jbr.mock.job = { id: 'job-01', quote_id: 'quote-01', scheduled_at: Date.tomorrow.noon }
+Jbr.mock.job = { id: 'job-01', quote: { id: 'quote-01' }, scheduled_at: Date.tomorrow.noon }
 ```
 
 Mock the jobs the account has. The mock dates nothing it was handed: what answers to
-`past` and to `upcoming` is whatever `scheduled_at` the app gave each one:
+`past` and to `upcoming` is whatever `scheduled_at` the app gave each one, and `find` answers
+the one listed under the ID asked for:
 
 ```ruby
-Jbr.mock.jobs = [ { id: 'job-01', title: 'Furnace tune-up', status: 'archived',
-  total: 260.0, quote_total: 240.0, created_at: Date.yesterday.noon,
+Jbr.mock.jobs = [ { id: 'job-01', description: 'Furnace tune-up', notes: 'Ring twice',
+  amount: 260.0, quote: { id: 'quote-01', amount: 240.0 }, created_at: Date.yesterday.noon,
   scheduled_at: Date.yesterday.noon, completed_at: Date.today.noon,
-  property: { id: 'property-01', street: '1 Main St',
-    client: { id: 'client-01', company_name: 'Acme Property Management' } } } ]
-```
-
-Mock the lines a job is made of, under the job that is made of them:
-
-```ruby
-Jbr.mock.jobs = [ { id: 'job-01', line_items: [
-  { quantity: 3.0, name: 'Bathroom Faucet Installation',
-    description: 'Professional installation of a new bathroom faucet' },
-  { quantity: 2.0, name: 'Change Toilet Valve' } ] } ]
+  lines: [ { quantity: 3.0, name: 'Bathroom Faucet Installation' }, { name: 'Trip fee' } ],
+  location: { id: 'property-01', street: '1 Main St',
+    customer: { id: 'client-01', name: 'Acme Property Management' } } } ]
 
-oauth.jobs.past.first.summary
-# => '3 Bathroom Faucet Installation and 2 Change Toilet Valve'
+account.jobs.past.first.lines.map(&:name) # => ['Bathroom Faucet Installation', 'Trip fee']
 ```
 
 ### Visits
 
-Mock the visits the account has:
+Mock the visits the account has, dated by `starts_at`:
 
 ```ruby
-Jbr.mock.visits = [ { id: 'visit-01', title: 'Furnace tune-up', job_id: 'job-01',
-  property: { id: 'property-01', street: '1 Main St',
-    client: { id: 'client-01', first_name: 'Jane' } },
-  client: { id: 'client-01', first_name: 'Jane' },
+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,
-  all_day: false, client_confirmed: true } ]
+  anytime: false, confirmed: true } ]
 ```
 
 ### Invoices
@@ -382,5 +368,6 @@ Jbr.mock.visits = [ { id: 'visit-01', title: 'Furnace tune-up', job_id: 'job-01'
 Mock successfully fetching an invoice:
 
 ```ruby
-Jbr.mock.invoice = { id: 'invoice-01', job_id: 'job-01', total: 19.99, issued_at: Date.yesterday.noon }
+Jbr.mock.invoice = { id: 'invoice-01', job: { id: 'job-01' }, amount: 19.99,
+  issued_at: Date.yesterday.noon }
 ```

data/lib/graphql/client.rb

@@ -28,20 +28,15 @@ module GraphQL
 
   private
 
-    # Refused over cost where the endpoint names the code for it, or prices the query above
-    # what it says was left. Anything else is a refusal of the query itself.
     def refusal_for(body)
       cost = body['extensions'].to_h['cost'].to_h
       available = cost['throttleStatus'].to_h['currentlyAvailable']
       coded = body['errors'].any? { |error| error.to_h.dig('extensions', 'code') == 'THROTTLED' }
       priced = available && cost['requestedQueryCost'].to_f > available.to_f
 
-      coded || priced ? Throttled.new(refusal(body), cost) : Error.new(refusal(body))
+      (coded || priced ? Throttled : Error).new refusal(body)
     end
 
-    # What the endpoint refused, and — where it priced the refusal — what the query would have
-    # cost against what was available. `Throttled` on its own leaves a caller unable to tell a
-    # query too big to ever run from a bucket that a moment would have refilled.
     def refusal(body)
       message = body['errors'].map { |error| error['message'] }.join '; '
       cost = body['extensions'].to_h['cost'].to_h
@@ -51,6 +46,7 @@ module GraphQL
       "#{message} (cost #{cost['requestedQueryCost']}, #{status['currentlyAvailable']} of " \
         "#{status['maximumAvailable']} available, restoring #{status['restoreRate']}/s)"
     end
+
     def request_headers
       { 'Authorization' => "Bearer #{@token}", 'Content-Type' => 'application/json' }.merge @headers
     end