usage_credits 0.5.0 → 1.0.0

data/lib/usage_credits/callbacks.rb

@@ -1,67 +1,22 @@
 # frozen_string_literal: true
 
 module UsageCredits
-  # Centralized callback dispatch module
-  # Handles executing callbacks with error isolation
+  # usage_credits adapter for wallets' shared callback dispatcher.
   module Callbacks
-    module_function
-
-    # Dispatch a callback event with error isolation
-    # Callbacks should never break the main operation
-    #
-    # @param event [Symbol] The event type (e.g., :credits_added, :low_balance_reached)
-    # @param context_data [Hash] Data to pass to the callback via CallbackContext
-    def dispatch(event, **context_data)
-      config = UsageCredits.configuration
-      callback = config.public_send(:"on_#{event}_callback")
-
-      return unless callback.is_a?(Proc)
-
-      context = CallbackContext.new(event: event, **context_data)
+    extend Wallets::CallbackDispatcher
 
-      execute_safely(callback, context)
-    end
-
-    # Execute callback with error isolation and arity handling
-    #
-    # @param callback [Proc] The callback to execute
-    # @param context [CallbackContext] The context to pass
-    def execute_safely(callback, context)
-      case callback.arity
-      when 1, -1, -2  # Accepts one arg or variable args
-        callback.call(context)
-      when 0
-        callback.call
-      else
-        log_warn "[UsageCredits] Callback has unexpected arity (#{callback.arity}). Expected 0 or 1."
-      end
-    rescue StandardError => e
-      # Log but don't re-raise - callbacks should never break credit operations
-      log_error "[UsageCredits] Callback error for #{context.event}: #{e.class}: #{e.message}"
-      log_debug e.backtrace.join("\n")
-    end
+    module_function
 
-    # Safe logging that works with or without Rails
-    def log_error(message)
-      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-        Rails.logger.error(message)
-      else
-        warn message
-      end
+    def callback_configuration
+      UsageCredits.configuration
     end
 
-    def log_warn(message)
-      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-        Rails.logger.warn(message)
-      else
-        warn message
-      end
+    def callback_context_class
+      UsageCredits::CallbackContext
     end
 
-    def log_debug(message)
-      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger&.debug?
-        Rails.logger.debug(message)
-      end
+    def callback_log_prefix
+      "[UsageCredits]"
     end
   end
 end

data/lib/usage_credits/configuration.rb

@@ -33,6 +33,12 @@ module UsageCredits
     # Custom transaction categories that extend the default set
     attr_reader :additional_categories
 
+    # Table prefix for usage_credits tables (for wallets gem compatibility)
+    # Note: usage_credits uses fixed table names, so this is always "usage_credits_"
+    def table_prefix
+      "usage_credits_"
+    end
+
     # Minimum allowed fulfillment period for subscription plans.
     # Defaults to 1.day to prevent accidental 1-second refill loops in production.
     # Can be set to shorter periods (e.g., 2.seconds) in development/test for faster iteration.
@@ -53,12 +59,12 @@ module UsageCredits
     # =========================================
 
     attr_reader :on_credits_added_callback,
-                :on_credits_deducted_callback,
-                :on_low_balance_reached_callback,
-                :on_balance_depleted_callback,
-                :on_insufficient_credits_callback,
-                :on_subscription_credits_awarded_callback,
-                :on_credit_pack_purchased_callback
+      :on_credits_deducted_callback,
+      :on_low_balance_reached_callback,
+      :on_balance_depleted_callback,
+      :on_insufficient_credits_callback,
+      :on_subscription_credits_awarded_callback,
+      :on_credit_pack_purchased_callback
 
     def initialize
       # Initialize empty data stores
@@ -159,15 +165,18 @@ module UsageCredits
     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(', ')}"
+        raise ArgumentError, "Invalid currency. Must be one of: #{VALID_CURRENCIES.join(", ")}"
       end
       @default_currency = value
     end
 
-    # Set low balance threshold with validation
+    # Set low balance threshold with validation. Accepts plain integers and
+    # the DSL form the initializer template shows (`100.credits`, a
+    # Cost::Fixed) — anything else fails WholeNumber.parse loudly.
     def low_balance_threshold=(value)
       if value
-        value = value.to_i
+        value = value.to_i if value.is_a?(UsageCredits::Cost::Fixed)
+        value = Wallets::WholeNumber.parse(value, name: "Low balance threshold", allow_string: true)
         raise ArgumentError, "Low balance threshold must be greater than or equal to zero" if value.negative?
       end
       @low_balance_threshold = value
@@ -183,7 +192,10 @@ module UsageCredits
     end
 
     def fulfillment_grace_period=(value)
-      if value.nil? || value&.to_i == 0
+      # Only actual nil/numeric zero select the safe one-second fallback.
+      # String coercion previously made arbitrary garbage ("nope".to_i == 0)
+      # silently valid configuration; non-Duration strings now fail closed.
+      if value.nil? || value == 0
         @fulfillment_grace_period = 1.second
         return
       end
@@ -296,19 +308,19 @@ module UsageCredits
     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(', ')}"
+        raise ArgumentError, "Invalid currency. Must be one of: #{VALID_CURRENCIES.join(", ")}"
       end
     end
 
     def validate_threshold!
-      if @low_balance_threshold && @low_balance_threshold.negative?
+      if @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(', ')}"
+        raise ArgumentError, "Invalid rounding strategy. Must be one of: #{VALID_ROUNDING_STRATEGIES.join(", ")}"
       end
     end
 

data/lib/usage_credits/core_ext/numeric.rb

@@ -7,28 +7,24 @@ require "active_support/core_ext/numeric"
 # (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)
+    UsageCredits::Cost::Fixed.new(self)
   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
+    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

data/lib/usage_credits/cost/base.rb

@@ -31,12 +31,7 @@ module UsageCredits
       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
+        CreditCalculator.normalize_credit_amount(amount)
       end
     end
   end

data/lib/usage_credits/cost/compound.rb

@@ -12,8 +12,9 @@ module UsageCredits
       end
 
       def calculate(params = {})
-        total = costs.sum { |cost| cost.calculate(params) }
-        CreditCalculator.apply_rounding(total)
+        # Components stay unrounded until Operation#calculate_cost applies the
+        # configured strategy once to the final sum.
+        costs.sum { |cost| cost.calculate(params) }
       end
 
       def +(other)

data/lib/usage_credits/cost/fixed.rb

@@ -7,7 +7,7 @@ module UsageCredits
       attr_reader :period
 
       def initialize(amount)
-        @amount = amount
+        super
         @period = nil  # Will default to 1.month in CreditSubscriptionPlan
       end
 
@@ -18,7 +18,6 @@ module UsageCredits
           value.calculate(params)
         else
           validate_amount!(value)
-          value.to_i
         end
       end
 

data/lib/usage_credits/cost/variable.rb

@@ -4,37 +4,52 @@ module UsageCredits
   module Cost
     # Variable credit cost based on units (e.g., 1 credit per MB)
     class Variable < Base
+      SUPPORTED_UNITS = %i[kb mb gb units].freeze
+
       attr_reader :unit
 
       def initialize(amount, unit)
         super(amount)
         @unit = unit.to_sym
+        raise ArgumentError, "Unknown unit: #{unit}" unless SUPPORTED_UNITS.include?(@unit)
       end
 
       def calculate(params = {})
+        # Return the raw composable cost. Operation#calculate_cost is the one
+        # rounding boundary, preventing nested Variable/Compound calculators
+        # from rounding the same business cost more than once.
         size = extract_size(params)
-        raw_cost = amount * size
-        CreditCalculator.apply_rounding(raw_cost)
+        amount * size
       end
 
       private
 
       def extract_size(params)
         case unit
-        when :mb
+        when :kb, :mb, :gb
           # First check for direct MB value
           if params[:mb]
-            CreditCalculator.apply_rounding(params[:mb].to_f)
+            convert_megabytes(params[:mb])
           # Then check for bytes that need conversion
           elsif params[:size]
-            CreditCalculator.apply_rounding(params[:size].to_f / 1.megabyte)
+            params[:size].to_f / bytes_per_unit
           else
             0
           end
         when :units
-          CreditCalculator.apply_rounding(params.fetch(:units, 0).to_f)
-        else
-          raise ArgumentError, "Unknown unit: #{unit}"
+          params.fetch(:units, 0)
+        end
+      end
+
+      def convert_megabytes(megabytes)
+        (megabytes.to_f * 1.megabyte) / bytes_per_unit
+      end
+
+      def bytes_per_unit
+        case unit
+        when :kb then 1.kilobyte
+        when :mb then 1.megabyte
+        when :gb then 1.gigabyte
         end
       end
     end

data/lib/usage_credits/engine.rb

@@ -5,16 +5,9 @@ module 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
+    # All gem code is required eagerly by lib/usage_credits.rb. Adding these
+    # directories to the host app's autoloaders would make Zeitwerk claim
+    # common top-level constants such as ::Wallet and ::Operation.
 
     # Add has_credits method to ActiveRecord::Base
     initializer "usage_credits.active_record" do
@@ -30,8 +23,11 @@ module UsageCredits
       end
     end
 
-    initializer "usage_credits.configs" do
-      # Initialize any config settings
+    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/helpers/credit_calculator.rb

@@ -21,6 +21,24 @@ module UsageCredits
       end
     end
 
+    # Normalize every configured or dynamically calculated credit cost through
+    # one strict boundary. Keeping parse-error translation here means fixed
+    # values and Proc results cannot match Wallets error-message text in
+    # separate places and drift apart.
+    def normalize_credit_amount(amount)
+      number = begin
+        Wallets::WholeNumber.parse(amount, name: "Credit amount")
+      rescue ArgumentError
+        raise ArgumentError, "Credit amount must be a whole number (got: #{amount})"
+      end
+
+      if number.negative?
+        raise ArgumentError, "Credit amount cannot be negative (got: #{amount})"
+      end
+
+      number
+    end
+
     # Convert a monetary amount to credits
     def money_to_credits(cents, exchange_rate)
       apply_rounding(cents * exchange_rate / 100.0)

data/lib/usage_credits/helpers/credits_helper.rb

@@ -17,20 +17,19 @@ module UsageCredits
     # 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
+        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)
@@ -40,6 +39,5 @@ module UsageCredits
         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

@@ -4,7 +4,6 @@ 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 = {
       second: [:second, :seconds],        # 1.second
@@ -17,6 +16,7 @@ module UsageCredits
       year: [:year, :yearly, :annually]   # 1.year
     }.freeze
 
+    ABSOLUTE_MIN_PERIOD = 1.second
     MIN_PERIOD = 1.day  # Deprecated: Use UsageCredits.configuration.min_fulfillment_period instead
 
     module_function
@@ -37,8 +37,7 @@ module UsageCredits
 
       # Handle ActiveSupport::Duration objects directly
       if period.is_a?(ActiveSupport::Duration)
-        min_period = min_fulfillment_period
-        raise ArgumentError, "Period must be at least #{min_period.inspect}" if period < min_period
+        validate_minimum!(period)
         period
       else
         # Convert symbols to canonical durations
@@ -55,8 +54,7 @@ module UsageCredits
           raise ArgumentError, "Unsupported period: #{period}. Supported periods: #{VALID_PERIODS.values.flatten.inspect}"
         end
 
-        min_period = min_fulfillment_period
-        raise ArgumentError, "Period must be at least #{min_period.inspect}" if duration < min_period
+        validate_minimum!(duration)
         duration
       end
     end
@@ -65,8 +63,11 @@ module UsageCredits
     # @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)
+    def parse_period(period_str, enforce_minimum: true)
+      if period_str.is_a?(ActiveSupport::Duration)
+        validate_minimum!(period_str, persisted: !enforce_minimum)
+        return period_str
+      end
 
       if period_str.to_s =~ /\A(\d+)[.\s](\w+)\z/
         amount = $1.to_i
@@ -82,14 +83,19 @@ module UsageCredits
         canonical_unit = canonical_unit_for(unit)
 
         duration = amount.send(canonical_unit)
-        min_period = min_fulfillment_period
-        raise ArgumentError, "Period must be at least #{min_period.inspect}" if duration < min_period
+        validate_minimum!(duration, persisted: !enforce_minimum)
         duration
       else
         raise ArgumentError, "Invalid period format: #{period_str}. Expected format: '1.month', '2 months', etc."
       end
     end
 
+    # Persisted commercial schedules remain valid if an operator later raises
+    # the minimum allowed for newly configured plans.
+    def parse_persisted_period(period_str)
+      parse_period(period_str, enforce_minimum: false)
+    end
+
     # Map any alias to its canonical unit method name
     # @param unit [Symbol] The unit symbol (e.g., :hourly, :seconds, :day)
     # @return [Symbol] The canonical unit method (e.g., :hour, :second, :day)
@@ -111,5 +117,21 @@ module UsageCredits
       false
     end
 
