Adding SDK examples to components API docs

Author: dannyroosevelt

docs-v2/pages/connect/api-proxy.mdx

@@ -1,4 +1,3 @@
-import { Tabs } from 'nextra/components'
 import Callout from '@/components/Callout'
 
 # Connect API Proxy

docs-v2/pages/connect/components.mdx

@@ -38,13 +38,68 @@ You can skip steps 1 and 2 if you already know the component you want to use or
 
 <Steps>
 
+### Authenticate to the Pipedream API
+
+Before sending requests to the API, make sure to authenticate using a Pipedream OAuth client:
+
+<Tabs items={['Node.js', 'HTTP (cURL)']}>
+<Tabs.Tab>
+```javascript
+// Initialize the Pipedream client with the SDK
+
+import { createBackendClient } from "@pipedream/sdk/server";
+
+const pd = createBackendClient({
+  environment: "development | production",
+  credentials: {
+    clientId: "{oauth_client_id}",
+    clientSecret: "{oauth_client_secret}",
+  },
+  projectId: "{your_project_id}"
+});
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```bash
+# Get an access token for the REST API
+
+curl -X POST https://api.pipedream.com/v1/oauth/token \
+  -H "Content-Type: application/json" \
+  -d '{
+    "grant_type": "client_credentials",
+    "client_id": "{your_oauth_client_id}",
+    "client_secret": "{your_oauth_client_secret}"
+  }'
+```
+</Tabs.Tab>
+</Tabs>
+
+<Callout type="info">
+All subsequent examples assume that you've either initialized the SDK client or have a valid access token.
+</Callout>
+
 ### Find the app you want to use
 
 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
+<Tabs items={['Node.js', 'HTTP (cURL)']}>
+<Tabs.Tab>
+```javascript
+const apps = await pd.getApps({ q: "gitlab" });
+
+// Parse and return the data you need
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```bash
+curl -X https://api.pipedream.com/v1/apps?q=gitlab \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer {access_token}"
+
+# Parse and return the data you need
 ```
+</Tabs.Tab>
+</Tabs>
 
 Here's the response:
 
@@ -77,9 +132,25 @@ Here's the response:
 
 Once you have the app you want to use, now you can list the triggers and/or actions for that app. We'll list the actions for Gitlab and we'll pass the `name_slug` `gitlab` as the `app`.
 
-```text
-GET /actions?app=gitlab
+<Tabs items={['Node.js', 'HTTP (cURL)']}>
+<Tabs.Tab>
+```javascript
+const components = await pd.getComponents({ q: "gitlab" });
+
+// Parse and return the data you need
 ```
+</Tabs.Tab>
+<Tabs.Tab>
+```bash
+curl -X https://api.pipedream.com/v1/connect/{project_id}/actions?app=gitlab \
+  -H "Content-Type: application/json" \
+  -H "X-PD-Environment: development" \
+  -H "Authorization: Bearer {access_token}"
+
+# Parse and return the data you need
+```
+</Tabs.Tab>
+</Tabs>
 
 Here's the response:
 
@@ -156,9 +227,25 @@ details.
 As an example, the following API call will return the structure of the **List
 Commits** action for Gitlab:
 
-```text
-GET /v1/connect/components/gitlab-list-commits
+<Tabs items={['Node.js', 'HTTP (cURL)']}>
+<Tabs.Tab>
+```javascript
+const component = await pd.getComponent({ key: "gitlab-list-commits" });
+
+// Parse and return the data you need
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```bash
+curl -X https://api.pipedream.com/v1/connect/{project_id}/components/gitlab-list-commits \
+  -H "Content-Type: application/json" \
+  -H "X-PD-Environment: development" \
+  -H "Authorization: Bearer {access_token}"
+
+# Parse and return the data you need
 ```
+</Tabs.Tab>
+</Tabs>
 
 The response will contain the component's structure, including its user-friendly name,
 version, and most importantly, the configuration options the component accepts
@@ -217,10 +304,6 @@ steps, focused on getting the right input parameters (aka
 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
-```
-
 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
@@ -232,31 +315,56 @@ The payload for the configuration API call must contain the following fields:
 2. `id`: the component's unique ID (aka **key**)
 3. `prop_name`: the name of the prop you want to configure
 4. `configured_props`: an object containing the props that have already been
-   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).
+    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).
 
 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)
 as an example, to illustrate a call that retrieves the options for the
-`projectId` prop of that component. The payload sent to the configuration API
-would look like this:
-
-```json
-{
-  "external_user_id": "demo-34c13d13-a31e-4a3d-8b63-0ac954671095",
-  "id": "gitlab-list-commits",
-  "prop_name": "projectId",
-  "configured_props": {
-    "gitlab": {
-      "authProvisionId": "apn_oOhaBlD"
+`projectId` prop of that component:
+
+<Tabs items={['Node.js', 'HTTP (cURL)']}>
+<Tabs.Tab>
+```javascript
+const { options } = await pd.configureComponent({
+  externalUserId: "abc-123",
+  id: "gitlab-list-commits",
+  propName: "projectId",
+  configuredProps: {
+    gitlab: {
+      authProvisionId: "apn_kVh9AoD",
     }
   }
-}
+});
+
+// Parse and return the data you need
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```bash
+curl -X POST https://api.pipedream.com/v1/connect/{project_id}/components/configure \
+  -H "Content-Type: application/json" \
+  -H "X-PD-Environment: development" \
+  -H "Authorization: Bearer {access_token}" \
+  -d '{
+    "external_user_id": "abc-123",
+    "id": "gitlab-list-commits",
+    "prop_name": "projectId",
+    "configured_props": {
+      "gitlab": {
+        "authProvisionId": "apn_kVh9AoD"
+      }
+    }
+  }'
+# Parse and return the data you need
 ```
+</Tabs.Tab>
+</Tabs>
+
 
