usage_credits 0.1.0

data/lib/usage_credits/helpers/credits_helper.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # View helpers for displaying credit information
+  module CreditsHelper
+    # Format credit amount for display
+    def format_credits(amount)
+      UsageCredits.configuration.credit_formatter.call(amount)
+    end
+
+    # Format price in currency
+    def format_credit_price(cents, currency = nil)
+      currency ||= UsageCredits.configuration.default_currency
+      format("%.2f %s", cents / 100.0, currency.to_s.upcase)
+    end
+
+    # Credit pack purchase button
+    def credit_pack_button(pack, options = {})
+      button_to options[:path] || credit_pack_purchase_path(pack),
+                class: options[:class] || "credit-pack-button",
+                method: :post,
+                data: {
+                  turbo: false,
+                  pack_name: pack.name,
+                  credits: pack.credits,
+                  bonus_credits: pack.bonus_credits,
+                  price: pack.price_cents
+                } do
+        render_credit_pack_button_content(pack)
+      end
+    end
+
+
+    private
+
+    def render_credit_pack_button_content(pack)
+      safe_join([
+        content_tag(:span, "#{format_credits(pack.credits)} Credits", class: "credit-amount"),
+        pack.bonus_credits.positive? ? content_tag(:span, "+ #{format_credits(pack.bonus_credits)} Bonus", class: "bonus-amount") : nil,
+        content_tag(:span, format_credit_price(pack.price_cents, pack.price_currency), class: "price")
+      ].compact, " ")
+    end
+
+  end
+end

data/lib/usage_credits/helpers/period_parser.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Handles parsing and normalization of time periods throughout the gem.
+  # Converts strings like "1.month" or symbols like :monthly into ActiveSupport::Duration objects.
+  module PeriodParser
+
+    # Canonical periods and their aliases
+    VALID_PERIODS = {
+      day: [:day, :daily],                # 1.day
+      week: [:week, :weekly],             # 1.week
+      month: [:month, :monthly],          # 1.month
+      quarter: [:quarter, :quarterly],    # 3.months
+      year: [:year, :yearly, :annually]   # 1.year
+    }.freeze
+
+    MIN_PERIOD = 1.day
+
+    module_function
+
+    # Turns things like `:monthly` into `1.month` to always store consistent time periods
+    def normalize_period(period)
+      return nil unless period
+
+      # Handle ActiveSupport::Duration objects directly
+      if period.is_a?(ActiveSupport::Duration)
+        raise ArgumentError, "Period must be at least #{MIN_PERIOD.inspect}" if period < MIN_PERIOD
+        period
+      else
+        # Convert symbols to canonical durations
+        case period
+        when *VALID_PERIODS[:day] then 1.day
+        when *VALID_PERIODS[:week] then 1.week
+        when *VALID_PERIODS[:month] then 1.month
+        when *VALID_PERIODS[:quarter] then 3.months
+        when *VALID_PERIODS[:year] then 1.year
+        else
+          raise ArgumentError, "Unsupported period: #{period}. Supported periods: #{VALID_PERIODS.values.flatten.inspect}"
+        end
+      end
+    end
+
+    # Parse a period string into an ActiveSupport::Duration
+    # @param period_str [String, ActiveSupport::Duration] A string like "1.month" or "1 month" or an existing duration
+    # @return [ActiveSupport::Duration] The parsed duration
+    # @raise [ArgumentError] If the period string is invalid
+    def parse_period(period_str)
+      return period_str if period_str.is_a?(ActiveSupport::Duration)
+
+      if period_str.to_s =~ /\A(\d+)[.\s](\w+)\z/
+        amount = $1.to_i
+        unit = $2.singularize.to_sym
+
+        # Validate the unit is supported
+        valid_units = VALID_PERIODS.values.flatten
+        unless valid_units.include?(unit)
+          raise ArgumentError, "Unsupported period unit: #{unit}. Supported units: #{valid_units.inspect}"
+        end
+
+        duration = amount.send(unit)
+        raise ArgumentError, "Period must be at least #{MIN_PERIOD.inspect}" if duration < MIN_PERIOD
+        duration
+      else
+        raise ArgumentError, "Invalid period format: #{period_str}. Expected format: '1.month', '2 months', etc."
+      end
+    end
+
+    # Validates that a period string matches the expected format and units
+    def valid_period_format?(period_str)
+      parse_period(period_str)
+      true
+    rescue ArgumentError
+      false
+    end
+
+  end
+end

