printavo-ruby 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bdc16c358a3dafbdae1842e0ddb8eebbe8775053b1b95efb2308cd33056e2ea
-  data.tar.gz: 7399f57922f9244a02900c458bf9d2b9830aa0d63a5b4ff07952ca3ade6254fd
+  metadata.gz: 34f4d971a1f4d0c685fb6780bc12d7737c915d533bc49c9d96fb5c73522eec58
+  data.tar.gz: 687c158df7fa205ac7aa5607bb2c6a7171ee7eac972005b0b5d102cee3b7dd0d
 SHA512:
-  metadata.gz: fa26e26063d2ed94011d20f22c4ae6c9fa964c62d2fa07b31343b97f2d1e9dbe623114960dab489cca029fe0d1f036964c7748b27a96e1c2eb7d63d33d3d285f
-  data.tar.gz: 0427ed5bc1601858080cb1f057547cb4143cc51d32cbd7189fa4fc8546260045c11603204814e28656b26a97f00e286634b24f8b536c879d14e5f8dd44f8313c
+  metadata.gz: 402856b46761b8a924bd92a5e433d99faf0f5aa976b9e7e9e4a2e35ee814dda18e4caddafe40f890507832535e233596e6979a439a26895bf20a8caefe8979ad
+  data.tar.gz: dd48f4059d8d5d596e1a3e569cdecaa3842c79713ea2da48c112c86664c42f418c035988bbc9c11e48e337508e6af6aa8f6c9938bacf762eda79a5b2e6366e76

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
@@ -294,7 +345,7 @@ end
 | 0.2.0 | Status registry + Inquiries ✅ |
 | 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.5.0 | Mutations (create/update) ✅ |
 | 0.6.0 | Analytics / Reporting queries |
 | 0.7.0 | Community burn-in / API stabilization |
 | 0.8.0 | Retry/backoff + rate limit awareness |

data/docs/CHANGELOG.md

@@ -8,6 +8,22 @@ 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

data/lib/printavo/client.rb

@@ -1,4 +1,6 @@
 # lib/printavo/client.rb
+# frozen_string_literal: true
+
 module Printavo
   class Client
     attr_reader :graphql

data/lib/printavo/config.rb

@@ -1,9 +1,11 @@
 # lib/printavo/config.rb
+# frozen_string_literal: true
+
 module Printavo
   class Config
     attr_accessor :email, :token, :base_url, :timeout
 
-    BASE_URL = 'https://www.printavo.com/api/v2'.freeze
+    BASE_URL = 'https://www.printavo.com/api/v2'
 
     def initialize
       @base_url = BASE_URL

data/lib/printavo/connection.rb

@@ -1,4 +1,6 @@
 # lib/printavo/connection.rb
+# frozen_string_literal: true
+
 require 'faraday'
 require 'faraday/retry'
 

data/lib/printavo/errors.rb

@@ -1,4 +1,6 @@
 # lib/printavo/errors.rb
+# frozen_string_literal: true
+
 module Printavo
   class Error < StandardError; end
 

data/lib/printavo/graphql_client.rb

@@ -1,4 +1,6 @@
 # lib/printavo/graphql_client.rb
+# frozen_string_literal: true
+
 require 'json'
 
 module Printavo

data/lib/printavo/models/base.rb

@@ -1,4 +1,6 @@
 # lib/printavo/models/base.rb
+# frozen_string_literal: true
+
 module Printavo
   module Models
     class Base

data/lib/printavo/models/customer.rb

@@ -1,4 +1,6 @@
 # lib/printavo/models/customer.rb
+# frozen_string_literal: true
+
 module Printavo
   class Customer < Models::Base
     def id         = self['id']

data/lib/printavo/models/inquiry.rb

@@ -1,4 +1,6 @@
 # lib/printavo/models/inquiry.rb
+# frozen_string_literal: true
+
 module Printavo
   class Inquiry < Models::Base
     def id          = self['id']

data/lib/printavo/models/job.rb

@@ -1,4 +1,6 @@
 # lib/printavo/models/job.rb
+# frozen_string_literal: true
+
 module Printavo
   class Job < Models::Base
     def id       = self['id']

data/lib/printavo/models/order.rb

@@ -1,4 +1,6 @@
 # lib/printavo/models/order.rb
