usage_credits 0.1.0

data/lib/usage_credits/models/wallet.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # A Wallet manages credit balance and transactions for a user/owner.
+  #
+  # It's responsible for:
+  #   1. Tracking credit balance
+  #   2. Performing credit operations (add/deduct)
+  #   3. Managing credit expiration
+  #   4. Handling low balance alerts
+
+  class Wallet < ApplicationRecord
+    self.table_name = "usage_credits_wallets"
+
+    # =========================================
+    # Associations & Validations
+    # =========================================
+
+    belongs_to :owner, polymorphic: true
+    has_many :transactions, class_name: "UsageCredits::Transaction", dependent: :destroy
+    has_many :fulfillments, class_name: "UsageCredits::Fulfillment", dependent: :destroy
+
+    validates :balance, numericality: { greater_than_or_equal_to: 0 }, unless: :allow_negative_balance?
+
+    # =========================================
+    # Credit Balance & History
+    # =========================================
+
+    # Get current credit balance
+    #
+    # The first naive approach was to compute this as a sum of all non-expired transactions like:
+    #   transactions.not_expired.sum(:amount)
+    # but that fails when we mix expiring and non-expiring credits: https://x.com/rameerez/status/1884246492837302759
+    #
+    # So we needed to introduce the Allocation model
+    #
+    # Now to calculate current balance, instead of summing:
+    # we sum only unexpired positive transactions’ remaining_amount
+    def credits
+      # Sum the leftover in all *positive* transactions that haven't expired
+      transactions
+        .where("amount > 0")
+        .where("expires_at IS NULL OR expires_at > ?", Time.current)
+        .sum("amount - (SELECT COALESCE(SUM(amount), 0) FROM usage_credits_allocations WHERE source_transaction_id = usage_credits_transactions.id)")
+        .yield_self { |sum| [sum, 0].max }.to_i
+    end
+
+    # Get transaction history (oldest first)
+    def credit_history
+      transactions.order(created_at: :asc)
+    end
+
+    # =========================================
+    # Credit Operations
+    # =========================================
+
+    # Check if wallet has enough credits for an operation
+    def has_enough_credits_to?(operation_name, **params)
+      operation = find_and_validate_operation(operation_name, params)
+
+      # Then check if we actually have enough credits
+      credits >= operation.calculate_cost(params)
+    rescue InvalidOperation => e
+      raise e
+    rescue StandardError => e
+      raise InvalidOperation, "Error checking credits: #{e.message}"
+    end
+
+    # Calculate how many credits an operation would cost
+    def estimate_credits_to(operation_name, **params)
+      operation = find_and_validate_operation(operation_name, params)
+
+      # Then calculate the cost
+      operation.calculate_cost(params)
+    rescue InvalidOperation => e
+      raise e
+    rescue StandardError => e
+      raise InvalidOperation, "Error estimating cost: #{e.message}"
+    end
+
+    # Spend credits on an operation
+    # @param operation_name [Symbol] The operation to perform
+    # @param params [Hash] Parameters for the operation
+    # @yield Optional block that must succeed before credits are deducted
+    def spend_credits_on(operation_name, **params)
+      operation = find_and_validate_operation(operation_name, params)
+
+      cost = operation.calculate_cost(params)
+
+      # Check if user has enough credits
+      raise InsufficientCredits, "Insufficient credits (#{credits} < #{cost})" unless has_enough_credits_to?(operation_name, **params)
+
+      # Create audit trail
+      audit_data = operation.to_audit_hash(params)
+      deduct_params = {
+        metadata: audit_data.merge(operation.metadata).merge(
+          "executed_at" => Time.current,
+          "gem_version" => UsageCredits::VERSION
+        ),
+        category: :operation_charge
+      }
+
+      if block_given?
+        # If block given, only deduct credits if it succeeds
+        ActiveRecord::Base.transaction do
+          lock!  # Row-level lock for concurrency safety
+
+          yield  # Perform the operation first
+
+          deduct_credits(cost, **deduct_params)  # Deduct credits only if the block was successful
+        end
+      else
+        deduct_credits(cost, **deduct_params)
+      end
+    rescue StandardError => e
+      raise e
+    end
+
+    # Give credits to the wallet
+    # @param amount [Integer] Number of credits to give
+    # @param reason [String] Why credits were given (for auditing)
+    def give_credits(amount, reason: nil)
+      raise ArgumentError, "Cannot give negative credits" if amount.negative?
+      raise ArgumentError, "Credit amount must be a whole number" unless amount.integer?
+
+      category = case reason&.to_s
+                when "signup" then :signup_bonus
+                when "referral" then :referral_bonus
+                else :manual_adjustment
+                end
+
+      add_credits(
+        amount,
+        metadata: { reason: reason },
+        category: category
+      )
+    end
+
+    # =========================================
+    # Credit Management (Internal API)
+    # =========================================
+
+    # Add credits to the wallet (internal method)
+    def add_credits(amount, metadata: {}, category: :credit_added, expires_at: nil, fulfillment: nil)
+      with_lock do
+        amount = amount.to_i
+        raise ArgumentError, "Cannot add non-positive credits" if amount <= 0
+
+        previous_balance = credits
+
+        transaction = transactions.create!(
+          amount: amount,
+          category: category,
+          expires_at: expires_at,
+          metadata: metadata,
+          fulfillment: fulfillment
+        )
+
+        # Sync the wallet's `balance` column
+        self.balance = credits
+        save!
+
+        notify_balance_change(:credits_added, amount)
+        check_low_balance if !was_low_balance?(previous_balance) && low_balance?
+
+        # To finish, let's return the transaction that has been just created so we can reference it in parts of the code
+        # Useful, for example, to update the transaction's `fulfillment` reference in the subscription extension
+        # after the credits have been awarded and the Fulfillment object has been created, we need to store it
+        return transaction
+      end
+    end
+
+    # Remove credits from the wallet (Internal method)
+    #
+    # After implementing the expiring FIFO inventory-like system through the Allocation model,
+    # we no longer just create one -X transaction. Now we also allocate that spend across whichever
+    # positive transactions still have leftover.
+    #
+    # TODO: This code enumerates all unexpired positive transactions each time.
+    # That’s fine if usage scale is moderate. We're already indexing this.
+    # If performance becomes a concern, we need to create a separate model to store the partial allocations efficiently.
+    def deduct_credits(amount, metadata: {}, category: :credit_deducted)
+    with_lock do
+      amount = amount.to_i
+      raise InsufficientCredits, "Cannot deduct a non-positive amount" if amount <= 0
+
+      # Figure out how many credits are available right now
+      available = credits
+      if amount > available && !allow_negative_balance?
+        raise InsufficientCredits, "Insufficient credits (#{available} < #{amount})"
+      end
+
+      # Create the negative transaction that represents the spend
+      spend_tx = transactions.create!(
+        amount: -amount,
+        category: category,
+        metadata: metadata
+      ) # We'll attach allocations to it next.
+
+      # We now allocate from oldest/soonest-expiring positive transactions
+      remaining_to_deduct = amount
+
+      # 1) Gather all unexpired positives with leftover, order by expire time (soonest first),
+      #    then fallback to any with no expiry (which should come last).
+      positive_txs = transactions
+                      .where("amount > 0")
+                      .where("expires_at IS NULL OR expires_at > ?", Time.current)
+                      .order(Arel.sql("COALESCE(expires_at, '9999-12-31 23:59:59'), id ASC"))
+                      .lock("FOR UPDATE")
+                      .select(:id, :amount, :expires_at)
+                      .to_a
+
+      positive_txs.each do |pt|
+        # Calculate leftover amount for this transaction
+        allocated = pt.incoming_allocations.sum(:amount)
+        leftover = pt.amount - allocated
+        next if leftover <= 0
+
+        allocate_amount = [leftover, remaining_to_deduct].min
+
+        # Create allocation
+        Allocation.create!(
+          spend_transaction: spend_tx,
+          source_transaction: pt,
+          amount: allocate_amount
+        )
+
+        remaining_to_deduct -= allocate_amount
+        break if remaining_to_deduct <= 0
+      end
+
+      # If anything’s still left to deduct (and we allow negative?), we just leave it unallocated
+      # TODO: implement this edge case; typically we'd create an unbacked negative record.
+      if remaining_to_deduct.positive? && allow_negative_balance?
+        # The spend_tx already has -amount, so effectively user goes negative
+        # with no “source bucket” to allocate from. That is an edge case the end user's business logic must handle.
+      elsif remaining_to_deduct.positive?
+        # We shouldn’t get here if InsufficientCredits is raised earlier, but just in case:
+        raise InsufficientCredits, "Not enough credit buckets to cover the deduction"
+      end
+
+      # Keep the `balance` column in sync
+      self.balance = credits
+      save!
+
+      # Fire your existing notifications
+      notify_balance_change(:credits_deducted, amount)
+      spend_tx
+    end
+  end
+
+
+    private
+
+    # =========================================
+    # Helper Methods
+    # =========================================
+
+    # Find an operation and validate its parameters
+    # @param name [Symbol] Operation name
+    # @param params [Hash] Operation parameters to validate
+    # @return [Operation] The validated operation
+    # @raise [InvalidOperation] If operation not found or validation fails
+    def find_and_validate_operation(name, params)
+      operation = UsageCredits.operations[name.to_sym]
+      raise InvalidOperation, "Operation not found: #{name}" unless operation
+      operation.validate!(params)
+      operation
+    end
+
+    def insufficient_credits?(amount)
+      !allow_negative_balance? && amount > credits
+    end
+
+    def allow_negative_balance?
+      UsageCredits.configuration.allow_negative_balance
+    end
+
+    # =========================================
+    # Balance Change Notifications
+    # =========================================
+
+    def notify_balance_change(event, amount)
+      UsageCredits.handle_event(
+        event,
+        wallet: self,
+        amount: amount,
+        balance: credits
+      )
+    end
+
+    def check_low_balance
+      return unless low_balance?
+      UsageCredits.handle_event(:low_balance_reached, wallet: self)
+    end
+
+    def low_balance?
+      threshold = UsageCredits.configuration.low_balance_threshold
+      return false if threshold.nil? || threshold.negative?
+      credits <= threshold
+    end
+
+    def was_low_balance?(previous_balance)
+      threshold = UsageCredits.configuration.low_balance_threshold
+      return false if threshold.nil? || threshold.negative?
+      previous_balance <= threshold
+    end
+  end
+
+end

