usage_credits 0.4.0 → 1.0.0

data/lib/usage_credits/models/credit_pack.rb

@@ -9,11 +9,10 @@ module UsageCredits
   #
   # @see PayChargeExtension for the actual payment processing, credit pack fulfilling and refund handling
   class CreditPack
-
     attr_reader :name,
-                :credits, :bonus_credits,
-                :price_cents, :price_currency,
-                :metadata
+      :credits, :bonus_credits,
+      :price_cents, :price_currency,
+      :metadata
 
     def initialize(name)
       @name = name
@@ -30,17 +29,17 @@ module UsageCredits
 
     # Set the base number of credits
     def gives(amount)
-      @credits = amount.to_i
+      @credits = normalize_whole_number!(amount, "Credits", minimum: 1)
     end
 
     # Set bonus credits (e.g., for promotions)
     def bonus(amount)
-      @bonus_credits = amount.to_i
+      @bonus_credits = normalize_whole_number!(amount, "Bonus credits", minimum: 0)
     end
 
     # Set the price in cents (e.g., 4900 for $49.00)
     def costs(cents)
-      @price_cents = cents
+      @price_cents = normalize_whole_number!(cents, "Price cents", minimum: 1)
     end
     alias_method :cost, :costs
 
@@ -48,7 +47,7 @@ module UsageCredits
     def currency(currency)
       currency = currency.to_s.downcase.to_sym
       unless UsageCredits::Configuration::VALID_CURRENCIES.include?(currency)
-        raise ArgumentError, "Invalid currency. Must be one of: #{UsageCredits::Configuration::VALID_CURRENCIES.join(', ')}"
+        raise ArgumentError, "Invalid currency. Must be one of: #{UsageCredits::Configuration::VALID_CURRENCIES.join(", ")}"
       end
       @price_currency = currency.to_s.upcase
     end
@@ -158,20 +157,22 @@ module UsageCredits
       raise ArgumentError, "User must have a payment processor" unless user.respond_to?(:payment_processor) && user.payment_processor
 
       # Merge custom metadata with base_metadata (base_metadata takes precedence for critical fields)
-      custom_metadata = options.delete(:metadata) || {}
-      merged_metadata = custom_metadata.merge(base_metadata)
+      custom_metadata = merge_hash_options!(options, :metadata)
+      merged_metadata = UsageCredits::ProcessorMetadata.normalize(custom_metadata.merge(base_metadata))
 
       # Handle payment_intent_data specially to preserve metadata
       # We dup to avoid mutating the caller's original hash
-      custom_payment_intent_data = (options.delete(:payment_intent_data) || {}).dup
-      custom_pi_metadata = custom_payment_intent_data.delete(:metadata) || {}
+      custom_payment_intent_data = merge_hash_options!(options, :payment_intent_data)
+      custom_pi_metadata = merge_hash_options!(custom_payment_intent_data, :metadata)
       merged_payment_intent_data = custom_payment_intent_data.merge(
-        metadata: custom_pi_metadata.merge(base_metadata)
+        metadata: UsageCredits::ProcessorMetadata.normalize(custom_pi_metadata.merge(base_metadata))
       )
 
       # Remove protected parameters that could break credit fulfillment
       options.delete(:mode)
+      options.delete("mode")
       options.delete(:line_items)
+      options.delete("line_items")
 
       user.payment_processor.checkout(
         mode: "payment",
@@ -202,5 +203,25 @@ module UsageCredits
         price_currency: price_currency
       }
     end
+
+    private
+
+    def merge_hash_options!(options, key)
+      values = [options.delete(key.to_s), options.delete(key)].compact
+      values.each_with_object(ActiveSupport::HashWithIndifferentAccess.new) do |value, merged|
+        unless value.respond_to?(:to_h)
+          raise ArgumentError, "#{key} must be hash-like"
+        end
+
+        merged.merge!(value.to_h.with_indifferent_access)
+      end
+    end
+
+    def normalize_whole_number!(amount, name, minimum:)
+      amount = amount.to_i if amount.is_a?(UsageCredits::Cost::Fixed)
+      value = Wallets::WholeNumber.parse(amount, name: name)
+      raise ArgumentError, "#{name} must be at least #{minimum}" if value < minimum
+      value
+    end
   end
 end

data/lib/usage_credits/models/credit_subscription_plan.rb

@@ -10,12 +10,12 @@ module UsageCredits
   # @see PaySubscriptionExtension for the actual credit fulfillment logic
   class CreditSubscriptionPlan
     attr_reader :name,
-                :processor_plan_ids,
-                :fulfillment_period, :credits_per_period,
-                :signup_bonus_credits, :trial_credits,
-                :rollover_enabled,
-                :expire_credits_on_cancel, :credit_expiration_period,
-                :metadata
+      :processor_plan_ids,
+      :fulfillment_period, :credits_per_period,
+      :signup_bonus_credits, :trial_credits,
+      :rollover_enabled,
+      :expire_credits_on_cancel, :credit_expiration_period,
+      :metadata
 
     attr_writer :fulfillment_period
 
@@ -41,23 +41,23 @@ module UsageCredits
     # Set base credits given each period
     def gives(amount)
       if amount.is_a?(UsageCredits::Cost::Fixed)
-        @credits_per_period = amount.amount
+        @credits_per_period = normalize_whole_number!(amount.amount, "Credits per period", minimum: 0)
         @fulfillment_period = UsageCredits::PeriodParser.normalize_period(amount.period || 1.month)
         self
       else
-        @credits_per_period = amount.to_i
+        @credits_per_period = normalize_whole_number!(amount, "Credits per period", minimum: 0)
         CreditGiver.new(self)
       end
     end
 
     # One-time signup bonus credits
     def signup_bonus(amount)
-      @signup_bonus_credits = amount.to_i
+      @signup_bonus_credits = normalize_whole_number!(amount, "Signup bonus credits", minimum: 0)
     end
 
     # Credits given during trial period
     def trial_includes(amount)
-      @trial_credits = amount.to_i
+      @trial_credits = normalize_whole_number!(amount, "Trial credits", minimum: 0)
     end
 
     # Configure whether unused credits roll over between periods
@@ -75,6 +75,12 @@ module UsageCredits
     # @param duration [ActiveSupport::Duration, nil] Grace period before credits expire
     # @return [void]
     def expire_after(duration)
+      unless duration.nil?
+        seconds = duration.is_a?(ActiveSupport::Duration) ? duration.value : duration
+        seconds = Wallets::WholeNumber.parse(seconds, name: "Credit expiration period")
+        raise ArgumentError, "Credit expiration period cannot be negative" if seconds.negative?
+      end
+
       @expire_credits_on_cancel = true
       @credit_expiration_period = duration
     end
@@ -170,7 +176,7 @@ module UsageCredits
       ids = plan_id_for(:stripe)
       return {} if ids.nil?
       return ids if ids.is_a?(Hash)
-      { default: ids } # Wrap single ID in hash for consistency
+      {default: ids} # Wrap single ID in hash for consistency
     end
 
     # Check if this plan matches a given processor price ID
@@ -180,7 +186,7 @@ module UsageCredits
     def matches_processor_id?(processor_id)
       processor_plan_ids.values.any? do |ids|
         if ids.is_a?(Hash)
-          ids.values.include?(processor_id)
+          ids.value?(processor_id)
         else
           ids == processor_id
         end
@@ -202,15 +208,18 @@ module UsageCredits
     #   plan.create_checkout_session(user, success_url: "/success", cancel_url: "/cancel", period: :year)
     def create_checkout_session(user, success_url:, cancel_url:, processor: :stripe, period: nil)
       raise ArgumentError, "User must respond to payment_processor" unless user.respond_to?(:payment_processor)
+      raise ArgumentError, "User must have a payment processor" unless user.payment_processor
       raise ArgumentError, "No fulfillment period configured for plan: #{name}" unless fulfillment_period
 
+      processor = processor.to_sym
+
       plan_ids = plan_id_for(processor)
       raise ArgumentError, "No #{processor.to_s.titleize} plan ID configured for plan: #{name}" unless plan_ids
 
       # Determine which price ID to use
       plan_id = if plan_ids.is_a?(Hash)
         # Multi-period plan: period is required
-        raise ArgumentError, "This plan has multiple billing periods (#{plan_ids.keys.join(', ')}). Please specify period: parameter (e.g., period: :month)" if period.nil?
+        raise ArgumentError, "This plan has multiple billing periods (#{plan_ids.keys.join(", ")}). Please specify period: parameter (e.g., period: :month)" if period.nil?
         plan_ids[period.to_sym] || raise(ArgumentError, "Period #{period.inspect} not found. Available periods: #{plan_ids.keys.inspect}")
       else
         # Single-price plan: use the ID directly
@@ -251,6 +260,10 @@ module UsageCredits
     end
 
     def create_stripe_checkout_session(user, plan_id, success_url, cancel_url)
+      processor_metadata = UsageCredits::ProcessorMetadata.normalize(
+        base_metadata.merge(processor_plan: plan_id)
+      )
+
       user.payment_processor.checkout(
         mode: "subscription",
         line_items: [{
@@ -259,7 +272,7 @@ module UsageCredits
         }],
         success_url: success_url,
         cancel_url: cancel_url,
-        subscription_data: { metadata: base_metadata }
+        subscription_data: {metadata: processor_metadata}
       )
     end
 
@@ -278,6 +291,15 @@ module UsageCredits
       }
     end
 
+    private
+
+    def normalize_whole_number!(amount, name, minimum:)
+      amount = amount.to_i if amount.is_a?(UsageCredits::Cost::Fixed)
+      value = Wallets::WholeNumber.parse(amount, name: name)
+      raise ArgumentError, "#{name} must be at least #{minimum}" if value < minimum
+      value
+    end
+
     # =========================================
     # DSL Helper Classes
     # =========================================
@@ -300,6 +322,5 @@ module UsageCredits
         @plan
       end
     end
-
   end
 end

data/lib/usage_credits/models/fulfillment.rb

@@ -5,51 +5,38 @@ module UsageCredits
   # 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
+    include Wallets::HasMetadata
+
     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
+    validates :source_id, uniqueness: {scope: :source_type}, if: :source_id?
+    validates :source_type, presence: true, if: :source_id?
+    validates :source_id, presence: true, if: :source_type?
+    validates :credits_last_fulfillment,
+      presence: true,
+      numericality: {only_integer: true, greater_than_or_equal_to: 0}
+    validates :fulfillment_type,
+      presence: true,
+      inclusion: {in: %w[subscription credit_pack manual]}
     validate :valid_fulfillment_period_format, if: :fulfillment_period?
-    validates :next_fulfillment_at, comparison: { greater_than: :last_fulfilled_at },
+    validates :next_fulfillment_at, comparison: {greater_than: :last_fulfilled_at},
       if: -> { recurring? && last_fulfilled_at.present? && next_fulfillment_at.present? }
 
-    # =========================================
-    # Metadata Handling
-    # =========================================
-
-    # Sync in-place modifications to metadata before saving
-    before_save :sync_metadata_cache
-
-    # Get metadata with indifferent access (string/symbol keys)
-    # Returns empty hash if nil (for MySQL compatibility where JSON columns can't have defaults)
-    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
-
-    # Clear metadata cache on reload to ensure fresh data from database
-    def reload(*)
-      @indifferent_metadata = nil
-      super
-    end
-
     # 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")