+    def valid_persisted_period_format?(period_str)
+      parse_persisted_period(period_str)
+      true
+    rescue ArgumentError
+      false
+    end
+
+    def validate_minimum!(duration, persisted: false)
+      # Persisted commercial terms must survive a later operator-configured
+      # minimum increase, but they can never bypass the gem's hard safety
+      # floor. A zero cadence remains perpetually due and can mint on every job
+      # run, so one second is the absolute minimum for all schedules.
+      min_period = persisted ? ABSOLUTE_MIN_PERIOD : min_fulfillment_period
+      raise ArgumentError, "Period must be at least #{min_period.inspect}" if duration < min_period
+    end
+    private_class_method :validate_minimum!
   end
 end

data/lib/usage_credits/helpers/processor_metadata.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Normalizes and validates metadata before it crosses a payment-processor
+  # boundary. Stripe stores metadata as at most 50 string key/value pairs;
+  # structured Ruby values are encoded as one JSON string instead of becoming
+  # unsupported nested form parameters.
+  module ProcessorMetadata
+    MAX_PAIRS = 50
+    MAX_KEY_LENGTH = 40
+    MAX_VALUE_LENGTH = 500
+
+    module_function
+
+    def normalize(value)
+      hash = value.nil? ? {} : value.to_h
+      raise ArgumentError, "Processor metadata cannot contain more than #{MAX_PAIRS} keys" if hash.size > MAX_PAIRS
+
+      hash.each_with_object(ActiveSupport::HashWithIndifferentAccess.new) do |(key, raw_value), normalized|
+        normalized_key = key.to_s
+        validate_key!(normalized_key)
+
+        normalized_value = structured?(raw_value) ? ActiveSupport::JSON.encode(raw_value) : raw_value.to_s
+        if normalized_value.length > MAX_VALUE_LENGTH
+          raise ArgumentError, "Processor metadata value for #{normalized_key.inspect} exceeds #{MAX_VALUE_LENGTH} characters"
+        end
+
+        normalized[normalized_key] = normalized_value
+      end
+    rescue NoMethodError, TypeError
+      raise ArgumentError, "Processor metadata must be hash-like"
+    end
+
+    def validate_key!(key)
+      if key.empty? || key.length > MAX_KEY_LENGTH || key.match?(/[\[\]]/)
+        raise ArgumentError, "Invalid processor metadata key: #{key.inspect}"
+      end
+    end
+    private_class_method :validate_key!
+
+    def structured?(value)
+      value.is_a?(Hash) || value.is_a?(Array)
+    end
+    private_class_method :structured?
+  end
+end

data/lib/usage_credits/jobs/fulfillment_job.rb

@@ -17,7 +17,7 @@ module UsageCredits
       end
 
       Rails.logger.info "Completed processing #{count} fulfillments in #{formatted_time}"
-    rescue StandardError => e
+    rescue => e
       Rails.logger.error "Error processing credit fulfillments: #{e.message}"
       raise # Re-raise to trigger job retry
     end

data/lib/usage_credits/models/allocation.rb

@@ -5,29 +5,24 @@ module UsageCredits
   # 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"
+  # This class extends Wallets::Allocation with usage_credits table configuration.
 
-    belongs_to :spend_transaction, class_name: "UsageCredits::Transaction", foreign_key: "transaction_id"
-    belongs_to :source_transaction, class_name: "UsageCredits::Transaction"
+  class Allocation < Wallets::AllocationBase
+    # =========================================
+    # Embeddability Configuration
+    # =========================================
 
-    validates :amount, presence: true, numericality: { only_integer: true, greater_than: 0 }
+    self.embedded_table_name = "usage_credits_allocations"
+    self.config_provider = -> { UsageCredits.configuration }
 
-    validate :allocation_does_not_exceed_remaining_amount
-
-    private
-
-    def allocation_does_not_exceed_remaining_amount
-      return if amount.blank? || source_transaction.blank?
-
-      if source_transaction.remaining_amount < amount
-        errors.add(:amount, "exceeds the remaining amount of the source transaction")
-      end
-    end
+    # =========================================
+    # Re-declare Associations with Correct Classes
+    # =========================================
 
+    belongs_to :spend_transaction,
+      class_name: "UsageCredits::Transaction",
+      foreign_key: "transaction_id",
+      optional: false
+    belongs_to :source_transaction, class_name: "UsageCredits::Transaction", optional: false
   end
 end