Various Connect docs updates

dannyroosevelt · dannyroosevelt · commit b019595a85d7 · 2024-12-14T15:01:18.000-08:00
diff --git a/docs-v2/pages/connect/_meta.tsx b/docs-v2/pages/connect/_meta.tsx
@@ -6,7 +6,7 @@ export default {
     "title": "Use cases",
   },
   "quickstart": {
-    "title": "Quickstart",
+    "title": "Managed auth",
   },
   "workflows": {
     "title": "Running workflows",
@@ -32,12 +32,12 @@ export default {
   "connect-link": {
     "title": "Connect Link",
   },
-  "troubleshooting": {
-    "title": "Troubleshooting",
-  },
   "customize-your-app": {
     "title": "Customize your app",
   },
+  "troubleshooting": {
+    "title": "Troubleshooting",
+  },
   "migrating-from-project-keys-to-oauth": {
     "display": "hidden",
   },
diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx
@@ -1,44 +1,35 @@
 import { Steps, Tabs } from 'nextra/components'
-import ArcadeEmbed from '@/components/ArcadeEmbed'
 import Callout from '@/components/Callout'
-import Image from 'next/image'
 
 # Running components for your end users
 
-Pipedream Connect provides you with the ability to pre-configure, deploy and
-invoke [components](/components) **on behalf of [your end
-users](/connect/api#external-users)**.
+Pipedream Connect provides APIs to embed [pre-built components](/components) directly in your application
+or AI agent, unlocking access to thousands of pre-built API operations. Enable [your end users](/connect/api#external-users) to
+configure, deploy, and invoke Pipedream triggers and actions for more than {process.env.PUBLIC_APPS} APIs.
 
 ## What are components?
 
-In the context of Pipedream Connect, components are self-contained executable
-units of code. They are usually provided with some arbitrary input and produce a
-result that's exported as output. These components are developed by the
-Pipedream community and their source code is available in our [public Github
-repository](https://github.com/PipedreamHQ/pipedream/tree/master/components).
-
-To learn more about components in detail, please visit our [Components
-guide](/components).
+In Pipedream, [components](/components) are self-contained executable units of code. Your end users configure the inputs and the components produce a
+result that's exported as output. These components are developed and maintained by Pipedream
+and our community and their source code is available in our [public Github repo](https://github.com/PipedreamHQ/pipedream/tree/master/components).
 
 <Callout type="info">
 Running components for your end users via Pipedream Connect is in **beta**, and we're looking for feedback. Please [let us know](https://pipedream.com/support) how you're using it, what's not working, and what else you'd like to see.
 </Callout>
 
-## How to run components for your end users
+## Getting stated
 
 <Callout type="info">
 Refer to the [Connect API docs](/connect/api) for the full API reference. Below is a quickstart with a few specific examples.
+
+You can skip steps 1 and 2 if you already know the component you want to use or if you'd prefer to [pass a natural language prompt to Pipedream's component search API](/rest-api#search-for-registry-components).
 </Callout>
 
 <Steps>
 
 ### Find the app you want to use
 
-<Callout type="info">
-You can also skip steps 1 and 2 if you already know the component you want to use or if you'd prefer to [pass a natural language prompt to Pipedream's component search API](/rest-api#search-for-registry-components).
-</Callout>
-
-In order to find the right trigger or action to configure and run, you first need to find the app. For this example, we'll search for `gitlab`.
+In order to find the right trigger or action to configure and run, you first need to find the app. In this example, we'll search for `gitlab`.
 
 ```text
 GET /v1/connect/apps?q=gitlab
@@ -145,7 +136,7 @@ Here's the response:
 ```
 ### Retrieve the component's definition
 
-In order to run a component for your end users, you need to understand
+To configure and run a component for your end users, you need to understand
 the component's definition. Now that you have the component's key from the previous step,
 you can retrieve its structure from the Pipedream API. See the [component
 structure](/components/api#component-structure) section in our docs for more
@@ -158,11 +149,10 @@ Commits** action for Gitlab:
 GET /v1/connect/components/gitlab-list-commits
 ```
 
-The response will contain the component's structure, including its
-(human-understandable) name, version, and most importantly, the configuration
-options that the component accepts (also known as [props](/components/api#props)
-or "properties"). Here's an example of the response for the component in the
-example above:
+The response will contain the component's structure, including its user-friendly name,
+version, and most importantly, the configuration options the component accepts
+(also known as [props](/components/api#props) or "properties").
+Here's an example of the response for the component in the example above:
 
 ```json
 {
@@ -213,9 +203,8 @@ Component execution on behalf of your end users requires a few preliminary
 steps, focused on getting the right input parameters (aka
 [props](/workflows/using-props)) to the component.
 
-Configuring each prop for a component usually involves an API call to our
-backend to retrieve the possible values, unless the values that a prop can take
-are static/free-form. The endpoint is accessible at:
+Configuring each prop for a component often involves an API call to retrieve the possible values,
+unless the values that a prop can take are static or free-form. The endpoint is accessible at:
 
 ```text
 POST /v1/connect/components/configure
@@ -224,7 +213,7 @@ POST /v1/connect/components/configure
 Typically, the options for a prop are linked to a specific user's account. Each
 of these props implements an `options` method that retrieves the necessary
 options from the third-party API, formats them, and sends them back in the
-response for the end user to select.
+response for the end user to select. Examples are listing Slack channels, Google Sheets, etc.
 
 The payload for the configuration API call must contain the following fields:
 
@@ -235,7 +224,7 @@ The payload for the configuration API call must contain the following fields:
    configured. The initial configuration call must contain the ID of the account
    (aka `authProvisionId`) that your user has connected to the target app (see
    [this section](workflows#configure-accounts-to-use-your-end-users-auth) for
-   more details on how to create these accounts)
+   more details on how to create these accounts).
 
 We'll use the [**List Commits** component for
 Gitlab](https://github.com/PipedreamHQ/pipedream/blob/master/components/gitlab/actions/list-commits/list-commits.mjs#L4)
@@ -344,7 +333,7 @@ For example, to retrieve the configuration options for the `refName` prop:
 
 ### Configure dynamic props (optional)
 
-The set of props that a component can accept might not be static, and can change
+The set of props that a component can accept might not be static, and may change
 depending on the values of prior props. Props that behave this way are called
 [dynamic props](/components/api#dynamic-props), and they need to be configured
 in a different way. Props that are dynamic will have a `reloadProps` attribute
@@ -361,7 +350,7 @@ The payload is similar to the one used for the configuration API, but it
 excludes the `prop_name` field since the goal of this call is to reload and
 retrieve the new set of props, not to configure a specific one.
 
-Using the **Add Single Row** component for Google Sheets as an example, the
+Using the [Add Single Row action for Google Sheets](https://pipedream.com/apps/google-sheets/actions/add-single-row) as an example, the
 request payload would look like this:
 
 ```json
@@ -455,7 +444,8 @@ Actions are components that perform a task by taking an input either during
 produce a result. Sources are very similar, but the difference is that they are
 not invoked directly by Pipedream users, but rather by events that happen on a
 third-party service. For example, the "New File" source for Google Drive will be
-triggered every time a new file is created in a specific folder in Google Drive.
+triggered every time a new file is created in a specific folder in Google Drive,
+then will emit an event for you to consume.
 
 All this means is that actions can be invoked manually on demand, while sources
 are instead deployed and run automatically when the event they are listening for
@@ -545,7 +535,7 @@ look something like this:
 
 ```json
 {
-  "external_user_id": "jverce",
+  "external_user_id": "demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9",
   "id": "gitlab-new-issue",
   "prop_name": "http",
   "configured_props": {
@@ -608,7 +598,7 @@ this:
         "type": "$.service.db"
       },
       "http": {
-        "endpoint_url": "https://39643dc2c8ff98a019f3fdc9078d6db9.m.pipedream.net"
+        "endpoint_url": "https://xxxxxxxxxx.m.pipedream.net"
       },
       "projectId": 45672541
     },
@@ -625,7 +615,7 @@ In the example above, the source ID is `dc_dAuGmW7`, which can be used to delete
 the source in the future:
 
 ```text
-DELETE /v1/connect/deployed-triggers/dc_dAuGmW7?external_user_id=jverce
+DELETE /v1/connect/deployed-triggers/dc_dAuGmW7?external_user_id=demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9
 ```
 
 </Steps>
diff --git a/docs-v2/pages/connect/environments.mdx b/docs-v2/pages/connect/environments.mdx
@@ -10,7 +10,7 @@ Pipedream customers on any plan can use all of the Connect features in `developm
 </Callout>
 
 
-## How to specify environment
+## How to specify the environment
 
 You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. When users succesfully connect their account, Pipedream saves the account credentials (API key, access token, etc) for that `external_user_id` in the specified environment.
 
@@ -41,7 +41,7 @@ curl -X POST https://api.pipedream.com/v1/connect/{project_id}/tokens \
 ```
 
 <Callout type="warning">
-When connecting an account in `development`, make sure you're signed in to pipedream.com in the same browser where you're connecting your account. This is only a requirement for the `development` environment. **You should only use the `development` environment with your own accounts when testing and developing, and not with your end users.**
+When connecting an account in `development`, make sure you're signed in to pipedream.com in the same browser where you're connecting your account. This is only a requirement for the `development` environment. **You should only use `development` with your own accounts when testing and developing, and not with your end users.**
 </Callout>
 
 <br />
diff --git a/docs-v2/pages/connect/index.mdx b/docs-v2/pages/connect/index.mdx
@@ -13,8 +13,8 @@ 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.
+3. [Run workflows](/connect/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. [Embed any Pipedream action or trigger](/connect/components) to run on behalf of your users, directly from within your application.
 
 <br />
 
@@ -61,7 +61,7 @@ So if user `abc-123` in your application connects their Slack account in `produc
 
 ## Plans and pricing
 
-**Connect is free to use for up to 1,000 connected accounts for any workspace**.
+**Managed authentication with Connect is free to use for up to 1,000 connected accounts for any workspace**. Check out our [pricing page](https://pipedream.com/pricing?plan=Enterprise) for details on running workflows and embedding components in your app.
 
 ## Security
 
diff --git a/docs-v2/pages/connect/quickstart.mdx b/docs-v2/pages/connect/quickstart.mdx
@@ -3,7 +3,7 @@ import { Steps, Tabs } from 'nextra/components'
 import Image from 'next/image'
 import VideoPlayer from "@/components/VideoPlayer";
 
-# Quickstart
+# Managed Auth Quickstart
 
 Pipedream Connect is the easiest way for your users to connect to [over {process.env.PUBLIC_APPS}+ APIs](https://pipedream.com/apps), **right in your product**. You can build in-app messaging, CRM syncs, AI agents, [and much more](/connect/use-cases), all in a few minutes.
 
@@ -94,7 +94,7 @@ Once you have a token, return it to your frontend to start the account connectio
 Refer to the API docs for [full set of parameters you can pass](/connect/api#create-a-new-token) in the `ConnectTokenCreate` call.
 </Callout>
 
-### Connect a user's account
+### Connect your user's account
 
 To connect a third-party account for a user, you have two options:
 
@@ -144,7 +144,7 @@ export default function Home() {
 
 Press that button to connect an account for the app you configured.
 
-#### Use Connect Link
+#### Or 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.
 
@@ -160,70 +160,17 @@ https://pipedream.com/_static/connect.html?token={token}&connectLink=true&app={a
 
 4. Redirect your users to this URL, or send it to them via email, SMS, and more.
 
-### Retrieve the credentials from the backend
+### Make authenticated requests
 
-Once your user connects an account, you can retrieve their credentials from your backend.
+Now that your users have connected an account, you can use their auth in one of a few ways:
 
-This example shows you how to fetch credentials by your end user's `external_user_id`. You can also fetch all connected accounts for a specific app, or a specific user — see the [Connect API reference](/connect/api).
-
-<Tabs items={['TypeScript', 'Node.js']}>
-<Tabs.Tab>
-```typescript
-import {
-  createBackendClient,
-} from "@pipedream/sdk/server";
-
-const pd = createBackendClient({
-  environment: "development", // change to production if running for a test production account, or in production
-  credentials: {
-    clientId: "{oauth_client_id}",
-    clientSecret: "{oauth_client_secret}",
-  },
-  projectId: "{your_project_id}"
-});
-
-async function getUserAccounts(external_user_id: string, include_credentials: boolean = false) {
-  await pd.getAccounts({
-    external_user_id,
-    include_credentials, // set to true to include credentials
-  })
-
-  // Parse and return the data you need. These may contain credentials, 
-  // which you should never return to the client
-}
-```
-</Tabs.Tab>
-<Tabs.Tab>
-```javascript
-import {
-  createBackendClient,
-} from "@pipedream/sdk/server";
-
-const pd = createBackendClient({
-  environment: "development", // change to production if running for a test production account, or in production
-  credentials: {
-    clientId: "{oauth_client_id}",
-    clientSecret: "{oauth_client_secret}",
-  },
-  projectId: "{your_project_id}"
-});
-
-async function getUserAccounts(external_user_id, include_credentials = false) {
-  await pd.getAccounts({
-    external_user_id,
-    include_credentials, // set to true to include credentials
-  })
-
-  // Parse and return the data you need. These may contain credentials, 
-  // which you should never return to the client
-}
-```
-</Tabs.Tab>
-</Tabs>
+1. [Retrieve their credentials from the REST API](/connect/api#accounts) to use in your backend application
+2. [Use Pipedream's visual workflow builder](/connect/workflows) to define complex logic to run on behalf of your users
+3. [Embed Pipedream components directly in your app](/connect/components) to run actions and triggers on their behalf
 
 ### 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.
+- Test end to end in [development](/connect/environments)
+- Ship to production!
 
 </Steps>
diff --git a/docs-v2/pages/connect/workflows.mdx b/docs-v2/pages/connect/workflows.mdx
@@ -30,7 +30,7 @@ Workflows also have built-in:
 
 Read [the quickstart](/quickstart/) to learn more.
 
-## How to run workflows for your end users
+## Getting started
 
 <Steps>
 
