printavo-ruby 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bdc16c358a3dafbdae1842e0ddb8eebbe8775053b1b95efb2308cd33056e2ea
-  data.tar.gz: 7399f57922f9244a02900c458bf9d2b9830aa0d63a5b4ff07952ca3ade6254fd
+  metadata.gz: 5c8061b68869c47ca86f6c37dc51d60020c035364ea70c68e68bad1df2f4da6c
+  data.tar.gz: 1d9c8f4d5805ab82bca17f28891fdc21899f2b166638c4e100e8531c8275073f
 SHA512:
-  metadata.gz: fa26e26063d2ed94011d20f22c4ae6c9fa964c62d2fa07b31343b97f2d1e9dbe623114960dab489cca029fe0d1f036964c7748b27a96e1c2eb7d63d33d3d285f
-  data.tar.gz: 0427ed5bc1601858080cb1f057547cb4143cc51d32cbd7189fa4fc8546260045c11603204814e28656b26a97f00e286634b24f8b536c879d14e5f8dd44f8313c
+  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
@@ -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/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.4.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.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Stan Carver II