printavo-ruby 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7786dadca364f38068636a9a6e30efac78ac79107c8dfb4ade22b39db5f0bc1
-  data.tar.gz: f0464978791f12c8e3f5d37d2de09ecfc4b97e57aca4999beda995b68957d2e1
+  metadata.gz: 5c8061b68869c47ca86f6c37dc51d60020c035364ea70c68e68bad1df2f4da6c
+  data.tar.gz: 1d9c8f4d5805ab82bca17f28891fdc21899f2b166638c4e100e8531c8275073f
 SHA512:
-  metadata.gz: a6aae8c15d5f5c348d8e717c09eaf85092a9421d473541ac1ef3c38042534ed1aa14c6e0c5283d6878325cdf32a7325fed52e980913e7b15e8c443ed64a695bb
-  data.tar.gz: bac95ec4243aa408c495f88d7c4841a308f7c49f509d8b7a0f3a4a161cb9db30418d2ba2c79be67f353c89b68d24cec6f70c1487b64496ea5ef74489fe44acc8
+  metadata.gz: 9b39cbc93da67a0b81114fa7209720d944d6ee87cd77763876191ce907a38498cf9c3020548b4f3f23f2a3a675bdd5b7f6ccf80ba937e1c929372e6cfe00761d
+  data.tar.gz: ab0e28809466df5269eece7960b2d425c1d4f15db68361c55aa730909bd3662b8ac9f1e256c49218e7cc03febe71c96661d64a2c472bb96bc2aa8c0f8b97ab13

data/README.md

@@ -136,6 +136,57 @@ end
 all_jobs = client.jobs.all_pages(order_id: "99")
 ```
 
+### Mutations
+
+#### Customers
+
+```ruby
+# Create
+customer = client.customers.create(
+  primary_contact: { firstName: "Jane", lastName: "Smith", email: "jane@example.com" },
+  company_name: "Acme Shirts"
+)
+puts customer.full_name   # => "Jane Smith"
+puts customer.company     # => "Acme Shirts"
+
+# Update
+customer = client.customers.update("42", company_name: "New Name Inc")
+```
+
+#### Orders
+
+```ruby
+# Create (Printavo creates orders as quotes first)
+order = client.orders.create(
+  contact:          { id: "456" },
+  due_at:           "2026-06-01T09:00:00Z",
+  customer_due_at:  "2026-06-01",
+  nickname:         "Summer Rush"
+)
+
+# Update
+order = client.orders.update("99", nickname: "Rush Job", production_note: "Ships Friday")
+
+# Move to a new status
+registry = client.statuses.registry
+order = client.orders.update_status("99", status_id: registry[:in_production].id)
+puts order.status   # => "In Production"
+```
+
+#### Inquiries
+
+```ruby
+# Create
+inquiry = client.inquiries.create(
+  name:    "Bob Johnson",
+  email:   "bob@example.com",
+  request: "100 hoodies, front + back print"
+)
+
+# Update
+inquiry = client.inquiries.update("55", nickname: "Hoodies Rush")
+```
+
 ### Statuses
 
 ```ruby
@@ -196,6 +247,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 +344,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.5.0 | Mutations (create/update) |
+| 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,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-03-30
+
+### Added
+- `Customers#create(primary_contact:, **input)` — `customerCreate` mutation; normalizes `primaryContact` + `companyName` response fields to match the read-side `Customer` model
+- `Customers#update(id, **input)` — `customerUpdate` mutation
+- `Orders#create(**input)` — `quoteCreate` mutation; normalizes `total` → `totalPrice` in response
+- `Orders#update(id, **input)` — `quoteUpdate` mutation
+- `Orders#update_status(id, status_id:)` — `statusUpdate` mutation; handles `OrderUnion (Quote | Invoice)` via inline fragments
+- `Inquiries#create(**input)` — `inquiryCreate` mutation
+- `Inquiries#update(id, **input)` — `inquiryUpdate` mutation
+- All mutation methods accept snake_case keyword args and camelize them for GraphQL input
+- `CREATE_MUTATION` and `UPDATE_MUTATION` constants on `Customers`, `Orders`, `Inquiries`; `UPDATE_STATUS_MUTATION` on `Orders`
+- Private `build_customer` and `build_order` normalizers centralize mutation response mapping
+- Private `camelize_keys` on `Customers` and `Orders` converts `snake_case` → `camelCase` for input variables
+- Factory helpers `fake_customer_mutation_response` and `fake_order_mutation_response` for testing
+
+## [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/resources/customers.rb

@@ -34,6 +34,38 @@ module Printavo
         }
       GQL
 
