Merge pull request #307 from scientist-softserv/better-readme

better-readme

.env.development.example

@@ -1,12 +1,12 @@
-NEXTAUTH_SECRET=
-NEXTAUTH_URL=
-CLIENT_ID=
-CLIENT_SECRET=
-NEXT_PUBLIC_TOKEN=
+CLIENT_ID= # Retrieved from the marketplace application show page under Developer Details
+CLIENT_SECRET= # Retrieved from the marketplace application show page under Developer Details
+NEXTAUTH_SECRET= # Create this by running `openssl rand -base64 32` in your terminal. (https://next-auth.js.org/configuration/options#nextauth_secret)
+NEXTAUTH_URL= # https://next-auth.js.org/configuration/options#nextauth_url
+NEXT_PUBLIC_TOKEN= # Ref: "Provider Credentials" in the README
 
 # uncomment the “SENTRY” prefixed variables below if you are using sentry and need to catch errors in local dev
+# SENTRY_AUTH_TOKEN= ref: https://github.com/getsentry/sentry-webpack-plugin#options (authToken)
 # SENTRY_DSN=ref: https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/#where-to-find-your-dsn
-# SENTRY_URL=https://sentry.io/
-# SENTRY_ORG= ref: https://github.com/getsentry/sentry-webpack-plugin#options (org)
 # SENTRY_PROJECT= ref: https://github.com/getsentry/sentry-webpack-plugin#options (project)
-# SENTRY_AUTH_TOKEN= ref: https://github.com/getsentry/sentry-webpack-plugin#options (authToken)
+# SENTRY_ORG= ref: https://github.com/getsentry/sentry-webpack-plugin#options (org)
+# SENTRY_URL=https://sentry.io/

.env.example

@@ -0,0 +1,8 @@
+# reference https://nextjs.org/docs/basic-features/environment-variables#exposing-environment-variables-to-the-browser
+# to learn about the NEXT_PUBLIC prefix
+
+NEXT_PUBLIC_APP_BASE_URL=https://store.webstore.com
+NEXT_PUBLIC_PROVIDER_ID=0001
+NEXT_PUBLIC_PROVIDER_NAME=webstore
+NEXT_PUBLIC_SCIENTIST_API_VERSION=v2
+NEXT_PUBLIC_WEBHOOK_URL=http://ss-mailer/webstore

.gitignore

@@ -4,6 +4,7 @@ node_modules/
 # Next.js build output
 .next
 
+.env
 # Where ENV secrets are stored. although NextJS uses `.env.local`
 # (https://nextjs.org/docs/basic-features/environment-variables#default-environment-variables), we are using `.env.development`
 # for consistency with other projects. this also ensures our CICD and docker processes work.

README.md

