core_merchant 0.5.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 465238229ff4e985efc17153d4d8efc1cca941745ded4a1e5dbe3a189499e6d0
-  data.tar.gz: 07ee307e66cbf913b89abbb41ec1eaa92a5ed5e981a577148cba3e8be0c02e95
+  metadata.gz: fceb2084b15e74e2aebe360df8cade628ffd930afd2ef689a6779c3f59f5f70a
+  data.tar.gz: 96368a736ce980a109bfd9d863b56cbec0c814111edd4839874738d13cc6c9e3
 SHA512:
-  metadata.gz: 6e85d2853136062219964072612ec3d82a8fa2296b3cf71f3400e1f68b01ff19c9ce7da09ef0acdcc9b681aecb487ae5680e9342df5428f7281d12569cad860c
-  data.tar.gz: 851db004b49a0ac7e0c737c6a53741b5d8747acfa052dedba8e78ac959ff532b02ff556a5a8a6a59cfe65b5aa0aec7cdb92d7500161904b37afdbd3ca1457607
+  metadata.gz: 643e829909744d948af7a5270ebdd0f3be2dfa7f3d540da9f0fd728fc9d052731719d6ec6f93cfc73d7357f25c3bbd50a8fd32046b0c2a354058fc611d34e8ac
+  data.tar.gz: a2ecdd77b9628e2dee8b67b422f0d4fa2f1a62214c28bc9bb1ae72338986272b03bfce1a193969a3fbbc6e440e45ac041c8dd2c637de1fa0d7f796244f6b6daf

data/Gemfile.lock

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

data/README.md

@@ -31,8 +31,10 @@ $ gem install core_merchant
 ### Initialization
 Run the generator to create the initializer file and the migrations:
 ```
-$ rails generate core_merchant:install
+$ rails generate core_merchant:install --customer_class=User
 ```
+`--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
 - `db/migrate/xxxxxx_create_core_merchant_subscription_plans.rb` - Migration for subscription plans
@@ -45,19 +47,10 @@ $ rails db:migrate
 ### Configuration
 The initializer file `config/initializers/core_merchant.rb` contains the following configuration options:
 ```ruby
-config.customer_class
-```
-
-### The cusomer class
-The customer class is 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. To do this, you need to set the `customer_class` configuration option in the initializer file:
-```ruby
-# config/initializers/core_merchant.rb
-CoreMerchant.configure do |config|
-  config.customer_class = 'User'
-end
+config.customer_class = 'User'
 ```
 
-You need to then include the `CoreMerchant::Customer` module in the customer class:
+You need to include the `CoreMerchant::Customer` module in the customer class:
 ```ruby
 # app/models/user.rb
 class User < ApplicationRecord

