usage_credits 0.1.0

data/lib/usage_credits/models/fulfillment.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # A Fulfillment represents a credit-giving action triggered by a purchase,
+  # including credit pack purchases and subscriptions.
+  # Some of this credit-giving actions are repeating in nature (i.e.: subscriptions), some are not (one-time purchases)
+  class Fulfillment < ApplicationRecord
+    self.table_name = "usage_credits_fulfillments"
+
+    belongs_to :wallet
+    belongs_to :source, polymorphic: true, optional: true
+
+    validates :wallet, presence: true
+    validates :source_id, uniqueness: { scope: :source_type }, if: :source_id?
+    validates :credits_last_fulfillment, presence: true, numericality: { only_integer: true }
+    validates :fulfillment_type, presence: true
+    validate :valid_fulfillment_period_format, if: :fulfillment_period?
+    validates :next_fulfillment_at, comparison: { greater_than: :last_fulfilled_at },
+      if: -> { recurring? && last_fulfilled_at.present? && next_fulfillment_at.present? }
+
+    # Only get fulfillments that are due AND not stopped
+    scope :due_for_fulfillment, -> {
+      where("next_fulfillment_at <= ?", Time.current)
+        .where("stops_at IS NULL OR stops_at > ?", Time.current)
+        .where("last_fulfilled_at IS NULL OR next_fulfillment_at > last_fulfilled_at")
+    }
+    scope :active, -> { where("stops_at IS NULL OR stops_at > ?", Time.current) }
+
+    # Alias for backward compatibility - will be removed in next version
+    scope :pending, -> { due_for_fulfillment }
+
+    def due_for_fulfillment?
+      return false unless next_fulfillment_at.present?
+      return false if stopped?
+      return false if last_fulfilled_at.present? && next_fulfillment_at <= last_fulfilled_at
+
+      next_fulfillment_at <= Time.current
+    end
+
+    def recurring?
+      fulfillment_period.present?
+    end
+
+    def stopped?
+      stops_at.present? && stops_at <= Time.current
+    end
+
+    def active?
+      !stopped?
+    end
+
+    def calculate_next_fulfillment
+      return nil unless recurring?
+      return nil if stopped?
+      return nil if next_fulfillment_at.nil?
+
+      # If next_fulfillment_at is in the past (e.g. due to missed fulfillments or errors),
+      # we use current time as the base to avoid scheduling multiple rapid fulfillments.
+      # This ensures smooth recovery from missed fulfillments by scheduling the next one
+      # from the current time rather than the missed fulfillment time.
+      base_time = next_fulfillment_at > Time.current ? next_fulfillment_at : Time.current
+
+      base_time + UsageCredits::PeriodParser.parse_period(fulfillment_period)
+    end
+
+    private
+
+    def valid_fulfillment_period_format
+      unless UsageCredits::PeriodParser.valid_period_format?(fulfillment_period)
+        errors.add(:fulfillment_period, "must be in format like '2.months' or '15.days' and use supported units")
+      end
+    end
+
+    validate :validate_fulfillment_schedule
+
+    def validate_fulfillment_schedule
+      return unless next_fulfillment_at.present?
+
+      if recurring?
+        # For recurring fulfillments, next_fulfillment_at should be in the future when created
+        if new_record? && next_fulfillment_at <= Time.current
+          errors.add(:next_fulfillment_at, "must be in the future for new recurring fulfillments")
+        end
+      else
+        # For one-time fulfillments, next_fulfillment_at should be nil
+        errors.add(:next_fulfillment_at, "should be nil for non-recurring fulfillments") unless new_record?
+      end
+    end
+
+  end
+end

data/lib/usage_credits/models/operation.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # A DSL to define an operation that consumes credits when performed.
+  class Operation
+
+    attr_reader :name,                # Operation identifier (e.g., :process_video)
+                :cost_calculator,     # Lambda or Fixed that calculates credit cost
+                :validation_rules,    # Array of [condition, message] pairs
+                :metadata             # Custom data for your app's use
+
+    def initialize(name, &block)
+      @name = name
+      @cost_calculator = Cost::Fixed.new(0)  # Default to free
+      @validation_rules = []
+      @metadata = {}
+      instance_eval(&block) if block_given?
+    end
+
+    # =========================================
+    # DSL Methods (used in initializer blocks)
+    # =========================================
+
+    # Set how many credits this operation costs
+    #
+    # @param amount_or_calculator [Integer, Lambda] Fixed amount or dynamic calculator
+    #   costs 10                          # Fixed cost
+    #   costs ->(params) { params[:mb] }  # Dynamic cost
+    def costs(amount_or_calculator)
+      @cost_calculator = case amount_or_calculator
+      when Cost::Base
+        amount_or_calculator
+      else
+        Cost::Fixed.new(amount_or_calculator)
+      end
+    end
+    alias_method :cost, :costs
+
+    # Add a validation rule for this operation
+    # Example: can't process images bigger than 100MB
+    #
+    # @param condition [Lambda] Returns true if valid
+    # @param message [String] Error message if invalid
+    def validate(condition, message = nil)
+      @validation_rules << [condition, message || "Operation validation failed"]
+    end
+
+    # Add custom metadata
+    def meta(hash)
+      @metadata = @metadata.merge(hash.transform_keys(&:to_s))
+    end
+
+    # =========================================
+    # Cost Calculation
+    # =========================================
+
+    # Calculate how many credits this operation will cost
+    # @param params [Hash] Operation parameters (e.g., file size)
+    # @return [Integer] Number of credits
+    def calculate_cost(params = {})
+      normalized_params = normalize_params(params)
+      validate!(normalized_params)  # Ensure params are valid before calculating
+
+      # Calculate raw cost
+      total = case cost_calculator
+              when Proc
+                result = cost_calculator.call(normalized_params)
+                raise ArgumentError, "Credit amount must be a whole number (got: #{result})" unless result == result.to_i
+                raise ArgumentError, "Credit amount cannot be negative (got: #{result})" if result.negative?
+                result
+              else
+                cost_calculator.calculate(normalized_params)
+              end
+
+      # Apply configured rounding strategy
+      CreditCalculator.apply_rounding(total)
+    end
+
+    # =========================================
+    # Validation
+    # =========================================
+
+    # Check if the operation can be performed
+    # @param params [Hash] Operation parameters to validate
+    # @raise [InvalidOperation] If validation fails
+    def validate!(params = {})
+      normalized = normalize_params(params)
+
+      validation_rules.each do |condition, message|
+        next unless condition.is_a?(Proc)
+
+        begin
+          result = condition.call(normalized)
+          raise InvalidOperation, message unless result
+        rescue StandardError => e
+          raise InvalidOperation, "Validation error: #{e.message}"
+        end
+      end
+    end
+
+    # =========================================
+    # Audit Trail
+    # =========================================
+
+    # Create an audit record of this operation
+    def to_audit_hash(params = {})
+      {
+        operation: name,
+        cost: calculate_cost(params),
+        params: params,
+        metadata: metadata,
+        executed_at: Time.current,
+        gem_version: UsageCredits::VERSION
+      }
+    end
+
+    private
+
+    # =========================================
+    # Parameter Handling
+    # =========================================
+
+    # Normalize different parameter formats
+    # - Handles different size units (MB, bytes)
+    # - Handles different parameter names
+    def normalize_params(params)
+      params = params.symbolize_keys
+
+      # Handle different size specifications
+      size = if params[:mb]
+               params[:mb].to_f
+             elsif params[:size_mb]
+               params[:size_mb].to_f
+             elsif params[:size_megabytes]
+               params[:size_megabytes].to_f
+             elsif params[:size]
+               params[:size].to_f / 1.megabyte
+             else
+               0.0
+             end
+
+      # Handle generic unit-based operations
+      units = params[:units].to_f if params[:units]
+
+      params.merge(
+        size: (size * 1.megabyte).to_i,   # Raw bytes
+        mb: size,                         # MB for convenience
+        units: units || 0.0               # Generic units
+      )
+    end
+
+  end
+end

