printavo-ruby 0.17.0 → 0.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59696533b085e116847901e6b03e9d3687e1a7485b513e350452351d990d9ed2
-  data.tar.gz: b435b6411596af3cb65310f2172f83d25d9ee1e0f317d05d0ad1a25f975c27ad
+  metadata.gz: d2291442eb2c04c3ead1543773bcd188723de181093941cdc8519681b5b43e4b
+  data.tar.gz: 00274b8c115044888d4099465521acf974c0356261130eb6aacaa21f1d4aa5ce
 SHA512:
-  metadata.gz: 0d08433f369b1f5d5943d089558daf52c875ca74d0d7e377ea7b93857b2bc7d905699a21d627a0d23c9ad398d8131a078ec509c36d7d83efb8175c98e877f956
-  data.tar.gz: 9c28bdd515691f4f5ec0b211883a42372cfa28df76f23a2b9608ea9a871b83340f8cca539360747a1e16b9274aa1c9593ab434db3f06f700535c89361504e009
+  metadata.gz: fdd286fc6a29e0313aed8f7ebbea302f7737e17f44144a524396eadcde292d70d9a87b610d22ec3bd692a9a93572d7bb844c861c71dd1e87435c59a3cd465ade
+  data.tar.gz: 29719257b52dfd20f4f9da862e3ccca5df84f8dc64dfb564421a73cbe1b88e46e2a5b36891066ed1e43607e30a3e9a9c6ceecdb3697ac85ce53c2eb1a17b9afa

data/docs/CACHING.md

@@ -205,26 +205,81 @@ how frequently staff update records.
 
 ---
 
-## Future: Built-In Cache Adapter
+## Built-In Cache Adapter
 
-A future version of `printavo-ruby` may support an optional cache adapter
-passed directly to the client:
+As of v0.18.0, `Printavo::Client` accepts an optional `cache:` argument — any
+object responding to `fetch(key, expires_in:) { }` and `delete(key)`. This
+matches the `Rails.cache` interface, so no adapter is needed in Rails apps.
+
+### With Rails.cache
+
+```ruby
+client = Printavo::Client.new(
+  email: ENV["PRINTAVO_EMAIL"],
+  token: ENV["PRINTAVO_TOKEN"],
+  cache: Rails.cache,   # Memcache, Redis, Solid Cache — anything Rails supports
+  default_ttl: 300      # seconds; default is 300 (5 minutes)
+)
+
+# All queries are automatically cached and deduped:
+client.customers.all   # fetches from API, stores result
+client.customers.all   # returns cached result — no HTTP request
+```
+
+### With Printavo::MemoryStore (no Rails dependency)
 
 ```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
+  cache: Printavo::MemoryStore.new,
+  default_ttl: 600
 )
+```
+
+`Printavo::MemoryStore` is a thread-safe, TTL-aware in-memory store included
+in the gem. No configuration required.
 
-# Would cache automatically:
-client.customers.all   # cached for 300s by default
-client.orders.find(1)  # cached per-id
+### Without a cache (default)
+
+```ruby
+client = Printavo::Client.new(
+  email: ENV["PRINTAVO_EMAIL"],
+  token: ENV["PRINTAVO_TOKEN"]
+)
+# cache: nil — every query hits the API
+```
+
+### Cache key generation
+
+Cache keys are generated from a SHA-256 digest of the normalized query document
+and variables: `"printavo:gql:<16-hex-chars>"`. Whitespace differences in query
+strings do not cause cache misses.
+
+### Mutations are never cached
+
+`client.graphql.mutate(...)` always bypasses the cache, regardless of the
+`cache:` setting. Only `client.graphql.query(...)` (and resource methods that
+call it) are cache-aware.
+
+### Custom cache stores
+
+Any object with this interface works:
+
+```ruby
+class MyCache
+  def fetch(key, expires_in: nil)
+    # return cached value, or call block and store the result
+  end
+
+  def delete(key)
+    # remove key from cache
+  end
+end
 ```
 
-Track this feature in [FUTURE.md](../FUTURE.md).
+This is exactly the interface `ActiveSupport::Cache::Store` exposes, so
+Solid Cache, Dalli (Memcache), and Redis Cache Store all work out of the box.
 
 ---
 

data/docs/FUTURE.md

@@ -6,81 +6,40 @@ initial `0.x` releases. Contributions and discussions welcome!
 
 ## Planned Features
 
