printavo-ruby 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c80d0cf1950d67050c32a5d20e9bc6d001587fb509c3f52831b6dfbec77e5b3
-  data.tar.gz: 2d117bae60f460bd9ba9aaa2571bdeacb4915e361224e3f3d61183e2b52a33df
+  metadata.gz: a7786dadca364f38068636a9a6e30efac78ac79107c8dfb4ade22b39db5f0bc1
+  data.tar.gz: f0464978791f12c8e3f5d37d2de09ecfc4b97e57aca4999beda995b68957d2e1
 SHA512:
-  metadata.gz: 1858601061541936154d9d8daad2b30950dd737501502681e266966f8de415eb84f15c0fa9ba3d8ac2725a27990d8cb000728a9be03c0d5c7e86c13362d53b06
-  data.tar.gz: 3ff3869148ccbabb980d352b1a3270de1c63d18eaf6d512a96fb116cd9c346718f90b7121a13455d582b7e205a1736ee357437f8f1a34cd9e83b572cd7d63184
+  metadata.gz: a6aae8c15d5f5c348d8e717c09eaf85092a9421d473541ac1ef3c38042534ed1aa14c6e0c5283d6878325cdf32a7325fed52e980913e7b15e8c443ed64a695bb
+  data.tar.gz: bac95ec4243aa408c495f88d7c4841a308f7c49f509d8b7a0f3a4a161cb9db30418d2ba2c79be67f353c89b68d24cec6f70c1487b64496ea5ef74489fe44acc8

data/README.md

@@ -116,6 +116,26 @@ job = client.jobs.find("77")
 puts job.taxable?   # => true
 ```
 
+### Pagination
+
+All list resources support `each_page` and `all_pages` in addition to `all`.
+
+```ruby
+# Iterate page by page (cursor-based, memory-efficient)
+client.customers.each_page(first: 50) do |records|
+  records.each { |c| puts c.full_name }
+end
+
+# Collect every record across all pages into one array
+all_orders = client.orders.all_pages
+
+# Jobs require order_id
+client.jobs.each_page(order_id: "99") do |records|
+  records.each { |j| puts j.name }
+end
+all_jobs = client.jobs.all_pages(order_id: "99")
+```
+
 ### Statuses
 
 ```ruby
@@ -234,9 +254,9 @@ end
 
 | Version | Milestone |
 |---|---|
-| 0.1.0 | Auth + Customers + Orders + Jobs ✅ |
+| 0.1.0 | Auth + Customers + Orders + Jobs + Webhooks (Rack-compatible) ✅ |
 | 0.2.0 | Status registry + Inquiries ✅ |
-| 0.3.0 | Webhooks (Rack-compatible) |
+| 0.3.0 | Pagination helpers (`each_page`, `all_pages`) + `bin/lint` ✅ |
 | 0.4.0 | Expanded GraphQL DSL |
 | 0.5.0 | Mutations (create/update) |
 | 0.6.0 | Analytics / Reporting queries |

data/docs/CHANGELOG.md

@@ -8,6 +8,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-29
+
+### Added
+- `Printavo::Page` — value object wrapping `records`, `has_next_page`, `end_cursor` with `to_a`, `size`, `empty?`
+- `Printavo::Resources::Base#each_page` — yields each page of records as an Array, following cursors automatically
+- `Printavo::Resources::Base#all_pages` — returns all records across all pages as a flat Array
+- All resources (`Customers`, `Orders`, `Jobs`, `Statuses`, `Inquiries`) implement `fetch_page` and support `each_page`/`all_pages`
+- `Jobs#each_page(order_id:)` and `Jobs#all_pages(order_id:)` — `order_id` forwarded via `**kwargs`
+- `bin/lint` — multi-Ruby RuboCop runner mirroring `bin/spec` (reads versions from `.mise.toml`)
+- Roadmap: moved Pagination from 0.8.0 to 0.3.0; Webhooks slot repurposed
+
+### Changed
+- All resource `all` methods refactored to delegate to `fetch_page` (backward compatible — still returns `Array`)
+
 ## [0.2.0] - 2026-03-29
 
 ### Added

data/lib/printavo/page.rb

