Add endpoint to apply coupon

Author: ericingram

README.md

@@ -3,7 +3,7 @@
 A standalone API for JS and other clients to use with Schema. Extend basic endpoints with your own custom functionality, for example, validating user input special or scoping product queries for client usage.
 
 ```
-Schema.io <===> NodeJS API (This Package) <===> Your App (React/Angular/Ember/Rails/Etc)
+Schema.io <==> NodeJS API (This Package) <==> Your App (React/Angular/Ember/Rails/Etc)
 ```
 
 ## Getting Started
@@ -15,10 +15,10 @@ Schema.io <===> NodeJS API (This Package) <===> Your App (React/Angular/Ember/Ra
 
 ### Example .env file
 
-```
+```bash
 NODE_ENV=development
 PORT=3001
-FORCE_SSL=true // if you want to redirect all requests to https
+FORCE_SSL=true # redirect all requests to https
 SCHEMA_CLIENT_ID=my-client-id
 SCHEMA_CLIENT_KEY=my-client-key
 ```
@@ -41,43 +41,41 @@ It's not strictly required to pass the session header, but certain endpoints wil
 
 #### Get current account (session required)
 
-```
+```json
 GET /v1/account
 ```
 
 Sensitive fields may be removed from the response. See `api/v1/account.js` for details.
 
 #### Update current account
 
-```
+```json
 PUT /v1/account
 {
   "first_name": "Example",
   "last_name": "Customer",
-  "email": "[email protected]",
-  ...
+  "email": "[email protected]"
 }
 ```
 
 Only specific fields may be updated. See `api/v1/account.js` for details.
 
 #### Create account for the current user
 
-```
+```json
 POST /v1/account
 {
   "first_name": "Example",
   "last_name": "Customer",
-  "email": "[email protected]",
-  ...
+  "email": "[email protected]"
 }
 ```
 
 Only specific fields may be created. See `api/v1/account.js` for details.
 
 #### Login to account
 
-```
+```json
 POST /v1/account/login
 {
   "email": "[email protected]",
@@ -89,15 +87,15 @@ If email and password are correct, an account record will be returned. Otherwise
 
 #### Logout of current account
 
-```
+```json
 POST /v1/account/logout
 ```
 
 This will remove the previously logged in `account_id` from the session.
 
 #### Send password recovery email
 
-```
+```json
 POST /v1/account/recover
 {
   "email": "[email protected]",
@@ -109,7 +107,7 @@ This will send an email to the account if one found, that contains the `reset_ur
 
 #### Reset password from recovery email
 
-```
+```json
 POST /v1/account/recover
 {
   "reset_key": "iud287ebuf9uwf92fdi2uhef872h",
@@ -123,15 +121,15 @@ This will reset an account's password if the `reset_key` is found. If successful
 
 #### Get current cart details (session required)
 
-```
+```json
 GET /v1/cart
 ```
 
 Sensitive fields may be removed from the response. See `api/v1/cart.js` for details.
 
 #### Update current cart details
 
-```
+```json
 PUT /v1/cart
 {
   "shipping": {
@@ -177,15 +175,15 @@ If the cart does not exist for the current session, it will be automatically cre
 
 #### Create cart for the current user
 
-```
+```json
 POST /v1/cart
 ```
 
 This will create a cart for the current session, if one does not already exist. Note that it's not usually necessary to make this request, since other requests like `/v1/cart/add-item` will do the same automatically on demand.
 
 #### Add item to cart
 
-```
+```json
 POST /v1/cart/add-item
 {
   "product_id": "...",
@@ -205,7 +203,7 @@ If the same product and options already exist in the cart, then its quantity wil
 
 #### Remove item from cart
 
-```
+```json
 POST /v1/cart/remove-item
 {
   "item_id": "..."
@@ -214,9 +212,22 @@ POST /v1/cart/remove-item
 
 This will remove an item from the cart matching `item_id`. You can get the item ID value from any of the previous calls to the cart endpoint.
 
-#### Get shipping prices
+#### Apply a coupon
 
+```json
+POST /v1/cart/apply-coupon
+{
+  "code": "SHIPFREE"
+}
 ```
+
+This will apply a valid coupon code to the cart and affect all relevant prices. If the coupon code is not found or is not valid, the server will respond with status `400` and an error message.
+
+To remove an applied coupon, make the same request with `"code": null`.
+
+#### Get shipping prices
+
+```json
 GET /v1/cart/shipment-rating
 ```
 
@@ -226,7 +237,7 @@ The typical flow is to update the cart with shipping information first, then mak
 
 ### Convert cart to order
 
-```
+```json
 POST /v1/cart/checkout
 ```
 
@@ -238,21 +249,21 @@ If successful, an order record will be returned. Otherwise an error.
 
 #### Get category by slug or ID
 
-```
+```json
 GET /v1/categories/:slug
 ```
 
 Sensitive fields may be removed from the response. See `api/v1/categories.js` for details.
 
 #### Get sub-categories by slug or ID
 
-```
+```json
 GET /v1/categories/:slug/children
 ```
 
 #### Get products in a category
 
-```
+```json
 GET /v1/categories/:slug/products
 ```
 
@@ -264,15 +275,15 @@ Note: If you want to get products in a single category only and ignore sub-categ
 
 #### Get a product
 
-```
+```json
 GET /v1/products/:id
 ```
 
 Sensitive fields may be removed from the response. See `api/v1/products.js` for details.
 
 #### Get products in a category
 
-```
+```json
 GET /v1/products?category=:slug
 ```
 
@@ -284,7 +295,7 @@ Note: If you want to get products including all sub-categories, then see `/v1/ca
 
 #### Subscribe contact to email list(s)
 
-```
+```json
 POST /v1/contacts/subscribe
 {
   "first_name": "Example",
@@ -298,7 +309,7 @@ All fields are optional except `email`. You may use `email_optin_lists` for trac
 
 #### Unsubscribe contact from email list(s)
 
-```
+```json
 POST /v1/contacts/unsubscribe
 {
   "email": "[email protected]",
@@ -313,15 +324,15 @@ This will flip the `email_optin` field to false on the contact record. If `email
 
 #### Get a page
 
-```
+```json
 GET /v1/pages/:id
 ```
 
 Pages are used to store content such as About Us, Privacy Policy, etcetera.
 
 #### Get page articles
 
-```
+```json
 GET /v1/pages/:id/articles
 ```
 
@@ -330,23 +341,23 @@ Articles are useful for different things depending on the page itself. For examp
 
 #### Get a page article
 
-```
+```json
 GET /v1/pages/:id/articles/:article_id
 ```
 
 ## /v1/sessions
 
 #### Get current session details
 
-```
+```json
 GET /v1/session
 ```
 
 This will return current session data, including `account_id` and `cart_id`, along with any other arbitrary fields stored by your client.
 
 #### Update current session details
 
-```
+```json
 PUT /v1/session
 {
   "arbitrary_field": "example"
@@ -357,21 +368,19 @@ Update the current session with any fields that might be useful to your client.
 
 ## Testing
 
-To run all tests:
-
-```
+```bash
 npm test
 ```
 
-As a best practice, you should write new tests for new or modified endpoints.
+As a best practice, you should write tests for all new or modified endpoints.
 
 #### Schema client testing
 
 The test setup includes a Schema client that should be used to stub itself with expected requests and results. This allows you to easily test your own API code, without calling out to the Schema.io API itself. It makes test faster and more reliable.
 
 Here's an example using this test client:
 
-```
+```javascript
 const schema = Test.schemaClient();
 const api = Test.apiClient(schema);
 

api/router.js

@@ -45,8 +45,9 @@ module.exports = () => {
 
 // Graceful error handler
 function handleRouterError(err, res) {
+  const message =  err.toString().replace('Error: ', '');
   res.status(err.code || 500).json({
-    error: err.code ? err.toString() : 'Internal Server Error'
+    error: err.code ? message : 'Internal Server Error'
   });
   if (!err.code) {
     console.log(err);

api/v1/cart.js

@@ -13,6 +13,7 @@ cart.init = (env, router, schema) => {
   router.post('/cart', requireSession, cart.create.bind(this, schema));
   router.post('/cart/add-item', requireSession, cart.addItem.bind(this, schema));
   router.post('/cart/remove-item', requireSession, cart.removeItem.bind(this, schema));
+  router.post('/cart/apply-coupon', requireSession, cart.applyCoupon.bind(this, schema));
   router.get('/cart/shipment-rating', requireSession, cart.shipmentRating.bind(this, schema));
   router.post('/cart/checkout', requireSession, cart.checkout.bind(this, schema));
 };
@@ -100,12 +101,26 @@ cart.removeItem = (schema, req) => {
   }
   return schema.delete('/carts/{cart_id}/items/{item_id}', {
     cart_id: req.session.cart_id,
-    item_id: req.body.item_id
+    item_id: req.body.item_id,
   }).then(() => {
     return cart.get(schema, req);
   });
 };
 
+// Apply a coupon code
+cart.applyCoupon = (schema, req) => {
+  return schema.put('/carts/{cart_id}', {
+    cart_id: req.session.cart_id,
+    coupon_code: req.body.code || req.body.coupon_code || null,
+  }).then(result => {
+    if (result.errors && result.errors.coupon_code) {
+      throw util.error(400, 'Coupon code is not valid');
+    }
+    return cart.get(schema, req);
+  });
+};
+
+// Ensure shipping fields are sane
 cart.sanitizeShipping = (shipping) => {
   shipping = util.filterData(shipping, [
     'name',
@@ -122,6 +137,7 @@ cart.sanitizeShipping = (shipping) => {
   return shipping;
 },
 
+// Ensure billing fields are sane
 cart.sanitizeBilling = (billing) => {
   billing = util.filterData(billing, [
     'name',