Merge branch 'feat/datastore-orderdesk' of github.com:Foxy/foxy-node-netlify-functions into polish/datastores

Author: ndvo

.eslintrc.js

@@ -4,7 +4,10 @@ module.exports = {
     commonjs: true,
     es2021: true,
   },
-  extends: "@foxy.io",
+  extends: [
+    "@foxy.io",
+    "plugin:jsdoc/recommended"
+  ],
   parserOptions: {
     ecmaVersion: 12,
   },

.gitignore

@@ -1,6 +1,13 @@
 node_modules
 dist
 
+# Istanbul code coverage files and folders
+.nyc_output
+coverage
+
+# ctags files
+tags
+
 # Local Netlify folder
 .netlify
 
@@ -9,4 +16,17 @@ dist
 .env
 
 # VSCode and other editor-specific files
-tempCodeRunner*
+tempCodeRunner*
+
+.idea
+
+### Vim ###
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-v][a-z]
+[._]sw[a-p]
+Session.vim
+.netrwhist
+*~
+.vimrc
+.vimlocal

README.md

@@ -1,15 +1,66 @@
 # Netlify Serverless Functions for the Foxy.io API
 
-This repository allows for easily creating serverless functions to work with the Foxy.io API, deployed using Netlify. The goal is to make this as approachable as possible, so we're avoiding unnecessary
+This repository allows you to (more) easily create serverless functions to work with the Foxy.io API, deployed using Netlify. The goal is to make this as approachable as possible, so we try to have reasonable default behaviours, and Netlify is a great choice because of the one-click deployment. Once you deploy to Netlify, you can modify your own GitHub files to customize as needed.
 
 ## Functions
 
-The functions provided in this repository can be used independently, or as a reference for building your own functinos.
-Be sure to check the README for each function in the functions folder.
+The functions provided in this repository can be used independently, or as a reference for building your own functions. Be sure to check the README for each function in the functions folder.
 
