docs: make hosted Companion more clear (#5394)

docs/companion.md

@@ -67,6 +67,42 @@ files to arrive at Transloadit servers, much like Uppy.
 
 :::
 
+To do so each provider plugin must be configured with Transloadit’s Companion
+URLs:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Dropbox from '@uppy/dropbox';
+
+uppy.use(Dropbox, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Dropbox from '@uppy/dropbox';
+
+uppy.use(Dropbox, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ## Installation & use
 
 Companion is installed from npm. Depending on how you want to run Companion, the
@@ -949,3 +985,5 @@ automatically restart when files are changed.
 [url]: /docs/url
 [zoom]: /docs/zoom
 [transloadit]: https://transloadit.com
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials

docs/sources/companion-plugins/box.mdx

@@ -81,6 +81,41 @@ new Uppy()
 	.use(Box, { companionUrl: 'https://your-companion.com' });
 ```
 
+### Use with Transloadit
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Box from '@uppy/box';
+
+uppy.use(Box, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Box from '@uppy/box';
+
+uppy.use(Box, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ### Use in Companion
 
 You can create a Box App on the
@@ -186,3 +221,6 @@ export default {
 	},
 };
 ```
+
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials

docs/sources/companion-plugins/dropbox.mdx

@@ -81,6 +81,41 @@ new Uppy()
 	.use(Dropbox, { companionUrl: 'https://your-companion.com' });
 ```
 
+### Use with Transloadit
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Dropbox from '@uppy/dropbox';
+
+uppy.use(Dropbox, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Dropbox from '@uppy/dropbox';
+
+uppy.use(Dropbox, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ### Use in Companion
 
 You can create a Dropbox App on the
@@ -186,3 +221,6 @@ export default {
 	},
 };
 ```
+
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials

docs/sources/companion-plugins/facebook.mdx

@@ -81,6 +81,41 @@ new Uppy()
 	.use(Facebook, { companionUrl: 'https://your-companion.com' });
 ```
 
+### Use with Transloadit
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Facebook from '@uppy/facebook';
+
+uppy.use(Facebook, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Facebook from '@uppy/facebook';
+
+uppy.use(Facebook, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ### Use in Companion
 
 You can create a Facebook App on the
@@ -183,3 +218,6 @@ export default {
 	},
 };
 ```
+
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials

docs/sources/companion-plugins/google-drive.mdx

@@ -81,6 +81,41 @@ new Uppy()
 	.use(GoogleDrive, { companionUrl: 'https://your-companion.com' });
 ```
 
+### Use with Transloadit
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import GoogleDrive from '@uppy/google-drive';
+
+uppy.use(GoogleDrive, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import GoogleDrive from '@uppy/google-drive';
+
+uppy.use(GoogleDrive, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ### Use in Companion
 
 To sign up for API keys, go to the
@@ -187,3 +222,6 @@ export default {
 	},
 };
 ```
+
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials

docs/sources/companion-plugins/google-photos.mdx

@@ -84,6 +84,41 @@ new Uppy()
 	});
 ```
 
+### Use with Transloadit
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import GooglePhotos from '@uppy/google-photos';
+
+uppy.use(GooglePhotos, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import GooglePhotos from '@uppy/google-photos';
+
+uppy.use(GooglePhotos, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ### Use in Companion
 
 To sign up for API keys, go to the
@@ -183,3 +218,6 @@ export default {
 	},
 };
 ```
+
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials

docs/sources/companion-plugins/instagram.mdx

@@ -81,6 +81,41 @@ new Uppy()
 	.use(Instagram, { companionUrl: 'https://your-companion.com' });
 ```
 
+### Use with Transloadit
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Instagram from '@uppy/instagram';
+
+uppy.use(Instagram, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Instagram from '@uppy/instagram';
+
+uppy.use(Instagram, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ### Use in Companion
 
 To sign up for API keys, go to the
@@ -196,3 +231,6 @@ export default {
 	},
 };
 ```
+
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials

docs/sources/companion-plugins/onedrive.mdx

@@ -81,6 +81,41 @@ new Uppy()
 	.use(OneDrive, { companionUrl: 'https://your-companion.com' });
 ```
 
+### Use with Transloadit
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import OneDrive from '@uppy/onedrive';
+
+uppy.use(OneDrive, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import OneDrive from '@uppy/onedrive';
+
+uppy.use(OneDrive, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ### Use in Companion
 
 To sign up for API keys, go to the
@@ -100,15 +135,14 @@ If you are using Transloadit hosted Companion:
 https://api2.transloadit.com/companion/onedrive/redirect
 ```
 
-Go to the “Manifest” tab, and find the `"signInAudience"` key.  
-Change it to `"signInAudience": "AzureADandPersonalMicrosoftAccount"`, and click
-“Save”.
+Go to the “Manifest” tab, and find the `"signInAudience"` key. Change it to
+`"signInAudience": "AzureADandPersonalMicrosoftAccount"`, and click “Save”.
 
-Go to the “Overview” tab.  
-Copy the `Application (client) ID` field - this will be your Oauth client ID.
+Go to the “Overview” tab. Copy the `Application (client) ID` field - this will
+be your Oauth client ID.
 
-Go to the “Certificates & secrets” tab, and click “+ New client secret”.  
-Copy the `Value` field - this will be your OAuth client secret.
+Go to the “Certificates & secrets” tab, and click “+ New client secret”. Copy
+the `Value` field - this will be your OAuth client secret.
 
 Configure the OneDrive key and secret in Companion. With the standalone
 Companion server, specify environment variables:
@@ -185,3 +219,6 @@ export default {
 	},
 };
 ```
+
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials

docs/sources/companion-plugins/unsplash.mdx

@@ -81,6 +81,41 @@ new Uppy()
 	.use(Unsplash, { companionUrl: 'https://your-companion.com' });
 ```
 
