printavo-ruby 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48b453128217df2c6051caddc404b2623acf14aa49f1c7ef9aab789359245ec4
-  data.tar.gz: e39850f5537b1a5362f01ac910e1501d3bf473470dca5cfce5465b3352fbb7ee
+  metadata.gz: 6ad593920d96da45a59747ebfaab7fce5d5a1b411e0f6afa781bca1fefcca158
+  data.tar.gz: 6eb415c85c7566986565daddcd6ebd5065d87af95680599ba0b4717892de20e0
 SHA512:
-  metadata.gz: 4a5effd363bbefcaff3ac665457d3b099f5f338911583e29885a4be4c2308ea912f753157a13d088b8b3e91105ea9b697fd78e41d5a02ab55fecebb4174d4f2e
-  data.tar.gz: 80760572b15654acd78928d16ef4e639961dae9ce4a95f9d812660a8612d0aeaf3205f5ac51f3bf6a4648e2bea00b37939afa077354bbf6baca540fbb4a18a86
+  metadata.gz: d95dc0294fe872e6db56d48ab7309c668f24edc5caadf22a5f1333407cac2f31d6845fef845c0cd126ba05cc5033e0ea776ec74768da609fd6878fb1d65fe8d3
+  data.tar.gz: c6b9e54ecd0491b4ffafcf9761473a967d180e1a0bac454ea22c511f1227ba5ec6198361e28303d7db58a4b2cb6fb5f24522820b95ba6add7ada251fe240e235

data/README.md

@@ -109,6 +109,22 @@ 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.
 
+`page.response_payload` contains the exact frozen binary HTTP response body
+captured before JSON parsing. It is intentionally omitted from ordinary
+inspection and serialization because provider responses may contain private
+customer data. Persist or log it only through an explicit encrypted evidence
+boundary.
+
+Captured contact responses can be replayed through the same SDK parser without
+provider access:
+
+```ruby
+replayed_page = client.contacts.page_from_response_payload(
+  page.response_payload,
+  metadata: page.metadata
+)
+```
+
 ### GraphQL Response Envelopes
 
 ```ruby

data/docs/CHANGELOG.md

@@ -6,6 +6,21 @@ 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.20.0] - 2026-08-17
+
+### Added
+- `ResponseEnvelope#response_payload` exposes the exact immutable binary HTTP
+  response bytes captured before JSON parsing.
+- `Page#response_payload` carries the exact payload for bounded contact pages.
+- `GraphqlClient#envelope_from_response_payload` and
+  `Contacts#page_from_response_payload` rehydrate captured responses through
+  the same validation, sanitization, and page-building path without network I/O.
+
+### Security
+- Raw response payloads remain excluded from `ResponseEnvelope#to_h` and from
+  ordinary `ResponseEnvelope` and `Page` inspection. They may contain private
+  provider data and must be handled through an explicit evidence boundary.
+
 ## [0.19.0] - 2026-07-29
 
 ### Added

data/lib/printavo/connection.rb

@@ -29,7 +29,7 @@ module Printavo
         f.headers['email']        = @email
         f.headers['token']        = @token
         f.request :retry, **retry_options
-        f.response :json
+        f.response :json, preserve_raw: true
         f.options.timeout      = @timeout
         f.options.open_timeout = @timeout
         f.adapter Faraday.default_adapter

data/lib/printavo/graphql_client.rb

@@ -92,6 +92,23 @@ module Printavo
       execute_envelope(mutation_string, variables: variables)
     end
 
