profitable 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db964563468a5d97aba1c885e241da6c9938c01a4e5bc491448effdd492fcb82
-  data.tar.gz: d8cc7bc12503aaabf2572841632d3d83c629258aa8b7727233a72c6f48f2f5f1
+  metadata.gz: 589bf3accd7eb5a430b00a724b1419ec8f1091bde38b86debdd1e996b8608371
+  data.tar.gz: 80402781b526c6bccc9b452034d3cabcd445d82adc1e85076f899ec4201bdcb8
 SHA512:
-  metadata.gz: bc7391cee28cb2e0b11c7e29583fb2651e4a35e34199f04c142322d2b7dad436f42b1523c3299b6f8a38988b376a753ef6ef7f5c5367213a262ea754b01148ef
-  data.tar.gz: '08d67a50ca5b2b9f20202b6fc77802e2abd8249aca8a670377080c2c37759c5175b4d886f8a0ebd7031eccf61e4eab730606491fd88d483008f46a0ccefb8da0'
+  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,25 @@
 # `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`

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,23 +28,18 @@ 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.
 
-Current MRR processor coverage is verified for `stripe`, `braintree`, `paddle_billing`, and `paddle_classic`.
-
 For Stripe, metered subscription items are intentionally excluded from fixed run-rate metrics like `mrr`, `arr`, `new_mrr`, and `churned_mrr`.
 
 > [!IMPORTANT]
-> `profitable` does **not** yet normalize MRR for every processor that `pay` supports.
-> If a subscription comes from an unsupported processor such as `lemon_squeezy`, it will currently contribute `0` to processor-adapter-dependent metrics until an adapter is added.
+> 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:
 >
-> Verified processor-adapter coverage today:
-> - `stripe`
-> - `braintree`
-> - `paddle_billing`
-> - `paddle_classic`
+> - **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 primarily on `Pay::Charge` and generic subscription lifecycle fields are much more portable across processors, including `all_time_revenue`, `revenue_in_period`, `ttm_revenue`, `revenue_run_rate`, customer counts, subscriber counts, and churn calculations.
+> 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
 
@@ -71,6 +66,7 @@ All methods return numbers that can be converted to a nicely-formatted, human-re
 ### Revenue metrics
 
 - `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
@@ -118,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"
 
@@ -170,6 +169,8 @@ Revenue methods are net of refunds when `amount_refunded` is present on `pay_cha
 
 ### 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.
 

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.")

data/lib/profitable/metrics.rb

@@ -4,9 +4,16 @@ module Profitable
   # Pay exposes some processor-specific status variants beyond the core generic list.
   # We normalize them into business-meaningful groups so current-state metrics,
   # historical event metrics, and churn denominators all behave consistently.
+  #
+  # - Trial statuses bill nothing until the trial actually ends (Stripe: trialing,
+  #   Lemon Squeezy: on_trial).
+  # - Churned statuses stop billing at ends_at (Stripe: canceled, Paddle Classic:
+  #   deleted, Braintree/Lemon Squeezy: expired, legacy Pay: ended/cancelled).
+  # - Never-billable statuses either failed to start billing (Stripe: incomplete,
+  #   incomplete_expired, unpaid) or have not started billing yet (Braintree: pending).
   TRIAL_SUBSCRIPTION_STATUSES = ['trialing', 'on_trial'].freeze
-  CHURNED_STATUSES  = ['canceled', 'cancelled', 'ended', 'deleted'].freeze
-  NEVER_BILLABLE_SUBSCRIPTION_STATUSES = ['incomplete', 'incomplete_expired', 'unpaid'].freeze
+  CHURNED_STATUSES  = ['canceled', 'cancelled', 'ended', 'deleted', 'expired'].freeze
+  NEVER_BILLABLE_SUBSCRIPTION_STATUSES = ['incomplete', 'incomplete_expired', 'unpaid', 'pending'].freeze
 
   class << self
     include ActionView::Helpers::NumberHelper
@@ -22,6 +29,11 @@ module Profitable
       NumericResult.new(MrrCalculator.calculate)
     end
 
+    # Historical MRR snapshot from subscriptions that were billable at the given date.
+    def mrr_at(date)
+      NumericResult.new(calculate_mrr_at(date))
+    end
+
     # Annual Recurring Revenue (ARR) based on the current recurring base.
     # This is today's MRR annualized, not historical 12-month revenue.
     def arr