-The response will contain the possible values (and their human-readable labels
+The response contains the possible values (and their human-readable labels
 when applicable) for the prop, as well as any possible errors that might have
 occurred. The response for the request above would look like this:
 
@@ -348,7 +456,7 @@ 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
-set to `true` in the component's code.
+set to `true` in the component's definition.
 
 After configuring a dynamic prop, the set of subsequent props must be recomputed
 (or reloaded), which is possible using the following API call:
@@ -452,8 +560,8 @@ supports two types of components: [actions](/components#actions) and
 
 Actions are components that perform a task by taking an input either during
 [configuration](#configure-the-component) and/or during invocation (usually both), and
-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
+produces a result. Sources are very similar, but the difference is that they are
+not invoked directly by end users directly, 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,
 then will emit an event for you to consume.
@@ -472,11 +580,11 @@ used for configuring a prop, with the exception of the `prop_name` attribute
 ```json
 {
   "async_handle": "xFfBakdTGTkI",
-  "external_user_id": "demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9",
+  "external_user_id": "abc-123",
   "id": "gitlab-list-commits",
   "configured_props": {
     "gitlab": {
-      "authProvisionId": "apn_JjhWOl0"
+      "authProvisionId": "apn_kVh9AoD"
     },
     "projectId": 45672541,
     "refName": "main"
@@ -487,9 +595,45 @@ used for configuring a prop, with the exception of the `prop_name` attribute
 To run the action with this configuration, simply send it as the request payload
 to the following endpoint:
 
-```text
-POST /v1/connect/actions/run
+<Tabs items={['Node.js', 'HTTP (cURL)']}>
+<Tabs.Tab>
+```javascript
+const resp = await pd.runAction({
+  externalUserId: "abc-123",
+  id: "gitlab-list-commits",
+  configuredProps: {
+    gitlab: {
+      authProvisionId: "apn_kVh9AoD",
+    },
+    projectId: 45672541,
+    refName: "main"
+  }
+});
+
+// Parse and return the data you need
+```
+</Tabs.Tab>
+<Tabs.Tab>
+```bash
+curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
+  -H "Content-Type: application/json" \
+  -H "X-PD-Environment: development" \
+  -H "Authorization: Bearer {access_token}" \
+  -d '{
+    "external_user_id": "abc-123",
+    "id": "gitlab-list-commits",
+    "prop_name": "projectId",
+    "configured_props": {
+      "gitlab": {
+        "authProvisionId": "apn_kVh9AoD"
+      }
+    }
+  }'
+
+# Parse and return the data you need
 ```
+</Tabs.Tab>
+</Tabs>
 
 The output of executing the action will be a JSON object containing the
 following fields:
@@ -534,19 +678,17 @@ above:
 
 Because sources are exercised by events that happen on a third-party service,
 their semantics are different from actions. Once a source is configured, it must
-be deployed in order to start listening for events. You might be asking where do
-those events go, and you'd be right to ask. That's the reason why when deploying
-a source you must provide a URL where the source will send these events, similar
-to how a webhook works.
+be deployed in order to start listening for events. When deploying a source, you
+can define either a webhook URL or a Pipedream workflow ID to consume those events.
 
 Deploying a source is done by sending a payload similar to the one used for
-running an action, with the addition of the webhook URL mentioned above. Using
+running an action, with the addition of the webhook URL or workflow ID. Using
 the **New Issue (Instant)** source for Gitlab as an example, the payload would
 look something like this:
 
 ```json
 {
-  "external_user_id": "demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9",
+  "external_user_id": "abc-123",
   "id": "gitlab-new-issue",
   "prop_name": "http",
   "configured_props": {
@@ -559,11 +701,53 @@ look something like this:
 }
 ```
 
-The endpoint to deploy a source is:
+Deploy a source for your users:
+
+<Tabs items={['Node.js', 'HTTP (cURL)']}>
+<Tabs.Tab>
+```javascript
+const { data: deployedTrigger } = await pd.deployTrigger({
+  externalUserId: "abc-123",
+  id: "gitlab-new-issue",
+  propName: "projectId",
+  configuredProps: {
+    gitlab: {
+      authProvisionId: "apn_kVh9AoD",
+    }
+  },
+  webhookUrl: "https://events.example.com/gitlab-new-issue"
+});
 
-```text
-POST /v1/connect/triggers/deploy
+const {
+  id: triggerId,      // The unique ID of the deployed trigger
+  name: triggerName,  // The name of the deployed trigger
+  owner_id: userId,   // The unique ID in Pipedream of your user
+} = deployedTrigger;
+
+// Parse and return the data you need
 ```
+</Tabs.Tab>
+<Tabs.Tab>
+```bash
+curl -X POST https://api.pipedream.com/v1/connect/{project_id}/components/triggers/deploy \
+  -H "Content-Type: application/json" \
+  -H "X-PD-Environment: development" \
+  -H "Authorization: Bearer {access_token}" \
+  -d '{
+    "external_user_id": "abc-123",
+    "id": "gitlab-new-issue",
+    "prop_name": "projectId",
+    "configured_props": {
+      "gitlab": {
+        "authProvisionId": "apn_kVh9AoD"
+      }
+    },
+    "webhook_url": "https://events.example.com/gitlab-new-issue"
+  }'
+# Parse and return the data you need
+```
+</Tabs.Tab>
+</Tabs>
 
 If the source deployment succeeds, the response will contain the information
 regarding the state of the source, including all the component's props metadata,
@@ -622,11 +806,9 @@ this:
 }
 ```
 
-In the example above, the source ID is `dc_dAuGmW7`, which can be used to delete
-the source in the future:
+In the example above, the source ID is `dc_dAuGmW7`, which can be used to delete,
+retrieve, or update the source in the future.
 
-```text
-DELETE /v1/connect/deployed-triggers/dc_dAuGmW7?external_user_id=demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9
-```
+Refer to the [full Connect API reference](/connect/api#components) for questions and additional examples.
 
 </Steps>