usage_credits 0.1.0

data/lib/generators/usage_credits/templates/create_usage_credits_tables.rb.erb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+class CreateUsageCreditsTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :usage_credits_wallets, id: primary_key_type do |t|
+      t.references :owner, polymorphic: true, null: false, type: foreign_key_type
+      t.integer :balance, null: false, default: 0
+      t.send(json_column_type, :metadata, null: false, default: {})
+
+      t.timestamps
+    end
+
+    create_table :usage_credits_transactions, id: primary_key_type do |t|
+      t.references :wallet, null: false, type: foreign_key_type
+      t.integer :amount, null: false
+      t.string :category, null: false
+      t.datetime :expires_at
+      t.references :fulfillment, type: foreign_key_type
+      t.send(json_column_type, :metadata, null: false, default: {})
+
+      t.timestamps
+    end
+
+    create_table :usage_credits_fulfillments, id: primary_key_type do |t|
+      t.references :wallet, null: false, type: foreign_key_type
+      t.references :source, polymorphic: true, type: foreign_key_type
+      t.integer :credits_last_fulfillment, null: false    # Credits given in last fulfillment
+      t.string :fulfillment_type, null: false             # What kind of fulfillment is this? (credit_pack / subscription)
+      t.datetime :last_fulfilled_at                       # When last fulfilled
+      t.datetime :next_fulfillment_at                     # When to fulfill next (nil if stopped/completed)
+      t.string :fulfillment_period                        # "2.months", "15.days", etc. (nil for one-time)
+      t.datetime :stops_at                                # When to stop performing fulfillments
+      t.send(json_column_type, :metadata, null: false, default: {})
+
+      t.timestamps
+    end
+
+    # Allocations are the basis for the bucket-based, FIFO with expiration inventory-like system
+    create_table :usage_credits_allocations, id: primary_key_type do |t|
+      # The "spend" transaction (negative) that is *using* credits
+      t.references :transaction, null: false, type: foreign_key_type,
+                                 foreign_key: { to_table: :usage_credits_transactions },
+                                 index: { name: "index_allocations_on_transaction_id" }
+
+      # The "source" transaction (positive) from which the credits are drawn
+      t.references :source_transaction, null: false, type: foreign_key_type,
+                                        foreign_key: { to_table: :usage_credits_transactions },
+                                        index: { name: "index_allocations_on_source_transaction_id" }
+
+      # How many credits were allocated from that particular source
+      t.integer :amount, null: false
+
+      t.timestamps
+    end
+
+    # Add indexes
+    add_index :usage_credits_transactions, :category
+    add_index :usage_credits_transactions, :expires_at
+
+    # Composite index on (expires_at, id) for efficient ordering when calculating balances
+    add_index :usage_credits_transactions, [:expires_at, :id], name: 'index_transactions_on_expires_at_and_id'
+
+    # Index on wallet_id and amount to speed up queries filtering by wallet and positive amounts
+    add_index :usage_credits_transactions, [:wallet_id, :amount], name: 'index_transactions_on_wallet_id_and_amount'
+
+    add_index :usage_credits_allocations, [:transaction_id, :source_transaction_id], name: "index_allocations_on_tx_and_source_tx"
+
+    add_index :usage_credits_fulfillments, :next_fulfillment_at
+    add_index :usage_credits_fulfillments, :fulfillment_type
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [primary_key_type, foreign_key_type]
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?('postgresql')
+    :json
+  end
+end 