data/lib/core_merchant/concerns/subscription_state_machine.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module CoreMerchant
+  module Concerns
+    class InvalidTransitionError < CoreMerchant::Error; end
+
+    # 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_cancellation` -> `canceled`, `expired`
+    # - `canceled` -> `pending`, `active`
+    # - `expired` -> `pending`, `active`
+    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],
+        pending_cancellation: %i[active trial],
+        canceled: %i[active pending_cancellation trial],
+        expired: %i[active pending_cancellation canceled trial],
+        past_due: [],
+        paused: [],
+        pending_change: []
+      }.freeze
+
+      included do
+        POSSIBLE_TRANSITIONS.each do |to_state, from_states|
+          define_method("can_transition_to_#{to_state}?") do
+            from_states.include?(status.to_sym)
+          end
+
+          define_method("transition_to_#{to_state}") do
+            return false unless send("can_transition_to_#{to_state}?")
+
+            update(status: to_state)
+          end
+
+          define_method("transition_to_#{to_state}!") do
+            raise InvalidTransitionError unless send("transition_to_#{to_state}")
+
+            update!(status: to_state)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/core_merchant/subscription.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "core_merchant/concerns/subscription_state_machine"
+
+module CoreMerchant
+  # 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, not yet implemented
+  # - `pending_cancellation`: Will be canceled at period end
+  # - `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)
+  #
+  # **Usage**:
+  #  ```ruby
+  #   subscription = CoreMerchant::Subscription.create(customer: user, subscription_plan: plan, status: :active)
+  #   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
+    include CoreMerchant::Concerns::SubscriptionStateMachine
+
+    self.table_name = "core_merchant_subscriptions"
+
+    belongs_to :customer, polymorphic: true
+    belongs_to :subscription_plan
+
+    enum status: {
+      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
+    }
+
+    validates :customer, :subscription_plan, :status, :start_date, presence: true
+    validates :status, inclusion: { in: statuses.keys }
+    validate :end_date_after_start_date, if: :end_date
+    validate :canceled_at_with_reason, if: :canceled_at
+
+    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
+      )
+    end
+
+    def cancel(reason:, at_period_end:)
+      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
+
+    private
+
+    def set_period_dates
+      self.start_date ||= Time.current
+      self.current_period_start ||= start_date
+      self.current_period_end ||= start_date + subscription_plan.duration_in_date
+    end
+
+    def end_date_after_start_date
+      errors.add(:end_date, "must be after the `start date") if end_date <= start_date
+    end
+
+    def canceled_at_with_reason
+      errors.add(:cancellation_reason, "must be present when `canceled_at` is set") if cancellation_reason.blank?
+    end
+  end
+end

data/lib/core_merchant/version.rb

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

data/lib/generators/core_merchant/install_generator.rb

@@ -27,14 +27,19 @@ module CoreMerchant
       end
 
       def create_migration_file
-        migration_template "create_core_merchant_subscription_plans.erb",
+        migration_template "migrate/create_core_merchant_subscription_plans.erb",
                            "db/migrate/create_core_merchant_subscription_plans.rb"
+
+        migration_template "migrate/create_core_merchant_subscriptions.erb",
+                           "db/migrate/create_core_merchant_subscriptions.rb"
       end
 
       def show_post_install
         say "CoreMerchant has been successfully installed.", :green
-        say "Customer class: #{@customer_class}"
-        say "Please run `rails db:migrate` to create the subscription plans table."
+        say <<~MESSAGE
+          Customer class: #{@customer_class}. Please update this model to include the CoreMerchant::CustomerBehavior module.
+        MESSAGE
+        say "Please run `rails db:migrate` to create the subscription and subscription plan tables.", :yellow
       end
 
       def self.banner

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

@@ -0,0 +1,26 @@
+# Created by: rails generate core_merchant:install
+class CreateCoreMerchantSubscriptions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :core_merchant_subscriptions do |t|
+      t.references :customer, polymorphic: true, null: false
+      t.references :subscription_plan, null: false
+      t.integer :status, null: false, default: 0
+      t.datetime :canceled_at
+      t.string :cancellation_reason
+
+      t.datetime :start_date, null: false
+      t.datetime :trial_end_date
+      t.datetime :end_date
+      t.datetime :current_period_start_date
+      t.datetime :current_period_end_date
+      t.datetime :pause_start_date
+      t.datetime :pause_end_date
+
+      t.integer :current_period_price_cents
+
+      t.timestamps
+
+      t.index :status
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: core_merchant
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Seyithan Teymur
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-20 00:00:00.000000000 Z
+date: 2024-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -130,13 +130,16 @@ files:
 - Rakefile
 - core_merchant.gemspec
 - lib/core_merchant.rb
+- lib/core_merchant/concerns/subscription_state_machine.rb
 - lib/core_merchant/customer_behavior.rb
+- lib/core_merchant/subscription.rb
 - lib/core_merchant/subscription_plan.rb
 - lib/core_merchant/version.rb
 - lib/generators/core_merchant/install_generator.rb
 - lib/generators/core_merchant/templates/core_merchant.en.yml
 - lib/generators/core_merchant/templates/core_merchant.erb
-- lib/generators/core_merchant/templates/create_core_merchant_subscription_plans.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
 homepage: https://github.com/theseyithan/core_merchant
 licenses: