usage_credits 0.1.0

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

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # Extension to Pay::Subscription to refill user credits
+  # (and/or set up the `Fulfillment` object that the `UsageCredits::FulfillmentJob` will pick up to refill periodically)
+  #
+  # We'll:
+  #   1) Immediately award trial or first-cycle credits on create
+  #   2) Create or update a Fulfillment record for future awarding (the fulfillment job will actually do fulfillment)
+  #   3) Expire leftover credits on cancellation if needed
+  #
+  # Explanation:
+  #
+  # `after_commit :handle_initial_award_and_fulfillment_setup, on: :create`
+  #   If the subscription is trialing or active, do immediate awarding and create a Fulfillment for future recurring awarding.
+  #
+  # Fulfillment
+  #   Has next_fulfillment_at set to (Time.current + 1.month), or whenever the first real billing cycle is.
+  #
+  # `update_fulfillment_on_cancellation`
+  #   If the user cancels, we set fulfillment.stops_at = ends_at, so no further awarding is done.
+  #   Optionally we can also forcibly expire leftover credits.
+  #
+  # That’s it. Everything else—like “monthly awarding,” “rollover credits,” etc.—should be handled by the
+  # `FulfillmentService#process` method, which checks the plan’s config to decide how many credits to add next time around.
+
+  # If the subscription is trialing or active, do immediate awarding and create a Fulfillment for future recurring awarding.
+  module PaySubscriptionExtension
+    extend ActiveSupport::Concern
+
+    included do
+      # For initial setup and fulfillment, we can't do after_create or on: :create because the subscription first may
+      # get created with status "incomplete" and only get updated to status "active" when the payment is cleared
+      after_commit :handle_initial_award_and_fulfillment_setup
+
+      after_commit :update_fulfillment_on_renewal,        if: :subscription_renewed?
+      after_commit :update_fulfillment_on_cancellation,   if: :subscription_canceled?
+
+      # TODO: handle plan changes (upgrades / downgrades)
+      # TODO: handle paused subscriptions (may still have an "active" status?)
+    end
+
+    # Identify the usage_credits plan object
+    def credit_subscription_plan
+      @credit_subscription_plan ||= UsageCredits.configuration.find_subscription_plan_by_processor_id(processor_plan)
+    end
+
+    def provides_credits?
+      credit_subscription_plan.present?
+    end
+
+    def fullfillment_should_stop_at
+      (ends_at || current_period_end)
+    end
+
+    private
+
+    # Returns true if the subscription 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 credits_already_fulfilled?
+      # TODO: There's a race condition where Pay actually updates the subscription two times on initial creation,
+      # leading to us triggering handle_initial_award_and_fulfillment_setup twice too.
+      # Since no Fulfillment record has been created yet, both callbacks will try to create the same Fulfillment object
+      # at about the same time, thus making this check useless (there's nothing written to the DB yet)
+      # For now, we handle it by adding a validation to the Fulfillment model so that there's no two Fulfillment objects
+      # with the same source_id -- so whichever of the two callbacks gets processed first wins, the other just fails.
+      # That's how we prevent double credit awarding for now, but this race condition should be handled more elegantly.
+      UsageCredits::Fulfillment.exists?(source: self)
+    end
+
+    def subscription_renewed?
+      (saved_change_to_ends_at? || saved_change_to_current_period_end?) && status == "active"
+    end
+
+    # This doesn't get called the exact moment the user cancels its subscription, but at the end of the period,
+    # when the payment processor sends the event that the subscription has actually been cancelled.
+    # For the moment the user clicks on "Cancel subscription", the sub keeps its state as "active" (for now),
+    # the sub just gets its `ends_at` set from nil to the actual cancellation date.
+    def subscription_canceled?
+      saved_change_to_status? && status == "canceled"
+    end
+
+    # =========================================
+    # Actual fulfillment logic
+    # =========================================
+
+    # Immediate awarding of first cycle + set up Fulfillment object for subsequent periods
+    def handle_initial_award_and_fulfillment_setup
+      return unless provides_credits?
+      return unless has_valid_wallet?
+
+      # We only do immediate awarding if the subscription is trialing or active
+      return unless ["trialing", "active"].include?(status)
+
+      # We'll skip if we already have a fulfillment record
+      return if credits_already_fulfilled?
+
+      plan = credit_subscription_plan
+      wallet = customer.owner.credit_wallet
+
+      # Using the configured grace period
+      credits_expire_at = !plan.rollover_enabled ? (created_at + plan.parsed_fulfillment_period + UsageCredits.configuration.fulfillment_grace_period) : nil
+
+      Rails.logger.info "Fulfilling initial credits for subscription #{id}"
+      Rails.logger.info "  Status: #{status}"
+      Rails.logger.info "  Plan: #{plan}"
+
+      # Transaction for atomic awarding + fulfillment creation
+      ActiveRecord::Base.transaction do
+
+        total_credits_awarded = 0
+        transaction_ids = []
+
+        # 1) If this is a trial and not an active subscription: award trial credits, if any
+        if status == "trialing" && plan.trial_credits.positive?
+
+          # Immediate awarding of trial credits
+          transaction = wallet.add_credits(plan.trial_credits,
+            category: "subscription_trial",
+            expires_at: trial_ends_at,
+            metadata: {
+              subscription_id: id,
+              reason: "initial_trial_credits",
+              plan: processor_plan,
+              fulfilled_at: Time.current
+            }
+          )
+          transaction_ids << transaction.id
+          total_credits_awarded += plan.trial_credits
+
+        elsif status == "active"
+
+          # Awarding of signup bonus, if any
+          if plan.signup_bonus_credits.positive?
+            transaction = wallet.add_credits(plan.signup_bonus_credits,
+              category: "subscription_signup_bonus",
+              metadata: {
+                subscription_id: id,
+                reason: "signup_bonus",
+                plan: processor_plan,
+                fulfilled_at: Time.current
+              }
+            )
+            transaction_ids << transaction.id
+            total_credits_awarded += plan.signup_bonus_credits
+          end
+
+          # Actual awarding of the subscription credits
+          if plan.credits_per_period.positive?
+            transaction = wallet.add_credits(plan.credits_per_period,
+              category: "subscription_credits",
+              expires_at: credits_expire_at,  # This will be nil if credit rollover is enabled
+              metadata: {
+                subscription_id: id,
+                reason: "first_cycle",
+                plan: processor_plan,
+                fulfilled_at: Time.current
+              }
+            )
+            transaction_ids << transaction.id
+            total_credits_awarded += plan.credits_per_period
+          end
+        end
+
+        # 2) Create a Fulfillment record for subsequent awarding
+        # Use current_period_start as the base time, falling back to created_at
+        period_start = if trial_ends_at && status == "trialing"
+                      trial_ends_at
+                    else
+                      current_period_start || created_at
+                    end
+
+        # Ensure next_fulfillment_at is in the future
+        next_fulfillment_at = period_start + plan.parsed_fulfillment_period
+        next_fulfillment_at = Time.current + plan.parsed_fulfillment_period if next_fulfillment_at <= Time.current
+
+        fulfillment = UsageCredits::Fulfillment.create!(
+          wallet: wallet,
+          source: self,
+          fulfillment_type: "subscription",
+          credits_last_fulfillment: total_credits_awarded,
+          fulfillment_period: plan.fulfillment_period_display,
+          last_fulfilled_at: Time.now,
+          next_fulfillment_at: next_fulfillment_at,
+          stops_at: fullfillment_should_stop_at, # Pre-emptively set when the fulfillment will stop, in case we miss a future event (like sub cancellation)
+          metadata: {
+            subscription_id: id,
+            plan: processor_plan,
+          }
+        )
+
+        # Link created transactions to the fulfillment object for traceability
+        UsageCredits::Transaction.where(id: transaction_ids).update_all(fulfillment_id: fulfillment.id)
+
+        Rails.logger.info "Initial fulfillment for subscription #{id} finished. Created fulfillment #{fulfillment.id}"
+      rescue => e
+        Rails.logger.error "Failed to fulfill initial credits for subscription #{id}: #{e.message}"
+        raise ActiveRecord::Rollback
+      end
+    end
+
+    # Handle subscription renewal (we received a new payment for another billing period)
+    # Each time the subscription renews and ends_at moves forward,
+    # we keep awarding credits because Fulfillment#stops_at also moves forward
+    def update_fulfillment_on_renewal
+      return unless provides_credits? && has_valid_wallet?
+
+      fulfillment = UsageCredits::Fulfillment.find_by(source: self)
+      return unless fulfillment
+
+      ActiveRecord::Base.transaction do
+        # Subscription renewed, we can set the new Fulfillment stops_at to the extended date
+        fulfillment.update!(stops_at: fullfillment_should_stop_at)
+        Rails.logger.info "Fulfillment #{fulfillment.id} stops_at updated to #{fulfillment.stops_at}"
+      rescue => e
+        Rails.logger.error "Failed to extend fulfillment period for subscription #{id}: #{e.message}"
+        raise ActiveRecord::Rollback
+      end
+    end
+
+
+    # If the subscription is canceled, let's set the Fulfillment's stops_at so that the job won't keep awarding
+    def update_fulfillment_on_cancellation
+      plan = credit_subscription_plan
+      return unless plan && has_valid_wallet?
+
+      fulfillment = UsageCredits::Fulfillment.find_by(source: self)
+      return unless fulfillment
+
+      ActiveRecord::Base.transaction do
+        # Subscription cancelled, so stop awarding credits in the future
+        fulfillment.update!(stops_at: fullfillment_should_stop_at)
+        Rails.logger.info "Fulfillment #{fulfillment.id} stops_at set to #{fulfillment.stops_at} due to cancellation"
+      rescue => e
+        Rails.logger.error "Failed to stop credit fulfillment for subscription #{id}: #{e.message}"
+        raise ActiveRecord::Rollback
+      end
+
+      # TODO: we can also expire already awarded credits here (without making the ledger mutable – we'll need to
+      # check if the plan expires credits or not, and if rollover we may need to add a negative transaction to offset
+      # the remaining balance)
+
+    end
+
+  end
+end

