billing_cycle 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: de1567f4fc4e2813c2e8a24d7c38d4972de4dd92
-  data.tar.gz: e433e801af93c75c6d5dc056d9af3d34c236a0b3
+SHA256:
+  metadata.gz: 56e5ae7abb7f48642d430ade7fa35c530b9dae71d9a62f8a8ba9b9e17aa4d9f3
+  data.tar.gz: 35c7a99568dfa8ce123f87445deef160fa2fa5ae7a4db857590cf84ae9b69499
 SHA512:
-  metadata.gz: 0cb00109a6b6d23b477aa8c5b6b4c3304f8c39441bf42939f17624ab3e47300cb076727d7996dc44083f4596ae6487863016f2b0f3f5581dbd904d511c2b1878
-  data.tar.gz: 7cf9c934466b6d9c4092f87f8f3af6aa60b18817786529f86599371b749991ccaf36717ebf68474f28ffafed8eb12f112d4a46e2e5173e6a4afc0415e364972b
+  metadata.gz: 0577b5c653533ca5450de90f69570c1b6ccf89dac6f3ee14f0883d019d0939bd086f1023d7a3bc72dcef793cc8798b44cf019d41acd0df14c2269cc81514418d
+  data.tar.gz: c1c22e8c030535db87b7a2ab53bd535131f3fd61ecc935e1ce425f2150f24c8aa4e8e26805d8449f9f5e029d868958eb14f28ca05c0775973ea16d060f3c0877

data/README.md

@@ -5,7 +5,8 @@
 [![Test Coverage](https://codeclimate.com/github/simplymadeapps/billing_cycle/badges/coverage.svg)](https://codeclimate.com/github/simplymadeapps/billing_cycle/coverage)
 [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/simplymadeapps/billing_cycle/)
 
-Billing Cycle is a gem used to calculate the next billing date for a recurring subscription.
+Billing Cycle is a gem used to calculate the billing due dates and time elapsed/remaining in
+a recurring subscription's billing cycle.
 
 ## Installation
 
@@ -23,6 +24,12 @@ $ bundle
 
 ## Usage
 
+### Due Dates
+
+Calculating due dates requires the original billing date as an anchor to determine due dates
+in the future. `BillingCycle::BillingCycle` does the work to handle edge cases like having
+a monthly subscription that started on the 31st when there's not 31 days in every month.
+
 ```ruby
 original_billing_date = Time.zone.parse("2018-01-31 00:00:00")
 billing_interval = 1.month
@@ -34,11 +41,15 @@ Time.zone.now
 billing_cycle.next_due_at
 # => Sat, 30 Jun 2018 00:00:00 CDT -05:00
 
-billing_cycle.next_due_at(Time.zone.parse("2020-02-01 00:00:00")
-# => Sat, 29 Feb 2020 00:00:00 CST -06:00
-
 billing_cycle.previous_due_at
 # => Thu, 31 May 2018 00:00:00 CDT -05:00
+```
+
+A time can be passed in as "now" instead of implicitly using the current time.
+
+```ruby
+billing_cycle.next_due_at(Time.zone.parse("2020-02-01 00:00:00")
+# => Sat, 29 Feb 2020 00:00:00 CST -06:00
 
 billing_cycle.previous_due_at(Time.zone.parse("2020-02-01 00:00:00")
 # => Fri, 31 Jan 2020 00:00:00 CST -06:00
@@ -59,6 +70,67 @@ billing_cycle.previous_due_at
 # => nil
 ```
 
+### Time Elapsed and Remaining
+
+The time elapsed and remaining can be used for displaying how much time has been used
+and how much time is left in a billing cycle.
+
+```ruby
+original_billing_date = Time.zone.parse("2019-06-01 00:00:00")
+billing_interval = 1.month
+billing_cycle = BillingCycle::BillingCycle.new(original_billing_date, billing_interval)
+
+Time.zone.now
+# => Sun, 16 Jun 2019 00:00:00 CDT -05:00
+
+billing_cycle.time_elapsed
+# => 1296000.0 (seconds)
+
+billing_cycle.time_remaining
+# => 1296000.0 (seconds)
+```
+
+An interval can be passed in instead of implicitly using seconds and time can be passed in as "now"
+instead of implicitly using the current time.
+
+```ruby
+billing_cycle.time_elapsed(1.day, Time.zone.parse("2019-06-07 00:00:00"))
+# => 6.0 (days)
+
+billing_cycle.time_remaining(1.day, Time.zone.parse("2019-06-07 00:00:00"))
+# => 24.0 (days)
+```
+
+### Percent Elapsed and Remaining
+
+The percent elapsed and remaining can be used for calculating subscription pricing when charging
+or refunding for a partial billing cycle. The percentages are returned as a fraction of 1.0.
+
+```ruby
+original_billing_date = Time.zone.parse("2019-06-01 00:00:00")
+billing_interval = 1.month
+billing_cycle = BillingCycle::BillingCycle.new(original_billing_date, billing_interval)
+
+Time.zone.now
+# => Sun, 16 Jun 2019 00:00:00 CDT -05:00
+
+billing_cycle.percent_elapsed
+# => 0.5
+
+billing_cycle.percent_remaining
+# => 0.5
+```
+
+A time can be passed in as "now" instead of implicitly using the current time.
+
+```ruby
+billing_cycle.percent_elapsed(Time.zone.parse("2019-06-07 00:00:00"))
+# => 0.2
+
+billing_cycle.percent_remaining(Time.zone.parse("2019-06-07 00:00:00"))
+# => 0.8
+```
+
 ## Contributing
 
 1. Fork it
@@ -68,4 +140,5 @@ billing_cycle.previous_due_at
 5. Create new Pull Request
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/billing_cycle/billing_cycle.rb

@@ -35,6 +35,20 @@ module BillingCycle
       next_due_at
     end
 
+    # Returns the percentage of time that's elapsed between the previous due date and the next due date.
+    # @param now [Time] The current time
+    # @return [Float] The percentage as a fraction of 1.0
+    def percent_elapsed(now = Time.zone.now)
+      time_elapsed(1.second, now) / seconds_in_cycle(now)
+    end
+
+    # Returns the percentage of time that's remaining between the previous due date and the next due date.
+    # @param now [Time] The current time
+    # @return [Float] The percentage as a fraction of 1.0
+    def percent_remaining(now = Time.zone.now)
+      time_remaining(1.second, now) / seconds_in_cycle(now)
+    end
+
     # Returns the previous billing date based on the subscription
     # @param now [Time] The current time
     # @return [Time] The previous billing date/time
@@ -55,6 +69,21 @@ module BillingCycle
       previous_due_at
     end
 
+    # Returns the time elapsed since the previous due date.
+    # @param interval [ActiveSupport::Duration] The duration
+    # @param now [Time] The current time
+    # @return [Float] The number of intervals since the previous due date
+    def time_elapsed(interval = 1.second, now = Time.zone.now)
+      (now - previous_due_at(now)) / interval
+    end
+
+    # Returns the time remaining until the next due date.
+    # @param now [Time] The current time
+    # @return [Float] The number of intervals until the next due date
+    def time_remaining(interval = 1.second, now = Time.zone.now)
+      (next_due_at(now) - now) / interval
+    end
+
     private
 
     # Calculate the due date based on number of billing cycles since
@@ -86,9 +115,17 @@ module BillingCycle
     end
 
     # Returns the number billing cycles that have occurred between the created date and "now".
+    # @param now [Time] The current time
     # @return [Integer]
     def number_of_cycles_since_created(now)
       (interval_value * ((now - created_at).to_i / interval)).to_i
     end
+
+    # Returns the total number of seconds in the current billing cycle.
+    # @param now [Time] The current time
+    # @return [Float]
+    def seconds_in_cycle(now)
+      next_due_at(now) - previous_due_at(now)
+    end
   end
 end

data/lib/billing_cycle/version.rb

@@ -1,3 +1,3 @@
 module BillingCycle
-  VERSION = "1.0.0".freeze
+  VERSION = "1.1.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: billing_cycle
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Brian Pattison
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-10 00:00:00.000000000 Z
+date: 2019-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -155,8 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Utility for calculating the next billing date for a recurring subscription.