printavo-ruby 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f47615b00a6d63bc35e5d5cc74e5e8d591fe38218eadd0bb76e11798626f9f42
-  data.tar.gz: aa6d86cb12b1ea7617c8d97093993252fc30f1401fef8893263ed2ba4f277a48
+  metadata.gz: a7786dadca364f38068636a9a6e30efac78ac79107c8dfb4ade22b39db5f0bc1
+  data.tar.gz: f0464978791f12c8e3f5d37d2de09ecfc4b97e57aca4999beda995b68957d2e1
 SHA512:
-  metadata.gz: '08fa3eb45c8ddef4ff5962c9bd59d01c14048d2c68fefb1b3e6ee526b6e4317b225958b5ed8865ba45fb42b35ef14d1c8f235a81b90a3c11e1e4dd661e2c1aa4'
-  data.tar.gz: 93ef9341891c36ab6ffa9fd61a9790b16662072a7ecb4bf733d6aa0f5cd9fe99ee75c77a47be7a023909b7468fb70abec3a8d5b076925a732c3cd8c6389ec1b6
+  metadata.gz: a6aae8c15d5f5c348d8e717c09eaf85092a9421d473541ac1ef3c38042534ed1aa14c6e0c5283d6878325cdf32a7325fed52e980913e7b15e8c443ed64a695bb
+  data.tar.gz: bac95ec4243aa408c495f88d7c4841a308f7c49f509d8b7a0f3a4a161cb9db30418d2ba2c79be67f353c89b68d24cec6f70c1487b64496ea5ef74489fe44acc8

data/README.md

