core_merchant 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bd7b45750d9491ddf78c12b41e73a1d79d8bc6fa5cdff69df22f536b1765e42
-  data.tar.gz: 056e3021e60c7c5edb4a301dae4a29b6184ad3889b55c81e226dccfcfcb00020
+  metadata.gz: 698e2da9b3b98b8e6c6275063af7d439c1c2a79384927e952e50419691331ce9
+  data.tar.gz: fde06b7ff60d2ac49bc36b5c89200c073a1f498eca046075c7bd0cfb626702de
 SHA512:
-  metadata.gz: f916fe4fb53d28a9fbb61c8d7306825cb96d82ceeb559a6aeea1373c83e5401c785c0400dd3b41f0d5f9a4c321f0cc91c85eddead5808d546c7fb09d6b671aa7
-  data.tar.gz: 218935fdbb73a113262735e5b4a0290d7942121b167932ad00a5ead4c1a75ef69d8f18dfffca5fea14aafbbb8bf79f6cb940042f15f0989a59ce1e6c14a58208
+  metadata.gz: 2cc9e74b4053e9a91435977f1b6d30222c96a69403654062a9c36dcfec6a18e2e4eebecfdc9c889cc3afbac1ac1a34e4f451cd78e6abbe64bf4ca7e795570543
+  data.tar.gz: 6a8cfc973fe959bfbb5cf29c0b68e3e7f644e1cee9f5e21fdc415a4d510b26ddf904e85d05c29188a176fec0225c6e763938713dcdb4d8521cf12d0aab4797c5

data/Gemfile.lock

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

data/README.md

@@ -10,15 +10,44 @@ 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
-- [ ] Add sidekiq jobs for subscription management
+- [X] Implement subscription manager and callbacks
+- [X] Implement SubscriptionEvent model for logging
 - [ ] Add Invoice model
 - [ ] Add billing and invoicing service
 