@@ -0,0 +1,20 @@
+# lib/printavo/page.rb
+module Printavo
+  # Wraps a single page of API results with cursor metadata.
+  #
+  # @example Iterating pages manually
+  #   page = client.customers.fetch_page(first: 10)
+  #   page.records.each { |c| puts c.full_name }
+  #   puts page.has_next_page   # => true
+  #   puts page.end_cursor      # => "cursor_abc123"
+  #
+  # @example Using each_page
+  #   client.customers.each_page(first: 10) do |records|
+  #     records.each { |c| puts c.full_name }
+  #   end
+  Page = Struct.new(:records, :has_next_page, :end_cursor, keyword_init: true) do
+    def to_a    = records
+    def size    = records.size
+    def empty?  = records.empty?
+  end
+end

data/lib/printavo/resources/base.rb

@@ -5,6 +5,47 @@ module Printavo
       def initialize(graphql)
         @graphql = graphql
       end
+
+      # Yields each page of records as an Array, following cursors automatically.
+      # Extra keyword arguments are forwarded to fetch_page (e.g. order_id: for Jobs).
+      #
+      # @param first [Integer] page size (default 25)
+      # @yieldparam records [Array] one page of domain model objects
+      #
+      # @example
+      #   client.customers.each_page(first: 50) do |records|
+      #     records.each { |c| puts c.full_name }
+      #   end
+      def each_page(first: 25, **kwargs)
+        after = nil
+        loop do
+          page = fetch_page(first: first, after: after, **kwargs)
+          yield(page.records)
+          break unless page.has_next_page
+
+          after = page.end_cursor
+        end
+      end
+
+      # Returns all records across all pages as a flat Array.
+      # Extra keyword arguments are forwarded to fetch_page (e.g. order_id: for Jobs).
+      #
+      # @param first [Integer] page size per request (default 25)
+      # @return [Array]
+      #
+      # @example
+      #   all_customers = client.customers.all_pages
+      #   all_jobs      = client.jobs.all_pages(order_id: "99")
+      def all_pages(first: 25, **kwargs)
+        [].tap { |all| each_page(first: first, **kwargs) { |records| all.concat(records) } }
+      end
+
+      private
+
+      # Subclasses must implement: returns a Printavo::Page.
+      def fetch_page(**)
+        raise NotImplementedError, "#{self.class}#fetch_page is not implemented"
+      end
     end
   end
 end

data/lib/printavo/resources/customers.rb

@@ -35,14 +35,26 @@ module Printavo
       GQL
 
       def all(first: 25, after: nil)
-        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
-        data['customers']['nodes'].map { |attrs| Printavo::Customer.new(attrs) }
+        fetch_page(first: first, after: after).records
       end
 
       def find(id)
         data = @graphql.query(FIND_QUERY, variables: { id: id.to_s })
         Printavo::Customer.new(data['customer'])
       end
+
+      private
+
+      def fetch_page(first: 25, after: nil, **)
+        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
+        nodes = data['customers']['nodes'].map { |attrs| Printavo::Customer.new(attrs) }
+        page_info = data['customers']['pageInfo']
+        Printavo::Page.new(
+          records: nodes,
+          has_next_page: page_info['hasNextPage'],
+          end_cursor: page_info['endCursor']
+        )
+      end
     end
   end
 end

data/lib/printavo/resources/inquiries.rb

@@ -53,14 +53,26 @@ module Printavo
       GQL
 
       def all(first: 25, after: nil)
-        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
-        data['inquiries']['nodes'].map { |attrs| Printavo::Inquiry.new(attrs) }
+        fetch_page(first: first, after: after).records
       end
 
       def find(id)
         data = @graphql.query(FIND_QUERY, variables: { id: id.to_s })
         Printavo::Inquiry.new(data['inquiry'])
       end
+
+      private
+
+      def fetch_page(first: 25, after: nil, **)
+        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
+        nodes = data['inquiries']['nodes'].map { |attrs| Printavo::Inquiry.new(attrs) }
+        page_info = data['inquiries']['pageInfo']
+        Printavo::Page.new(
+          records: nodes,
+          has_next_page: page_info['hasNextPage'],
+          end_cursor: page_info['endCursor']
+        )
+      end
     end
   end
 end