@@ -116,6 +116,57 @@ job = client.jobs.find("77")
 puts job.taxable?   # => true
 ```
 
+### Pagination
+
+All list resources support `each_page` and `all_pages` in addition to `all`.
+
+```ruby
+# Iterate page by page (cursor-based, memory-efficient)
+client.customers.each_page(first: 50) do |records|
+  records.each { |c| puts c.full_name }
+end
+
+# Collect every record across all pages into one array
+all_orders = client.orders.all_pages
+
+# Jobs require order_id
+client.jobs.each_page(order_id: "99") do |records|
+  records.each { |j| puts j.name }
+end
+all_jobs = client.jobs.all_pages(order_id: "99")
+```
+
+### Statuses
+
+```ruby
+# List all statuses
+statuses = client.statuses.all
+statuses.each { |s| puts "#{s.name} (#{s.color})" }
+
+# Build a registry for O(1) lookup by symbol key
+registry = client.statuses.registry
+registry[:in_production]          # => <Printavo::Status>
+registry[:in_production].color    # => "#ff6600"
+
+# Pair with an order's status_key
+order = client.orders.find("99")
+status = registry[order.status_key]
+puts "#{order.status} — #{status.color}"
+```
+
+### Inquiries
+
+```ruby
+# List inquiries (quotes / leads)
+inquiries = client.inquiries.all
+inquiries.each { |i| puts "#{i.nickname}: #{i.status}" }
+
+# Find a specific inquiry
+inquiry = client.inquiries.find("55")
+puts inquiry.status?(:new_inquiry)    # => true
+puts inquiry.customer.full_name       # => "Jane Smith"
+```
+
 ### Raw GraphQL
 
 For queries not yet wrapped by a resource, use the raw GraphQL client directly:
@@ -203,15 +254,15 @@ end
 
 | Version | Milestone |
 |---|---|
-| 0.1.0 | Auth + Customers + Orders + Jobs |
-| 0.2.0 | Status registry + Analytics/Reporting |
-| 0.3.0 | Webhooks (Rack-compatible) |
+| 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.6.0 | Community burn-in / API stabilization |
-| 0.7.0 | Pagination abstraction helpers |
-| 0.8.0 | Retry/backoff + rate limit awareness |
-| 0.9.0 | Community feedback + API freeze |
+| 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 |
 | 1.0.0 | Stable public SDK |
 
 **Rules**: `PATCH` = bug fix · `MINOR` = new backward-compatible feature · `MAJOR` = breaking change
@@ -241,7 +292,7 @@ bundle exec guard
 PRINTAVO_EMAIL=you@example.com PRINTAVO_TOKEN=your_token bin/console
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for full contribution guidelines.
+See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for full contribution guidelines.
 
 ## Colophon
 

data/docs/CACHING.md

@@ -0,0 +1,233 @@
+<!-- docs/CACHING.md -->
+# Caching Strategies for printavo-ruby
+
+The Printavo API enforces a **rate limit of 10 requests per 5 seconds** per account.
+For applications that read Printavo data frequently (dashboards, reporting tools,
+CRM syncs), caching is essential to stay within this limit and reduce latency.
+
+This guide covers practical caching patterns, from zero-dependency Ruby to
+Redis and Rails.cache, along with recommended TTLs for each resource type.
+
+---
+
+## Why Cache Printavo Responses?
+
+| Factor | Detail |
+|---|---|
+| Rate limit | 10 req / 5 sec per account |
+| Data volatility | Customers and statuses rarely change; orders change moderately |
+| Use case | Dashboards, CRM syncs, and reporting hammer read endpoints repeatedly |
+| Cost | Fewer API calls = faster responses + less risk of throttling |
+
+---
+
+## Strategy 1: In-Memory Caching (Zero Dependencies)
+
+Best for: **scripts, background jobs, single-request data batches**
+
+A plain Ruby hash is enough when you only need to deduplicate calls
+within a single process run:
+
+```ruby
+customer_cache = {}
+
+def fetch_customer(client, id, cache)
+  cache[id] ||= client.customers.find(id)
+end
+
+order = client.orders.find("99")
+customer = fetch_customer(client, order.customer.id, customer_cache)
+```
+
+> Note: In-memory caches are cleared on process restart and are not shared
+> across processes or threads (without synchronization).
+
+---
+
+## Strategy 2: Status Registry Caching
+
+Best for: **status-heavy workflows**
+
+Printavo statuses are user-defined and rarely change. Cache them once at
+startup to avoid repeated API calls when checking `order.status?`:
+
+```ruby
+# Fetch all statuses once and freeze them
+raw = client.graphql.query(<<~GQL)
+  {
+    statuses {
+      nodes { id name }
+    }
+  }
+GQL
+
+STATUS_REGISTRY = raw["statuses"]["nodes"].freeze
+# => [{"id"=>"1", "name"=>"Quote"}, {"id"=>"2", "name"=>"In Production"}, ...]
+```
+
+This pairs well with `Printavo::Order#status_key` for symbol-based lookups.
+
+---
+
+## Strategy 3: Rails.cache Integration
+
+Best for: **Rails applications** (recommended default)
+
+Wrap any Printavo call in `Rails.cache.fetch` to use whatever cache store
+your app already has configured (Redis, Memcache, memory, etc.):
+
+```ruby
+# config/initializers/printavo.rb
+PRINTAVO = Printavo::Client.new(
+  email: ENV["PRINTAVO_EMAIL"],
+  token: ENV["PRINTAVO_TOKEN"]
+)
+```
+
+```ruby
+# In a service, controller, or job:
+def customers
+  Rails.cache.fetch("printavo:customers", expires_in: 10.minutes) do
+    PRINTAVO.customers.all
+  end
+end
+
+def order(id)
+  Rails.cache.fetch("printavo:order:#{id}", expires_in: 2.minutes) do
+    PRINTAVO.orders.find(id)
+  end
+end
+```
+
+> Use namespaced cache keys (`printavo:resource:id`) to make invalidation
+> easier and to avoid collisions with other app cache entries.
+
+---
+
+## Strategy 4: Redis (Framework-Agnostic)
+
+Best for: **non-Rails Ruby applications** that need a shared, persistent cache
+
+```ruby
+require "redis"
+require "json"
+
+REDIS = Redis.new(url: ENV.fetch("REDIS_URL", "redis://localhost:6379"))
+PRINTAVO_CLIENT = Printavo::Client.new(
+  email: ENV["PRINTAVO_EMAIL"],
+  token: ENV["PRINTAVO_TOKEN"]
+)
+
+def cached_customer(id, ttl: 600)
+  key  = "printavo:customer:#{id}"
+  data = REDIS.get(key)
+
+  if data
+    Printavo::Customer.new(JSON.parse(data))
+  else
+    customer = PRINTAVO_CLIENT.customers.find(id)
+    REDIS.setex(key, ttl, JSON.generate(customer.to_h))
+    customer
+  end
+end
+```
+
+---
+
+## Strategy 5: Webhook-Driven Cache Invalidation
+
+Best for: **keeping cache fresh without polling**
+
+When Printavo sends a webhook event (order updated, customer changed),
+invalidate the specific cache entry immediately:
+
+```ruby
+# Rails controller
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def printavo
+    unless Printavo::Webhooks.verify(
+             request.headers["X-Printavo-Signature"],
+             request.raw_post,
+             ENV["PRINTAVO_WEBHOOK_SECRET"]
+           )
+      return head :unauthorized
+    end
+
+    event = JSON.parse(request.raw_post)
+    invalidate_cache(event)
+    head :ok
+  end
+
+  private
+
+  def invalidate_cache(event)
+    case event["type"]
+    when "order.updated", "order.created"
+      Rails.cache.delete("printavo:order:#{event.dig("data", "id")}")
+    when "customer.updated"
+      Rails.cache.delete("printavo:customer:#{event.dig("data", "id")}")
+      Rails.cache.delete("printavo:customers")
+    end
+  end
+end
+```
+
+This pattern gives you **real-time accuracy** with **minimal API calls**.
+
+---
+
+## Recommended TTLs
+
+| Resource | Suggested TTL | Rationale |
+|---|---|---|
+| Customers (list) | 10 minutes | Changes infrequently |
+| Customer (single) | 10 minutes | Same |
+| Orders (list) | 2 minutes | Status changes often during production |
+| Order (single) | 2 minutes | Same |
+| Statuses/enums | 1 hour | Rarely changed by shop admins |
+| Analytics/reports | 15 minutes | Acceptable staleness for reporting |
+
+Adjust these TTLs based on your shop's actual order velocity and
+how frequently staff update records.
+
+---
+
+## What NOT to Cache
+
+| Item | Reason |
+|---|---|
+| API credentials | Managed by Printavo; don't duplicate |
+| Full paginated collections | Cache individual pages by cursor key instead |
+| Results immediately after a mutation | Always re-fetch after writes |
+| Webhook payloads | Process once and discard |
+
+---
+
+## Future: Built-In Cache Adapter
+
+A future version of `printavo-ruby` may support an optional cache adapter
+passed directly to the client:
+
+```ruby
+# Possible future API — not implemented in v0.x
+client = Printavo::Client.new(
+  email: ENV["PRINTAVO_EMAIL"],
+  token: ENV["PRINTAVO_TOKEN"],
+  cache: Rails.cache,           # any object responding to fetch/delete
+  default_ttl: 300
+)
+
+# Would cache automatically:
+client.customers.all   # cached for 300s by default
+client.orders.find(1)  # cached per-id
+```
+
+Track this feature in [FUTURE.md](../FUTURE.md).
+
+---
+
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/CHANGELOG.md

@@ -0,0 +1,63 @@
+<!-- docs/CHANGELOG.md -->
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-03-29
+
+### Added
+- `Printavo::Page` — value object wrapping `records`, `has_next_page`, `end_cursor` with `to_a`, `size`, `empty?`
+- `Printavo::Resources::Base#each_page` — yields each page of records as an Array, following cursors automatically
+- `Printavo::Resources::Base#all_pages` — returns all records across all pages as a flat Array
+- All resources (`Customers`, `Orders`, `Jobs`, `Statuses`, `Inquiries`) implement `fetch_page` and support `each_page`/`all_pages`
+- `Jobs#each_page(order_id:)` and `Jobs#all_pages(order_id:)` — `order_id` forwarded via `**kwargs`
+- `bin/lint` — multi-Ruby RuboCop runner mirroring `bin/spec` (reads versions from `.mise.toml`)
+- Roadmap: moved Pagination from 0.8.0 to 0.3.0; Webhooks slot repurposed
+
+### Changed
+- All resource `all` methods refactored to delegate to `fetch_page` (backward compatible — still returns `Array`)
+
+## [0.2.0] - 2026-03-29
+
+### Added
+- `Printavo::Status` — domain model with `id`, `name`, `color`, `key` (snake\_case symbol)
+- `Printavo::Resources::Statuses` — `all`, `find`, and `registry` (O(1) Hash lookup by symbol key)
+- `Printavo::Inquiry` — domain model mirroring `Order` with status predicate helpers
+- `Printavo::Resources::Inquiries` — `all` and `find` for Printavo quote/inquiry records
+- `Printavo::Order#status_id` and `#status_color` — expose full status sub-object fields
+- `client.statuses` and `client.inquiries` — new entry points on `Printavo::Client`
+- Orders GraphQL query now fetches `status { id name color }` for full status data
+- Moved `CHANGELOG.md`, `CONTRIBUTING.md`, `FUTURE.md` to `docs/` for cleaner repo root
+
+### Changed
+- Gemspec `changelog_uri` updated to `docs/CHANGELOG.md`
+- Gemspec `spec.files` updated to include `docs/**/*.md`
+
+## [0.1.0] - 2026-03-29
+
+### Added
+- `Printavo::Client` — instance-based, multi-client capable entry point
+- `Printavo::Resources::Customers` — `all` and `find` via GraphQL
+- `Printavo::Resources::Orders` — `all` and `find` with status + customer association
+- `Printavo::Resources::Jobs` — `all` (by order) and `find` line item queries
+- `Printavo::Customer`, `Printavo::Order`, `Printavo::Job` — rich domain models
+- `Printavo::Order#status?` — dynamic status predicate (handles user-defined statuses)
+- `Printavo::GraphqlClient` — raw GraphQL query/mutation interface
+- `Printavo::Webhooks.verify` — Rack-compatible HMAC-SHA256 signature verification
+- Error hierarchy: `AuthenticationError`, `RateLimitError`, `NotFoundError`, `ApiError`
+- Faraday connection with retry middleware (max 2 retries; 429/5xx)
+- RSpec test suite — 62 examples, 100% line coverage with VCR + WebMock + Faker sanitization
+- Coveralls coverage badge (LCOV via `simplecov-lcov`)
+- Guard + RuboCop DX setup with `bin/spec` multi-Ruby local runner
+- GitHub Actions CI: Ruby 3.3 (primary) + Ruby 4.0 (`continue-on-error`)
+- Automated RubyGems publish on `v*` tag via `release.yml`
+- `docs/CACHING.md` — nine caching strategy patterns for rate-limit-aware consumers
+
+---
+
+— Stan Carver II / Made in Texas 🤠 / https://stancarver.com