data/lib/usage_credits/jobs/fulfillment_job.rb

@@ -0,0 +1,25 @@
+# lib/usage_credits/jobs/fulfillment_job.rb
+module UsageCredits
+  class FulfillmentJob < ApplicationJob
+    queue_as :default
+
+    def perform
+      Rails.logger.info "Starting credit fulfillment processing"
+      start_time = Time.current
+
+      count = FulfillmentService.process_pending_fulfillments
+
+      elapsed = Time.current - start_time
+      formatted_time = if elapsed >= 60
+        "#{(elapsed / 60).floor}m #{(elapsed % 60).round}s"
+      else
+        "#{elapsed.round(2)}s"
+      end
+
+      Rails.logger.info "Completed processing #{count} fulfillments in #{formatted_time}"
+    rescue StandardError => e
+      Rails.logger.error "Error processing credit fulfillments: #{e.message}"
+      raise # Re-raise to trigger job retry
+    end
+  end
+end

data/lib/usage_credits/models/allocation.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # An Allocation links a *negative* (spend) transaction
+  # to a *positive* (credit) transaction, indicating how many
+  # credits were taken from that specific credit source.
+  #
+  # Allocations are the basis for the bucket-based, FIFO-with-expiration inventory-like system
+  # This is critical for calculating balances when there are mixed expiring and non-expiring credits
+  # Otherwise, balance calculations will always be wrong because negative transactions get dragged forever
+  # More info: https://x.com/rameerez/status/1884246492837302759
+  class Allocation < ApplicationRecord
+    self.table_name = "usage_credits_allocations"
+
+    belongs_to :spend_transaction, class_name: "UsageCredits::Transaction", foreign_key: "transaction_id"
+    belongs_to :source_transaction, class_name: "UsageCredits::Transaction"
+
+    validates :amount, presence: true, numericality: { only_integer: true, greater_than: 0 }
+
+    validate :allocation_does_not_exceed_remaining_amount
+
+    private
+
+    def allocation_does_not_exceed_remaining_amount
+      if source_transaction.remaining_amount < amount
+        errors.add(:amount, "exceeds the remaining amount of the source transaction")
+      end
+    end
+
+  end
+end

data/lib/usage_credits/models/concerns/has_wallet.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Adds credit wallet functionality to a model
+  module HasWallet
+    extend ActiveSupport::Concern
+
+    included do
+      has_one :credit_wallet,
+              class_name: "UsageCredits::Wallet",
+              as: :owner,
+              dependent: :destroy
+
+      alias_method :credits_wallet, :credit_wallet
+      alias_method :wallet, :credit_wallet
+
+      after_create :create_credit_wallet, if: :should_create_wallet?
+
+      # More intuitive delegations
+      delegate :credits,
+               :credit_history,
+               :has_enough_credits_to?,
+               :estimate_credits_to,
+               :spend_credits_on,
+               :give_credits,
+               to: :ensure_credit_wallet,
+               allow_nil: false # Never return nil for these methods
+
+      # Fix recursion by properly aliasing the original method
+      alias_method :original_credit_wallet, :credit_wallet
+
+      # Then override it
+      define_method(:credit_wallet) do
+        ensure_credit_wallet
+      end
+
+      # Returns all active subscriptions as CreditSubscriptionPlan objects
+      def subscriptions
+        return [] unless credit_wallet
+
+        credit_wallet.fulfillments
+          .where(fulfillment_type: "subscription")
+          .active
+          .map { |f| UsageCredits.find_subscription_plan_by_processor_id(f.metadata["plan"]) }
+          .compact
+      end
+
+    end
+
+    # Class methods added to the model
+    class_methods do
+      def has_credits(**options)
+        include UsageCredits::HasWallet unless included_modules.include?(UsageCredits::HasWallet)
+
+        # Initialize class instance variable instead of class variable
+        @credit_options = options
+
+        # Ensure wallet is created by default unless explicitly disabled
+        @credit_options[:auto_create] = true if @credit_options[:auto_create].nil?
+      end
+
+      def credit_options
+        @credit_options ||= { auto_create: true }
+      end
+    end
+
+    def credit_options
+      self.class.credit_options
+    end
+
+    private
+
+    def should_create_wallet?
+      credit_options[:auto_create] != false
+    end
+
+    def ensure_credit_wallet
+      return original_credit_wallet if original_credit_wallet.present?
+      return unless should_create_wallet?
+
+      if persisted?
+        build_credit_wallet(
+          balance: credit_options[:initial_balance] || 0
+        ).tap(&:save!)
+      else
+        raise "Cannot create wallet for unsaved owner"
+      end
+    end
+
+    def create_credit_wallet
+      ensure_credit_wallet
+    end
+  end
+end