+      CREATE_MUTATION = <<~GQL.freeze
+        mutation CustomerCreate($input: CustomerCreateInput!) {
+          customerCreate(input: $input) {
+            id
+            companyName
+            primaryContact {
+              id
+              firstName
+              lastName
+              email
+              phone
+            }
+          }
+        }
+      GQL
+
+      UPDATE_MUTATION = <<~GQL.freeze
+        mutation CustomerUpdate($id: ID!, $input: CustomerInput!) {
+          customerUpdate(id: $id, input: $input) {
+            id
+            companyName
+            primaryContact {
+              id
+              firstName
+              lastName
+              email
+              phone
+            }
+          }
+        }
+      GQL
+
       def all(first: 25, after: nil)
         fetch_page(first: first, after: after).records
       end
@@ -43,6 +75,36 @@ module Printavo
         Printavo::Customer.new(data['customer'])
       end
 
+      # Creates a new customer. Requires a +primary_contact+ hash with at least
+      # +firstName+ and +email+. Optional keyword arguments map to CustomerCreateInput.
+      #
+      # @param primary_contact [Hash] contact fields (firstName, lastName, email, phone)
+      # @return [Printavo::Customer]
+      #
+      # @example
+      #   client.customers.create(
+      #     primary_contact: { firstName: "Jane", lastName: "Smith", email: "jane@example.com" },
+      #     company_name: "Acme Shirts"
+      #   )
+      def create(primary_contact:, **input)
+        variables = { input: camelize_keys(input).merge(primaryContact: primary_contact) }
+        data = @graphql.mutate(CREATE_MUTATION, variables: variables)
+        build_customer(data['customerCreate'])
+      end
+
+      # Updates an existing customer by ID.
+      #
+      # @param id  [String, Integer]
+      # @return [Printavo::Customer]
+      #
+      # @example
+      #   client.customers.update("42", company_name: "New Name")
+      def update(id, **input)
+        data = @graphql.mutate(UPDATE_MUTATION,
+                               variables: { id: id.to_s, input: camelize_keys(input) })
+        build_customer(data['customerUpdate'])
+      end
+
       private
 
       def fetch_page(first: 25, after: nil, **)
@@ -55,6 +117,29 @@ module Printavo
           end_cursor: page_info['endCursor']
         )
       end
+
+      # Normalizes a mutation response into the shape Customer.new expects.
+      # The mutation returns companyName + nested primaryContact; our model
+      # reads company, firstName, lastName, email, phone from the top level.
+      def build_customer(attrs)
+        return nil unless attrs
+
+        normalized = attrs.dup
+        normalized['company'] ||= attrs['companyName']
+        if (contact = attrs['primaryContact'])
+          %w[firstName lastName email phone].each do |field|
+            normalized[field] ||= contact[field]
+          end
+        end
+        Printavo::Customer.new(normalized)
+      end
+
+      # Converts snake_case Ruby keyword args to camelCase for GraphQL input.
+      def camelize_keys(hash)
+        hash.transform_keys do |key|
+          key.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
+        end
+      end
     end
   end
 end

data/lib/printavo/resources/inquiries.rb

@@ -52,6 +52,50 @@ module Printavo
         }
       GQL
 
+      CREATE_MUTATION = <<~GQL.freeze
+        mutation InquiryCreate($input: InquiryCreateInput!) {
+          inquiryCreate(input: $input) {
+            id
+            nickname
+            totalPrice
+            status {
+              id
+              name
+              color
+            }
+            customer {
+              id
+              firstName
+              lastName
+              email
+              company
+            }
+          }
+        }
+      GQL
+
+      UPDATE_MUTATION = <<~GQL.freeze
+        mutation InquiryUpdate($id: ID!, $input: InquiryInput!) {
+          inquiryUpdate(id: $id, input: $input) {
+            id
+            nickname
+            totalPrice
+            status {
+              id
+              name
+              color
+            }
+            customer {
+              id
+              firstName
+              lastName
+              email
+              company
+            }
+          }
+        }
+      GQL
+
       def all(first: 25, after: nil)
         fetch_page(first: first, after: after).records
       end
@@ -61,6 +105,31 @@ module Printavo
         Printavo::Inquiry.new(data['inquiry'])
       end
 
+      # Creates a new inquiry. Requires +name:+ at minimum.
+      #
+      # @return [Printavo::Inquiry]
+      #
+      # @example
+      #   client.inquiries.create(name: "Jane Smith", email: "jane@example.com",
+      #                           request: "100 hoodies, front + back print")
+      def create(**input)
+        data = @graphql.mutate(CREATE_MUTATION, variables: { input: input })
+        Printavo::Inquiry.new(data['inquiryCreate'])
+      end
+
+      # Updates an existing inquiry by ID.
+      #
+      # @param id [String, Integer]
+      # @return [Printavo::Inquiry]
+      #
+      # @example
+      #   client.inquiries.update("55", nickname: "Hoodies Rush")
+      def update(id, **input)
+        data = @graphql.mutate(UPDATE_MUTATION,
+                               variables: { id: id.to_s, input: input })
+        Printavo::Inquiry.new(data['inquiryUpdate'])
+      end
+
       private
 
       def fetch_page(first: 25, after: nil, **)

