printavo-ruby 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7786dadca364f38068636a9a6e30efac78ac79107c8dfb4ade22b39db5f0bc1
-  data.tar.gz: f0464978791f12c8e3f5d37d2de09ecfc4b97e57aca4999beda995b68957d2e1
+  metadata.gz: 4bdc16c358a3dafbdae1842e0ddb8eebbe8775053b1b95efb2308cd33056e2ea
+  data.tar.gz: 7399f57922f9244a02900c458bf9d2b9830aa0d63a5b4ff07952ca3ade6254fd
 SHA512:
-  metadata.gz: a6aae8c15d5f5c348d8e717c09eaf85092a9421d473541ac1ef3c38042534ed1aa14c6e0c5283d6878325cdf32a7325fed52e980913e7b15e8c443ed64a695bb
-  data.tar.gz: bac95ec4243aa408c495f88d7c4841a308f7c49f509d8b7a0f3a4a161cb9db30418d2ba2c79be67f353c89b68d24cec6f70c1487b64496ea5ef74489fe44acc8
+  metadata.gz: fa26e26063d2ed94011d20f22c4ae6c9fa964c62d2fa07b31343b97f2d1e9dbe623114960dab489cca029fe0d1f036964c7748b27a96e1c2eb7d63d33d3d285f
+  data.tar.gz: 0427ed5bc1601858080cb1f057547cb4143cc51d32cbd7189fa4fc8546260045c11603204814e28656b26a97f00e286634b24f8b536c879d14e5f8dd44f8313c

data/README.md

@@ -196,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.
@@ -257,12 +293,11 @@ end
 | 0.1.0 | Auth + Customers + Orders + Jobs + Webhooks (Rack-compatible) ✅ |
 | 0.2.0 | Status registry + Inquiries ✅ |
 | 0.3.0 | Pagination helpers (`each_page`, `all_pages`) + `bin/lint` ✅ |
-| 0.4.0 | Expanded GraphQL DSL |
+| 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,15 @@ 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

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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: printavo-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Stan Carver II