printavo-ruby 0.18.1 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2291442eb2c04c3ead1543773bcd188723de181093941cdc8519681b5b43e4b
-  data.tar.gz: 00274b8c115044888d4099465521acf974c0356261130eb6aacaa21f1d4aa5ce
+  metadata.gz: 48b453128217df2c6051caddc404b2623acf14aa49f1c7ef9aab789359245ec4
+  data.tar.gz: e39850f5537b1a5362f01ac910e1501d3bf473470dca5cfce5465b3352fbb7ee
 SHA512:
-  metadata.gz: fdd286fc6a29e0313aed8f7ebbea302f7737e17f44144a524396eadcde292d70d9a87b610d22ec3bd692a9a93572d7bb844c861c71dd1e87435c59a3cd465ade
-  data.tar.gz: 29719257b52dfd20f4f9da862e3ccca5df84f8dc64dfb564421a73cbe1b88e46e2a5b36891066ed1e43607e30a3e9a9c6ceecdb3697ac85ce53c2eb1a17b9afa
+  metadata.gz: 4a5effd363bbefcaff3ac665457d3b099f5f338911583e29885a4be4c2308ea912f753157a13d088b8b3e91105ea9b697fd78e41d5a02ab55fecebb4174d4f2e
+  data.tar.gz: 80760572b15654acd78928d16ef4e639961dae9ce4a95f9d812660a8612d0aeaf3205f5ac51f3bf6a4648e2bea00b37939afa077354bbf6baca540fbb4a18a86

data/README.md

@@ -22,6 +22,7 @@ A framework-agnostic Ruby SDK for the [Printavo](https://www.printavo.com) Graph
 - Full [Printavo v2 GraphQL API](https://www.printavo.com/docs/api/v2) support
 - Resource-oriented interface: `client.customers.all`, `client.orders.find(id)`
 - Raw GraphQL access: `client.graphql.query("{ ... }")`
+- Sanitized GraphQL response envelopes that preserve partial data and errors
 - Rich domain models: `order.status`, `order.status?(:in_production)`, `order.customer`
 - Rack-compatible webhook signature verification
 - Multi-client support — no globals required
@@ -88,6 +89,44 @@ puts customer.full_name   # => "Jane Smith"
 puts customer.company     # => "Acme Shirts"
 ```
 
+### Bounded Contact Pages
+
+```ruby
+page = client.contacts.page(
+  first: 50,
+  after: previous_cursor,
+  primary_only: true,
+  sort_on: Printavo::Enums::ContactSortField::CONTACT_NAME
+)
+
+page.records.each { |contact| puts contact.full_name }
+next_cursor = page.end_cursor if page.has_next_page
+
+# Partial GraphQL responses preserve successful records and sanitized errors.
+warn(page.errors.inspect) unless page.success?
+```
+
+`contacts.page` performs exactly one request and caps `first` at 100. It never
+follows the next cursor automatically.
+
+### GraphQL Response Envelopes
+
+```ruby
+envelope = client.graphql.query_envelope(
+  "query Contact($id: ID!) { contact(id: $id) { id email } }",
+  variables: { id: "123" }
+)
+
+envelope.data
+envelope.errors
+envelope.metadata
+envelope.partial?
+```
+
+`query` and `mutate` retain their strict behavior and raise `Printavo::ApiError`
+when GraphQL errors are present. Envelope methods preserve partial data without
+retaining credentials, raw HTTP objects, or provider response bodies.
+
 ### Orders
 
 ```ruby

data/docs/CHANGELOG.md

@@ -6,6 +6,60 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.19.0] - 2026-07-29
+
+### Added
+- `Contacts#page` for one bounded contacts request with cursor, primary-contact,
+  query, and documented sort controls
+- `GraphqlClient#query_envelope` and `#mutate_envelope` for deeply immutable
+  partial data, sanitized errors, and allowlisted response metadata
+- `Page#errors`, `#metadata`, `#success?`, and `#partial?`
+
+### Security
+- Provider transport failures now raise an identifier-only `TransportError`
+  without retaining a Faraday exception cause or response body
+- GraphQL error details retain only allowlisted fields and redact configured
+  email and token values
+
+## [0.18.1] - 2026-04-05
+
+### Added
+- `examples/diagramming/workflow_diagram.rb` — generates Printavo status
+  workflows as ASCII, Mermaid, DOT, or SVG
+- `examples/reporting/sales_report.rb` — summarizes invoice revenue for common
+  and custom reporting periods
+- `examples/reporting/sales_tax_report.rb` — provides invoice-level sales-tax
+  estimates and fee-level taxable detail
+- `examples/reporting/customers_export.rb` — exports customer data to CSV,
+  XLSX, XLS, vCard, HubSpot, Salesforce, Mailchimp, Constant Contact, Beehiiv,
+  Brevo, and ActiveCampaign formats
+- `examples/reporting/outstanding_tasks.rb` — reports outstanding tasks by due
+  period and assignee and generates an HTML calendar
+- `docs/VISUALIZATION.md` — documents the standalone workflow-diagram example,
+  supported formats, dependencies, and usage
+
+### Changed
+- GitHub Actions now use Node.js 24-compatible `actions/checkout@v4.3.1` and
+  `actions/upload-artifact@v4.6.2`
+
+## [0.18.0] - 2026-04-05
+
+### Added
+- Optional `cache:` and `default_ttl:` arguments on `Printavo::Client`; the
+  cache accepts any store implementing the `Rails.cache`-compatible
+  `fetch(key, expires_in:) { }` and `delete(key)` interface
+- `Printavo::MemoryStore` — a thread-safe, TTL-aware in-memory cache for
+  applications that do not use Rails or an external cache
+- Automatic GraphQL query caching with stable SHA-256 keys derived from the
+  normalized query document and variables
+- Cache adapter and memory-store coverage in the client and GraphQL client
+  specs
+
+### Changed
+- GraphQL mutations always bypass the cache
+- `docs/CACHING.md` now documents `Rails.cache`, `Printavo::MemoryStore`,
+  custom stores, cache-key generation, and mutation behavior
+
 ## [0.17.0] - 2026-04-01
 
 ### Added

data/lib/printavo/client.rb

@@ -47,7 +47,12 @@ module Printavo
         max_retries: max_retries,
         retry_on_rate_limit: retry_on_rate_limit
       ).build
