add some info about env variables and how to create new marketplaces

scientist-softserv · Sep 12, 2023 · 572949a · 572949a
1 parent f2532d3
commit 572949a
Showing 1 changed file with 76 additions and 40 deletions.
diff --git a/README.md b/README.md
@@ -2,12 +2,15 @@
 
 - [Getting Started](#getting-started)
  - [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)
@@ -31,51 +34,45 @@
 
 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
-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
-In the terminal:
-``` bash
-# first check for whether there is an updated version
-yarn outdated @scientist-softserv/webstore-component-library # check the values under "current" and "latest"
-
-# if there's an updated version
-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:
-
- 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:
-
- npm run build-lib # for a onetime build
- npm run watch-lib # for a continuous build
-
-Back in your webstore checkout:
-
- yarn link "@scientist-softserv/webstore-component-library"
-
-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.
+The following variables can be found in the `.env` and `.env.local` files.
+
+| Name | Description | Required |
+| ------------- | ------------- | ------------- |
+| NEXT_PUBLIC_PROVIDER_NAME | The subdomain of the `marketplace-domain` | Yes |
+| NEXT_PUBLIC_PROVIDER_ID | TODO | Yes |
+| NEXT_PUBLIC_APP_BASE_URL | TODO | Yes |
+| NEXT_PUBLIC_SCIENTIST_API_VERSION | TODO | Yes |
+| NEXT_PUBLIC_WEBHOOK_URL | TODO | Yes |
+| NEXTAUTH_SECRET | TODO | Yes |
+| NEXTAUTH_URL | TODO | Yes |
+| CLIENT_ID | TODO | Yes |
+| CLIENT_SECRET | TODO | Yes |
+| NEXT_PUBLIC_TOKEN | TODO | Yes |
+| SENTRY_DSN | TODO | No |
+| NEXT_PUBLIC_SENTRY_DSN | TODO | No |
+| SENTRY_URL | TODO | No |
+| SENTRY_ORG | TODO | No |
+| SENTRY_PROJECT | TODO | No |
+| SENTRY_AUTH_TOKEN | TODO | No |
+
+#### 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 app needs to be created on it by a developer with the proper permissions. This will allow for the environment variables in the `.env` and `.env.local` files to be set. 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.
+- Once you've clicked the "Applications" link mentioned above, press "New Application"
+ - Only the application name is required for the moment
+- 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-domain>/api/v2/providers.json?q=${YOUR_PROVIDER_NAME}`, e.g. `webstore.scientist.com/api/v2/providers.json?q=webstore`. Your authorization needs to be your token from the step above, formatted as a Bearer Token. Scroll to the `provider_refs` array and use the `provider_id` value to fill in the `NEXT_PUBLIC_PROVIDER_ID` variable below.
+
+The `NEXT_PUBLIC_PROVIDER_NAME` needs to exactly match the subdomain of the `marketplace-domain`.
 
-#### 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.
 
 ``` bash
 # .env
-NEXT_PUBLIC_PROVIDER_NAME # e.g.: acme
+NEXT_PUBLIC_PROVIDER_NAME # e.g.: webstore
 NEXT_PUBLIC_PROVIDER_ID # e.g.: 500
 ```
 
@@ -108,6 +105,45 @@ The curl command will return a JSON object that has an `access_token` property.
 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
+In the terminal:
+``` bash
+# first check for whether there is an updated version
+yarn outdated @scientist-softserv/webstore-component-library # check the values under "current" and "latest"
+
+# if there's an updated version
+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:
+
+ 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:
+
+ npm run build-lib # for a onetime build
+ npm run watch-lib # for a continuous build
+
+Back in your webstore checkout:
+
+ yarn link "@scientist-softserv/webstore-component-library"
+
+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.
+
+## Exception Handling
+<!-- TODO: add sentry details -->
+
 ## Linting
 ``` bash
 # lint all files