+    # Rehydrates one captured GraphQL response without performing network I/O.
+    # The exact payload remains attached to the immutable envelope while parsed
+    # data and errors follow the same validation and sanitization as live calls.
+    def envelope_from_response_payload(response_payload, metadata: {})
+      raise ArgumentError, 'response_payload must be a String' unless response_payload.is_a?(String)
+
+      payload = response_payload.b.dup.freeze
+      body = JSON.parse(payload)
+      build_envelope(
+        body: body,
+        metadata: safe_metadata_hash(metadata),
+        response_payload: payload
+      )
+    rescue JSON::ParserError
+      malformed_envelope(metadata: safe_metadata_hash(metadata), response_payload: payload)
+    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`.
@@ -145,10 +162,10 @@ module Printavo
     end
 
     def execute_envelope(document, variables: {})
-      response = @connection.post('') do |req|
-        req.body = JSON.generate(query: document, variables: variables)
-      end
+      response = @connection.post('') { |request| request.body = JSON.generate(query: document, variables: variables) }
       handle_envelope(response)
+    rescue Faraday::ParsingError => e
+      handle_envelope(e.response)
     rescue Faraday::Error
       raise TransportError, 'Printavo transport request failed', cause: nil
     end
@@ -160,26 +177,33 @@ module Printavo
       when 404 then raise NotFoundError, 'Resource not found'
       end
 
-      body = response.body
-      return malformed_envelope(response) unless valid_envelope?(body)
+      build_envelope(
+        body: response.body,
+        metadata: safe_metadata_hash(response.headers.to_h),
+        response_payload: raw_response_payload(response)
+      )
+    end
+
+    def build_envelope(body:, metadata:, response_payload:)
+      return malformed_envelope(metadata: metadata, response_payload: response_payload) unless valid_envelope?(body)
 
       ResponseEnvelope.new(
         data: body['data'],
         errors: sanitize_errors(body.fetch('errors', [])),
-        metadata: safe_metadata(response)
+        metadata: metadata,
+        response_payload: response_payload
       )
     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.is_a?(Hash) && (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)
+    def malformed_envelope(metadata:, response_payload:)
       ResponseEnvelope.new(
         data: nil,
         errors: [
@@ -188,10 +212,16 @@ module Printavo
             'extensions' => { 'code' => 'MALFORMED_RESPONSE' }
           }
         ],
-        metadata: safe_metadata(response)
+        metadata: metadata,
+        response_payload: response_payload
       )
     end
 
+    def raw_response_payload(response)
+      payload = response.env[:raw_body] || response.body
+      payload if payload.is_a?(String)
+    end
+
     def sanitize_errors(errors)
       errors.map do |error|
         {
@@ -227,8 +257,10 @@ module Printavo
       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)
+    def safe_metadata_hash(value)
+      raise ArgumentError, 'metadata must be a Hash' unless value.is_a?(Hash)
+
+      headers = value.transform_keys { |key| key.to_s.downcase }
       SAFE_METADATA_HEADERS.each_with_object({}) do |header, metadata|
         value = headers[header]
         metadata[header] = redact(value.to_s)[0, 100] unless value.nil?

data/lib/printavo/page.rb

@@ -14,11 +14,32 @@ 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, :errors, :metadata, keyword_init: true) do
+  Page = Struct.new(
+    :records,
+    :has_next_page,
+    :end_cursor,
+    :errors,
+    :metadata,
+    :response_payload,
+    keyword_init: true
+  ) do
+    def initialize(**attributes)
+      payload = attributes[:response_payload]
+      raise ArgumentError, 'response_payload must be a String' if payload && !payload.is_a?(String)
+
+      payload = payload.b.dup.freeze if payload
+      super(**attributes.merge(response_payload: payload))
+    end
+
     def to_a    = records
     def size    = records.size
     def empty?  = records.empty?
     def success? = Array(errors).empty?
     def partial? = records.any? && !success?
+
+    def inspect
+      "#<#{self.class} records=#{records.inspect} has_next_page=#{has_next_page.inspect} " \
+        "end_cursor=#{end_cursor.inspect} errors=#{errors.inspect} metadata=#{metadata.inspect}>"
+    end
   end
 end

data/lib/printavo/resources/contacts.rb

@@ -30,6 +30,14 @@ module Printavo
         build_page(envelope)
       end
 
+      # Rebuilds a captured contacts page through the SDK parser without
+      # performing provider network I/O.
+      def page_from_response_payload(response_payload, metadata: {})
+        build_page(
+          @graphql.envelope_from_response_payload(response_payload, metadata: metadata)
+        )
+      end
+
       # Finds a contact by ID.
       #
       # @param id [String, Integer]
@@ -115,7 +123,8 @@ module Printavo
           has_next_page: page_info.fetch('hasNextPage', false),
           end_cursor: page_info['endCursor'],
           errors: envelope.errors,
-          metadata: envelope.metadata
+          metadata: envelope.metadata,
+          response_payload: envelope.response_payload
         )
       end
     end

data/lib/printavo/response_envelope.rb

@@ -3,12 +3,13 @@
 
 module Printavo
   class ResponseEnvelope
-    attr_reader :data, :errors, :metadata
+    attr_reader :data, :errors, :metadata, :response_payload
 
-    def initialize(data:, errors: [], metadata: {})
+    def initialize(data:, errors: [], metadata: {}, response_payload: nil)
       @data = immutable_copy(data)
       @errors = immutable_copy(errors)
       @metadata = immutable_copy(metadata)
+      @response_payload = immutable_payload(response_payload)
       freeze
     end
 
@@ -24,8 +25,19 @@ module Printavo
       { 'data' => data, 'errors' => errors, 'metadata' => metadata }.freeze
     end
 
+    def inspect
+      "#<#{self.class} data=#{data.inspect} errors=#{errors.inspect} metadata=#{metadata.inspect}>"
+    end
+
     private
 
+    def immutable_payload(value)
+      return if value.nil?
+      raise ArgumentError, 'response_payload must be a String' unless value.is_a?(String)
+
+      value.b.dup.freeze
+    end
+
     def immutable_copy(value)
       case value
       when Hash

data/lib/printavo/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: printavo-ruby
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Stan Carver II
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-30 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.14'
 - !ruby/object:Gem::Dependency
   name: faraday-retry
   requirement: !ruby/object:Gem::Requirement