core_merchant 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 154e94061339edca03a2e9c88630c4e49ce37272252e5d6436810579ea2bd529
-  data.tar.gz: 5fe4eb2a4c24b26945a505f35d9a7694de69e7630c03776ac78b7dcd6671616b
+  metadata.gz: 2bd7b45750d9491ddf78c12b41e73a1d79d8bc6fa5cdff69df22f536b1765e42
+  data.tar.gz: 056e3021e60c7c5edb4a301dae4a29b6184ad3889b55c81e226dccfcfcb00020
 SHA512:
-  metadata.gz: 9debecdb722370c173fc97648d5f38e130e95475edb673d5f420b7074db10dfad908221cb2b2a1dec966be064fa07040a4ad287ab10380741cd9d9df27f8d618
-  data.tar.gz: 6d5675f20dfa56f708026a28f64cb48dcc44792f6e2663a13e1c466867defb2120f5947f84db8314d983246ef511bac2ce434aa3956fc621bdaf9cdd12b4a04c
+  metadata.gz: f916fe4fb53d28a9fbb61c8d7306825cb96d82ceeb559a6aeea1373c83e5401c785c0400dd3b41f0d5f9a4c321f0cc91c85eddead5808d546c7fb09d6b671aa7
+  data.tar.gz: 218935fdbb73a113262735e5b4a0290d7942121b167932ad00a5ead4c1a75ef69d8f18dfffca5fea14aafbbb8bf79f6cb940042f15f0989a59ce1e6c14a58208

data/.rubocop.yml

@@ -12,6 +12,9 @@ Style/StringLiteralsInInterpolation:
 Layout/LineLength:
   Max: 120
 
+Metrics/MethodLength:
+  Max: 16
+
 # Disable frozen string literals for lib/generators/**
 FrozenStringLiteralComment:
   Exclude:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    core_merchant (0.6.2)
+    core_merchant (0.8.0)
       activesupport (~> 7.0)
       rails (~> 7.0)
 

data/lib/core_merchant/concerns/subscription_manager_renewals.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module CoreMerchant
+  module Concerns
+    # Includes logic for renewal processing, grace period handling, and expiration checking.
+    module SubscriptionManagerRenewals
+      extend ActiveSupport::Concern
+
+      included do # rubocop:disable Metrics/BlockLength
+        def check_renewals
+          Subscription.find_each do |subscription|
+            process_for_renewal(subscription) if subscription.due_for_renewal?
+          end
+        end
+
+        def process_for_renewal(subscription)
+          return unless subscription.transition_to_processing_renewal
+
+          notify(subscription, :due_for_renewal)
+        end
+
+        def no_payment_needed_for_renewal(subscription)
+          return unless subscription.transition_to_active
+
+          notify(subscription, :renewed)
+        end
+
+        def processing_payment_for_renewal(subscription)
+          return unless subscription.transition_to_processing_payment
+
+          notify(subscription, :renewal_payment_processing)
+        end
+
+        def payment_successful_for_renewal(subscription)
+          return unless subscription.transition_to_active
+
+          notify(subscription, :renewed)
+        end
+
+        def payment_failed_for_renewal(subscription)
+          is_in_grace_period = subscription.in_grace_period?
+          if is_in_grace_period
+            subscription.transition_to_past_due
+            notify(subscription, :grace_period_started, days_remaining: subscription.days_remaining_in_grace_period)
+          else
+            subscription.transition_to_expired
+            notify(subscription, :expired)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/core_merchant/concerns/subscription_notifications.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module CoreMerchant
+  module Concerns
+    # Includes logic for notifying the SubscriptionManager when a subscription is created or destroyed,
+    # as well as providing a hook for custom notification logic.
+    module SubscriptionNotifications
+      extend ActiveSupport::Concern
+
+      included do
+        # Notify SubscriptionManager on creation and destruction.
+        after_create { notify_subscription_manager(:created) }
+        after_destroy { notify_subscription_manager(:destroyed) }
+
+        def notify_subscription_manager(event, **options)
+          CoreMerchant.subscription_manager.notify(self, event, **options)
+        end
+      end
+    end
+  end
+end

data/lib/core_merchant/concerns/subscription_state_machine.rb

@@ -9,26 +9,29 @@ module CoreMerchant
     # Adds state machine logic to a subscription.
     # This module defines the possible states and transitions for a subscription.
     # Possible transitions:
-    # - `pending` -> `active`, `trial`
-    # - `trial` -> `active`, `pending_cancellation`, `canceled`
-    # - `active` -> `pending_cancellation`, `canceled`, `expired`
+    # - `pending` -> `active`, `trial`, `processing_renewal`
+    # - `trial` -> `processing_renewal`, `active`, `canceled`, `pending_cancellation`, `expired`
+    # - `active` -> `pending_cancellation`, `canceled`, `expired`, `processing_renewal`
+    # - `past_due` -> `processing_renewal`
     # - `pending_cancellation` -> `canceled`, `expired`
-    # - `canceled` -> `pending`, `active`
-    # - `expired` -> `pending`, `active`
+    # - `processing_renewal` -> `processing_payment`, `active`, `expired`, `past_due`
+    # - `processing_payment` -> `active`, `expired`, `canceled`, `past_due`
+    # - `canceled` -> `pending`, `processing_renewal`
+    # - `expired` -> `pending`, `processing_renewal`
     module SubscriptionStateMachine
       extend ActiveSupport::Concern
 
       # List of possible transitions in the form of { to_state: [from_states] }
       POSSIBLE_TRANSITIONS = {
         pending: %i[canceled expired],
-        trial: %i[pending],
-        active: %i[pending trial canceled expired],
+        trial: [:pending],
+        active: %i[pending trial processing_renewal processing_payment],
+        past_due: %i[active processing_renewal processing_payment],
         pending_cancellation: %i[active trial],
-        canceled: %i[active pending_cancellation trial],
-        expired: %i[active pending_cancellation canceled trial],
-        past_due: [],
-        paused: [],
-        pending_change: []
+        processing_renewal: %i[pending trial active past_due canceled expired],
+        processing_payment: [:processing_renewal],
+        canceled: %i[trial active pending_cancellation processing_payment],
+        expired: %i[trial active pending_cancellation processing_renewal processing_payment]
       }.freeze
 
       included do

data/lib/core_merchant/customer_behavior.rb

@@ -6,6 +6,8 @@ module CoreMerchant
     extend ActiveSupport::Concern
 
     included do
+      has_many :subscriptions, class_name: "CoreMerchant::Subscription", as: :customer, dependent: :destroy
+
       def core_merchant_customer_id
         id
       end
@@ -17,10 +19,6 @@ module CoreMerchant
       def core_merchant_customer_name
         name if respond_to?(:name)
       end
-
-      def subscriptions
-        CoreMerchant::Subscription.where(customer_id: core_merchant_customer_id)
-      end
     end
   end
 end

data/lib/core_merchant/subscription.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "core_merchant/concerns/subscription_state_machine"
+require "core_merchant/concerns/subscription_notifications"
 
 module CoreMerchant
   # Represents a subscription in CoreMerchant.
@@ -10,8 +11,10 @@ module CoreMerchant
   # - `pending`: Subscription created but not yet started
   # - `trial`: In a trial period
   # - `active`: Currently active and paid
-  # - `past_due`: Payment failed but in grace period, not yet implemented
+  # - `past_due`: Payment failed but in grace period
   # - `pending_cancellation`: Will be canceled at period end
+  # - `processing_renewal`: Renewal in progress
+  # - `processing_payment`: Payment processing
   # - `canceled`: Canceled by user or due to payment failure
   # - `expired`: Subscription period ended
   # - `paused`: Temporarily halted, not yet implemented
@@ -51,6 +54,7 @@ module CoreMerchant
   #   ```
   class Subscription < ActiveRecord::Base
     include CoreMerchant::Concerns::SubscriptionStateMachine
+    include CoreMerchant::Concerns::SubscriptionNotifications
 
     self.table_name = "core_merchant_subscriptions"
 
@@ -61,12 +65,14 @@ module CoreMerchant
       pending: 0,
       trial: 1,
       active: 2,
-      past_due: 3, # Logic not yet implemented
-      pending_cancellation: 4,
-      canceled: 5,
-      expired: 6,
-      paused: 7, # Logic not yet implemented
-      pending_change: 8 # Logic not yet implemented
+      past_due: 10,
+      pending_cancellation: 11,
+      processing_renewal: 20,
+      processing_payment: 21,
+      canceled: 30,
+      expired: 31,
+      paused: 40, # Logic not yet implemented
+      pending_change: 50 # Logic not yet implemented
     }
 
     validates :customer, :subscription_plan, :status, :start_date, presence: true
@@ -74,27 +80,79 @@ module CoreMerchant
     validate :end_date_after_start_date, if: :end_date
     validate :canceled_at_with_reason, if: :canceled_at
 
+    # Starts the subscription.
+    # Sets the current period start and end dates based on the plan's duration.
     def start
       new_period_start = start_date
       new_period_end = new_period_start + subscription_plan.duration_in_date
 
-      transition_to_active!
-      update!(
-        current_period_start: new_period_start,
-        current_period_end: new_period_end
-      )
+      transaction do
+        transition_to_active!
+        update!(
+          current_period_start: new_period_start,
+          current_period_end: new_period_end
+        )
+      end
+
+      notify_subscription_manager(:started)
     end
 
-    def cancel(reason:, at_period_end:)
-      if at_period_end
-        transition_to_pending_cancellation!
-      else
-        transition_to_canceled!
+    # Cancels the subscription.
+    # Parameters:
+    # - `reason`: Reason for cancellation
+    # - `at_period_end`: If true, the subscription will be canceled at the end of the current period.
+    #   Otherwise, the subscription will be canceled immediately.
+    #   Default is `true`.
+    def cancel(reason:, at_period_end: true)
+      transaction do
+        if at_period_end
+          transition_to_pending_cancellation!
+        else
+          transition_to_canceled!
+        end
+        update!(
+          canceled_at: at_period_end ? current_period_end : Time.current,
+          cancellation_reason: reason
+        )
       end
-      update!(
-        canceled_at: at_period_end ? current_period_end : Time.current,
-        cancellation_reason: reason
-      )
+
+      notify_subscription_manager(:canceled, reason: reason, immediate: !at_period_end)
+    end
+
+    # Returns the days remaining in the current period.
+    # Use to show the user how many days are left before the next renewal or
+    # to refund pro-rated amounts for early cancellations.
+    def days_remaining_in_current_period
+      (current_period_end.to_date - Time.current.to_date).to_i
+    end
+
+    # Returns the number of days as a grace period for past-due subscriptions.
+    # By default, this is 3 days.
+    def grace_period
+      3.days
+    end
+
+    def grace_period_end_date
+      current_period_end + grace_period
+    end
+
+    def in_grace_period?
+      due_for_renewal? && Time.current <= grace_period_end_date
+    end
+
+    def days_remaining_in_grace_period
+      return 0 unless due_for_renewal?
+
+      (grace_period_end_date.to_date - Time.current.to_date).to_i
+    end
+
+    def grace_period_exceeded?
+      due_for_renewal? && Time.current > grace_period_end_date
+    end
+
+    def due_for_renewal?
+      (active? || trial? || past_due? || processing_renewal? || processing_payment?) &&
+        current_period_end <= Time.current
     end
 
     private

data/lib/core_merchant/subscription_listener.rb

@@ -5,10 +5,50 @@ module CoreMerchant
   module SubscriptionListener
     extend ActiveSupport::Concern
 
-    included do
+    included do # rubocop:disable Metrics/BlockLength
       def on_test_event_received
         puts "Test event received by CoreMerchant::SubscriptionListener. Override this method in your application."
       end
+
+      # rubocop:disable Metrics/LineLength
+
+      def on_subscription_created(subscription)
+        puts "Subscription (#{subscription.id}) created. Override #{__method__} in your application to handle this event."
+      end
+
+      def on_subscription_destroyed(subscription)
+        puts "Subscription (#{subscription.id}) destroyed. Override #{__method__} in your application to handle this event."
+      end
+
+      def on_subscription_started(subscription)
+        puts "Subscription (#{subscription.id}) started. Override #{__method__} in your application to handle this event."
+      end
+
+      def on_subscription_canceled(subscription, reason:, immediate:)
+        puts "Subscription (#{subscription.id}) canceled with reason '#{reason}' and immediate=#{immediate}. Override #{__method__} in your application to handle this event."
+      end
+
+      def on_subscription_due_for_renewal(subscription)
+        puts "Subscription (#{subscription.id}) is due for renewal. Override #{__method__} in your application to handle this event."
+      end
+
+      def on_subscription_grace_period_(subscription, days_remaining)
+        puts "Subscription (#{subscription.id}) has entered a grace period with #{days_remaining} days remaining. Override #{__method__} in your application to handle this event."
+      end
+
+      def on_subscription_renewed(subscription)
+        puts "Subscription (#{subscription.id}) renewed. Override #{__method__} in your application to handle this event."
+      end
+
+      def on_subscription_renewal_payment_processing(subscription)
+        puts "Subscription (#{subscription.id}) renewal payment processing. Override #{__method__} in your application to handle this event."
+      end
+
+      def on_subscription_expired(subscription)
+        puts "Subscription (#{subscription.id}) expired. Override #{__method__} in your application to handle this event."
+      end
+
+      # rubocop:enable Metrics/LineLength
     end
   end
 end

