From ecd575dcc80162f9b1bc57f6ac670457c229105d Mon Sep 17 00:00:00 2001 From: Jay Vercellone Date: Thu, 5 Dec 2024 16:23:45 -0800 Subject: [PATCH 01/10] Document the Connect component API * Add new left-nav link to the new docs * Describe how to use the new API to configure and run a component * Document the new API endpoints in the API/SDK reference section * Add the exact `pnpm` entry to `.tool-versions` in the docs directory * Minor fixes in the docstring of the component configuration methods * Update SDK changelog for the previous and this current changes --- docs-v2/.tool-versions | 1 + docs-v2/pages/connect/_meta.tsx | 5 +- docs-v2/pages/connect/api.mdx | 709 ++++++++++++++++++++++++++- docs-v2/pages/connect/components.mdx | 501 +++++++++++++++++++ packages/sdk/CHANGELOG.md | 24 +- packages/sdk/package.json | 2 +- packages/sdk/src/shared/index.ts | 12 +- 7 files changed, 1238 insertions(+), 16 deletions(-) create mode 100644 docs-v2/pages/connect/components.mdx diff --git a/docs-v2/.tool-versions b/docs-v2/.tool-versions index c2ca3d3d25e33..fdb1cb75b15d8 100644 --- a/docs-v2/.tool-versions +++ b/docs-v2/.tool-versions @@ -1 +1,2 @@ nodejs 20.9.0 +pnpm 9.14.2 diff --git a/docs-v2/pages/connect/_meta.tsx b/docs-v2/pages/connect/_meta.tsx index 0276d989af55e..690996ad26048 100644 --- a/docs-v2/pages/connect/_meta.tsx +++ b/docs-v2/pages/connect/_meta.tsx @@ -9,7 +9,10 @@ export default { "title": "Quickstart", }, "workflows": { - "title": "Running workflows", + "title": "Running Workflows", + }, + "components": { + "title": "Running Components", }, "api": { "title": "API & SDK Reference", diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx index bdea29788ce63..cf868bb0c7f09 100644 --- a/docs-v2/pages/connect/api.mdx +++ b/docs-v2/pages/connect/api.mdx @@ -15,7 +15,7 @@ https://api.pipedream.com/v1/connect/{project_id} ## Installing the TypeScript SDK -Pipedream's SDK will work in any browser or server that can run JavaScript. +Pipedream's SDK will work in any browser or server that can run JavaScript. ### npm @@ -76,7 +76,7 @@ Here's a Next.js example [from our quickstart](/connect/quickstart): import { createFrontendClient } from "@pipedream/sdk/browser" // Example from our Next.js app import { serverConnectTokenCreate } from "./server" - + const { token, expires_at } = await serverConnectTokenCreate({ external_user_id: externalUserId // The end user's ID in your system }); @@ -134,7 +134,7 @@ curl -X POST https://api.pipedream.com/v1/connect/{project_id}/tokens \ ## External users -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. +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. @@ -165,7 +165,7 @@ See [the Connect tokens docs](/connect/tokens) for more information. ``` POST /{project_id}/tokens -``` +``` ##### Path parameters @@ -199,7 +199,7 @@ Pipedream will send events on successful auth, or any errors, to this URL via we ##### Examples -To create a short-lived token via TypeScript / JavaScript SDK, you'll need to create a Pipedream API client and call the `createConnectToken` method. In our example app, this code is in `app/server.ts`. +To create a short-lived token via TypeScript / JavaScript SDK, you'll need to create a Pipedream API client and call the `createConnectToken` method. In our example app, this code is in `app/server.ts`. In other languages, you'll need to make an HTTP POST request to the `/tokens` endpoint to create a token, then return the token to your frontend. Click into other tabs to see examples in additional languages. @@ -208,8 +208,8 @@ In other languages, you'll need to make an HTTP POST request to the `/tokens` en ```typescript import { createBackendClient, - type ConnectAPIResponse, - type ConnectTokenCreateOpts, + type ConnectAPIResponse, + type ConnectTokenCreateOpts, type ConnectTokenResponse, } from "@pipedream/sdk/server"; @@ -494,7 +494,7 @@ const account = await pd.getAccountById(accountId, { include_credentials: true, // set to true to include credentials }); -// Parse and return the data you need. These may contain credentials, +// Parse and return the data you need. These may contain credentials, // which you should never return to the client ``` @@ -517,7 +517,7 @@ const account = await pd.getAccountById(accountId, { include_credentials: true, // set to true to include credentials }); -// Parse and return the data you need. These may contain credentials, +// Parse and return the data you need. These may contain credentials, // which you should never return to the client ``` @@ -850,6 +850,697 @@ curl -X DELETE "https://api.pipedream.com/v1/connect/{project_id}/users/{externa Pipedream returns a `204 No Content` response on successful account deletion + +### Components + +#### List Components + +List all the components in the Pipedream registry. + +``` +GET /{component_type} +``` + +##### Path parameters + +`component_type` **string** + +Either `sources`, `actions`, or `components`. + +##### Query parameters + +`app` **string** (_optional_) + +The ID or name slug the app you'd like to retrieve. For example, Slack's unique +app ID is `app_OkrhR1`, and its name slug is `slack`. + +You can find the app's ID in the response from the [List apps](#list-apps) +endpoint, and the name slug under the **Authentication** section of any [app +page](https://pipedream.com/apps). + +--- + +`q` **string** (_optional_) + +A search query to filter the components by key (see the [component structure +table](/components/api#component-structure)). + +##### Examples + + + + +```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}" +}); + +// Retrieve components containing the word "issue" in their name, belonging to +// the Gitlab app +const { data: components } = await pd.getComponents({ + app: "gitlab", + q: "issue", +}); + +// Parse and return the data you need +``` + + + +```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}" +}); + +// Retrieve components containing the word "issue" in their name, belonging to +// the Gitlab app +const { data: components } = await pd.getComponents({ + app: "gitlab", + q: "issue", +}); + +// Parse and return the data you need +``` + + + +```bash +# First, obtain an OAuth access token +curl -X POST https://api.pipedream.com/v1/oauth/token \ + -H "Content-Type: application/json" \ + -d '{ + "grant_type": "client_credentials", + "client_id": "{oauth_client_id}", + "client_secret": "{oauth_client_secret}" + }' + +# The response will include an access_token. Use it in the Authorization header below. +# This request will fetch the first 3 components for the Gitlab app that contain +# the word "issue" in their name +curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components?app=gitlab&limit=3&q=issue" \ + -H "Authorization: Bearer {access_token}" +``` + + + +##### Example Response + +```json +{ + "page_info": { + "total_count": 5, + "count": 3, + "start_cursor": "c2NfM3ZpanpRcg", + "end_cursor": "c2NfQjVpTkJBcA" + }, + "data": [ + { + "name": "New Issue (Instant)", + "version": "0.1.2", + "key": "gitlab-new-issue" + }, + { + "name": "Update Issue", + "version": "0.0.2", + "key": "gitlab-update-issue" + }, + { + "name": "Search Issues", + "version": "0.0.3", + "key": "gitlab-search-issues" + } + ] +} +``` + + +#### Retrieve a Component + +Retrieve a specific component from the Pipedream registry. + +``` +GET /{component_type}/{component_key} +``` + +##### Path parameters + +`component_type` **string** + +Either `sources`, `actions`, or `components`. + +--- + +`component_key` **string** + +The key that identifies the component (see the [component structure +table](/components/api#component-structure)). + +##### Examples + + + + +```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}" +}); + +// Retrieve the "New Issue (Instant)" component for the Gitlab app +const { data: component } = await pd.getComponent({ + key: "gitlab-new-issue", +}); + +// Parse and return the data you need +``` + + + +```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}" +}); + +// Retrieve the "New Issue (Instant)" component for the Gitlab app +const { data: component } = await pd.getComponent({ + key: "gitlab-new-issue", +}); + +// Parse and return the data you need +``` + + + +```bash +# First, obtain an OAuth access token +curl -X POST https://api.pipedream.com/v1/oauth/token \ + -H "Content-Type: application/json" \ + -d '{ + "grant_type": "client_credentials", + "client_id": "{oauth_client_id}", + "client_secret": "{oauth_client_secret}" + }' + +# The response will include an access_token. Use it in the Authorization header below. +# This request will fetch the "New Issue (Instant)" component for the Gitlab app. +curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/gitlab-new-issue" \ + -H "Authorization: Bearer {access_token}" +``` + + + +##### Example Response + +```json +{ + "data": { + "name": "New Issue (Instant)", + "version": "0.1.2", + "key": "gitlab-new-issue", + "configurable_props": [ + { + "name": "gitlab", + "type": "app", + "app": "gitlab" + }, + { + "name": "db", + "type": "$.service.db" + }, + { + "name": "http", + "type": "$.interface.http", + "customResponse": true + }, + { + "name": "projectId", + "type": "integer", + "label": "Project ID", + "description": "The project ID, as displayed in the main project page", + "remoteOptions": true + } + ] + } +} +``` + + + + +#### Configure a Component + +Configure the a component's prop, based on the current component's +configuration. This endpoint will use the component's configuration to retrieve +the list of options that can be used to configure the prop indicated in the +request. + +```text +GET /{component_type}/configure +``` + +##### Path parameters + +`component_type` **string** + +Either `sources`, `actions`, or `components`. + +##### Body Parameters + +`configured_props` **object** + +The props that have already been configured for the component. This is a +JSON-serializable object with the prop names as keys and the configured values +as values. + +--- + +`external_user_id` **string** + +[The external user ID](/connect/api/#external-users) in your system that you +want to retrieve accounts for. + +--- + +`id` **string** + +The key that identifies the component (see the [component structure +table](/components/api#component-structure)). + +--- + +`prop_name` **string** + +The name of the component's prop to configure. + +##### Examples + + + + +```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}" +}); + +// Retrieve the configuration options for the "projectId" prop of the "List +// Commits" component for the Gitlab app. +const { options } = await pd.configureComponent({ + componentId: { + key: "gitlab-list-commits", + }, + configuredProps: { + gitlab: { + authProvisionId: "apn_kVh9AoD", + }, + }, + externalUserId: "jverce", + propName: "projectId", +}); + +// Parse and return the data you need +``` + + + +```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}" +}); + +// Retrieve the configuration options for the "projectId" prop of the "List +// Commits" component for the Gitlab app. +const { options } = await pd.configureComponent({ + componentId: { + key: "gitlab-list-commits", + }, + configuredProps: { + gitlab: { + authProvisionId: "apn_kVh9AoD", + }, + }, + externalUserId: "jverce", + propName: "projectId", +}); + +// Parse and return the data you need +``` + + + +```bash +# First, obtain an OAuth access token +curl -X POST https://api.pipedream.com/v1/oauth/token \ + -H "Content-Type: application/json" \ + -d '{ + "grant_type": "client_credentials", + "client_id": "{oauth_client_id}", + "client_secret": "{oauth_client_secret}" + }' + +# The response will include an access_token. Use it in the Authorization header below. +# This request will fetch the configuration options for the "projectId" prop of +# the "List Commits" component for the Gitlab app. + +echo '{ + "external_user_id": "jverce", + "id": "gitlab-list-commits", + "prop_name": "projectId", + "configured_props": { + "gitlab": { + "authProvisionId": "apn_kVh9AoD" + } + } +}' > data.json + +curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/configure" \ + -H "Authorization: Bearer {access_token}" \ + -H "Content-Type: application/json" \ + -d @data.json +``` + + + + +##### Example Response + +```json +{ + "observations": [], + "context": null, + "options": [ + { + "label": "jverce/foo-massive-10231-1", + "value": 45672541 + }, + { + "label": "jverce/foo-massive-10231", + "value": 45672514 + }, + { + "label": "jverce/foo-massive-14999-2", + "value": 45672407 + }, + { + "label": "jverce/foo-massive-14999-1", + "value": 45672382 + }, + { + "label": "jverce/foo-massive-14999", + "value": 45672215 + }, + { + "label": "jverce/gitlab-development-kit", + "value": 21220953 + }, + { + "label": "jverce/gitlab", + "value": 21208123 + } + ], + "errors": [], + "timings": { + "api_to_sidekiq": 1734043172355.1042, + "sidekiq_received": 1734043172357.867, + "sidekiq_to_lambda": 1734043172363.6812, + "sidekiq_done": 1734043173461.6406, + "lambda_configure_prop_called": 1734043172462, + "lambda_done": 1734043173455 + }, + "stringOptions": null +} +``` + +#### Reload a Component's Props (i.e. Configure Dynamic Props) + +Reload the component's props after configuring a dynamic prop, based on the +current component's configuration. This endpoint will use the component's +configuration to retrieve a new list of props depending on the value of the +props that were configured so far. See the [Dynamic +Props](/connect/components#dynamic-props) section for more information. + +```text +GET /{component_type}/props +``` + +##### Path parameters + +`component_type` **string** + +Either `sources`, `actions`, or `components`. + +##### Body Parameters + +`configured_props` **object** + +The props that have already been configured for the component. This is a +JSON-serializable object with the prop names as keys and the configured values +as values. + +--- + +`external_user_id` **string** + +[The external user ID](/connect/api/#external-users) in your system that you +want to retrieve accounts for. + +--- + +`id` **string** + +The key that identifies the component (see the [component structure +table](/components/api#component-structure)). + +--- + +`dynamic_props_id` **string** (_optional_) + +The ID of the last prop reconfiguration (or none when reconfiguring the props +for the first time). + +##### Examples + + + + +```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}" +}); + +// Retrieve the configuration options for the "Add Single Row" component for +// the Google Sheets app. Note that the `sheetId` prop is a dynamic prop. +const { dynamicProps } = await pd.reloadComponentProps({ + componentId: { + key: "google_sheets-add-single-row", + }, + configuredProps: { + googleSheets: { + authProvisionId: "apn_V1hMoE7", + }, + sheetId: "1BfWjFF2dTW_YDiLISj5N9nKCUErShgugPS434liyytg", + }, + externalUserId: "jay", +}); + +const { + configurableProps, // The new set of props + id: dynamicPropsId, // The ID of the last prop reconfiguration +} = dynamicProps; + +// Parse and return the data you need +``` + + + +```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}" +}); + +// Retrieve the configuration options for the "Add Single Row" component for +// the Google Sheets app. Note that the `sheetId` prop is a dynamic prop. +const { dynamicProps } = await pd.reloadComponentProps({ + componentId: { + key: "google_sheets-add-single-row", + }, + configuredProps: { + googleSheets: { + authProvisionId: "apn_V1hMoE7", + }, + sheetId: "1BfWjFF2dTW_YDiLISj5N9nKCUErShgugPS434liyytg", + }, + externalUserId: "jay", +}); + +const { + configurableProps, // The new set of props + id: dynamicPropsId, // The ID of the last prop reconfiguration +} = dynamicProps; + +// Parse and return the data you need +``` + + + +```bash +# First, obtain an OAuth access token +curl -X POST https://api.pipedream.com/v1/oauth/token \ + -H "Content-Type: application/json" \ + -d '{ + "grant_type": "client_credentials", + "client_id": "{oauth_client_id}", + "client_secret": "{oauth_client_secret}" + }' + +# The response will include an access_token. Use it in the Authorization header below. +# This request will fetch the new set of props for the "Add Single Row" component +# for the Google Sheets app. Note that the `sheetId` prop is a dynamic prop. + +echo '{ + "external_user_id": "jay", + "id": "google_sheets-add-single-row", + "configured_props": { + "googleSheets": { + "authProvisionId": "apn_V1hMoE7" + }, + "sheetId": "1BfWjFF2dTW_YDiLISj5N9nKCUErShgugPS434liyytg" + } +}' > data.json + +curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/props" \ + -H "Authorization: Bearer {access_token}" \ + -H "Content-Type: application/json" \ + -d @data.json +``` + + + + +##### Example Response + +```json +{ + "observations": [], + "errors": [], + "dynamicProps": { + "id": "dyp_6xUyVgQ", + "configurableProps": [ + { + "name": "googleSheets", + "type": "app", + "app": "google_sheets" + }, + { + "name": "drive", + "type": "string", + "label": "Drive", + "description": "Defaults to `My Drive`. To select a [Shared Drive](https://support.google.com/a/users/answer/9310351) instead, select it from this list.", + "optional": true, + "default": "My Drive", + "remoteOptions": true + }, + { + "name": "sheetId", + "type": "string", + "label": "Spreadsheet", + "description": "The Spreadsheet ID", + "useQuery": true, + "remoteOptions": true, + "reloadProps": true + }, + { + "name": "worksheetId", + "type": "string[]", + "label": "Worksheet(s)", + "description": "Select a worksheet or enter a custom expression. When referencing a spreadsheet dynamically, you must provide a custom expression for the worksheet.", + "remoteOptions": true, + "reloadProps": true + }, + { + "name": "hasHeaders", + "type": "boolean", + "label": "Does the first row of the sheet have headers?", + "description": "If the first row of your document has headers, we'll retrieve them to make it easy to enter the value for each column. Note: When using a dynamic reference for the worksheet ID (e.g. `{{steps.foo.$return_value}}`), this setting is ignored.", + "reloadProps": true + }, + { + "name": "myColumnData", + "type": "string[]", + "label": "Values", + "description": "Provide a value for each cell of the row. Google Sheets accepts strings, numbers and boolean values for each cell. To set a cell to an empty value, pass an empty string." + } + ] + } +} +``` + +#### Invoke an Action + +#### Deploy a Trigger + ### Projects #### Retrieve project info diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx new file mode 100644 index 0000000000000..0ddb1dc26ef20 --- /dev/null +++ b/docs-v2/pages/connect/components.mdx @@ -0,0 +1,501 @@ +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)**. + +## 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). + +## How to Run Components for Your End Users + +### Retrieving a Component's Definition + +The first thing to do in order to run a component for your end users is to know +about the component itself. To start with, you need to know the component's +unique key. Using that key, you can retrieve the component's structure from the +Pipedream API. See the [component +structure](/components/api#component-structure) section in our docs for more +details. + +As an example, the following API call will return the structure of the "List +Commits" component for Gitlab: + +```text +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", which is an +abbreviation of "properties"). Here's an example of the response for the +component in the example above: + +```json +{ + "data": { + "name": "List Commits", + "version": "0.0.3", + "key": "gitlab-list-commits", + "configurable_props": [ + { + "name": "gitlab", + "type": "app", + "app": "gitlab" + }, + { + "name": "projectId", + "type": "integer", + "label": "Project ID", + "description": "The project ID, as displayed in the main project page", + "remoteOptions": true + }, + { + "name": "refName", + "type": "string", + "label": "Branch Name", + "description": "The name of the branch", + "remoteOptions": true, + "optional": true + }, + { + "name": "max", + "type": "integer", + "label": "Max Results", + "description": "Max number of results to return. Default value is `100`", + "optional": true, + "default": 100 + } + ] + } +} +``` + +Using this information, you can now drive the configuration of the component for +your end users, as described in the next section. + +### Configuration + +Component execution on behalf of your end users requires a few preliminary +steps, focused on getting the right input parameters (a.k.a. +[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: + +```text +POST /v1/connect/components/configure +``` + +The reason for this back-and-forth is because the options for a prop are usually +linked to a specific user's account, and the Pipedream API is the one in charge +of contacting the third-party service using the user's credentials, retrieving +the necessary data, and sending these options back as a response. Please not +that this logic is not implemented by the API itself, but by the component's +code; in particular, the `options` function of the corresponding prop. + +The initial configuration call must contain your user's account ID for the +target app, and the name of the prop you want to configure. Using 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, the payload sent to the configuration API would look like this: + +```json +{ + "async_handle": "qxyTp7QcS2A6", + "external_user_id": "demo-34c13d13-a31e-4a3d-8b63-0ac954671095", + "id": "gitlab-list-commits", + "prop_name": "projectId", + "configured_props": { + "gitlab": { + "authProvisionId": "apn_oOhaBlD" + } + } +} +``` + +The goal of this particular call is to retrieve the options for the `projectId` +prop of the "List Commits" component for Gitlab, for the user with the ID +`demo-34c13d13-a31e-4a3d-8b63-0ac954671095`. The `authProvisionId` is the ID of +the account that the user has connected to the Gitlab app (see [this +section](workflows#configure-accounts-to-use-your-end-users-auth) for more +details on how to create these accounts). + +The response will contain 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: + +```json +{ + "observations": [], + "context": null, + "options": [ + { + "label": "jverce/foo-massive-10231-1", + "value": 45672541 + }, + { + "label": "jverce/foo-massive-10231", + "value": 45672514 + }, + { + "label": "jverce/foo-massive-14999-2", + "value": 45672407 + }, + { + "label": "jverce/foo-massive-14999-1", + "value": 45672382 + }, + { + "label": "jverce/foo-massive-14999", + "value": 45672215 + }, + { + "label": "jverce/gitlab-development-kit", + "value": 21220953 + }, + { + "label": "jverce/gitlab", + "value": 21208123 + } + ], + "errors": [], + "timings": { + "api_to_sidekiq": 1734043172355.1042, + "sidekiq_received": 1734043172357.867, + "sidekiq_to_lambda": 1734043172363.6812, + "sidekiq_done": 1734043173461.6406, + "lambda_configure_prop_called": 1734043172462, + "lambda_done": 1734043173455 + }, + "stringOptions": null +} +``` + + + +Fields inside `configured_props` are written in camel case since they refer to +the names of props as they appear in the component's code, they are not +attributes that the API itself consumes. For example, to retrieve the +configuration options for the `refName` prop: + + + +Subsequent prop configuration calls will be identical to the one above, but will +incrementally add more props to the `configured_props` object, with the name of +the prop being configured as the value for the `prop_name` attribute. + +```json +{ + "async_handle": "IyvFeE5oNpYd", + "external_user_id": "demo-34c13d13-a31e-4a3d-8b63-0ac954671095", + "id": "gitlab-list-commits", + "prop_name": "refName", + "configured_props": { + "gitlab": { + "authProvisionId": "apn_oOhaBlD" + }, + "projectId": 21208123 + } +} +``` + +#### Dynamic Props + +The set of props that a component can accept might not be static, and can 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. + +After configuring a dynamic prop, the set of subsequent props must be recomputed +(or reloaded), which is possible using the following API call: + +```text +POST /v1/connect/components/props +``` + +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 +request payload would look like this: + +```json +{ + "async_handle": "PL41Yf3PuX61", + "external_user_id": "demo-25092fa8-86c0-4d46-86c9-9dc9bde3b964", + "id": "google_sheets-add-single-row", + "configured_props": { + "googleSheets": { + "authProvisionId": "apn_V1hMoE7" + }, + "sheetId": "1BfWjFF2dTW_YDiLISj5N9nKCUErShgugPS434liyytg" + } +} +``` + +In this case, the `sheetId` prop is dynamic, and so after configuring it, the +set of props must be reloaded. The response will contain the new set of props +and their definition, similar to when the [component information was first +retrieved](#retrieving-a-components-definition). The response will also contain +an ID that can be used to reference the new set of props in subsequent +configuration calls. If this is ID is not provided, the set of props will be +based on the definition of the component that was retrieved initially. + +To illustrate, the response for the request above would look like this: + +```json +{ + "observations": [], + "errors": [], + "dynamicProps": { + "id": "dyp_6xUyVgQ", + "configurableProps": [ + { + "name": "googleSheets", + "type": "app", + "app": "google_sheets" + }, + { + "name": "drive", + "type": "string", + "label": "Drive", + "description": "Defaults to `My Drive`. To select a [Shared Drive](https://support.google.com/a/users/answer/9310351) instead, select it from this list.", + "optional": true, + "default": "My Drive", + "remoteOptions": true + }, + { + "name": "sheetId", + "type": "string", + "label": "Spreadsheet", + "description": "The Spreadsheet ID", + "useQuery": true, + "remoteOptions": true, + "reloadProps": true + }, + { + "name": "worksheetId", + "type": "string[]", + "label": "Worksheet(s)", + "description": "Select a worksheet or enter a custom expression. When referencing a spreadsheet dynamically, you must provide a custom expression for the worksheet.", + "remoteOptions": true, + "reloadProps": true + }, + { + "name": "hasHeaders", + "type": "boolean", + "label": "Does the first row of the sheet have headers?", + "description": "If the first row of your document has headers, we'll retrieve them to make it easy to enter the value for each column. Note: When using a dynamic reference for the worksheet ID (e.g. `{{steps.foo.$return_value}}`), this setting is ignored.", + "reloadProps": true + }, + { + "name": "myColumnData", + "type": "string[]", + "label": "Values", + "description": "Provide a value for each cell of the row. Google Sheets accepts strings, numbers and boolean values for each cell. To set a cell to an empty value, pass an empty string." + } + ] + } +} +``` + +### Execution + +Once all the props have been configured, the component can be invoked. Pipedream +supports two types of components: [actions](/components#actions) and +[sources](/components#sources). + +Actions are components that perform a task by taking an input either during +[configuration](#configuration) 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 +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. + +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 +occurs. + +#### Invoking an Action + +At the end of the configuration process for an action, you'll end up with a +payload that you can use to invoke the action. The payload is similar to the one +used for configuring a prop, with the exception of the `prop_name` attribute +(because we're not configuring any props at this point): + +```json +{ + "async_handle": "xFfBakdTGTkI", + "external_user_id": "demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9", + "id": "gitlab-list-commits", + "configured_props": { + "gitlab": { + "authProvisionId": "apn_JjhWOl0" + }, + "projectId": 45672541, + "refName": "main" + } +} +``` + +To run the action with this configuration, simply send it as the request payload +to the following endpoint: + +```text +POST /v1/connect/actions/run +``` + +The output of executing the action will be a JSON object containing the +following fields: + +1. `exports`: all the named exports produced by the action, like when calling + [`$.export` in a Node.js](/code/nodejs#using-export) component. +2. `os`: a list of observations produced by the action (e.g. logs, errors, etc). +3. `ret`: the return value of the action, if any. + +The following (abbreviated) example shows the output of running the action +above: + +```json +{ + "exports": { + "$summary": "Retrieved 1 commit" + }, + "os": [], + "ret": [ + { + "id": "387262aea5d4a6920ac76c1e202bc9fd0841fea5", + "short_id": "387262ae", + "created_at": "2023-05-03T03:03:25.000+00:00", + "parent_ids": [], + "title": "Initial commit", + "message": "Initial commit", + "author_name": "Jay Vercellone", + "author_email": "nope@pipedream.com", + "authored_date": "2023-05-03T03:03:25.000+00:00", + "committer_name": "Jay Vercellone", + "committer_email": "nope@pipedream.com", + "committed_date": "2023-05-03T03:03:25.000+00:00", + "trailers": {}, + "extended_trailers": {}, + "web_url": "https://gitlab.com/jverce/foo-massive-10231-1/-/commit/387262aea5d4a6920ac76c1e202bc9fd0841fea5" + } + ] +} +``` + +#### Deploying a Source + +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. + +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 +the "New Issue (Instant)" source for Gitlab as an example, the payload would +look something like this: + +```json +{ + "external_user_id": "jverce", + "id": "gitlab-new-issue", + "prop_name": "http", + "configured_props": { + "gitlab": { + "authProvisionId": "apn_kVh9AoD" + }, + "projectId": 45672541 + }, + "webhook_url": "https://events.example.com/gitlab-new-issue" +} +``` + +The endpoint to deploy a source is: + +```text +POST /v1/connect/triggers/deploy +``` + +If the source deployment succeeds, the response will contain the information +regarding the state of the source, including all the component's props metadata, +as well as their values. It will also contain its name, creation date, owner, +and most importantly its unique ID, which can be used to manage the source in +the future (e.g. delete it). The response for the request above would look like +this: + +```json +{ + "data": { + "id": "dc_dAuGmW7", + "owner_id": "exu_oedidz", + "component_id": "sc_3vijzQr", + "configurable_props": [ + { + "name": "gitlab", + "type": "app", + "app": "gitlab" + }, + { + "name": "db", + "type": "$.service.db" + }, + { + "name": "http", + "type": "$.interface.http", + "customResponse": true + }, + { + "name": "projectId", + "type": "integer", + "label": "Project ID", + "description": "The project ID, as displayed in the main project page", + "remoteOptions": true + } + ], + "configured_props": { + "gitlab": { + "authProvisionId": "apn_kVh9AoD" + }, + "db": { + "type": "$.service.db" + }, + "http": { + "endpoint_url": "https://39643dc2c8ff98a019f3fdc9078d6db9.m.pipedream.net" + }, + "projectId": 45672541 + }, + "active": true, + "created_at": 1734028283, + "updated_at": 1734028283, + "name": "My first project - exu_oedidz", + "name_slug": "my-first-project---exu-oedidz-2" + } +} +``` + +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 +``` diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.md index 6512e3d698115..78879fe842a80 100644 --- a/packages/sdk/CHANGELOG.md +++ b/packages/sdk/CHANGELOG.md @@ -1,6 +1,28 @@ # Changelog +## [1.1.1] - 2024-12-12 + +### Changed + +- Fixed the docstring referring to the `componentConfigure` and + `reloadComponentProps` methods of the components API + +## [1.1.0] - 2024-12-10 + +### Added + +- Documented the public methods and types for the components API + +### Changed + +- Renamed the methods involved with the components API (e.g. + `componentConfigure` -> `configureComponent`) +- Renamed the types used for passing options and accessing responses from the + components API endpoints (e.g. `ComponentRequestResponse` -> + `GetComponentResponse`) +- Marked the renamed methods and types as deprecated + ## [1.0.12] - 2024-12-06 ### Added @@ -55,7 +77,7 @@ - The backend client used to default to `production` if the environment was not specified. Now `environment` is a required argument for `createBackendClient` -and must be one of `production` or `development`. +and must be one of `production` or `development`. ## [1.0.4] - 2024-11-15 diff --git a/packages/sdk/package.json b/packages/sdk/package.json index 37cca219591be..43fd7c74c3430 100644 --- a/packages/sdk/package.json +++ b/packages/sdk/package.json @@ -1,6 +1,6 @@ { "name": "@pipedream/sdk", - "version": "1.1.0", + "version": "1.1.1", "description": "Pipedream SDK", "main": "dist/server/server/index.js", "module": "dist/server/server/index.js", diff --git a/packages/sdk/src/shared/index.ts b/packages/sdk/src/shared/index.ts index da8fce0b9bc45..beccbd751aaee 100644 --- a/packages/sdk/src/shared/index.ts +++ b/packages/sdk/src/shared/index.ts @@ -939,8 +939,10 @@ export abstract class BaseClient { * }, * propName: "channel", * configuredProps: { - * authProvisionId: "apn_z8hD1b4", - * } + * slack: { + * authProvisionId: "apn_z8hD1b4", + * }, + * }, * }); * console.log(options); */ @@ -992,8 +994,10 @@ export abstract class BaseClient { * key: "slack-send-message", * }, * configuredProps: { - * authProvisionId: "apn_z8hD1b4", - * } + * slack: { + * authProvisionId: "apn_z8hD1b4", + * }, + * }, * }); * * const { configurableProps, id: dynamicPropsId } = dynamicProps; From b114dfee79d1d8e456fa55153e70a32208f86aa2 Mon Sep 17 00:00:00 2001 From: Jay Vercellone Date: Thu, 12 Dec 2024 15:41:57 -0800 Subject: [PATCH 02/10] Fix linter issues with the SDK changelog --- packages/sdk/CHANGELOG.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.md index 4fa2f5ce6e70f..568a421e95a0e 100644 --- a/packages/sdk/CHANGELOG.md +++ b/packages/sdk/CHANGELOG.md @@ -12,7 +12,7 @@ ### Changed -- Remove deprecated asynchoronous response handling code. +- Remove deprecated asynchronous response handling code. ## [1.1.0] - 2024-12-10 @@ -33,7 +33,8 @@ ### Added -- Allow passing `before`, `after` pagination cursors for apps, accounts, components endpoints +- Allow passing `before`, `after` pagination cursors for apps, accounts, + components endpoints ## [1.0.11] - 2024-12-06 @@ -64,8 +65,8 @@ ### Changed -- The backend client now correctly uses asynchronous messaging to handle long running - operations. +- The backend client now correctly uses asynchronous messaging to handle long + running operations. - Updated the backend command line tool to respect the `ENVIRONMENT` env variable if set. @@ -74,8 +75,8 @@ ### Changed - Use client Connect tokens to make api calls directly from the client. -- Deprecated the `environments` property on `createFrontendClient` since it is now - stored in the token +- Deprecated the `environments` property on `createFrontendClient` since it is + now stored in the token ## [1.0.5] - 2024-11-18 From 44da6c6ca0a391404214eca2bec070522a3f5e60 Mon Sep 17 00:00:00 2001 From: Jay Vercellone Date: Thu, 12 Dec 2024 15:57:31 -0800 Subject: [PATCH 03/10] Fix sources-triggers typos --- docs-v2/pages/connect/api.mdx | 8 ++++---- docs-v2/pages/connect/components.mdx | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx index 6119e13ff0925..f484bd9f5834d 100644 --- a/docs-v2/pages/connect/api.mdx +++ b/docs-v2/pages/connect/api.mdx @@ -966,7 +966,7 @@ GET /{component_type} `component_type` **string** -Either `sources`, `actions`, or `components`. +Either `triggers`, `actions`, or `components`. ##### Query parameters @@ -1103,7 +1103,7 @@ GET /{component_type}/{component_key} `component_type` **string** -Either `sources`, `actions`, or `components`. +Either `triggers`, `actions`, or `components`. --- @@ -1234,7 +1234,7 @@ GET /{component_type}/configure `component_type` **string** -Either `sources`, `actions`, or `components`. +Either `triggers`, `actions`, or `components`. ##### Body Parameters @@ -1434,7 +1434,7 @@ GET /{component_type}/props `component_type` **string** -Either `sources`, `actions`, or `components`. +Either `triggers`, `actions`, or `components`. ##### Body Parameters diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx index 0ddb1dc26ef20..d68b613a91e1a 100644 --- a/docs-v2/pages/connect/components.mdx +++ b/docs-v2/pages/connect/components.mdx @@ -320,7 +320,7 @@ To illustrate, the response for the request above would look like this: Once all the props have been configured, the component can be invoked. Pipedream supports two types of components: [actions](/components#actions) and -[sources](/components#sources). +[sources](/components#sources) (a.k.a. triggers). Actions are components that perform a task by taking an input either during [configuration](#configuration) and/or during invocation (usually both), and From d5e39c7d94e5bac8a1fd05f28dfb0bf0dada88bd Mon Sep 17 00:00:00 2001 From: Jay Vercellone Date: Thu, 12 Dec 2024 16:05:53 -0800 Subject: [PATCH 04/10] Remove Projects section --- docs-v2/pages/connect/api.mdx | 74 ----------------------------------- 1 file changed, 74 deletions(-) diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx index f484bd9f5834d..f69b275fb3df2 100644 --- a/docs-v2/pages/connect/api.mdx +++ b/docs-v2/pages/connect/api.mdx @@ -2027,77 +2027,3 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/triggers/dep } } ``` - -### Projects - -#### Retrieve project info - -Retrieve the configuration for a specific project - -``` -GET /{project_id}/info -``` - -##### Path parameters - -`project_id` **string** - -[The project's ID](/projects#finding-your-projects-id) - -##### Examples - - - -```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}" -}); - -const info = await pd.getProjectInfo({ - project_id: "{your_project_id}", -}); -``` - - -```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}" -}); - -const info = await pd.getProjectInfo({ - project_id: "{your_project_id}", -}); -``` - - -```bash -# First, obtain an OAuth access token -curl -X POST https://api.pipedream.com/v1/oauth/token \ - -H "Content-Type: application/json" \ - -d '{ - "grant_type": "client_credentials", - "client_id": "{oauth_client_id}", - "client_secret": "{oauth_client_secret}" - }' - -# The response will include an access_token. Use it in the Authorization header below. - -curl -X POST https://api.pipedream.com/v1/connect/{project_id}/info \ - -H "Authorization: Bearer {access_token}" \ -``` - - From 800886c35632cb4bbab329967414877db1a1827b Mon Sep 17 00:00:00 2001 From: Jay Vercellone Date: Thu, 12 Dec 2024 16:06:28 -0800 Subject: [PATCH 05/10] Fix broken link --- docs-v2/pages/connect/api.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx index f69b275fb3df2..54dc002878617 100644 --- a/docs-v2/pages/connect/api.mdx +++ b/docs-v2/pages/connect/api.mdx @@ -975,9 +975,9 @@ Either `triggers`, `actions`, or `components`. The ID or name slug the app you'd like to retrieve. For example, Slack's unique app ID is `app_OkrhR1`, and its name slug is `slack`. -You can find the app's ID in the response from the [List apps](#list-apps) -endpoint, and the name slug under the **Authentication** section of any [app -page](https://pipedream.com/apps). +You can find the app's ID in the response from the [List +apps](/rest-api#list-apps) endpoint, and the name slug under the +**Authentication** section of any [app page](https://pipedream.com/apps). --- From 4c065e367b29123df119a174525fcb99bdbbcf56 Mon Sep 17 00:00:00 2001 From: Jay Vercellone Date: Thu, 12 Dec 2024 16:23:44 -0800 Subject: [PATCH 06/10] Fix title capitalizations --- docs-v2/pages/connect/_meta.tsx | 16 +++++------ docs-v2/pages/connect/api.mdx | 42 ++++++++++++++-------------- docs-v2/pages/connect/components.mdx | 14 +++++----- docs-v2/pages/connect/use-cases.mdx | 6 ++-- 4 files changed, 39 insertions(+), 39 deletions(-) diff --git a/docs-v2/pages/connect/_meta.tsx b/docs-v2/pages/connect/_meta.tsx index 690996ad26048..b6f7c2f4358aa 100644 --- a/docs-v2/pages/connect/_meta.tsx +++ b/docs-v2/pages/connect/_meta.tsx @@ -3,40 +3,40 @@ export default { "title": "Overview", }, "use-cases": { - "title": "Use Cases", + "title": "Use cases", }, "quickstart": { "title": "Quickstart", }, "workflows": { - "title": "Running Workflows", + "title": "Running workflows", }, "components": { - "title": "Running Components", + "title": "Running components", }, "api": { - "title": "API & SDK Reference", + "title": "API & SDK reference", }, "tokens": { - "title": "Connect Tokens", + "title": "Connect tokens", }, "environments": { "title": "Environments", }, "oauth-clients": { - "title": "OAuth Clients", + "title": "OAuth clients", }, "webhooks": { "title": "Webhooks", }, "connect-link": { - "title": "Connect Link", + "title": "Connect link", }, "troubleshooting": { "title": "Troubleshooting", }, "customize-your-app": { - "title": "Customize Your App", + "title": "Customize your app", }, "migrating-from-project-keys-to-oauth": { "display": "hidden", diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx index 54dc002878617..9da3994e8ff75 100644 --- a/docs-v2/pages/connect/api.mdx +++ b/docs-v2/pages/connect/api.mdx @@ -1,11 +1,11 @@ import Callout from '@/components/Callout' import { Tabs } from 'nextra/components' -# Connect API & SDK Reference +# Connect API & SDK reference Pipedream provides a TypeScript SDK and a REST API to interact with the Connect service. You'll find examples using the SDK and the REST API in multiple languages below. -## REST API Base URL +## REST API base URL Pipedream Connect resources are scoped to [projects](/projects), so you'll need to pass [the project's ID](/projects#finding-your-projects-id) as a part of the base URL: @@ -43,7 +43,7 @@ or a specific version: See the [REST API Authentication docs](/rest-api/auth). -### TypeScript SDK (Server) +### TypeScript SDK (server) Most of your interactions with the Connect API will happen on the server, to protect API requests and user credentials. You'll use the SDK in [your frontend](#typescript-sdk-browser) to let users connect accounts. Once connected, you'll use the SDK on the server to retrieve credentials, invoke workflows on their behalf, and more. @@ -63,7 +63,7 @@ const pd = createBackendClient({ // The `pd` client provides methods to interact with the Connect API — see below ``` -### TypeScript SDK (Browser) +### TypeScript SDK (browser) You'll primarily use the browser SDK to let your users securely connect apps from your frontend. Here, you @@ -667,7 +667,7 @@ curl -X GET \ } ``` -##### Example Response (with `include_credentials=true`) +##### Example response (with `include_credentials=true`) ```json { @@ -954,7 +954,7 @@ Pipedream returns a `204 No Content` response on successful account deletion ### Components -#### List Components +#### List components List all the components in the Pipedream registry. @@ -1060,8 +1060,8 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components?a -##### Example Response +##### Example response ```json { "page_info": { @@ -1091,7 +1091,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components?a ``` -#### Retrieve a Component +#### Retrieve a component Retrieve a specific component from the Pipedream registry. @@ -1181,7 +1181,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/g -##### Example Response +##### Example response ```json { @@ -1219,7 +1219,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/g -#### Configure a Component +#### Configure a component Configure the a component's prop, based on the current component's configuration. This endpoint will use the component's configuration to retrieve @@ -1236,7 +1236,7 @@ GET /{component_type}/configure Either `triggers`, `actions`, or `components`. -##### Body Parameters +##### Body parameters `configured_props` **object** @@ -1369,7 +1369,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/c -##### Example Response +##### Example response ```json { @@ -1418,7 +1418,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/c } ``` -#### Reload a Component's Props (i.e. Configure Dynamic Props) +#### Reload a component's props (i.e. configure dynamic props) Reload the component's props after configuring a dynamic prop, based on the current component's configuration. This endpoint will use the component's @@ -1436,7 +1436,7 @@ GET /{component_type}/props Either `triggers`, `actions`, or `components`. -##### Body Parameters +##### Body parameters `configured_props` **object** @@ -1580,7 +1580,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/p -##### Example Response +##### Example response ```json { @@ -1638,7 +1638,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/p } ``` -#### Invoke an Action +#### Invoke an action Invoke an action component for a Pipedream Connect user in a project. @@ -1646,7 +1646,7 @@ Invoke an action component for a Pipedream Connect user in a project. POST /actions/run ``` -##### Body Parameters +##### Body parameters `id` **string** @@ -1787,7 +1787,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/actions/run" -##### Example Response +##### Example response ```json { @@ -1817,7 +1817,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/actions/run" } ``` -#### Deploy a Trigger +#### Deploy a trigger Deploy a trigger component for a Pipedream Connect user in a project. @@ -1825,7 +1825,7 @@ Deploy a trigger component for a Pipedream Connect user in a project. POST /triggers/deploy ``` -##### Body Parameters +##### Body parameters `id` **string** @@ -1976,7 +1976,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/triggers/dep -##### Example Response +##### Example response ```json { diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx index d68b613a91e1a..7f14294b5bd85 100644 --- a/docs-v2/pages/connect/components.mdx +++ b/docs-v2/pages/connect/components.mdx @@ -3,13 +3,13 @@ import ArcadeEmbed from '@/components/ArcadeEmbed' import Callout from '@/components/Callout' import Image from 'next/image' -# Running Components for Your End Users +# 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)**. -## What are Components? +## 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 @@ -20,9 +20,9 @@ repository](https://github.com/PipedreamHQ/pipedream/tree/master/components). To learn more about components in detail, please visit our [Components guide](/components). -## How to Run Components for Your End Users +## How to run components for your end users -### Retrieving a Component's Definition +### Retrieving a component's definition The first thing to do in order to run a component for your end users is to know about the component itself. To start with, you need to know the component's @@ -214,7 +214,7 @@ the prop being configured as the value for the `prop_name` attribute. } ``` -#### Dynamic Props +#### Dynamic props The set of props that a component can accept might not be static, and can change depending on the values of prior props. Props that behave this way are called @@ -333,7 +333,7 @@ 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 occurs. -#### Invoking an Action +#### Invoking an action At the end of the configuration process for an action, you'll end up with a payload that you can use to invoke the action. The payload is similar to the one @@ -401,7 +401,7 @@ above: } ``` -#### Deploying a Source +#### Deploying a source 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 diff --git a/docs-v2/pages/connect/use-cases.mdx b/docs-v2/pages/connect/use-cases.mdx index 5d1867920331b..593ef2017d7db 100644 --- a/docs-v2/pages/connect/use-cases.mdx +++ b/docs-v2/pages/connect/use-cases.mdx @@ -1,10 +1,10 @@ -# Pipedream Connect Use Cases +# Pipedream Connect use cases Developers use Pipedream Connect to build customer-facing API integrations into their products. It lets you build [in-app messaging](#in-app-messaging), [CRM syncs](#crm-syncs), [AI-driven products](#ai-products), and much more, all in a few minutes. ## Core value to app developers -In 20 years of building software, we've seen a common theme. No matter the product, your customers end up needing to connect your app to third-party APIs. +In 20 years of building software, we've seen a common theme. No matter the product, your customers end up needing to connect your app to third-party APIs. You might build real-time notifications with messaging apps, export customer data to databases or spreadsheets, ingest data from CRMs, or connect to any of the thousands of APIs and SaaS services your customers are using. These features are often tied to large contracts and Enterprise customers. @@ -38,4 +38,4 @@ Sync data between your app and Google Sheets, Airtable, or any spreadsheet. Pipe ### And much more -Building an app with Pipedream and want to be profiled here (anonymously or otherwise)? Email connect@pipedream.com to let us know! \ No newline at end of file +Building an app with Pipedream and want to be profiled here (anonymously or otherwise)? Email connect@pipedream.com to let us know! From 6a6a5186486cfd94b2045c3fa26a7538900be0be Mon Sep 17 00:00:00 2001 From: Jay Vercellone Date: Thu, 12 Dec 2024 16:56:29 -0800 Subject: [PATCH 07/10] Address some of the feedback --- docs-v2/pages/connect/_meta.tsx | 2 +- docs-v2/pages/connect/components.mdx | 38 +++++++++++++++------------- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/docs-v2/pages/connect/_meta.tsx b/docs-v2/pages/connect/_meta.tsx index b6f7c2f4358aa..41958fea4e0ed 100644 --- a/docs-v2/pages/connect/_meta.tsx +++ b/docs-v2/pages/connect/_meta.tsx @@ -30,7 +30,7 @@ export default { "title": "Webhooks", }, "connect-link": { - "title": "Connect link", + "title": "Connect Link", }, "troubleshooting": { "title": "Troubleshooting", diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx index 7f14294b5bd85..a3c545a5e46b1 100644 --- a/docs-v2/pages/connect/components.mdx +++ b/docs-v2/pages/connect/components.mdx @@ -22,6 +22,8 @@ guide](/components). ## How to run components for your end users + + ### Retrieving a component's definition The first thing to do in order to run a component for your end users is to know @@ -31,8 +33,8 @@ Pipedream API. See the [component structure](/components/api#component-structure) section in our docs for more details. -As an example, the following API call will return the structure of the "List -Commits" component for Gitlab: +As an example, the following API call will return the structure of the **List +Commits** component for Gitlab: ```text GET /v1/connect/components/gitlab-list-commits @@ -40,9 +42,9 @@ 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", which is an -abbreviation of "properties"). Here's an example of the response for the -component in the example above: +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: ```json { @@ -90,7 +92,7 @@ your end users, as described in the next section. ### Configuration Component execution on behalf of your end users requires a few preliminary -steps, focused on getting the right input parameters (a.k.a. +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 @@ -101,16 +103,14 @@ are static/free-form. The endpoint is accessible at: POST /v1/connect/components/configure ``` -The reason for this back-and-forth is because the options for a prop are usually -linked to a specific user's account, and the Pipedream API is the one in charge -of contacting the third-party service using the user's credentials, retrieving -the necessary data, and sending these options back as a response. Please not -that this logic is not implemented by the API itself, but by the component's -code; in particular, the `options` function of the corresponding prop. +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. The initial configuration call must contain your user's account ID for the -target app, and the name of the prop you want to configure. Using the ["List -Commits" component for +target app, and the name of the prop you want to configure. Using 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, the payload sent to the configuration API would look like this: @@ -129,7 +129,7 @@ as an example, the payload sent to the configuration API would look like this: ``` The goal of this particular call is to retrieve the options for the `projectId` -prop of the "List Commits" component for Gitlab, for the user with the ID +prop of the **List Commits** component for Gitlab, for the user with the ID `demo-34c13d13-a31e-4a3d-8b63-0ac954671095`. The `authProvisionId` is the ID of the account that the user has connected to the Gitlab app (see [this section](workflows#configure-accounts-to-use-your-end-users-auth) for more @@ -233,7 +233,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** component for Google Sheets as an example, the request payload would look like this: ```json @@ -320,7 +320,7 @@ To illustrate, the response for the request above would look like this: Once all the props have been configured, the component can be invoked. Pipedream supports two types of components: [actions](/components#actions) and -[sources](/components#sources) (a.k.a. triggers). +[sources](/components#sources) (aka triggers). Actions are components that perform a task by taking an input either during [configuration](#configuration) and/or during invocation (usually both), and @@ -412,7 +412,7 @@ to how a webhook works. 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 -the "New Issue (Instant)" source for Gitlab as an example, the payload would +the **New Issue (Instant)** source for Gitlab as an example, the payload would look something like this: ```json @@ -499,3 +499,5 @@ the source in the future: ```text DELETE /v1/connect/deployed-triggers/dc_dAuGmW7?external_user_id=jverce ``` + + From 4bde167b5207f6e2b733bd84f0f4164f90efd0ab Mon Sep 17 00:00:00 2001 From: Jay Vercellone Date: Thu, 12 Dec 2024 17:13:35 -0800 Subject: [PATCH 08/10] Address some of the feedback --- docs-v2/pages/connect/components.mdx | 33 +++++++++++++++------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx index a3c545a5e46b1..2f29311af7aa2 100644 --- a/docs-v2/pages/connect/components.mdx +++ b/docs-v2/pages/connect/components.mdx @@ -108,15 +108,25 @@ 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. -The initial configuration call must contain your user's account ID for the -target app, and the name of the prop you want to configure. Using the [**List -Commits** component for +The payload for the configuration API call must contain the following fields: + +1. `external_user_id`: the ID of your user on your end +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) + +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, the payload sent to the configuration API would look like this: +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 { - "async_handle": "qxyTp7QcS2A6", "external_user_id": "demo-34c13d13-a31e-4a3d-8b63-0ac954671095", "id": "gitlab-list-commits", "prop_name": "projectId", @@ -128,13 +138,6 @@ as an example, the payload sent to the configuration API would look like this: } ``` -The goal of this particular call is to retrieve the options for the `projectId` -prop of the **List Commits** component for Gitlab, for the user with the ID -`demo-34c13d13-a31e-4a3d-8b63-0ac954671095`. The `authProvisionId` is the ID of -the account that the user has connected to the Gitlab app (see [this -section](workflows#configure-accounts-to-use-your-end-users-auth) for more -details on how to create these accounts). - The response will contain 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: @@ -190,14 +193,14 @@ occurred. The response for the request above would look like this: Fields inside `configured_props` are written in camel case since they refer to the names of props as they appear in the component's code, they are not -attributes that the API itself consumes. For example, to retrieve the -configuration options for the `refName` prop: +attributes that the API itself consumes. Subsequent prop configuration calls will be identical to the one above, but will incrementally add more props to the `configured_props` object, with the name of -the prop being configured as the value for the `prop_name` attribute. +the prop being configured as the value for the `prop_name` attribute. For +example, to retrieve the configuration options for the `refName` prop: ```json { From c77df2aebbcd27fedad2f4b19c0cbf90da4345b9 Mon Sep 17 00:00:00 2001 From: Jay Vercellone Date: Thu, 12 Dec 2024 17:28:08 -0800 Subject: [PATCH 09/10] Amend title and fix curl copy/paste --- docs-v2/pages/connect/api.mdx | 10 +++++----- docs-v2/pages/connect/components.mdx | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx index 9da3994e8ff75..33e17a3f8d040 100644 --- a/docs-v2/pages/connect/api.mdx +++ b/docs-v2/pages/connect/api.mdx @@ -1360,7 +1360,7 @@ echo '{ } }' > data.json -curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/configure" \ +curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/components/configure" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d @data.json @@ -1424,7 +1424,7 @@ Reload the component's props after configuring a dynamic prop, based on the current component's configuration. This endpoint will use the component's configuration to retrieve a new list of props depending on the value of the props that were configured so far. See the [Dynamic -Props](/connect/components#dynamic-props) section for more information. +Props](/connect/components#dynamic-props-optional) section for more information. ```text GET /{component_type}/props @@ -1571,7 +1571,7 @@ echo '{ } }' > data.json -curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/components/props" \ +curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/components/props" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d @data.json @@ -1778,7 +1778,7 @@ echo '{ } }' > data.json -curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/actions/run" \ +curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/actions/run" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d @data.json @@ -1967,7 +1967,7 @@ echo '{ "webhook_url": "https://events.example.com/gitlab-new-issue" }' > data.json -curl -X GET "https://api.pipedream.com/v1/connect/{your_project_id}/triggers/deploy" \ +curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/triggers/deploy" \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d @data.json diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx index 2f29311af7aa2..56a16b3e82e16 100644 --- a/docs-v2/pages/connect/components.mdx +++ b/docs-v2/pages/connect/components.mdx @@ -217,7 +217,7 @@ example, to retrieve the configuration options for the `refName` prop: } ``` -#### Dynamic props +#### Dynamic props (optional) The set of props that a component can accept might not be static, and can change depending on the values of prior props. Props that behave this way are called From 27ae7189ddb6f5fb35d7e7213d05ab3d743159ec Mon Sep 17 00:00:00 2001 From: Jay Vercellone Date: Thu, 12 Dec 2024 17:29:53 -0800 Subject: [PATCH 10/10] Address some of the feedback --- docs-v2/pages/connect/components.mdx | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx index 56a16b3e82e16..c8d6c19b91042 100644 --- a/docs-v2/pages/connect/components.mdx +++ b/docs-v2/pages/connect/components.mdx @@ -197,10 +197,17 @@ attributes that the API itself consumes. -Subsequent prop configuration calls will be identical to the one above, but will -incrementally add more props to the `configured_props` object, with the name of -the prop being configured as the value for the `prop_name` attribute. For -example, to retrieve the configuration options for the `refName` prop: +You configure props one-by-one, making a call to the component configuration API +for each new prop. Subsequent prop configuration calls will be identical to the +one above: + +1. Add the prop you currently want to configure as the `prop_name` +2. Include the names and values of all previously-configured props in the + `configured_props` object. Keep this object in your app's local state, add a + prop once you or the end user selects a value, and pass it to the + `configured_props` API param. + +For example, to retrieve the configuration options for the `refName` prop: ```json {