data/lib/usage_credits/models/concerns/pay_charge_extension.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Extends Pay::Charge with credit pack functionality
+  module PayChargeExtension
+    extend ActiveSupport::Concern
+
+    included do
+      after_initialize :init_metadata
+      after_commit :fulfill_credit_pack!
+      after_commit :handle_refund!, on: :update, if: :refund_needed?
+    end
+
+    def init_metadata
+      self.metadata ||= {}
+      self.data ||= {}
+    end
+
+    def succeeded?
+      return true if data["status"] == "succeeded" || data[:status] == "succeeded"
+      # For Stripe charges, a successful charge has amount_captured equal to the charge amount
+      return true if type == "Pay::Stripe::Charge" && data["amount_captured"] == amount
+      false
+    end
+
+    def refunded?
+      return false unless amount_refunded
+      amount_refunded > 0
+    end
+
+    private
+
+    # Returns true if the charge has a valid credit wallet to operate on
+    def has_valid_wallet?
+      return false unless customer&.owner&.respond_to?(:credit_wallet)
+      return false unless customer.owner.credit_wallet.present?
+      true
+    end
+
+    def credit_wallet
+      return nil unless has_valid_wallet?
+      customer.owner.credit_wallet
+    end
+
+    def refund_needed?
+      saved_change_to_amount_refunded? && amount_refunded.to_i.positive?
+    end
+
+    def is_credit_pack_purchase?
+      metadata["purchase_type"] == "credit_pack"
+    end
+
+    def pack_identifier
+      metadata["pack_name"]
+    end
+
+    def credits_already_fulfilled?
+      # First check if there's a fulfillment record for this charge
+      return true if UsageCredits::Fulfillment.exists?(source: self)
+
+      # Fallback: check transactions directly
+      credit_wallet&.transactions&.where(category: "credit_pack_purchase")
+        .exists?(['metadata @> ?', { purchase_charge_id: id, credits_fulfilled: true }.to_json])
+    end
+
+    def fulfill_credit_pack!
+      return unless is_credit_pack_purchase?
+      return unless pack_identifier
+      return unless has_valid_wallet?
+      return unless succeeded?
+      return if refunded?
+      return if credits_already_fulfilled?
+
+      Rails.logger.info "Starting to process charge #{id} to fulfill credits"
+
+      pack_name = pack_identifier.to_sym
+      pack = UsageCredits.find_pack(pack_name)
+
+      unless pack
+        Rails.logger.error "Credit pack not found: #{pack_name} for charge #{id}"
+        return
+      end
+
+      # Validate that the pack details match if they're provided in metadata
+      if metadata["credits"].present?
+        expected_credits = metadata["credits"].to_i
+        if expected_credits != pack.credits
+          Rails.logger.error "Credit pack mismatch: expected #{expected_credits} credits but pack #{pack_name} provides #{pack.credits}"
+          return
+        end
+      end
+
+      begin
+        # Wrap credit addition in a transaction for atomicity
+        ActiveRecord::Base.transaction do
+          # Add credits to the user's wallet
+          credit_wallet.add_credits(
+            pack.total_credits,
+            category: "credit_pack_purchase",
+            metadata: {
+              purchase_charge_id: id,
+              purchased_at: created_at,
+              credits_fulfilled: true,
+              fulfilled_at: Time.current,
+              **pack.base_metadata
+            }
+          )
+
+          # Also create a one-time fulfillment record for audit and consistency
+          # This Fulfillment record won't get picked up by the fulfillment job because `next_fulfillment_at` is nil
+          Fulfillment.create!(
+            wallet: credit_wallet,
+            source: self, # the Pay::Charge
+            fulfillment_type: "credit_pack",
+            credits_last_fulfillment: pack.total_credits,
+            last_fulfilled_at: Time.current,
+            next_fulfillment_at: nil, # so it doesn't get re-processed
+            metadata: {
+              purchase_charge_id: id,
+              purchased_at: created_at,
+              **pack.base_metadata
+            }
+          )
+        end
+
+        Rails.logger.info "Successfully fulfilled credit pack #{pack_name} for charge #{id}"
+      rescue StandardError => e
+        Rails.logger.error "Failed to fulfill credit pack #{pack_name} for charge #{id}: #{e.message}"
+        raise
+      end
+    end
+
+    def credits_already_refunded?
+      # Check if refund was already processed with credits deducted by looking for a refund transaction
+      credit_wallet&.transactions&.where(category: "credit_pack_refund")
+        .exists?(['metadata @> ?', { refunded_purchase_charge_id: id, credits_refunded: true }.to_json])
+    end
+
+    def handle_refund!
+      # Guard clauses for required data and state
+      return unless refunded?
+      return unless pack_identifier
+      return unless has_valid_wallet?
+      return unless amount.is_a?(Numeric) && amount.positive?
+      return if credits_already_refunded?
+
+      pack_name = pack_identifier.to_sym
+      pack = UsageCredits.find_pack(pack_name)
+
+      unless pack
+        Rails.logger.error "Credit pack not found for refund: #{pack_name} for charge #{id}"
+        return
+      end
+
+      # Validate refund amount
+      if amount_refunded > amount
+        Rails.logger.error "Invalid refund amount: #{amount_refunded} exceeds original charge amount #{amount} for charge #{id}"
+        return
+      end
+
+      # Calculate refund ratio and credits to remove
+      # Always use ceil for credit calculations to avoid giving more credits than paid for
+      refund_ratio = amount_refunded.to_f / amount.to_f
+      credits_to_remove = (pack.total_credits * refund_ratio).ceil
+
+      begin
+        Rails.logger.info "Processing refund for charge #{id}: #{credits_to_remove} credits (#{(refund_ratio * 100).round(2)}% of #{pack.total_credits})"
+
+        # Wrap credit deduction in a transaction for atomicity
+        ActiveRecord::Base.transaction do
+          credit_wallet.deduct_credits(
+            credits_to_remove,
+            category: "credit_pack_refund",
+            metadata: {
+              refunded_purchase_charge_id: id,
+              credits_refunded: true,
+              refunded_at: Time.current,
+              refund_percentage: refund_ratio,
+              refund_amount_cents: amount_refunded,
+              **pack.base_metadata
+            }
+          )
+        end
+
+        Rails.logger.info "Successfully processed refund for charge #{id}"
+      rescue UsageCredits::InsufficientCredits => e
+        Rails.logger.error "Insufficient credits for refund on charge #{id}: #{e.message}"
+        # If negative balance not allowed and user has used credits,
+        # we'll let the error propagate
+        raise
+      rescue StandardError => e
+        Rails.logger.error "Failed to process refund for charge #{id}: #{e.message}"
+        raise
+      end
+    end
+
+  end
+end