profitable 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f24a9849fbf5f3d6b87beaa3f0a4100d18a45ccb2b585e8e48b417d303759593
-  data.tar.gz: 7c8523a9547f30468ee7517a92af604aa66c7bcc269e6292200d8722f83c30ff
+  metadata.gz: 589bf3accd7eb5a430b00a724b1419ec8f1091bde38b86debdd1e996b8608371
+  data.tar.gz: 80402781b526c6bccc9b452034d3cabcd445d82adc1e85076f899ec4201bdcb8
 SHA512:
-  metadata.gz: 4b79c94e7288c859f7419a8afe27c4352db1be8cff2c269b9d9d57348761a59e5f3a48cfe4b601496a1d4642b88fd5e2e5f349a1733f133488bb47a153b6a453
-  data.tar.gz: 216578eb9882a946fed3818c7d9301449727cd2b1bc64b282e90e1d8cf056b2f05ff801e49748ec46cf89a008771d796ec65daf9ce99d7ed058da5fa0d284e01
+  metadata.gz: 3cb3efa5003453fe2ba9372ac6fe51c35954c5e0e6d02829a6916c8876138d9458aee1273091a8ea28c71303be5fca826459d7343eb48141dd69d0de6309f158
+  data.tar.gz: cf45ac397f09ea38dda42719d629e6eb238b349dd9e02a5afb2c1291bcab166945b6ea53b1f9a8015cfe766e9be6bb9e4574e041fe7b9bb00a4f8d7ecfd6c9c4

data/.simplecov

@@ -15,10 +15,10 @@ SimpleCov.start do
   add_filter "/lib/profitable/engine.rb"
   add_filter "/app/"
 
-  # Exclude the main profitable.rb entry point - it loads the engine and
-  # defines the Profitable module. Our unit tests use a test-specific
-  # Profitable module (defined in test_helper.rb) to avoid Rails dependencies.
-  # The core logic is tested via the individual lib/profitable/*.rb files.
+  # Exclude the main profitable.rb entry point - it only requires the engine
+  # and the gem's components. The test harness loads those components directly
+  # (test_helper.rb) because requiring the engine needs a full Rails app, so
+  # all core logic in lib/profitable/*.rb runs as real production code paths.
   add_filter "/lib/profitable.rb"
 
   # Track the lib directory (core gem logic)

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # `profitable`
 
+## [0.6.0] - 2026-06-23
+
+Accuracy-focused release: every metric was re-audited line by line against the actual data `pay` (7.x–11.x) stores.
+
+- **Fix canceled trials polluting nearly every flow metric**: a trial that was canceled without ever converting no longer counts in `total_subscribers`, `total_customers`, `new_customers`, `new_subscribers`, `new_mrr`, `churned_customers`, `churned_mrr`, `churn`, or the monthly/daily summaries. A subscription now only counts as ever-billable if it ended *after* billing started
+- **Fix survivor bias in `monthly_summary` churn rates**: the churn denominator now includes subscribers who churned later inside the window, so early months no longer overstate churn
+- **Fix summaries counting future trial conversions**: a trial scheduled to convert later this month/day no longer appears as a new subscriber (and new MRR) before it actually converts
+- **Fix `paid: false` charges counting as revenue on SQLite**: JSON booleans surface as integers on SQLite (vs. text on PostgreSQL/MySQL); JSON extraction is now text-cast so all adapters filter identically (Rails 8 runs SQLite in production)
+- **Handle Braintree/Lemon Squeezy statuses**: `expired` now counts as churn (at `ends_at`) instead of billable-forever, and `pending` (future start date, never billed) is excluded everywhere
+- **Fix `time_to_next_mrr_milestone` returning a bare String**: it now returns a `NumericResult` like every other metric, so the documented `.to_readable` works (plain string comparisons still behave the same)
+- **Fix Pay 7-9 schema compatibility for charge filtering**: revenue queries now only reference `pay_charges.object` when that column exists, so legacy `data`-only schemas do not crash
+- **Fix paused subscriptions disappearing from lifecycle metrics**: paused subscriptions without a local pause start date remain excluded from current MRR, but still count as customers/subscribers if they had already become billable
+- **Fix two small edge cases**: sub-dollar positive MRR no longer reports as "No MRR yet" for milestone messaging, and monthly churn denominators now match the inclusive period-start semantics used by `churn`
+- Add `Profitable.mrr_at(date)` as the public historical MRR snapshot API, keeping the raw `calculate_mrr_at` helper private
+- Preserve existing `Profitable::Error` messages in MRR snapshot delegation instead of double-wrapping them
+- **Correct the processor coverage docs**: `pay` only stores subscription price payloads locally for Stripe, so Braintree/Paddle subscriptions contribute 0 to MRR-style metrics unless the payload is backfilled — the README previously overstated this; charge-based and lifecycle-based metrics remain fully portable across all processors
+- DRY consolidation: MRR "billable right now" and "billable at date" are now literally the same query (`MrrCalculator.calculate` delegates to the shared snapshot), churn-event queries are defined once and reused by all metrics and summaries, and `subscription_data` has a single source of truth
+- `MrrCalculator.calculate` streams subscriptions in batches (`find_each`) everywhere, keeping memory flat on large datasets
+- Test coverage increased to ~98% line / ~90% branch, including regression tests for every bug above, exercised against Pay 7.3–11.x and Rails 7.2–8.1
+
+## [0.5.0] - 2026-03-19
+- Add `Profitable.ttm_revenue` for trailing twelve-month revenue
+- Add `Profitable.ttm` as a founder-friendly alias for `ttm_revenue`
+- Add `Profitable.revenue_run_rate`, `estimated_arr_valuation`, `estimated_ttm_revenue_valuation`, and `estimated_revenue_run_rate_valuation`
+- Make revenue metrics net of refunds when `amount_refunded` is present
+- Make subscriber and MRR metrics distinguish between current billable subscriptions and historical period events
+- Count `new_customers` from first monetization date rather than signup date
+- Count `new_subscribers` / `new_mrr` from when a subscription becomes billable, not when a free trial starts
+- Handle additional Pay status variants like `on_trial`, `cancelled`, and `deleted`
+- Keep grace-period subscriptions billable until `ends_at`
+- Exclude metered Stripe items from fixed run-rate MRR calculations
+- Surface TTM revenue in the built-in dashboard
+- Extract shared metric logic to `lib/profitable/metrics.rb` for cleaner architecture
+
 ## [0.4.0] - 2026-02-10
 - Add monthly summary (12mo) and daily summary (30d) tables to dashboard
 - Add `period_data` method for efficient batch computation of period metrics
@@ -32,4 +66,4 @@
 
 ## [0.1.0] - 2024-08-29
 
-- Initial test release (not production ready)
+- Initial test release (not production ready)

data/README.md

@@ -15,7 +15,7 @@
 
 Usually, you would look into your Stripe Dashboard or query the Stripe API to know your MRR / ARR / churn – but when you're using `pay`, you already have that data available and auto synced to your own database. So we can leverage it to make handy, composable ActiveRecord queries that you can reuse in any part of your Rails app (dashboards, internal pages, reports, status messages, etc.)
 
-Think doing something like: `"Current MRR: $#{Profitable.mrr}"` or `"Your app is worth $#{Profitable.valuation_estimate("3x")} at a 3x valuation"`
+Think doing something like: `"Current MRR: $#{Profitable.mrr}"` or `"Your app is worth $#{Profitable.estimated_valuation("3x")} at a 3x valuation"`
 
 ## Installation
 
