koudoku 0.0.2

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in koudoku.gemspec
+gemspec

data/README.md

@@ -0,0 +1,111 @@
+# Koudoku
+
+Robust subscription support for Ruby on Rails apps using [Stripe](https://stripe.com). Makes it easy to manage actions related to new subscriptions, upgrades, downgrades, cancelations, as well as hooking up notifications, metrics logging, coupons, etc.
+
+## Installation
+
+Include the following in your `Gemfile`:
+
+    gem 'koudoku'
+
+## Usage
+
+There are no generators at the moment, so you'll need to generate plans, subscriptions, and (optionally) coupons on your own:
+
+### Subscriptions
+
+    rails g model subscription stripe_id:string plan_id:integer last_four:string coupon_id:integer current_price:float user_id:integer
+    
+Only include `coupon_id` if you want to support coupons. The `user_id` property should actually be the foreign key for whatever model you want your subscriptions to relate to. (User is just the default.)
+
+Then, dress up your subscription model by including the `Koudoku::Subscription` module and defining some essential relationships:
+
+    class Subscription < ActiveRecord::Base
+      include Koudoku::Subscription
+
+      # Belongs to user. (This is the default.)
+      attr_accessible :user_id
+      belongs_to :user
+  
+      # Supports coupons.
+      attr_accessible :coupon_id
+      belongs_to :coupon
+
+    end
+
+### Plans
+
+    rails g model plan name:string stripe_id:string price:float
+    
+The `stripe_id` for each plan must match the ID from Stripe. The price here isn't affected by (nor does it affect) the price in Stripe.
+
+You'll need to create a few plans to start. (You don't need to create a plan to represent "free" accounts.)
+
+    Plan.create(name: 'Personal', price: '10.00')
+    Plan.create(name: 'Team', price: '30.00')
+    Plan.create(name: 'Enterprise', price: '100.00')
+
+### Coupons
+
+Again, this is only required if you want to support coupons:
+
+    rails g model coupon code:string free_trial_length:string
+
+
+## Subscriptions That Belong to Models Other than User
+
+Here's an example of a subscription that belongs to a company rather than a user:
+
+    class Subscription < ActiveRecord::Base
+      include Koudoku::Subscription
+
+      # Ownership.
+      attr_accessible :company_id
+      belongs_to :company
+
+      # Inform Koudoku::Subscription how to identify the owner of the subscription.
+      def subscription_owner
+        company
+      end
+  
+      # Inform Koudoku::Subscription how to represent the owner in emails, etc.
+      def subscription_owner_description
+        "#{company.name} (#{company.primary_contact_name})"
+      end
+
+    end
+
+
+## Using Coupons
+
+While more robust coupon support is expected in the future, the simple way to use a coupon is to first create it:
+
+    coupon = Coupon.create(code: '30-days-free', free_trial_length: 30)
+    
+Then assign it to a _new_ subscription before saving:
+
+    subscription = Subscription.new(...)
+    subscription.coupon = coupon
+    subscription.save
+    
+    
+## Implementing Logging, Notifications, etc.
+
+The included module defined the following empty "template methods" which you're able to provide an implementation for:
+
+ - `prepare_for_plan_change`
+ - `prepare_for_new_subscription`
+ - `prepare_for_upgrade`
+ - `prepare_for_downgrade`
+ - `prepare_for_cancelation`
+ - `finalize_plan_change!`
+ - `finalize_new_subscription!`
+ - `finalize_upgrade!`
+ - `finalize_downgrade!`
+ - `finalize_cancelation!`
+ - `card_was_declined`
+
+Be sure to include a call to `super` in each of your implementations, especially if you're using multiple concerns to break all this logic into smaller pieces.
+
+Between `prepare_for_*` and `finalize_*`, so far I've used `finalize_*` almost exclusively. The difference is that `prepare_for_*` runs before we settle things with Stripe, and `finalize_*` runs after everything is settled in Stripe. For that reason, please be sure not to implement anything in `finalize_*` implementations that might cause issues with ActiveRecord saving the updated state of the subscription.
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/koudoku.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "koudoku/version"
+
+Gem::Specification.new do |s|
+  s.name        = "koudoku"
+  s.version     = Koudoku::VERSION
+  s.authors     = ["Andrew Culver"]
+  s.email       = ["andrew.culver@gmail.com"]
+  s.homepage    = "http://github.com/andrewculver/koudoku"
+  s.summary     = %q{Robust subscription support for Rails with Stripe.}
+  s.description = %q{Robust subscription support for Rails with Stripe. Provides package levels, coupons, logging, notifications, etc.}
+
+  s.rubyforge_project = "koudoku"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "rails"
+  s.add_dependency "stripe"
+  
+end

data/lib/koudoku.rb

@@ -0,0 +1,5 @@
+require "koudoku/version"
+require "koudoku/subscription"
+
+module Koudoku
+end

data/lib/koudoku/subscription.rb

