profitable 0.2.3 → 0.4.0

data/lib/profitable.rb

@@ -6,14 +6,20 @@ 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"
 
 module Profitable
+  # Subscription status constants (at module level so MrrCalculator can reference them)
+  EXCLUDED_STATUSES = ['trialing', 'paused'].freeze
+  CHURNED_STATUSES  = ['canceled', 'ended'].freeze
+
   class << self
     include ActionView::Helpers::NumberHelper
+    include Profitable::JsonHelpers
 
     DEFAULT_PERIOD = 30.days
     MRR_MILESTONES = [5, 10, 20, 30, 50, 75, 100, 200, 300, 400, 500, 1_000, 2_000, 3_000, 5_000, 10_000, 20_000, 30_000, 50_000, 83_333, 100_000, 250_000, 500_000, 1_000_000, 5_000_000, 10_000_000, 25_000_000, 50_000_000, 75_000_000, 100_000_000]
@@ -100,7 +106,9 @@ module Profitable
     end
 
     def time_to_next_mrr_milestone
-      current_mrr = (mrr.to_i)/100
+      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
 
@@ -109,6 +117,7 @@ module Profitable
 
       # 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
@@ -118,11 +127,56 @@ module Profitable
       "#{days_to_milestone} days left to $#{number_with_delimiter(next_milestone)} MRR (#{target_date.strftime('%b %d, %Y')})"
     end
 
+    def monthly_summary(months: 12)
+      calculate_monthly_summary(months)
+    end
+
+    def daily_summary(days: 30)
+      calculate_daily_summary(days)
+    end
+
+    def period_data(in_the_last: DEFAULT_PERIOD)
+      calculate_period_data(in_the_last)
+    end
+
     private
 
+    # Helper to load subscriptions with processor info from customer
+    def subscriptions_with_processor(scope = Pay::Subscription.all)
+      scope
+        .includes(:customer)
+        .select('pay_subscriptions.*, pay_customers.processor as customer_processor')
+        .joins(:customer)
+    end
+
     def paid_charges
