integrallis/stripe_saas

== StripeSaas

A Rails 4 Engine providing Stripe subscription management for SaaS applications.
Based on the work of Andrew Culver in Koudoku (https://github.com/andrewculver/koudoku).

== Status

image:https://www.codeship.io/projects/7ab95b50-8968-0133-979d-4619ccd24e37/status?branch=master[CI Status]
image:https://codeclimate.com/github/integrallis/stripe_saas/badges/gpa.svg[
"Code Climate",link="https://codeclimate.com/github/integrallis/stripe_saas"]
image:https://codeclimate.com/github/integrallis/stripe_saas/badges/coverage.svg[
"Test Coverage",link="https://codeclimate.com/github/integrallis/stripe_saas/coverage"]

== Installation

=== Add gem dependency

Include the stripe_saas gem in your Gemfile and bundle (install):

[source,ruby]
-------------------------------------------
gem 'stripe_saas'
-------------------------------------------

=== Install subscriptions management on a model.

A rails generator is provided to install the StripeSaas models:

[source,ruby]
-------------------------------------------
rails g stripe_saas:install user
-------------------------------------------

==== Stripe Subscriptions

A model that mirrors a Stripe subscription (https://stripe.com/docs/api/ruby#subscriptions)
is generated and a one-to-one relationship between it and one of your
application's models as the owner of the subscription.

In the example above the generated StripeSaas::Subscription 'belongs to' your
application's User:

[source,ruby]
-------------------------------------------
class Subscription < ActiveRecord::Base
  include StripeSaas::Subscription

  belongs_to :user
end
-------------------------------------------

and the User class will have one (has_one) subscription:

[source,ruby]
-------------------------------------------
has_one :subscription
-------------------------------------------

==== Stripe Plans

A model that mirrors a Stripe plan (https://stripe.com/docs/api/ruby#plans) is
generated.

[source,ruby]
-------------------------------------------
class Plan < ActiveRecord::Base
  has_many :subscriptions
  has_many :plan_features
  has_many :features, through: :plan_features

  default_scope { order(:display_order) }

  include StripeSaas::Plan
end
-------------------------------------------

Plans have PlanFeatures which in turn are join table/model between Plan and Feature:

[source,ruby]
-------------------------------------------
class Feature < ActiveRecord::Base
  has_many :plan_features
  has_many :plans, through: :plan_features

  default_scope { order(:display_order) }

  include StripeSaas::Feature
end
-------------------------------------------

To create a Feature for example, you could use:

[source,ruby]
-------------------------------------------
Feature.find_or_create_by(name: 'signals').update({
  description: "Inbound Signals",
  feature_type: :number,
  unit: "signals",
  display_order: 1
})
-------------------------------------------

Where the feature type can be one of:

[source,ruby]
-------------------------------------------
FEATURE_TYPES = {
  boolean: 'Boolean',
  interval: 'Interval (in seconds)',
  filesize: 'Filesize (in bytes)',
  number: 'Number',
  percentage: 'Percentage (%)'
}
-------------------------------------------

To create a plan (in your seeds for example) with a set of features you could use
something like:

[source,ruby]
-------------------------------------------
developer_plan = Plan.find_or_create_by(stripe_id: 'developer')
developer_plan.update({
  name: 'Developer',
  price: 0.0,
  interval: 'month',
  interval_count: 1,
  statement_descriptor: 'Binnacle Developer Plan',
  trial_period_days: 30,
  display_order: 1
})

developer_plan.add_feature(:signals, 50000)
-------------------------------------------

Any plan with a price of 0.0 is considered a free plan in StripeSaas which will
not require the user to enter credit card information.

After running the installer you will have to migrate your database:

[source,ruby]
-------------------------------------------
rake db:migrate
-------------------------------------------

== Configuration

As part of the installation procedure an initializer is generated under config/initializers/stripe_saas.rb:

[source,ruby]
-------------------------------------------
StripeSaas.setup do |config|
  config.subscriptions_owned_by = :user
  # config.devise_scope = :user
  config.stripe_publishable_key = ENV['STRIPE_PUBLISHABLE_KEY']
  config.stripe_secret_key = ENV['STRIPE_SECRET_KEY']
  config.create_plans_in_stripe = false
end
-------------------------------------------

* _subscriptions_owned_by_: The symbol of the class that owns the subscription
* _devise_scope_: If using Devise and the subscription is not owned by the devise
  class (user/customer). For example, if users have accounts, and accounts have
  subscriptions. Then config.subscriptions_owned_by = :account and config.devise_scope = :user
* _stripe_publishable_key_: Your Stripe Publishable Key https://stripe.com/docs/tutorials/dashboard#api-keys
* _stripe_secret_key_: Your Stripe Secret Key https://stripe.com/docs/tutorials/dashboard#api-keys
* _create_plans_in_stripe_: Whether to autogenerate the local Plans in Stripe and
  keep then in synch