@@ -0,0 +1,188 @@
+module Koudoku::Subscription
+  extend ActiveSupport::Concern
+
+  included do
+
+    attr_accessible :plan_id, :stripe_id, :current_price
+
+    # We don't store these one-time use tokens, but this is what Strie provides
+    # client-side after storing the credit card information.
+    attr_accessor :credit_card_token
+
+    belongs_to :plan
+
+    # update details.
+    before_save do
+
+      # if their package level has changed ..
+      if changing_plans? 
+
+        prepare_for_plan_change
+
+        # and a customer exists in stripe ..
+        if stripe_id.present?
+
+          # fetch the customer.
+          customer = Stripe::Customer.retrieve(self.stripe_id)
+
+          # if a new plan has been selected
+          if self.plan.present?
+
+            # Record the new plan pricing.
+            self.current_price = self.plan.price
+
+            prepare_for_downgrade if downgrading?
+            prepare_for_upgrade if upgrading?
+
+            # update the package level with stripe.
+            customer.update_subscription(:plan => self.plan.stripe_id)
+
+            finalize_downgrade! if downgrading?
+            finalize_upgrade! if upgrading?
+
+          # if no plan has been selected.
+          else
+
+            prepare_for_cancelation
+
+            # Remove the current pricing.
+            self.current_price = nil
+
+            # delete the subscription.
+            customer.cancel_subscription
+
+            finalize_cancelation!
+
+          end
+
+        # otherwise
+        else
+
+          # if a new plan has been selected
+          if self.plan.present?
+
+            # Record the new plan pricing.
+            self.current_price = self.plan.price
+
+            prepare_for_new_subscription
+            prepare_for_upgrade
+
+            begin
+
+              customer_attributes = {
+                description: subscription_owner_description,
+                card: credit_card_token, # obtained with Stripe.js
+                plan: plan.stripe_id
+              }
+
+              # If the class we're being included in supports coupons ..
+              if respond_to? :coupon
+                if coupon.present? and coupon.free_trial?
+                  customer_attributes[:trial_end] = coupon.free_trial_ends.to_i
+                end
+              end
+
+              # create a customer at that package level.
+              customer = Stripe::Customer.create(customer_attributes)
+
+            rescue Stripe::CardError => card_error
+              errors[:base] << card_error.message
+              card_was_declined
+              return false
+            end
+
+            # store the customer id.
+            self.stripe_id = customer.id
+            self.last_four = customer.active_card.last4
+
+            finalize_new_subscription!
+            finalize_upgrade!
+
+          else
+
+            # This should never happen.
+
+            self.plan_id = nil
+
+            # Remove any plan pricing.
+            self.current_price = nil
+
+          end
+
+        end
+
+        finalize_plan_change!
+
+      end
+
+    end
+
+  end
+
+  module ClassMethods
+  end
+
+  module InstanceMethods
+
+    # Pretty sure this wouldn't conflict with anything someone would put in their model
+    def subscription_owner
+      # Return whatever we belong to.
+      # If this object doesn't respond to 'name', please update owner_description.
+      user
+    end
+
+    def subscription_owner_description
+      # assuming owner responds to name.
+      # we should check for whether it responds to this or not.
+      "#{subscription_owner.name} (#{subscription_owner.id})"
+    end
+
+    def changing_plans?
+      plan_id_changed?
+    end
+
+    def downgrading?
+      plan.present? and plan_id_was.present? and plan_id_was > self.plan_id
+    end
+
+    def upgrading?
+      (plan_id_was.present? and plan_id_was < plan_id) or plan_id_was.nil?
+    end
+
+    # Template methods.
+    def prepare_for_plan_change
+    end
+
+    def prepare_for_new_subscription
+    end
+
+    def prepare_for_upgrade
+    end
+
+    def prepare_for_downgrade
+    end
+
+    def prepare_for_cancelation
+    end
+
+    def finalize_plan_change!
+    end
+
+    def finalize_new_subscription!
+    end
+
+    def finalize_upgrade!
+    end
+
+    def finalize_downgrade!
+    end
+
+    def finalize_cancelation!
+    end
+
+    def card_was_declined
+    end
+
+  end
+
+end

data/lib/koudoku/version.rb

@@ -0,0 +1,3 @@
+module Koudoku
+  VERSION = "0.0.2"
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: koudoku
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Andrew Culver
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: &70303128505700 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70303128505700
+- !ruby/object:Gem::Dependency
+  name: stripe
+  requirement: &70303128502880 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70303128502880
+description: Robust subscription support for Rails with Stripe. Provides package levels,
+  coupons, logging, notifications, etc.
+email:
+- andrew.culver@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- koudoku.gemspec
+- lib/koudoku.rb
+- lib/koudoku/subscription.rb
+- lib/koudoku/version.rb
+homepage: http://github.com/andrewculver/koudoku
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: koudoku
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Robust subscription support for Rails with Stripe.
+test_files: []