-- [cart](src/functions/cart): Converts a cart between recurring and non-recurring.
-- [idevaffiliate-marketplace](src/functions/idevaffiliate-marketplace): 
-- [pre-payment-webhook-webflow](src/functions/pre-payment-webhook-webflow): Validates the price and/or availability of items against Webflow CMS collections before a payment is processed.
+- [cart](src/functions/cart): Converts a cart between recurring and non-recurring. Useful in an upsell flow.
+- [idevaffiliate-marketplace](src/functions/idevaffiliate-marketplace): A marketplace-style integration, using iDevAffiliate.
+- Datastore integrations: 
+    - [pre-payment-webhook-webflow](src/functions/pre-payment-webhook-webflow): Validates the price and/or availability of items against Webflow CMS collections before a payment is processed.
+    - [datastore-integration-orderdesk](src/functions/datastore-integration-orderdesk): Validates the cart against OrderDesk and updates the inventory upon successful transaction.
+
+### Data Store Integrations
+
+Data store integrations allow you to verify the cart against a third-party Data Store.
+
+Your customer workflow is basically unchanged.
+
+The image below shows the order flow, with the gray steps showing the functionality provided by these functions (invisible to the customer). Notice that upon cart submit the pre-payment validation is triggered. The webhook makes a request to this function, which then gets the inventory and price information from your data store (Webflow or OrderDesk), and checks if the cart is valid.
+
+![Data Store Integration workflow](https://github.com/Foxy/foxy-node-netlify-functions/blob/feat/datastore-orderdesk/images/datastore-integrations-workflow.png?raw=true)
+
+- You may choose not to validate prices at all or for specific items.
+- You may choose not to validate the inventory.
+- Depending on your data store, you may have other configuration available.
+
+
+#### Available DataStores
+
+- [OrderDesk](https://www.orderdesk.com)
+- [Webflow CMS](https://webflow.com)
+
+#### The Foxy Pre-Payment Webhook
+
+The pre-payment webhook fires before a transaction is submitted to the payment processor (Stripe, Authorize.net, PayPal, etc.). We'll use that with these functions to prevent overselling, and also to prevent product link/form tampering if you can't use Foxy's [link+form signing](https://wiki.foxycart.com/v/2.0/hmac_validation) (either directly or via [the Cloudflare Worker hmac signing function](https://github.com/Foxy/foxy-cloudflare-addtocart-signing) to do it automatically).
+
+**It ignores existing subscriptions**. If a subscription start date is "today", the price will be checked. If it is in the past, the price is not checked.
+
+#### Limitations
+
+- It does not handle discounts.
+- It does not handle item options, such as `price_mod`.
+- Due to netlify time limit, and the need to make requests to the datastore, it
+  may break against large product databases if the Datastore do not allow for
+  requesting specific items directly. Check the README for your datastore
+  integration about this issue.
+
+#### Usage
+
+1. Read the short **Configuration** section in the datastore integration page.
+  - **Important**: Your datastore must meet some criteria for the webhook to work. Product items need a `code` field.
+1. Grab the credentials needed for integrating with your datastore. Check the details in your datastore integration page.
+1. Click the **deploy to Netlify** button at the end of this page.
+  - Netlify will provide you with a form for you to provide your configuration.
+  - The Webflow Prepayment Webhook requires only `FOXY_WEBFLOW_TOKEN`. The other settings are used for the other services in this repository.
+1. Grab the URL for your webhook in Netlify. Be sure to get the correct URL for your specific webhook.
+  - To do this, after the deploy is finished, click the "functions" tab, look for your webhook function and copy the **Endpoint URL**.
+1. Configure your prepayment webhook using your endpoint. Check the docs here: https://wiki.foxycart.com/v/2.0/pre_payment_webhook
+
+
+# Development
 
 ## Localdev Setup
 

doc/datastore-integration.dot

@@ -0,0 +1,74 @@
+digraph G {
+  node [shape = box];
+  newrank=true;
+  rankdir=TB;
+  
+
+  subgraph clusterCustomer {
+    label="Customer\n\nYour customer workflow\nremains fluid.";
+    chooseProduct[label="Choose\nproducts"];
+    goToCart[label="Go to\ncart"];
+    success[label="Success"];
+    goToCart->success[style=invis];
+  }
+
+  subgraph clusterFoxy {
+    label="Foxy.io";
+    cart[label="Cart"];
+    cartSubmit[label="Cart\nSubmit"];
+    cartProcess[label="Payment\nprocessing", color="gray"];
+  }
+
+  subgraph clusterWebhook {
+    label="Datastore Integration Webhook";
+    color="gray";
+    prepaymentValidation[label="Prepayment\ntransaction\nvalidation", color="gray"];
+    transactionCreated[label="Transaction\nCreated", color="gray"];
+
+    prepaymentValidation->transactionCreated[style=invis];
+  }
+
+  subgraph clusterDatastore {
+    label="Datastore";
+    color="gray";
+    getInventory[label="get\nInventory", color="gray"];
+    getPrice[label="get\nPrice", color="gray"];
+    updateInventory[label="update\nInventory", color="gray"];
+  }
+
+chooseProduct->goToCart;
+
+goToCart->cart;
+
+cart->cartSubmit;
+
+cartSubmit->prepaymentValidation[dir="both"; label="is trasaction valid?"; style="dashed", fontsize="10px"];
+
+cartSubmit->cartProcess;
+
+cartProcess->transactionCreated[label="successful transaction"; style="dashed", fontsize="10px"];
+
+prepaymentValidation->getPrice[dir="both"; label="is price correct?", style="dashed", color=blue; fontcolor=blue; fontsize="10px"];
+prepaymentValidation->getInventory[dir="both"; label="is price correct?", style="dashed", color=blue; fontcolor=blue; fontsize="10px"];
+transactionCreated->updateInventory[label="update inventory", style="dashed", color=blue; fontcolor=blue; fontsize="10px"];
+
+cartProcess->success;
+cartSubmit->cart[label="if invalid,\ntry again", fontsize="10px", color="red", style="dashed", fontcolor=red];
+
+{rank=same;
+  goToCart; cart;
+}
+
+{rank=same;
+  cartSubmit; prepaymentValidation;
+}
+
+{rank=same;
+  cartProcess; transactionCreated;
+}
+
+{rank=same;
+chooseProduct; getInventory; updateInventory; getPrice
+}
+
+}

images/datastore-integrations-workflow.png

@@ -7,7 +7,8 @@
   FOXY_API_CLIENT_ID = "Enter your Foxy.io API Client ID here."
   FOXY_API_CLIENT_SECRET = "Enter your Foxy.io API Client Secret here."
   FOXY_API_REFRESH_TOKEN = "Enter your Foxy.io API Refresh Token here."
-  DEFAULT_AUTOSHIP_FREQUENCY = "Default autoship frequency (such as `1m`)"
-  IDEV_SECRET_KEY = "iDevAffiliate secret key (from the API settings)"
-  IDEV_API_URL = "iDevAffiliate API URL (from the API settings; should end in `sale.php`)"
-  WEBFLOW_TOKEN = "Get this from Webflow's project settings, at the 'Integrations' tab."
+  FOXY_DEFAULT_AUTOSHIP_FREQUENCY = "Default autoship frequency (such as `1m`)"
+  FOXY_IDEV_SECRET_KEY = "iDevAffiliate secret key (from the API settings)"
+  FOXY_IDEV_API_URL = "iDevAffiliate API URL (from the API settings; should end in `sale.php`)"
+  FOXY_WEBFLOW_TOKEN = "Get this from Webflow's project settings, at the 'Integrations' tab."
+  FOXY_DATASTORE_CREDENTIALS = "Datastore credentials"