Updated READMEs and logging output.

All log messages are written in the same format to both the console and
a file.  Errors are written to a separate file.

Author: TheF1rstPancake

README.md

@@ -2,31 +2,29 @@
 Kvasir (Vas-eer) is a support dashboard meant for WePay partners to be able to provide their end-users with basic support.  
 It will perform:
 
-    - account lookups
+    - Account Lookups
         - Get the status of a merchant's account
-
         - Get a merchant's withdrawal info including their bank info and when the next withdrawal will take place
-
-    - user lookups
-
-    - resending user confirmation
-
-    - refunding checkouts
-
+    - Merchant (User) Lookups
+    - Resending merchant confirmation
+    - Refunding Checkouts
         - Both full and partial refunds are possible
+    - Payment Method Lookups
+        - Get the information that a given *payment_method_id* represents
+
+## Full Documentation
+This README only contains a brief outline of what Kvasir is and what it is capable of.  To view the whole documentation, head to http://jalepeno112.github.io/Kvasir/index.html
 
 ## Functionality
-All of the functionality has been tested, but there may be some cases that I missed.  The WePay API isn't always predicatable, so if you run into an error, be sure to report it as an issue so that I can investigate furhter.  Giving me the original call information (without your client_secret or any access tokens) is extremely helpful so that I can try and reproduce the error.
+All of the functionality has been tested, but there may be some cases that we missed.  The WePay API isn't always predictable, so if you run into an error, be sure to report it as an issue so that we can investigate further.  Giving me the original call information (without your client_secret or any access tokens as those are sensitive pieces of information you shouldn't share with anyone) is extremely helpful so that I can try and reproduce the error.
 
 To see how the framework behaves in action go to: https://nameless-hollows-55554.herokuapp.com/
 
-The test cases are found in the "test" directory.
-
-## More Info
-To see more info and the full documentation on Kvasir's specs and what's required to use Kvasir, checkout the full documentation: https://wedemoapp.gitlab.io/kvasir/index.html
+## Test Cases
+The test cases are found in the "test" directory.  They test the backend functionality and Kvasir's ability to interact with your middleware.
 
 ## Why Kvasir?
-`Kvasir is a Norse god of wisdom <http://norse-mythology.org/kvasir/>`_.  In fact he's considered the wisest of all of them.  He was killed by dwarves and his blood became the Mead of Poetry which was used to inspire poets and scholars.  Basically, he's the personification of alcohol.  Given that we were drinking when we came up with the idea for Kvasir, it only made sense.
+Kvasir is a Norse god of wisdom <http://norse-mythology.org/kvasir/>.  He was killed by dwarves and his blood became the Mead of Poetry which was used to inspire poets and scholars.  Basically, he's the personification of alcohol.  Given that we were drinking when we came up with the idea for Kvasir, it only made sense.
 
 ## Who is this mystical "we" all over the documentation?
 We are many, but we are one.

docs/architecture.rst

@@ -2,7 +2,7 @@
 
 Kvasir's Architecture
 =========================
-This page details Kvasir's architecture.  It explains in detail why each architecture decision was made.
+This page details Kvasir's architecture.  We do this so that you have a better idea for why certain decisions are made in the :ref:`back-end <kvasirbackend>` and :ref:`front-end <kvasirfrontend>`.
 
 A Brief History
 -------------------
@@ -15,14 +15,14 @@ On the security side, many of the WePay API calls that we need to make required
 
 While exposing access tokens to the front-end was considered a deal breaker, being able to get tokens to the front-end in the first place was also a challenge.  No two database configurations are the same, and we wanted this solution to be available to any company that currently integrates with WePay.  Normally, data makes up the fundamental building block of a web-application, but here we were presented with the unusual problem of having absolutely no control over the underlying database.  Not only that, but many databases would likely not be optimized for use with Kvasir, so we could make no assumptions about how certain pieces of data were connected or about the presence of data.
 
-A pure SPA with no attached back-end fell of the table pretty quickly, but we wanted to try and hold on to many of the benefits that come with a SPA such as:
+A SPA with no attached back-end fell of the table pretty quickly, but we wanted to try and hold on to many of the benefits that come with a SPA such as:
     1) **Being back-end agnostic**.  Someone could simply take our front-end, and redesign the lower pieces and it should work just as well (if not better)
     2) **Easy setup and deployment**.  One of the nice parts of an SPA is that all of the logic and external calls are contained in the app running in a user's browser.  It only requires a small static server to push the necessary files forward, but the burden of the work falls on the user's machine.
 
 
 Architecture
 -----------------
-With all of these considerations in mind, we decided to stick with a SPA but provide it a sturdy back-end server for managing external API calls and database connections.
+With all of these considerations in mind, we decided to stick with a SPA design but provide it a sturdy back-end server for managing external API calls and database connections.
 
 .. figure:: images/KvasirInitialArchitecture_Prototype.*
     :align: center
@@ -43,7 +43,7 @@ In order to achieve this, we came up with this idea of a :ref:`"middleware compo
 This middleware can be provided in any language that the developer chooses, using any structure that they want.  As long as it can receive and send back information in the way that Kvasir expects, the rest is up to the developer.  The information that Kvasir requests may be spread out across three or four tables for one developer, but be completed contained in a single table for another.  This middleware piece allows Kvasir to be apathetic towards a developer's underlying database.  This provides us with the necessary flexibility to be able to provide this as a solution to all platforms currently using WePay, not just a handful.
 
 
-Integration Environment with Kvasir
+How to Host Kvasir
 ----------------------------------------
 The entire architectural model assumes that Kvasir and your middleware are running on your company's internal network.  Kvasir does not come with any sort of authentication and there are *no plans for it*.  Similarly to database configurations, there are a plethora of authentication systems out there that we cannot provide mechanisms to interact with all of them.
 

docs/frontend.rst

@@ -25,7 +25,7 @@ React and Redux apps are comprised of 3 parts:
 Holding onto the idea that our application is really taking a user on a walk through their internal database, we have a set of "objects" or "models", each of which have their own set of actions, reducers and components.
 
 These objects are:
-   - :ref:`User <user_object>`
+    - :ref:`User <user_object>`
         * represents a given *merchant*.  
         * A merchant can have multiple accounts.
 
@@ -55,12 +55,14 @@ If you look at these objects, you might recognize that all of these *except for
 
 The *components* are responsible for handling user actions and then dispatching the associated Redux actions.  They are also responsible for subscribing to all of the necessary state information and formatting that data.  While all actions are globally published, not every component relies on all of that info (and they shouldn't).
 
-For example, when an account is clicked in the account component, the account component registers that the click happened, manipulates the table, and then dispatches the *searchedAccounts*, *fetchWithdrawalsIfNeeded* and *fetchCheckoutsIfNeeded* actions.  Some of these actions will directly impact the action component causing it to re-render with new info, while others will impact other components forcing them to re-render with the new information, but the *User* objects is not impacted at all.  Actions to accounts do not affect the User who owns them.
+For example, when an account is clicked in the account component, the account component registers that the click happened, manipulates the table, and then dispatches the *searchedAccounts*, *fetchWithdrawalsIfNeeded* and *fetchCheckoutsIfNeeded* actions.  Some of these actions will directly impact the action component causing it to re-render with new info, while others will impact other components forcing them to re-render with new info as well.  On the other hand, the *User* objects is not impacted at all.  Actions to accounts do not affect the User who owns them so we do not see the user component re-render.
 
 General Object Implementation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 All of the objects are different in the sense that they require different search requirements (user_id, account_id, etc.); however, they are all implemented in very similar ways.  
 
+Actions
+^^^^^^^^^^
 All of the objects require a handful of actions:
     1) Search
         - Notify all components the object is being *searched* for and what exactly we are searching for
@@ -82,7 +84,7 @@ But not all of these actions are directly accessible.  For example, request and
 In general, these are the public functions that each object has for dispatching actions:
     1) .. function:: search(id)
 
-        Will cause the associated reducer to update its state with the information the user passed in order to search the object.
+        Will cause the associated reducer to update its state with the information the user passed in order to search the object. This is necessary so that we can verify that the info coming back is actually the info we requested.
 
         :param id:  some unique id of the object that we just looked up.  For example, for user's this is an email address; accounts use an account_id
 
@@ -94,6 +96,8 @@ In general, these are the public functions that each object has for dispatching
 
         :param id:  some unique id of the object that we just looked up.  For example, for user's this is an email address; accounts use an account_id
 
+Reducers
+^^^^^^^^^^^^
 The reducers that take these actions are also very similar.  
 Each reducer is actually composed of two smaller functions - a *searched* function and a *base* function. 
 We do this because of the asynchronous nature of Redux actions mixed with the POST requests to our back-end.  If someone searches a user, but then realizes they searched the wrong email and changes the search parameter, we need a way to handle that.
@@ -128,7 +132,7 @@ Going back to the earlier example, if someone were to search a user with one ema
 .. _user_object:
 
 User Object
-~~~~~~~~~~~~
+------------
 The user objects represents a WePay merchant accessible through the :wepay:`user` endpoint.
 This is the primary building block for all other information that we gather.
 
@@ -149,7 +153,7 @@ The state of the user is important because if the user is not in the *registered
 .. _account_object:
 
 Account Object
-~~~~~~~~~~~~~~~~
+----------------
 As soon we have a user's access token, we can also get a list of all of their merchant accounts tied to the app_id that the access token is associated with via the :wepay:`account find` call.
 
 A user could have multiple accounts, so each account is displayed as a row in a larger table. Clicking on a row of the table will cause the row to become highlighted, and will dispatch actions to fetch more information about that specific account.  This information includes withdrawals, reserves, and checkouts.
@@ -171,7 +175,7 @@ The account table itself includes:
 .. _withdrawal_object:
 
 Withdrawal Object
-~~~~~~~~~~~~~~~~~~~~~
+------------------
 The withdrawal object represents information gained from the :wepay:`withdrawal` endpoint. 
 This includes information about where a merchant's money is being withdrawn too, when it's being withdrawn, and how much is being withdrawn.
 
@@ -182,7 +186,7 @@ These tables will render the 50 most recent withdrawals/reserves for a merchant.
 .. _checkouts_object:
 
 Checkouts Object
-~~~~~~~~~~~~~~~~~~~
+------------------
 The checkout object is one of the more intensive objects.  Since it is the heart of many operations that a platform performs, there are also several actions tied to any given checkout.
 
 The checkout component renders a table of information gathered from a :wepay:`checkout find` call which includes:
@@ -214,7 +218,7 @@ The checkout component is also currently responsible for rendering the informati
 .. _credit_card_object:
 
 Credit Card Object
-~~~~~~~~~~~~~~~~~~~
+--------------------
 The credit_card object represents information gathered by a :wepay:`credit_card` call.  One of the benefits of WePay is the ability to tokenize payment information and simply store a token instead of all the payer's info.  Storing all payer info requires a higher level of PCI compliance than just the token.
 
 However, a platform may want to lookup information associated with a tokenized card at any point in time.  The *Payment Method ID* column in the checkout object contains the tokenized id.  Clicking on one of them (they are all hyperlinks) will dispatch actions to fetch more information about the card and render it in a table.
@@ -233,7 +237,7 @@ This table includes:
 .. _payer_object:
 
 Payer Object
-~~~~~~~~~~~~~~~~
+-------------------
 As mentioned earlier the Payer object is the only one that doesn't tie directly back to a WePay endpoint.  This is because the WePay API does not provide any way to search by a payer's information.  All you can search by is a tokenized credit card ID.
 
 However, if a payer comes to a platform's customer support and requests a refund, they likely don't know the token associated with their purchase.  Storing payer information falls squarely onto the platform.

docs/index.rst

@@ -32,8 +32,15 @@ These actions include:
     - Withdrawal Lookups
         * Gather information about where a merchant's funds have been withdrawn to and when the next withdrawal should take place
         * This also includes being able to get reserve details for accounts that have money in reserve
-    - Credit Card Token Lookup
+    - Payment Method Lookups
         * Given a tokenized credit card, Kvasir can gather the original information used to create the token
+        * Given a preapproval id, Kvasir can gather the original information used to create the token and provide a link where the conditions of the preapproval can be updated
+
+.. figure:: images/KvasirLiveSnapshot.png
+  :align: center
+  :scale: 65%
+
+  A live snapshot of Kvasir in action
 
 Tech Stack
 -----------

docs/sphinxext/wepay_docs.py

@@ -6,7 +6,7 @@
 
 
 def setup(app):
-    app.add_config_value("wepay_docs_home", "https://stage.wepay.com/developer/reference/", 'html')
+    app.add_config_value("wepay_docs_home", "https://developer.wepay.com/api-calls/", 'html')
 
     app.add_role("wepay", wepay_docs_role)
 
@@ -34,7 +34,8 @@ def make_wepay_link(app, rawtext, endpoint, function, options):
 
     # build external url
     # if no function is given, then it is the main endpoint, which is accessed by #lookup on the page
-    ref = base + endpoint + "#" + function if function else base + endpoint + "#lookup"
+    ref = "{0}{1}#{2}"
+    ref = ref.format(base,endpoint,function) if function else ref.format(base,endpoint,"lookup")
 
     # build the text that we will display instead of :wepay:`endpoint function`
 

logs/README.rst

@@ -2,3 +2,5 @@ Logging Directory
 ------------------
 
 This directory holds all of the log files generated by the application.
+
+Logs are saved in JSON format.  Express.js packages the requests and responses objects in a JSON format and writes them one per line.  So each line is a different request or response.  Looking at the status code lets you know what was and wasn't successful.

server.js

@@ -99,16 +99,31 @@ if (!app_config.http_override) {
     var credentials = {key: privateKey, cert: certificate};
 }
 
-// point the app to the static folder
-app.use('/static', express.static('static'));
 app.use(config.output.publicPath, express.static(config.output.path));
 
 
 var expressWinston = require("express-winston");
 var winston = require("winston");
+
+// create a logger for our other log inputs
+// we remove the default Console logger and add our own to allow for more fine-tuned formatting
+winston.add(winston.transports.File, {
+    level:"info",
+    filename:"logs/log.log",
+    timestamp: true,
+    json: true,
+    colorize: true
+});
+winston.remove(winston.transports.Console);
+winston.add(winston.transports.Console, {
+    colorize: true,
+    timstamp:true
+})
+
 // define our logger
-app.use(expressWinston.logger({
-    transports: [
+// the expressWinston.logger only logs the HTTP(s) requests and response
+// the expressWinston.errorLogger is at the bottom of the file.  It has be 
+var expressTransports = [
         new winston.transports.Console({
             colorize: true,
             timstamp:true,
@@ -120,13 +135,16 @@ app.use(expressWinston.logger({
             timestamp:true,
 
         })
-    ],
+]
+app.use(expressWinston.logger({
+    transports: expressTransports,
     meta: true, // optional: control whether you want to log the meta data about the request (default to true)
     expressFormat: true
 }));
 
-
 // use ejs for our template engine
+// point the app to the static folder
+app.use('/static', express.static('static'));
 app.set("view engine", "ejs");
 
 /**
@@ -496,6 +514,20 @@ app.post("/preapproval/cancel", csrfProtection, function(req, res){
 
 })
 
+// define the error logger.
+// it uses the same transports as the normal logger, and will write all errors to a special file for easier access
+var error_transport = new winston.transports.File({
+        filename: "logs/error.log",
+        level: "error",
+        json: true,
+        timestamp:true
+    });
+app.use(expressWinston.errorLogger({
+    transports: [error_transport],
+    meta: true, // optional: control whether you want to log the meta data about the request (default to true)
+    expressFormat: true
+}));
+
 
 /**
  * Start the application