data/lib/generators/usage_credits/templates/initializer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+UsageCredits.configure do |config|
+  #
+  # Define your credit-consuming operations below
+  #
+  # Example:
+  #
+  # operation :send_email do
+  #   costs 1.credit
+  # end
+  #
+  # operation :process_image do
+  #   costs 10.credits + 1.credit_per(:mb)
+  #   validate ->(params) { params[:size] <= 100.megabytes }, "File too large"
+  # end
+  #
+  # operation :generate_ai_response do
+  #   costs 5.credits
+  #   validate ->(params) { params[:prompt].length <= 1000 }, "Prompt too long"
+  #   meta category: :ai, description: "Generate AI response"
+  # end
+  #
+  # operation :process_items do
+  #   costs 1.credit_per(:units)  # Cost per item processed
+  #   meta category: :batch, description: "Process items in batch"
+  # end
+  #
+  #
+  #
+  # Example credit packs (uncomment and modify as needed):
+  #
+  # credit_pack :tiny do
+  #   gives 100.credits
+  #   costs 99.cents # Price can be in cents or dollars
+  # end
+  #
+  # credit_pack :starter do
+  #   gives 1000.credits
+  #   bonus 100.credits  # Optional bonus credits
+  #   costs 49.dollars
+  # end
+  #
+  # credit_pack :pro do
+  #   gives 5000.credits
+  #   bonus 1000.credits
+  #   costs 199.dollars
+  # end
+  #
+  #
+  #
+  # Example subscription plans (uncomment and modify as needed):
+  #
+  # subscription_plan :basic do
+  #   gives 1000.credits.every(:month)
+  #   signup_bonus 100.credits
+  #   unused_credits :expire  # Credits reset each month
+  # end
+  #
+  # subscription_plan :pro do
+  #   gives 10_000.credits.every(:month)
+  #   signup_bonus 1_000.credits
+  #   trial_includes 500.credits
+  #   unused_credits :expire  # Credits expire at the end of the fulfillment period (use :rollover to roll over to next period)
+  # end
+  #
+  #
+  #
+  # Alert when balance drops below this threshold (default: 100 credits)
+  # Set to nil to disable low balance alerts
+  #
+  # config.low_balance_threshold = 100.credits
+  #
+  #
+  # Handle low credit balance alerts – Useful to sell booster credit packs, for example
+  #
+  # config.on_low_balance do |user|
+    # Send notification to user when their balance drops below the threshold
+    # UserMailer.low_credits_alert(user).deliver_later
+  # end
+  #
+  #
+  #
+  # For how long expiring credits from the previous fulfillment cycle will "overlap" the following fulfillment period.
+  # During this time, old credits from the previous period will erroneously count as available balance.
+  # But if we set this to 0 or nil, user balance will show up as zero some time until the next fulfillment cycle hits.
+  # A good default is to match the frequency of your UsageCredits::FulfillmentJob
+  # fulfillment_grace_period = 5.minutes
+  #
+  #
+  #
+  # Rounding strategy for credit calculations (default: :ceil)
+  # :ceil - Always round up (2.1 => 3)
+  # :floor - Always round down (2.9 => 2)
+  # :round - Standard rounding (2.4 => 2, 2.6 => 3)
+  #
+  # config.rounding_strategy = :ceil
+  #
+  #
+  # Format credits for display (default: "X credits")
+  #
+  # config.format_credits do |amount|
+  #   "#{amount} credits"
+  # end
+end

data/lib/usage_credits/configuration.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Configuration for the UsageCredits gem. This is the single source of truth for all settings.
+  # This is what turns what's defined in the initializer DSL into actual objects we can use and operate with.
+  class Configuration
+    VALID_ROUNDING_STRATEGIES = [:ceil, :floor, :round].freeze
+    VALID_CURRENCIES = [:usd, :eur, :gbp, :sgd, :chf].freeze
+
+    # =========================================
+    # Core Data Stores
+    # =========================================
+
+    # Stores all the things users can do with credits
+    attr_reader :operations
+
+    # Stores all the things users can buy or subscribe to
+    attr_reader :credit_packs
+    attr_reader :credit_subscription_plans
+
+    # =========================================
+    # Basic Settings
+    # =========================================
+
+    attr_reader :default_currency
+
+    attr_reader :rounding_strategy
+
+    attr_reader :credit_formatter
+
+    attr_accessor :fulfillment_grace_period
+
+    # =========================================
+    # Low balance
+    # =========================================
+
+    attr_accessor :allow_negative_balance
+
+    attr_reader :low_balance_threshold
+
+    attr_reader :low_balance_callback
+
+    def initialize
+      # Initialize empty data stores
+      @operations = {}                  # Credit-consuming operations (e.g., "send_email: 1 credit")
+      @credit_packs = {}                # One-time purchases (e.g., "100 credits for $49")
+      @credit_subscription_plans = {}   # Recurring plans (e.g., "1000 credits/month for $99")
+
+      # Set sensible defaults
+      @default_currency = :usd
+      @rounding_strategy = :ceil  # Always round up to ensure we never undercharge
+      @credit_formatter = ->(amount) { "#{amount} credits" }  # How to format credit amounts in the UI
+
+      # Grace period for credit expiration after fulfillment period ends.
+      # For how long will expiring credits "overlap" the following fulfillment period.
+      # This ensures smooth transition between fulfillment periods.
+      # For this amount of time, old, already expired credits will be erroneously counted as available in the user's balance.
+      # Keep it short enough that users don't notice they have the last period's credits still available, but
+      # long enough that there's a smooth transition and users never get zero credits in between fullfillment periods
+      # A good setting is to match the frequency of your UsageCredits::FulfillmentJob runs
+      @fulfillment_grace_period = 5.minutes # If you run your fulfillment job every 5 minutes, this should be enough
+
+      @allow_negative_balance = false
+      @low_balance_threshold = nil
+      @low_balance_callback = nil # Called when user hits low_balance_threshold
+    end
+
+    # =========================================
+    # DSL Methods for Defining Things
+    # =========================================
+
+    # Define a credit-consuming operation
+    def operation(name, &block)
+      raise ArgumentError, "Block is required for operation definition" unless block_given?
+      operation = Operation.new(name)
+      operation.instance_eval(&block)
+      @operations[name.to_sym] = operation
+      operation
+    end
+
+    # Define a one-time purchase credit pack
+    def credit_pack(name, &block)
+      raise ArgumentError, "Block is required for credit pack definition" unless block_given?
+      raise ArgumentError, "Credit pack name can't be blank" if name.blank?
+
+      name = name.to_sym
+      pack = CreditPack.new(name)
+      pack.instance_eval(&block)
+      pack.validate!
+      @credit_packs[name] = pack
+    end
+
+    # Define a recurring subscription plan
+    def subscription_plan(name, &block)
+      raise ArgumentError, "Block is required for subscription plan definition" unless block_given?
+      raise ArgumentError, "Subscription plan name can't be blank" if name.blank?
+
+      name = name.to_sym
+      plan = CreditSubscriptionPlan.new(name)
+      plan.instance_eval(&block)
+      plan.validate!
+      @credit_subscription_plans[name] = plan
+    end
+
+    # Find a subscription plan by its processor-specific ID
+    def find_subscription_plan_by_processor_id(processor_id)
+      @credit_subscription_plans.values.find do |plan|
+        plan.processor_plan_ids.values.include?(processor_id)
+      end
+    end
+
+    # =========================================
+    # Configuration Setters
+    # =========================================
+
+    # Set default currency with validation
+    def default_currency=(value)
+      value = value.to_s.downcase.to_sym
+      unless VALID_CURRENCIES.include?(value)
+        raise ArgumentError, "Invalid currency. Must be one of: #{VALID_CURRENCIES.join(', ')}"
+      end
+      @default_currency = value
+    end
+
+    # Set low balance threshold with validation
+    def low_balance_threshold=(value)
+      if value
+        value = value.to_i
+        raise ArgumentError, "Low balance threshold must be greater than or equal to zero" if value.negative?
+      end
+      @low_balance_threshold = value
+    end
+
+    # Set rounding strategy with validation
+    def rounding_strategy=(strategy)
+      strategy = strategy.to_sym if strategy.respond_to?(:to_sym)
+      unless VALID_ROUNDING_STRATEGIES.include?(strategy)
+        strategy = :ceil  # Default to ceiling if invalid
+      end
+      @rounding_strategy = strategy
+    end
+
+    def fulfillment_grace_period=(value)
+      if value.nil? || value&.to_i == 0
+        @fulfillment_grace_period = 1.second
+        return
+      end
+
+      unless value.is_a?(ActiveSupport::Duration)
+        raise ArgumentError, "Fulfillment grace period must be an ActiveSupport::Duration (e.g. 1.day, 7.minutes)"
+      end
+
+      @fulfillment_grace_period = value
+    end
+
+    # =========================================
+    # Callback & Formatter Configuration
+    # =========================================
+
+    # Set how credits are displayed in the UI
+    def format_credits(&block)
+      @credit_formatter = block
+    end
+
+    # Set what happens when credits are low
+    def on_low_balance(&block)
+      raise ArgumentError, "Block is required for low balance callback" unless block_given?
+      @low_balance_callback = block
+    end
+
+    # =========================================
+    # Validation
+    # =========================================
+
+    # Ensure configuration is valid
+    def validate!
+      validate_currency!
+      validate_threshold!
+      validate_rounding_strategy!
+      true
+    end
+
+    private
+
+    def validate_currency!
+      raise ArgumentError, "Default currency can't be blank" if default_currency.blank?
+      unless VALID_CURRENCIES.include?(default_currency.to_s.downcase.to_sym)
+        raise ArgumentError, "Invalid currency. Must be one of: #{VALID_CURRENCIES.join(', ')}"
+      end
+    end
+
+    def validate_threshold!
+      if @low_balance_threshold && @low_balance_threshold.negative?
+        raise ArgumentError, "Low balance threshold must be greater than or equal to zero"
+      end
+    end
+
+    def validate_rounding_strategy!
+      unless VALID_ROUNDING_STRATEGIES.include?(@rounding_strategy)
+        raise ArgumentError, "Invalid rounding strategy. Must be one of: #{VALID_ROUNDING_STRATEGIES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/usage_credits/core_ext/numeric.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/numeric"
+
+# This is what allows us to write things like `3.credits` in the DSL
+# Then the actual cost gets calculated in the UsageCredits::Cost classes
+# (Cost::Base, Cost::Fixed, Cost::Variable, Cost::Compound, etc.)
+class Numeric
+  def credits
+    raise ArgumentError, "Credit amount must be a whole number (decimals are not allowed)" unless self == self.to_i
+    raise ArgumentError, "Credit amount cannot be negative" if self.negative?
+    UsageCredits::Cost::Fixed.new(self.to_i)
+  end
+  alias_method :credit, :credits
+
+  def credits_per(unit)
+    raise ArgumentError, "Credit cost rate must be a whole number (decimals are not allowed)" unless self == self.to_i
+
+    # Convert common units to their base unit
+    unit = case unit.to_s.downcase
+           when "mb", "megabyte", "megabytes"
+             :mb
+           when "kb", "kilobyte", "kilobytes"
+             :kb
+           when "gb", "gigabyte", "gigabytes"
+             :gb
+           when "unit", "units"
+             :units
+           else
+             unit.to_sym
+           end
+
+    UsageCredits::Cost::Variable.new(self, unit)
+  end
+  alias_method :credit_per, :credits_per
+
+  def dollars
+    self * 100 # Convert to cents for payment processors
+  end
+  alias_method :dollar, :dollars
+  alias_method :euro, :dollars
+  alias_method :euros, :dollars
+  alias_method :pound, :dollars
+  alias_method :pounds, :dollars
+
+  def cents
+    self
+  end
+  alias_method :cent, :cents
+end
+
+# This is what allows us to write .credit amounts as Procs, like:
+#   cost ->(params) { 2 * params[:variable] }.credits
+class Proc
+  def credits
+    UsageCredits::Cost::Fixed.new(self)
+  end
+  alias_method :credit, :credits
+end

