core_merchant 0.10.3 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1b4b1cbf5077a524194ccfd967de5ffa09300f0044eb1510f29685f3f423a61
-  data.tar.gz: 9cbf2263f4dc11a235a7d4fb3bac772d9b596ee819eda49462dc5c1d7495bf83
+  metadata.gz: 22e2c74252e4e4b93cfcda94ce010339441225e0214b5feb3ae595adc539e421
+  data.tar.gz: a7bfb337cb13efebae8aba09f9e7eb0df7186b815fd489faca0d25709a195cc8
 SHA512:
-  metadata.gz: d6c14e092f4f7bd2097163bb731c50cc24e4142a5c4857544237d908a3b0c71c54a9297ea905fe30adb2bcc218b649bbbbe5cd9381321097926c75ac27322732
-  data.tar.gz: 898f6dfe26822e55091af5ab6a320d4e087feee85925a174e6937ef1597ef701072589a9ebcb48cf4446cfd20e3a5aacff1c62870e1191a3e544d8de651d22df
+  metadata.gz: 891a264116088a5fbbf92b0878b7d704a17d8f92052332d498816256ee2414e0b55c765d8994ca4c4731aa8cccf99926099ef00006022c7c202fced43e3e1932
+  data.tar.gz: 6fe89dc891685e3f124b75c01f10ead88effdcbfbdf6d1a6d12d2894f0eaff8c92c74328e9ef69367ce3b169b9f7bff0e46f9b28a41e0ee415a338c053c30ff4

data/Gemfile.lock

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

data/README.md

@@ -57,6 +57,36 @@ $ gem install core_merchant
 ```
 
 # Usage
+The steps below will guide you through setting up CoreMerchant in your Rails application. After completing these steps, you will be able to create subscription plans, manage subscriptions, and handle subscription events.
+
+```ruby
+# Create a subscription plan
+plan = CoreMerchant::SubscriptionPlan.create(name_key: 'basic', price_cents: 9_99, duration: '1m')
+
+# Subscribe a customer to the plan
+customer = current_user
+subscription = CoreMerchant::Subscription.create(customer: customer, plan: plan)
+
+# Start the subscription
+CoreMerchant.subscription_manager.start_subscription(subscription)
+
+# Use a listener to handle subscription events
+class MySubscriptionListener
+  include CoreMerchant::SubscriptionListener
+
+  def on_subscription_started(subscription)
+    puts "Subscription started for #{subscription.customer.email}, subscribed to #{subscription.plan.name}"
+  end
+
+  def on_subscription_due_for_renewal(subscription)
+    puts "Subscription due for renewal for #{subscription.customer.email}, renewing until #{subscription.current_period_end_date}"
+
+    # After payment is processed
+    CoreMerchant.subscription_manager.payment_successful_for_renewal(subscription)
+  end
+end
+```
+
 ## Initialization
 Run the generator to create the initializer file and the migrations:
 ```

data/lib/core_merchant/subscription.rb

@@ -51,7 +51,7 @@ module CoreMerchant
   #   subscription.start
   #   subscription.cancel(reason: "Too expensive", at_period_end: true)
   #   ```
-  class Subscription < ActiveRecord::Base # rubocop:disable Metrics/ClassLength
+  class Subscription < ActiveRecord::Base
     include CoreMerchant::Concerns::SubscriptionStateMachine
     include CoreMerchant::Concerns::SubscriptionNotifications
     include CoreMerchant::Concerns::SubscriptionEventAssociation
@@ -89,18 +89,7 @@ module CoreMerchant
     # Starts the subscription.
     # Sets the current period start and end dates based on the plan's duration.
     def start
-      new_period_start = start_date
-      new_period_end = new_period_start + subscription_plan.duration_in_date
-
-      transaction do
-        transition_to_active!
-        update!(
-          current_period_start: new_period_start.to_date,
-          current_period_end: new_period_end.to_date
-        )
-      end
-
-      notify_subscription_manager(:started)
+      CoreMerchant.subscription_manager.start_subscription(self)
     end
 
     # Cancels the subscription.
@@ -110,26 +99,13 @@ module CoreMerchant
     #   Otherwise, the subscription will be canceled immediately.
     #   Default is `true`.
     def cancel(reason:, at_period_end: true)
