jbr 3.8.0 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de01eb560b5d6366142d35901817eae421a30ccebf31aeede4cacb2e97720cd3
-  data.tar.gz: 1a613711f19080da2368d9b2d38d2e9fff372dbd4e37126b2bc06e9d4c9a9493
+  metadata.gz: 5a315b6ba52c573f0d7fa1a0adec8145578550bd67a136071e7b8a02ea328ea1
+  data.tar.gz: 8c338c2f5a13ce4e98c99c2b5c11377274c71908a2b93fc6c114d8fb109ae540
 SHA512:
-  metadata.gz: 9b8fc6971e3cbe48eecf5025cb7f5b9beb9e7490a0b7a6830b0a22eb9b4c98fbe3c066686866dff576de01bfc0e10f16050c6bd1002b929bd18940dfeeccd137
-  data.tar.gz: 2cbdcb7fd7bd995bf7450784afdb08d59acce2c0ea788f3192a1c62aabaf00251497bfb8ff6efa57a932d96a15735dbaa9bdc4e846824679521056e7a3129e33
+  metadata.gz: e82a0f7dac54170d4f791a752f7497d0b783dce98f4057c606c3ee1f5fe73c85ef32032eb297e2406b95d82bf531d6ba1cf2f4db8a9de5be1fbef38ac1c1c69b
+  data.tar.gz: 82a90ec3316204bb8ccf87c4d4011e249cd7b5d4484697fc30477f553bd4146baa9402bff10f4c6c2f893ce93bc7d06509831ecaf4a7d8a16a60dfad5b0ae67d

data/README.md

@@ -111,15 +111,19 @@ 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. 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 paces itself, so a long one is never refused: see
-[Rate limits](#rate-limits).
+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).
 
 ```ruby
 jobs = oauth.jobs # => an Enumerable of every job, nothing fetched yet
-oauth.jobs.past # => an Enumerator of the ones dated before now
-oauth.jobs.upcoming # => an Enumerator of the ones dated from now on
+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
@@ -175,8 +179,10 @@ Walk the account's visits, oldest first, the same way as its jobs:
 
 ```ruby
 visits = oauth.visits # => an Enumerable of every visit, nothing fetched yet
-oauth.visits.upcoming # => an Enumerator of the ones dated from now on
-oauth.visits.past # => an Enumerator of the ones dated before now
+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
 
 visit = visits.first
 visit.id # => 'Z2lkOi8vS'
@@ -247,6 +253,15 @@ 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:
+
+```ruby
+oauth.jobs.past.ids.each { |id| ImportJob.perform_later id }
+```
+
 ### Events
 
 Parse the payload of a Jobber event webhook:

data/lib/jbr/jobs.rb

@@ -1,23 +1,13 @@
 module Jbr
   # The jobs on a Jobber account, oldest first, walked a page at a time.
   class Jobs < Resource
-    include Enumerable, Includable
+    include Includable, Listable
 
     # What a job answers with wherever one is read, before anything it was asked to bring
     # back with it.
     FIELDS = 'id title instructions jobStatus total createdAt startAt completedAt ' \
              'quote { id amounts { total } }'
 
-    # Every job on the account, past and future alike. Nothing is read until the walk starts,
-    # and a page is read only once the one before it runs out.
-    def each(&) = walk.each(&)
-
-    # @return [Enumerator<Job>] the jobs scheduled from now on.
-    def upcoming = walk from_now
-
-    # @return [Enumerator<Job>] the jobs that started before now.
-    def past = walk until_now
-
     # Shadows Enumerable#find on purpose, the way Active Record does: a job is reached by the
     # ID Jobber files it under, not by asking every job on the account whether it is the one.
     # @param id [String] the Jobber ID of the job.
@@ -29,20 +19,7 @@ module Jbr
 
   private
 