@@ -1,18 +1,21 @@
-# Webstore
-## Table of Contents
+# Webstore (a.k.a. Digital Storefront)
 
 - [Getting Started](#getting-started)
- - [Webstore Component Library](#webstore-component-library)
- - [Upgrading To The Latest Version](#upgrading-to-the-latest-version)
- - [Component Library Dev Mode](#component-library-dev-mode)
  - [Environment Variables](#environment-variables)
+ - [Creating the marketplace app](#creating-the-marketplace-app)
+ - [Provider ID](#provider-id)
  - [Authentication](#authentication)
  - [User Credentials](#user-credentials)
  - [Provider Credentials](#provider-credentials)
+- [Webstore Component Library](#webstore-component-library)
+ - [Upgrading To The Latest Version](#upgrading-to-the-latest-version)
+ - [Component Library Dev Mode](#component-library-dev-mode)
+- [Exception Handling](#exception-handling)
 - [Linting](#linting)
 - [Testing](#testing)
  - [Jest](#jest)
  - [Cypress](#cypress)
+ - [Setup your Cypress env variables](#setup-your-cypress-env-variables)
 - [Deployment](#deployment)
 
 ---
@@ -31,7 +34,55 @@
 
 The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages. -->
 
-### Webstore Component Library
+### Environment Variables
+_The terms "client" and "provider" are fairly interchangeable in this application. In the details below we will assume that the client's name is "webstore". Their marketplace would be at "webstore.scientist.com"._
+
+| Name | Required | Location | Description |
+| ------------- | ------------- | ------------- | ------------- |
+| CLIENT_ID | Yes | .env.development | The identifier of the client's marketplace application |
+| CLIENT_SECRET | Yes | .env.development | The secret related to the client's marketplace application |
+| NEXTAUTH_SECRET | Yes | .env.development | Used to encrypt the NextAuth.js JWT |
+| NEXTAUTH_URL | Yes | .env.development | The authentication route used for NextAuth.js |
+| NEXT_PUBLIC_APP_BASE_URL | Yes | .env | The URL to the deployed webstore instance |
+| NEXT_PUBLIC_PROVIDER_ID | Yes | .env | The identifier of the client's marketplace in the database |
+| NEXT_PUBLIC_PROVIDER_NAME | Yes | .env | The subdomain of the client's marketplace |
+| NEXT_PUBLIC_SCIENTIST_API_VERSION | Yes | .env | The version of the API we should be talking to |
+| NEXT_PUBLIC_TOKEN | Yes | .env.development | The access token for logged out users. Ref: Provider Credentials|
+| NEXT_PUBLIC_WEBHOOK_URL | Yes | .env | The URL that defines how user notifications are sent |
+| SENTRY_AUTH_TOKEN | No | .env.development | The organization based auth token for the Sentry project |
+| SENTRY_DSN | No | .env.development | The Data Source Name that allows monitoring of Sentry events |
+| SENTRY_ORG | No | .env.development | The slug of the Sentry organization associated with the Sentry application |
+| SENTRY_PROJECT | No | .env.development | The slug of the Sentry project associated with the Sentry application |
+| SENTRY_URL | No | .env.development | The base URL of the Sentry instance |
+
+#### Creating the marketplace app
+Ensure that a marketplace, e.g. client-name.scientist.com, has been created by the Scientist.com Professional Services team. Once that exists, an application needs to be created on that marketplace by a developer with the proper permissions. This is how some of the environment variables are created. You'll know if you have the proper developer permissions if once logged in on the client marketplace, you can hover over your avatar and see "Applications" underneath the "Developer" settings. _If you don't have the permissions, you need to request them, or ask someone with the permissions to complete the steps below._
+- Once you've clicked the "Applications" link mentioned above, press "New Application"
+ - Only the application name is required for the moment. Name it the same as the provider name.
+- Save, and you should be redirected to the "Developer Details" page
+- There will be a button that says "Reveal Token"
+- Click it. You'll need that token in the next step.
+
+#### Provider ID
+In an API GUI (e.g. Postman) make a GET request for `<marketplace>/api/v2/providers.json?q=${PROVIDER_NAME}`. Your authorization will be your token from the step above, formatted as a Bearer Token. e.g. `Bearer MY_TOKEN` Scroll to the `provider_refs` array and use the `provider_id` value to fill in the `NEXT_PUBLIC_PROVIDER_ID` variable.
+
+#### Authentication
+All API endpoints in this app require some form of authentication. A logged out user will be able to access the home and browse pages using a provider credential, while a logged in user can access all pages using their own credentials.
+
+##### Provider Credentials
+Please run the following in your terminal:
+``` bash
+# When replacing the variables below with your actual values,
+# the following code should return something like: THISISAREALLYLONGALPHANUMERICSTRING
+echo -n 'CLIENT_ID:CLIENT_SECRET' | base64
+
+# Plug that string into the following line of code, replacing the all caps values with your actual values
+curl -X POST -H 'Authorization: Basic THISISAREALLYLONGALPHANUMERICSTRING' -d 'grant_type=client_credentials' https://NEXT_PUBLIC_PROVIDER_NAME.scientist.com/oauth/token/
+```
+
+The curl command will return a JSON object that has an `access_token` property. Set this as the `NEXT_PUBLIC_TOKEN`.
+
+## Webstore Component Library
 The webstore requires a [React component library](https://reactjs.org/docs/react-component.html) of view components. That dependency is packaged and released independently.
 
 #### Upgrading To The Latest Version
@@ -47,66 +98,36 @@ yarn upgrade @scientist-softserv/webstore-component-library --latest
 #### Component Library Dev Mode
 Using the local github repository requires you to manually clone the component library to your computer, build, and link it:
 
-Preparing your local copy of the component library:
+##### Preparing your local copy of the component library:
+_Prerequisite: clone the [webstore-component-library](https://github.com/scientist-softserv/webstore-component-library.git) and [get the app running](https://github.com/scientist-softserv/webstore-component-library#running-the-app)_
 
- git clone https://github.com/scientist-softserv/webstore-component-library.git
  cd webstore-component-library
- npm install
  yarn link # now there is a magic symlink in `~/.config/yarn/link` usable by the webstore app
 
-If there are changes to the component library, you will need to rebuild in order to get the newest changes. You can either rebuild manually after changes are made, or have the webstore continually "watch" for changes:
+Choose one of the below:
 
- npm run build-lib # for a onetime build
- npm run watch-lib # for a continuous build
+ npm run build-lib # must be run every time you want a change to show in the webstore
+ npm run watch-lib # run once and the wcl will watch for changes
 
-Back in your webstore checkout:
+##### Preparing your local copy of the webstore:
 
+ # run in a separate terminal window than where the wcl is
+ cd webstore
  yarn link "@scientist-softserv/webstore-component-library"
+ yarn remove @scientist-softserv/webstore-component-library
+ (restart the dev server)
 
-and your `webstore` will start using the local component build.
-
-If you are using a local version of the component library, you will need to temporarily delete the line `"@scientist-softserv/webstore-component-library": "VERSION_HERE",` from the `package.json` file in order to see your local changes as opposed to pulling from the github package.
-
-### Environment Variables
-Configure the environment variables below in your local and published application to ensure that it works.
+##### Return to using the packaged version of the webstore-component-library:
+ # in the webstore repository
+ yarn unlink "@scientist-softserv/webstore-component-library"
+ git checkout package.json yarn.lock
+ yarn install --check-files --force
+ (restart the dev server)
 
-#### Provider
-Someone with access to the api needs to visit `/providers.json?q=${YOUR_PROVIDER_NAME}` to find your provider object and id. Once found, update the variable below.
+## Exception Handling
+The application is configured to use Sentry. Refer to ".env.development.example" for how to find the necessary variables.
 
-``` bash
-# .env
-NEXT_PUBLIC_PROVIDER_NAME # e.g.: acme
-NEXT_PUBLIC_PROVIDER_ID # e.g.: 500
-```
-
-#### Authentication
-All API endpoints in this app require some form of authentication. A logged out user will be able to access the home and browse pages using a provider credential, while a logged in user can access all pages using their own credentials.
-
-##### User Credentials
-``` bash
-# .env.development
-NEXTAUTH_SECRET # create this by running `openssl rand -base64 32` in your terminal
-CLIENT_ID # retrieved from the provider storefront
-CLIENT_SECRET # retrieved from the provider storefront
-```
-
-##### Provider Credentials
-Please run the following in your terminal:
-``` bash
-# When replacing the variables below with your actual values,
-# the following code should return something like: THISISAREALLYLONGALPHANUMERICSTRING
-echo -n 'CLIENT_ID:CLIENT_SECRET' | base64
-
-# Plug that string into the following line of code, replacing the all caps values with your actual values
-curl -X POST -H 'Authorization: Basic THISISAREALLYLONGALPHANUMERICSTRING' -d 'grant_type=client_credentials' https://NEXT_PUBLIC_PROVIDER_NAME.scientist.com/oauth/token/
-```
-
-The curl command will return a JSON object that has an `access_token` property. Store the value of that property as shown below:
-
-``` bash
-# .env.development
-NEXT_PUBLIC_TOKEN
-```
+If any other exception handler is desired, it will require configuration.
 
 ## Linting
 ``` bash