@@ -63,7 +75,7 @@ module Profitable
       NumericResult.new(calculate_recurring_revenue_percentage(in_the_last), :percentage)
     end
 
-    def revenue_run_rate(in_the_last: 30.days)
+    def revenue_run_rate(in_the_last: DEFAULT_PERIOD)
       NumericResult.new(calculate_revenue_run_rate(in_the_last))
     end
 
@@ -83,7 +95,7 @@ module Profitable
       NumericResult.new(calculate_estimated_valuation_from(ttm_revenue.to_i, actual_multiplier))
     end
 
-    def estimated_revenue_run_rate_valuation(multiplier = nil, at: nil, multiple: nil, in_the_last: 30.days)
+    def estimated_revenue_run_rate_valuation(multiplier = nil, at: nil, multiple: nil, in_the_last: DEFAULT_PERIOD)
       actual_multiplier = multiplier || at || multiple || 3
       NumericResult.new(calculate_estimated_valuation_from(revenue_run_rate(in_the_last:).to_i, actual_multiplier))
     end
@@ -148,25 +160,7 @@ module Profitable
     end
 
     def time_to_next_mrr_milestone
-      current_mrr = (mrr.to_i) / 100  # Convert cents to dollars
-      return "Unable to calculate. No MRR yet." if current_mrr <= 0
-
-      next_milestone = MRR_MILESTONES.find { |milestone| milestone > current_mrr }
-      return "Congratulations! You've reached the highest milestone." unless next_milestone
-
-      monthly_growth_rate = calculate_mrr_growth_rate / 100
-      return "Unable to calculate. Need more data or positive growth." if monthly_growth_rate <= 0
-
-      # Convert monthly growth rate to daily growth rate
-      daily_growth_rate = (1 + monthly_growth_rate) ** (1.0 / 30) - 1
-      return "Unable to calculate. Growth rate too small." if daily_growth_rate <= 0
-
-      # Calculate the number of days to reach the next milestone
-      days_to_milestone = (Math.log(next_milestone.to_f / current_mrr) / Math.log(1 + daily_growth_rate)).ceil
-
-      target_date = Time.current + days_to_milestone.days
-
-      "#{days_to_milestone} days left to $#{number_with_delimiter(next_milestone)} MRR (#{target_date.strftime('%b %d, %Y')})"
+      NumericResult.new(calculate_time_to_next_mrr_milestone, :string)
     end
 
     def monthly_summary(months: 12)
@@ -198,10 +192,23 @@ module Profitable
       'COALESCE(pay_subscriptions.trial_ends_at, pay_subscriptions.created_at)'
     end
 
+    # A subscription only ever counts as billable if it ended AFTER billing started.
+    # Canceled trials never satisfy this: Pay normalizes trial_ends_at down to the
+    # end date on ended Stripe subscriptions (ends_at == trial_ends_at), and Paddle
+    # leaves a stale future trial_ends_at (ends_at < trial_ends_at). The strict
+    # `>` is intentional: equality means the subscription never had a billable
+    # interval for metric purposes, even if those timestamps share a second
+    # (for example, ends_at == trial_ends_at on an immediately canceled trial).
+    # This single predicate keeps never-converted trials out of subscriber counts,
+    # new/churned MRR, churn rates, and the dashboard summaries.
+    def subscription_was_billable_before_ending_sql
+      "(pay_subscriptions.ends_at IS NULL OR pay_subscriptions.ends_at > #{subscription_became_billable_at_sql})"
+    end
+
     # We intentionally do not reuse Pay::Subscription.active here.
     # Pay's active scope is access-oriented and can include free-trial access,
     # while profitable needs billable subscription semantics for metrics.
-    def subscription_is_billable_by(date, scope = Pay::Subscription.all)
+    def subscription_has_billable_lifecycle_by(date, scope = Pay::Subscription.all)
       scope
         .where.not(status: NEVER_BILLABLE_SUBSCRIPTION_STATUSES)
         .where(
@@ -213,6 +220,11 @@ module Profitable
           "(pay_subscriptions.status NOT IN (?) OR pay_subscriptions.ends_at IS NOT NULL)",
           CHURNED_STATUSES
         )
