ducky/subscriptions

     1.1 --- a/stripe.go	Sun Sep 27 21:20:09 2015 -0700
     1.2 +++ b/stripe.go	Sun Sep 27 21:20:46 2015 -0700
     1.3 @@ -12,22 +12,33 @@
     1.4  )
     1.5  
     1.6  const (
     1.7 +	// PendingPlan holds the name for the plan users that haven't chosen a plan are subscribed to.
     1.8  	PendingPlan = "pending"
     1.9  )
    1.10  
    1.11  var (
    1.12 -	ErrNilCustomer               = errors.New("nil customer passed")
    1.13 -	ErrNilCustomerSubs           = errors.New("customer with nil subscriptions list passed")
    1.14 +	// ErrNilCustomer is returned when a *Customer is expected, but nil is passed.
    1.15 +	ErrNilCustomer = errors.New("nil customer passed")
    1.16 +	// ErrNilCustomerSubs is returned when *Customer.Subs is expected to be a slice, but is nil.
    1.17 +	ErrNilCustomerSubs = errors.New("customer with nil subscriptions list passed")
    1.18 +	// ErrWrongNumberOfCustomerSubs is returned when a *Customer.Subs slice has more or fewer elements than expected.
    1.19  	ErrWrongNumberOfCustomerSubs = errors.New("customer with wrong number of subscriptions passed")
    1.20 -	ErrNilSubscription           = errors.New("nil subscription passed")
    1.21 +	// ErrNilSubscription is returned when a *Subscription is expected, but nil is passed.
    1.22 +	ErrNilSubscription = errors.New("nil subscription passed")
    1.23  )
    1.24  
    1.25 +// Stripe is a wrapper around the clients for Stripe that we're using. It's responsible for
    1.26 +// all the interaction with the Stripe API that we're doing. It is a level higher than the
    1.27 +// raw Stripe clients, and can be thought of as Stripe-from-the-perspective-of-subscriptions.
    1.28  type Stripe struct {
    1.29  	apiKey        string
    1.30  	customers     customer.Client
    1.31  	subscriptions sub.Client
    1.32  }
    1.33  
    1.34 +// NewStripe creates a new Stripe instance using the passed parameters. The stripe.Backend
    1.35 +// parameter can be used to create a stub instead of something that actually hits the Stripe
    1.36 +// API. See the github.com/stripe/stripe-go documentation for more information about Backends.
    1.37  func NewStripe(apiKey string, backend stripe.Backend) Stripe {
    1.38  	return Stripe{
    1.39  		apiKey: apiKey,
    1.40 @@ -42,6 +53,9 @@
    1.41  	}
    1.42  }
    1.43  
    1.44 +// CreateStripeCustomer sets up a customer using the passed Stripe client, ensuring it follows all
    1.45 +// the conventions that subscriptions expects (the description being set properly, the UserID meta,
    1.46 +// etc.) Creating a customer automatically creates a subscription for that customer.
    1.47  func CreateStripeCustomer(plan, email string, userID uuid.ID, s Stripe) (*stripe.Customer, error) {
    1.48  	customerParams := &stripe.CustomerParams{
    1.49  		Desc:  "Customer for user " + userID.String(),
    1.50 @@ -56,6 +70,8 @@
    1.51  	return c, nil
    1.52  }
    1.53  
    1.54 +// UpdateStripeSubscription modifies a subscription in Stripe, updating the plan and/or token.
    1.55 +// A nil plan or token indicates no change to the parameter.
    1.56  func UpdateStripeSubscription(customerID string, plan, token *string, s Stripe) (*stripe.Sub, error) {
    1.57  	params := &stripe.SubParams{}
    1.58  	if plan != nil {
    1.59 @@ -110,6 +126,8 @@
    1.60  	return subscription, nil
    1.61  }
    1.62  
    1.63 +// StripeSubscriptionChange takes a Subscription and a stripe.Sub, and returns a SubscriptionChange
    1.64 +// that will change only the properties necessary to make the Subscription match the stripe.Sub.
    1.65  func StripeSubscriptionChange(orig Subscription, subscription stripe.Sub) SubscriptionChange {
    1.66  	var change SubscriptionChange
    1.67  	if subscription.ID != orig.StripeSubscription {