feat: v0.18.1 — examples: diagramming, reporting, and CRM exports

[scarver2]

Summary

Standalone runnable examples — no new gem dependencies added to the library itself.

examples/diagramming/workflow_diagram.rb

• Fetches client.statuses.all and renders the shop's workflow in 4 formats
• :ascii — zero-dependency terminal output
• :mermaid — GitHub-renderable flowchart (paste between ```mermaid fences)
• :dot — Graphviz DOT source written to workflow.dot; pipe to dot -Tsvg for any format
• :svg — written via dot CLI (brew install graphviz) or ruby-graphviz gem; both optional, both skip gracefully
• Hex status colors from Printavo with automatic black/white text contrast

examples/reporting/sales_report.rb

• Pages all invoices via client.invoices.all_pages, filters by period in Ruby
• Periods: today, this week, this month, this quarter, YTD, last year, custom range (REPORT_START / REPORT_END)
• Metrics: gross revenue, amount paid, outstanding, paid-in-full count, average, largest, YTD breakdown by status

examples/reporting/sales_tax_report.rb

• Approach 1 — invoice-level estimate using TAX_RATE env var (fast, no extra API calls)
• Approach 2 — fee-level detail fetching taxable: true fees per invoice; MemoryStore cache wired in

examples/reporting/customers_export.rb — 11 formats

File	Format
customers.csv	Universal CSV (stdlib)
customers.vcf	vCard 3.0 — any CRM, email client, or phone
customers_hubspot.csv	HubSpot Contacts import
customers_salesforce.csv	Salesforce Leads/Contacts import
customers_mailchimp.csv	Mailchimp audience import
customers_constantcontact.csv	Constant Contact contact import
customers_beehiiv.csv	Beehiiv subscriber import (with UTM tagging)
customers_brevo.csv	Brevo (Sendinblue) attribute-named import
customers_activecampaign.csv	ActiveCampaign import (auto-tags printavo-customer)
customers.xlsx	Excel workbook — gem install caxlsx
customers.xls	Legacy Excel 97–2003 — gem install spreadsheet

Optional gem exports skip gracefully with a gem install hint.

examples/reporting/outstanding_tasks.rb

• Terminal report: overdue (bold red), due today (yellow), this week (cyan), upcoming (green), no due date
• By-assignee summary with overdue count highlighted
• HTML calendar (tasks_calendar.html) — self-contained, no CDN, printable
  • Monthly grid (Mon–Sun), up to 3 months per row
  • Color-coded task chips with hover tooltips (full body + assignee)
  • No-due-date tasks in a table below the calendars
  • Range: span of task due dates by default; override with CALENDAR_START / CALENDAR_END

docs/FUTURE.md

Workflow Diagram section replaced with examples-folder reference and rationale for keeping graphviz out of the gem.

Test plan

• All example files have file-path prolog + # frozen_string_literal: true
• .env.example in both example directories
• docs/FUTURE.md and docs/TODO.md updated
• Pre-push hook passes (Gemfile.lock version ✓, x86_64-linux platform ✓)
• Smoke-test: cp .env.example .env && ruby examples/diagramming/workflow_diagram.rb
• Smoke-test: ruby examples/reporting/customers_export.rb
• Smoke-test: ruby examples/reporting/outstanding_tasks.rb && open tasks_calendar.html

🤖 Generated with Claude Code