You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Upgrading To The Latest Version](#upgrading-to-the-latest-version)
12
+
-[Component Library Dev Mode](#component-library-dev-mode)
13
+
-[Exception Handling](#exception-handling)
12
14
-[Linting](#linting)
13
15
-[Testing](#testing)
14
16
-[Jest](#jest)
15
17
-[Cypress](#cypress)
18
+
-[Setup your Cypress env variables](#setup-your-cypress-env-variables)
16
19
-[Deployment](#deployment)
17
20
18
21
---
@@ -31,7 +34,55 @@
31
34
32
35
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. -->
33
36
34
-
### Webstore Component Library
37
+
### Environment Variables
38
+
_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"._
| CLIENT_ID | Yes | .env.development | The identifier of the client's marketplace application |
43
+
| CLIENT_SECRET | Yes | .env.development | The secret related to the client's marketplace application |
44
+
| NEXTAUTH_SECRET | Yes | .env.development | Used to encrypt the NextAuth.js JWT |
45
+
| NEXTAUTH_URL | Yes | .env.development | The authentication route used for NextAuth.js |
46
+
| NEXT_PUBLIC_APP_BASE_URL | Yes | .env | The URL to the deployed webstore instance |
47
+
| NEXT_PUBLIC_PROVIDER_ID | Yes | .env | The identifier of the client's marketplace in the database |
48
+
| NEXT_PUBLIC_PROVIDER_NAME | Yes | .env | The subdomain of the client's marketplace |
49
+
| NEXT_PUBLIC_SCIENTIST_API_VERSION | Yes | .env | The version of the API we should be talking to |
50
+
| NEXT_PUBLIC_TOKEN | Yes | .env.development | The access token for logged out users. Ref: Provider Credentials|
51
+
| NEXT_PUBLIC_WEBHOOK_URL | Yes | .env | The URL that defines how user notifications are sent |
52
+
| SENTRY_AUTH_TOKEN | No | .env.development | The organization based auth token for the Sentry project |
53
+
| SENTRY_DSN | No | .env.development | The Data Source Name that allows monitoring of Sentry events |
54
+
| SENTRY_ORG | No | .env.development | The slug of the Sentry organization associated with the Sentry application |
55
+
| SENTRY_PROJECT | No | .env.development | The slug of the Sentry project associated with the Sentry application |
56
+
| SENTRY_URL | No | .env.development | The base URL of the Sentry instance |
57
+
58
+
#### Creating the marketplace app
59
+
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._
60
+
- Once you've clicked the "Applications" link mentioned above, press "New Application"
61
+
- Only the application name is required for the moment. Name it the same as the provider name.
62
+
- Save, and you should be redirected to the "Developer Details" page
63
+
- There will be a button that says "Reveal Token"
64
+
- Click it. You'll need that token in the next step.
65
+
66
+
#### Provider ID
67
+
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.
68
+
69
+
#### Authentication
70
+
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.
71
+
72
+
##### Provider Credentials
73
+
Please run the following in your terminal:
74
+
```bash
75
+
# When replacing the variables below with your actual values,
76
+
# the following code should return something like: THISISAREALLYLONGALPHANUMERICSTRING
77
+
echo -n 'CLIENT_ID:CLIENT_SECRET'| base64
78
+
79
+
# Plug that string into the following line of code, replacing the all caps values with your actual values
80
+
curl -X POST -H 'Authorization: Basic THISISAREALLYLONGALPHANUMERICSTRING' -d 'grant_type=client_credentials' https://NEXT_PUBLIC_PROVIDER_NAME.scientist.com/oauth/token/
81
+
```
82
+
83
+
The curl command will return a JSON object that has an `access_token` property. Set this as the `NEXT_PUBLIC_TOKEN`.
84
+
85
+
## Webstore Component Library
35
86
The webstore requires a [React component library](https://reactjs.org/docs/react-component.html) of view components. That dependency is packaged and released independently.
Using the local github repository requires you to manually clone the component library to your computer, build, and link it:
49
100
50
-
Preparing your local copy of the component library:
101
+
##### Preparing your local copy of the component library:
102
+
_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)_
yarn link # now there is a magic symlink in `~/.config/yarn/link` usable by the webstore app
56
106
57
-
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:
107
+
Choose one of the below:
58
108
59
-
npm run build-lib # for a onetime build
60
-
npm run watch-lib # for a continuous build
109
+
npm run build-lib # must be run every time you want a change to show in the webstore
110
+
npm run watch-lib # run once and the wcl will watch for changes
61
111
62
-
Back in your webstore checkout:
112
+
##### Preparing your local copy of the webstore:
63
113
114
+
# run in a separate terminal window than where the wcl is
115
+
cd webstore
64
116
yarn link "@scientist-softserv/webstore-component-library"
and your `webstore` will start using the local component build.
67
-
68
-
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.
69
-
70
-
### Environment Variables
71
-
Configure the environment variables below in your local and published application to ensure that it works.
120
+
##### Return to using the packaged version of the webstore-component-library:
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.
127
+
##Exception Handling
128
+
The application is configured to use Sentry. Refer to ".env.development.example" for how to find the necessary variables.
75
129
76
-
```bash
77
-
# .env
78
-
NEXT_PUBLIC_PROVIDER_NAME # e.g.: acme
79
-
NEXT_PUBLIC_PROVIDER_ID # e.g.: 500
80
-
```
81
-
82
-
#### Authentication
83
-
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.
84
-
85
-
##### User Credentials
86
-
```bash
87
-
# .env.development
88
-
NEXTAUTH_SECRET # create this by running `openssl rand -base64 32` in your terminal
89
-
CLIENT_ID # retrieved from the provider storefront
90
-
CLIENT_SECRET # retrieved from the provider storefront
91
-
```
92
-
93
-
##### Provider Credentials
94
-
Please run the following in your terminal:
95
-
```bash
96
-
# When replacing the variables below with your actual values,
97
-
# the following code should return something like: THISISAREALLYLONGALPHANUMERICSTRING
98
-
echo -n 'CLIENT_ID:CLIENT_SECRET'| base64
99
-
100
-
# Plug that string into the following line of code, replacing the all caps values with your actual values
101
-
curl -X POST -H 'Authorization: Basic THISISAREALLYLONGALPHANUMERICSTRING' -d 'grant_type=client_credentials' https://NEXT_PUBLIC_PROVIDER_NAME.scientist.com/oauth/token/
102
-
```
103
-
104
-
The curl command will return a JSON object that has an `access_token` property. Store the value of that property as shown below:
105
-
106
-
```bash
107
-
# .env.development
108
-
NEXT_PUBLIC_TOKEN
109
-
```
130
+
If any other exception handler is desired, it will require configuration.
0 commit comments