-      transaction do
-        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
-
-      notify_subscription_manager(:canceled, reason: reason, immediate: !at_period_end)
-      cancellation_events.create!(reason: reason, at_period_end: at_period_end)
+      CoreMerchant.subscription_manager.cancel_subscription(self, reason: reason, at_period_end: 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_start = current_period_end || start_date
       new_period_end = new_period_start + subscription_plan.duration_in_date
 
       update!(

data/lib/core_merchant/subscription_manager.rb

@@ -40,41 +40,95 @@ module CoreMerchant
       @listeners = []
     end
 
+    # Checks all subscriptions for renewals and cancellations.
+    # Call this method periodically (probably daily) to check for subscriptions that need attention.
+    # This method will notify listeners when subscriptions are due for renewal or cancellation.
     def check_subscriptions
       check_renewals
       check_cancellations
     end
 
+    # Adds a listener to the list of listeners.
+    # You probably don't need to call this method directly. Instead, set the listener in the configuration.
+    # config.subscription_listener_class = "MySubscriptionListener"
     def add_listener(listener)
       @listeners << listener
     end
 
+    # Checks all subscriptions for renewals. Called by `check_subscriptions`.
     def check_renewals
       Subscription.find_each do |subscription|
         process_for_renewal(subscription) if subscription.due_for_renewal?
       end
     end
 
+    # Starts the subscription.
+    # Sets the current period start and end dates based on the plan's duration.
+    def start_subscription(subscription)
+      subscription.transaction do
+        subscription.start_new_period
+        subscription.transition_to_active!
+      end
+
+      notify(subscription, :started)
+    end
+
+    # Cancels the subscription.
+    # Parameters:
+    # - `reason`: Reason for cancellation
+    # - `at_period_end`: If true, the subscription will be canceled at the end of the current period.
+    #   Otherwise, the subscription will be canceled immediately.
+    #   Default is `true`.
+    def cancel_subscription(subscription, reason:, at_period_end: true)
+      subscription.transaction do
+        if at_period_end
+          subscription.transition_to_pending_cancellation!
+        else
+          subscription.transition_to_canceled!
+        end
+        subscription.update!(
+          canceled_at: at_period_end ? subscription.current_period_end : Time.current,
+          cancellation_reason: reason
+        )
+      end
+
+      notify(subscription, :canceled, reason: reason, immediate: !at_period_end)
+      subscription.cancellation_events.create!(reason: reason, at_period_end: at_period_end)
+    end
+
+    # Starts the subscription renewal process.
+    # This method is called when a subscription is due for renewal. It will in turn call notify the listener.
+    # When you receive a notification that a subscription is due for renewal, you should either call
+    # `no_payment_needed_for_renewal`, `processing_payment_for_renewal`, `payment_successful_for_renewal`, or
+    # `payment_failed_for_renewal` to continue the renewal process.
     def process_for_renewal(subscription)
       return unless subscription.transition_to_processing_renewal
 
       notify(subscription, :due_for_renewal)
     end
 
+    # Call this method when a subscription is renewed without payment.
+    # It will renew the subscription and notify listeners.
     def no_payment_needed_for_renewal(subscription)
       renew_subscription(subscription)
     end
 
+    # Call this method when payment is being processed for a renewal. This needs to be followed by either
+    # `payment_successful_for_renewal` or `payment_failed_for_renewal`.
     def processing_payment_for_renewal(subscription)
       return unless subscription.transition_to_processing_payment
 
       notify(subscription, :renewal_payment_processing)
     end
 
+    # Call this method when payment was successful for a renewal.
+    # It will renew the subscription and notify listeners.
     def payment_successful_for_renewal(subscription)
       renew_subscription(subscription)
     end
 
+    # Call this method when payment failed for a renewal.
+    # It will transition the subscription to past due when in grace period, or expired if not.
     def payment_failed_for_renewal(subscription)
       is_in_grace_period = subscription.in_grace_period?
       if is_in_grace_period
@@ -86,12 +140,15 @@ module CoreMerchant
       end
     end
 
+    # Checks all subscriptions for cancellations. Called by `check_subscriptions`.
     def check_cancellations
       Subscription.find_each do |subscription|
         process_for_cancellation(subscription) if subscription.pending_cancellation?
       end
     end
 
+    # Processes a subscription for cancellation.
+    # This method is called when a subscription is pending cancellation.
     def process_for_cancellation(subscription)
       return unless subscription.transition_to_expired
 

data/lib/core_merchant/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: core_merchant
 version: !ruby/object:Gem::Version
-  version: 0.10.3
+  version: 0.11.0
 platform: ruby
 authors:
 - Seyithan Teymur