cherry picked changes from new docs

dannyroosevelt · dannyroosevelt · commit ac6366e03460 · 2024-10-30T21:53:17.000-07:00
diff --git a/docs-v2/pages/connect/_meta.json b/docs-v2/pages/connect/_meta.json
@@ -10,5 +10,20 @@
   },
   "api": {
     "title": "API & SDK Reference"
+  },
+  "tokens": {
+    "title": "Connect tokens"
+  },
+  "environments": {
+    "title": "Environments"
+  },
+  "oauth-clients": {
+    "title": "OAuth Clients"
+  },
+  "webhooks": {
+    "title": "Webhooks"
+  },
+  "connect-link": {
+    "title": "Connect Link"
   }
 }
diff --git a/docs-v2/pages/connect/connect-link.mdx b/docs-v2/pages/connect/connect-link.mdx
@@ -0,0 +1,32 @@
+# Connect Link
+
+Connect Link provides a Pipedream-hosted link that lets you connect third-party accounts without any frontend implementation in your app.
+
+## When to use Connect Link
+
+If you aren't able to execute JavaScript or open an iFrame in your frontend, or you want to send users a URL to connect accounts via email or SMS, use Connect Link. That URL opens a Pipedream-hosted page that guides the user through the account connection flow. The URL is scoped to the specific end user, and expires after 4 hours.
+
+## How to generate a link
+
+See [the Connect quickstart](/connect/quickstart) for a full tutorial for getting Connect up and running. 
+
+Here's a quick overview of how to generate a Connect Link URL:
+
+1. First, [generate a token](/connect/quickstart/#generate-a-token) for your users.
+2. Extract the `connect_link_url` from the token response.
+3. Before returning the URL to your user, add an `app` parameter to the end of the query string:
+
+```
+https://pipedream.com/_static/connect.html?token={token}&connectLink=true&app={appSlug}
+```
+
+4. Redirect your users to this URL, or send it to them via email, SMS, and more.
+
+**To test this code, check out this workflow:**
+[https://pipedream.com/new?h=tch_EvfbvQ](https://pipedream.com/new?h=tch_EvfbvQ)
+
+## Success and error redirect URLs
+
+When you [generate a Connect link](/connect/quickstart/#how-to-generate-a-link), you can specify `success_redirect_url` and `error_redirect_url` parameters. Pipedream will redirect the end user to these URLs after they complete the connection flow, or if an error occurs. [See the API docs](/connect/api#create-a-new-token) for details.
+
+In the absence of these URLs, Pipedream will redirect the user to a Pipedream-hosted success or error page at the end of the connection flow.
diff --git a/docs-v2/pages/connect/environments.mdx b/docs-v2/pages/connect/environments.mdx
@@ -0,0 +1,10 @@
+# Environments
+
+Pipedream Connect projects support two environments: `development` and `production`.
+
+1. Connected accounts and credentials stored in `development` remain separate from `production`.
+2. In `development`, you can use the official Pipedream OAuth apps, so you can test integrations without creating your own OAuth client.
+
+## How to specify environment
+
+You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the enviromment is set to `production`. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `project_environment`.
diff --git a/docs-v2/pages/connect/oauth-clients.mdx b/docs-v2/pages/connect/oauth-clients.mdx
@@ -0,0 +1,35 @@
+import Image from 'next/image'
+import Callout from '@/components/Callout'
+
+# OAuth Clients
+
+When connecting an account for any OAuth app via Pipedream Connect, we'll default to using Pipedream's official OAuth client, which enables you to quickly get up and running. [Read more about OAuth clients in Pipedream here](/connected-accounts/oauth-clients).
+
+## Using Pipedream OAuth
+
+There are two types of apps in Pipedream:
+
+1. **Key-based**: These apps require static credentials, like API keys. Pipedream stores these credentials securely and exposes them via API.
+2. **OAuth**: These apps require OAuth authorization. Pipedream manages the OAuth flow for these apps, ensuring you always have a fresh access token for requests.
+
+**OAuth apps require you create your own OAuth client to [deploy to production](/connect/environments):**
+
+<Callout type="info">
+To get started in [development mode](/connect/environments), you can skip these steps. To deploy your app to production, you'll need to [create an OAuth client](#using-a-custom-oauth-client) for the app you're integrating.
+</Callout>
+
+## Using a custom OAuth client
+
+1. Follow the steps [here](/connected-accounts/oauth-clients#configuring-custom-oauth-clients) to create an OAuth client in Pipedream.
+2. Open the **Apps** tab within your Pipedream project and select **Add app**.
+3. Select the app you're looking for, then select your OAuth client from the dropdown menu.
+4. When connecting an account either via the [frontend SDK](/connect/quickstart#use-the-pipedream-sdk-in-your-frontend), make sure to include the `oauth_app_id` in `pd.connectAccount()`.
+5. If using [Connect Link](/connect/quickstart#use-connect-link), make sure to include the `oauth_app_id` in the URL.
+
+### Finding your OAuth app ID
+
+[Create your OAuth client in Pipedream](https://pipedream.com/@/accounts/oauth-clients) then click the arrow to the left of the client name to expand the details.
+
+<br />
+
+<Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1730241292/oauth-app-id_umhhqi.png" alt="Copy OAuth App ID" width={650} height={529} />
diff --git a/docs-v2/pages/connect/quickstart.mdx b/docs-v2/pages/connect/quickstart.mdx
@@ -21,24 +21,10 @@ And here's the technical flow between your frontend, backend, and Pipedream's AP
 
 <Steps>
 
-### Add the apps you want to integrate
-
-1. Open an existing Pipedream project or create a new one at [https://pipedream.com/projects](https://pipedream.com/projects).
-2. Click the **Connect** tab, then select **Apps**.
-3. From here, you can add any app to your project that you want to integrate with your application.
-
-There are two types of apps in Pipedream:
-
-1. **Key-based**: These apps require static credentials, like API keys. Pipedream stores these credentials securely and exposes them via API.
-2. **OAuth**: These apps require OAuth authorization. Pipedream manages the OAuth flow for these apps, ensuring you always have a fresh access token for requests.
-
-**OAuth apps require you [create your own OAuth client](#creating-a-custom-oauth-client):**
-1. First, [create an OAuth client](/connected-accounts/oauth-clients#configuring-custom-oauth-clients) for the app you'd like to integrate.
-2. Now when selecting an OAuth app in the **Apps** tab, you'll be prompted to select the OAuth client you've created.
-
 ### Get your project keys
 
-1. From within the the **Connect** tab in your project, select **Configuration**.
+1. Open an existing Pipedream project or create a new one at [https://pipedream.com/projects](https://pipedream.com/projects).
+2. From within the the **Connect** tab in your project, select **Configuration**.
 3. Find your project's **Public Key** and **Secret Key**.
 
 You'll need these when configuring the SDK and making API requests.
@@ -47,15 +33,19 @@ You'll need these when configuring the SDK and making API requests.
 
 <Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1724773559/connect-keys_cb4ujt.png" alt="Project keys in the Connect tab" width={650} height={300} />
 
-### Run the Pipedream demo app or configure your own
+### Run the Pipedream example app or configure your own
 
-You'll need to do two things to integrate Pipedream Connect into your app:
+You'll need to do two things to add Pipedream Connect to your app:
 
-1. [Connect to the Pipedream API from your server](#connect-to-the-pipedream-api-from-your-server-and-create-a-token). This lets you make secure calls to the Pipedream API to initiate the account connection flow and retrieve account credentials. If you're running a JavaScript framework like Node.js on the server, you can use the Pipedream SDK.
-2. [Add the Pipedream SDK to your frontend](#connect-your-account-from-the-frontend) or deliver a URL to your users to start the account connection flow.
+1. [Connect to the Pipedream API from your server](#connect-to-the-pipedream-api-from-your-server-and-create-a-token). This lets you make secure calls to the Pipedream API to initiate the account connection flow and retrieve account credentials. If you're running a JavaScript framework like Node.js on your server, you can use the Pipedream SDK.
+2. [Add the Pipedream SDK to your frontend](#connect-your-account-from-the-frontend) or redirect your users to [a Pipedream-hosted URL](/connect/connect-link) to start the account connection flow.
 
 We'll walk through these steps below, using [an example Next.js app](https://github.com/PipedreamHQ/pipedream-connect-examples/tree/master/next-app/). To follow along, clone [the repo](https://github.com/PipedreamHQ/pipedream-connect-examples/) and follow the instructions in [the app's `README`](https://github.com/PipedreamHQ/pipedream-connect-examples/tree/master/next-app/). That will run the app on `localhost:3000`.
 
+<Callout type="info">
+The Next.js app is just an example. You can build Connect apps in any framework, using any language. We've provided examples in Python, Ruby, and others below.
+</Callout>
+
 First, copy the `.env.example` file to `.env.local`:
 
 ```bash
@@ -521,20 +511,28 @@ const { token, expires_at } = await serverConnectTokenCreate({
 
 If you're using a different server / API framework, you'll need to make secure calls to that API to create a new token for your users. For example, you might validate a user's session, then call the Pipedream API to create a new token for that user.
 
-### Connect your account
+<Callout type="info">
+Refer to the API docs for [all the parameters you can pass](/connect/api#create-a-new-token) in the `ConnectTokenCreate` call.
+</Callout>
+
+### Connect a user's account
+
+To connect a third-party account for a user, you have two options:
 
-To actually connect an account, you have two options:
 1. [Use the Pipedream SDK](#use-the-pipedream-sdk-in-your-frontend) in your frontend
-2. [Use Connect Link](#use-connect-link) to deliver a hosted URL to your user
+2. [Use Connect Link](#use-connect-link) to deliver a hosted URL to your user (see above).
 
 #### Use the Pipedream SDK in your frontend
+
+Use this method when you want to handle the account connection flow yourself, in your app. For example, you might want to show a **Connect Slack** button in your app that triggers the account connection flow.
+
 First, install the [Pipedream SDK](https://www.npmjs.com/package/@pipedream/sdk) in your frontend:
 
 ```bash
 npm i --save @pipedream/sdk
 ```
 
-When the user connects an account in your product, [fetch a token from your backend](#connect-to-the-pipedream-api-from-your-server-and-create-a-token) and call `connectAccount`. This opens a Pipedream iFrame that guides the user through the account connection.
+When the user connects an account in your product, [pass the token from your backend](#connect-to-the-pipedream-api-from-your-server-and-create-a-token) and call `connectAccount`. This opens a Pipedream iFrame that guides the user through the account connection.
 
 In our example, `app/page.tsx` calls the `connectAccount` method from the Pipedream SDK when the user clicks the **Connect your account** button.
 
@@ -549,7 +547,8 @@ export default function Home() {
   const pd = createClient()
   function connectAccount() {
     pd.connectAccount({
-      app: process.env.NEXT_PUBLIC_PIPEDREAM_APP_SLUG, // From the Next.js example — adjust to pass your own app name slug
+      app: appSlug, // Pass the app name slug of the app you want to integrate
+      oauthAppId: appId, // For OAuth apps, pass the OAuth app ID; omit this param to use Pipedream's OAuth client or for key-based apps
       token: "YOUR_TOKEN", // The token you received from your server above
       onSuccess: ({ id: accountId }) => {
         console.log(`Account successfully connected: ${accountId}`)
@@ -559,7 +558,7 @@ export default function Home() {
 
   return (
     <main>
-      <button style={{ all: "revert" }} onClick={connectAccount}>Connect your account</button>
+      <button onClick={connectAccount}>Connect your account</button>
     </main>
   )
 }
@@ -568,17 +567,20 @@ export default function Home() {
 Press that button to connect an account for the app you configured.
 
 #### Use Connect Link
-- Avoid any frontend implementation
-- If you aren't able to execute JavaScript or open an iFrame in your frontend, you can use the `connect_link_url` that's returned from the `connectTokenCreate` method to deliver a URL to your users.
-- Before returning the URL to your user, you'll need to include the `app` on the URL. For example, see below.
-- Users can open this URL in a browser window to connect their account.
+
+Use this option when you can't execute JavaScript or open an iFrame in your environment (e.g. mobile apps), or when you want to offload the account connection flow to Pipedream and avoid frontend work. You can also send these links via email or SMS.
+
+The Connect Link opens a Pipedream-hosted page, guiding users through the account connection process. The URL is specific to the user and expires after 4 hours.
+
+1. First, [generate a token](#generate-a-token) for your users.
+2. Extract the `connect_link_url` from the token response.
+3. Before returning the URL to your user, add an `app` parameter to the end of the query string:
 
 ```
-https://pipedream.com/_static/connect.html?token={token}&connectLink=true&app={appSlug}
+https://pipedream.com/_static/connect.html?token={token}&connectLink=true&app={appSlug}&oauthAppId={oauthAppId}
 ```
 
-**To test this code, check out this workflow:**
-[https://pipedream.com/new?h=tch_EvfbvQ](https://pipedream.com/new?h=tch_EvfbvQ)
+4. Redirect your users to this URL, or send it to them via email, SMS, and more.
 
 ### Retrieve the credentials from the backend
 
@@ -971,6 +973,7 @@ response = client.get_user_accounts('USER_ID')
 
 ### Deploy your app to production
 
-Now that you've successfully connected an account and retrieved the credentials, you're ready to deploy your app to production!
+- Now that you've successfully connected an account and retrieved the credentials, you're almost done!
+- Learn about [development environments](/connect/environments) and [using OAuth clients](/connect/oauth-clients) to deploy your app to production.
 
 </Steps>
diff --git a/docs-v2/pages/connect/tokens.mdx b/docs-v2/pages/connect/tokens.mdx
@@ -0,0 +1,26 @@
+# Connect tokens
+
+When you initiate account connection for your end users, you must either:
+
+1. Generate a secure, short-lived token scoped to the end user, or
+2. Use the [Connect Link](/connect/connect-link) feature to generate a URL that guides the user through the account connection flow without any frontend work on your side.
+
+Here, we'll show you how to generate tokens for your users and return that to your frontend, passing that to the account connection flow. 
+
+Use tokens when you want to handle the account connection flow yourself, in your app's UI. For example, you might want to show a **Connect Slack** button in your app that triggers the account connection flow for Slack, or launch the flow in a modal.
+
+## Creating a token
+
+See docs on [the `/tokens` endpoint](/connect/api/#create-a-new-token) to create new tokens.
+
+## Webhooks
+
+When you generate a token, you can specify a `webhook_uri` where Pipedream will deliver updates on the account connection flow. This is useful if you want to update your UI based on the status of the account connection flow, get a log of errors, and more. 
+
+[See the webhooks docs](/connect/webhooks) for more information.
+
+## Tokens are scoped to end users and project environments
+
+When you [create a new Connect token](/connect/api/#create-a-new-token), you pass an `external_user_id` and an optional `project_environment` parameter. By default, the enviromment is set to `production`. 
+
+Tokens are scoped to this user and environment. When the user successfully connects an account with that token, it will be saved for that `external_user_id` in the specified `project_environment`.
diff --git a/docs-v2/pages/connect/webhooks.mdx b/docs-v2/pages/connect/webhooks.mdx
@@ -0,0 +1,54 @@
+# Connect Webhooks
+
+When you [generate a Connect token](/connect/quickstart/#generate-a-token), you can pass a `webhook_uri` parameter. Pipedream will send a POST request to this URL when the user completes the connection flow, or if an error occurs at any point. [See the API docs](/connect/api#create-a-new-token) for details.
+
+## Webhook events
+
+- `CONNECTION_SUCCESS` - Sent when the user successfully connects their account
+- `CONNECTION_ERROR` - Sent when an error occurs during the connection flow
+
+## Webhook payload
+
+### Successful connection
+
+Please note that user credentials are not sent in the webhook request. To retrieve credentials, use the [Connect API to fetch the account](/connect/api#retrieve-account-details-by-id) using the `account.id` provided in the webhook payload.
+
+```json
+{
+  "event": "CONNECTION_SUCCESS",
+  "connect_token": "abc123",
+  "environment": "production",
+  "connect_session_id": 123,
+  "account": {
+    "id": "apn_abc123",
+    "name": "My Slack workspace",
+    "external_id": "U123456",
+    "healthy": true,
+    "dead": false,
+    "app": {
+      "id": "app_abc123",
+      "name_slug": "slack",
+      "name": "Slack",
+      "auth_type": "oauth",
+      "description": "Slack is a channel-based messaging platform",
+      "img_src": "https://assets.pipedream.net/icons/slack.svg",
+      "custom_fields_json": [],
+      "categories": "Communication",
+    },
+    "created_at": "2021-09-01T00:00:00Z",
+    "updated_at": "2021-09-01T00:00:00Z",
+  }
+}
+```
+
+### Error
+
+```json
+{
+  "event": "CONNECTION_ERROR",
+  "connect_token": "abc123",
+  "environment": "production",
+  "connect_session_id": 123,
+  "error": "You've hit your limit on the number of external users you can connect."
+}
+```