data/docs/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+<!-- docs/CONTRIBUTING.md -->
+# Contributing to printavo-ruby
+
+Thank you for your interest in contributing! This guide covers setup, workflow,
+and standards for working on `printavo-ruby`.
+
+## Setup
+
+```bash
+git clone https://github.com/scarver2/printavo-ruby.git
+cd printavo-ruby
+bundle install
+```
+
+## Running Tests
+
+```bash
+bundle exec rspec
+```
+
+Coverage is tracked via SimpleCov. The minimum threshold is **90%**.
+New code must include specs.
+
+## Guard DX (Recommended)
+
+Guard watches for file changes and re-runs specs and RuboCop automatically:
+
+```bash
+bundle exec guard
+```
+
+## Coding Standards
+
+This project uses [RuboCop](https://rubocop.org/) with the
+`rubocop-performance`, `rubocop-rake`, and `rubocop-rspec` extensions.
+
+```bash
+bundle exec rubocop
+bundle exec rubocop -a   # auto-correct safe offenses
+```
+
+## VCR Cassettes
+
+Integration tests use [VCR](https://github.com/vcr/vcr) to record and replay
+HTTP interactions. All cassettes **must be sanitized** before committing:
+
+- Real email addresses → `customer@example.com`
+- Real phone numbers → `555-867-5309`
+- Real customer names → `Acme Customer`
+- API credentials are filtered automatically by `spec/support/vcr.rb`
+
+Use the A1Web demo Printavo account when recording new cassettes — never
+record against production TER data.
+
+## Pull Request Guidelines
+
+- Branch from `master`
+- One feature / bug fix per PR
+- All CI checks must pass (RSpec + RuboCop across Ruby 3.1–4.0)
+- Write specs for any new code
+- Update `docs/CHANGELOG.md` with a summary of changes
+
+## Version Bump Rules
+
+Versions follow [Semantic Versioning](https://semver.org/):
+
+| Change type | Version part |
+|---|---|
+| Bug fix | PATCH (0.1.x) |
+| New backward-compatible feature | MINOR (0.x.0) |
+| Breaking API change | MAJOR (x.0.0) |
+
+Bump `lib/printavo/version.rb`, update `docs/CHANGELOG.md`, then:
+
+```bash
+git commit -am "Release vX.Y.Z"
+git tag vX.Y.Z
+git push origin master --tags
+```
+
+GitHub Actions will build and push to RubyGems automatically on tag push.
+
+---
+
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/FUTURE.md

@@ -0,0 +1,116 @@
+<!-- docs/FUTURE.md -->
+# Future Roadmap
+
+Ideas and planned features for `printavo-ruby` that are out of scope for the
+initial `0.x` releases. Contributions and discussions welcome!
+
+## Planned Features
+
+### CLI (Thor-based)
+
+A `printavo` command-line tool built with [Thor](https://github.com/rails/thor):
+
+```bash
+printavo customers
+printavo orders
+printavo orders find 12345
+printavo analytics revenue
+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:
+
+```ruby
+client = Printavo::Client.new(
+  email: ENV["PRINTAVO_EMAIL"],
+  token: ENV["PRINTAVO_TOKEN"],
+  max_retries: 3,
+  retry_on_rate_limit: true
+)
+```
+
+Planned version: `0.9.0`
+
+### Analytics / Reporting Expansion
+
+Richer wrappers for Printavo's analytics queries (revenue, job counts,
+customer activity, turnaround times).
+
+Planned version: `0.6.0`
+
+### Mutations (Create / Update)
+
+Support for creating and updating resources:
+
+```ruby
+client.customers.create(first_name: "Jane", last_name: "Smith", email: "jane@example.com")
+client.orders.update("99", nickname: "Rush Job")
+```
+
+Planned version: `0.5.0`
+
+### Built-In Cache Adapter
+
+Optional cache layer that plugs into any cache store:
+
+```ruby
+client = Printavo::Client.new(
+  email: ENV["PRINTAVO_EMAIL"],
+  token: ENV["PRINTAVO_TOKEN"],
+  cache: Rails.cache  # or a Redis client, etc.
+)
+```
+
+See [docs/CACHING.md](docs/CACHING.md) for current caching recommendations.
+
+## Visualization
+
+### Workflow Diagram Generation (SVG/PNG)
+
+Generate a visual map of a shop's Printavo status workflow:
+
+```ruby
+client.workflow.diagram(format: :svg)
+# => Outputs an SVG flowchart: Quote → Approved → In Production → Completed
+```
+
+Implementation options:
+- [ruby-graphviz](https://github.com/glejeune/Ruby-Graphviz) — DOT → SVG/PNG
+- Pure Ruby → Mermaid output (copy-paste into docs or GitHub markdown)
+
+## Multi-Language SDK Family
+
+`printavo-ruby` is the first gem in a planned multi-language SDK family:
+
+| Repo | Language | Status |
+|---|---|---|
+| `printavo-ruby` | Ruby | Active |
+| `printavo-python` | Python | Planned |
+| `printavo-swift` | Swift | Planned |
+| `printavo-zig` | Zig | Planned |
+| `printavo-odin` | Odin | Planned |
+
+---
+
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/lib/printavo/client.rb

@@ -27,6 +27,10 @@ module Printavo
       Resources::Customers.new(@graphql)
     end
 
+    def statuses
+      Resources::Statuses.new(@graphql)
+    end
+
     def orders
       Resources::Orders.new(@graphql)
     end
@@ -34,5 +38,9 @@ module Printavo
     def jobs
       Resources::Jobs.new(@graphql)
     end
+
+    def inquiries
+      Resources::Inquiries.new(@graphql)
+    end
   end
 end

data/lib/printavo/models/inquiry.rb

@@ -0,0 +1,27 @@
+# lib/printavo/models/inquiry.rb
+module Printavo
+  class Inquiry < Models::Base
+    def id          = self['id']
+    def nickname    = self['nickname']
+    def total_price = self['totalPrice']
+
+    def status
+      dig('status', 'name')
+    end
+
+    def status_key
+      return nil if status.nil?
+
+      status.downcase.gsub(/\s+/, '_').to_sym
+    end
+
+    def status?(key)
+      status_key == key.to_sym
+    end
+
+    def customer
+      attrs = self['customer']
+      Customer.new(attrs) if attrs
+    end
+  end
+end

data/lib/printavo/models/order.rb

@@ -9,6 +9,14 @@ module Printavo
       dig('status', 'name')
     end
 
+    def status_id
+      dig('status', 'id')
+    end
+
+    def status_color
+      dig('status', 'color')
+    end
+
     def status_key
       return nil if status.nil?
 

data/lib/printavo/models/status.rb

@@ -0,0 +1,16 @@
+# lib/printavo/models/status.rb
+module Printavo
+  class Status < Models::Base
+    def id    = self['id']
+    def name  = self['name']
+    def color = self['color']
+
+    # Returns a normalized symbol key matching Order#status_key.
+    # e.g. "In Production" => :in_production
+    def key
+      return nil if name.nil?
+
+      name.downcase.gsub(/\s+/, '_').to_sym
+    end
+  end
+end

data/lib/printavo/page.rb

@@ -0,0 +1,20 @@
+# lib/printavo/page.rb
+module Printavo
+  # Wraps a single page of API results with cursor metadata.
+  #
+  # @example Iterating pages manually
+  #   page = client.customers.fetch_page(first: 10)
+  #   page.records.each { |c| puts c.full_name }
+  #   puts page.has_next_page   # => true
+  #   puts page.end_cursor      # => "cursor_abc123"
+  #
+  # @example Using each_page
+  #   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
+    def to_a    = records
+    def size    = records.size
+    def empty?  = records.empty?
+  end
+end

data/lib/printavo/resources/base.rb

@@ -5,6 +5,47 @@ module Printavo
       def initialize(graphql)
         @graphql = graphql
       end
+
+      # Yields each page of records as an Array, following cursors automatically.
+      # Extra keyword arguments are forwarded to fetch_page (e.g. order_id: for Jobs).
+      #
+      # @param first [Integer] page size (default 25)
+      # @yieldparam records [Array] one page of domain model objects
+      #
+      # @example
+      #   client.customers.each_page(first: 50) do |records|
+      #     records.each { |c| puts c.full_name }
+      #   end
+      def each_page(first: 25, **kwargs)
+        after = nil
+        loop do
+          page = fetch_page(first: first, after: after, **kwargs)
+          yield(page.records)
+          break unless page.has_next_page
+
+          after = page.end_cursor
+        end
+      end
+
+      # Returns all records across all pages as a flat Array.
+      # Extra keyword arguments are forwarded to fetch_page (e.g. order_id: for Jobs).
+      #
+      # @param first [Integer] page size per request (default 25)
+      # @return [Array]
+      #
+      # @example
+      #   all_customers = client.customers.all_pages
+      #   all_jobs      = client.jobs.all_pages(order_id: "99")
+      def all_pages(first: 25, **kwargs)
+        [].tap { |all| each_page(first: first, **kwargs) { |records| all.concat(records) } }
+      end
+
+      private
+
+      # Subclasses must implement: returns a Printavo::Page.
+      def fetch_page(**)
+        raise NotImplementedError, "#{self.class}#fetch_page is not implemented"
+      end
     end
   end
 end

data/lib/printavo/resources/customers.rb

@@ -35,14 +35,26 @@ module Printavo
       GQL
 
       def all(first: 25, after: nil)
-        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
-        data['customers']['nodes'].map { |attrs| Printavo::Customer.new(attrs) }
+        fetch_page(first: first, after: after).records
       end
 
       def find(id)
         data = @graphql.query(FIND_QUERY, variables: { id: id.to_s })
         Printavo::Customer.new(data['customer'])
       end
+
+      private
+
+      def fetch_page(first: 25, after: nil, **)
+        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
+        nodes = data['customers']['nodes'].map { |attrs| Printavo::Customer.new(attrs) }
+        page_info = data['customers']['pageInfo']
+        Printavo::Page.new(
+          records: nodes,
+          has_next_page: page_info['hasNextPage'],
+          end_cursor: page_info['endCursor']
+        )
+      end
     end
   end
 end

data/lib/printavo/resources/inquiries.rb

@@ -0,0 +1,78 @@
+# lib/printavo/resources/inquiries.rb
+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
+
+      def all(first: 25, after: nil)
+        fetch_page(first: first, after: after).records
+      end
+
+      def find(id)
+        data = @graphql.query(FIND_QUERY, variables: { id: id.to_s })
+        Printavo::Inquiry.new(data['inquiry'])
+      end
+
+      private
+
+      def fetch_page(first: 25, after: nil, **)
+        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
+        nodes = data['inquiries']['nodes'].map { |attrs| Printavo::Inquiry.new(attrs) }
+        page_info = data['inquiries']['pageInfo']
+        Printavo::Page.new(
+          records: nodes,
+          has_next_page: page_info['hasNextPage'],
+          end_cursor: page_info['endCursor']
+        )
+      end
+    end
+  end
+end

data/lib/printavo/resources/jobs.rb

@@ -35,14 +35,29 @@ module Printavo
       GQL
 
       def all(order_id:, first: 25, after: nil)
-        data = @graphql.query(ALL_QUERY, variables: { orderId: order_id.to_s, first: first, after: after })
-        data['order']['lineItems']['nodes'].map { |attrs| Printavo::Job.new(attrs) }
+        fetch_page(order_id: order_id, first: first, after: after).records
       end
 
       def find(id)
         data = @graphql.query(FIND_QUERY, variables: { id: id.to_s })
         Printavo::Job.new(data['lineItem'])
       end
+
+      private
+
+      def fetch_page(order_id:, first: 25, after: nil, **)
+        data = @graphql.query(
+          ALL_QUERY,
+          variables: { orderId: order_id.to_s, first: first, after: after }
+        )
+        nodes = data['order']['lineItems']['nodes'].map { |attrs| Printavo::Job.new(attrs) }
+        page_info = data['order']['lineItems']['pageInfo']
+        Printavo::Page.new(
+          records: nodes,
+          has_next_page: page_info['hasNextPage'],
+          end_cursor: page_info['endCursor']
+        )
+      end
     end
   end
 end

data/lib/printavo/resources/orders.rb

@@ -12,6 +12,7 @@ module Printavo
               status {
                 id
                 name
+                color
               }
               customer {
                 id
@@ -38,6 +39,7 @@ module Printavo
             status {
               id
               name
+              color
             }
             customer {
               id
@@ -51,14 +53,26 @@ module Printavo
       GQL
 
       def all(first: 25, after: nil)
-        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
-        data['orders']['nodes'].map { |attrs| Printavo::Order.new(attrs) }
+        fetch_page(first: first, after: after).records
       end
 
       def find(id)
         data = @graphql.query(FIND_QUERY, variables: { id: id.to_s })
         Printavo::Order.new(data['order'])
       end
+
+      private
+
+      def fetch_page(first: 25, after: nil, **)
+        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
+        nodes = data['orders']['nodes'].map { |attrs| Printavo::Order.new(attrs) }
+        page_info = data['orders']['pageInfo']
+        Printavo::Page.new(
+          records: nodes,
+          has_next_page: page_info['hasNextPage'],
+          end_cursor: page_info['endCursor']
+        )
+      end
     end
   end
 end

data/lib/printavo/resources/statuses.rb

@@ -0,0 +1,62 @@
+# lib/printavo/resources/statuses.rb
+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
+
+      def all(first: 100, after: nil)
+        fetch_page(first: first, after: after).records
+      end
+
+      def find(id)
+        data = @graphql.query(FIND_QUERY, variables: { id: id.to_s })
+        Printavo::Status.new(data['status'])
+      end
+
+      # Returns a Hash{Symbol => Status} keyed by Status#key for O(1) lookup.
+      # Pairs with Order#status_key:
+      #   registry = client.statuses.registry
+      #   registry[order.status_key]  #=> <Printavo::Status>
+      def registry
+        all.to_h { |status| [status.key, status] }
+      end
+
+      private
+
+      def fetch_page(first: 100, after: nil, **)
+        data = @graphql.query(ALL_QUERY, variables: { first: first, after: after })
+        nodes = data['statuses']['nodes'].map { |attrs| Printavo::Status.new(attrs) }
+        page_info = data['statuses']['pageInfo']
+        Printavo::Page.new(
+          records: nodes,
+          has_next_page: page_info['hasNextPage'],
+          end_cursor: page_info['endCursor']
+        )
+      end
+    end
+  end
+end

data/lib/printavo/version.rb

@@ -1,4 +1,4 @@
 # lib/printavo/version.rb
 module Printavo
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/lib/printavo.rb

@@ -8,14 +8,19 @@ require_relative 'printavo/errors'
 require_relative 'printavo/config'
 require_relative 'printavo/connection'
 require_relative 'printavo/graphql_client'
+require_relative 'printavo/page'
 require_relative 'printavo/models/base'
 require_relative 'printavo/models/customer'
+require_relative 'printavo/models/status'
 require_relative 'printavo/models/order'
 require_relative 'printavo/models/job'
+require_relative 'printavo/models/inquiry'
 require_relative 'printavo/resources/base'
 require_relative 'printavo/resources/customers'
+require_relative 'printavo/resources/statuses'
 require_relative 'printavo/resources/orders'
 require_relative 'printavo/resources/jobs'
+require_relative 'printavo/resources/inquiries'
 require_relative 'printavo/webhooks'
 require_relative 'printavo/client'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: printavo-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Stan Carver II
@@ -259,9 +259,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- CHANGELOG.md
 - LICENSE
 - README.md
+- docs/CACHING.md
+- docs/CHANGELOG.md
+- docs/CONTRIBUTING.md
+- docs/FUTURE.md
 - lib/printavo.rb
 - lib/printavo/client.rb
 - lib/printavo/config.rb
@@ -270,12 +273,17 @@ files:
 - lib/printavo/graphql_client.rb
 - lib/printavo/models/base.rb
 - lib/printavo/models/customer.rb
+- lib/printavo/models/inquiry.rb
 - lib/printavo/models/job.rb
 - lib/printavo/models/order.rb
+- lib/printavo/models/status.rb
+- lib/printavo/page.rb
 - lib/printavo/resources/base.rb
 - lib/printavo/resources/customers.rb
+- lib/printavo/resources/inquiries.rb
 - lib/printavo/resources/jobs.rb
 - lib/printavo/resources/orders.rb
+- lib/printavo/resources/statuses.rb
 - lib/printavo/version.rb
 - lib/printavo/webhooks.rb
 homepage: https://github.com/scarver2/printavo-ruby
@@ -283,7 +291,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/scarver2/printavo-ruby/issues
-  changelog_uri: https://github.com/scarver2/printavo-ruby/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/scarver2/printavo-ruby/blob/master/docs/CHANGELOG.md
   documentation_uri: https://github.com/scarver2/printavo-ruby#readme
   source_code_uri: https://github.com/scarver2/printavo-ruby
   rubygems_mfa_required: 'true'

data/CHANGELOG.md

@@ -1,33 +0,0 @@
-<!-- CHANGELOG.md -->
-# Changelog
-
-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).
-
-## [Unreleased]
-
-## [0.1.0] - 2026-03-29
-
-### Added
-- `Printavo::Client` — instance-based, multi-client capable entry point
-- `Printavo::Resources::Customers` — `all` and `find` via GraphQL
-- `Printavo::Resources::Orders` — `all` and `find` with status + customer association
-- `Printavo::Resources::Jobs` — `all` (by order) and `find` line item queries
-- `Printavo::Customer`, `Printavo::Order`, `Printavo::Job` — rich domain models
-- `Printavo::Order#status?` — dynamic status predicate (handles user-defined statuses)
-- `Printavo::GraphqlClient` — raw GraphQL query/mutation interface
-- `Printavo::Webhooks.verify` — Rack-compatible HMAC-SHA256 signature verification
-- Error hierarchy: `AuthenticationError`, `RateLimitError`, `NotFoundError`, `ApiError`
-- Faraday connection with retry middleware (max 2 retries; 429/5xx)
-- RSpec test suite — 62 examples, 100% line coverage with VCR + WebMock + Faker sanitization
-- Coveralls coverage badge (LCOV via `simplecov-lcov`)
-- Guard + RuboCop DX setup with `bin/spec` multi-Ruby local runner
-- GitHub Actions CI: Ruby 3.3 (primary) + Ruby 4.0 (`continue-on-error`)
-- Automated RubyGems publish on `v*` tag via `release.yml`
-- `docs/CACHING.md` — nine caching strategy patterns for rate-limit-aware consumers
-
----
-
-— Stan Carver II / Made in Texas 🤠 / https://stancarver.com