data/lib/usage_credits/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Railtie for Rails integration
+  class Railtie < Rails::Railtie
+    railtie_name :usage_credits
+
+    # Set up action view helpers if needed
+    initializer "usage_credits.action_view" do
+      ActiveSupport.on_load :action_view do
+        require "usage_credits/helpers/credits_helper"
+        include UsageCredits::CreditsHelper
+      end
+    end
+
+  end
+end

data/lib/usage_credits/services/fulfillment_service.rb

@@ -0,0 +1,129 @@
+# lib/usage_credits/services/fulfillment_service.rb
+module UsageCredits
+  class FulfillmentService
+    def self.process_pending_fulfillments
+      count = 0
+      failed = 0
+
+      Fulfillment.due_for_fulfillment.find_each do |fulfillment|
+        begin
+          new(fulfillment).process
+          count += 1
+        rescue StandardError => e
+          failed += 1
+          Rails.logger.error "Failed to process fulfillment #{fulfillment.id}: #{e.message}"
+          Rails.logger.error e.backtrace.join("\n")
+          next # Continue with next fulfillment
+        end
+      end
+
+      Rails.logger.info "Processed #{count} fulfillments (#{failed} failed)"
+      count
+    end
+
+    def initialize(fulfillment)
+      @fulfillment = fulfillment
+      validate_fulfillment!
+    end
+
+    def process
+      ActiveRecord::Base.transaction do
+        @fulfillment.lock! # row lock to avoid double awarding
+
+        # re-check if it's still due, in case time changed or another process already updated it
+        return unless @fulfillment.due_for_fulfillment?
+
+        credits = calculate_credits
+        give_credits(credits)
+        update_fulfillment(credits)
+      end
+    rescue UsageCredits::Error => e
+      Rails.logger.error "Usage credits error processing fulfillment #{@fulfillment.id}: #{e.message}"
+      raise
+    rescue StandardError => e
+      Rails.logger.error "Unexpected error processing fulfillment #{@fulfillment.id}: #{e.message}"
+      raise
+    end
+
+    private
+
+    def validate_fulfillment!
+      raise UsageCredits::Error, "No fulfillment provided" if @fulfillment.nil?
+      raise UsageCredits::Error, "Invalid fulfillment type" unless ["subscription", "credit_pack", "manual"].include?(@fulfillment.fulfillment_type)
+      raise UsageCredits::Error, "No wallet associated with fulfillment" if @fulfillment.wallet.nil?
+
+      # Validate required metadata based on type
+      case @fulfillment.fulfillment_type
+      when "subscription"
+        raise UsageCredits::Error, "No plan specified in metadata" unless @fulfillment.metadata["plan"].present?
+      when "credit_pack"
+        raise UsageCredits::Error, "No pack specified in metadata" unless @fulfillment.metadata["pack"].present?
+      else
+        raise UsageCredits::Error, "No credits amount specified in metadata" unless @fulfillment.metadata["credits"].present?
+      end
+    end
+
+    def give_credits(credits)
+      @fulfillment.wallet.add_credits(
+        credits,
+        category: fulfillment_category,
+        metadata: fulfillment_metadata,
+        expires_at: calculate_expiration, # Will be nil if rollover is enabled
+        fulfillment: @fulfillment
+      )
+    end
+
+    def update_fulfillment(credits)
+      @fulfillment.update!(
+        last_fulfilled_at: Time.current,
+        credits_last_fulfillment: credits,
+        next_fulfillment_at: @fulfillment.calculate_next_fulfillment
+      )
+    end
+
+    def calculate_credits
+      case @fulfillment.fulfillment_type
+      when "subscription"
+        @plan = UsageCredits.find_subscription_plan_by_processor_id(@fulfillment.metadata["plan"])
+        raise UsageCredits::InvalidOperation, "No subscription plan found for processor ID #{@fulfillment.metadata["plan"]}" unless @plan
+        @plan.credits_per_period
+      when "credit_pack"
+        pack = UsageCredits.find_credit_pack(@fulfillment.metadata["pack"])
+        raise UsageCredits::InvalidOperation, "No credit pack named #{@fulfillment.metadata["pack"]}" unless pack
+        pack.total_credits
+      else
+        @fulfillment.metadata["credits"].to_i
+      end
+    end
+
+    def calculate_expiration
+      return nil unless @fulfillment.fulfillment_type == "subscription" && @plan
+      return nil if @plan.rollover_enabled
+
+      @fulfillment.calculate_next_fulfillment + UsageCredits.configuration.fulfillment_grace_period
+    end
+
+    def fulfillment_category
+      case @fulfillment.fulfillment_type
+      when "subscription" then "subscription_credits"
+      when "credit_pack" then "credit_pack_purchase"
+      else "credit_added"
+      end
+    end
+
+    def fulfillment_metadata
+      base_metadata = {
+        last_fulfilled_at: Time.current,
+        reason: "fulfillment_cycle",
+        fulfillment_period: @fulfillment.fulfillment_period,
+        fulfillment_id: @fulfillment.id
+      }
+
+      if @fulfillment.source.is_a?(Pay::Subscription)
+        base_metadata[:subscription_id] = @fulfillment.source.id
+      end
+
+      @fulfillment.metadata.merge(base_metadata)
+    end
+  end
+end

data/lib/usage_credits/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  VERSION = "0.1.0"
+end

data/lib/usage_credits.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# UsageCredits provides a credits system for your application.
+# This is the entry point to the gem.
+
+require "rails"
+require "active_record"
+require "pay"
+require "active_support/all"
+
+# Load order matters! Dependencies are loaded in this specific order:
+#
+# 1. Core helpers
+require "usage_credits/helpers/credit_calculator"   # Centralized credit rounding
+require "usage_credits/helpers/period_parser"       # Parse fulfillment periods like `:monthly` to `1.month`
+require "usage_credits/core_ext/numeric"            # Numeric extension to write `10.credits` in our DSL
+
+# 2. Cost calculation
+require "usage_credits/cost/base"
+require "usage_credits/cost/fixed"
+require "usage_credits/cost/variable"
+require "usage_credits/cost/compound"
+
+# 3. Model concerns (needed by models)
+require "usage_credits/models/concerns/has_wallet"
+require "usage_credits/models/concerns/pay_subscription_extension"
+require "usage_credits/models/concerns/pay_charge_extension"
+
+# 4. Core functionality
+require "usage_credits/version"
+require "usage_credits/configuration"  # Single source of truth for all configuration in this gem
+
+# 5. Shim Rails classes so requires don't break
+module UsageCredits
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+
+  class ApplicationJob < ActiveJob::Base
+  end
+end
+
+# 6. Models (order matters for dependencies)
+require "usage_credits/models/wallet"
+require "usage_credits/models/transaction"
+require "usage_credits/models/allocation"
+require "usage_credits/models/operation"
+require "usage_credits/models/fulfillment"
+require "usage_credits/models/credit_pack"
+require "usage_credits/models/credit_subscription_plan"
+
+# 7. Jobs
+require "usage_credits/services/fulfillment_service.rb"
+require "usage_credits/jobs/fulfillment_job.rb"
+
+# Main module that serves as the primary interface to the gem.
+# Most methods here delegate to Configuration, which is the single source of truth for all config in the initializer
+module UsageCredits
+  # Custom error classes
+  class Error < StandardError; end
+  class InsufficientCredits < Error; end
+  class InvalidOperation < Error; end
+
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the gem with a block (main entry point)
+    def configure
+      yield(configuration)
+    end
+
+    # Reset configuration to defaults (mainly for testing)
+    def reset!
+      @configuration = nil
+    end
+
+    # DSL methods - all delegate to configuration
+    # These enable things like both `UsageCredits.credit_pack` and bare `credit_pack` usage
+
+    def operation(name, &block)
+      configuration.operation(name, &block)
+    end
+
+    def operations
+      configuration.operations
+    end
+
+    def credit_pack(name, &block)
+      configuration.credit_pack(name, &block)
+    end
+
+    def credit_packs
+      configuration.credit_packs
+    end
+    alias_method :packs, :credit_packs
+
+    def find_credit_pack(name)
+      credit_packs[name.to_sym]
+    end
+    alias_method :find_pack, :find_credit_pack
+
+    def available_credit_packs
+      credit_packs.values.uniq
+    end
+    alias_method :available_packs, :available_credit_packs
+
+    def subscription_plan(name, &block)
+      configuration.subscription_plan(name, &block)
+    end
+
+    def credit_subscription_plans
+      configuration.credit_subscription_plans
+    end
+    alias_method :subscription_plans, :credit_subscription_plans
+    alias_method :plans, :credit_subscription_plans
+
+    def find_subscription_plan(name)
+      credit_subscription_plans[name.to_sym]
+    end
+    alias_method :find_plan, :find_subscription_plan
+
+    def find_subscription_plan_by_processor_id(processor_id)
+      configuration.find_subscription_plan_by_processor_id(processor_id)
+    end
+    alias_method :find_plan_by_id, :find_subscription_plan_by_processor_id
+
+    # Event handling for low balance notifications
+    def notify_low_balance(owner)
+      return unless configuration.low_balance_callback
+      configuration.low_balance_callback.call(owner)
+    end
+
+    def handle_event(event, **params)
+      case event
+      when :low_balance_reached
+        notify_low_balance(params[:wallet].owner)
+      end
+    end
+
+  end
+end
+
+# Rails integration
+require "usage_credits/engine" if defined?(Rails)
+require "usage_credits/railtie" if defined?(Rails)
+
+# Make DSL methods available at top level
+# This is what enables the "bare" DSL syntax in initializers. Without it, users would have to write things like
+#   UsageCredits.credit_pack :starter do
+# instead of
+#   credit_pack :starter do
+#
+# Note: This modifies the global Kernel module, which is a powerful but invasive approach.
+module Kernel
+  def operation(name, &block)
+    UsageCredits.operation(name, &block)
+  end
+
+  def credit_pack(name, &block)
+    UsageCredits.credit_pack(name, &block)
+  end
+
+  def subscription_plan(name, &block)
+    UsageCredits.subscription_plan(name, &block)
+  end
+end

data/sig/usagecredits.rbs

@@ -0,0 +1,4 @@
+module UsageCredits
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end