printavo-ruby 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c80d0cf1950d67050c32a5d20e9bc6d001587fb509c3f52831b6dfbec77e5b3
-  data.tar.gz: 2d117bae60f460bd9ba9aaa2571bdeacb4915e361224e3f3d61183e2b52a33df
+  metadata.gz: 4bdc16c358a3dafbdae1842e0ddb8eebbe8775053b1b95efb2308cd33056e2ea
+  data.tar.gz: 7399f57922f9244a02900c458bf9d2b9830aa0d63a5b4ff07952ca3ade6254fd
 SHA512:
-  metadata.gz: 1858601061541936154d9d8daad2b30950dd737501502681e266966f8de415eb84f15c0fa9ba3d8ac2725a27990d8cb000728a9be03c0d5c7e86c13362d53b06
-  data.tar.gz: 3ff3869148ccbabb980d352b1a3270de1c63d18eaf6d512a96fb116cd9c346718f90b7121a13455d582b7e205a1736ee357437f8f1a34cd9e83b572cd7d63184
+  metadata.gz: fa26e26063d2ed94011d20f22c4ae6c9fa964c62d2fa07b31343b97f2d1e9dbe623114960dab489cca029fe0d1f036964c7748b27a96e1c2eb7d63d33d3d285f
+  data.tar.gz: 0427ed5bc1601858080cb1f057547cb4143cc51d32cbd7189fa4fc8546260045c11603204814e28656b26a97f00e286634b24f8b536c879d14e5f8dd44f8313c

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
@@ -176,6 +196,42 @@ result = client.graphql.query(
 )
 ```
 
+### Mutations
+
+Use `mutate` for GraphQL write operations:
+
+```ruby
+result = client.graphql.mutate(
+  <<~GQL,
+    mutation UpdateOrder($id: ID!, $nickname: String!) {
+      updateOrder(id: $id, input: { nickname: $nickname }) {
+        order { id nickname }
+        errors
+      }
+    }
+  GQL
+  variables: { id: "99", nickname: "Rush Job" }
+)
+result["updateOrder"]["order"]["nickname"]   # => "Rush Job"
+```
+
+### Raw GraphQL Pagination
+
+Paginate any custom query without a resource wrapper using `paginate`.
+The `path:` option is dot-separated and maps to the connection in the response:
+
+```ruby
+client.graphql.paginate(MY_QUERY, path: "orders", first: 50) do |nodes|
+  nodes.each { |n| puts n["nickname"] }
+end
+
+# Nested connection (e.g. order.lineItems)
+client.graphql.paginate(JOBS_QUERY, path: "order.lineItems",
+                                    variables: { orderId: "99" }) do |nodes|
+  nodes.each { |j| puts j["name"] }
+end
+```
+
 ## Webhooks
 
 `Printavo::Webhooks.verify` provides Rack-compatible HMAC-SHA256 signature verification.
@@ -234,15 +290,14 @@ 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.4.0 | Expanded GraphQL DSL |
+| 0.3.0 | Pagination helpers (`each_page`, `all_pages`) + `bin/lint` ✅ |
+| 0.4.0 | Expanded GraphQL DSL (`mutate`, `paginate`) ✅ |
 | 0.5.0 | Mutations (create/update) |
 | 0.6.0 | Analytics / Reporting queries |
 | 0.7.0 | Community burn-in / API stabilization |
-| 0.8.0 | Pagination abstraction helpers |
-| 0.9.0 | Retry/backoff + rate limit awareness |
+| 0.8.0 | Retry/backoff + rate limit awareness |
 | 1.0.0 | Stable public SDK |
 
 **Rules**: `PATCH` = bug fix · `MINOR` = new backward-compatible feature · `MAJOR` = breaking change

data/docs/CHANGELOG.md

@@ -8,6 +8,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-30
+
+### Added
+- `GraphqlClient#mutate` — semantic method for GraphQL mutations; identical transport to `query` but signals write intent at the call site; lays the foundation for 0.5.0 resource-level mutations
+- `GraphqlClient#paginate` — cursor-following pagination for raw GraphQL queries; accepts a dot-separated `path:` to resolve nested connections (e.g. `"order.lineItems"`); yields each page's `nodes` array
+- `GraphqlClient#execute` (private) — extracted shared POST logic; `query` and `mutate` both delegate to it
+- `GraphqlClient#dig_path` (private) — resolves dot-separated key paths against nested response hashes
+- Roadmap: removed stale Pagination entry from 0.8.0 (shipped in 0.3.0); Retry/backoff renumbered to 0.8.0
+
+## [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/docs/FUTURE.md

