Mongoose Subscriptions

Processor agnostic payment subscription backend. It provides some premitive mongoose models to model subscriptions, namely Customer and Coupon and, by using an adapter syncs the state in the database to the state in the payment subscription, transparently updating payment methods, subscriptions, trials and promotions.

It works both ways. You can make changes to your Customer and execute "saveProcessor", propogating it to the payment processor. Or you can execute "loadProcessor" and get the latest state in the db.

Installation

yarn add mongoose-subscriptions

You'll also need a specific processor driver. Currently only supported is braintree

yarn add mongoose-subscriptions-braintree

Usage

You can use the Customer model directly:

const ms = require('mongoose-subscriptions');
const customer = new ms.Customer({ ... });

You can also extend CustomerSchema with more fields and use that as your own model:

const ms = require('mongoose-subscriptions');
const UserSchema = ms.Schema.Customer.add({
    userAgent: String,
    photo: String,
    hashedPassword: String,
});
const User = mongoose.model('User', UserSchema);

Structure

   ┌────────────────────┐
   │Customer            │
   │--------            │
   │User Info           │
┌─▶│[Addresses]         │
│  │[Payment Methods]   │
│  │[Subscriptions]     │
│  │[Transactions]      │
│  └────────────────────┘
│      ┌──────────────────────┐
│      │Address               │
│      │-------               │
│      │ID                    │
├──────│Street                │◀─┐
│      │Country               │  │
│      │etc.                  │  │
│      └──────────────────────┘  │
│      ┌──────────────────────┐──┘
│      │Payment Method        │
│      │--------------        │
├──────│ID                    │◀─┐
│      │addressId             │  │
│      │processor token       │  │
│      └──────────────────────┘  │
│      ┌──────────────────────┐──┘
│      │Subscription          │
│      │------------          │
│      │ID                    │
├──────│paymentMethodId       │◀─┐
│      │plan (id, price, name)│  │
│      │billing dates         │  │
│      └──────────────────────┘  │
│      ┌──────────────────────┐  │
│      │Transaction           │  │
│      │-----------           │  │
│      │ID                    │  │
│      │plan                  │  │
└──────│price                 │──┘
       │subscriptionId        │
       │payment Info          │
       │dates                 │
       └──────────────────────┘

All the connections between objects are done with internal local ids, without using the ids from the payment processor. This way you can establish relationships between objects even before they are sent to the processor.

const customer = new Customer({
    name: "John DOe",
    email: "[e-mail]",
    subscriptions: [
        {
            paymentMethodId: "test-pay",
            plan: {
                price: 4.99,
                processorId: "basic",
                level: 1,
                billingFrequency: 1,
            },
        },
    ],
    paymentMethods: [
        {
            _id: "test-pay",
            billingAddressId: 'addr-1',
            nonce: "some-nonce",
        },
    ],
    defaultPaymentMethodId: "test-pay",
    addresses: [
        {
            _id: 'addr-1',
            phone: '1-3232-123-323',
            name: 'John Doe',
            country: 'United States',
            locality: 'Florida',
            streetAddress: 'Monti 1',
            postalCode: 'NX032',
        }
    ].
});

Braintree

To sync with braintree you'll need to use the mongoose-subscriptions-braintree package.

const braintree = require("braintree");
const Processor = require("mongoose-subscriptions-braintree");
 
// Provide an array of plan objects to be used by the processor
// processorId is the id of the plan in braintree,
// and level is the precedence of the plan, this goes in effect,
// whenever someone has more than one subscription active.
const plans = [{
    processorId: 'plan1',
    price: 9.35,
    billingFrequency: 1,
    level: 1,
}];
 
const gateway = braintree.connect({
    environment: braintree.Environment.Sandbox,
    merchantId: ...,
    publicKey: ...,
    privateKey: ...,
});
 
const processor = new Processor(gateway, plans);
 
const address = customer.addAddress({ ... });
const paymentMethod = customer.addPaymentMethodNonce(nonce, address);
 
customer.saveProcessor(processor).then(() => {
    console.log('Saved in braintree');
});

High Level Api

Customer methods

Methods that change the state of the object itself.

Method	Description
.cancelSubscriptions()	Set all active subscriptions to canceled
.addAddress(addressData)	Add an address and returns the newly added address object
.defaultPaymentMethod()	Get the default payment method object
.addPaymentMethodNonce(nonce, [address])	Add a new payment method based on a nonce, optionally providing an address to assign to the payment method. Will set it as the default payment method.
.setDefaultPaymentMethod(paymentMethod, [address])	Create or update the current default payment method, along with its billing data information. If the type of the payment method is different, a new payment method will be created. If there is no default payment method, will try to find an unused address to reuse, instead of creating a new one each time.
.addSubscription(plan, [paymentMethod], [activeDate])	Add a subscription for a given plan, optionally providing a paymentMethod to assign to it. Takes into account current subscriptions, if there are subs that are greater or equal level, will set up the firstBillingDate to start after the last sub. For lower level subs, will discount the new sub with the amount left from the existing subs. Optionally add a third argument "activeDate" that will be used as a "new Date()" calculations
.activeSubscriptions(activeDate)	Return all subscriptions that currently have active state
.validSubscriptions(activeDate)	Return all subs that are active based on firstBillingDate and paidThroughDate. Exclude all the subs that have not had an active status ever, and order by largest level first
.subscription(activeDate)	Return the first object from validSubscriptions
.resetProcessor()	Remove any unsaved data e.g. "inital" addresses / payment methods / subscriptions. This is useful when there was an error but that data was already saved to the database.

Methods that change the state in the processor (e.g. braintree). Take processor as a first argument.

Method	Description
.cancelProcessor(processor, subscriptionId)	perform a subscription cancel and load the result into the current customer
.refundProcessor(processor, transactionId, [amount])	perform a full refund on a given transaciton, or a partial refund if "amount" is passed.
.voidProcessor(processor, transactionId)	perform a void on a given transaciton
.loadProcessor(processor)	load all the data about the customer (subs, transactions, payment methods) from the processor
.saveProcessor(processor)	save the current state of the customer object in the processor, creating addresses, payment methods and subscriptions, potentially doing transactions.

Coupon methods

Method	Description
coupon.isExpired(currentDate)	Check if the coupon has expireAt field set and its in the future
coupon.isPending(currentDate)	Check if the coupon has startAt field set and its in the past
coupon.isUseLimitReached()	Check if the usedCountMax is set and is larger or equal to usedCount
Coupon.validateState(coupon, currentDate)	Check if all the coupon validation checks pass, and returns an error object if any issue is found
Coupon.findOneAndValidate(query)	Perform a findOne and then validateState on the resulted coupon, making sure we get a valid Coupon object.

Subscription subdocument methods

Method	Description
.hasActiveStatus	A boolean virtual attribute that return true if this subscription has ever had an "Active" status
nextBillingDate	A virtual setter / getter for paidThroughDate
addDiscounts(callback)	The result of the callback must return an array of discounts. It will go through the new discount and the ones already present on the subscription and will leave only one discount with the largest amount

License

Copyright (c) 2016-2017 Enhancv Licensed under the MIT license.