+### Use with Transloadit
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Unsplash from '@uppy/unsplash';
+
+uppy.use(Unsplash, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Unsplash from '@uppy/unsplash';
+
+uppy.use(Unsplash, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ### Use in Companion
 
 You can create a Unsplash App on the
@@ -162,3 +197,6 @@ export default {
 	},
 };
 ```
+
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials

docs/sources/companion-plugins/url.mdx

@@ -89,6 +89,41 @@ new Uppy()
 	.use(Url, { companionUrl: 'https://your-companion.com' });
 ```
 
+### Use with Transloadit
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Url from '@uppy/url';
+
+uppy.use(Url, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Url from '@uppy/url';
+
+uppy.use(Url, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ### Use in Companion
 
 Companion supports this plugin out-of-the-box, however it must be enabled in
@@ -148,3 +183,6 @@ export default {
 	},
 };
 ```
+
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials

docs/sources/companion-plugins/zoom.mdx

@@ -84,6 +84,41 @@ new Uppy()
 	.use(Zoom, { companionUrl: 'https://your-companion.com' });
 ```
 
+### Use with Transloadit
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Zoom from '@uppy/zoom';
+
+uppy.use(Zoom, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+});
+```
+
+You may also hit rate limits, because the OAuth application is shared between
+everyone using Transloadit.
+
+To solve that, you can use your own OAuth keys with Transloadit’s hosted
+Companion servers by using Transloadit Template Credentials. [Create a Template
+Credential][template-credentials] on the Transloadit site. Select “Companion
+OAuth” for the service, and enter the key and secret for the provider you want
+to use. Then you can pass the name of the new credentials to that provider:
+
+```js
+import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
+import Zoom from '@uppy/zoom';
+
+uppy.use(Zoom, {
+	companionUrl: COMPANION_URL,
+	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
+	companionKeysParams: {
+		key: 'YOUR_TRANSLOADIT_API_KEY',
+		credentialsName: 'my_companion_dropbox_creds',
+	},
+});
+```
+
 ### Use in Companion
 
 To sign up for API keys, go through the following steps:
@@ -187,3 +222,6 @@ export default {
 	},
 };
 ```
+
+[template-credentials]:
+	https://transloadit.com/docs/#how-to-create-template-credentials