Skip to content

Commit

Permalink
Gutting the high level API and VCR driven tests
Browse files Browse the repository at this point in the history 
in preparation for the rebuild
  • Loading branch information
@dmvt
dmvt committed Oct 19, 2016
1 parent 9070587 commit e55855c
Show file tree
Hide file tree
Showing 155 changed files with 98 additions and 12,048 deletions.
6 changes: 5 additions & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
## 2.0.0

Changes:


## 1.0.0 (2015-12-22)

Changes:

- Bumped version to 1.0.0 as it has become quite feature full and it has a slight breakage factor.
- Bumped version to 1.0.0 as it has become quite feature full and it has a slight breakage factor.
- Stripe Connect standalone account support. All modules were refactored to allow api key to flow thru
- Refactored all subscriptions/invoices to their own modules. Expect a few rough edges there.
- Improved the README
28 changes: 23 additions & 5 deletions LICENSE
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,27 @@ Copyright (c) 2015-2016, Rob Conery
2016, Code Corps PBC and Strumber
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the names Code Corps nor Strumber, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.

Neither the names Code Corps nor Strumber, nor the names of its contributors may
be used to endorse or promote products derived from this software without
specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
153 changes: 61 additions & 92 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,28 @@
# Stripe for Elixir [![Build Status](https://travis-ci.org/code-corps/stripity-stripe.svg?branch=master)](https://travis-ci.org/code-corps/stripity-stripe) [![Hex.pm](https://img.shields.io/hexpm/v/stripity_stripe.svg?maxAge=2592000)](https://hex.pm/packages/stripity_stripe) [![Hex Docs](https://img.shields.io/badge/hex-docs-9768d1.svg)](https://hexdocs.pm/stripity_stripe) [![Hex.pm](https://img.shields.io/hexpm/dt/stripity_stripe.svg?maxAge=2592000)](https://hex.pm/packages/stripity_stripe) [![Inline docs](http://inch-ci.org/github/code-corps/stripity-stripe.svg)](http://inch-ci.org/github/code-corps/stripity-stripe) [![Coverage Status](https://coveralls.io/repos/github/code-corps/stripity-stripe/badge.svg?branch=master)](https://coveralls.io/github/code-corps/stripity-stripe?branch=master)
# Stripe for Elixir [![Build Status](https://travis-ci.org/code-corps/stripity-stripe.svg?branch=2.0)](https://travis-ci.org/code-corps/stripity-stripe) [![Hex.pm](https://img.shields.io/hexpm/v/stripity_stripe.svg?maxAge=2592000)](https://hex.pm/packages/stripity_stripe) [![Hex Docs](https://img.shields.io/badge/hex-docs-9768d1.svg)](https://hexdocs.pm/stripity_stripe) [![Hex.pm](https://img.shields.io/hexpm/dt/stripity_stripe.svg?maxAge=2592000)](https://hex.pm/packages/stripity_stripe) [![Inline docs](http://inch-ci.org/github/code-corps/stripity-stripe.svg)](http://inch-ci.org/github/code-corps/stripity-stripe) [![Coverage Status](https://coveralls.io/repos/github/code-corps/stripity-stripe/badge.svg?branch=master)](https://coveralls.io/github/code-corps/stripity-stripe?branch=master)

An Elixir library for working with [Stripe](https://stripe.com/).

Features:

* manage accounts (your own, standalone/managed via connect) [Stripe.Accounts](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe/accounts.ex)
* manage customers [Stripe.Customers](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe/customers.ex)
* manage Subscriptions [Stripe.Subscriptions](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe/subscriptions.ex)
* manage plans [Stripe.Plans](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe/plans.ex)
* manage Invoices [Stripe.Invoices](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe/invoices.ex)
* manage Invoice Items [Stripe.InvoiceItems](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe/invoice_items.ex)
* manage tokens for credit card and bank account [Stripe.Tokens](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe/tokens.ex)
* list and retrieve stripe events (paged, max 100 per page, up to 30 days kept on stripe for retrieve) [Stripe.Events](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe/events.ex)
* manage/capture charges with or without an existing Customer [Stripe.Charges](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe/charges.ex)
* manage and validate coupons [Stripe.Coupons](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe/coupons.ex)
* facilitate using the Connect API (for standalone/managed accounts) [Stripe Connect](https://stripe.com/docs/connect) by allowing you to supply your own key. The oauth callback processor (not endpoint) is supplied by this library as well as a connect button url generator. See below for [Instructions](#connect). [Stripe Connect API reference](https://stripe.com/docs/connect/reference)
* all functions are available with a parameter that allow a stripe api key to be passed in and be used for the underlying request. This api key would be the one obtained by the oauth connect authorize workflow.

Why another Stripe Library? Currently there are a number of them in the Elixir world that are, well just not "done" yet. I started to fork/help but soon it became clear to me that what I wanted was:

* an existing/better test story
* an API that didn't just mimic a REST interaction
* a library that was up to date with Elixir > 1.0 and would, you know, actually *compile*.
* function calls that returned a standard `{:ok, result}` or `{:error, message}` response

As I began digging things up with these other libraries it became rather apparent that I was not only tweaking the API, but also ripping out a lot of the existing code... and that usually means I should probably do my own thing. So I did.

### Update:

As of October 18th, Rob has graciously handed over the reins to the teams at [Code Corps](https://www.codecorps.org/) and [Strumber](https://strumber.com/). Over the next several weeks, we will be working to produce and release a 2.0 version of Stripity Stripe which fully addresses the concerns Rob mentioned above and updates the high level api to work with all of the Stripe API Endpoints.

**If you are starting a new implementation, particularly one using Stripe Connect, we recommend relying on [the low level API defined here](https://github.com/code-corps/stripity-stripe/blob/master/lib/stripe.ex#L88).**

Stay tuned...
* facilitate using the Connect API (for standalone/managed accounts)
[Stripe Connect](https://stripe.com/docs/connect) by allowing you to supply your
own key. The oauth callback processor (not endpoint) is supplied by this library
as well as a connect button url generator. See below for
[Instructions](#connect).
[Stripe Connect API reference](https://stripe.com/docs/connect/reference)
* TBD

## Stripe API

I've tested this library against Stripe API v1 and above. [The docs are up at Hex](http://hexdocs.pm/stripity_stripe/)

Works with API version 2015-10-16
This library is built on Stripe API version 2016-07-06.
[The docs are up at Hex](http://hexdocs.pm/stripity_stripe/)

## Usage

Install the dependency:

```ex
{:stripity_stripe, "~> 1.4.0"}
{:stripity_stripe, "~> 2.0.0"}
```

Next, add to your applications:
Expand All @@ -58,7 +35,8 @@ end

## Configuration

To make API calls, it is necessary to configure your Stripe secret key (and optional platform client id if you are using Stripe Connect):
To make API calls, it is necessary to configure your Stripe secret key (and
optional platform client id if you are using Stripe Connect):

```ex
use Mix.Config
Expand All @@ -67,62 +45,74 @@ config :stripity_stripe, secret_key: "YOUR SECRET KEY"
config :stripity_stripe, platform_client_id: "YOUR CONNECT PLATFORM CLIENT ID"
```

To customize the underlying HTTPoison library, you may optionally add an `:httpoison_options` key to the stripity_stripe configuration. For a full list of configuration options, please refer to the [HTTPoison documentation](https://github.com/edgurgel/httpoison).
To customize the underlying HTTPoison library, you may optionally add an
`:httpoison_options` key to the stripity_stripe configuration. For a full list
of configuration options, please refer to the
[HTTPoison documentation](https://github.com/edgurgel/httpoison).

```ex
config :stripity_stripe, httpoison_options: [timeout: 10000, recv_timeout: 10000, proxy: {"proxy.mydomain.com", 8080}]
config :stripity_stripe, httpoison_options: [
timeout: 10000,
recv_timeout: 10000,
proxy: {"proxy.mydomain.com", 8080}
]
```

## Testing
If you start contributing and you want to run mix test, first you need to export STRIPE_SECRET_KEY environment variable in the same shell as the one you will be running mix test in. All tests have the @tag disabled: false and the test runner is configured to ignore disabled: true. This helps to turn tests on/off when working in them. Most of the tests depends on the order of execution (test random seed = 0) to minimize runtime. I've tried having each tests isolated but this made it take ~10 times longer.

All tests have the @tag disabled: false and the test runner is configured to
ignore disabled: true. This helps to turn tests on/off when working in them.

```
export STRIPE_SECRET_KEY="yourkey"
mix test
```

## The API

I've tried to make the API somewhat comprehensive and intuitive. If you'd like to see things in detail be sure to have a look at the tests - they show (generally) the way the API goes together.

In general, if Stripe requires some information for a given API call, you'll find that as part of the arity of the given function. For instance if you want to delete a Customer, you'll find that you *must* pass the id along:
The API attempts to model the official Ruby library as closely as makes sense
while adhering to Elixir syntax and principles.

```ex
{:ok, result} = Stripe.Customers.delete "some_id"
{:ok, object} = Stripe.Customer.delete "cus_8Pq6iJMrd4M0AD"
```

For optional arguments, you can send in a Keyword list that will get translated to parameters. So if you want to update a Subscription, for instance, you must send in the `customer_id` and `subscription_id` with the list of changes:
For optional arguments, you can send in a Keyword list that will get translated
to parameters. So if you want to update a Subscription, for instance, you must
send in the `customer_id` and `subscription_id` with the list of changes:

```ex
# Change customer to the Premium subscription
{:ok, result} = Stripe.Customers.change_subscription "customer_id", "sub_id", [plan: "premium"]
{:ok, customer} = Stripe.Customer.update %{email: "dan@strumber.com"}
```

Metadata (metadata:) key is supported on most object type and allow the storage of extra information on the stripe platform. See [test](https://github.com/code-corps/stripity-stripe/blob/master/test/stripe/customer_test.exs) for an example.
Metadata (metadata: %{}) key is supported on most object type and allow the
storage of extra information on the stripe platform.

API calls will always return either `{:ok, _record}` or `{:error, error}`.
Errors will be maps directly mirroring
[the Stripe API Error response object](https://stripe.com/docs/api/ruby#errors).

That's the rule of thumb with this library. If there are any errors with your call, they will bubble up to you in the `{:error, message}` match.
Pagination is available on list calls and follows
[the Stripe API Pagination docs](https://stripe.com/docs/api/ruby#pagination).

```ex
# Example of paging through events
{:ok, events} = Stripe.Events.list(key, "", 100) # second arg is a marker for paging

case events[:has_more] do
true ->
# retrieve marker
last = List.last( events[:data] )
case Stripe.Events.list key, last["id"], 100 do
{:ok, events} -> events[:data]
# ...
end
false -> events[:data]
end
{:ok, events} = Stripe.Customer.list(%{limit: 10})
```

# Connect

Stripe Connect allows you to provide your customers with an easy onboarding to their own Stripe account. This is useful when you run an e-commerce as a service platform. Each merchant can transact using their own account using your platform. Then your platform uses Stripe's API with their own API key obtained in the onboarding process.
Stripe Connect allows you to provide your customers with an easy onboarding to
their own Stripe account. This is useful when you run an e-commerce as a service
platform. Each merchant can transact using their own account using your
platform. Then your platform uses Stripe's API with their own API key obtained
in the onboarding process.

First, you need to register your platform on Stripe Connect to obtain a `client_id`. In your account settings, there's a "Connect" tab, select it. Then fill the information to activate your connect platform settings. The select he `client_id` (notice there's one for dev and one for prod), stash this `client_id` in the config file under
First, you need to register your platform on Stripe Connect to obtain a
`client_id`. In your account settings, there's a "Connect" tab, select it. Then
fill the information to activate your connect platform settings. Then select the
`client_id` (notice there's one for dev and one for prod), stash this
`client_id` in the config file under

```ex
config :stripity_stripe, platform_client_id: "ac_???"
Expand All @@ -137,56 +127,35 @@ Here's an example of a button to start the workflow:
You can generate this URL using:

```ex
url = Stripe.Connect.generate_button_url csrf_token
url = Stripe.Connect.generate_button_url(%{state: "csrf_token"})
```

When the user gets back to your platform, the following url (`redirect_uri` form item on your "Connect" settings) will be used:
When the user gets back to your platform, the following url (`redirect_uri` form
item on your "Connect" settings) will be used:

```
//yoursvr/your_endpoint?scope=read_write&code=AUTHORIZATION_CODE
https://yoursvr/your_endpoint?scope=read_write&code=AUTHORIZATION_CODE
```

or

```
//yoursvr/your_endpoint?error=access_denied&error_description=The%20user%20denied%20your%20request
https://yoursvr/your_endpoint?error=access_denied&error_description=The%20user%20denied%20your%20request
```

Using the code request parameter, you make the following call:

```ex
{:ok, resp} -> Stripe.Connect.oauth_token_callback code
{:ok, resp} -> Stripe.Connect.oauth_token_callback(code)
resp[:access_token]
```

`resp` will look like this:
```ex
%{
token_type: "bearer",
stripe_publishable_key: PUBLISHABLE_KEY,
scope: "read_write",
livemode: false,
stripe_user_id: USER_ID,
refresh_token: REFRESH_TOKEN,
access_token: ACCESS_TOKEN
}
```

You can then pass the `access_token` to the other API modules to act on their behalf.

See a [demo](https://github.com/nicrioux/stripity-connect-phoenix) using the Phoenix framework with the bare minimum to get this working.

## Testing Connect

The tests are currently manual as they require a unique OAuth authorization code per test. You need to obtain this code manually using the stripe connect workflow (that your user would go through using the above url).

First, log in your account. Then go to the following url: https://dashboard.stripe.com/account/applications/settings

Create a connect standalone account. Grab your development `client_id`. Put it in your config file. Enter a redirect url to your endpoint. Capture the "code" request parameter. Pass it to `Stripe.Connect.oauth_token_callback` or `Stripe.Connect.get_token`.

## Contributing

Feedback, feature requests, and fixes are welcomed and encouraged. Please make appropriate use of [Issues](https://github.com/code-corps/stripity-stripe/issues) and [Pull Requests](https://github.com/code-corps/stripity-stripe/pulls). All code should have accompanying tests.
Feedback, feature requests, and fixes are welcomed and encouraged. Please make
appropriate use of [Issues](https://github.com/code-corps/stripity-stripe/issues)
and [Pull Requests](https://github.com/code-corps/stripity-stripe/pulls). All
code should have accompanying tests.

## License

Expand Down
37 changes: 0 additions & 37 deletions fixture/vcr_cassettes/account_test/delete.json
View file

This file was deleted.

Loading

0 comments on commit e55855c

Please sign in to comment.