data/lib/usage_credits/cost/base.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  module Cost
+    # Base class for all credit cost calculations.
+    # Subclasses implement different ways of calculating credit costs:
+    # - Fixed: Simple fixed amount
+    # - Variable: Amount based on units (MB, etc)
+    # - Compound: Multiple costs added together
+    class Base
+      attr_reader :amount
+
+      def initialize(amount)
+        validate_amount!(amount) unless amount.is_a?(Proc)
+        @amount = amount
+      end
+
+      def +(other)
+        case other
+        when Fixed, Variable
+          Compound.new(self, other)
+        else
+          raise ArgumentError, "Cannot add #{other.class} to #{self.class}"
+        end
+      end
+
+      def to_i
+        calculate({})
+      end
+
+      protected
+
+      def validate_amount!(amount)
+        unless amount == amount.to_i
+          raise ArgumentError, "Credit amount must be a whole number (got: #{amount})"
+        end
+        if amount.negative?
+          raise ArgumentError, "Credit amount cannot be negative (got: #{amount})"
+        end
+      end
+    end
+  end
+end

data/lib/usage_credits/cost/compound.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  module Cost
+    # Compound credit cost that adds multiple costs together
+    # Example: base cost + per MB cost
+    class Compound < Base
+      attr_reader :costs
+
+      def initialize(*costs)
+        @costs = costs.flatten
+      end
+
+      def calculate(params = {})
+        total = costs.sum { |cost| cost.calculate(params) }
+        CreditCalculator.apply_rounding(total)
+      end
+
+      def +(other)
+        case other
+        when Fixed, Variable
+          self.class.new(costs + [other])
+        else
+          raise ArgumentError, "Cannot add #{other.class} to #{self.class}"
+        end
+      end
+    end
+
+    def self.credits(amount)
+      Fixed.new(amount)
+    end
+
+    class_eval do
+      singleton_class.alias_method :credit, :credits
+    end
+  end
+end