data/lib/usage_credits/models/transaction.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Records all credit changes in a wallet (additions, deductions, expirations).
+  #
+  # Each transaction represents a single credit operation and includes:
+  #   - amount: How many credits (positive for additions, negative for deductions)
+  #   - category: What kind of operation (subscription fulfillment, pack purchase, etc)
+  #   - metadata: Additional details about the operation
+  #   - expires_at: When these credits expire (optional)
+  class Transaction < ApplicationRecord
+    self.table_name = "usage_credits_transactions"
+
+    # =========================================
+    # Transaction Categories
+    # =========================================
+
+    # All possible transaction types, grouped by purpose:
+    CATEGORIES = [
+      # Bonus credits
+      "signup_bonus",                   # Initial signup bonus
+      "referral_bonus",                 # Referral reward
+
+      # Subscription-related
+      "subscription_credits",           # Generic subscription credits
+      "subscription_trial",             # Trial period credits
+      "subscription_signup_bonus",      # Bonus for subscribing
+
+      # One-time purchases
+      "credit_pack",                    # Generic credit pack
+      "credit_pack_purchase",           # Credit pack bought
+      "credit_pack_refund",             # Credit pack refunded
+
+      # Credit usage & management
+      "operation_charge",               # Credits spent on operation
+      "manual_adjustment",              # Manual admin adjustment
+      "credit_added",                   # Generic addition
+      "credit_deducted"                 # Generic deduction
+    ].freeze
+
+    # =========================================
+    # Associations & Validations
+    # =========================================
+
+    belongs_to :wallet
+
+    belongs_to :fulfillment, optional: true
+
+    has_many :outgoing_allocations,
+              class_name: "UsageCredits::Allocation",
+              foreign_key: :transaction_id,
+              dependent: :destroy
+
+    has_many :incoming_allocations,
+              class_name: "UsageCredits::Allocation",
+              foreign_key: :source_transaction_id,
+              dependent: :destroy
+
+    validates :amount, presence: true, numericality: { only_integer: true }
+    validates :category, presence: true, inclusion: { in: CATEGORIES }
+
+    validate :remaining_amount_cannot_be_negative
+
+    # =========================================
+    # Scopes
+    # =========================================
+
+    scope :credits_added, -> { where("amount > 0") }
+    scope :credits_deducted, -> { where("amount < 0") }
+    scope :by_category, ->(category) { where(category: category) }
+    scope :recent, -> { order(created_at: :desc) }
+    scope :operation_charges, -> { where(category: :operation_charge) }
+
+    # A transaction is not expired if:
+    # 1. It has no expiration date, OR
+    # 2. Its expiration date is in the future
+    scope :not_expired, -> { where("expires_at IS NULL OR expires_at > ?", Time.current) }
+    scope :expired, -> { where("expires_at < ?", Time.current) }
+
+
+    # =========================================
+    # Helpers
+    # =========================================
+
+    # Get the owner of the wallet these credits belong to
+    def owner
+      wallet.owner
+    end
+
+    # Have these credits expired?
+    def expired?
+      expires_at.present? && expires_at < Time.current
+    end
+
+    # Is this transaction a positive credit or a negative (spend)?
+    def credit?
+      amount > 0
+    end
+
+    def debit?
+      amount < 0
+    end
+
+    # How many credits from this transaction have already been allocated (spent)?
+    # Only applies if this transaction is positive.
+    def allocated_amount
+      incoming_allocations.sum(:amount)
+    end
+
+    # How many credits remain unused in this positive transaction?
+    # If negative, this will effectively be 0.
+    def remaining_amount
+      return 0 unless credit?
+      amount - allocated_amount
+    end
+
+    # =========================================
+    # Display Formatting
+    # =========================================
+
+    # Format the amount for display (e.g., "+100 credits" or "-10 credits")
+    def formatted_amount
+      prefix = amount.positive? ? "+" : ""
+      "#{prefix}#{UsageCredits.configuration.credit_formatter.call(amount)}"
+    end
+
+    # Get a human-readable description of what this transaction represents
+    def description
+      # Custom description takes precedence
+      return self[:description] if self[:description].present?
+
+      # Operation charges have dynamic descriptions
+      return operation_description if category == "operation_charge"
+
+      # Use predefined description or fallback to titleized category
+      category.titleize
+    end
+
+    # =========================================
+    # Metadata Handling
+    # =========================================
+
+    # Get metadata with indifferent access (string/symbol keys)
+    def metadata
+      @indifferent_metadata ||= ActiveSupport::HashWithIndifferentAccess.new(super || {})
+    end
+
+    # Set metadata, ensuring consistent storage format
+    def metadata=(hash)
+      @indifferent_metadata = nil  # Clear cache
+      super(hash.is_a?(Hash) ? hash.to_h : {})
+    end
+
+    private
+
+    # Format operation charge descriptions (e.g., "Process Video (-10 credits)")
+    def operation_description
+      operation = metadata["operation"]&.to_s&.titleize
+      cost = metadata["cost"]
+
+      return "Operation charge" if operation.blank?
+      return operation if cost.blank?
+
+      "#{operation} (-#{cost} credits)"
+    end
+
+    def remaining_amount_cannot_be_negative
+      if credit? && remaining_amount < 0
+        errors.add(:base, "Allocated amount exceeds transaction amount")
+      end
+    end
+
+  end
+end