-### CLI (Thor-based)
+### Client-Side Aggregation Helpers
 
-A `printavo` command-line tool built with [Thor](https://github.com/rails/thor):
+Printavo's V2 GraphQL API is a transactional API — it has no pre-aggregated
+analytics or reporting endpoints. Any analytics must be computed by paging
+through existing resources in Ruby.
 
-```bash
-printavo customers
-printavo orders
-printavo orders find 12345
-printavo analytics revenue
-printavo sync orders --to crm
-```
-
-Planned version: `0.7.0`
-
-### Retry/Backoff
-
-Intelligent rate limit handling with exponential backoff:
+Potential helpers that would add value:
 
 ```ruby
-client = Printavo::Client.new(
-  email: ENV["PRINTAVO_EMAIL"],
-  token: ENV["PRINTAVO_TOKEN"],
-  max_retries: 3,
-  retry_on_rate_limit: true
-)
-```
+# Revenue across all invoices in a date range
+client.invoices.revenue_summary(after: "2026-01-01")
+# => { total: "142300.00", count: 87, average: "1636.78" }
 
-Planned version: `0.8.0`
+# Order counts grouped by status
+client.orders.status_breakdown
+# => { in_production: 12, approved: 5, completed: 230, ... }
 
-### Analytics / Reporting Expansion
+# Most active customers by order count
+client.customers.top(limit: 10, by: :order_count)
 
-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")
+# Average turnaround time (created_at → updated_at) per status
+client.orders.avg_turnaround
 ```
 
-Planned version: `0.5.0`
+These helpers would page all relevant records locally and compute aggregates
+in Ruby. Because they require full pagination, using the built-in cache adapter
+is strongly recommended before implementing these in production workflows.
 
-### 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.
+See [docs/CACHING.md](docs/CACHING.md) for caching options.
 
 ## 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)
+See **[docs/VISUALIZATION.md](VISUALIZATION.md)** for workflow diagram generation —
+Mermaid, DOT, ASCII, and SVG output via the standalone example script.
 
 ## Multi-Language SDK Family
 

data/docs/TODO.md

@@ -402,6 +402,30 @@ return values — they are exposed via model field accessors, not separate resou
 - [x] `Printavo::Enums::TransactionCategory`
 - [x] `Printavo::Enums::TransactionSource`
 
+### v0.17.0 — GraphQL Interface Field Coverage ✅
+
+- [x] `VisualIDed` interface — `visualId` on all applicable models
+- [x] `Timestamps` interface — `createdAt` / `updatedAt` on all applicable models
+- [x] `MailAddress` interface — address fields on all applicable models
+
+### v0.18.0 — Built-In Cache Adapter ✅
+
+- [x] Optional `cache:` kwarg on `Printavo::Client` (any `Rails.cache`-compatible store)
+- [x] `Printavo::MemoryStore` — thread-safe TTL-aware in-memory store (no Rails dependency)
+- [x] `GraphqlClient` caching: `#query` is cache-aware; `#mutate` always bypasses
+- [x] Stable SHA-256 cache key from normalized query + variables
+- [x] `default_ttl: 300` configurable per-client
+- [x] `docs/CACHING.md` updated with built-in adapter usage examples
+
+### v0.18.1 — Examples: Diagramming & Reporting
+
+- [x] `examples/diagramming/workflow_diagram.rb` — Mermaid, DOT, ASCII, SVG (dot CLI + ruby-graphviz gem)
+- [x] `examples/reporting/sales_report.rb` — today, week, month, quarter, YTD, last year, custom range
+- [x] `examples/reporting/sales_tax_report.rb` — invoice-level estimates + fee-level taxable detail
+- [x] `examples/reporting/customers_export.rb` — CSV, XLSX, XLS, vCard (.vcf), HubSpot, Salesforce, Mailchimp, Constant Contact, Beehiiv, Brevo, ActiveCampaign
+- [x] `examples/reporting/outstanding_tasks.rb` — overdue, due today, this week, upcoming, no due date; by-assignee summary; HTML calendar export
+- [x] `docs/FUTURE.md` — Workflow Diagram section replaced with examples reference and rationale
+
 ### v0.99.0 — API Freeze
 
 - [ ] Community feedback integration
@@ -418,11 +442,26 @@ return values — they are exposed via model field accessors, not separate resou
 
 ## Future / Stretch Goals
 
-### Built-In Cache Adapter
+### Client-Side Aggregation Helpers
 
-- [ ] Optional `cache:` kwarg on `Printavo::Client`
-- [ ] Adapter interface: `read(key)` / `write(key, value, ttl:)` / `delete(key)`
-- [ ] `Rails.cache`, Redis, and in-memory adapter support
+> **Note:** Printavo's V2 GraphQL API exposes no pre-aggregated analytics or
+> reporting endpoints. All "analytics" must be computed locally by paging
+> through existing resources. A cache adapter (see below) is a prerequisite
+> before these helpers would be practical in production.
+
+- [ ] `Invoices#revenue_summary(after:, before:)` — page invoices, return total/count/average
+- [ ] `Orders#status_breakdown` — group order count by status key
+- [ ] `Customers#top(limit:, by:)` — rank customers by order count or revenue
+- [ ] `Orders#avg_turnaround` — average time from `created_at` to most recent `updated_at`
+
+### Built-In Cache Adapter ✅ (v0.18.0)
+
+- [x] Optional `cache:` kwarg on `Printavo::Client`
+- [x] Duck-typed adapter interface: `fetch(key, expires_in:) { }` / `delete(key)` — matches `Rails.cache`
+- [x] `Printavo::MemoryStore` — thread-safe in-memory store for non-Rails usage
+- [x] `GraphqlClient#query` is cache-aware; `#mutate` always bypasses cache
+- [x] Stable SHA-256 cache key from normalized query + variables
+- [x] `default_ttl: 300` configurable per-client
 
 ### Workflow Diagram Generation
 
@@ -430,13 +469,6 @@ return values — they are exposed via model field accessors, not separate resou
 - [ ] `ruby-graphviz` backend (DOT → SVG/PNG)
 - [ ] Mermaid output option (embed in GitHub markdown)
 
-### Multi-Language SDK Family
-
-- [ ] `printavo-python`
-- [ ] `printavo-swift`
-- [ ] `printavo-zig`
-- [ ] `printavo-odin`
-
 ---
 
 

data/docs/VISUALIZATION.md

@@ -0,0 +1,81 @@
+<!-- docs/VISUALIZATION.md -->
+# Visualization for [printavo-ruby](https://github.com/scarver2/printavo-ruby)
+
+## Workflow Diagram Generation
+
+See **[examples/diagramming/workflow_diagram.rb](../examples/diagramming/workflow_diagram.rb)**
+for a complete, runnable example covering all four output formats.
+
+Adding diagram generation to the gem itself would require either shipping
+`ruby-graphviz` as a hard dependency or assuming a system `dot` binary —
+both are burdensome for a Ruby API client. The standalone example gives
+consumers full control over their output format and toolchain without
+bloating the gem.
+
+**Supported formats in the example:**
+
+| Format | Dependency | Best for |
+|---|---|---|
+| `:ascii` | none | Terminal output, quick sanity-check |
+| `:mermaid` | none | GitHub README/issues/PRs, VS Code preview |
+| `:dot` | none (text) | Piping to `dot -Tsvg` or any Graphviz renderer |
+| `:svg` | `brew install graphviz` or `gem install ruby-graphviz` | Production-grade visual files |
+
+Statuses are fetched via `client.statuses.all` and rendered as a linear
+left-to-right flow in the order Printavo returns them. Printavo has no
+explicit transition edges in its API — the workflow is an implied sequence.
+
+### Quick Start
+
+```bash
+cd examples/diagramming
+cp .env.example .env   # fill in PRINTAVO_EMAIL and PRINTAVO_TOKEN
+gem install printavo-ruby dotenv
+ruby workflow_diagram.rb
+```
+
+Output files written to the current directory:
+
+| File | Format |
+|---|---|
+| *(stdout)* | ASCII chain |
+| *(stdout)* | Mermaid fenced block |
+| `workflow.dot` | Graphviz DOT source |
+| `workflow_cli.svg` | SVG via `dot` CLI (if graphviz installed) |
+| `workflow_gv.svg` | SVG via `ruby-graphviz` gem (if installed) |
+
+### Rendering DOT to Other Formats
+
+```bash
+# SVG
+dot -Tsvg workflow.dot > workflow.svg
+
+# PNG
+dot -Tpng workflow.dot > workflow.png
+
+# PDF
+dot -Tpdf workflow.dot > workflow.pdf
+```
+
+### Embedding Mermaid in GitHub Markdown
+
+Paste the Mermaid output between fences in any `.md` file:
+
+````markdown
+```mermaid
+flowchart LR
+  s_quote["Quote"] --> s_in_production["In Production"] --> s_completed["Completed"]
+```
+````
+
+GitHub renders it automatically in READMEs, issues, PRs, and wiki pages.
+
+---
+
+## Colophon
+
+[MIT License](LICENSE)
+
+&copy;2026 [Stan Carver II](https://stancarver.com)
+
+![Made in Texas](https://raw.githubusercontent.com/scarver2/howdy-world/master/_dashboard/www/assets/made-in-texas.png)

data/lib/printavo/client.rb

@@ -8,21 +8,38 @@ module Printavo
     # Creates a new Printavo API client. Each instance is independent —
     # multiple clients with different credentials can coexist in one process.
     #
-    # @param email               [String]  the email address associated with your Printavo account
-    # @param token               [String]  the API token from your Printavo My Account page
-    # @param timeout             [Integer] HTTP timeout in seconds (default: 30)
-    # @param max_retries         [Integer] max retry attempts on 5xx/429 responses (default: 2)
-    # @param retry_on_rate_limit [Boolean] retry automatically on 429 Too Many Requests (default: true)
+    # @param email               [String]           the email address associated with your Printavo account
+    # @param token               [String]           the API token from your Printavo My Account page
+    # @param timeout             [Integer]          HTTP timeout in seconds (default: 30)
+    # @param max_retries         [Integer]          max retry attempts on 5xx/429 responses (default: 2)
+    # @param retry_on_rate_limit [Boolean]          retry automatically on 429 Too Many Requests (default: true)
+    # @param cache               [#fetch, #delete]  optional cache store; any object responding to
+    #                                               +fetch(key, expires_in:) { }+ and +delete(key)+,
+    #                                               e.g. +Rails.cache+ or +Printavo::MemoryStore.new+
+    # @param default_ttl         [Integer]          TTL in seconds for cached queries (default: 300)
     #
-    # @example
+    # @example No caching (default)
     #   client = Printavo::Client.new(
     #     email: ENV["PRINTAVO_EMAIL"],
     #     token: ENV["PRINTAVO_TOKEN"]
     #   )
-    #   client.customers.all
-    #   client.orders.find("12345")
-    #   client.graphql.query("{ customers { nodes { id } } }")
-    def initialize(email:, token:, timeout: 30, max_retries: 2, retry_on_rate_limit: true)
+    #
+    # @example With Rails.cache
+    #   client = Printavo::Client.new(
+    #     email: ENV["PRINTAVO_EMAIL"],
+    #     token: ENV["PRINTAVO_TOKEN"],
+    #     cache: Rails.cache,
+    #     default_ttl: 300
+    #   )
+    #
+    # @example With built-in in-memory store
+    #   client = Printavo::Client.new(
+    #     email: ENV["PRINTAVO_EMAIL"],
+    #     token: ENV["PRINTAVO_TOKEN"],
+    #     cache: Printavo::MemoryStore.new
+    #   )
+    def initialize(email:, token:, timeout: 30, max_retries: 2, retry_on_rate_limit: true, # rubocop:disable Metrics/ParameterLists
+                   cache: nil, default_ttl: 300)
       connection = Connection.new(
         email: email,
         token: token,
@@ -30,7 +47,7 @@ module Printavo
         max_retries: max_retries,
         retry_on_rate_limit: retry_on_rate_limit
       ).build
-      @graphql = GraphqlClient.new(connection)
+      @graphql = GraphqlClient.new(connection, cache: cache, default_ttl: default_ttl)
     end
 
     def account

data/lib/printavo/graphql_client.rb

@@ -1,12 +1,20 @@
 # lib/printavo/graphql_client.rb
 # frozen_string_literal: true
 
+require 'digest'
 require 'json'
 
 module Printavo
   class GraphqlClient
-    def initialize(connection)
-      @connection = connection
+    # @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)
+      @connection  = connection
+      @cache       = cache
+      @default_ttl = default_ttl
     end
 
     # Executes a GraphQL query and returns the parsed `data` hash.
@@ -22,7 +30,11 @@ module Printavo
     #     variables: { id: "42" }
     #   )
     def query(query_string, variables: {})
-      execute(query_string, variables: variables)
+      return execute(query_string, variables: variables) unless @cache
+
+      @cache.fetch(cache_key(query_string, variables), expires_in: @default_ttl) do
+        execute(query_string, variables: variables)
+      end
     end
 
     # Executes a GraphQL mutation and returns the parsed `data` hash.
@@ -86,6 +98,13 @@ module Printavo
 
     private
 
+    # Generates a stable, namespaced cache key from the query document and variables.
+    # Whitespace in the query is collapsed so formatting differences don't cause misses.
+    def cache_key(query_string, variables)
+      payload = JSON.generate([query_string.gsub(/\s+/, ' ').strip, variables])
+      "printavo:gql:#{Digest::SHA256.hexdigest(payload)[0, 16]}"
+    end
+
     def execute(document, variables: {})
       response = @connection.post('') do |req|
         req.body = JSON.generate(query: document, variables: variables)

data/lib/printavo/memory_store.rb

@@ -0,0 +1,76 @@
+# lib/printavo/memory_store.rb
+# frozen_string_literal: true
+
+module Printavo
+  # A simple thread-safe in-memory cache store for use without Rails or Redis.
+  # Implements the same +fetch+ / +delete+ interface as +Rails.cache+, so it
+  # can be swapped for any compatible store without changing call sites.
+  #
+  # @example Standalone use
+  #   client = Printavo::Client.new(
+  #     email: ENV["PRINTAVO_EMAIL"],
+  #     token: ENV["PRINTAVO_TOKEN"],
+  #     cache: Printavo::MemoryStore.new
+  #   )
+  #
+  # @example With custom default TTL
+  #   client = Printavo::Client.new(
+  #     email: ENV["PRINTAVO_EMAIL"],
+  #     token: ENV["PRINTAVO_TOKEN"],
+  #     cache:       Printavo::MemoryStore.new,
+  #     default_ttl: 600  # 10 minutes
+  #   )
+  class MemoryStore
+    def initialize
+      @store      = {}
+      @expires_at = {}
+      @mutex      = Mutex.new
+    end
+
+    # Returns the cached value for +key+, or calls the block, stores the
+    # result, and returns it. Expired entries are treated as missing.
+    #
+    # @param key        [String]
+    # @param expires_in [Integer, nil] TTL in seconds; +nil+ means no expiry
+    # @yieldreturn      the value to cache on a miss
+    # @return           the cached or freshly-computed value
+    def fetch(key, expires_in: nil)
+      @mutex.synchronize do
+        cached = read(key)
+        return cached unless cached.nil?
+
+        yield.tap { |v| write(key, v, expires_in: expires_in) }
+      end
+    end
+
+    # Removes +key+ from the cache.
+    #
+    # @param key [String]
+    # @return [nil]
+    def delete(key)
+      @mutex.synchronize do
+        @store.delete(key)
+        @expires_at.delete(key)
+      end
+      nil
+    end
+
+    private
+
+    def read(key)
+      exp = @expires_at[key]
+      if @store.key?(key) && (exp.nil? || Time.now < exp)
+        @store[key]
+      else
+        @store.delete(key)
+        @expires_at.delete(key)
+        nil
+      end
+    end
+
+    def write(key, value, expires_in: nil)
+      @store[key]      = value
+      @expires_at[key] = Time.now + expires_in if expires_in
+    end
+  end
+end

data/lib/printavo/version.rb

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

data/lib/printavo.rb

@@ -11,6 +11,7 @@ require_relative 'printavo/connection'
 require_relative 'printavo/enums'
 require_relative 'printavo/errors'
 require_relative 'printavo/graphql_client'
+require_relative 'printavo/memory_store'
 require_relative 'printavo/page'
 require_relative 'printavo/models/base'
 require_relative 'printavo/models/account'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: printavo-ruby
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.1
 platform: ruby
 authors:
 - Stan Carver II
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-01 00:00:00.000000000 Z
+date: 2026-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -285,6 +285,7 @@ files:
 - docs/CONTRIBUTING.md
 - docs/FUTURE.md
 - docs/TODO.md
+- docs/VISUALIZATION.md
 - lib/printavo.rb
 - lib/printavo/cli.rb
 - lib/printavo/client.rb
@@ -465,6 +466,7 @@ files:
 - lib/printavo/graphql/vendors/all.graphql
 - lib/printavo/graphql/vendors/find.graphql
 - lib/printavo/graphql_client.rb
+- lib/printavo/memory_store.rb
 - lib/printavo/models/account.rb
 - lib/printavo/models/approval_request.rb
 - lib/printavo/models/base.rb