-## Installation
+## 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)
+    - [Subscription History](#subscription-history)
+  - [Public API](#public-api)
+    - [SubscriptionManager](#subscriptionmanager)
+    - [SubscriptionPlan](#subscriptionplan)
+    - [Subscription](#subscription)
+    - [SubscriptionEvent](#subscriptionevent)
+      - [Subclasses](#subclasses)
+        - [SubscriptionRenewalEvent](#subscriptionrenewalevent)
+        - [SubscriptionStatusChangeEvent](#subscriptionstatuschangeevent)
+        - [SubscriptionPlanChangeEvent](#subscriptionplanchangeevent)
+        - [SubscriptionCancellationEvent](#subscriptioncancellationevent)
+  - [Contributing](#contributing)
+
+
+# Installation
 Add this line to your application's Gemfile:
 ```
-gem 'core_merchant', '~> 0.1.0'
+gem 'core_merchant', '~> 0.10.0'
 ```
 and run `bundle install`.
 
@@ -27,30 +56,32 @@ Alternatively, you can install the gem manually:
 $ gem install core_merchant
 ```
 
-## Usage
-### Initialization
+# Usage
+## 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
 ```
 
-### Configuration
+## 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 +91,149 @@ class User < ApplicationRecord
 end
 ```
 
-## Models
+### 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:)`
+
+### Subscription History
+CoreMerchant now keeps a detailed history of subscription events, including creations, renewals, cancellations, status changes, and plan changes. This provides an audit trail and can be useful for debugging, customer support, and analytics.
+
+To access a subscription's history:
+```ruby
+subscription = CoreMerchant::Subscription.find(42)
+
+# Get all events
+subscription.subscription_events
+
+# Get specific event types
+latest_renewal = subscription.renewal_events.last
+puts "Last renewed at: #{latest_renewal.created_at}"
+puts "Renewal price: #{latest_renewal.price_cents} cents, renewed until: #{latest_renewal.renewed_until}"
+
+latest_status_change = subscription.status_change_events.last
+puts "Status changed from #{latest_status_change.from} to #{latest_status_change.to}"
+
+latest_plan_change = subscription.plan_change_events.last
+puts "Plan changed from #{latest_plan_change.from_plan.name} to #{latest_plan_change.to_plan.name}"
+```
+
+## Public API
+### 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 +244,109 @@ 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)
+```
+
+### SubscriptionEvent
+The `SubscriptionEvent` model represents a historical log of events related to a subscription. It provides an audit trail of all significant actions and state changes for a subscription.
+
+This class has subclasses for specific event types, such as `SubscriptionRenewalEvent`, `SubscriptionStatusChangeEvent`, and `SubscriptionPlanChangeEvent`. Each subclass has additional fields specific to the event type.
+
+**Attributes**:
+- `subscription`: Association to the related Subscription
+- `event_type`: Type of the event (e.g., 'created', 'renewed', 'canceled', 'status_changed', 'plan_changed')
+- `metadata`: JSON field for storing additional event-specific data
+
+**Usage**:
+```ruby
+# Automatically logged when a subscription is created
+subscription = CoreMerchant::Subscription.create(customer: user, subscription_plan: plan)
+
+# Logging a custom event
+subscription.log_event('custom_event', key: 'value')
+
+# Retrieve the last renewal event
+latest_renewal = subscription.renewal_events.last
+puts "Last renewed at: #{latest_renewal.created_at}"
+puts "Renewal price: #{latest_renewal.price_cents} cents, renewed until: #{latest_renewal.renewed_until}"
+
+# Retrieve the last event of any type
+latest_event = subscription.subscription_events.last
+puts "Last event type: #{latest_event.event_type}, metadata: #{latest_event.metadata}"
+```
+
+#### Subclasses
+##### SubscriptionRenewalEvent
+- `price_cents`: The price of the renewal in cents
+- `renewed_until`: The end date of the renewal
+- `renewed_at`: The date and time of the renewal
+
+##### SubscriptionStatusChangeEvent
+- `from`: The previous status of the subscription
+- `to`: The new status of the subscription
+
+##### SubscriptionPlanChangeEvent
+- `from_plan`: The previous plan of the subscription
+- `to_plan`: The new plan of the subscription
+
+##### SubscriptionCancellationEvent
+- `reason`: The reason for the cancellation
+- `at_period_end`: Whether the cancellation is scheduled for the end of the current period
+- `canceled_at`: The date and time of the cancellation
+
 > [!NOTE]
 > Other models and features are being developed and will be added in future releases.
 

data/lib/core_merchant/concerns/subscription_event_association.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CoreMerchant
+  module Concerns
+    # This concern adds a SubscriptionEvent association including creation and retrieval
+    module SubscriptionEventAssociation
+      extend ActiveSupport::Concern
+
+      EVENT_TYPES = %i[renewal status_change plan_change cancellation].freeze
+
+      included do
+        has_many :events, class_name: "SubscriptionEvent", dependent: :destroy
+
+        EVENT_TYPES.each do |event_type|
+          scope_name = "#{event_type}_events".to_sym
+          class_name = "Subscription#{event_type.to_s.camelize}Event"
+
+          has_many scope_name, -> { where(event_type: event_type) }, class_name: class_name
+
+          define_method "create_#{event_type}_event" do |**metadata|
+            events.create!(event_type: event_type, metadata: metadata)
+          end
+        end
+      end
+    end
+  end
+end

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/subscription.rb

@@ -2,6 +2,8 @@
 
 require "core_merchant/concerns/subscription_state_machine"
 require "core_merchant/concerns/subscription_notifications"
+require "core_merchant/concerns/subscription_event_association"
+require "core_merchant/subscription_event"
 
 module CoreMerchant
   # Represents a subscription in CoreMerchant.
@@ -46,15 +48,13 @@ 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
+    include CoreMerchant::Concerns::SubscriptionEventAssociation
 
     self.table_name = "core_merchant_subscriptions"
 
@@ -80,6 +80,12 @@ 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
@@ -89,8 +95,8 @@ module CoreMerchant
       transaction do
         transition_to_active!
         update!(
-          current_period_start: new_period_start,
-          current_period_end: new_period_end
+          current_period_start: new_period_start.to_date,
+          current_period_end: new_period_end.to_date
         )
       end
 
@@ -119,6 +125,18 @@ module CoreMerchant
       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!(
+        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.
@@ -151,8 +169,23 @@ module CoreMerchant
     end
 
     def due_for_renewal?
-      (active? || trial? || past_due? || processing_renewal? || processing_payment?) &&
-        current_period_end <= Time.current
+      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

data/lib/core_merchant/subscription_event.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module CoreMerchant
+  #   The `SubscriptionEvent` model represents a historical log of events related to a subscription.
+  #   It provides an audit trail of all significant actions and state changes for a subscription.
+
+  # This class has subclasses for specific event types, such as
+  # `SubscriptionRenewalEvent`, `SubscriptionStatusChangeEvent`, and `SubscriptionPlanChangeEvent`.
+  # Each subclass has additional fields specific to the event type.
+
+  # **Attributes**:
+  # - `subscription`: Association to the related Subscription
+  # - `event_type`: Type of the event (e.g., 'created', 'renewed', 'canceled', 'status_changed', 'plan_changed')
+  # - `metadata`: JSON field for storing additional event-specific data
+
+  # **Usage**:
+  # ```ruby
+  # # Automatically logged when a subscription is created
+  # subscription = CoreMerchant::Subscription.create(customer: user, subscription_plan: plan)
+
+  # # Logging a custom event
+  # subscription.log_event('custom_event', key: 'value')
+
+  # # Retrieve the last renewal event
+  # latest_renewal = subscription.renewal_events.last
+  # puts "Last renewed at: #{latest_renewal.created_at}"
+  # puts "Renewal price: #{latest_renewal.price_cents} cents, renewed until: #{latest_renewal.renewed_until}"
+
+  # # Retrieve the last event of any type
+  # latest_event = subscription.subscription_events.last
+  # puts "Last event type: #{latest_event.event_type}, metadata: #{latest_event.metadata}"
+  # ```
+  class SubscriptionEvent < ActiveRecord::Base
+    self.table_name = "core_merchant_subscription_events"
+
+    belongs_to :subscription, class_name: "CoreMerchant::Subscription"
+
+    validates :event_type, presence: true
+
+    def self.event_type
+      name.demodulize.underscore
+    end
+
+    def metadata
+      value = self[:metadata]
+      value.is_a?(Hash) ? value : JSON.parse(value || "{}")
+    end
+
+    def metadata=(value)
+      self[:metadata] = value.is_a?(Hash) ? value.to_json : value
+    end
+  end
+
+  # Represents a renewal event for a subscription.
+  class SubscriptionRenewalEvent < SubscriptionEvent
+    def price_cents
+      metadata["price_cents"]
+    end
+
+    def price_cents=(value)
+      self.metadata = metadata.merge(price_cents: value)
+    end
+
+    def renewed_from
+      metadata["renewed_from"].to_date
+    end
+
+    def renewed_from=(value)
+      self.metadata = metadata.merge(renewed_from: value)
+    end
+
+    def renewed_until
+      metadata["renewed_until"].to_date
+    end
+
+    def renewed_until=(value)
+      self.metadata = metadata.merge(renewed_until: value)
+    end
+  end
+
+  # Represents a status change event for a subscription.
+  class SubscriptionStatusChangeEvent < SubscriptionEvent
+    def from
+      metadata["from_status"]
+    end
+
+    def from=(value)
+      self.metadata = metadata.merge(from_status: value)
+    end
+
+    def to
+      metadata["to_status"]
+    end
+
+    def to=(value)
+      self.metadata = metadata.merge(to_status: value)
+    end
+  end
+
+  # Represents a plan change event for a subscription.
+  class SubscriptionPlanChangeEvent < SubscriptionEvent
+    def from_plan
+      id = metadata["from_plan_id"]
+      CoreMerchant::SubscriptionPlan.find(id) if id
+    end
+
+    def from_plan=(value)
+      self.metadata = metadata.merge(from_plan_id: value.id)
+    end
+
+    def to_plan
+      id = metadata["to_plan_id"]
+      CoreMerchant::SubscriptionPlan.find(id) if id
+    end
+
+    def to_plan=(value)
+      self.metadata = metadata.merge(to_plan_id: value.id)
+    end
+  end
+
+  # Represents a cancellation event for a subscription.
+  class SubscriptionCancellationEvent < SubscriptionEvent
+    def canceled_at
+      created_at
+    end
+
+    def at_period_end?
+      metadata["at_period_end"]
+    end
+
+    def at_period_end=(value)
+      self.metadata = metadata.merge(at_period_end: value)
+    end
+
+    def reason
+      metadata["reason"]
+    end
+
+    def reason=(value)
+      self.metadata = metadata.merge(reason: value)
+    end
+  end
+end

data/lib/core_merchant/subscription_manager.rb

@@ -1,14 +1,38 @@
 # frozen_string_literal: true
 
-require "core_merchant/concerns/subscription_manager_renewals"
+require "core_merchant/concerns/subscription_manager_notifications"
 
 module CoreMerchant
   # Manages subscriptions in CoreMerchant.
-  # This class is responsible for notifying listeners when subscription events occur.
-  # Attributes:
+  # 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::SubscriptionManagerRenewals
+    include Concerns::SubscriptionManagerNotifications
 
     attr_reader :listeners
 
@@ -18,82 +42,69 @@ module CoreMerchant
 
     def check_subscriptions
       check_renewals
+      check_cancellations
     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)
+    def check_renewals
+      Subscription.find_each do |subscription|
+        process_for_renewal(subscription) if subscription.due_for_renewal?
       end
     end
 
-    def notify_test_event
-      send_notification_to_listeners(nil, :on_test_event_received)
-    end
-
-    private
+    def process_for_renewal(subscription)
+      return unless subscription.transition_to_processing_renewal
 
-    def notify_subscription_created(subscription)
-      send_notification_to_listeners(subscription, :on_subscription_created)
+      notify(subscription, :due_for_renewal)
     end
 
-    def notify_subscription_destroyed(subscription)
-      send_notification_to_listeners(subscription, :on_subscription_destroyed)
+    def no_payment_needed_for_renewal(subscription)
+      renew_subscription(subscription)
     end
 
-    def notify_subscription_started(subscription)
-      send_notification_to_listeners(subscription, :on_subscription_started)
-    end
+    def processing_payment_for_renewal(subscription)
+      return unless subscription.transition_to_processing_payment
 
-    def notify_subscription_canceled(subscription, reason, immediate)
-      send_notification_to_listeners(subscription, :on_subscription_canceled, reason: reason, immediate: immediate)
+      notify(subscription, :renewal_payment_processing)
     end
 
-    def notify_subscription_due_for_renewal(subscription)
-      send_notification_to_listeners(subscription, :on_subscription_due_for_renewal)
+    def payment_successful_for_renewal(subscription)
+      renew_subscription(subscription)
     end
 
-    def notify_subscription_renewed(subscription)
-      send_notification_to_listeners(subscription, :on_subscription_renewed)
+    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 notify_subscription_renewal_payment_processing(subscription)
-      send_notification_to_listeners(subscription, :on_subscription_renewal_payment_processing)
+    def check_cancellations
+      Subscription.find_each do |subscription|
+        process_for_cancellation(subscription) if subscription.pending_cancellation?
+      end
     end
 
-    def notify_subscription_expired(subscription)
-      send_notification_to_listeners(subscription, :on_subscription_expired)
-    end
+    def process_for_cancellation(subscription)
+      return unless subscription.transition_to_expired
 
-    def notify_subscription_grace_period_started(subscription, days_remaining)
-      send_notification_to_listeners(
-        subscription, :on_subscription_grace_period_started,
-        days_remaining: days_remaining
-      )
+      notify(subscription, :expired)
     end
 
-    def notify_subscription_grace_period_exceeded(subscription)
-      send_notification_to_listeners(subscription, :on_subscription_grace_period_exceeded)
+    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)

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.8.0"
+  VERSION = "0.10.0"
 end

data/lib/generators/core_merchant/install_generator.rb

@@ -28,6 +28,9 @@ module CoreMerchant
 
         migration_template "migrate/create_core_merchant_subscriptions.erb",
                            "db/migrate/create_core_merchant_subscriptions.rb"
+
+        migration_template "migrate/create_core_merchant_subscription_events.erb",
+                           "db/migrate/create_core_merchant_subscription_events.rb"
       end
 
       def show_post_install
@@ -36,7 +39,7 @@ module CoreMerchant
           Next steps:
           1. Set the customer class in the initializer file (config/initializers/core_merchant.rb) to the class you want to use for customers.
           2. Create a subscription listener class (should include CoreMerchant::SubscriptionListener) in your app and set this class in the initializer file (config/initializers/core_merchant.rb) to the class you want to use for subscription listeners.
-          3. Run `rails db:migrate` to create the subscription and subscription plan tables.
+          3. Run `rails db:migrate` to create the subscription, subscription plan, and subscription event tables.
         MESSAGE
         say next_steps, :yellow
       end
@@ -47,7 +50,7 @@ module CoreMerchant
 
       def self.description
         <<~DESC
-          Installs CoreMerchant into your application. This generator will create an initializer file, migration files for the subscription and subscription plan tables, and a locale file."
+          Installs CoreMerchant into your application. This generator will create an initializer file, migration files for the subscription, subscription plan, and subscription event tables, and a locale file.
         DESC
       end
     end

data/lib/generators/core_merchant/templates/migrate/create_core_merchant_subscription_events.erb

@@ -0,0 +1,14 @@
+# Created by: rails generate core_merchant:install
+class CreateCoreMerchantSubscriptionEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :core_merchant_subscription_events do |t|
+      t.references :subscription, null: false, foreign_key: { to_table: :core_merchant_subscriptions }
+      t.string :event_type, null: false
+      t.jsonb :metadata, default: {}, null: false
+
+      t.timestamps
+
+      t.index :event_type
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: core_merchant
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Seyithan Teymur
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-23 00:00:00.000000000 Z
+date: 2024-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -144,11 +144,13 @@ files:
 - Rakefile
 - core_merchant.gemspec
 - lib/core_merchant.rb
-- lib/core_merchant/concerns/subscription_manager_renewals.rb
+- lib/core_merchant/concerns/subscription_event_association.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
+- lib/core_merchant/subscription_event.rb
 - lib/core_merchant/subscription_listener.rb
 - lib/core_merchant/subscription_manager.rb
 - lib/core_merchant/subscription_plan.rb
@@ -156,6 +158,7 @@ files:
 - lib/generators/core_merchant/install_generator.rb
 - lib/generators/core_merchant/templates/core_merchant.en.yml
 - lib/generators/core_merchant/templates/core_merchant.rb
+- lib/generators/core_merchant/templates/migrate/create_core_merchant_subscription_events.erb
 - lib/generators/core_merchant/templates/migrate/create_core_merchant_subscription_plans.erb
 - lib/generators/core_merchant/templates/migrate/create_core_merchant_subscriptions.erb
 - sig/core_merchant.rbs

data/lib/core_merchant/concerns/subscription_manager_renewals.rb

@@ -1,53 +0,0 @@
-# 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