Merge branch 'connect/workflow-sdk-docs' of github.com:PipedreamHQ/pipedream into connect/workflow-sdk-docs

Author: dylburger

docs-v2/pages/connect/api.mdx

@@ -104,7 +104,7 @@ export default function Home() {
 
 ## External users
 
-When you use the Connect API, you'll pass an `external_id` parameter when initiating account connections and retrieving credentials. This is your user's ID, in your system — whatever you use to uniquely identify them. 
+When you use the Connect API, you'll pass an `external_user_id` parameter when initiating account connections and retrieving credentials. This is your user's ID, in your system — whatever you use to uniquely identify them. 
 
 Pipedream associates this ID with user accounts, so you can retrieve credentials for a specific user, and invoke workflows on their behalf.
 
@@ -114,7 +114,7 @@ External IDs are limited to 250 characters.
 
 | API Endpoint               | Rate Limit                                           |
 |----------------------------|------------------------------------------------------|
-| `POST /tokens`   | 100 requests per minute per `external_id`            |
+| `POST /tokens`   | 100 requests per minute per `external_user_id`            |
 | `GET */accounts/*`| The sum of requests across all `*/accounts/*` endpoints must not exceed 100 requests per minute. This includes requests to `/accounts`, `/apps/:app_id/accounts`, `/accounts/:account_id`, and more — any request for account metadata and credentials is counted towards this total. |
 
 If you need higher rate limits, please [reach out](https://pipedream.com/support).
@@ -722,7 +722,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{project_id}/accounts/{account
 Retrieve the account details for a specific account based on the external user ID
 
 ```
-GET /{project_id}/users/{external_id}/accounts
+GET /{project_id}/users/{external_user_id}/accounts
 ```
 
 ##### Path parameters
@@ -733,7 +733,7 @@ GET /{project_id}/users/{external_id}/accounts
 
 ---
 
-`external_id` **string**
+`external_user_id` **string**
 
 [The external user ID](#external-users) in your system that you want to retrieve accounts for.
 
@@ -1095,7 +1095,7 @@ Pipedream returns a `204 No Content` response on successful account deletion
 Delete an end user and all their connected accounts
 
 ```
-DELETE /{project_id}/users/{external_id}
+DELETE /{project_id}/users/{external_user_id}
 ```
 
 ##### Path parameters
@@ -1106,7 +1106,7 @@ DELETE /{project_id}/users/{external_id}
 
 ---
 
-`external_id` **string**
+`external_user_id` **string**
 
 [The external user ID](#external-users) in your system
 
@@ -1162,7 +1162,7 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \
 
 # The response will include an access_token. Use it in the Authorization header below.
 
-curl -X DELETE "https://api.pipedream.com/v1/connect/{project_id}/users/{external_id}" \
+curl -X DELETE "https://api.pipedream.com/v1/connect/{project_id}/users/{external_user_id}" \
   -H "Authorization: Bearer {access_token}"
 ```
 </Tabs.Tab>

docs-v2/pages/connect/environments.mdx

@@ -2,7 +2,7 @@
 
 Pipedream Connect projects support two environments: `development` and `production`.
 
-1. Credentials stored in `development` remain separate from `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

docs-v2/pages/connect/index.mdx

@@ -6,7 +6,7 @@ import VideoPlayer from "@/components/VideoPlayer";
 # Pipedream Connect
 
 <Callout type="info">
-**Pipedream Connect is currently in preview, and we're looking for design partners to pair with us on the product roadmap and provide feedback**. If you're building apps, AI agents, or anything else that needs to integrate with many third-party APIs, please reach out at `[email protected]` or our [Slack community](https://pipedream.com/support)
+**Pipedream Connect is currently in preview, and we're looking for design partners to pair with us on the product roadmap and provide feedback**. If you're building apps, AI agents, or anything else that needs to integrate with many third-party APIs, please reach out at `[email protected]` or in our [Slack community](https://pipedream.com/support).
 
 During the preview phase, Connect is free to use for any workspace. The API may change without notice, which may cause breaking changes. We'll do our best to communicate these changes. Please let us know how you're using it, what's not working, and what else you'd like to see.
 </Callout>
@@ -20,6 +20,7 @@ Connect lets you:
 1. Handle authorization or accept API keys on behalf of your users, for any of Pipedream's [{process.env.PUBLIC_APPS}+ APIs](https://pipedream.com/apps). Use the [Client SDK](https://github.com/PipedreamHQ/pipedream/tree/master/packages/sdk) or [Connect Link](/connect/quickstart#use-connect-link) to accept auth in minutes.
 2. Securely retrieve OAuth access tokens, API keys, and other credentials for your end users with Pipedream's [REST API](/connect/api)
 3. Run workflows for your end users with Pipedream's [workflow builder](/workflows), [serverless runtime](/), and thousands of no-code [triggers](/workflows/triggers) and [actions](/workflows/actions). Build complex integrations in minutes, writing code when you need it and using no-code components when you don't. Pipedream workflows are easy to modify, debug, and scale.
+4. Run [any Pipedream action](https://pipedream.com/explore) or [deploy any Pipedream trigger](https://pipedream.com/explore) on behalf of your users, directly from within your application.
 
 <br />
 
@@ -61,12 +62,6 @@ All credentials and tokens are sent to Pipedream securely over HTTPS, and encryp
 - **Use secure, session-based auth between your client and server** — authorize all requests from your client to your server using a secure, session-based auth mechanism. Use well-known identity providers with services like [Clerk](https://clerk.com/), [Firebase](https://firebase.google.com/), or [Auth0](https://auth0.com/) to securely generate and validate authentication tokens. The same follows for Pipedream workflows — if you trigger Pipedream workflows from your client or server, validate all requests in the workflow before executing workflow code.
 - **Secure your workflows** — See our [standard security practices](/privacy-and-security/best-practices) for recommendations on securing your Pipedream workflows.
 
-## Product roadmap for Connect
-
-- Address bugs and feedback during the preview phase
-- Invoke Pipedream workflows on behalf of your end users
-- And more!
-
 ## Glossary of terms
 
 - **App**: GitHub, Notion, Slack, Google Sheets, and more. The app is the API you want your users to connect to in your product. See the [full list here](https://pipedream.com/apps).

docs-v2/pages/connect/quickstart.mdx

@@ -35,7 +35,11 @@ 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):**
+**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 for the app you're integrating.
+</Callout>
 
 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.
@@ -44,7 +48,7 @@ There are two types of apps in Pipedream:
 
 Pipedream uses OAuth to authorize requests to the REST API. To create an OAuth application:
 
-1. Visit your workspace's [API settings](https://pipedream.com/settings/api).
+1. Visit the [API settings](https://pipedream.com/settings/api) for your workspace.
 2. Click the **New OAuth App** button.
 3. Name your app and click **Create**.
 4. Copy the app's client secret. **It will not be accessible again**. Click **Close**.
@@ -61,7 +65,7 @@ You'll need to do two things to add Pipedream Connect to your app:
 
 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>
+<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>
 
@@ -81,16 +85,9 @@ PIPEDREAM_OAUTH_CLIENT_SECRET=your_client_secret
 
 If you're building your own app, you'll need to provide these values to the environment, or retrieve them from your secrets store.
 
-### Generate a token or Connect Link URL for your end users
-
-To securely initiate account connections for your users, you'll need to either:
-
-1. [Generate a short-lived token](#generate-a-token) for your users and return that to your frontend, passing that to the account connection flow. 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.
-2. Redirect your users to [a Pipedream-hosted URL](#use-connect-link), which handles the account connection flow for you. Use this option when you can't execute JavaScript in your environment (e.g. mobile apps), or when you want to offload the account connection flow to Pipedream. You can also send these links in email or SMS.
-
-#### Generate a token
+### Generate a short-lived token
 
-See [the docs on Connect tokens](/connect/tokens) for a general overview of why we need to create tokens and scope them to end users.
+To securely initiate account connections for your users, you'll need generate a short-lived token for your users and use that in the [account connection flow](#connect-a-users-account). See [the docs on Connect tokens](/connect/tokens) for a general overview of why we need to create tokens and scope them to end users.
 
 In the Next.js example here, we're running [Next server components](https://nextjs.org/docs/app/building-your-application/rendering/server-components) in `app/server.ts`. We call the `serverConnectTokenCreate` method from the frontend to retrieve a token **for a specific user**.
 
@@ -104,26 +101,11 @@ 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.
 
-Once you have a token, return it to your frontend to start the account connection flow for the user, or redirect them to a Pipedream-hosted URL with [Connect Link](#using-connect-link).
-
-#### Use Connect Link
-
-Connect Link lets you connect third-party accounts without any frontend implementation in your app.
-
-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.
+Once you have a token, return it to your frontend to start the account connection flow for the user, or redirect them to a Pipedream-hosted URL with [Connect Link](#use-connect-link).
 
-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}
-```
-
-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)
+<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
 
@@ -134,6 +116,8 @@ To connect a third-party account for a user, you have two options:
 
 #### 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
@@ -173,6 +157,22 @@ export default function Home() {
 
 Press that button to connect an account for the app you configured.
 
+#### Use Connect Link
+
+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}
+```
+
+4. Redirect your users to this URL, or send it to them via email, SMS, and more.
+
 ### Retrieve the credentials from the backend
 
 Once your user connects an account, you can retrieve their credentials from your backend.

docs-v2/pages/workflows/triggers.mdx

@@ -115,6 +115,8 @@ To configure a static, custom token for HTTP auth:
 2. Select **Custom token**.
 3. Enter whatever secret you'd like and click **Save and Continue**.
 
+![Custom token auth](https://res.cloudinary.com/pipedreamin/image/upload/v1729791152/Google_Chrome_-_Untitled_Workflow_-_10-24-2024_10-30_AM_-_Build_-_Pipedream_2024-10-24_at_10.31.01_AM_pkh8dk.png)
+
 When making HTTP requests, pass the custom token as a `Bearer` token in the `Authorization` header:
 
 ```bash
@@ -129,6 +131,8 @@ You can also authorize requests using [Pipedream OAuth clients](/rest-api/auth#o
 2. Select **OAuth**.
 3. If you don't have an existing OAuth client, [create one in your workspace's API settings](/rest-api/auth#creating-an-oauth-application).
 
+![OAuth authorization](https://res.cloudinary.com/pipedreamin/image/upload/v1729791415/Google_Chrome_-_Untitled_Workflow_-_10-24-2024_10-30_AM_-_Build_-_Pipedream_2024-10-24_at_10.36.04_AM_ujx34e.png)
+
 Next, you'll need to [generate an OAuth access token](/rest-api/auth#how-to-get-an-access-token).
 
 When making HTTP requests, pass the OAuth access token as a `Bearer` token in the `Authorization` header: