bank_teller 0.1.0

data/README.md

@@ -0,0 +1,156 @@
+# Bank Teller
+[![Code Climate](https://codeclimate.com/repos/572c190b20916e00680030b0/badges/df6d434fec0219cc1364/gpa.svg)](https://codeclimate.com/repos/572c190b20916e00680030b0/feed)
+
+Bank Teller is a Ruby on Rails interface for interacting with Stripe. It is an implementation the Laravel library, [Cashier](http://github.com/laravel/cashier). Major props to Taylor Otwell and all of the contributors to Cashier, it's amazing. Bank Teller has some minor API differences from Cashier, mostly to match the Ruby style. To quote the Cashier project: "It handles almost all of the boilerplate subscription billing code you are dreading writing... coupons, swapping subscription, subscription 'quantities', cancellation grace periods, and invoice PDFs."
+
+This gem cannot be used as a stand-alone gem. It is very tightly integrated with ActiveSupport and ActiveRecord. This gem is best used in a Ruby on Rails application.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bank_teller'
+```
+
+And then execute:
+
+    $ bundle
+
+Bank Teller comes with a couple of migrations:
+  1. A migration to add fields to a `users` table. `users` should already exist.
+  2. A migration to create a `subscriptions` table.
+
+To add these migrations to your application, run:
+
+    $ rails generate bank_teller:install
+    $ rake db:migrate
+
+## Usage
+### Setting It Up
+Stripe requires a private API key. Once you have aquired your private key, you'll need to set the environment variable `ENV["STRIPE_API_KEY"]` equal to your API key. If you're not sure how to use environment variables, checkout [Figaro](https://github.com/laserlemon/figaro) or my favorite, [dotenv](https://github.com/bkeepers/dotenv).
+
+Once you have your key in place, all you need to do is include the `Billable` module in your `User` class:
+
+```ruby
+# app/models/user.rb
+class User < ActiveRecord::Base
+  include Billable
+end
+```
+
+### Make Some Money
+#### Create a Subscription
+```ruby
+user = User.find(1)
+user.new_subscription('main', 'monthly').create(token)
+```
+
+`#new_subscription` is a method call on a `User` object that takes two arguments:
+  1. The name of the plan, for internal use
+  2. The ID of the plan you created with Stripe
+
+`#create` takes one argument, the stripe credit card token. It sends the subscription to Stripe and creates the subscription record in the databse.
+
+You can also send addtional fields for the user when creating a new subscription.
+
+```ruby
+user.new_subscription('main', 'monthly').create(token, { email: 'john@johndoe.com' })
+```
+
+To see all the options, [checkout the Stripe docs](https://stripe.com/docs/api#create_customer).
+
+##### Coupons!
+```ruby
+user.new_subscription('main', 'monthly', coupon: 'code').create(token)
+```
+
+<hr>
+
+#### Subscription Status
+##### Active(ness)
+See if a user has an active subscription:
+```ruby
+user.subscribed?('main')
+```
+
+See if a user's subscription is still on a trial:
+```ruby
+user.subscription('main').on_trial?
+```
+
+See if a user is subscribed to a specific plan:
+```ruby
+user.subscribed_to_plan?('main', 'monthly')
+```
+
+##### Cancellations
+See if a user has cancelled their subscription:
+```ruby
+user.subscription('main').cancelled?
+```
+
+See if a user has cancelled their subscription, but still has a grace period:
+```ruby
+user.subscription('main').on_grace_period?
+```
+
+#### Switch Plans
+Swap between different Stripe plans:
+```ruby
+user.subscription('main').swap('another-stripe-plan-id')
+```
+
+#### Quantity
+Add 1 to the quantity of plans:
+```ruby
+user.subscription('main').increment_quantity
+```
+
+Add n to the quantity of plans:
+```ruby
+user.subscription('main').increment_quantity(10)
+```
+
+Remove 1 from the quantity of plans:
+```ruby
+user.subscription('main').decrement_quantity
+```
+
+Remove n from the quantity of plans:
+```ruby
+user.subscription('main').decrement_quantity(10)
+```
+
+Directly update the quantity of plans:
+```ruby
+user.subscription('main').update_quantity(20)
+```
+
+#### Taxes
+To charge tax for your plans, overwrite the `tax_percentage` method in your `User` class:
+```ruby
+# app/models/user.rb
+class User < ActiveRecord::Base
+  def tax_percentage
+    9.25
+  end
+end
+```
+
+#### Cancel Subscriptions
+Cancel a subscription with a grace period (time remaining in the active plan):
+```ruby
+user.subscription('main').cancel
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jasoncharnes/bank_teller.
+

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/bank_teller.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bank_teller/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bank_teller"
+  spec.version       = BankTeller::VERSION
+  spec.authors       = ["Jason Charnes"]
+  spec.email         = ["jason@jasoncharnes.com"]
+
+  spec.summary       = %q{A subscription billing interface modeled after Laravel Cashier}
+  spec.description   = %q{A subscription billing interface modeled after Laravel Cashier}
+  spec.homepage      = "http://www.github.com/jasoncharnes/bank_teller"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib", "app"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_runtime_dependency 'stripe', "~> 1.42.0"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "bank_teller"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/bank_teller/engine.rb

@@ -0,0 +1,5 @@
+module BankTeller
+  class Engine < ::Rails::Engine
+    config.autoload_paths += Dir["#{config.root}/lib/**/"]
+  end
+end

data/lib/bank_teller/version.rb

@@ -0,0 +1,3 @@
+module BankTeller
+  VERSION = "0.1.0"
+end

data/lib/bank_teller.rb

@@ -0,0 +1,70 @@
+require "bank_teller/version"
+require 'bank_teller/engine' if defined?(Rails)
+
+module BankTeller
+  # The current currency.
+  #
+  # @return [String]
+  @@currency = 'usd'
+
+  # The current currency symbol.
+  #
+  # @return [String]
+  @@currency_symbol = '$'
+
+  # The custom currency formatter.
+  #
+  # @return [Lambda]
+  @@format_currency_using = nil
+
+  # Set the currency to be used when billing users.
+  #
+  # @param currency [Integer]
+  # @param symbol [String]
+  # @return [Boolean]
+  def self.use_currency(currency, symbol = nil)
+    @@currency = currency
+    symbol = self.guess_currency_symbol(currency) if symbol.nil?
+    self.use_currency_symbol(symbol)
+  end
+
+  def self.guess_currency_symbol(currency)
+    case currency.downcase
+    when 'usd', 'cad', 'aud'
+      '$'
+    when 'eur'
+      '€'
+    when 'gbp'
+      '£'
+    else
+      raise 'You must explicitly specify the currency symbol.'
+    end
+  end
+
+  def self.use_currency_symbol(symbol)
+    @@currency_symbol = symbol
+  end
+
+  def self.uses_currency
+    @@currency
+  end
+
+  def self.uses_currency_symbol
+    @@currency_symbol
+  end
+
+  def self.formatCurrencyUsing(callback)
+    @@format_currency_using = callback
+  end
+
+  def self.format_amount(amount)
+    self.format_currency_using(amount) if @@format_currency_using
+    amount = sprintf("%03d", amount).insert(-3, ".")
+
+    if amount.start_with?('-')
+      return "-#{self.uses_currency_symbol}#{amount.sub!(/^-/, '')}"
+    end
+
+    "#{uses_currency_symbol}#{amount}"
+  end
+end

data/lib/billable.rb

@@ -0,0 +1,204 @@
+require 'subscription_builder'
+require 'stripe'
+
+module Billable
+  def self.included(base)
+    base.class_eval do
+      has_many :subscriptions
+      Stripe.api_key = ENV["STRIPE_API_KEY"]
+    end
+  end
+
+  def charge(amount, options = {})
+    options.merge!({ currency: preferred_currency })
+    options[:amount] = amount
+
+    if !options.key?('source') && stripe_id
+      options[:customer] = stripe_id
+    end
+
+    if !options.key?('source') && !options.key?('customer')
+      raise 'No payment source provided.'
+    end
+
+    Stripe::Charge.create(options)
+  end
+
+  def refund(charge, options = {})
+    options[:charge] = charge
+    Stripe::Refund.create(options)
+  end
+
+  def invoice_for(description, amount, options = {})
+    if !stripe_id
+      raise 'User is not a customer. See the create_as_stripe_customer method.'
+    end
+
+    options.merge!({
+      customer: stripe_id,
+      amount: amount,
+      currency: preferred_currency,
+      description: description
+    })
+
+    Stripe::InvoiceItem.create(options)
+  end
+
+  def new_subscription(subscription, plan, *args)
+    SubscriptionBuilder.new(self, subscription, plan, *args)
+  end
+
+  def on_trial?(subscription = 'default', plan = nil)
+    return true if on_generic_trial?
+    subscription = get_subscription(subscription)
+
+    if plan.nil?
+      has_subscription_on_trial?(subscription)
+    else
+      has_subscription_on_trial?(subscription) && stripe_plan === plan
+    end
+  end
+
+  def has_subscription_on_trial?(subscription)
+    subscription && subscription.on_trial
+  end
+
+  def on_generic_trial?
+    trial_ends_at && DateTime.now < trial_ends_at.to_datetime
+  end
+
+  def subscribed?(subscription = 'default', plan = nil)
+    subscription = get_subscription(subscription)
+
+    if subscription.nil?
+      false
+    elsif plan.nil?
+      subscription.valid
+    else
+      subscription.valid && stripe_plan === plan
+    end
+  end
+
+  def get_subscription(subscription = 'default')
+    subscription_in_db = subscriptions.order(created_at: :desc).first
+    subscription_in_db if subscription_in_db.name === subscription
+  end
+
+  def subscription(name)
+    get_subscription(name)
+  end
+
+  def invoice
+    Stripe::Invoice.create(customer: stripe_id).pay
+  rescue
+    false
+  end
+
+  def upcoming_invoice
+    args = { customer: stripe_id }
+    stripe_invoice = Stripe::Invoice.upcoming(args)
+    Invoice.new(self, stripe_invoice)
+  rescue
+    false
+  end
+
+  def find_invoice(id)
+    stripe_invoice = Stripe::Invoice.retrieve(id)
+    Invoice.new(self, stripe_invoice)
+  rescue
+    false
+  end
+
+  def find_invoice_or_fail(id)
+    invoice = find_invoice(id)
+    raise 'Invoice not found' if invoice.nil?
+    invoice
+  end
+
+  def download_invoice(id, data, storage_path = nil)
+    # Coming Soon
+  end
+
+  def invoices(include_pending = false, parameters = {})
+    invoices = []
+    parameters.merge!({ limit: 24 })
+    stripe_invoices = as_stripe_customer.invoices(parameters)
+
+    unless stripe_invoices.nil?
+      stripe_invoices.data.each do |invoice|
+        if invoice.paid || include_pending
+          invoices << Invoice.new(self, invoice)
+        end
+      end
+    end
+
+    invoices
+  end
+
+  def invoices_including_pending(parameters = [])
+    invoices(true, parameters)
+  end
+
+  def update_card(token)
+    customer = as_stripe_customer
+    token = Stripe::Token.retrieve(token)
+    return if token.card.id === customer.default_source
+
+    card = customer.sources.create(source: token)
+    customer.default_source = card.id
+    customer.save
+
+    if customer.default_source
+      source = customer.sources.retrieve(customer.default_source)
+    end
+
+    if source
+      self.card_brand = source.brand
+      self.card_last_four = source.last4
+    end
+
+    self.save
+  end
+
+  def apply_coupon(coupon)
+    customer = as_stripe_customer
+    customer.coupon = coupon
+    customer.save
+  end
+
+  def subscribed_to_plan?(subscription = 'default', plan)
+    subscription = get_subscription(subscription)
+    return false unless subscription || subscription.valid
+    subscription.stripe_plan === plan
+  end
+
+  def on_plan(plan)
+    subscription = subscriptions.first
+    subscription.stripe_plan === plan && subscription.valid
+  end
+
+  def has_stripe_id
+    !!stripe_id
+  end
+
+  def create_as_stripe_customer(token, options = {})
+    options.merge!({ email: email })
+    customer = Stripe::Customer.create(options)
+    self.stripe_id = customer.id
+    self.save
+    update_card(token) unless token.nil?
+    customer
+  end
+
+  def as_stripe_customer
+    Stripe::Customer.retrieve(stripe_id)
+  end
+
+  def preferred_currency
+    BankTeller::uses_currency
+  end
+
+  def tax_percentage
+    0
+  end
+end

data/lib/generators/bank_teller/install_generator.rb

@@ -0,0 +1,31 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module BankTeller
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+    extend ActiveRecord::Generators::Migration
+
+    desc "Install the migrations needed for Bank Teller."
+    class_option :provider, type: :string, default: :stripe
+    source_root File.expand_path('../templates', __FILE__)
+
+    def self.next_migration_number(*)
+      sleep 1 # Prevents Duplicate Timestamps on FAAAAST Machines
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    end
+
+    def alter_users
+      if ActiveRecord::Base.connection.table_exists?('users')
+        migration_template "add_bank_teller_fields_to_users.rb", "db/migrate/add_bank_teller_fields_to_users.rb"
+      else
+        raise "You must have a users table to install Bank Teller."
+      end
+    end
+
+    def create_subscriptions
+      migration_template "create_subscriptions.rb", "db/migrate/create_subscriptions.rb"
+    end
+  end
+end

data/lib/generators/bank_teller/templates/add_bank_teller_fields_to_users.rb

@@ -0,0 +1,30 @@
+class AddBankTellerFieldsToUsers < ActiveRecord::Migration
+  def self.up
+    unless column_exists? :users, :email
+      add_column :users, :email, :string
+    end
+
+    unless column_exists? :users, :stripe_id
+      add_column :users, :stripe_id, :string
+    end
+
+    unless column_exists? :users, :card_brand
+      add_column :users, :card_brand, :string
+    end
+
+    unless column_exists? :users, :card_last_four
+      add_column :users, :card_last_four, :string
+    end
+
+    unless column_exists? :users, :trial_ends_at
+      add_column :users, :trial_ends_at, :datetime
+    end
+  end
+
+  def self.down
+    remove_column :users, :stripe_id, :string
+    remove_column :users, :card_brand, :string
+    remove_column :users, :card_last_four, :string
+    remove_column :users, :trial_ends_at, :datetime
+  end
+end

data/lib/generators/bank_teller/templates/create_subscriptions.rb

@@ -0,0 +1,16 @@
+class CreateSubscriptions < ActiveRecord::Migration
+  def change
+    create_table :subscriptions do |t|
+      t.integer :user_id, null: false
+      t.string :name, null: false
+      t.string :stripe_id, null: false
+      t.string :stripe_plan, null: false
+      t.integer :quantity, null: false
+      t.string :stripe_plan
+      t.datetime :trial_ends_at
+      t.datetime :ends_at
+
+      t.timestamps null: false
+    end
+  end
+end

data/lib/invoice.rb

@@ -0,0 +1,115 @@
+class Invoice
+  def initialize(user, invoice)
+    @user = user
+    @invoice = invoice
+  end
+
+  def date(timezone = nil)
+    invoice.to_time.in_time_zone(timezone).to_date
+  end
+
+  def total
+    format_amount(raw_total)
+  end
+
+  def raw_total
+    amount = invoice.total - (raw_starting_balance * -1)
+    [0, amount].max
+  end
+
+  def subtotal
+    amount = invoice.subtotal - raw_starting_balance
+    amount = [0, amount].max
+    format_amount(amount)
+  end
+
+  def has_starting_balance?
+    raw_starting_balance > 0
+  end
+
+  def starting_balance
+    format_amount(raw_starting_balance)
+  end
+
+  def has_discount
+    invoice.subtotal > 0 and
+      invoice.subtotal != invoice.total and
+        !invoice.discount.nil?
+  end
+
+  def discount
+    amount = invoice.subtotal - invoice.total
+    format_amount(amount)
+  end
+
+  def coupon
+    invoice.discount.coupon.id if invoice.discount
+  end
+
+  def discount_is_percentage?
+    coupon and invoice.discount.coupon.percent_off
+  end
+
+  def percent_off
+    if coupon
+      invoice.discount.coupon.percent_off
+    else
+      0
+    end
+  end
+
+  def amount_off
+    amount = invoice.discount.coupon.amount_off || 0
+    format_amount(amount)
+  end
+
+  def invoice_items
+    invoice_items_by_type('invoiceitem')
+  end
+
+  def subscriptions
+    invoice_items_by_type('subscription')
+  end
+
+  def invoice_items_by_type(type)
+    line_items = []
+
+    if lines.data
+      lines.data.each do |line|
+        if line.type == type
+          line_items << InvoiceItem.new(user, line)
+        end
+      end
+    end
+
+    line_items
+  end
+
+  def format_amount(amount)
+    BankTeller::format_amount(amount)
+  end
+
+  def view(data)
+    # Coming Soon
+  end
+
+  def pdf(data)
+    # Coming Soon
+  end
+
+  def download(data)
+    # Coming Soon
+  end
+
+  def raw_starting_balance
+    invoice.starting_balance || 0
+  end
+
+  def as_stripe_invoice
+    invoice
+  end
+
+  protected
+
+  attr_accessor :user, :invoice
+end