data/lib/printavo/resources/orders.rb

@@ -52,6 +52,73 @@ module Printavo
         }
       GQL
 
+      # Printavo creates orders as quotes first; the mutation is quoteCreate.
+      CREATE_MUTATION = <<~GQL.freeze
+        mutation QuoteCreate($input: QuoteCreateInput!) {
+          quoteCreate(input: $input) {
+            id
+            nickname
+            total
+            status {
+              id
+              name
+              color
+            }
+            customer {
+              id
+              firstName
+              lastName
+              email
+              company
+            }
+          }
+        }
+      GQL
+
+      UPDATE_MUTATION = <<~GQL.freeze
+        mutation QuoteUpdate($id: ID!, $input: QuoteInput!) {
+          quoteUpdate(id: $id, input: $input) {
+            id
+            nickname
+            total
+            status {
+              id
+              name
+              color
+            }
+            customer {
+              id
+              firstName
+              lastName
+              email
+              company
+            }
+          }
+        }
+      GQL
+
+      # statusUpdate returns an OrderUnion (Quote | Invoice) — requires fragments.
+      UPDATE_STATUS_MUTATION = <<~GQL.freeze
+        mutation StatusUpdate($parentId: ID!, $statusId: ID!) {
+          statusUpdate(parentId: $parentId, statusId: $statusId) {
+            ... on Quote {
+              id
+              nickname
+              total
+              status { id name color }
+              customer { id firstName lastName email company }
+            }
+            ... on Invoice {
+              id
+              nickname
+              total
+              status { id name color }
+              customer { id firstName lastName email company }
+            }
+          }
+        }
+      GQL
+
       def all(first: 25, after: nil)
         fetch_page(first: first, after: after).records
       end
@@ -61,6 +128,50 @@ module Printavo
         Printavo::Order.new(data['order'])
       end
 
+      # Creates a new order (quote) in Printavo.
+      # Requires at minimum +contact:+ (IDInput), +due_at:+, and +customer_due_at:+.
+      #
+      # @return [Printavo::Order]
+      #
+      # @example
+      #   client.orders.create(
+      #     contact: { id: "456" },
+      #     due_at: "2026-06-01T09:00:00Z",
+      #     customer_due_at: "2026-06-01"
+      #   )
+      def create(**input)
+        data = @graphql.mutate(CREATE_MUTATION, variables: { input: camelize_keys(input) })
+        build_order(data['quoteCreate'])
+      end
+
+      # Updates an existing order (quote or invoice) by ID.
+      #
+      # @param id [String, Integer]
+      # @return [Printavo::Order]
+      #
+      # @example
+      #   client.orders.update("99", nickname: "Rush Job", production_note: "Ships Friday")
+      def update(id, **input)
+        data = @graphql.mutate(UPDATE_MUTATION,
+                               variables: { id: id.to_s, input: camelize_keys(input) })
+        build_order(data['quoteUpdate'])
+      end
+
+      # Moves an order to a new status.
+      #
+      # @param id        [String, Integer] order (quote/invoice) ID
+      # @param status_id [String, Integer] target status ID
+      # @return [Printavo::Order]
+      #
+      # @example
+      #   registry = client.statuses.registry
+      #   client.orders.update_status("99", status_id: registry[:in_production].id)
+      def update_status(id, status_id:)
+        data = @graphql.mutate(UPDATE_STATUS_MUTATION,
+                               variables: { parentId: id.to_s, statusId: status_id.to_s })
+        build_order(data['statusUpdate'])
+      end
+
       private
 
       def fetch_page(first: 25, after: nil, **)
@@ -73,6 +184,22 @@ module Printavo
           end_cursor: page_info['endCursor']
         )
       end
+
+      # Normalizes mutation response: quoteCreate/quoteUpdate return `total`
+      # rather than `totalPrice`. Map it so Order model accessors work unchanged.
+      def build_order(attrs)
+        return nil unless attrs
+
+        normalized = attrs.dup
+        normalized['totalPrice'] ||= attrs['total']
+        Printavo::Order.new(normalized)
+      end
+
+      def camelize_keys(hash)
+        hash.transform_keys do |key|
+          key.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
+        end
+      end
     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.5.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.5.0
 platform: ruby
 authors:
 - Stan Carver II