@@ -20,21 +20,6 @@ printavo sync orders --to crm
 
 Planned version: `0.7.0`
 
-### Pagination Abstraction
-
-A lazy-enumerator-style helper to automatically page through all results:
-
-```ruby
-client.customers.each_page do |page|
-  page.each { |c| process(c) }
-end
-
-# Or collect all:
-all_orders = client.orders.all_pages
-```
-
-Planned version: `0.8.0`
-
 ### Retry/Backoff
 
 Intelligent rate limit handling with exponential backoff:
@@ -48,7 +33,7 @@ client = Printavo::Client.new(
 )
 ```
 
-Planned version: `0.9.0`
+Planned version: `0.8.0`
 
 ### Analytics / Reporting Expansion
 

data/lib/printavo/graphql_client.rb

@@ -7,16 +7,90 @@ module Printavo
       @connection = connection
     end
 
+    # Executes a GraphQL query and returns the parsed `data` hash.
+    #
+    # @param query_string [String] the GraphQL query document
+    # @param variables    [Hash]   optional input variables
+    # @return [Hash]
+    #
+    # @example
+    #   client.graphql.query("{ customers { nodes { id } } }")
+    #   client.graphql.query(
+    #     "query Customer($id: ID!) { customer(id: $id) { id email } }",
+    #     variables: { id: "42" }
+    #   )
     def query(query_string, variables: {})
-      response = @connection.post('') do |req|
-        req.body = JSON.generate(query: query_string, variables: variables)
-      end
+      execute(query_string, variables: variables)
+    end
 
-      handle_response(response)
+    # Executes a GraphQL mutation and returns the parsed `data` hash.
+    # Semantically equivalent to `query` — both POST to the same endpoint —
+    # but distinguishes write intent at the call site.
+    #
+    # @param mutation_string [String] the GraphQL mutation document
+    # @param variables       [Hash]   optional input variables
+    # @return [Hash]
+    #
+    # @example
+    #   client.graphql.mutate(
+    #     <<~GQL,
+    #       mutation UpdateOrder($id: ID!, $input: OrderInput!) {
+    #         updateOrder(id: $id, input: $input) {
+    #           order { id nickname }
+    #           errors
+    #         }
+    #       }
+    #     GQL
+    #     variables: { id: "99", input: { nickname: "Rush Job" } }
+    #   )
+    def mutate(mutation_string, variables: {})
+      execute(mutation_string, variables: variables)
+    end
+
+    # Iterates all pages of a paginated GraphQL query, yielding each page's
+    # nodes array. The query must accept `$first: Int` and `$after: String`
+    # variables, and the target connection must expose `nodes` and `pageInfo`.
+    #
+    # @param query_string [String] the GraphQL query document
+    # @param path         [String] dot-separated key path to the connection in the response
+    #                              e.g. "orders" or "customer.orders"
+    # @param variables    [Hash]   additional variables merged with `first` and `after`
+    # @param first        [Integer] page size (default 25)
+    # @yieldparam nodes   [Array<Hash>] one page of raw node hashes
+    #
+    # @example
+    #   client.graphql.paginate(ORDERS_QUERY, path: "orders") do |nodes|
+    #     nodes.each { |n| puts n["nickname"] }
+    #   end
+    #
+    # @example With extra variables
+    #   client.graphql.paginate(JOBS_QUERY, path: "order.lineItems",
+    #                           variables: { orderId: "99" }, first: 50) do |nodes|
+    #     nodes.each { |j| puts j["name"] }
+    #   end
+    def paginate(query_string, path:, variables: {}, first: 25)
+      after = nil
+      loop do
+        data  = execute(query_string, variables: variables.merge(first: first, after: after))
+        conn  = dig_path(data, path)
+        nodes = conn&.fetch('nodes', []) || []
+        yield nodes
+        page_info = conn&.fetch('pageInfo', {}) || {}
+        break unless page_info['hasNextPage']
+
+        after = page_info['endCursor']
+      end
     end
 
     private
 
+    def execute(document, variables: {})
+      response = @connection.post('') do |req|
+        req.body = JSON.generate(query: document, variables: variables)
+      end
+      handle_response(response)
+    end
+
     def handle_response(response)
       body = response.body
 
@@ -34,5 +108,11 @@ module Printavo
 
       body.is_a?(Hash) ? body['data'] : body
     end
+
+    # Resolves a dot-separated path against a nested hash.
+    # e.g. dig_path(data, "customer.orders") => data["customer"]["orders"]
+    def dig_path(data, path)
+      path.split('.').reduce(data) { |obj, key| obj.is_a?(Hash) ? obj[key] : nil }
+    end
   end
 end

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.4.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.4.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