+# frozen_string_literal: true
+
 module Printavo
   class Order < Models::Base
     def id          = self['id']

data/lib/printavo/models/status.rb

@@ -1,4 +1,6 @@
 # lib/printavo/models/status.rb
+# frozen_string_literal: true
+
 module Printavo
   class Status < Models::Base
     def id    = self['id']

data/lib/printavo/page.rb

@@ -1,4 +1,6 @@
 # lib/printavo/page.rb
+# frozen_string_literal: true
+
 module Printavo
   # Wraps a single page of API results with cursor metadata.
   #

data/lib/printavo/resources/base.rb

@@ -1,4 +1,6 @@
 # lib/printavo/resources/base.rb
+# frozen_string_literal: true
+
 module Printavo
   module Resources
     class Base

data/lib/printavo/resources/customers.rb

@@ -1,38 +1,13 @@
 # lib/printavo/resources/customers.rb
+# frozen_string_literal: true
+
 module Printavo
   module Resources
     class Customers < Base
-      ALL_QUERY = <<~GQL.freeze
-        query Customers($first: Int, $after: String) {
-          customers(first: $first, after: $after) {
-            nodes {
-              id
-              firstName
-              lastName
-              email
-              phone
-              company
-            }
-            pageInfo {
-              hasNextPage
-              endCursor
-            }
-          }
-        }
-      GQL
-
-      FIND_QUERY = <<~GQL.freeze
-        query Customer($id: ID!) {
-          customer(id: $id) {
-            id
-            firstName
-            lastName
-            email
-            phone
-            company
-          }
-        }
-      GQL
+      ALL_QUERY      = File.read(File.join(__dir__, '../graphql/customers/all.graphql')).freeze
+      FIND_QUERY     = File.read(File.join(__dir__, '../graphql/customers/find.graphql')).freeze
+      CREATE_MUTATION = File.read(File.join(__dir__, '../graphql/customers/create.graphql')).freeze
+      UPDATE_MUTATION = File.read(File.join(__dir__, '../graphql/customers/update.graphql')).freeze
 
       def all(first: 25, after: nil)
         fetch_page(first: first, after: after).records
@@ -43,6 +18,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 +60,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

@@ -1,56 +1,13 @@
 # lib/printavo/resources/inquiries.rb
+# frozen_string_literal: true
+
 module Printavo
   module Resources
     class Inquiries < Base
-      ALL_QUERY = <<~GQL.freeze
-        query Inquiries($first: Int, $after: String) {
-          inquiries(first: $first, after: $after) {
-            nodes {
-              id
-              nickname
-              totalPrice
-              status {
-                id
-                name
-                color
-              }
-              customer {
-                id
-                firstName
-                lastName
-                email
-                company
-              }
-            }
-            pageInfo {
-              hasNextPage
-              endCursor
-            }
-          }
-        }
-      GQL
-
-      FIND_QUERY = <<~GQL.freeze
-        query Inquiry($id: ID!) {
-          inquiry(id: $id) {
-            id
-            nickname
-            totalPrice
-            status {
-              id
-              name
-              color
-            }
-            customer {
-              id
-              firstName
-              lastName
-              email
-              company
-            }
-          }
-        }
-      GQL
+      ALL_QUERY       = File.read(File.join(__dir__, '../graphql/inquiries/all.graphql')).freeze
+      FIND_QUERY      = File.read(File.join(__dir__, '../graphql/inquiries/find.graphql')).freeze
+      CREATE_MUTATION = File.read(File.join(__dir__, '../graphql/inquiries/create.graphql')).freeze
+      UPDATE_MUTATION = File.read(File.join(__dir__, '../graphql/inquiries/update.graphql')).freeze
 
       def all(first: 25, after: nil)
         fetch_page(first: first, after: after).records
@@ -61,6 +18,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/jobs.rb

@@ -1,38 +1,11 @@
 # lib/printavo/resources/jobs.rb
+# frozen_string_literal: true
+
 module Printavo
   module Resources
     class Jobs < Base
