Remove duplication in documentation (#148)

Single page about environment variables, logging, error handling, and forms. We previously had separate pages under Shipping/Orders/Fulfillment Providers that had the exact same content. The information applies to all apps and should be available at a higher level.
ShipEngine · Jul 25, 2023 · 6e591bd · 6e591bd
1 parent 7a0a795
commit 6e591bd
Show file tree

Hide file tree

Showing 20 changed files with 117 additions and 196 deletions.
diff --git a/environment-variables/_environment-variables.md b/environment-variables/_environment-variables.md
diff --git a/error-handling/_error-handling.md b/error-handling/_error-handling.md
@@ -3,7 +3,7 @@ All errors can be imported from the `@shipengine/connect-runtime` package and ar
 
 :::warning Warning
 
-Avoid intentionally throwing generic JavaScript errors, these errors will be represented as an issue with your integration, and can cause your integration to be turned off from public consumption.
+Avoid intentionally throwing generic JavaScript errors. These errors will be represented as an issue with your integration, and can cause your integration to be turned off from public consumption.
 ```JavaScript
 throw new Error('This is a bad idea'); // Don't do this.
 ```

diff --git a/forms/_intro.md b/forms/_intro.md
@@ -1,3 +1,5 @@
 # Forms
 
-A part of the ShipEngine Connect platform is allowing integrations to define their own forms used for things like registering or connecting a new account, and updating settings in the case of shipping integrations. These forms are defined using a library call `rect-jsonschema-form` and are comprised of two parts, a `JsonSchema` and a `UiSchema`.
+A part of the ShipEngine Connect platform is allowing integrations to define
+their own forms used for things like registering or connecting a new account.
+These forms are defined using the [react-jsonschema-form](https://rjsf-team.github.io/react-jsonschema-form/docs/) syntax, and are comprised of two parts, a `JsonSchema` and a `UiSchema`.
diff --git a/fulfillment-provider/authentication.md b/fulfillment-provider/authentication.md
@@ -81,7 +81,7 @@ The next step will be to publish your application using the `connect publish` co
 
 - Contact a member of the [ShipEngine Connect Team](mailto:[email protected]?subject=OAuth%20Installation) in order to establish the platform installation
     - Provide a ClientId & ClientSecret used for initiating the oauth workflow
-- Once the installation has been created you will recieve back a callback url
+- Once the installation has been created you will receive back a callback url
 
 ## Test
 :::success PRO TIP

diff --git a/fulfillment-provider/environment-variables.md b/fulfillment-provider/environment-variables.md
diff --git a/fulfillment-provider/forms.md b/fulfillment-provider/forms.md
diff --git a/fulfillment-provider/logging.md b/fulfillment-provider/logging.md
diff --git a/getting-started/environment-variables.md b/getting-started/environment-variables.md
@@ -1,8 +1,8 @@
 ---
-title: Managing App Environment Variables
+title: Managing Configuration
 ---
 
-# Managing Environment Variables
+# Managing Configuration
 
 The `shipengine-connect env` command allows you to set environment variables that
 will be available to your app once it is published to ShipEngine Connect. This
@@ -19,28 +19,57 @@ When you run the `shipengine-connect env` command, you will include one of its
 subcommands listed below to indicate which environment variable action you would
 like to perform.
 
-## Set Environment Variables
+## Commands
+
+### Set Environment Variables
 This subcommand sets one or more environment variables.
+
+`shipengine-connect env:set NAME=value NAME_2=value2 ... NAME_N=valueN [OPTIONS]`
+
+Example:
+
 ```bash
-shipengine-connect env:set NAME=value NAME_2=value2 ... NAME_N=valueN [OPTIONS]
+shipengine-connect env:set API_URL=https://www.sandbox.example.com/api API_KEY=3435dfafa32424
 ```
 
-## Get Environment Variables
-This subcommand lists the current value for one or more environment variables.
-```bash
-shipengine-connect env:get NAME NAME_2 ... NAME_N [OPTIONS]
+Output:
+
+```
+API_URL=https://www.sandbox.example.com/api has been set
+API_KEY=3435dfafa32424 has been set
 ```
 
-## List Environment Variables
+### List Environment Variables
 This subcommand lists the values of all environment variables.
+
+`shipengine-connect env:list [OPTIONS]`
+
+Example:
+
+```bash
+shipengine-connect env:list
+```
+
+### Get Environment Variables
+This subcommand lists the current value for one or more environment variables.
+
+`shipengine-connect env:get NAME NAME_2 ... NAME_N [OPTIONS]`
+
+Example:
+
 ```bash
-shipengine-connect env:list [OPTIONS]
+shipengine-connect env:get API_URL
 ```
 
-## Unset Environment Variables
+### Unset Environment Variables
 This subcommand unsets one or more environment variables.
+
+`shipengine-connect env:unset NAME NAME_2 ... NAME_N [OPTIONS]`
+
+Example:
+
 ```bash
-shipengine-connect env:unset NAME NAME_2 ... NAME_N [OPTIONS]
+shipengine-connect env:unset API_URL
 ```
 
 ## Options
@@ -54,3 +83,22 @@ This option formats the output of the `shipengine-connect list` command. Set
 this option to `table` to list the environment variables in a table format or
 `dotenv` to list the environment variables in the
 [dotenv](https://www.npmjs.com/package/dotenv) format.
+
+## Recommendations
+
+### Single File
+We typically recommend having a single file in your project where you access your enviornment variables. This could be a `constants.ts` file, and we recommend having preset values that default to staging variables.
+
+**Example**
+
+```TypeScript constants.ts
+export const API_URL = process.env.API_URL ?? 'https://www.sandbox.example.com/api';
+```
+```TypeScript consumer.ts
+import { API_URL } from './constants'
+
+```
+
+### Moving to Production
+We recommend when reaching out to the [ShipEngine Connect Team](mailto:[email protected]) to have your application moved into our production systems, that you also notify them of any environment variables that will need to be set, and what their values should be in both testing and production environments.
+
diff --git a/fulfillment-provider/error-handling.md → getting-started/error-handling.md b/fulfillment-provider/error-handling.md → getting-started/error-handling.md
diff --git a/shipping/forms.md → getting-started/forms.md b/shipping/forms.md → getting-started/forms.md
@@ -8,7 +8,13 @@ title: Forms
 
 <embed src="../forms/_learning-more.md" />
 
-### Registration Form
+### Handling input in the `Register` method
+
+If you are building a `Carrier` app, you must implement a `Register` method to
+process the user input when a connection is created. Other types of apps do
+not currently support the `Register` method, however, all of the user input
+from the registration form is included in the `auth` part of the input in
+every function call to your app.
 
 Given the following definition for the JsonSchema
 ```JSON
@@ -27,12 +33,12 @@ Given the following definition for the JsonSchema
   }
 }
 ```
-When the button to connect is clicked by a user the [Register Method](../reference/operation/Register/) would recieve a payload looking something like this.
+When the "Connect" button is clicked by a user the [Register Method](/shipping/reference/operation/Register/) would receive a payload looking something like this:
 
 ```JSON Request Payload
 {
     "registration_info": {
-        "email": "test@gmail.com",
+        "email": "test@example.com",
         "password": "password",
         "CaseSensitive": true
     },
@@ -59,5 +65,7 @@ export const Register = async (request: RegisterRequest): Promise<RegisterRespon
 }
 ```
 :::warning Notice
-Notice how the interface for the `RegistrationForm` in the typescript code defined every feild as being potentially null given the `?`. This is because we did not mark any of these fields as required in our JsonSchema.
+Notice how the interface for the `RegistrationForm` in the typescript code
+defined every field as being potentially null given the `?`. This is because we
+did not mark any of these fields as required in our JsonSchema.
 :::
diff --git a/logging/_logging.md → getting-started/logging.md b/logging/_logging.md → getting-started/logging.md
@@ -1,13 +1,8 @@
-# Logging
-:::warning Avoid
-Avoid using the generic JavaScript logging or a custom logging solution.
-```JavaScript
-// There is no way to tie this to a customers transaction
-console.log('this will get lost easily');
-```
-:::
+# Logs
+
+
+The `@shipengine/connect-runtime` provides a wrapper for logging in the form of a `logger` object that can be imported into any file as demonstrated below:
 
-The `@shipengine/connect-runtime` provides a wrapper for logging in the form of a `logger` object that can be imported into any file demonstrated below.
 
 ```TypeScript
 import { logger } from '@shipengine/connect-runtime';