+        .where(subscription_was_billable_before_ending_sql)
+    end
+
+    def subscription_is_billable_by(date, scope = Pay::Subscription.all)
+      subscription_has_billable_lifecycle_by(date, scope)
         .where(
           "(pay_subscriptions.status != ? OR pay_subscriptions.pause_starts_at IS NOT NULL)",
           'paused'
@@ -222,7 +234,7 @@ module Profitable
     # Any subscription that has ever crossed into a paid/billable state,
     # even if it later churned. This is used for "ever" style counts.
     def ever_billable_subscription_scope(scope = Pay::Subscription.all)
-      subscription_is_billable_by(Time.current, scope)
+      subscription_has_billable_lifecycle_by(Time.current, scope)
         .where("#{subscription_became_billable_at_sql} <= ?", Time.current)
     end
 
@@ -244,44 +256,76 @@ module Profitable
     # Historical "new subscriber" / "new MRR" event window.
     # The event date is when billing starts, not when the subscription record is created.
     def billable_subscription_events_in_period(period_start, period_end, scope = Pay::Subscription.all)
-      subscription_is_billable_by(period_end, scope)
+      subscription_has_billable_lifecycle_by(period_end, scope)
         .where("#{subscription_became_billable_at_sql} BETWEEN ? AND ?", period_start, period_end)
     end
 
+    # Churn events: subscriptions whose billing actually stopped inside the window.
+    # Pay stores the moment access/billing ends on ends_at. The billable-before-ending
+    # guard keeps canceled trials (which never paid) from showing up as churn.
+    def churned_subscription_events_in_period(period_start, period_end, scope = Pay::Subscription.all)
+      scope
+        .where(status: CHURNED_STATUSES)
+        .where(ends_at: period_start..period_end)
+        .where(subscription_was_billable_before_ending_sql)
+    end
+
     def subscription_became_billable_at(subscription)
       subscription.trial_ends_at || subscription.created_at
     end
 
+    # Full fixed monthly value of every subscription in the scope.
+    # find_each keeps memory flat on large datasets.
+    def mrr_sum(scope)
+      subscriptions_with_processor(scope).find_each.sum do |subscription|
+        MrrCalculator.process_subscription(subscription)
+      end
+    end
+
     def paid_charges
-      # Pay gem v10+ stores charge data in `object` column, older versions used `data`
-      # We check both columns for backwards compatibility using database-agnostic JSON extraction
+      # Stripe charges (the only processor Pay stores raw payloads for) carry
+      # `paid` and `status` keys we filter on. Charges from other processors have
+      # neither key, so they pass through the IS NULL branches — Pay only syncs
+      # their successful transactions in the first place.
       #
       # Performance note: The COALESCE pattern may prevent index usage on some databases.
       # This is an acceptable tradeoff for backwards compatibility with Pay < 10.
       # For high-volume scenarios, consider adding a composite index or upgrading to Pay 10+
       # where only the `object` column is used.
+      paid = charge_json_value_sql('paid')
+      status = charge_json_value_sql('status')
 
-      # Build JSON extraction SQL for both object and data columns
-      paid_object = json_extract('pay_charges.object', 'paid')
-      paid_data = json_extract('pay_charges.data', 'paid')
-      status_object = json_extract('pay_charges.object', 'status')
-      status_data = json_extract('pay_charges.data', 'status')
-
+      # JSON booleans surface as 'false'/'true' on PostgreSQL/MySQL but as
+      # text-cast integers '0'/'1' on SQLite, so we exclude both spellings.
       Pay::Charge
         .where("pay_charges.amount > 0")
-        .where(<<~SQL.squish, 'false', 'succeeded')
-          (
-            (COALESCE(#{paid_object}, #{paid_data}) IS NULL
-             OR COALESCE(#{paid_object}, #{paid_data}) != ?)
-          )
+        .where(<<~SQL.squish, 'false', '0', 'succeeded')
+          (#{paid} IS NULL OR #{paid} NOT IN (?, ?))
           AND
-          (
-            COALESCE(#{status_object}, #{status_data}) = ?
-            OR COALESCE(#{status_object}, #{status_data}) IS NULL
-          )
+          (#{status} = ? OR #{status} IS NULL)
         SQL
     end
 
+    # Pay gem v10+ stores charge payloads in the `object` column, older versions
+    # used `data`. Real Pay 7-9 schemas do not have an `object` column, so only
+    # reference columns that are actually present in the host app.
+    def charge_json_value_sql(key)
+      extractions = charge_payload_columns.map { |column| json_extract("pay_charges.#{column}", key) }
+
+      case extractions.length
+      when 0
+        'NULL'
+      when 1
+        extractions.first
+      else
+        "COALESCE(#{extractions.join(', ')})"
+      end
+    end
+
+    def charge_payload_columns
+      @charge_payload_columns ||= %w[object data].select { |column| Pay::Charge.column_names.include?(column) }
+    end
+
     # Revenue metrics should reflect net cash collected, not gross billed amounts.
     # When Pay stores refunded cents on the charge, subtract them from revenue.
     def net_revenue(scope)
@@ -297,11 +341,7 @@ module Profitable
     end
 
     def calculate_arr
-      (mrr.to_f * 12).round
-    end
-
-    def calculate_estimated_valuation(multiplier = 3)
-      calculate_estimated_valuation_from(calculate_arr, multiplier)
+      mrr.to_i * 12
     end
 
     def calculate_estimated_valuation_from(base_amount, multiplier = 3)
@@ -356,7 +396,7 @@ module Profitable
     def calculate_recurring_revenue_in_period(period)
       net_revenue(
         paid_charges
-          .joins('INNER JOIN pay_subscriptions ON pay_charges.subscription_id = pay_subscriptions.id')
+          .joins(:subscription)
           .where(created_at: period.ago..Time.current)
       )
     end
@@ -441,6 +481,15 @@ module Profitable
       new_mrr - churned_mrr
     end
 
+    def calculate_mrr_at(date)
+      # Find subscriptions that were active AT the given date:
+      # - Started billing before or on that date
+      # - Not ended before that date (ends_at is nil OR ends_at > date)
+      # - Not paused at that date
+      # - Not still in a free trial at that date
+      mrr_sum(billable_subscription_scope_at(date))
+    end
+
     def calculate_mrr_growth_rate(period = DEFAULT_PERIOD)
       end_date = Time.current
       start_date = end_date - period
@@ -452,17 +501,26 @@ module Profitable
       ((end_mrr.to_f - start_mrr) / start_mrr * 100).round(2)
     end
 
-    def calculate_mrr_at(date)
-      # Find subscriptions that were active AT the given date:
-      # - Started billing before or on that date
-      # - Not ended before that date (ends_at is nil OR ends_at > date)
-      # - Not paused at that date
-      # - Not still in a free trial at that date
-      subscriptions_with_processor(
-        billable_subscription_scope_at(date)
-      ).sum do |subscription|
-        MrrCalculator.process_subscription(subscription)
-      end
+    def calculate_time_to_next_mrr_milestone
+      current_mrr = mrr.to_f / 100  # Convert cents to dollars
+      return "Unable to calculate. No MRR yet." if current_mrr <= 0
+
+      next_milestone = MRR_MILESTONES.find { |milestone| milestone > current_mrr }
+      return "Congratulations! You've reached the highest milestone." unless next_milestone
+
+      monthly_growth_rate = calculate_mrr_growth_rate / 100
+      return "Unable to calculate. Need more data or positive growth." if monthly_growth_rate <= 0
+
+      # Convert monthly growth rate to daily growth rate
+      daily_growth_rate = (1 + monthly_growth_rate) ** (1.0 / 30) - 1
+      return "Unable to calculate. Growth rate too small." if daily_growth_rate <= 0
+
+      # Calculate the number of days to reach the next milestone
+      days_to_milestone = (Math.log(next_milestone.to_f / current_mrr) / Math.log(1 + daily_growth_rate)).ceil
+
+      target_date = Time.current + days_to_milestone.days
+
+      "#{days_to_milestone} days left to $#{number_with_delimiter(next_milestone)} MRR (#{target_date.strftime('%b %d, %Y')})"
     end
 
     def calculate_period_data(period)
@@ -480,7 +538,7 @@ module Profitable
       # Churn rate (reuses churned_count)
       total_at_start = billable_subscription_scope_at(period_start)
         .distinct
-        .count('customer_id')
+        .count(:customer_id)
       churn_rate = total_at_start > 0 ? (churned_count.to_f / total_at_start * 100).round(1) : 0
 
       {
@@ -497,18 +555,17 @@ module Profitable
     # Batched: loads all data in 5 queries then groups by month in Ruby
     def calculate_monthly_summary(months_count)
       overall_start = (months_count - 1).months.ago.beginning_of_month
-      overall_end = Time.current.end_of_month
+      # Events cannot exist in the future: a trial scheduled to convert later
+      # this month is not a new subscriber yet, so the window is capped at now.
+      overall_end = Time.current
 
       # Bulk load all data for the full range, then group in Ruby.
       # This keeps the dashboard query count low while preserving the same
       # billable-date semantics used by the single-metric helpers.
-      new_sub_records = Pay::Subscription
-        .merge(billable_subscription_events_in_period(overall_start, overall_end))
+      new_sub_records = billable_subscription_events_in_period(overall_start, overall_end)
         .pluck(:customer_id, Arel.sql(subscription_became_billable_at_sql))
 
-      churned_sub_records = Pay::Subscription
-        .where(status: CHURNED_STATUSES)
-        .where(ends_at: overall_start..overall_end)
+      churned_sub_records = churned_subscription_events_in_period(overall_start, overall_end)
         .pluck(:customer_id, :ends_at)
 
       new_mrr_subs = subscriptions_with_processor(
@@ -516,14 +573,16 @@ module Profitable
       ).to_a
 
       churned_mrr_subs = subscriptions_with_processor(
-        Pay::Subscription
-          .where(status: CHURNED_STATUSES)
-          .where(ends_at: overall_start..overall_end)
+        churned_subscription_events_in_period(overall_start, overall_end)
       ).to_a
 
-      churn_base_records = billable_subscription_scope_at(overall_end, Pay::Subscription)
+      # The churn denominator needs every subscription that was billable at each
+      # month's start — including ones that churned later inside the window — so
+      # the end-date and pause cutoffs are evaluated per month in Ruby, not in SQL.
+      churn_base_records = subscription_is_billable_by(overall_end)
+        .where("#{subscription_became_billable_at_sql} <= ?", overall_end)
         .where('pay_subscriptions.ends_at IS NULL OR pay_subscriptions.ends_at > ?', overall_start)
-        .pluck(:customer_id, Arel.sql(subscription_became_billable_at_sql), :ends_at)
+        .pluck(:customer_id, Arel.sql(subscription_became_billable_at_sql), :ends_at, :pause_starts_at)
 
       # Group by month in Ruby using billable-at and ends_at as the event dates,
       # rather than raw subscription created_at.
@@ -533,7 +592,7 @@ module Profitable
         month_end = month_start.end_of_month
 
         new_count = new_sub_records
-          .select { |_, created_at| created_at >= month_start && created_at <= month_end }
+          .select { |_, became_billable_at| became_billable_at >= month_start && became_billable_at <= month_end }
           .map(&:first).uniq.count
 
         churned_count = churned_sub_records
@@ -549,7 +608,11 @@ module Profitable
           .sum { |s| MrrCalculator.process_subscription(s) }
 
         total_at_start = churn_base_records
-          .select { |_, billable_at, ends_at| billable_at < month_start && (ends_at.nil? || ends_at > month_start) }
+          .select do |_, billable_at, ends_at, pause_starts_at|
+            billable_at <= month_start &&
+              (ends_at.nil? || ends_at > month_start) &&
+              (pause_starts_at.nil? || pause_starts_at > month_start)
+          end
           .map(&:first).uniq.count
 
         churn_rate = total_at_start > 0 ? (churned_count.to_f / total_at_start * 100).round(1) : 0
@@ -573,17 +636,15 @@ module Profitable
     # Batched: loads all data in 2 queries then groups by day in Ruby
     def calculate_daily_summary(days_count)
       overall_start = (days_count - 1).days.ago.beginning_of_day
-      overall_end = Time.current.end_of_day
+      # Capped at now so trials scheduled to convert later today do not count yet.
+      overall_end = Time.current
 
       # Daily summary intentionally uses the same "became billable" event date as
       # new_subscribers/new_mrr, so trial starts do not appear as paid conversions.
-      new_sub_records = Pay::Subscription
-        .merge(billable_subscription_events_in_period(overall_start, overall_end))
+      new_sub_records = billable_subscription_events_in_period(overall_start, overall_end)
         .pluck(:customer_id, Arel.sql(subscription_became_billable_at_sql))
 
-      churned_sub_records = Pay::Subscription
-        .where(status: CHURNED_STATUSES)
-        .where(ends_at: overall_start..overall_end)
+      churned_sub_records = churned_subscription_events_in_period(overall_start, overall_end)
         .pluck(:customer_id, :ends_at)
 
       summary = []
@@ -592,7 +653,7 @@ module Profitable
         day_end = day_start.end_of_day
 
         new_count = new_sub_records
-          .select { |_, created_at| created_at >= day_start && created_at <= day_end }
+          .select { |_, became_billable_at| became_billable_at >= day_start && became_billable_at <= day_end }
           .map(&:first).uniq.count
 
         churned_count = churned_sub_records
@@ -617,34 +678,21 @@ module Profitable
     end
 
     def calculate_churned_subscribers_in_period(period_start, period_end)
-      # Churn happens when access/billing actually ends, which Pay stores on ends_at.
-      Pay::Subscription
-        .where(status: CHURNED_STATUSES)
-        .where(ends_at: period_start..period_end)
+      churned_subscription_events_in_period(period_start, period_end)
         .distinct
-        .count('customer_id')
+        .count(:customer_id)
     end
 
     def calculate_new_mrr_in_period(period_start, period_end)
       # New MRR is the full fixed monthly value of subscriptions whose billing
       # started in the window. It is not prorated, and it still counts if the
       # subscription churns later in the same period.
-      subscriptions_with_processor(
-        billable_subscription_events_in_period(period_start, period_end)
-      ).sum do |subscription|
-        MrrCalculator.process_subscription(subscription)
-      end
+      mrr_sum(billable_subscription_events_in_period(period_start, period_end))
     end
 
     def calculate_churned_mrr_in_period(period_start, period_end)
       # Churned MRR is the full fixed monthly value being lost at churn time.
-      subscriptions_with_processor(
-        Pay::Subscription
-          .where(status: CHURNED_STATUSES)
-          .where(ends_at: period_start..period_end)
-      ).sum do |subscription|
-        MrrCalculator.process_subscription(subscription)
-      end
+      mrr_sum(churned_subscription_events_in_period(period_start, period_end))
     end
 
     def calculate_churn_rate_for_period(period_start, period_end)
@@ -652,7 +700,7 @@ module Profitable
       # This keeps free trials and not-yet-paying subscriptions out of the denominator.
       total_subscribers_start = billable_subscription_scope_at(period_start)
         .distinct
-        .count('customer_id')
+        .count(:customer_id)
 
       churned = calculate_churned_subscribers_in_period(period_start, period_end)
       return 0 if total_subscribers_start == 0

data/lib/profitable/mrr_calculator.rb

@@ -6,40 +6,13 @@ require_relative 'processors/paddle_classic_processor'
 
 module Profitable
   class MrrCalculator
+    # Current MRR is just the historical MRR snapshot taken right now.
+    # The billable-subscription query lives in Profitable's metrics module so
+    # current MRR, MRR-at-date, and growth rates can never drift apart.
     def self.calculate
-      total_mrr = 0
-
-      # Do not use Pay::Subscription.active here.
-      # Pay's active scope is designed for entitlement/access checks and can include
-      # free-trial access. MRR needs subscriptions that are billable right now.
-      subscriptions = Pay::Subscription
-        .where.not(status: Profitable::NEVER_BILLABLE_SUBSCRIPTION_STATUSES)
-        .where(
-          "(pay_subscriptions.status NOT IN (?) OR (pay_subscriptions.trial_ends_at IS NOT NULL AND pay_subscriptions.trial_ends_at <= ?))",
-          Profitable::TRIAL_SUBSCRIPTION_STATUSES,
-          Time.current
-        )
-        .where(
-          "(pay_subscriptions.status NOT IN (?) OR pay_subscriptions.ends_at IS NOT NULL)",
-          Profitable::CHURNED_STATUSES
-        )
-        .where(
-          "(pay_subscriptions.status != ? OR pay_subscriptions.pause_starts_at IS NOT NULL)",
-          'paused'
-        )
-        .where('COALESCE(pay_subscriptions.trial_ends_at, pay_subscriptions.created_at) <= ?', Time.current)
-        .where('pay_subscriptions.pause_starts_at IS NULL OR pay_subscriptions.pause_starts_at > ?', Time.current)
-        .where('pay_subscriptions.ends_at IS NULL OR pay_subscriptions.ends_at > ?', Time.current)
-        .includes(:customer)
-        .select('pay_subscriptions.*, pay_customers.processor as customer_processor')
-        .joins(:customer)
-
-      subscriptions.find_each do |subscription|
-        mrr = process_subscription(subscription)
-        total_mrr += mrr if mrr.is_a?(Numeric) && mrr > 0
-      end
-
-      total_mrr
+      Profitable.mrr_at(Time.current).to_i
+    rescue Profitable::Error
+      raise
     rescue => e
       Rails.logger.error("Error calculating total MRR: #{e.message}")
       raise Profitable::Error, "Failed to calculate MRR: #{e.message}"
@@ -62,15 +35,16 @@ module Profitable
       0
     end
 
-    # Pay gem v10+ stores Stripe objects in the `object` column,
-    # while older versions used `data`. This method provides backwards compatibility.
     def self.subscription_data(subscription)
-      subscription.try(:object) || subscription.try(:data)
+      Processors::Base.subscription_data(subscription)
     end
 
     def self.processor_for(processor_name)
-      # MRR parsing is only implemented for processors with explicit adapters below.
-      # Unknown processors safely fall back to Base and contribute zero until supported.
+      # MRR parsing needs the processor's price payload stored locally, which Pay
+      # only does for Stripe (in `object` on Pay v10+, `data` before that).
+      # The remaining adapters only apply when that payload has been backfilled by
+      # the application; otherwise unknown or payload-less subscriptions safely
+      # contribute zero instead of guessing.
       case processor_name
       when 'stripe'
         Processors::StripeProcessor

data/lib/profitable/numeric_result.rb

@@ -1,3 +1,6 @@
+require "delegate"
+require "action_view"
+
 module Profitable
   class NumericResult < SimpleDelegator
     include ActionView::Helpers::NumberHelper

data/lib/profitable/processors/base.rb

@@ -3,6 +3,12 @@ module Profitable
     class Base
       attr_reader :subscription
 
+      # Pay gem v10+ stores processor payloads in the `object` column,
+      # while older versions used `data`. Single source of truth for that fallback.
+      def self.subscription_data(subscription)
+        subscription.try(:object) || subscription.try(:data)
+      end
+
       def initialize(subscription)
         @subscription = subscription
       end
@@ -13,10 +19,8 @@ module Profitable
 
       protected
 
-      # Pay gem v10+ stores Stripe objects in the `object` column,
-      # while older versions used `data`. This method provides backwards compatibility.
       def subscription_data
-        subscription.try(:object) || subscription.try(:data)
+        self.class.subscription_data(subscription)
       end
 
       # Converts a billing amount to its monthly equivalent rate.

data/lib/profitable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Profitable
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/profitable.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
+# Third-party dependencies must load before the metrics module: NumericResult
+# mixes in ActionView helpers and metrics use ActiveSupport durations at
+# definition time.
+require "pay"
+require "active_support/time"
+require "active_support/core_ext/numeric/conversions"
+require "active_support/core_ext/string/filters"
+require "action_view"
+
 require_relative "profitable/version"
 require_relative "profitable/error"
 require_relative "profitable/engine"
-
 require_relative "profitable/mrr_calculator"
 require_relative "profitable/numeric_result"
 require_relative "profitable/json_helpers"
-
-require "pay"
-require "active_support/core_ext/numeric/conversions"
-require "action_view"
-
 require_relative "profitable/metrics"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: profitable
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-03-19 00:00:00.000000000 Z
+date: 2026-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pay
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
 description: Calculate SaaS metrics like the MRR, ARR, churn, LTV, ARPU, total revenue,
   estimated valuation, and other business metrics of your `pay`-powered Rails app
   – and display them in a simple dashboard.