core_merchant 0.9.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff6bdd381d58ecdb8153a14ceff12482d22b55b70a738de1e46df9480f3ab472
-  data.tar.gz: a87c17013865cdbe94f70daf969624f494135955568c0662e86cfe41463a6d88
+  metadata.gz: f2a8720cdfe9e44ee389c1f9297dca125be49ee41dd0aa36353480ebe59242f1
+  data.tar.gz: 8dc8ed8fd42ef4fca3ecd63b5064a0b5499da237df1fbc19bdb75301054b7646
 SHA512:
-  metadata.gz: 044f0541c54678616eff01372b20b54e4a2bfd3f3d087ba276dc749ce06bc550f6bb047ba90bad084d1edb04f1600774cf5dd681fb56b4c91ef0c8530dbcfa38
-  data.tar.gz: f471e4c215f2d9f36944621e9bb067f9fcde0a6f67d72ee9b6e1cc6a3a2aeb507dd93cdc110bdaf9058be19c7cb700062932609ce9f10437bb5c813c75f0ed82
+  metadata.gz: 76f2ff5aa75aeb8f992be5be10d1e5b7630102cf34ddf2bfcdeeafe7ac151253e27ff6dbeea2936b245af3b6965b02dce856354ae2ee7d958844e93f07cc51dd
+  data.tar.gz: 7175e21168584ba3b16863933e4ea5afc297fe8fb053f8502766fc8c55b1614168eb0b0c28f9ba89ca4d2e5a82d24c928b5effcbe5633dc18a38dba536d2b188

data/Gemfile.lock

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

data/README.md

@@ -11,7 +11,7 @@ CoreMerchant is a library for customer, product, and subscription management in
 - [X] Add SubscriptionPlan model
 - [X] Add Subscription model
 - [X] Implement subscription manager and callbacks
-- [ ] Add sidekiq jobs for subscription management
+- [X] Implement SubscriptionEvent model for logging
 - [ ] Add Invoice model
 - [ ] Add billing and invoicing service
 
@@ -19,28 +19,35 @@ CoreMerchant is a library for customer, product, and subscription management in
 - [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)
+- [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
+# 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`.
 
@@ -49,8 +56,8 @@ 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
@@ -66,10 +73,10 @@ 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
+### 1. Customer class
 ```ruby
 config.customer_class = 'User'
 ```
@@ -84,7 +91,7 @@ class User < ApplicationRecord
 end
 ```
 
-#### 2. Subscription listener class
+### 2. Subscription listener class
 ```ruby
 config.subscription_listener_class = 'MySubscriptionListener'
 ```
@@ -101,15 +108,15 @@ end
 
 More about subscription events in the [Handling subscription events](#handling-subscription-events) section.
 
-### Subscription management
+## Subscription management
 
-#### Creating a subscription plan
+### 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
+### Creating a subscription
 You can create a subscription for a customer using the `Subscription` model:
 ```ruby
 customer = User.find(1)
@@ -122,13 +129,13 @@ Note that the subscription will not be active until you start it:
 subscription.start
 ```
 
-#### Cancelling a subscription
+### 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
+### 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
@@ -173,7 +180,29 @@ Available subscription events:
 - `on_subscription_renewal_payment_processing(subscription)`
 - `on_subscription_grace_period_started(subscription, days_remaining:)`
 
-## Models
+### 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.
 
@@ -271,6 +300,53 @@ 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,32 @@
+# 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
+        after_update :create_status_change_event, if: :saved_change_to_status?
+
+        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
+
+        def create_status_change_event
+          status_change_events.create!(from: saved_changes["status"].first, to: status)
+        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.
@@ -52,6 +54,7 @@ module CoreMerchant
   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"
 
@@ -120,6 +123,7 @@ module CoreMerchant
       end
 
       notify_subscription_manager(:canceled, reason: reason, immediate: !at_period_end)
+      cancellation_events.create!(reason: reason, at_period_end: at_period_end)
     end
 
     # Starts a new period for the subscription.

data/lib/core_merchant/subscription_event.rb

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

@@ -104,6 +104,11 @@ module CoreMerchant
       return unless subscription.transition_to_active
 
       subscription.start_new_period
+      subscription.renewal_events.create!(
+        price_cents: subscription.subscription_plan.price_cents,
+        renewed_from: subscription.current_period_start, renewed_until: subscription.current_period_end
+      )
+
       notify(subscription, :renewed)
     end
 

data/lib/core_merchant/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CoreMerchant
-  VERSION = "0.9.0"
+  VERSION = "0.10.1"
 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/core_merchant.rb

@@ -7,7 +7,7 @@ CoreMerchant.configure do |config|
   #   include CoreMerchant::CustomerBehavior
   #   ...
   # end
-  config.customer_class = "User"
+  # config.customer_class = "User"
 
   # Set the class that will receive subscription notifications/
   # This class must include the CoreMerchant::SubscriptionListener module.
@@ -22,5 +22,5 @@ CoreMerchant.configure do |config|
   #
   # To test notifications to this class, you can override `on_test_event_received` method
   # and call `CoreMerchant.subscription_manager.notify_test_event`.
-  config.subscription_listener_class = "SubscriptionListener"
+  # config.subscription_listener_class = "SubscriptionListener"
 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.9.0
+  version: 0.10.1
 platform: ruby
 authors:
 - Seyithan Teymur
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-24 00:00:00.000000000 Z
+date: 2024-07-26 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_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