pay 0.0.2 → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 92f9482ce3c201c076c2717a75c9e0670f412c4b
-  data.tar.gz: cd8a5de08bf9fdf46b71648202967b3202615f9c
+SHA256:
+  metadata.gz: 39a6a209996b8c3b63ddb74f21be8d17077fc6319def22dab795978f5bdf2f35
+  data.tar.gz: 0b27221f94c0dbbb34f4a3931c2fa8b39b1961773069ba28a9979418631ed309
 SHA512:
-  metadata.gz: 7383c1f3dcbd887dd185c4cc28277513e4d9f1ab29229ebb042342ffb3301ad2e25e86dd45889c88b85df6a388ee831152c7ba594ccc14aef30f4ee0dae27336
-  data.tar.gz: a8431aee8abb65ff7d8550ed471ebdada798b686de30bfe21830554c1e59d509406e0031fd834236e1bbdd56cfb12f1c67b1c2455fff1a42a0a252da777dcf41
+  metadata.gz: cd5f398491802b0040c20b074941b2848a693d4c85dc1d41ee6cdc60af283dc45b79248e8405acd5cf609efd897f273f1b7e47025f6929d0e22adfa63ca0c96a
+  data.tar.gz: 7daad387da4860cdeb62b67f3d7cec7de2056bf9842d7a9d735f72fa4aa6748112452205f2d0198e0737389b902008aa8cc148597dfb268e06e56ecf81b5454f

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2017 Jason Charnes
+Copyright 2019 Jason Charnes
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,62 +1,110 @@
-# Pay
-[ ![Codeship Status for jasoncharnes/pay](https://img.shields.io/codeship/72941cf0-31a8-0135-af58-3a3212f0f89d/master.svg)](https://app.codeship.com/projects/225793)
+<p align="center"><img src="logo.png"></p>
 
-Pay is a subscription engine for Ruby on Rails.
+## Pay
 
-Supports Ruby on Rails 4.2 and higher.
+### Payments engine for Ruby on Rails
+
+[![Build Status](https://travis-ci.org/excid3/pay.svg?branch=master)](https://travis-ci.org/excid3/pay)
+
+Pay is a payments engine for Ruby on Rails 4.2 and higher.
 
 **Current Payment Providers**
-* Stripe
 
-**Payment Providers In Development**
-* Braintree
+- Stripe (API version [2018-08-23](https://stripe.com/docs/upgrades#2018-08-23) or higher required)
+- Braintree
 
 Want to add a new payment provider? Contributions are welcome and the instructions [are here](https://github.com/jasoncharnes/pay/wiki/New-Payment-Provider).
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
 gem 'pay'
+
+# To use Stripe, also include:
+gem 'stripe', '< 5.0', '>= 2.8'
+gem 'stripe_event', '~> 2.2'
+
+# To use Braintree + PayPal, also include:
+gem 'braintree', '< 3.0', '>= 2.92.0'
+
+# To use Receipts
+gem 'receipts', '~> 0.2.2'
 ```
 
 And then execute:
+
 ```bash
 $ bundle
 ```
 
 Or install it yourself as:
+
 ```bash
 $ gem install pay
 ```
 
 ## Setup
+
 #### Migrations
+
 This engine will create a subscription model and the neccessary migrations for the model you want to make "billable." The most common use case for the billable model is a User.
 
 To add the migrations to your application, run the following migration:
 
 `$ bin/rails pay:install:migrations`
 
-This will install two migrations:
-- db/migrate/create_subscriptions.rb
-- db/migrate/add_fields_to_users.rb
+This will install three migrations:
+
+- db/migrate/create_subscriptions.pay.rb
+- db/migrate/add_fields_to_users.pay.rb
+- db/migrate/create_charges.pay.rb
+
+#### The User Model
+
+If you have a `User` model defined in `app/models/user.rb` Pay will add the fields it needs to the `users` table.
+
+If you do not have a `User` model defined, Pay will create a `users` table and you will need to add `app/models/user.rb`.
 
 #### Non-User Model
+
 If you need to use a model other than `User`, check out the [wiki page](https://github.com/jasoncharnes/pay/wiki/Model-Other-Than-User).
 
 #### Run the Migrations
+
 Finally, run the migrations with `$ rake db:migrate`
 
+#### Getting NoMethodError?
+
+`NoMethodError (undefined method 'stripe_customer' for #<User:0x00007fbc34b9bf20>)`
+
+Fully restart your Rails application `bin/spring stop && rails s`
+
 #### Stripe
-You'll need to add your private Stripe API key to your Rails secrets. `config/secrets.yml`
+
+You'll need to add your private Stripe API key to your Rails secrets `config/secrets.yml`, credentials `rails credentials:edit`
 
 ```yaml
 development:
-  stripe_api_key: sk_test_....
+  stripe:
+    private_key: xxxx
+    public_key: yyyy
+    signing_secret: zzzz
 ```
 
+You can also use the `STRIPE_PRIVATE_KEY` and `STRIPE_SIGNING_SECRET` environment variables.
+
+**To see how to use Stripe Elements JS & Devise, [click here](https://github.com/jasoncharnes/pay/wiki/Using-Stripe-Elements-and-Devise).**
+
+#### Background jobs
+
+If a user's email is updated and they have a `processor_id` set, Pay will enqueue a background job (EmailSyncJob) to sync the email with the payment processor.
+
+It's important you set a queue_adapter for this to happen. If you don't, the code will be executed immediately upon user update. [More information here](https://guides.rubyonrails.org/v4.2/active_job_basics.html#backends)
+
 ## Usage
+
 Include the `Pay::Billable` module in the model you want to know about subscriptions.
 
 ```ruby
@@ -66,13 +114,125 @@ class User < ActiveRecord::Base
 end
 ```
 
-**To see how to use Stripe Elements JS & Devise, [click here](https://github.com/jasoncharnes/pay/wiki/Using-Stripe-Elements-and-Devise).**
+To sync over customer names, your `Billable` model should respond to the `first_name` and `last_name` methods. Pay will sync these over to your Customer objects in Stripe and Braintree.
+
+## Configuration
+
+Need to make some changes to how Pay is used? You can create an initializer `config/initializers/pay.rb`
+
+```ruby
+Pay.setup do |config|
+  config.billable_class = 'User'
+  config.billable_table = 'users'
+
+  config.chargeable_class = 'Pay::Charge'
+  config.chargeable_table = 'pay_charges'
+
+  # For use in the receipt/refund/renewal mailers
+  config.business_name = "Business Name"
+  config.business_address = "1600 Pennsylvania Avenue NW"
+  config.application_name = "My App"
+  config.support_email = "helpme@example.com"
+
+  config.send_emails = true
+end
+```
+
+This allows you to create your own Charge class for instance, which could add receipt functionality:
+
+```ruby
+class Charge < Pay::Charge
+  def receipts
+    # do some receipts stuff using the https://github.com/excid3/receipts gem
+  end
+end
+
+Pay.setup do |config|
+  config.chargeable_class = 'Charge'
+end
+```
+
+### Generators
+
+#### Email Templates
+
+If you want to modify the email templates, you can copy over the view files using:
+
+```
+$ bin/rails generate pay:email_views
+```
+
+## Emails
+
+### Stripe
+
+Emails can be enabled/disabled using the `send_emails` configuration option (enabled per default). When enabled, the following emails will be sent:
+
+- When a charge succeeded
+- When a charge was refunded
+- When a subscription is about to renew
 
 ## User API
+
+#### Trials
+
+You can check if the user is on a trial by simply asking:
+
+```ruby
+user = User.find_by(email: 'michael@bluthcompany.co')
+
+user.on_trial? #=> true or false
+```
+
+The `on_trial?` method has two optional arguments with default values.
+
+```ruby
+user = User.find_by(email: 'michael@bluthcompany.co')
+
+user.on_trial?(name: 'default', plan: 'plan') #=> true or false
+```
+
+#### Generic Trials
+
+For trials that don't require cards upfront:
+
+```ruby
+user = User.create(
+  email: 'michael@bluthcompany.co',
+  trial_ends_at: 30.days.from_now
+)
+
+user.on_generic_trial? #=> true
+```
+
+#### Creating a Charge
+
+```ruby
+user = User.find_by(email: 'michael@bluthcompany.co')
+
+user.processor = 'stripe'
+user.card_token = 'stripe-token'
+user.charge(1500) # $15.00 USD
+
+user = User.find_by(email: 'michael@bluthcompany.co')
+
+user.processor = 'braintree'
+user.card_token = 'nonce'
+user.charge(1500) # $15.00 USD
+```
+
+The `charge` method takes the amount in cents as the primary argument.
+
+You may pass optional arguments that will be directly passed on to
+either Stripe or Braintree. You can use these options to charge
+different currencies, etc.
+
 #### Creating a Subscription
 
 ```ruby
 user = User.find_by(email: 'michael@bluthcompany.co')
+
+user.processor = 'stripe'
 user.card_token = 'stripe-token'
 user.subscribe
 ```
@@ -82,23 +242,39 @@ A `card_token` must be provided as an attribute.
 The subscribe method has three optional arguments with default values.
 
 ```ruby
-def subscribe(name = 'default', plan = 'default', processor = 'stripe')
+def subscribe(name: 'default', plan: 'default', **options)
   ...
 end
 ```
 
 ##### Name
+
 Name is an internally used name for the subscription.
 
 ##### Plan
+
 Plan is the plan ID from the payment processor.
 
+##### Options
+
+They do something?
+
 #### Retrieving a Subscription from the Database
+
 ```ruby
 user = User.find_by(email: 'gob@bluthcompany.co')
+
 user.subscription
 ```
 
+A subscription can be retrieved by name, too.
+
+```ruby
+user = User.find_by(email: 'gob@bluthcompany.co')
+
+user.subscription(name: 'bananastand+')
+```
+
 #### Checking a User's Subscription Status
 
 ```ruby
@@ -109,31 +285,32 @@ user.subscribed?
 The `subscribed?` method has two optional arguments with default values.
 
 ```ruby
-def subscribed?(name = 'default', plan = nil)
+def subscribed?(name: 'default', plan: nil)
   ...
 end
 ```
 
 ##### Name
+
 Name is an internally used name for the subscription.
 
 ##### Plan
-Plan is the plan ID from the payment processor.
 
-##### Processor
-Processor is the string value of the payment processor subscription. Pay currently only supports Stripe, but other implementations are welcome.
+Plan is the plan ID from the payment processor.
 
 #### Retrieving a Payment Processor Account
 
 ```ruby
 user = User.find_by(email: 'george.michael@bluthcompany.co')
-user.customer
+
+user.customer #> Stripe or Braintree customer account
 ```
 
 #### Updating a Customer's Credit Card
 
 ```ruby
 user = User.find_by(email: 'tobias@bluthcompany.co')
+
 user.update_card('stripe-token')
 ```
 
@@ -141,42 +318,49 @@ user.update_card('stripe-token')
 
 ```ruby
 user = User.find_by(email: 'lucille@bluthcompany.co')
-user.processor_subscription(subscription_id)
+
+user.processor_subscription(subscription_id) #=> Stripe or Braintree Subscription
 ```
 
 ## Subscription API
+
 #### Checking a Subscription's Trial Status
 
 ```ruby
 user = User.find_by(email: 'lindsay@bluthcompany.co')
-user.subscription.on_trial?
+
+user.subscription.on_trial? #=> true or false
 ```
 
 #### Checking a Subscription's Cancellation Status
 
 ```ruby
 user = User.find_by(email: 'buster@bluthcompany.co')
-user.subscription.cancelled?
+
+user.subscription.cancelled? #=> true or false
 ```
 
 #### Checking a Subscription's Grace Period Status
 
 ```ruby
 user = User.find_by(email: 'her?@bluthcompany.co')
-user.subscription.on_grace_period?
+
+user.subscription.on_grace_period? #=> true or false
 ```
 
 #### Checking to See If a Subscription Is Active
 
 ```ruby
 user = User.find_by(email: 'carl.weathers@bluthcompany.co')
-user.subscription.active?
+
+user.subscription.active? #=> true or false
 ```
 
 #### Cancel a Subscription (At End of Billing Cycle)
 
 ```ruby
 user = User.find_by(email: 'oscar@bluthcompany.co')
+
 user.subscription.cancel
 ```
 
@@ -184,13 +368,23 @@ user.subscription.cancel
 
 ```ruby
 user = User.find_by(email: 'annyong@bluthcompany.co')
+
 user.subscription.cancel_now!
 ```
 
+#### Swap a Subscription to another Plan
+
+```ruby
+user = User.find_by(email: 'steve.holt@bluthcompany.co')
+
+user.subscription.swap("yearly")
+```
+
 #### Resume a Subscription on a Grace Period
 
 ```ruby
 user = User.find_by(email: 'steve.holt@bluthcompany.co')
+
 user.subscription.resume
 ```
 
@@ -198,23 +392,56 @@ user.subscription.resume
 
 ```ruby
 user = User.find_by(email: 'lucille2@bluthcompany.co')
+
 user.subscription.processor_subscription
 ```
 
+### Customizing Pay Models
+
+Want to add methods to `Pay::Subscription` or `Pay::Charge`? You can
+define a concern and simply include it in the model when Rails loads the
+code.
+
+Pay uses the `to_prepare` method to allow concerns to be
+included every time Rails reloads the models in development as well.
+
+```ruby
+# app/models/concerns/subscription_extensions.rb
+module SubscriptionExtensions
+  extend ActiveSupport::Concern
+
+  included do
+    # associations and other class level things go here
+  end
+
+  # instance methods and code go here
+end
+```
+
+```ruby
+# config/initializers/subscription_extensions.rb
+
+# Re-include the SubscriptionExtensions every time Rails reloads
+Rails.application.config.to_prepare do
+  Pay.subscription_model.include SubscriptionExtensions
+end
+```
+
 ## Contributors
-* [Jason Charnes](https://twitter.com/jmcharnes)
-* [Chris Oliver](https://twitter.com/excid3)
+
+- [Jason Charnes](https://twitter.com/jmcharnes)
+- [Chris Oliver](https://twitter.com/excid3)
 
 ## Contributing
+
 👋 Thanks for your interest in contributing. Feel free to fork this repo.
 
 If you have an issue you'd like to submit, please do so using the issue tracker in GitHub. In order for us to help you in the best way possible, please be as detailed as you can.
 
 If you'd like to open a PR please make sure the following things pass:
-* `rake test`
-* `rubocop`
 
-These will need to be passing in order for a Pull Request to be accepted.
+- `rake test`
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).