data/lib/core_merchant/subscription_manager.rb

@@ -1,21 +1,104 @@
 # frozen_string_literal: true
 
+require "core_merchant/concerns/subscription_manager_renewals"
+
 module CoreMerchant
   # Manages subscriptions in CoreMerchant.
+  # This class is responsible for notifying listeners when subscription events occur.
+  # Attributes:
+  #   - `listeners` - An array of listeners that will be notified when subscription events occur.
   class SubscriptionManager
+    include Concerns::SubscriptionManagerRenewals
+
     attr_reader :listeners
 
     def initialize
       @listeners = []
     end
 
+    def check_subscriptions
+      check_renewals
+    end
+
     def add_listener(listener)
       @listeners << listener
     end
 
+    def notify(subscription, event, **options) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+      case event
+      when :created
+        notify_subscription_created(subscription)
+      when :destroyed
+        notify_subscription_destroyed(subscription)
+      when :started
+        notify_subscription_started(subscription)
+      when :canceled
+        notify_subscription_canceled(subscription, options[:reason], options[:immediate])
+      when :due_for_renewal
+        notify_subscription_due_for_renewal(subscription)
+      when :renewed
+        notify_subscription_renewed(subscription)
+      when :renewal_payment_processing
+        notify_subscription_renewal_payment_processing(subscription)
+      when :grace_period_started
+        notify_subscription_grace_period_started(subscription, options[:days_remaining])
+      when :expired
+        notify_subscription_expired(subscription)
+      end
+    end
+
     def notify_test_event
+      send_notification_to_listeners(nil, :on_test_event_received)
+    end
+
+    private
+
+    def notify_subscription_created(subscription)
+      send_notification_to_listeners(subscription, :on_subscription_created)
+    end
+
+    def notify_subscription_destroyed(subscription)
+      send_notification_to_listeners(subscription, :on_subscription_destroyed)
+    end
+
+    def notify_subscription_started(subscription)
+      send_notification_to_listeners(subscription, :on_subscription_started)
+    end
+
+    def notify_subscription_canceled(subscription, reason, immediate)
+      send_notification_to_listeners(subscription, :on_subscription_canceled, reason: reason, immediate: immediate)
+    end
+
+    def notify_subscription_due_for_renewal(subscription)
+      send_notification_to_listeners(subscription, :on_subscription_due_for_renewal)
+    end
+
+    def notify_subscription_renewed(subscription)
+      send_notification_to_listeners(subscription, :on_subscription_renewed)
+    end
+
+    def notify_subscription_renewal_payment_processing(subscription)
+      send_notification_to_listeners(subscription, :on_subscription_renewal_payment_processing)
+    end
+
+    def notify_subscription_expired(subscription)
+      send_notification_to_listeners(subscription, :on_subscription_expired)
+    end
+
+    def notify_subscription_grace_period_started(subscription, days_remaining)
+      send_notification_to_listeners(
+        subscription, :on_subscription_grace_period_started,
+        days_remaining: days_remaining
+      )
+    end
+
+    def notify_subscription_grace_period_exceeded(subscription)
+      send_notification_to_listeners(subscription, :on_subscription_grace_period_exceeded)
+    end
+
+    def send_notification_to_listeners(subscription, method_name, **args)
       @listeners.each do |listener|
-        listener.on_test_event_received if listener.respond_to?(:on_test_event_received)
+        listener.send(method_name, subscription, **args) if listener.respond_to?(method_name)
       end
     end
   end

data/lib/core_merchant/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CoreMerchant
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/core_merchant.rb

@@ -47,15 +47,9 @@ module CoreMerchant
   end
 
   # Default customer class in CoreMerchant. Use this class if you don't have a model for customers in your application.
-  class Customer
+  class Customer < ActiveRecord::Base
     include CustomerBehavior
 
     attr_accessor :id, :email, :name
-
-    def initialize(id:, email:, name: nil)
-      @id = id
-      @email = email
-      @name = name
-    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: core_merchant
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Seyithan Teymur
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-22 00:00:00.000000000 Z
+date: 2024-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -144,6 +144,8 @@ files:
 - Rakefile
 - core_merchant.gemspec
 - lib/core_merchant.rb
+- lib/core_merchant/concerns/subscription_manager_renewals.rb
+- lib/core_merchant/concerns/subscription_notifications.rb
 - lib/core_merchant/concerns/subscription_state_machine.rb
 - lib/core_merchant/customer_behavior.rb
 - lib/core_merchant/subscription.rb