@@ -28,6 +28,19 @@ Then run `bundle install`.
 
 Provided you have a valid [`pay`](https://github.com/pay-rails/pay) installation (`Pay::Customer`, `Pay::Subscription`, `Pay::Charge`, etc.) everything is already set up and you can just start using [`Profitable` methods](#main-profitable-methods) right away.
 
+For Stripe, metered subscription items are intentionally excluded from fixed run-rate metrics like `mrr`, `arr`, `new_mrr`, and `churned_mrr`.
+
+> [!IMPORTANT]
+> MRR-style metrics need each subscription's price payload, and `pay` only stores that payload locally for **Stripe** (in the `object` column on Pay v10+, and in `data['subscription_items']` on Pay 7–9). So:
+>
+> - **Subscription amount parsing (full support): `stripe`.**
+> - `braintree`, `paddle_billing`, and `paddle_classic` subscriptions contribute `0` to amount-derived metrics out of the box, because `pay` does not persist their price payloads locally. `profitable` ships parsing adapters for them, so they are supported if your app backfills `pay_subscriptions.object` with the processor's subscription payload — otherwise they are counted in subscriber/churn metrics but add `0` MRR (never wrong amounts).
+> - Subscriptions from any other processor (e.g. `lemon_squeezy`) also contribute `0` to amount-derived metrics until an adapter is added.
+>
+> Metrics that depend on processor-specific subscription amount parsing include `mrr`, `arr`, `new_mrr`, `churned_mrr`, `mrr_growth`, `mrr_growth_rate`, `lifetime_value`, `time_to_next_mrr_milestone`, and MRR-derived fields in summaries.
+>
+> Metrics based on `Pay::Charge` and generic subscription lifecycle fields are portable across **all** processors, including `all_time_revenue`, `revenue_in_period`, `ttm_revenue`, `revenue_run_rate`, customer counts, subscriber counts, and churn calculations — `pay` stores real amounts and lifecycle dates locally for every processor.
+
 ## Mount the `/profitable` dashboard
 
 `profitable` also provides a simple dashboard to see your main business metrics.
@@ -52,25 +65,32 @@ All methods return numbers that can be converted to a nicely-formatted, human-re
 
 ### Revenue metrics
 
-- `Profitable.mrr`: Monthly Recurring Revenue (MRR)
-- `Profitable.arr`: Annual Recurring Revenue (ARR)
-- `Profitable.all_time_revenue`: Total revenue since launch
-- `Profitable.revenue_in_period(in_the_last: 30.days)`: Total revenue (recurring and non-recurring) in the specified period
+- `Profitable.mrr`: Monthly Recurring Revenue (MRR) from subscriptions that are billable right now
+- `Profitable.mrr_at(date)`: Historical MRR snapshot from subscriptions that were billable at the given date
+- `Profitable.arr`: Annual Recurring Revenue (ARR), calculated as current `mrr * 12`, not trailing revenue
+- `Profitable.ttm`: Founder-friendly shorthand alias for `ttm_revenue`
+- `Profitable.ttm_revenue`: Trailing twelve-month revenue, net of refunds when `amount_refunded` is present
+- `Profitable.revenue_run_rate(in_the_last: 30.days)`: Recent revenue annualized (useful for TrustMRR-style revenue multiples)
+- `Profitable.all_time_revenue`: Net revenue since launch
+- `Profitable.revenue_in_period(in_the_last: 30.days)`: Net revenue (recurring and non-recurring) in the specified period
 - `Profitable.recurring_revenue_in_period(in_the_last: 30.days)`: Only recurring revenue in the specified period
 - `Profitable.recurring_revenue_percentage(in_the_last: 30.days)`: Percentage of revenue that is recurring in the specified period
-- `Profitable.new_mrr(in_the_last: 30.days)`: New MRR added in the specified period
+- `Profitable.new_mrr(in_the_last: 30.days)`: Full MRR from subscriptions that first became billable in the specified period
 - `Profitable.churned_mrr(in_the_last: 30.days)`: MRR lost due to churn in the specified period
 - `Profitable.average_revenue_per_customer`: Average revenue per customer (ARPC)
 - `Profitable.lifetime_value`: Estimated customer lifetime value (LTV)
-- `Profitable.estimated_valuation(at: "3x")`: Estimated company valuation based on ARR
+- `Profitable.estimated_valuation(at: "3x")`: ARR-based valuation heuristic
+- `Profitable.estimated_arr_valuation(at: "3x")`: Explicit ARR-based valuation heuristic
+- `Profitable.estimated_ttm_revenue_valuation(at: "2x")`: TTM revenue-based valuation heuristic
+- `Profitable.estimated_revenue_run_rate_valuation(at: "2x", in_the_last: 30.days)`: Recent revenue run-rate valuation heuristic
 
 ### Customer metrics
 
-- `Profitable.total_customers`: Total number of customers who have ever made a purchase or had a subscription (current and past)
-- `Profitable.total_subscribers`: Total number of customers who have ever had a subscription (active or not)
-- `Profitable.active_subscribers`: Number of customers with currently active subscriptions
-- `Profitable.new_customers(in_the_last: 30.days)`: Number of new customers added in the specified period
-- `Profitable.new_subscribers(in_the_last: 30.days)`: Number of new subscribers added in the specified period
+- `Profitable.total_customers`: Total number of customers who have ever monetized through a paid charge or a paid subscription state
+- `Profitable.total_subscribers`: Total number of customers who have ever reached a paid subscription state (trial-only subscriptions do not count)
+- `Profitable.active_subscribers`: Number of customers with subscriptions that are billable right now
+- `Profitable.new_customers(in_the_last: 30.days)`: Number of first-time customers added in the period based on first monetization date, not signup date
+- `Profitable.new_subscribers(in_the_last: 30.days)`: Number of customers whose subscriptions first became billable in the specified period
 - `Profitable.churned_customers(in_the_last: 30.days)`: Number of customers who churned in the specified period
 
 ### Other metrics
@@ -94,6 +114,9 @@ All methods return numbers that can be converted to a nicely-formatted, human-re
 # Get the current MRR
 Profitable.mrr.to_readable # => "$1,234"
 
+# Get the MRR snapshot for a historical date
+Profitable.mrr_at(30.days.ago).to_readable # => "$987"
+
 # Get the number of new customers in the last 60 days
 Profitable.new_customers(in_the_last: 60.days).to_readable # => "42"
 
@@ -104,11 +127,24 @@ Profitable.churn(in_the_last: 3.months).to_readable # => "12%"
 Profitable.new_mrr(in_the_last: 24.hours).to_readable(2) # => "$123.45"
 
 # Get the estimated valuation at 5x ARR (defaults to 3x if no multiple is specified)
-Profitable.estimated_valuation(multiple: 5).to_readable # => "$500,000"
+Profitable.estimated_arr_valuation(multiple: 5).to_readable # => "$500,000"
+
+# Get trailing twelve-month revenue
+Profitable.ttm_revenue.to_readable # => "$123,456"
+
+# Founder-friendly shorthand for trailing twelve-month revenue
+Profitable.ttm.to_readable # => "$123,456"
 
-# You can also pass the multiplier as a string. You can also use the `at:` keyword argument (same thing as `multiplier:`) – and/or ignore the `at:` or `multiplier:` named arguments altogether
+# Get recent revenue annualized (useful for TrustMRR-style revenue multiples)
+Profitable.revenue_run_rate(in_the_last: 30.days).to_readable # => "$96,000"
+
+# `estimated_valuation` remains as a backwards-compatible alias of `estimated_arr_valuation`
 Profitable.estimated_valuation(at: "4.5x").to_readable # => "$450,000"
 
+# Be explicit about the denominator when comparing marketplace comps
+Profitable.estimated_ttm_revenue_valuation(2).to_readable
+Profitable.estimated_revenue_run_rate_valuation(2.7, in_the_last: 30.days).to_readable
+
 # Get the time to next MRR milestone
 Profitable.time_to_next_mrr_milestone.to_readable  # => "26 days left to $10,000 MRR"
 ```
@@ -129,11 +165,207 @@ For more precise calculations, you can access the raw numeric value:
 Profitable.mrr # => 123456
 ```
 
+Revenue methods are net of refunds when `amount_refunded` is present on `pay_charges`.
+
 ### Notes on specific metrics
 
+- **Canceled trials never count.** A subscription only enters subscriber counts, new/churned MRR, churn rates, and the dashboard summaries if it actually started billing before it ended. A free trial that gets canceled (before or at conversion) adds nothing to any metric — it was never revenue, so it is neither a "new subscriber" nor "churn".
+- `churn` and `churned_customers`: a churn event happens when billing actually stops (`ends_at`), not when the cancellation is requested. A subscription canceled with a grace period keeps counting in MRR and `active_subscribers` until the grace period runs out.
 - `mrr_growth_rate`: This calculation compares the MRR at the start and end of the specified period. It assumes a linear growth rate over the period, which may not reflect short-term fluctuations. For more accurate results, consider using shorter periods or implementing a more sophisticated growth calculation method if needed.
 - `time_to_next_mrr_milestone`: This estimation is based on the current MRR and the recent growth rate. It assumes a constant growth rate, which may not reflect real-world conditions. The calculation may be inaccurate for very new businesses or those with irregular growth patterns.
 
+## Metric guide: TTM, Revenue, Profit, ARR, and MRR
+
+`profitable` exposes both standard recurring revenue metrics (`MRR`, `ARR`) and trailing actuals (`TTM revenue`) on purpose.
+
+These metrics are related, but they are not interchangeable:
+
+| Metric | What it means | Best for | What it is **not** |
+| --- | --- | --- | --- |
+| `MRR` | Monthly Recurring Revenue from subscriptions that are billable right now | Operating cadence, near-term momentum, tracking upgrades/downgrades | It's **not** monthly cash collected from all sources |
+| `ARR` | Annual Recurring Revenue, calculated as the current recurring base annualized | Forecasting recurring scale, board/investor reporting, recurring-revenue quality | It's **not** a historical last-12-month revenue |
+| `MRR * 12` | Simple annualization of the current monthly recurring base | Fast ARR approximation when the base is normalized monthly | It's **not** TTM revenue or TTM profit |
+| `TTM revenue` | Actual revenue collected over the last 12 months | Buyer-facing historical actuals, smoothing seasonality, sanity-checking ARR | It's **not** a forward recurring run-rate |
+| `TTM profit` | Actual profit over the last 12 months | Small bootstrapped SaaS exits, ROI-minded buyers, earnings-based multiples | It's **not** something `profitable` can derive from `pay` alone |
+
+### The distinction
+
+- `ARR` is a run-rate metric. Stripe describes it as revenue you "expect to earn in a year" and notes that `ARR = MRR × 12`.
+- `TTM` is a trailing metric. CFI defines it as the "most recent 12-month period" and uses it for reported actuals such as revenue and EBITDA.
+- `TTM revenue` tells you what customers actually paid over the last year.
+- `TTM profit` tells you what the business actually kept after costs. This is often what smaller acquisition buyers care about most, but it requires cost data outside `pay`.
+- In acquire-style market reports, `TTM` can refer to **both** `TTM profit` and `TTM revenue` depending on the chart. The denominator must always be stated explicitly.
+- In `profitable`, the shorthand method `ttm` is defined to mean `ttm_revenue` because the gem does not yet model costs or profit.
+
+In other words:
+
+- `ARR` answers: "What is my current recurring run-rate? What do I expect to earn in a year?"
+- `TTM revenue` answers: "What did I actually collect over the last year?"
+
+### What `profitable` calculates
+
+- `Profitable.mrr`: Monthly Recurring Revenue (MRR) from subscriptions that are billable right now
+- `Profitable.arr`: Annual Recurring Revenue (ARR), calculated from current MRR
+- `Profitable.ttm`: shorthand alias for `ttm_revenue`
+- `Profitable.ttm_revenue`: trailing 12-month revenue, net of refunds when `amount_refunded` is present
+- `Profitable.revenue_run_rate`: recent revenue annualized to a yearly run-rate
+- `Profitable.estimated_valuation`: ARR-multiple heuristic
+- `Profitable.estimated_ttm_revenue_valuation`: TTM revenue heuristic
+- `Profitable.estimated_revenue_run_rate_valuation`: recent revenue run-rate heuristic
+
+`profitable` does **not** calculate `TTM profit`, because payroll, contractor spend, hosting, support, software tools, taxes, and owner add-backs do not live inside `pay`.
+
+### Which metric matters in which situation?
+
+- If you're operating the business week to week: `MRR` is usually the best pulse metric.
+- If you want to understand your current subscription run-rate: `ARR` is the right metric.
+- If you're preparing buyer materials for a bootstrapped SaaS exit: add `TTM revenue` and your own `TTM profit`.
+- If your business has meaningful one-time revenue, services, setup fees, or seasonal swings: `TTM revenue` matters more than `ARR`.
+- If you are speaking to serious SaaS buyers about revenue quality: pair `ARR` with churn, growth, concentration, and margins.
+
+### What the market says
+
+These are short excerpts from current market and finance sources, followed by why they matter for `profitable`.
+
+- [Acquire.com Biannual Multiples Report (Jan 2026)](https://blog.acquire.com/acquire-com-biannual-acquisition-multiples-report-jan-2026/): "anchor valuation on profit"
+  Acquire says the January 2026 report is focused "entirely on profit multiples," which is highly relevant for smaller bootstrapped SaaS exits.
+  In the same report, some visual breakdowns segment businesses by `TTM revenue` bands, so it is important not to assume one bare `TTM` label means the same thing everywhere.
+
+- [Acquire.com Biannual Multiples Report, January 2024](https://blog.acquire.com/wp-content/uploads/2024/01/Acquire-Biannual-Multiples-Report-Jan-2024.pdf): "4.3x TTM profit"
+  The earlier report gives a concrete historical benchmark for how these profit multiples looked on the marketplace.
+
+- [Acquire.com 2025 webinar recap](https://blog.acquire.com/the-secrets-behind-2024s-biggest-exits-webinar-recap/): "$100k-$1M in TTM revenue"
+  Acquire says that cohort averaged `4.35x`, which is a useful live-market anchor for micro-SaaS exits.
+
+- [Acquire.com SaaS valuation multiples guide](https://blog.acquire.com/saas-valuation-multiples/): "5x to 15x ARR"
+  Stronger recurring SaaS businesses are also routinely discussed in ARR-multiple terms, especially when growth and retention are strong.
+
+- [Stripe on ARR](https://stripe.com/us/resources/more/acv-vs-arr-what-each-metric-really-means-and-when-they-matter): "ARR = £50,000 x 12 = £600,000"
+  This is the clearest shorthand for why `ARR` is a run-rate, not a trailing actual.
+
+- [CFI on TTM](https://corporatefinanceinstitute.com/resources/valuation/railing-twelve-months-ttm-definition/): "most recent 12-month period"
+  This is why `ttm_revenue` belongs beside `arr`: it measures trailing actuals, not a projection.
+
+- [Quiet Light on selling SaaS](https://quietlight.com/sell-your-saas-business-for-the-best-price/): "EBITDA or SDE"
+  Quiet Light explicitly says smaller SaaS businesses are often valued on earnings, not revenue, which is why `TTM profit` matters.
+
+- [Quiet Light on larger SaaS](https://quietlight.com/sell-your-saas-business-for-the-best-price/): "ARR of $1M or more"
+  The same source says larger SaaS businesses may qualify for revenue multiples, which is why `ARR` becomes more important as the business scales.
+
+- [Software Equity Group, 3Q25 SaaS M&A](https://softwareequity.com/blog/saas-ma-deal-volume-and-valuations): "5.4x"
+  SEG reported average SaaS M&A valuations of `5.4x` revenue in 3Q25, which is useful context for larger, more institutional software transactions.
+
+- [TrustMRR live listing example](https://trustmrr.com/startup/appalchemy): "$164,819 TTM revenue"
+  Live marketplaces increasingly show `TTM revenue`, `TTM profit`, and `ARR` side by side, which matches how buyers actually compare deals.
+
+- [TrustMRR FAQ](https://trustmrr.com/faq): "asking price divided by annualized revenue"
+  TrustMRR explicitly defines its marketplace multiple as asking price divided by `last 30 days revenue × 12`, so its multiple is a revenue run-rate multiple, not an ARR multiple.
+
+- [TrustMRR FAQ](https://trustmrr.com/faq): "Only aggregate revenue metrics"
+  TrustMRR says it only pulls revenue-level aggregates from payment providers, which is another reason its native multiple is revenue-based rather than profit-based.
+
+- [TrustMRR FAQ](https://trustmrr.com/faq): "profit margin for the last 30 days"
+  TrustMRR asks sellers to provide profit margin separately when listing for sale, which reinforces that profit-based heuristics need cost inputs outside the payment provider.
+
+### How to use these metrics responsibly
+
+- `estimated_valuation` is intentionally simple. It is kept as a backwards-compatible ARR heuristic. Prefer `estimated_arr_valuation` in new code when you want the denominator to be explicit.
+- Do not compare an ARR multiple and a TTM profit multiple as if they were the same kind of number. They are based on different denominators.
+- A `4x TTM profit` deal, a `2x TTM revenue` deal, and an `8x ARR` deal can all describe reasonable SaaS outcomes in different buyer segments.
+- If two businesses both have `$300k ARR`, the one with lower churn, better margins, lower concentration, and cleaner growth usually deserves the higher multiple.
+- If two businesses both have `$300k TTM revenue`, the one with stronger profit and more recurring revenue usually deserves the higher price.
+
+### Typical multiples by SaaS type and size
+
+These are rough, source-backed heuristics. They are not interchangeable.
+
+| SaaS profile | Common denominator | Rough multiple | Source |
+| --- | --- | --- | --- |
+| Smaller profitable SaaS on Acquire.com (2024-2025 confirmed transactions) | `TTM profit` | `3.9x` median | [Acquire.com Jan 2026 report](https://blog.acquire.com/acquire-com-biannual-acquisition-multiples-report-jan-2026/) |
+| Micro-SaaS under `$100k` TTM revenue | `TTM profit` | `3.55x` average | [Acquire.com webinar recap](https://blog.acquire.com/the-secrets-behind-2024s-biggest-exits-webinar-recap/) |
+| Micro-SaaS with `$100k-$1M` TTM revenue | `TTM profit` | `4.35x` average | [Acquire.com webinar recap](https://blog.acquire.com/the-secrets-behind-2024s-biggest-exits-webinar-recap/) |
+| TrustMRR marketplace listings | `Annualized last 30d revenue` | often roughly `0.6x-5.5x` ask multiples | [TrustMRR homepage snapshot](https://trustmrr.com/) |
+| Mid-6-figure ARR SaaS | `TTM revenue` | `2x-4x` revenue | [Acquire.com founder-driven acquisition recap](https://blog.acquire.com/how-founders-can-drive-their-own-acquisition-process-webinar-recap/) |
+| Older Acquire.com SaaS baseline | `TTM revenue` or `TTM profit` | `2-3x revenue` or `5x profit` | [Acquire.com 7-8 figures webinar recap](https://blog.acquire.com/how-to-sell-your-company-playbook-webinar/) |
+| Strong recurring SaaS with high growth and retention | `ARR` | `5x-15x ARR` | [Acquire.com SaaS valuation multiples guide](https://blog.acquire.com/saas-valuation-multiples/) |
+
+How to read this table:
+
+- Smaller bootstrapped SaaS buyers on Acquire-style marketplaces often underwrite on `TTM profit`.
+- If profit is low or intentionally reinvested, buyers may fall back to `TTM revenue`.
+- TrustMRR listing multiples are a secondary comparison set: they are based on recent revenue run-rate, specifically `last 30 days revenue × 12`.
+- Higher-quality SaaS with real scale, low churn, and strong growth is more likely to be discussed in `ARR` terms.
+
+### Rough valuation formulas from `profitable`
+
+You can only multiply a metric by a multiple if the denominator matches.
+
+#### 1. ARR multiple
+
+This is already built into the gem:
+
+```ruby
+# Example: 6x ARR
+Profitable.estimated_arr_valuation(multiple: 6).to_readable
+```
+
+Use this when:
+
+- your business is strongly recurring,
+- churn and retention are solid,
+- and you want a run-rate-based heuristic.
+
+#### 2. TTM revenue multiple
+
+This is useful when buyers care more about trailing actuals than annualized run-rate:
+
+```ruby
+ttm_revenue_cents = Profitable.ttm_revenue.to_i
+
+low_estimate_cents  = (ttm_revenue_cents * 2.0).round
+high_estimate_cents = (ttm_revenue_cents * 4.0).round
+```
+
+Use this when:
+
+- the business has meaningful one-time revenue,
+- profit is thin because you are reinvesting,
+- or the buyer is thinking in revenue-band terms.
+
+#### 2b. Recent revenue run-rate multiple
+
+This is the closest match to TrustMRR-style marketplace multiples:
+
+```ruby
+# Default: annualized last-30-days revenue
+Profitable.revenue_run_rate.to_readable
+Profitable.estimated_revenue_run_rate_valuation(2.7).to_readable
+```
+
+Use this when:
+
+- you're comparing against TrustMRR listings,
+- the market is quoting a multiple on recent revenue rather than ARR,
+- and you want the denominator to match the marketplace comp.
+
+#### 3. TTM profit multiple
+
+`profitable` cannot calculate this yet because it does not know your costs.
+
+```ruby
+# You need to compute this outside of profitable:
+ttm_profit_cents = your_ttm_profit_cents
+
+low_estimate_cents  = (ttm_profit_cents * 3.5).round
+high_estimate_cents = (ttm_profit_cents * 4.35).round
+```
+
+Use this when:
+
+- the business is a smaller profitable micro-SaaS,
+- the buyer is focused on ROI and cash flow,
+- or you're comparing yourself to Acquire.com-style marketplace comps.
+
 ## Development
 
 After checking out the repo, install dependencies:

data/app/controllers/profitable/dashboard_controller.rb

@@ -4,6 +4,7 @@ module Profitable
       @mrr = Profitable.mrr
       @mrr_growth_rate = Profitable.mrr_growth_rate
       @total_customers = Profitable.total_customers
+      @ttm_revenue = Profitable.ttm_revenue
       @all_time_revenue = Profitable.all_time_revenue
       @estimated_valuation = Profitable.estimated_valuation
       @average_revenue_per_customer = Profitable.average_revenue_per_customer

data/app/views/profitable/dashboard/index.html.erb

@@ -53,6 +53,10 @@
       <h2><%= @mrr.to_readable %></h2>
       <p>MRR</p>
     </div>
+    <div class="card">
+      <h2><%= @ttm_revenue.to_readable %></h2>
+      <p>TTM revenue</p>
+    </div>
     <div class="card">
       <h2><%= @estimated_valuation.to_readable %></h2>
       <p>Valuation at 3x ARR</p>

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/profitable",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

data/lib/profitable/json_helpers.rb

@@ -7,8 +7,9 @@ module Profitable
     VALID_TABLE_COLUMN_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_.]*\z/
     VALID_JSON_KEY_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
 
-    # Returns the appropriate JSON extraction syntax for the current database adapter
-    # Supports PostgreSQL, MySQL (5.7.9+), and SQLite
+    # Returns the appropriate JSON extraction syntax for the current database adapter,
+    # always yielding a TEXT-typed value so comparisons behave identically everywhere.
+    # Supports PostgreSQL, MySQL (5.7.9+), and SQLite.
     #
     # @param table_column [String] The table and column name (e.g., 'pay_charges.object')
     # @param json_key [String] The JSON key to extract (e.g., 'paid', 'status')
@@ -25,7 +26,7 @@ module Profitable
     #
     # @example SQLite
     #   json_extract('pay_charges.object', 'paid')
-    #   # => "json_extract(pay_charges.object, '$.paid')"
+    #   # => "CAST(json_extract(pay_charges.object, '$.paid') AS TEXT)"
     def json_extract(table_column, json_key)
       # Validate inputs to prevent SQL injection
       validate_table_column!(table_column)
@@ -41,7 +42,9 @@ module Profitable
         # We use JSON_UNQUOTE(JSON_EXTRACT()) for maximum compatibility
         "JSON_UNQUOTE(JSON_EXTRACT(#{table_column}, '$.#{json_key}'))"
       when /sqlite/
-        "json_extract(#{table_column}, '$.#{json_key}')"
+        # SQLite returns JSON booleans as integers (0/1), unlike ->> on
+        # PostgreSQL/MySQL which return text. CAST keeps the adapters in sync.
+        "CAST(json_extract(#{table_column}, '$.#{json_key}') AS TEXT)"
       else
         # Fallback to PostgreSQL syntax for unknown adapters
         Rails.logger.warn("Unknown database adapter '#{adapter}' for JSON extraction. Falling back to PostgreSQL syntax.")