core_merchant 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 154e94061339edca03a2e9c88630c4e49ce37272252e5d6436810579ea2bd529
-  data.tar.gz: 5fe4eb2a4c24b26945a505f35d9a7694de69e7630c03776ac78b7dcd6671616b
+  metadata.gz: ff6bdd381d58ecdb8153a14ceff12482d22b55b70a738de1e46df9480f3ab472
+  data.tar.gz: a87c17013865cdbe94f70daf969624f494135955568c0662e86cfe41463a6d88
 SHA512:
-  metadata.gz: 9debecdb722370c173fc97648d5f38e130e95475edb673d5f420b7074db10dfad908221cb2b2a1dec966be064fa07040a4ad287ab10380741cd9d9df27f8d618
-  data.tar.gz: 6d5675f20dfa56f708026a28f64cb48dcc44792f6e2663a13e1c466867defb2120f5947f84db8314d983246ef511bac2ce434aa3956fc621bdaf9cdd12b4a04c
+  metadata.gz: 044f0541c54678616eff01372b20b54e4a2bfd3f3d087ba276dc749ce06bc550f6bb047ba90bad084d1edb04f1600774cf5dd681fb56b4c91ef0c8530dbcfa38
+  data.tar.gz: f471e4c215f2d9f36944621e9bb067f9fcde0a6f67d72ee9b6e1cc6a3a2aeb507dd93cdc110bdaf9058be19c7cb700062932609ce9f10437bb5c813c75f0ed82

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/README.md

@@ -10,11 +10,33 @@ CoreMerchant is a library for customer, product, and subscription management in
 - [X] Add initializer generator
 - [X] Add SubscriptionPlan model
 - [X] Add Subscription model
-- [ ] Implement subscription manager and callbacks
+- [X] Implement subscription manager and callbacks
 - [ ] Add sidekiq jobs for subscription management
 - [ ] Add Invoice model
 - [ ] Add billing and invoicing service
 
