core_merchant 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57cd9272d6c0056fdfd69e31fa31d88ebcee7e0f707d45201564ff464a1ad1d8
-  data.tar.gz: 8715a63c453c11936e17b98d9712073a1f083f9f35170e6723d03f7789eef67f
+  metadata.gz: 4f973a1881b08969b6c5ba44de3ea5c3a047f3e1b28d8fc76e856a3c61ad4101
+  data.tar.gz: 1927e4b2202dcf7c0f25c41edc4bcdcac4abc89bf3f90d12f167afb392700c84
 SHA512:
-  metadata.gz: cd166c331713fe259316708d16aee09ed7144a54302a52bf5b3aae298e58fa9bee37cc6371f54b3e6bf622be5fcf76ba5b2449e1fafd39e0ce177a5a1be44851
-  data.tar.gz: a9760cb3d38f36b196bf0f3c22abee20e357bd1cd176c1385e36d00febf5ddbf07135a03a961454d65743063d6cb528f296836a19e042d062a5f557c8892652b
+  metadata.gz: 98c6446f4aaa3337e281099ab45bba98fdeae286c8332a753b943c0bbb086e37c026a72d870fe557c92d817eb8c9928d49a148b7c5bfac472d44bae5a09bda1c
+  data.tar.gz: e18ff914eaf377f8606c6b4766364678088cd1035384bd580d0ccad3b8bd6b920e513d11d63e9678c47d5e7bf35af8f34a2655377761e0eb5c71a9e758fe72e3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    core_merchant (0.2.2)
+    core_merchant (0.5.1)
       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
+  # - `next_subscription_plan`: The plan to change to at next renewal (if any)
+  # - `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
+  # - `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.3.0"
+  VERSION = "0.6.0"
 end

data/lib/generators/core_merchant/install_generator.rb

@@ -10,8 +10,12 @@ module CoreMerchant
 
       source_root File.expand_path("templates", __dir__)
 
+      class_option :customer_class, type: :string, required: true,
+                                    desc: "Name of your existing customer class, e.g. User"
+
       def copy_initializer
-        template "core_merchant.rb", "config/initializers/core_merchant.rb"
+        @customer_class = options[:customer_class].classify
+        template "core_merchant.erb", "config/initializers/core_merchant.rb"
       end
 
       def copy_locales
@@ -26,6 +30,25 @@ module CoreMerchant
         migration_template "create_core_merchant_subscription_plans.erb",
                            "db/migrate/create_core_merchant_subscription_plans.rb"
       end
+
+      def show_post_install
+        say "CoreMerchant has been successfully installed.", :green
+        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 plans table."
+      end
+
+      def self.banner
+        "rails generate core_merchant:install --customer_class=User"
+      end
+
+      def self.description
+        <<~DESC
+          Installs CoreMerchant into your application with the specified customer class.
+          This could be User, Customer, or any other existing model in your application that represents a customer."
+        DESC
+      end
     end
   end
 end

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

@@ -0,0 +1,5 @@
+# Created by: rails generate core_merchant:install --customer_class=<%= @customer_class %>
+
+CoreMerchant.configure do |config|
+  config.customer_class = "<%= @customer_class %>"
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: core_merchant
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.6.0
 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,12 +130,14 @@ 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.rb
+- lib/generators/core_merchant/templates/core_merchant.erb
 - lib/generators/core_merchant/templates/create_core_merchant_subscription_plans.erb
 - sig/core_merchant.rbs
 homepage: https://github.com/theseyithan/core_merchant

data/lib/generators/core_merchant/templates/core_merchant.rb

@@ -1,4 +0,0 @@
-# Created by: rails generate core_merchant:install
-CoreMerchant.configure do |config|
-  # config.customer_class = "User" # Uncomment and set to your class name that can represent a customer
-end