+      table = arel_table
+      where(table[:next_fulfillment_at].lteq(Time.current))
+        .where(table[:stops_at].eq(nil).or(table[:stops_at].gt(Time.current)))
+        .where(table[:last_fulfilled_at].eq(nil).or(table[:next_fulfillment_at].gt(table[:last_fulfilled_at])))
+    }
+    scope :active, -> {
+      table = arel_table
+      where(table[:stops_at].eq(nil).or(table[:stops_at].gt(Time.current)))
     }
-    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 }
@@ -83,26 +70,15 @@ module UsageCredits
       # 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 = (next_fulfillment_at > Time.current) ? next_fulfillment_at : Time.current
 
-      base_time + UsageCredits::PeriodParser.parse_period(fulfillment_period)
+      base_time + UsageCredits::PeriodParser.parse_persisted_period(fulfillment_period)
     end
 
     private
 
-    # Sync in-place modifications to the cached metadata back to the attribute
-    # This ensures changes like `metadata["key"] = "value"` are persisted on save
-    # Also ensures metadata is never null for MySQL compatibility (JSON columns can't have defaults)
-    def sync_metadata_cache
-      if @indifferent_metadata
-        write_attribute(:metadata, @indifferent_metadata.to_h)
-      elsif read_attribute(:metadata).nil?
-        write_attribute(:metadata, {})
-      end
-    end
-
     def valid_fulfillment_period_format
-      unless UsageCredits::PeriodParser.valid_period_format?(fulfillment_period)
+      unless UsageCredits::PeriodParser.valid_persisted_period_format?(fulfillment_period)
         errors.add(:fulfillment_period, "must be in format like '2.months' or '15.days' and use supported units")
       end
     end
@@ -122,6 +98,5 @@ module UsageCredits
         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

@@ -3,11 +3,10 @@
 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
+      :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
@@ -61,16 +60,9 @@ module UsageCredits
       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
+      # `costs` wraps every configured value (including a Proc) in a Cost
+      # object, so there is one calculation/validation path here.
+      total = cost_calculator.calculate(normalized_params)
 
       # Apply configured rounding strategy
       CreditCalculator.apply_rounding(total)
@@ -92,7 +84,7 @@ module UsageCredits
         begin
           result = condition.call(normalized)
           raise InvalidOperation, message unless result
-        rescue StandardError => e
+        rescue => e
           raise InvalidOperation, "Validation error: #{e.message}"
         end
       end
@@ -103,10 +95,12 @@ module UsageCredits
     # =========================================
 
     # Create an audit record of this operation
-    def to_audit_hash(params = {})
+    def to_audit_hash(params = nil, cost: nil, **keyword_params)
+      params = (params || {}).merge(keyword_params)
+
       {
         operation: name,
-        cost: calculate_cost(params),
+        cost: cost.nil? ? calculate_cost(params) : cost,
         params: params,
         metadata: metadata,
         executed_at: Time.current,
@@ -128,19 +122,23 @@ module UsageCredits
 
       # 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
+        normalize_quantity(params[:mb], :mb)
+      elsif params[:kb]
+        normalize_quantity(params[:kb], :kb) / 1024.0
+      elsif params[:gb]
+        normalize_quantity(params[:gb], :gb) * 1024.0
+      elsif params[:size_mb]
+        normalize_quantity(params[:size_mb], :size_mb)
+      elsif params[:size_megabytes]
+        normalize_quantity(params[:size_megabytes], :size_megabytes)
+      elsif params[:size]
+        normalize_quantity(params[:size], :size) / 1.megabyte
+      else
+        0.0
+      end
 
       # Handle generic unit-based operations
-      units = params[:units].to_f if params[:units]
+      units = normalize_quantity(params[:units], :units) if params[:units]
 
       params.merge(
         size: (size * 1.megabyte).to_i,   # Raw bytes
@@ -149,5 +147,15 @@ module UsageCredits
       )
     end
 
+    def normalize_quantity(value, name)
+      number = Float(value)
+      unless number.finite? && !number.negative?
+        raise ArgumentError, "#{name} must be a finite, non-negative number"
+      end
+
+      number
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "#{name} must be a finite, non-negative number"
+    end
   end
 end