-      ALL_QUERY = <<~GQL.freeze
-        query LineItems($orderId: ID!, $first: Int, $after: String) {
-          order(id: $orderId) {
-            lineItems(first: $first, after: $after) {
-              nodes {
-                id
-                name
-                quantity
-                price
-                taxable
-              }
-              pageInfo {
-                hasNextPage
-                endCursor
-              }
-            }
-          }
-        }
-      GQL
-
-      FIND_QUERY = <<~GQL.freeze
-        query LineItem($id: ID!) {
-          lineItem(id: $id) {
-            id
-            name
-            quantity
-            price
-            taxable
-          }
-        }
-      GQL
+      ALL_QUERY  = File.read(File.join(__dir__, '../graphql/jobs/all.graphql')).freeze
+      FIND_QUERY = File.read(File.join(__dir__, '../graphql/jobs/find.graphql')).freeze
 
       def all(order_id:, first: 25, after: nil)
         fetch_page(order_id: order_id, first: first, after: after).records

data/lib/printavo/resources/orders.rb

@@ -1,56 +1,16 @@
 # lib/printavo/resources/orders.rb
+# frozen_string_literal: true
+
 module Printavo
   module Resources
     class Orders < Base
-      ALL_QUERY = <<~GQL.freeze
-        query Orders($first: Int, $after: String) {
-          orders(first: $first, after: $after) {
-            nodes {
-              id
-              nickname
-              totalPrice
-              status {
-                id
-                name
-                color
-              }
-              customer {
-                id
-                firstName
-                lastName
-                email
-                company
-              }
-            }
-            pageInfo {
-              hasNextPage
-              endCursor
-            }
-          }
-        }
-      GQL
-
-      FIND_QUERY = <<~GQL.freeze
-        query Order($id: ID!) {
-          order(id: $id) {
-            id
-            nickname
-            totalPrice
-            status {
-              id
-              name
-              color
-            }
-            customer {
-              id
-              firstName
-              lastName
-              email
-              company
-            }
-          }
-        }
-      GQL
+      ALL_QUERY      = File.read(File.join(__dir__, '../graphql/orders/all.graphql')).freeze
+      FIND_QUERY     = File.read(File.join(__dir__, '../graphql/orders/find.graphql')).freeze
+      # Printavo creates orders as quotes first; the mutation is quoteCreate.
+      CREATE_MUTATION        = File.read(File.join(__dir__, '../graphql/orders/create.graphql')).freeze
+      UPDATE_MUTATION        = File.read(File.join(__dir__, '../graphql/orders/update.graphql')).freeze
+      # statusUpdate returns an OrderUnion (Quote | Invoice) — requires fragments.
+      UPDATE_STATUS_MUTATION = File.read(File.join(__dir__, '../graphql/orders/update_status.graphql')).freeze
 
       def all(first: 25, after: nil)
         fetch_page(first: first, after: after).records
@@ -61,6 +21,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 +77,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/resources/statuses.rb

@@ -1,32 +1,11 @@
 # lib/printavo/resources/statuses.rb
+# frozen_string_literal: true
+
 module Printavo
   module Resources
     class Statuses < Base
-      ALL_QUERY = <<~GQL.freeze
-        query Statuses($first: Int, $after: String) {
-          statuses(first: $first, after: $after) {
-            nodes {
-              id
-              name
-              color
-            }
-            pageInfo {
-              hasNextPage
-              endCursor
-            }
-          }
-        }
-      GQL
-
-      FIND_QUERY = <<~GQL.freeze
-        query Status($id: ID!) {
-          status(id: $id) {
-            id
-            name
-            color
-          }
-        }
-      GQL
+      ALL_QUERY  = File.read(File.join(__dir__, '../graphql/statuses/all.graphql')).freeze
+      FIND_QUERY = File.read(File.join(__dir__, '../graphql/statuses/find.graphql')).freeze
 
       def all(first: 100, after: nil)
         fetch_page(first: first, after: after).records

data/lib/printavo/version.rb

@@ -1,4 +1,6 @@
 # lib/printavo/version.rb
+# frozen_string_literal: true
+
 module Printavo
-  VERSION = '0.4.0'.freeze
+  VERSION = '0.5.1'
 end

data/lib/printavo/webhooks.rb

@@ -1,4 +1,6 @@
 # lib/printavo/webhooks.rb
+# frozen_string_literal: true
+
 require 'openssl'
 
 module Printavo

data/lib/printavo.rb

@@ -1,4 +1,6 @@
 # lib/printavo.rb
+# frozen_string_literal: true
+
 require 'faraday'
 require 'faraday/retry'
 require 'json'

metadata

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