Merge pull request #9 from Foxy/polish/datastores

brettflorio · web-flow · commit 0fed19745f79 · 2021-05-05T15:05:29.000-07:00
Polish/datastores
diff --git a/README.md b/README.md
@@ -1,17 +1,26 @@
 # Netlify Serverless Functions for the Foxy.io API
 
-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.
+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](#Built to be 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.
+
+You may use this repository:
+- directly, configuring it to your needs with environment variables
+- as usage examples, to better understand the usage of Foxy API and FoxySDK.
 
 ## Functions
 
-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.
+The functions provided in this repository are used independently.
+
+Be sure to check the README for each function in the functions folder, as they provide specific documentation.
 
-- [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-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.
-- [ShipTheory](src/functions/shiptheory): Creates shipments in your ShipTheory account upon successful transactions.
+- Other features:
+  - [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.
+  - [shiptheory](src/functions/shiptheory): Creates shipments in your ShipTheory account upon successful transactions.
 
 
 ### Data Store Integrations
@@ -61,9 +70,74 @@ The pre-payment webhook fires before a transaction is submitted to the payment p
   - 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
 
+# Configuration Reference
+
+This section contains all **environment variables** you can use to configure the webhooks in this repository.
+
+**You do not need to configure all these.** Check the documentation for the functions you are using for the configuration relevant to them.
+
+This list is provided for your quick reference.
+
+**Please, note** that the default values for these variables may be different for each function.
+We try to have sensible defaults for each third party service we are integrating with and for each task we are performing.
+
+## How to set **environment variables** in Netlify
+
+These are set with **environment variables** that you can set directly in Netlify dashboard.
+
+To configure your **environment variables** follow these steps:
+- go to your site admin dashboard in Netlify
+- click "Site settings" button
+- click the "Build & deploy" tab in the left menu
+- under **Environment**, click "Edit variables"
+
+Please, notice that the default values where chosen to match the default OrderDesk settings.
+You shouldn't need to change these values unless you are not using OrderDesk default fields.
+
+This section contains all possible customizations you can do by setting environment variables.
+
+After changing your environment variables you will want to redeploy your webhook.
+
+| Environment Variable | Description |
+| -------  | --- | 
+|`FOXY_API_CLIENT_ID`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_API_CLIENT_SECRET`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_API_REFRESH_TOKEN`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_DEFAULT_AUTOSHIP_FREQUENCY`|[description in Cart doc](src/functions/cart#environment-variables)|
+|`FOXY_ERROR_INSUFFICIENT_INVENTORY`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_ERROR_PRICE_MISMATCH`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_FIELD_CODE`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_FIELD_INVENTORY`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_FIELD_PRICE`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_IDEV_API_URL`|[description in Idev Affiliate doc](src/functions/idevaffiliate-marketplace/README.md#environment-variables)|
+|`FOXY_IDEV_SECRET_KEY`|[description in Idev Affiliate doc](src/functions/idevaffiliate-marketplace/README.md#environment-variables)|
+|`FOXY_ORDERDESK_API_KEY`|[description in Idev Affiliate doc](src/functions/datastore-integration-orderdesk/README.md#environment-variables)|
+|`FOXY_ORDERDESK_STORE_ID`|[description in Idev Affiliate doc](src/functions/datastore-integration-orderdesk/README.md#environment-variables)|
+|`FOXY_SKIP_INVENTORY_CODES`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_SKIP_INVENTORY_UPDATE_CODES`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_SKIP_PRICE_CODES`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
+|`FOXY_WEBFLOW_TOKEN`|[description in Idev Affiliate doc](src/functions/datastore-integration-webflow/README.md#environment-variables)|
+|`FOXY_WEBHOOK_ENCRYPTION_KEY`| [description in Foxy Webhook doc](src/foxy/README.md#environment-variables)|
 
 # Development
 
+## Built to be approachable
+
+This repository aims to used as a reference to users who wish to extend their use of Foxy by adding custom server-side features.
+
+Here are some choices we've made:
+
+- Javascript: the language is approachable in itself and widely known.
+- Netlify: provides easy deployment and continuous integration with near zero configuration.
+- Default behaviours: are set in according to the task, tunned to feel natural for users of the tools each function is integrating with
+- Specific instructions: each function has its own README file that should be the only required reading to implement that function. This does not mean we will repeat instructions everywhere, but simply that by reading the docs of the function user will find everything needed, either on that page or on clearly provided links.
+
+These are some goals:
+
+- users should be able to navigate the code with ease, without usage or knowledge of advanced tools
+- users should be able to copy and customize code with relative ease, without the need 
+
+
 ## Localdev Setup
 
 1. `npm install -g netlify-cli`
diff --git a/config.js b/config.js
@@ -12,7 +12,6 @@ function env(envVar) {
 
 const config = {
   datastore: {
-    credentials: env('FOXY_DATASTORE_CREDENTIALS'),
     error: {
       insufficientInventory: env('FOXY_ERROR_INSUFFICIENT_INVENTORY') || env('FX_ERROR_INSUFFICIENT_INVENTORY'),
       priceMismatch: env('FOXY_ERROR_PRICE_MISMATCH') || env('FX_ERROR_PRICE_MISMATCH')
diff --git a/netlify.toml b/netlify.toml
@@ -2,13 +2,3 @@
   command = "npm i"
   functions = "src/functions"
 
-[template.environment]
-  FOXY_TIMEZONE = "Foxy store timezone, as in `America/Los_Angeles`. Full list: https://tinyurl.com/yxoaxbpz"
-  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."
-  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"
diff --git a/src/foxy/FoxyWebhook.js b/src/foxy/FoxyWebhook.js
@@ -149,6 +149,10 @@ function validSignature(payload, signature, key) {
  * @returns {boolean} the signature is valid
  */
 function verifyWebhookSignature(req) {
+  if (!config.foxy.webhook.encryptionKey) {
+    console.log("Foxy Webhook Encryption key is not set. Security can be enhanced if you set it.");
+    return true;
+  }
   const foxyEvent = req.headers['foxy-webhook-event'];
   const signature = req.headers['foxy-webhook-signature'];
   if (foxyEvent === 'validation/payment') {
diff --git a/src/foxy/README.md b/src/foxy/README.md
@@ -0,0 +1,35 @@
+# Foxy Webhook
+
+This module aims to consolidate the interaction with Foxy Webhooks.
+
+- use FoxySDK to validate the Foxy Webhook Signature
+- provide default responses
+
+## Webhook validation
+
+The webhook validation is optional and is performed if the
+`FOXY_WEBHOOK_ENCRYPTION_KEY` environment variable is set. If it is not set
+requests are presumed to be from Foxy.
+
+## Environment variables
+
+These environment variables are used to configure datastore functions.
+
+| Variable                   | Default Value   | Description|
+| -------------------------- | --------------- | ------------------- |
+| `FOXY_API_CLIENT_ID`         | ""      | **Required** Your Foxy Client Id. |
+| `FOXY_API_CLIENT_SECRET`     | ""      | **Required** Your Foxy Client Secret.|
+| `FOXY_API_REFRESH_TOKEN `    | ""      | **Required** Your Foxy Client Refresh Token.|
+| `FOXY_WEBHOOK_ENCRYPTION_KEY`     | "" | **Required** Your wehook encryption key. **This value must not be shared or made public.** |
+| `FOXY_ERROR_INSUFFICIENT_INVENTORY` | "Insufficient inventory for these items:" | Occurs when the quantity purchased is greater than the inventory available in Webflow. **A comma separated list of the names of the products out-of-stock will be appended to the end of the error message**. |
+| `FOXY_ERROR_PRICE_MISMATCH`         | "Prices do not match."                    | Occurs when the price of any of the products does not match with the `price` field in Webflow |
+| `FOXY_FIELD_CODE`                   | "code"\* | The name of the field that stores the code in the webflow collection.                                                                                                                                              |
+| `FOXY_FIELD_PRICE`                  | "price"\* | The name of the field that stores the price in the webflow collection.                                                                                                                                             |
+| `FOXY_FIELD_INVENTORY`              | "inventory"\* | The name of the field that stores the inventory in the webflow collection. Set this variable to "false" (without the quotes) to disable inventory verification for all items.                                      |
+| `FOXY_SKIP_INVENTORY_CODES`         | ""\* | A comma separated list of code values (this is the value set in your 'code' field in Webflow or in the field you set with `code_field` parameter. **The items with these codes will skip inventory verification**. |
+| `FOXY_SKIP_PRICE_CODES`             | ""\* | A comma separated list of code values (this is the value set in your 'code' field in Webflow or in the field you set with `code_field` parameter. **The items with these codes will skip price verification**.     |
+| `FOXY_SKIP_INVENTORY_CODES`         | ""\* | A comma separated list of code values (this is the value set in your 'code' field in Webflow or in the field you set with `code_field` parameter. **The items with these codes will skip inventory verification**. |
+
+\* These default values may be different for some functions.
+Please, check the specific documentation for the function you are using.
+
diff --git a/src/functions/cart/README.md b/src/functions/cart/README.md
@@ -17,15 +17,16 @@ functions from this repository you don't need to do this step.
 1. Go to Netlify and click `New site from Git`.
 1. Choose the repository you've just cloned.
 
-### Configuration
+### Environment variables
 
 This webhook depends on FoxyAPI and requires setting the following environment variables:
 
 | Variable                   | Default Value   | Description|
 | -------------------------- | --------------- | ------------------- |
-| FOXY_API_CLIENT_ID         | ""         | **Required** Your Foxy Client Id. | 
-| FOXY_API_CLIENT_SECRET     | ""         | **Required** Your Foxy Client Secret.|
-| FOXY_API_REFRESH_TOKEN     | ""         | **Required** Your Foxy Client Refresh Token.|
+| `FOXY_API_CLIENT_ID`         | ""         | **Required** Your Foxy Client Id. | 
+| `FOXY_API_CLIENT_SECRET`     | ""         | **Required** Your Foxy Client Secret.|
+| `FOXY_API_REFRESH_TOKEN `    | ""         | **Required** Your Foxy Client Refresh Token.|
+|`FOXY_DEFAULT_AUTOSHIP_FREQUENCY`| "1m" | The default subscription frequency to be used when converting a cart into subscriptions.|
 
 
 You can grab these values for your store going to your Foxy Store Admin page, click on the "integrations" link and, under "current integrations" click "Get Token".
diff --git a/src/functions/datastore-integration-orderdesk/DataStore.js b/src/functions/datastore-integration-orderdesk/DataStore.js
@@ -64,21 +64,9 @@ class DataStore extends DataStoreBase {
   }
 
   parseConfigCredentials(config) {
-    const rawCredentials = config.datastore.credentials;
-    let matched;
-    if (rawCredentials) {
-      matched = rawCredentials.match(/Store ID (\d{5}) API Key ([A-Za-z0-9]+)$/);
-    }
-    if (matched && matched.length === 3) {
-      return {
-        id: matched[1],
-        key: matched[2]
-      }
-    } else {
-      return {
-        id: config.datastore.provider.orderDesk.storeId,
-        key: config.datastore.provider.orderDesk.apiKey
-      }
+    return {
+      id: config.datastore.provider.orderDesk.storeId,
+      key: config.datastore.provider.orderDesk.apiKey
     }
   }
 
diff --git a/src/functions/datastore-integration-orderdesk/README.md b/src/functions/datastore-integration-orderdesk/README.md
@@ -32,7 +32,7 @@ Please, notice that **it ignores existing subscriptions**.
 - It does not handle discounts.
 - It does not handle item options, such as `price_mod`.
 
-# Setup 
+# Setup
 
 ## Setup Overview
 
@@ -82,7 +82,7 @@ repository, there are some steps you may skip (those you've already done).
     - Save your settings clicking on the "Update Payment Gateway" button in the bottom of the page.
 1. Configure your **transaction/created** webhook if you want it to update your inventory in OrderDesk. You may check the docs here: https://wiki.foxycart.com/v/2.0/webhooks
     - Go to your [Foxy.io Admin page](https://admin.foxycart.com/admin.php)
-    - Under "Account", click ["integrations]"(https://admin.foxycart.com/admin.php?ThisAction=AddIntegration) 
+    - Under "Account", click ["integrations]"(https://admin.foxycart.com/admin.php?ThisAction=AddIntegration)
     - Check the "JSON Webhook" box and paste the same Endpoint you copied from your Netlify function in the URL field.
     - Give it a title that makes sense to you.
     - Copy the value from the "Encryption Key" field.
@@ -92,7 +92,7 @@ repository, there are some steps you may skip (those you've already done).
 
 # Configuration Reference
 
-There are a some customization you can do to your webhook.
+There are some customization you can do to your webhook.
 These are set with **environment variables** that you can set directly in Netlify dashboard.
 
 To configure your **environment variables** follow these steps:
@@ -108,17 +108,16 @@ This section contains all possible customizations you can do by setting environm
 
 After changing your environment variables you may want to redeploy your webhook.
 
-##### Configuration
+##### Environment variables
 
 These environment variables are used to allow your webhook to authenticate authenticate with Foxy and OrderDesk.
 
 
 | Variable                        | Default Value   | Description|
 | ------------------------------- | --------------- | --------------------------------------------------------------------------------  |
-| `FOXY_WEBHOOK_ENCRYPTION_KEY`     | ""         | **Required** Your wehook encryption key. **This value must not be shared or made public.** | 
+| `FOXY_WEBHOOK_ENCRYPTION_KEY`     | ""         | **Optional** Your wehook encryption key. **This value must not be shared or made public.** |
 | `FOXY_ORDERDESK_API_KEY`          | ""         | **Required** Your OrderDesk API Key                                                    |
 | `FOXY_ORDERDESK_STORE_ID`         | ""         | **Required** Your OrderDesk Store id                                                   |
-| `FOXY_DATASTORE_CREDENTIALS`      | ""         | This variable is an alternative to `FOXY_ORDERDESK_API_KEY` and `FOXY_ORDERDESK_STORE_ID`. If you provide this variable you don't have to provide those. This is meant to receive a copy of the values provided in the API tab in your OrderDesk settings.|
 
 
 ##### Price and Inventory verification
@@ -139,7 +138,7 @@ This is likely unnecessary and you shouldn't change these default values unless
 | Variable                         | Default Value   | Example config         |Description                                                                                                                                                                                                        |
 | -------------------------------- | --------------- | ---------------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `FOXY_FIELD_CODE`                  | "sku"           | "code"                 |The name of the field that stores the code in OrderDesk. **There is no need to set this if you are using OrderDesk "code" as your "sku"**.                           |
-| `FOXY_FIELD_PRICE`                 | "price"         | "value"                |The name of the field that stores the price in the OrderDesk. **There is no need to set this if you are using OrderDesk "price" field**.                             | 
+| `FOXY_FIELD_PRICE`                 | "price"         | "value"                |The name of the field that stores the price in the OrderDesk. **There is no need to set this if you are using OrderDesk "price" field**.                             |
 | `FOXY_FIELD_INVENTORY`             | "stock"         | "inventory"            |The name of the field that stores the inventory in OrderDesk. **There is no need to set this if you are using OrderDesk "stock" field**. |
 
 ##### Error messages
@@ -173,9 +172,11 @@ Cloning the repository will create your own copy of this Webhook, allowing you t
 Go to your Netlify account and click the "New site from Git" button.
 
 - Choose your repository.
-- Click the "Advanced" button and then "New Variable"
-  - The key should be: `FOXY_DATASTORE_CREDENTIALS`
-  - To get this token, go to OrderDesk settings, at the 'API' tab. Copy all the information provided.
+- Click the "Advanced" button add the following variables.
+    - `FOXY_ORDERDESK_API_KEY`
+    - `FOXY_ORDERDESK_STORE_ID`
+- To get these variables go to OrderDesk settings, at the 'API' tab.
+
 
 # Upgrade your webhook
 
@@ -188,3 +189,4 @@ If you forked the repository, you can use the GitHub Action available in the "Ac
 - Click the SyncFork workflow and then "run workflow"
 
 If you've made customizations, there may be conflicts. In this case you par pull the changes and resolve the conflicts manually.
+
diff --git a/src/functions/idevaffiliate-marketplace/README.md b/src/functions/idevaffiliate-marketplace/README.md
diff --git a/test/functions/datastore-integration-orderdesk/DataStore.test.js b/test/functions/datastore-integration-orderdesk/DataStore.test.js