data/lib/printavo/resources/jobs.rb

@@ -35,14 +35,29 @@ module Printavo
       GQL
 
       def all(order_id:, first: 25, after: nil)
-        data = @graphql.query(ALL_QUERY, variables: { orderId: order_id.to_s, first: first, after: after })
-        data['order']['lineItems']['nodes'].map { |attrs| Printavo::Job.new(attrs) }
+        fetch_page(order_id: order_id, first: first, after: after).records
       end
 
       def find(id)
         data = @graphql.query(FIND_QUERY, variables: { id: id.to_s })
         Printavo::Job.new(data['lineItem'])
       end
+
+      private
+
+      def fetch_page(order_id:, first: 25, after: nil, **)
+        data = @graphql.query(
+          ALL_QUERY,
+          variables: { orderId: order_id.to_s, first: first, after: after }
+        )
+        nodes = data['order']['lineItems']['nodes'].map { |attrs| Printavo::Job.new(attrs) }
+        page_info = data['order']['lineItems']['pageInfo']
+        Printavo::Page.new(
+          records: nodes,
+          has_next_page: page_info['hasNextPage'],
+          end_cursor: page_info['endCursor']
+        )
+      end
     end
   end
 end

data/lib/printavo/resources/orders.rb

@@ -39,6 +39,7 @@ module Printavo
             status {
               id
               name
+              color
             }
             customer {
               id
@@ -52,14 +53,26 @@ module Printavo
       GQL
 
       def all(first: 25, after: nil)
-        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
-        data['orders']['nodes'].map { |attrs| Printavo::Order.new(attrs) }
+        fetch_page(first: first, after: after).records
       end
 
       def find(id)
         data = @graphql.query(FIND_QUERY, variables: { id: id.to_s })
         Printavo::Order.new(data['order'])
       end
+
+      private
+
+      def fetch_page(first: 25, after: nil, **)
+        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
+        nodes = data['orders']['nodes'].map { |attrs| Printavo::Order.new(attrs) }
+        page_info = data['orders']['pageInfo']
+        Printavo::Page.new(
+          records: nodes,
+          has_next_page: page_info['hasNextPage'],
+          end_cursor: page_info['endCursor']
+        )
+      end
     end
   end
 end

data/lib/printavo/resources/statuses.rb

@@ -29,8 +29,7 @@ module Printavo
       GQL
 
       def all(first: 100, after: nil)
-        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
-        data['statuses']['nodes'].map { |attrs| Printavo::Status.new(attrs) }
+        fetch_page(first: first, after: after).records
       end
 
       def find(id)
@@ -45,6 +44,19 @@ module Printavo
       def registry
         all.to_h { |status| [status.key, status] }
       end
+
+      private
+
+      def fetch_page(first: 100, after: nil, **)
+        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
+        nodes = data['statuses']['nodes'].map { |attrs| Printavo::Status.new(attrs) }
+        page_info = data['statuses']['pageInfo']
+        Printavo::Page.new(
+          records: nodes,
+          has_next_page: page_info['hasNextPage'],
+          end_cursor: page_info['endCursor']
+        )
+      end
     end
   end
 end

data/lib/printavo/version.rb

@@ -1,4 +1,4 @@
 # lib/printavo/version.rb
 module Printavo
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/lib/printavo.rb

@@ -8,6 +8,7 @@ require_relative 'printavo/errors'
 require_relative 'printavo/config'
 require_relative 'printavo/connection'
 require_relative 'printavo/graphql_client'
+require_relative 'printavo/page'
 require_relative 'printavo/models/base'
 require_relative 'printavo/models/customer'
 require_relative 'printavo/models/status'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: printavo-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Stan Carver II
@@ -277,6 +277,7 @@ files:
 - lib/printavo/models/job.rb
 - lib/printavo/models/order.rb
 - lib/printavo/models/status.rb
+- lib/printavo/page.rb
 - lib/printavo/resources/base.rb
 - lib/printavo/resources/customers.rb
 - lib/printavo/resources/inquiries.rb