-    # Twenty a page, not forty and not a hundred: Jobber prices a query by its page size, and
-    # what an includes brings back is charged for on top of every row of it — so a page of jobs
-    # carrying their lines, their property and its client priced past what a bucket holds. Half
-    # the page costs half the query and loses nothing, since a walk simply reads more pages.
-    def page
-      <<~GRAPHQL
-        query($after: String, $filter: JobFilterAttributes) {
-          jobs(first: 20, after: $after, filter: $filter) {
-            nodes { #{FIELDS} #{selections} }
-            pageInfo { hasNextPage endCursor }
-          }
-        }
-      GRAPHQL
-    end
+    def page = paged "#{FIELDS} #{selections}", PAGE
 
     def one
       <<~GRAPHQL
@@ -54,6 +31,8 @@ module Jbr
 
     def field = 'jobs'
 
+    def filtered = 'JobFilterAttributes'
+
     def item(node) = Job.new node: node
   end
 end

data/lib/jbr/listable.rb

@@ -0,0 +1,96 @@
+module Jbr
+  # What a list of records answers, and how much of an account it costs to ask. Jobber prices
+  # a query by the page it asks for and by what every row of that page carries, so a list is
+  # read either as records or as the IDs alone, each with a page sized to what it carries.
+  module Listable
+    include Enumerable
+
+    # Records a page, not forty and not a hundred: what an includes brings back is charged for
+    # on top of every row of it, so a page of jobs carrying their lines, their property and its
+    # client priced past what a bucket holds. Half the page costs half the query and loses
+    # nothing, since a walk simply reads more pages.
+    PAGE = 20
+
+    # IDs a page, which the same budget affords five times over where a row carries one field
+    # and no nesting at all.
+    IDS_PAGE = 100
+
+    # Every record the list is narrowed to, oldest first. Nothing is read until the walk
+    # starts, and a page is read only once the one before it runs out.
+    def each(&) = walk(page).each(&)
+
+    # @param within [ActiveSupport::Duration, Numeric, nil] how far ahead to look, or nil for
+    #   as far ahead as the account is scheduled.
+    # @return [Listable] the same list, narrowed to what is scheduled from now on.
+    def upcoming(within = nil)
+      now = Time.now
+      narrowed after: now, before: (now + within if within)
+    end
+
+    # @param within [ActiveSupport::Duration, Numeric, nil] how far back to look, or nil for
+    #   as far back as the account goes.
+    # @return [Listable] the same list, narrowed to what started before now.
+    def past(within = nil)
+      now = Time.now
+      narrowed before: now, after: (now - within if within)
+    end
+
+    # 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
+    # own through {#find}.
+    # @return [Array<String>] every ID in the list, every page of them read.
+    def ids = walk(ids_page).map(&:id)
+
+  private
+
+    # The two halves of a schedule, split at the moment they are asked for rather than per
+    # page: read page by page the boundary would slide, and something could cross it unseen.
+    # The same moment is the near end of a window, so the far end is measured from it too.
+    def narrowed(after: nil, before: nil)
+      bounds = { after: after&.iso8601, before: before&.iso8601 }.compact
+      self.class.new oauth: @oauth, includes: @includes, filter: { startAt: bounds }
+    end
+
+    # Whether a moment falls in the stretch of the schedule the list was narrowed to, for
+    # anything answering one without asking Jobber. A record with no moment at all is in an
+    # open-ended upcoming list, since nothing has started it, and in no window, since a window
+    # is a stretch it would have to have fallen in.
+    def scheduled?(at)
+      return true unless @filter
+
+      after, before = @filter[:startAt].values_at :after, :before
+      return before.nil? unless at
+
+      (after.nil? || at >= Time.iso8601(after)) && (before.nil? || at <= Time.iso8601(before))
+    end
+
+    # Every record a paged query answers, one at a time, a page read only once the one before
+    # it runs out. The filter is data: narrowed to nothing, the query narrows nothing.
+    def walk(statement)
+      Enumerator.new do |yielder|
+        after = nil
+        loop do
+          answered = @oauth.query statement, variables: { after: after, filter: @filter }.compact
+          current = answered.fetch field, {}
+          current.fetch('nodes', []).each { |node| yielder << item(node) }
+          break unless current.dig 'pageInfo', 'hasNextPage'
+
+          after = current.dig 'pageInfo', 'endCursor'
+        end
+      end
+    end
+
+    def ids_page = paged 'id', IDS_PAGE
+
+    def paged(fields, size)
+      <<~GRAPHQL
+        query($after: String, $filter: #{filtered}) {
+          #{field}(first: #{size}, after: $after, filter: $filter) {
+            nodes { #{fields} }
+            pageInfo { hasNextPage endCursor }
+          }
+        }
+      GRAPHQL
+    end
+  end
+end

data/lib/jbr/mock/jobs.rb

@@ -1,27 +1,19 @@
 module Jbr
-  # The jobs an app under test asked {Jbr.mock} to answer with.
+  # The jobs 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.
   class Mock::Jobs < Jobs
     # The job filed under that ID where the app listed one, and otherwise the single job it
     # named — which is every app that mocks a lookup without mocking a list.
     # @return [Mock::Job] the job asked for.
     def find(id) = Mock::Job.new node: listed(id) || Jbr.mock.job
 
-    # @return [Enumerator<Mock::Job>] every job the app named.
-    def each(&) = mocked(Jbr.mock.jobs).each(&)
-
-    # @return [Enumerator<Mock::Job>] those it dated from now on, and any it left undated.
-    def upcoming = mocked Jbr.mock.jobs.reject { |job| started? job }
-
-    # @return [Enumerator<Mock::Job>] those it dated before now.
-    def past = mocked Jbr.mock.jobs.select { |job| started? job }
-
   private
 
-    def mocked(jobs)
-      Enumerator.new { |yielder| jobs.each { |job| yielder << Mock::Job.new(node: job) } }
+    def walk(_statement)
+      Enumerator.new { |yielder| selected.each { |job| yielder << Mock::Job.new(node: job) } }
     end
 
-    def started?(job) = job[:scheduled_at] ? job[:scheduled_at] <= Time.now : false
+    def selected = Jbr.mock.jobs.select { |job| scheduled? job[:scheduled_at] }
 
     # Only a real list is looked through: an app that mocked the list as something raising
     # was mocking the walk failing, and a lookup is a question of its own.

data/lib/jbr/mock/visits.rb

@@ -1,25 +1,17 @@
 module Jbr
-  # The visits an app under test asked {Jbr.mock} to answer with.
+  # 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.
   class Mock::Visits < Visits
-    # @return [Enumerator<Mock::Visit>] every visit the app named.
-    def each(&) = mocked(Jbr.mock.visits).each(&)
-
-    # @return [Enumerator<Mock::Visit>] those it dated from now on, and any it left undated.
-    def upcoming = mocked Jbr.mock.visits.reject { |visit| started? visit }
-
-    # @return [Enumerator<Mock::Visit>] those it dated before now.
-    def past = mocked Jbr.mock.visits.select { |visit| started? visit }
-
     # @return [Mock::Visit] the visit the app listed under that ID.
     def find(id) = Mock::Visit.new node: listed(id)
 
   private
 
-    def mocked(visits)
-      Enumerator.new { |yielder| visits.each { |visit| yielder << Mock::Visit.new(node: visit) } }
+    def walk(_statement)
+      Enumerator.new { |yielder| selected.each { |it| yielder << Mock::Visit.new(node: it) } }
     end
 
-    def started?(visit) = visit[:starts_at] ? visit[:starts_at] <= Time.now : false
+    def selected = Jbr.mock.visits.select { |visit| scheduled? visit[:starts_at] }
 
     def listed(id) = Jbr.mock.visits.to_a.find { |visit| visit[:id] == id }.to_h
   end

data/lib/jbr/resource.rb

@@ -1,15 +1,17 @@
 module Jbr
   # What every Jobber resource shares: the node Jobber answered with, the credentials it was
-  # read through, and the paging that every list of them arrives in.
+  # read through, and what a list of them was asked and narrowed to.
   class Resource
     # @param oauth [OAuth] the credentials to reach Jobber with, where reaching it is needed.
     # @param node [Hash] the record as Jobber answered it.
     # @param includes [Hash] what a list was asked to bring back beside its records.
-    def initialize(oauth: nil, node: {}, includes: {})
+    # @param filter [Hash] what a list was narrowed to, in the shape Jobber filters by.
+    def initialize(oauth: nil, node: {}, includes: {}, filter: nil)
       @oauth = oauth
       @node = node
       @id = node['id']
       @includes = includes
+      @filter = filter
     end
 
     # @return [String, nil] the Jobber ID, from the node it came in or once one was created.
@@ -20,27 +22,5 @@ module Jbr
     # @return [Time, nil] what Jobber answered under a key, as a time. An empty answer is no
     #   answer: Time.iso8601 raises on one, where nothing at all it simply has none of.
     def time(key) = (Time.iso8601 @node[key] if @node[key].present?)
-
-    # Every item a paged query answers, one at a time, a page read only once the one before
-    # it runs out. The filter is data: handed none, the query narrows nothing.
-    def walk(filter = nil)
-      Enumerator.new do |yielder|
-        after = nil
-        loop do
-          answered = @oauth.query(page, variables: { after: after, filter: filter }.compact)
-          current = answered.fetch field, {}
-          current.fetch('nodes', []).each { |node| yielder << item(node) }
-          break unless current.dig 'pageInfo', 'hasNextPage'
-
-          after = current.dig 'pageInfo', 'endCursor'
-        end
-      end
-    end
-
-    # The two halves of a schedule, split at the moment they are asked for rather than per
-    # page: read page by page the boundary would slide, and something could cross it unseen.
-    def from_now = { startAt: { after: Time.now.iso8601 } }
-
-    def until_now = { startAt: { before: Time.now.iso8601 } }
   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 = '3.8.0'
+  VERSION = '3.10.0'
 end

data/lib/jbr/visits.rb

@@ -1,21 +1,11 @@
 module Jbr
   # The visits on a Jobber account, oldest first, walked a page at a time.
   class Visits < Resource
-    include Enumerable, Includable
+    include Includable, Listable
 
     # What a visit answers with, before anything it was asked to bring back with it.
     FIELDS = 'id title startAt endAt allDay clientConfirmed job { id }'
 
-    # Every visit on the account, past and future alike. Nothing is read until the walk
-    # starts, and a page is read only once the one before it runs out.
-    def each(&) = walk.each(&)
-
-    # @return [Enumerator<Visit>] the visits scheduled from now on.
-    def upcoming = walk from_now
-
-    # @return [Enumerator<Visit>] the visits that started before now.
-    def past = walk until_now
-
     # 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] the Jobber ID of the visit.
@@ -27,6 +17,8 @@ module Jbr
 
   private
 
+    def page = paged "#{FIELDS} #{selections}", PAGE
+
     def one
       <<~GRAPHQL
         query($id: EncodedId!) {
@@ -35,21 +27,10 @@ module Jbr
       GRAPHQL
     end
 
-    # Twenty a page, the same as jobs: Jobber prices a query by its page size, and what an
-    # includes brings back is charged for on top of every row of it.
-    def page
-      <<~GRAPHQL
-        query($after: String, $filter: VisitFilterAttributes) {
-          visits(first: 20, after: $after, filter: $filter) {
-            nodes { #{FIELDS} #{selections} }
-            pageInfo { hasNextPage endCursor }
-          }
-        }
-      GRAPHQL
-    end
-
     def field = 'visits'
 
+    def filtered = 'VisitFilterAttributes'
+
     def item(node) = Visit.new node: node
   end
 end

data/lib/jbr.rb

@@ -36,6 +36,7 @@ require 'jbr/account'
 require 'jbr/property'
 require 'jbr/properted'
 require 'jbr/includable'
+require 'jbr/listable'
 # LineItem before Itemized, and both before Job: the lines a job is made of are asked for
 # by a constant the include reads as it loads.
 require 'jbr/line_item'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jbr
 version: !ruby/object:Gem::Version
-  version: 3.8.0
+  version: 3.10.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -120,6 +120,7 @@ files:
 - lib/jbr/job.rb
 - lib/jbr/jobs.rb
 - lib/jbr/line_item.rb
+- lib/jbr/listable.rb
 - lib/jbr/mock.rb
 - lib/jbr/mock/account.rb
 - lib/jbr/mock/client.rb