data/lib/usage_credits/models/credit_pack.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # A DSL to define credit packs that users can buy as one-time purchases.
+  #
+  # Credit packs can be purchased independently and separately from any subscription.
+  #
+  # The actual credit fulfillment is handled by the PayChargeExtension.
+  #
+  # @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
+
+    def initialize(name)
+      @name = name
+      @credits = 0
+      @bonus_credits = 0
+      @price_cents = 0
+      @price_currency = UsageCredits.configuration.default_currency.to_s.upcase
+      @metadata = {}
+    end
+
+    # =========================================
+    # DSL Methods (used in initializer blocks)
+    # =========================================
+
+    # Set the base number of credits
+    def gives(amount)
+      @credits = amount.to_i
+    end
+
+    # Set bonus credits (e.g., for promotions)
+    def bonus(amount)
+      @bonus_credits = amount.to_i
+    end
+
+    # Set the price in cents (e.g., 4900 for $49.00)
+    def costs(cents)
+      @price_cents = cents
+    end
+    alias_method :cost, :costs
+
+    # Set the currency (defaults to configuration)
+    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(', ')}"
+      end
+      @price_currency = currency.to_s.upcase
+    end
+
+    # Add custom metadata
+    def meta(hash)
+      @metadata.merge!(hash.transform_keys(&:to_sym))
+    end
+
+    # =========================================
+    # Validation
+    # =========================================
+
+    def validate!
+      raise ArgumentError, "Name can't be blank" if name.blank?
+      raise ArgumentError, "Credits must be greater than 0" unless credits.to_i.positive?
+      raise ArgumentError, "Bonus credits must be greater than or equal to 0" if bonus_credits.to_i.negative?
+      raise ArgumentError, "Price must be greater than 0" unless price_cents.to_i.positive?
+      raise ArgumentError, "Currency can't be blank" if price_currency.blank?
+      # raise ArgumentError, "Price must be in whole cents ($49 = 4900)" if price_cents % 100 != 0 # Payment processors should handle this anyways
+      true
+    end
+
+    # =========================================
+    # Credit & Price Calculations
+    # =========================================
+
+    # Get total credits (including bonus)
+    def total_credits
+      credits + bonus_credits
+    end
+
+    # Get price in dollars
+    def price
+      price_cents / 100.0
+    end
+
+    # Get formatted price (e.g., "49.00 USD")
+    def formatted_price
+      format("%.2f %s", price, price_currency)
+    end
+
+    # Get credits per dollar ratio (for comparison)
+    def credits_per_dollar
+      return 0 if price.zero?
+      total_credits / price
+    end
+
+    # =========================================
+    # Display Formatting
+    # =========================================
+
+    def display_credits
+      if bonus_credits.positive?
+        "#{credits} + #{bonus_credits} bonus credits"
+      else
+        "#{credits} credits"
+      end
+    end
+    alias_method :display_description, :display_credits
+
+    def display_name
+      "#{name.to_s.titleize} pack"
+    end
+
+    # Generate human-friendly button text for purchase links
+    def button_text
+      "Get #{display_credits} for #{formatted_price}"
+    end
+
+    # =========================================
+    # Payment Integration
+    # =========================================
+
+    # Create a Stripe Checkout session for this pack
+    def create_checkout_session(user)
+      raise ArgumentError, "User must have a payment processor" unless user.respond_to?(:payment_processor) && user.payment_processor
+
+      user.payment_processor.checkout(
+        mode: "payment",
+        line_items: [{
+          price_data: {
+            currency: price_currency.downcase,
+            unit_amount: price_cents,
+            product_data: {
+              name: display_name,
+              description: display_description
+            }
+          },
+          quantity: 1
+        }],
+        payment_intent_data: { metadata: base_metadata },
+        metadata: base_metadata
+      )
+    end
+
+    def base_metadata
+      {
+        purchase_type: "credit_pack",
+        pack_name: name,
+        credits: credits,
+        bonus_credits: bonus_credits,
+        price_cents: price_cents,
+        price_currency: price_currency
+      }
+    end
+  end
+end