data/lib/usage_credits/cost/fixed.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  module Cost
+    # Fixed credit cost (e.g., always costs 10 credits)
+    class Fixed < Base
+      attr_reader :period
+
+      def initialize(amount)
+        @amount = amount
+        @period = nil  # Will default to 1.month in CreditSubscriptionPlan
+      end
+
+      def calculate(params = {})
+        value = amount.is_a?(Proc) ? amount.call(params) : amount
+        case value
+        when UsageCredits::Cost::Fixed
+          value.calculate(params)
+        else
+          validate_amount!(value)
+          value.to_i
+        end
+      end
+
+      # Set the recurring period for subscription plans
+      # @param period [Symbol, ActiveSupport::Duration, nil] The period (e.g., :month, 2.months, 15.days)
+      # @return [self]
+      def every(period = nil)
+        @period = period  # nil will default to 1.month in CreditSubscriptionPlan
+        self
+      end
+    end
+  end
+end

data/lib/usage_credits/cost/variable.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  module Cost
+    # Variable credit cost based on units (e.g., 1 credit per MB)
+    class Variable < Base
+      attr_reader :unit
+
+      def initialize(amount, unit)
+        super(amount)
+        @unit = unit.to_sym
+      end
+
+      def calculate(params = {})
+        size = extract_size(params)
+        raw_cost = amount * size
+        CreditCalculator.apply_rounding(raw_cost)
+      end
+
+      private
+
+      def extract_size(params)
+        case unit
+        when :mb
+          # First check for direct MB value
+          if params[:mb]
+            CreditCalculator.apply_rounding(params[:mb].to_f)
+          # Then check for bytes that need conversion
+          elsif params[:size]
+            CreditCalculator.apply_rounding(params[:size].to_f / 1.megabyte)
+          else
+            0
+          end
+        when :units
+          CreditCalculator.apply_rounding(params.fetch(:units, 0).to_f)
+        else
+          raise ArgumentError, "Unknown unit: #{unit}"
+        end
+      end
+    end
+  end
+end

data/lib/usage_credits/engine.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Rails engine for UsageCredits
+  class Engine < ::Rails::Engine
+    isolate_namespace UsageCredits
+
+    # Ensure our models load first
+    config.autoload_paths << File.expand_path("../models", __dir__)
+    config.autoload_paths << File.expand_path("../models/concerns", __dir__)
+
+    # Set up autoloading paths
+    initializer "usage_credits.autoload", before: :set_autoload_paths do |app|
+      app.config.autoload_paths << root.join("lib")
+      app.config.autoload_paths << root.join("lib/usage_credits/models")
+      app.config.autoload_paths << root.join("lib/usage_credits/models/concerns")
+    end
+
+    # Add has_credits method to ActiveRecord::Base
+    initializer "usage_credits.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        extend UsageCredits::HasWallet::ClassMethods
+      end
+    end
+
+    initializer "usage_credits.pay_integration" do
+      ActiveSupport.on_load(:pay) do
+        Pay::Subscription.include UsageCredits::PaySubscriptionExtension
+        Pay::Charge.include UsageCredits::PayChargeExtension
+      end
+    end
+
+    initializer "usage_credits.configs" do
+      # Initialize any config settings
+    end
+  end
+end

data/lib/usage_credits/helpers/credit_calculator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Centralized credit calculations used throughout the gem.
+  # This ensures consistent rounding and credit math everywhere.
+  module CreditCalculator
+    module_function
+
+    # Apply the configured rounding strategy to a credit amount
+    # Always defaults to ceiling to ensure we never undercharge
+    def apply_rounding(amount)
+      case UsageCredits.configuration.rounding_strategy
+      when :round
+        amount.round
+      when :floor
+        amount.floor
+      when :ceil
+        amount.ceil
+      else
+        amount.ceil # Default to ceiling to never undercharge
+      end
+    end
+
+    # Convert a monetary amount to credits
+    def money_to_credits(cents, exchange_rate)
+      apply_rounding(cents * exchange_rate / 100.0)
+    end
+
+    # Convert credits to a monetary amount
+    def credits_to_money(credits, exchange_rate)
+      apply_rounding(credits * 100.0 / exchange_rate)
+    end
+  end
+end