@@ -38,11 +33,20 @@ export const CreateLabel = async (
   // You can also log objects
   logger.info({
     response: ...some response payload,
-    message: 'recieved a response'
+    message: 'received a response'
   })
 };
 ```
 
+
+:::warning Avoid
+Avoid using `console.log` or a third-party logging solution that does not build
+upon the Connect runtime `logger`, as the log messages
+will not include the additional context provided by the Connect runtime.
+:::
+
 :::success Runtime Logger
-The runtime logger formats messages in a way that is easier to parse, and also appends information like transaction id's an other id's that help our support team get to the root of an issue when a customer recieves an error.
+The runtime logger formats messages in a way that is easier to parse, and also
+appends information like transaction identifiers that help our support
+team get to the root of an issue when a customer receives an error.
 :::
diff --git a/logging/index.md b/logging/index.md
diff --git a/orders/environment-variables.md b/orders/environment-variables.md
diff --git a/orders/error-handling.md b/orders/error-handling.md
diff --git a/orders/forms.md b/orders/forms.md
diff --git a/orders/logging.md b/orders/logging.md
diff --git a/shipping/environment-variables.md b/shipping/environment-variables.md
diff --git a/shipping/error-handling.md b/shipping/error-handling.md
diff --git a/shipping/logging.md b/shipping/logging.md