-      @graphql = GraphqlClient.new(connection, cache: cache, default_ttl: default_ttl)
+      @graphql = GraphqlClient.new(
+        connection,
+        cache: cache,
+        default_ttl: default_ttl,
+        sensitive_values: [email, token]
+      )
     end
 
     def account

data/lib/printavo/errors.rb

@@ -10,6 +10,8 @@ module Printavo
 
   class NotFoundError < Error; end
 
+  class TransportError < Error; end
+
   class ApiError < Error
     attr_reader :response
 

data/lib/printavo/graphql/contacts/all.graphql

@@ -0,0 +1,36 @@
+query Contacts(
+  $first: Int
+  $after: String
+  $primaryOnly: Boolean
+  $query: String
+  $sortOn: ContactSortField
+  $sortDescending: Boolean
+) {
+  contacts(
+    first: $first
+    after: $after
+    primaryOnly: $primaryOnly
+    query: $query
+    sortOn: $sortOn
+    sortDescending: $sortDescending
+  ) {
+    nodes {
+      id
+      firstName
+      lastName
+      fullName
+      email
+      phone
+      fax
+      createdAt
+      updatedAt
+      customer {
+        id
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}

data/lib/printavo/graphql_client.rb

@@ -6,15 +6,29 @@ require 'json'
 
 module Printavo
   class GraphqlClient
+    SAFE_ERROR_EXTENSION_KEYS = %w[classification code].freeze
+    SAFE_METADATA_HEADERS = %w[
+      retry-after
+      x-request-id
+      x-ratelimit-limit
+      x-ratelimit-remaining
+      x-ratelimit-reset
+    ].freeze
+
     # @param connection  [Faraday::Connection]
     # @param cache       [#fetch, #delete, nil] any cache store implementing
     #                    +fetch(key, expires_in:) { }+ and +delete(key)+,
     #                    e.g. +Rails.cache+, +Printavo::MemoryStore.new+, or +nil+
     # @param default_ttl [Integer] default TTL in seconds applied to cached queries (default: 300)
-    def initialize(connection, cache: nil, default_ttl: 300)
+    # @param sensitive_values [Array<String>] credentials to redact from provider messages
+    def initialize(connection, cache: nil, default_ttl: 300, sensitive_values: [])
       @connection  = connection
       @cache       = cache
       @default_ttl = default_ttl
+      @sensitive_values = sensitive_values.filter_map do |value|
+        string = value.to_s
+        string unless string.empty?
+      end.freeze
     end
 
     # Executes a GraphQL query and returns the parsed `data` hash.
@@ -61,6 +75,23 @@ module Printavo
       execute(mutation_string, variables: variables)
     end
 
+    # Executes a GraphQL query without discarding partial data when GraphQL
+    # errors are present. HTTP and transport failures still raise their
+    # identifier-only SDK exceptions.
+    #
+    # @return [Printavo::ResponseEnvelope]
+    def query_envelope(query_string, variables: {})
+      execute_envelope(query_string, variables: variables)
+    end
+
+    # Mutation equivalent of #query_envelope. Callers must decide whether a
+    # partial mutation response represents an uncertain write.
+    #
+    # @return [Printavo::ResponseEnvelope]
+    def mutate_envelope(mutation_string, variables: {})
+      execute_envelope(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`.
@@ -106,28 +137,106 @@ module Printavo
     end
 
     def execute(document, variables: {})
+      envelope = execute_envelope(document, variables: variables)
+      return envelope.data if envelope.success?
+
+      messages = envelope.errors.map { |error| error.fetch('message') }.join(', ')
+      raise ApiError.new(messages, response: { 'errors' => envelope.errors }.freeze)
+    end
+
+    def execute_envelope(document, variables: {})
       response = @connection.post('') do |req|
         req.body = JSON.generate(query: document, variables: variables)
       end
-      handle_response(response)
+      handle_envelope(response)
+    rescue Faraday::Error
+      raise TransportError, 'Printavo transport request failed', cause: nil
     end
 
-    def handle_response(response)
-      body = response.body
-
+    def handle_envelope(response)
       case response.status
       when 401 then raise AuthenticationError, 'Invalid credentials — check your email and token'
       when 429 then raise RateLimitError, 'Printavo rate limit exceeded (10 req/5 sec)'
       when 404 then raise NotFoundError, 'Resource not found'
       end
 
-      errors = body.is_a?(Hash) ? body['errors'] : nil
-      if errors&.any?
-        messages = errors.map { |e| e['message'] }.join(', ')
-        raise ApiError.new(messages, response: body)
+      body = response.body
+      return malformed_envelope(response) unless valid_envelope?(body)
+
+      ResponseEnvelope.new(
+        data: body['data'],
+        errors: sanitize_errors(body.fetch('errors', [])),
+        metadata: safe_metadata(response)
+      )
+    end
+
+    def valid_envelope?(body)
+      return false unless body.is_a?(Hash)
+      return false unless body.key?('data') || body.key?('errors')
+      return false unless body['data'].nil? || body['data'].is_a?(Hash)
+
+      errors = body.fetch('errors', [])
+      errors.is_a?(Array) && errors.all?(Hash)
+    end
+
+    def malformed_envelope(response)
+      ResponseEnvelope.new(
+        data: nil,
+        errors: [
+          {
+            'message' => 'Malformed GraphQL response',
+            'extensions' => { 'code' => 'MALFORMED_RESPONSE' }
+          }
+        ],
+        metadata: safe_metadata(response)
+      )
+    end
+
+    def sanitize_errors(errors)
+      errors.map do |error|
+        {
+          'message' => redact(error.fetch('message', 'GraphQL request failed').to_s)[0, 500],
+          'path' => sanitize_path(error['path']),
+          'locations' => sanitize_locations(error['locations']),
+          'extensions' => sanitize_extensions(error['extensions'])
+        }.compact
+      end
+    end
+
+    def sanitize_path(path)
+      return unless path.is_a?(Array)
+
+      path.select { |part| part.is_a?(String) || part.is_a?(Integer) }
+    end
+
+    def sanitize_locations(locations)
+      return unless locations.is_a?(Array)
+
+      locations.filter_map do |location|
+        next unless location.is_a?(Hash)
+
+        line = location['line']
+        column = location['column']
+        { 'line' => line, 'column' => column } if line.is_a?(Integer) && column.is_a?(Integer)
+      end
+    end
+
+    def sanitize_extensions(extensions)
+      return unless extensions.is_a?(Hash)
+
+      extensions.slice(*SAFE_ERROR_EXTENSION_KEYS).transform_values { |value| redact(value.to_s)[0, 100] }
+    end
+
+    def safe_metadata(response)
+      headers = response.headers.to_h.transform_keys(&:downcase)
+      SAFE_METADATA_HEADERS.each_with_object({}) do |header, metadata|
+        value = headers[header]
+        metadata[header] = redact(value.to_s)[0, 100] unless value.nil?
       end
+    end
 
-      body.is_a?(Hash) ? body['data'] : body
+    def redact(value)
+      @sensitive_values.reduce(value.dup) { |result, secret| result.gsub(secret, '[FILTERED]') }
     end
 
     # Resolves a dot-separated path against a nested hash.

data/lib/printavo/page.rb

@@ -14,9 +14,11 @@ module Printavo
   #   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
+  Page = Struct.new(:records, :has_next_page, :end_cursor, :errors, :metadata, keyword_init: true) do
     def to_a    = records
     def size    = records.size
     def empty?  = records.empty?
+    def success? = Array(errors).empty?
+    def partial? = records.any? && !success?
   end
 end

data/lib/printavo/resources/contacts.rb

@@ -4,11 +4,32 @@
 module Printavo
   module Resources
     class Contacts < Base
+      ALL_QUERY       = File.read(File.join(__dir__, '../graphql/contacts/all.graphql')).freeze
       FIND_QUERY      = File.read(File.join(__dir__, '../graphql/contacts/find.graphql')).freeze
       CREATE_MUTATION = File.read(File.join(__dir__, '../graphql/contacts/create.graphql')).freeze
       DELETE_MUTATION = File.read(File.join(__dir__, '../graphql/contacts/delete.graphql')).freeze
       UPDATE_MUTATION = File.read(File.join(__dir__, '../graphql/contacts/update.graphql')).freeze
 
+      MAX_PAGE_SIZE = 100
+      PAGE_FILTERS = %i[primary_only query sort_descending sort_on].freeze
+
+      def all(first: 25, after: nil, **filters)
+        page(first: first, after: after, **filters).records
+      end
+
+      # Fetches one bounded contact page while preserving sanitized partial
+      # GraphQL errors. This method never follows the next cursor.
+      #
+      # @return [Printavo::Page]
+      def page(first: 25, after: nil, **filters)
+        validate_page!(first: first, filters: filters)
+        envelope = @graphql.query_envelope(
+          ALL_QUERY,
+          variables: contact_variables(first: first, after: after, filters: filters)
+        )
+        build_page(envelope)
+      end
+
       # Finds a contact by ID.
       #
       # @param id [String, Integer]
@@ -57,6 +78,46 @@ module Printavo
         @graphql.mutate(DELETE_MUTATION, variables: { id: id.to_s })
         nil
       end
+
+      private
+
+      def validate_page!(first:, filters:)
+        unless first.is_a?(Integer) && first.between?(1, MAX_PAGE_SIZE)
+          raise ArgumentError, "first must be between 1 and #{MAX_PAGE_SIZE}"
+        end
+
+        unknown_filters = filters.keys - PAGE_FILTERS
+        raise ArgumentError, "unknown contact filters: #{unknown_filters.join(', ')}" if unknown_filters.any?
+
+        sort_on = filters[:sort_on]
+        return if sort_on.nil? || Enums::ContactSortField::ALL.include?(sort_on)
+
+        raise ArgumentError, 'sort_on must be a Printavo::Enums::ContactSortField value'
+      end
+
+      def contact_variables(first:, after:, filters:)
+        {
+          first: first,
+          after: after,
+          primaryOnly: filters[:primary_only],
+          query: filters[:query],
+          sortOn: filters[:sort_on],
+          sortDescending: filters[:sort_descending]
+        }
+      end
+
+      def build_page(envelope)
+        connection = envelope.data&.fetch('contacts', nil) || {}
+        records = Array(connection['nodes']).map { |attrs| Printavo::Contact.new(attrs) }
+        page_info = connection.fetch('pageInfo', {})
+        Printavo::Page.new(
+          records: records,
+          has_next_page: page_info.fetch('hasNextPage', false),
+          end_cursor: page_info['endCursor'],
+          errors: envelope.errors,
+          metadata: envelope.metadata
+        )
+      end
     end
   end
 end

data/lib/printavo/response_envelope.rb

@@ -0,0 +1,44 @@
+# lib/printavo/response_envelope.rb
+# frozen_string_literal: true
+
+module Printavo
+  class ResponseEnvelope
+    attr_reader :data, :errors, :metadata
+
+    def initialize(data:, errors: [], metadata: {})
+      @data = immutable_copy(data)
+      @errors = immutable_copy(errors)
+      @metadata = immutable_copy(metadata)
+      freeze
+    end
+
+    def success?
+      errors.empty?
+    end
+
+    def partial?
+      !data.nil? && errors.any?
+    end
+
+    def to_h
+      { 'data' => data, 'errors' => errors, 'metadata' => metadata }.freeze
+    end
+
+    private
+
+    def immutable_copy(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, item), copy|
+          copy[key.to_s.freeze] = immutable_copy(item)
+        end.freeze
+      when Array
+        value.map { |item| immutable_copy(item) }.freeze
+      when String
+        value.dup.freeze
+      else
+        value
+      end
+    end
+  end
+end

data/lib/printavo/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Printavo
-  VERSION = '0.18.1'
+  VERSION = '0.19.0'
 end

data/lib/printavo.rb

@@ -10,6 +10,7 @@ require_relative 'printavo/config'
 require_relative 'printavo/connection'
 require_relative 'printavo/enums'
 require_relative 'printavo/errors'
+require_relative 'printavo/response_envelope'
 require_relative 'printavo/graphql_client'
 require_relative 'printavo/memory_store'
 require_relative 'printavo/page'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: printavo-ruby
 version: !ruby/object:Gem::Version
-  version: 0.18.1
+  version: 0.19.0
 platform: ruby
 authors:
 - Stan Carver II
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-05 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -320,6 +320,7 @@ files:
 - lib/printavo/graphql/approval_requests/unapprove.graphql
 - lib/printavo/graphql/categories/all.graphql
 - lib/printavo/graphql/categories/find.graphql
+- lib/printavo/graphql/contacts/all.graphql
 - lib/printavo/graphql/contacts/create.graphql
 - lib/printavo/graphql/contacts/delete.graphql
 - lib/printavo/graphql/contacts/find.graphql
@@ -544,6 +545,7 @@ files:
 - lib/printavo/resources/types_of_work.rb
 - lib/printavo/resources/users.rb
 - lib/printavo/resources/vendors.rb
+- lib/printavo/response_envelope.rb
 - lib/printavo/version.rb
 - lib/printavo/webhooks.rb
 homepage: https://github.com/scarver2/printavo-ruby