core_merchant 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff6bdd381d58ecdb8153a14ceff12482d22b55b70a738de1e46df9480f3ab472
-  data.tar.gz: a87c17013865cdbe94f70daf969624f494135955568c0662e86cfe41463a6d88
+  metadata.gz: 698e2da9b3b98b8e6c6275063af7d439c1c2a79384927e952e50419691331ce9
+  data.tar.gz: fde06b7ff60d2ac49bc36b5c89200c073a1f498eca046075c7bd0cfb626702de
 SHA512:
-  metadata.gz: 044f0541c54678616eff01372b20b54e4a2bfd3f3d087ba276dc749ce06bc550f6bb047ba90bad084d1edb04f1600774cf5dd681fb56b4c91ef0c8530dbcfa38
-  data.tar.gz: f471e4c215f2d9f36944621e9bb067f9fcde0a6f67d72ee9b6e1cc6a3a2aeb507dd93cdc110bdaf9058be19c7cb700062932609ce9f10437bb5c813c75f0ed82
+  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

@@ -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,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/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"
 

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

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