+## Table of contents
+- [CoreMerchant](#coremerchant)
+  - [To-dos until 1.0.0 release](#to-dos-until-100-release)
+  - [Table of contents](#table-of-contents)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Initialization](#initialization)
+    - [Configuration](#configuration)
+      - [1. Customer class](#1-customer-class)
+      - [2. Subscription listener class](#2-subscription-listener-class)
+    - [Subscription management](#subscription-management)
+      - [Creating a subscription plan](#creating-a-subscription-plan)
+      - [Creating a subscription](#creating-a-subscription)
+      - [Cancelling a subscription](#cancelling-a-subscription)
+      - [Handling subscription events](#handling-subscription-events)
+  - [Models](#models)
+    - [SubscriptionManager](#subscriptionmanager)
+    - [SubscriptionPlan](#subscriptionplan)
+    - [Subscription](#subscription)
+  - [Contributing](#contributing)
+
+
 ## Installation
 Add this line to your application's Gemfile:
 ```
@@ -31,14 +53,14 @@ $ gem install core_merchant
 ### Initialization
 Run the generator to create the initializer file and the migrations:
 ```
-$ rails generate core_merchant:install --customer_class=User
+$ rails generate core_merchant:install
 ```
-`--customer_class` option is required and should be the name of the model that represents the customer in your application. For example, if you already have a `User` model that represents the users of your application, you can use it as the customer class in CoreMerchant.
 
 This will create the following files:
 - `config/initializers/core_merchant.rb` - Configuration file
+- `config/locales/core_merchant.en.yml` - English translations for core merchant models
 - `db/migrate/xxxxxx_create_core_merchant_subscription_plans.rb` - Migration for subscription plans
-
+- `db/migrate/xxxxxx_create_core_merchant_subscriptions.rb` - Migration for subscriptions
 You can then run the migrations:
 ```
 $ rails db:migrate
@@ -46,11 +68,13 @@ $ rails db:migrate
 
 ### Configuration
 The initializer file `config/initializers/core_merchant.rb` contains the following configuration options:
+
+#### 1. Customer class
 ```ruby
 config.customer_class = 'User'
 ```
 
-You need to include the `CoreMerchant::Customer` module in the customer class:
+This is the class that includes the `CoreMerchant::Customer` module. It should be the model class that represents your customers. For example, if you have a `User` model that represents your customers, you can include the `CoreMerchant::Customer` module in the `User` class:
 ```ruby
 # app/models/user.rb
 class User < ApplicationRecord
@@ -60,9 +84,127 @@ class User < ApplicationRecord
 end
 ```
 
+#### 2. Subscription listener class
+```ruby
+config.subscription_listener_class = 'MySubscriptionListener'
+```
+This is the class that will receive subscription events. It should include the `CoreMerchant::SubscriptionListener` module and implement event handlers for the subscription events. Some examples:
+```ruby
+class MySubscriptionListener
+  include CoreMerchant::SubscriptionListener
+
+  def on_test_event_received
+    puts 'Test event received, hooray!'
+  end
+end
+```
+
+More about subscription events in the [Handling subscription events](#handling-subscription-events) section.
+
+### Subscription management
+
+#### Creating a subscription plan
+You can create a subscription plan using the `SubscriptionPlan` model:
+```ruby
+CoreMerchant::SubscriptionPlan.create(name_key: 'basic', price_cents: 10_00, duration: '1m')
+```
+
+#### Creating a subscription
+You can create a subscription for a customer using the `Subscription` model:
+```ruby
+customer = User.find(1)
+plan = CoreMerchant::SubscriptionPlan.find_by(name_key: 'basic')
+subscription = CoreMerchant::Subscription.create(customer: customer, plan: plan)
+```
+
+Note that the subscription will not be active until you start it:
+```ruby
+subscription.start
+```
+
+#### Cancelling a subscription
+You can cancel a subscription by calling the `cancel` method. You can also specify a reason for the cancellation and whether the cancellation should take effect immediately or at the end of the current billing period:
+```ruby
+subscription.cancel(reason: 'Customer request', at_period_end: false)
+```
+
+#### Handling subscription events
+You can handle subscription events by implementing event handlers in the subscription listener class. For example, you can send an email to the customer when a subscription is created:
+```ruby
+class MySubscriptionListener
+  include CoreMerchant::SubscriptionListener
+
+  
+  def on_subscription_created(subscription)
+    FakeEmailService.send_email(subscription.customer.email, "We're happy to have you on board!")
+
+    # You can also start the subscription automatically
+    subscription.start
+  end
+
+  def on_subscription_started(subscription)
+    FakeEmailService.send_email(subscription.customer.email, "Your subscription has started!")
+  end
+
+  def on_subscription_due_for_renewal(subscription)
+    success = FakePaymentService.charge(subscription.customer, subscription.plan.price_cents)
+
+    if success
+      CoreMerchant.subscription_manager.payment_successful_for_renewal(subscription)
+    else
+      FakeEmailService.send_email(subscription.customer.email, "Payment failed, please update your payment method.")
+      CoreMerchant.subscription_manager.payment_failed_for_renewal(subscription)
+    end
+  end
+
+  def on_subscription_renewed(subscription)
+    FakeEmailService.send_email(subscription.customer.email, "Your subscription has been renewed until #{subscription.current_period_end_date}")
+  end
+end
+```
+
+Available subscription events:
+- `on_subscription_created(subscription)`
+- `on_subscription_destroyed(subscription)`
+- `on_subscription_started(subscription)`
+- `on_subscription_canceled(subscription, reason:, at_period_end:)`
+- `on_subscription_due_for_renewal(subscription)`
+- `on_subscription_renewed(subscription)`
+- `on_subscription_renewal_payment_processing(subscription)`
+- `on_subscription_grace_period_started(subscription, days_remaining:)`
+
 ## Models
+### SubscriptionManager
+Access from `CoreMerchant.subscription_manager`. The `SubscriptionManager` class is responsible for managing subscriptions. It is responsible for notifying listeners when subscription events occur and checking for and handling renewals.
+
+**Attributes**:
+  - `listeners` - An array of listeners that will be notified when subscription events occur.
+
+**Methods**:
+- `check_subscriptions` - Checks all subscriptions for renewals
+- `add_listener(listener)` - Adds a listener to the list of listeners
+- `no_payment_needed_for_renewal(subscription)` - Handles the case where no payment is needed for a renewal.
+  Call when a subscription is renewed without payment.
+- `processing_payment_for_renewal(subscription)` - Handles the case where payment is being processed for a renewal.
+  Call when payment is being processed for a renewal.
+- `payment_successful_for_renewal(subscription)` - Handles the case where payment was successful for a renewal.
+  Call when payment was successful for a renewal.
+- `payment_failed_for_renewal(subscription)` - Handles the case where payment failed for a renewal.
+  Call when payment failed for a renewal.
+
+**Usage**:
+```ruby
+manager = CoreMerchant.subscription_manager
+manager.check_subscriptions
+# ... somewhere else in the code ...
+manager.payment_successful_for_renewal(subscription1)
+manager.payment_failed_for_renewal(subscription2)
+```
+
 ### SubscriptionPlan
-The `SubscriptionPlan` model represents a subscription plan in your application. It has the following attributes:
+The `SubscriptionPlan` model represents a subscription plan in your application. Subscription plans are used to define the pricing and features of a subscription. All prices are in cents.
+
+**Attributes**:
 - `name_key`: A unique key for the subscription plan.
             This key is used to identify the plan in the application,
             as well as the translation key for the plan name through `core_merchant.subscription_plans`.
@@ -73,6 +215,62 @@ The `SubscriptionPlan` model represents a subscription plan in your application.
 - `introductory_price_cents`: The introductory price of the subscription plan in cents.
 - `introductory_duration`: The duration of the introductory price of the subscription plan.
 
+**Usage**:
+``` ruby
+  plan = CoreMerchant::SubscriptionPlan.new(name_key: "basic_monthly", price_cents: 7_99)
+  plan.save
+```
+### Subscription
+Represents a subscription in CoreMerchant.
+This class manages the lifecycle of a customer's subscription to a specific plan.
+
+**Subscriptions can transition through various statuses**:
+- `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
+- `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
+- `pending_change`: Plan change scheduled for next renewal, not yet implemented
+
+**Key features**:
+- Supports immediate and end-of-period cancellations
+- Allows plan changes, effective immediately or at next renewal
+- Handles subscription pausing and resuming
+- Manages trial periods
+- Supports variable pricing for renewals
+
+**Attributes**:
+- `customer`: Polymorphic association to the customer
+- `subscription_plan`: The current plan for this subscription
+- `status`: Current status of the subscription (see enum definition)
+- `start_date`: When the subscription started
+- `end_date`: When the subscription ended (or will end)
+- `trial_end_date`: End date of the trial period (if applicable)
+- `canceled_at`: When the subscription was canceled
+- `current_period_start`: Start of the current billing period
+- `current_period_end`: End of the current billing period
+- `pause_start_date`: When the subscription was paused
+- `pause_end_date`: When the paused subscription will resume
+- `current_period_price_cents`: Price for the current period
+- `next_renewal_price_cents`: Price for the next renewal (if different from plan)
+- `cancellation_reason`: Reason for cancellation (if applicable)
+
+**Methods**:
+- `start` - Starts the subscription
+- `cancel(reason:, at_period_end:)` - Cancels the subscription, optionally at the end of the current period
+
+**Usage**:
+```ruby
+subscription = CoreMerchant::Subscription.create(customer: user, subscription_plan: plan, status: :active)
+subscription.start
+subscription.cancel(reason: "Too expensive", at_period_end: true)
+```
+
 > [!NOTE]
 > Other models and features are being developed and will be added in future releases.
 

data/lib/core_merchant/concerns/subscription_manager_notifications.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module CoreMerchant
+  module Concerns
+    # Includes logic for notifying listeners of subscription events.
+    module SubscriptionManagerNotifications
+      extend ActiveSupport::Concern
+
+      included do # rubocop:disable Metrics/BlockLength
+        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
+      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
@@ -43,14 +46,12 @@ module CoreMerchant
   # **Usage**:
   #  ```ruby
   #   subscription = CoreMerchant::Subscription.create(customer: user, subscription_plan: plan, status: :active)
+  #   subscription.start
   #   subscription.cancel(reason: "Too expensive", at_period_end: true)
-  #   subscription.change_plan(new_plan, at_period_end: false)
-  #   subscription.pause(until_date: 1.month.from_now)
-  #   subscription.resume
-  #   subscription.renew(price_cents: 1999)
   #   ```
-  class Subscription < ActiveRecord::Base
+  class Subscription < ActiveRecord::Base # rubocop:disable Metrics/ClassLength
     include CoreMerchant::Concerns::SubscriptionStateMachine
+    include CoreMerchant::Concerns::SubscriptionNotifications
 
     self.table_name = "core_merchant_subscriptions"
 
@@ -61,12 +62,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,29 +77,114 @@ module CoreMerchant
     validate :end_date_after_start_date, if: :end_date
     validate :canceled_at_with_reason, if: :canceled_at
 
+    scope :due_for_renewal,
+          lambda {
+            where(status: %i[active trial past_due processing_renewal processing_payment])
+              .where("current_period_end <= ?", Time.current)
+          }
+
+    # 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.to_date,
+          current_period_end: new_period_end.to_date
+        )
+      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
+
+      notify_subscription_manager(:canceled, reason: reason, immediate: !at_period_end)
+    end
+
+    # Starts a new period for the subscription.
+    # This is called by SubscriptionManager when a subscription renewal is successful.
+    def start_new_period
+      new_period_start = current_period_end
+      new_period_end = new_period_start + subscription_plan.duration_in_date
+
       update!(
-        canceled_at: at_period_end ? current_period_end : Time.current,
-        cancellation_reason: reason
+        current_period_start: new_period_start.to_date,
+        current_period_end: new_period_end.to_date
       )
     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?
+      renewable? && current_period_end <= Time.current
+    end
+
+    def expired_or_canceled?
+      expired? || canceled?
+    end
+
+    def processing?
+      processing_renewal? || processing_payment?
+    end
+
+    def ongoing?
+      active? || trial? || past_due? || processing_renewal? || processing_payment? || pending_cancellation?
+    end
+
+    def renewable?
+      active? || trial? || past_due? || processing?
+    end
+
     private
 
     def end_date_after_start_date

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,115 @@
 # frozen_string_literal: true
 
+require "core_merchant/concerns/subscription_manager_notifications"
+
 module CoreMerchant
   # Manages subscriptions in CoreMerchant.
+  # This class is responsible for notifying listeners when subscription events
+  # occur and checking for and handling renewals.
+  # **Attributes**:
+  #   - `listeners` - An array of listeners that will be notified when subscription events occur.
+  #
+  # **Methods**:
+  #  - `check_subscriptions` - Checks all subscriptions for renewals
+  #  - `add_listener(listener)` - Adds a listener to the list of listeners
+  #  - `no_payment_needed_for_renewal(subscription)` - Handles the case where no payment is needed for a renewal.
+  #     Call when a subscription is renewed without payment.
+  #  - `processing_payment_for_renewal(subscription)` - Handles the case where payment is being processed for a renewal.
+  #     Call when payment is being processed for a renewal.
+  #  - `payment_successful_for_renewal(subscription)` - Handles the case where payment was successful for a renewal.
+  #     Call when payment was successful for a renewal.
+  #  - `payment_failed_for_renewal(subscription)` - Handles the case where payment failed for a renewal.
+  #     Call when payment failed for a renewal.
+  #
+  # **Usage**:
+  #  ```ruby
+  #  manager = CoreMerchant.subscription_manager
+  #  manager.check_subscriptions
+  #
+  #  # ... somewhere else in the code ...
+  #  manager.payment_successful_for_renewal(subscription1)
+  #  manager.payment_failed_for_renewal(subscription2)
+  #  ```
+  #
   class SubscriptionManager
+    include Concerns::SubscriptionManagerNotifications
+
     attr_reader :listeners
 
     def initialize
       @listeners = []
     end
 
+    def check_subscriptions
+      check_renewals
+      check_cancellations
+    end
+
     def add_listener(listener)
       @listeners << listener
     end
 
-    def notify_test_event
+    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)
+      renew_subscription(subscription)
+    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)
+      renew_subscription(subscription)
+    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
+
+    def check_cancellations
+      Subscription.find_each do |subscription|
+        process_for_cancellation(subscription) if subscription.pending_cancellation?
+      end
+    end
+
+    def process_for_cancellation(subscription)
+      return unless subscription.transition_to_expired
+
+      notify(subscription, :expired)
+    end
+
+    private
+
+    def renew_subscription(subscription)
+      return unless subscription.transition_to_active
+
+      subscription.start_new_period
+      notify(subscription, :renewed)
+    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/subscription_plan.rb

@@ -16,7 +16,7 @@ module CoreMerchant
   # - `introductory_price_cents`: The introductory price of the subscription plan in cents.
   # - `introductory_duration`: The duration of the introductory price of the subscription plan.
   #
-  # Example:
+  # Usage:
   #  ```
   #   plan = CoreMerchant::SubscriptionPlan.new(name_key: "basic_monthly", price_cents: 7_99)
   #   plan.save

data/lib/core_merchant/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CoreMerchant
-  VERSION = "0.7.0"
+  VERSION = "0.9.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.9.0
 platform: ruby
 authors:
 - Seyithan Teymur
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-22 00:00:00.000000000 Z
+date: 2024-07-24 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_notifications.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