-      Pay::Charge.where("(pay_charges.data ->> 'paid' IS NULL OR pay_charges.data ->> 'paid' != ?) AND pay_charges.amount > 0", 'false')
-                 .where("pay_charges.data ->> 'status' = ? OR pay_charges.data ->> 'status' IS NULL", 'succeeded')
+      # 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
+      #
+      # 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.
+
+      # 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')
+
+      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}) != ?)
+          )
+          AND
+          (
+            COALESCE(#{status_object}, #{status_data}) = ?
+            OR COALESCE(#{status_object}, #{status_data}) IS NULL
+          )
+        SQL
     end
 
     def calculate_all_time_revenue
@@ -154,71 +208,19 @@ module Profitable
     end
 
     def calculate_churn(period = DEFAULT_PERIOD)
-      start_date = period.ago
-      total_subscribers_start = Pay::Subscription.active.where('created_at < ?', start_date).distinct.count('customer_id')
-      churned = calculate_churned_customers(period)
-      return 0 if total_subscribers_start == 0
-      (churned.to_f / total_subscribers_start * 100).round(2)
-    end
-
-    def churned_subscriptions(period = DEFAULT_PERIOD)
-      Pay::Subscription
-        .includes(:customer)
-        .select('pay_subscriptions.*, pay_customers.processor as customer_processor')
-        .joins(:customer)
-        .where(status: ['canceled', 'ended'])
-        .where(ends_at: period.ago..Time.current)
+      calculate_churn_rate_for_period(period.ago, Time.current)
     end
 
     def calculate_churned_customers(period = DEFAULT_PERIOD)
-      churned_subscriptions(period).distinct.count('customer_id')
+      calculate_churned_subscribers_in_period(period.ago, Time.current)
     end
 
     def calculate_churned_mrr(period = DEFAULT_PERIOD)
-      start_date = period.ago
-      end_date = Time.current
-
-      Pay::Subscription
-        .includes(:customer)
-        .select('pay_subscriptions.*, pay_customers.processor as customer_processor')
-        .joins(:customer)
-        .where(status: ['canceled', 'ended'])
-        .where('pay_subscriptions.updated_at BETWEEN ? AND ?', start_date, end_date)
-        .sum do |subscription|
-          if subscription.ends_at && subscription.ends_at > end_date
-            # Subscription ends in the future, don't count it as churned yet
-            0
-          else
-            # Calculate prorated MRR if the subscription ended within the period
-            end_date = [subscription.ends_at, end_date].compact.min
-            days_in_period = (end_date - start_date).to_i
-            total_days = (subscription.current_period_end - subscription.current_period_start).to_i
-            prorated_days = [days_in_period, total_days].min
-
-            mrr = MrrCalculator.process_subscription(subscription)
-            (mrr.to_f * prorated_days / total_days).round
-          end
-        end
+      calculate_churned_mrr_in_period(period.ago, Time.current)
     end
 
     def calculate_new_mrr(period = DEFAULT_PERIOD)
-      start_date = period.ago
-      end_date = Time.current
-
-      Pay::Subscription
-        .active
-        .includes(:customer)
-        .select('pay_subscriptions.*, pay_customers.processor as customer_processor')
-        .joins(:customer)
-        .where(created_at: start_date..end_date)
-        .where.not(status: ['trialing', 'paused'])
-        .sum do |subscription|
-          mrr = MrrCalculator.process_subscription(subscription)
-          days_in_period = (end_date - subscription.created_at).to_i
-          total_days = (subscription.current_period_end - subscription.current_period_start).to_i
-          prorated_days = [days_in_period, total_days].min
-          (mrr.to_f * prorated_days / total_days).round
-        end
+      calculate_new_mrr_in_period(period.ago, Time.current)
     end
 
     def calculate_revenue_in_period(period)
@@ -271,10 +273,7 @@ module Profitable
     end
 
     def calculate_new_subscribers(period)
-      Pay::Customer.joins(:subscriptions)
-                   .where(created_at: period.ago..Time.current)
-                   .distinct
-                   .count
+      calculate_new_subscribers_in_period(period.ago, Time.current)
     end
 
     def calculate_average_revenue_per_customer
@@ -284,10 +283,16 @@ module Profitable
     end
 
     def calculate_lifetime_value
-      return 0 if total_customers.zero?
-      churn_rate = churn.to_f / 100
+      # LTV = Monthly ARPU / Monthly Churn Rate
+      # where ARPU (Average Revenue Per User) = MRR / active subscribers
+      subscribers = calculate_active_subscribers
+      return 0 if subscribers.zero?
+
+      monthly_arpu = mrr.to_f / subscribers  # in cents
+      churn_rate = churn.to_f / 100  # monthly churn as decimal (e.g., 5% = 0.05)
       return 0 if churn_rate.zero?
-      (average_revenue_per_customer.to_f / churn_rate).round
+
+      (monthly_arpu / churn_rate).round  # LTV in cents
     end
 
     def calculate_mrr_growth(period = DEFAULT_PERIOD)
@@ -308,16 +313,218 @@ module Profitable
     end
 
     def calculate_mrr_at(date)
+      # Find subscriptions that were active AT the given date:
+      # - Created before or on that date
+      # - Not ended before that date (ends_at is nil OR ends_at > date)
+      # - Not paused at that date
+      # - Not in trialing status (trials don't count as MRR)
+      subscriptions_with_processor(
+        Pay::Subscription
+          .where('pay_subscriptions.created_at <= ?', date)
+          .where('pay_subscriptions.ends_at IS NULL OR pay_subscriptions.ends_at > ?', date)
+          .where('pay_subscriptions.pause_starts_at IS NULL OR pay_subscriptions.pause_starts_at > ?', date)
+          .where.not(status: EXCLUDED_STATUSES)
+      ).sum do |subscription|
+        MrrCalculator.process_subscription(subscription)
+      end
+    end
+
+    def calculate_period_data(period)
+      period_start = period.ago
+      period_end = Time.current
+
+      new_customers_count = actual_customers.where(created_at: period_start..period_end).count
+      churned_count = calculate_churned_subscribers_in_period(period_start, period_end)
+      new_mrr_val = calculate_new_mrr_in_period(period_start, period_end)
+      churned_mrr_val = calculate_churned_mrr_in_period(period_start, period_end)
+      revenue_val = paid_charges.where(created_at: period_start..period_end).sum(:amount)
+
+      # Churn rate (reuses churned_count)
+      total_at_start = Pay::Subscription
+        .where('pay_subscriptions.created_at < ?', period_start)
+        .where('pay_subscriptions.ends_at IS NULL OR pay_subscriptions.ends_at > ?', period_start)
+        .where.not(status: EXCLUDED_STATUSES)
+        .distinct
+        .count('customer_id')
+      churn_rate = total_at_start > 0 ? (churned_count.to_f / total_at_start * 100).round(1) : 0
+
+      {
+        new_customers: NumericResult.new(new_customers_count, :integer),
+        churned_customers: NumericResult.new(churned_count, :integer),
+        churn: NumericResult.new(churn_rate, :percentage),
+        new_mrr: NumericResult.new(new_mrr_val),
+        churned_mrr: NumericResult.new(churned_mrr_val),
+        mrr_growth: NumericResult.new(new_mrr_val - churned_mrr_val),
+        revenue: NumericResult.new(revenue_val)
+      }
+    end
+
+    # 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
+
+      # Bulk load all data for the full range
+      new_sub_records = Pay::Subscription
+        .where(created_at: overall_start..overall_end)
+        .where.not(status: EXCLUDED_STATUSES)
+        .pluck(:customer_id, :created_at)
+
+      churned_sub_records = Pay::Subscription
+        .where(status: CHURNED_STATUSES)
+        .where(ends_at: overall_start..overall_end)
+        .pluck(:customer_id, :ends_at)
+
+      new_mrr_subs = subscriptions_with_processor(
+        Pay::Subscription
+          .where(status: 'active')
+          .where(created_at: overall_start..overall_end)
+      ).to_a
+
+      churned_mrr_subs = subscriptions_with_processor(
+        Pay::Subscription
+          .where(status: CHURNED_STATUSES)
+          .where(ends_at: overall_start..overall_end)
+      ).to_a
+
+      churn_base_records = Pay::Subscription
+        .where('pay_subscriptions.created_at < ?', overall_end)
+        .where('pay_subscriptions.ends_at IS NULL OR pay_subscriptions.ends_at > ?', overall_start)
+        .where.not(status: EXCLUDED_STATUSES)
+        .pluck(:customer_id, :created_at, :ends_at)
+
+      # Group by month in Ruby
+      summary = []
+      (months_count - 1).downto(0) do |months_ago|
+        month_start = months_ago.months.ago.beginning_of_month
+        month_end = month_start.end_of_month
+
+        new_count = new_sub_records
+          .select { |_, created_at| created_at >= month_start && created_at <= month_end }
+          .map(&:first).uniq.count
+
+        churned_count = churned_sub_records
+          .select { |_, ends_at| ends_at >= month_start && ends_at <= month_end }
+          .map(&:first).uniq.count
+
+        new_mrr_amount = new_mrr_subs
+          .select { |s| s.created_at >= month_start && s.created_at <= month_end }
+          .sum { |s| MrrCalculator.process_subscription(s) }
+
+        churned_mrr_amount = churned_mrr_subs
+          .select { |s| s.ends_at >= month_start && s.ends_at <= month_end }
+          .sum { |s| MrrCalculator.process_subscription(s) }
+
+        total_at_start = churn_base_records
+          .select { |_, created_at, ends_at| created_at < month_start && (ends_at.nil? || ends_at > month_start) }
+          .map(&:first).uniq.count
+
+        churn_rate = total_at_start > 0 ? (churned_count.to_f / total_at_start * 100).round(1) : 0
+
+        summary << {
+          month: month_start.strftime('%Y-%m'),
+          month_date: month_start,
+          new_subscribers: new_count,
+          churned_subscribers: churned_count,
+          net_subscribers: new_count - churned_count,
+          new_mrr: new_mrr_amount,
+          churned_mrr: churned_mrr_amount,
+          net_mrr: new_mrr_amount - churned_mrr_amount,
+          churn_rate: churn_rate
+        }
+      end
+
+      summary
+    end
+
+    # 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
+
+      new_sub_records = Pay::Subscription
+        .where(created_at: overall_start..overall_end)
+        .where.not(status: EXCLUDED_STATUSES)
+        .pluck(:customer_id, :created_at)
+
+      churned_sub_records = Pay::Subscription
+        .where(status: CHURNED_STATUSES)
+        .where(ends_at: overall_start..overall_end)
+        .pluck(:customer_id, :ends_at)
+
+      summary = []
+      (days_count - 1).downto(0) do |days_ago|
+        day_start = days_ago.days.ago.beginning_of_day
+        day_end = day_start.end_of_day
+
+        new_count = new_sub_records
+          .select { |_, created_at| created_at >= day_start && created_at <= day_end }
+          .map(&:first).uniq.count
+
+        churned_count = churned_sub_records
+          .select { |_, ends_at| ends_at >= day_start && ends_at <= day_end }
+          .map(&:first).uniq.count
+
+        summary << {
+          date: day_start.to_date,
+          new_subscribers: new_count,
+          churned_subscribers: churned_count
+        }
+      end
+
+      summary
+    end
+
+    # Consolidated methods that work with any date range
+    def calculate_new_subscribers_in_period(period_start, period_end)
+      Pay::Customer.joins(:subscriptions)
+                   .where(pay_subscriptions: { created_at: period_start..period_end })
+                   .where.not(pay_subscriptions: { status: EXCLUDED_STATUSES })
+                   .distinct
+                   .count
+    end
+
+    def calculate_churned_subscribers_in_period(period_start, period_end)
       Pay::Subscription
-        .active
-        .where('pay_subscriptions.created_at <= ?', date)
-        .where.not(status: ['trialing', 'paused'])
-        .includes(:customer)
-        .select('pay_subscriptions.*, pay_customers.processor as customer_processor')
-        .joins(:customer)
-        .sum do |subscription|
-          MrrCalculator.process_subscription(subscription)
-        end
+        .where(status: CHURNED_STATUSES)
+        .where(ends_at: period_start..period_end)
+        .distinct
+        .count('customer_id')
+    end
+
+    def calculate_new_mrr_in_period(period_start, period_end)
+      subscriptions_with_processor(
+        Pay::Subscription
+          .where(status: 'active')
+          .where(created_at: period_start..period_end)
+      ).sum do |subscription|
+        MrrCalculator.process_subscription(subscription)
+      end
+    end
+
+    def calculate_churned_mrr_in_period(period_start, period_end)
+      subscriptions_with_processor(
+        Pay::Subscription
+          .where(status: CHURNED_STATUSES)
+          .where(ends_at: period_start..period_end)
+      ).sum do |subscription|
+        MrrCalculator.process_subscription(subscription)
+      end
+    end
+
+    def calculate_churn_rate_for_period(period_start, period_end)
+      # Count subscribers who were active AT the start of the period
+      total_subscribers_start = Pay::Subscription
+        .where('pay_subscriptions.created_at < ?', period_start)
+        .where('pay_subscriptions.ends_at IS NULL OR pay_subscriptions.ends_at > ?', period_start)
+        .where.not(status: EXCLUDED_STATUSES)
+        .distinct
+        .count('customer_id')
+
+      churned = calculate_churned_subscribers_in_period(period_start, period_end)
+      return 0 if total_subscribers_start == 0
+
+      (churned.to_f / total_subscribers_start * 100).round(1)
     end
 
   end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: profitable
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.4.0
 platform: ruby
 authors:
 - rameerez
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-01 00:00:00.000000000 Z
+date: 2026-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pay
@@ -47,7 +46,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".simplecov"
+- AGENTS.md
+- Appraisals
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -56,9 +59,17 @@ files:
 - app/views/layouts/profitable/application.html.erb
 - app/views/profitable/dashboard/index.html.erb
 - config/routes.rb
+- gemfiles/pay_10.0.gemfile
+- gemfiles/pay_11.0.gemfile
+- gemfiles/pay_7.3.gemfile
+- gemfiles/pay_8.3.gemfile
+- gemfiles/pay_9.0.gemfile
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.1.gemfile
 - lib/profitable.rb
 - lib/profitable/engine.rb
 - lib/profitable/error.rb
+- lib/profitable/json_helpers.rb
 - lib/profitable/mrr_calculator.rb
 - lib/profitable/numeric_result.rb
 - lib/profitable/processors/base.rb
@@ -76,8 +87,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/rameerez/profitable
   source_code_uri: https://github.com/rameerez/profitable
-  changelog_uri: https://github.com/rameerez/profitable
-post_install_message:
+  changelog_uri: https://github.com/rameerez/profitable/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -92,8 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Calculate the MRR, ARR, churn, LTV, ARPU, total revenue & est. valuation
   of your `pay`-powered Rails SaaS