data/lib/usage_credits/models/credit_subscription_plan.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module UsageCredits
+  # A DSL to define subscription plans that give credits to users on a recurring basis.
+  #
+  # The actual credit fulfillment is handled by the PaySubscriptionExtension,
+  # which monitors subscription events (creation, renewal, etc) and adds
+  # credits to the user's wallet accordingly.
+  #
+  # @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
+
+    attr_writer :fulfillment_period
+
+    MIN_PERIOD = 1.day
+
+    def initialize(name)
+      @name = name
+      @processor_plan_ids = {}  # Store processor-specific plan IDs
+      @fulfillment_period = nil
+      @credits_per_period = 0
+      @signup_bonus_credits = 0
+      @trial_credits = 0
+      @rollover_enabled = false
+      @expire_credits_on_cancel = false
+      @credit_expiration_period = nil
+      @metadata = {}
+    end
+
+    # =========================================
+    # DSL Methods (used in initializer blocks)
+    # =========================================
+
+    # Set base credits given each period
+    def gives(amount)
+      if amount.is_a?(UsageCredits::Cost::Fixed)
+        @credits_per_period = amount.amount
+        @fulfillment_period = UsageCredits::PeriodParser.normalize_period(amount.period || 1.month)
+        self
+      else
+        @credits_per_period = amount.to_i
+        CreditGiver.new(self)
+      end
+    end
+
+    # One-time signup bonus credits
+    def signup_bonus(amount)
+      @signup_bonus_credits = amount.to_i
+    end
+
+    # Credits given during trial period
+    def trial_includes(amount)
+      @trial_credits = amount.to_i
+    end
+
+    # Configure whether unused credits roll over between periods
+    def unused_credits(behavior)
+      @rollover_enabled = (behavior == :rollover)
+    end
+
+    # Configure credit expiration after subscription cancellation
+    #
+    # When a subscription is cancelled, you can control what happens to remaining credits:
+    # 1. By default (if this is not called), users keep their credits forever
+    # 2. If called with a duration, credits expire after that grace period
+    # 3. If called with nil/0, credits expire immediately on cancellation
+    #
+    # @param duration [ActiveSupport::Duration, nil] Grace period before credits expire
+    # @return [void]
+    def expire_after(duration)
+      @expire_credits_on_cancel = true
+      @credit_expiration_period = duration
+    end
+
+    # Add custom metadata
+    def meta(hash)
+      @metadata.merge!(hash)
+    end
+
+    # =========================================
+    # Payment Processor Integration
+    # =========================================
+
+    # Set the processor-specific plan ID
+    def processor_plan(processor, id)
+      processor_plan_ids[processor.to_sym] = id
+    end
+
+    # Get the plan ID for a specific processor
+    def plan_id_for(processor)
+      processor_plan_ids[processor.to_sym]
+    end
+
+    # Shorthand for Stripe price ID
+    def stripe_price(id = nil)
+      if id.nil?
+        plan_id_for(:stripe) # getter
+      else
+        processor_plan(:stripe, id) # setter
+      end
+    end
+
+    # Create a checkout session for this subscription plan
+    def create_checkout_session(user, success_url:, cancel_url:, processor: :stripe)
+      raise ArgumentError, "User must respond to payment_processor" unless user.respond_to?(:payment_processor)
+      raise ArgumentError, "No fulfillment period configured for plan: #{name}" unless fulfillment_period
+
+      plan_id = plan_id_for(processor)
+      raise ArgumentError, "No #{processor.to_s.titleize} plan ID configured for plan: #{name}" unless plan_id
+
+      case processor
+      when :stripe
+        create_stripe_checkout_session(user, plan_id, success_url, cancel_url)
+      else
+        raise ArgumentError, "Unsupported payment processor: #{processor}"
+      end
+    end
+
+    # =========================================
+    # Validation
+    # =========================================
+
+    def validate!
+      raise ArgumentError, "Name can't be blank" if name.blank?
+      raise ArgumentError, "Credits per period must be greater than 0" unless credits_per_period.to_i.positive?
+      raise ArgumentError, "Fulfillment period must be set" if fulfillment_period.nil?
+      raise ArgumentError, "Signup bonus credits must be greater than or equal to 0" if signup_bonus_credits.to_i.negative?
+      raise ArgumentError, "Trial credits must be greater than or equal to 0" if trial_credits.to_i.negative?
+      true
+    end
+
+    # =========================================
+    # Helper Methods
+    # =========================================
+
+    def fulfillment_period_display
+      fulfillment_period.is_a?(ActiveSupport::Duration) ? fulfillment_period.inspect : fulfillment_period
+    end
+
+    def parsed_fulfillment_period
+      UsageCredits::PeriodParser.parse_period(@fulfillment_period)
+    end
+
+    def create_stripe_checkout_session(user, plan_id, success_url, cancel_url)
+      user.payment_processor.checkout(
+        mode: "subscription",
+        line_items: [{
+          price: plan_id,
+          quantity: 1
+        }],
+        success_url: success_url,
+        cancel_url: cancel_url,
+        payment_intent_data: { metadata: base_metadata },
+        subscription_data: { metadata: base_metadata }
+      )
+    end
+
+    def base_metadata
+      {
+        purchase_type: "credit_subscription",
+        subscription_name: name,
+        fulfillment_period: fulfillment_period_display,
+        credits_per_period: credits_per_period,
+        signup_bonus_credits: signup_bonus_credits,
+        trial_credits: trial_credits,
+        rollover_enabled: rollover_enabled,
+        expire_credits_on_cancel: expire_credits_on_cancel,
+        credit_expiration_period: credit_expiration_period&.to_i,
+        metadata: metadata
+      }
+    end
+
+    # =========================================
+    # DSL Helper Classes
+    # =========================================
+
+    # CreditGiver is a helper class that enables the DSL within `subscription_plan` blocks to define credit amounts.
+    #
+    # This is what allows us to write:
+    #   gives 10_000.credits.every(:month)
+    #
+    # Instead of:
+    #   set_credits(10_000)
+    #   set_period(:month)
+    class CreditGiver
+      def initialize(plan)
+        @plan = plan
+      end
+
+      def every(period)
+        @plan.fulfillment_period = UsageCredits::PeriodParser.normalize_period(period)
+        @plan
+      end
+    end
+
+  end
+end