diff --git a/docs-v2/next.config.mjs b/docs-v2/next.config.mjs index bb13365241d6b..4ce4edb28de5f 100644 --- a/docs-v2/next.config.mjs +++ b/docs-v2/next.config.mjs @@ -438,17 +438,37 @@ export default withNextra({ }, { source: "/cli/", - destination: "/workflows/cli/reference/", + destination: "/components/contributing/cli/reference/", permanent: true, }, { source: "/cli/reference/", - destination: "/workflows/cli/reference/", + destination: "/components/contributing/cli/reference/", permanent: true, }, { source: "/cli/login/", - destination: "/workflows/cli/login/", + destination: "/components/contributing/cli/login/", + permanent: true, + }, + { + source: "/cli/install/", + destination: "/components/contributing/cli/install/", + permanent: true, + }, + { + source: "/cli/:path*", + destination: "/components/contributing/cli/:path*", + permanent: true, + }, + { + source: "/workflows/cli/", + destination: "/components/contributing/cli/reference/", + permanent: true, + }, + { + source: "/workflows/cli/:path*", + destination: "/components/contributing/cli/:path*", permanent: true, }, { diff --git a/docs-v2/pages/components/contributing/_meta.tsx b/docs-v2/pages/components/contributing/_meta.tsx index dd8f1829093a5..bcb33dce05358 100644 --- a/docs-v2/pages/components/contributing/_meta.tsx +++ b/docs-v2/pages/components/contributing/_meta.tsx @@ -5,4 +5,5 @@ export default { "sources-quickstart": "Quickstart — Sources", "guidelines": "Guidelines", "typescript": "TypeScript components", + "cli": "CLI", } as const diff --git a/docs-v2/pages/components/contributing/actions-quickstart.mdx b/docs-v2/pages/components/contributing/actions-quickstart.mdx index 0b2e6b8788a6e..1c7e570fc502d 100644 --- a/docs-v2/pages/components/contributing/actions-quickstart.mdx +++ b/docs-v2/pages/components/contributing/actions-quickstart.mdx @@ -22,10 +22,10 @@ If you previously developed actions using Pipedream's UI, we recommend reviewing ## Prerequisites - Create a free account at [https://pipedream.com](https://pipedream.com) -- Download and install the [Pipedream CLI](/workflows/cli/install/) -- Once the CLI is installed, [link your Pipedream account](/workflows/cli/login/#existing-pipedream-account) to the CLI by running `pd login` in your terminal +- Download and install the [Pipedream CLI](/components/contributing/cli/install/) +- Once the CLI is installed, [link your Pipedream account](/components/contributing/cli/login/#existing-pipedream-account) to the CLI by running `pd login` in your terminal -> **NOTE:** See the [CLI reference](/workflows/cli/reference/) for detailed usage and examples beyond those covered below. +> **NOTE:** See the [CLI reference](/components/contributing/cli/reference/) for detailed usage and examples beyond those covered below. ## Walkthrough diff --git a/docs-v2/pages/components/contributing/api.mdx b/docs-v2/pages/components/contributing/api.mdx index 443d6b5423e83..6eeb275a44334 100644 --- a/docs-v2/pages/components/contributing/api.mdx +++ b/docs-v2/pages/components/contributing/api.mdx @@ -20,7 +20,7 @@ Components are Node.js modules that run on Pipedream's serverless infrastructure - Trigger Node.js code on HTTP requests, timers, cron schedules, or manually - Emit data on each event to inspect it. Trigger Pipedream hosted workflows or access it outside of Pipedream via API -- Accept user input on deploy via [CLI](/workflows/cli/reference/#pd-deploy), [API](/workflows/rest-api), or [UI](https://pipedream.com/sources) +- Accept user input on deploy via [CLI](/components/contributing/cli/reference/#pd-deploy), [API](/workflows/rest-api), or [UI](https://pipedream.com/sources) - Connect to [{process.env.PUBLIC_APPS}+ apps](https://pipedream.com/apps) using Pipedream managed auth - Use most npm packages with no `npm install` or `package.json` required - Store and retrieve state using the [built-in key-value store](#db) @@ -49,9 +49,9 @@ Sources and actions share the same component API. However, certain features of t ### Getting Started with the CLI -Several examples below use the Pipedream CLI. To install it, [follow the instructions for your OS / architecture](/workflows/cli/install/). +Several examples below use the Pipedream CLI. To install it, [follow the instructions for your OS / architecture](/components/contributing/cli/install/). -See the [CLI reference](/workflows/cli/reference/) for detailed usage and examples beyond those covered below. +See the [CLI reference](/components/contributing/cli/reference/) for detailed usage and examples beyond those covered below. ### Example Components @@ -1052,11 +1052,11 @@ pd deploy https://raw.githubusercontent.com/PipedreamHQ/pipedream/master/compone #### CLI - Update -View the [CLI command reference](/workflows/cli/reference/#command-reference). +View the [CLI command reference](/components/contributing/cli/reference/#command-reference). #### CLI - Delete -View the [CLI command reference](/workflows/cli/reference/#command-reference). +View the [CLI command reference](/components/contributing/cli/reference/#command-reference). #### UI - Deploy diff --git a/docs-v2/pages/workflows/cli/_meta.tsx b/docs-v2/pages/components/contributing/cli/_meta.tsx similarity index 100% rename from docs-v2/pages/workflows/cli/_meta.tsx rename to docs-v2/pages/components/contributing/cli/_meta.tsx diff --git a/docs-v2/pages/workflows/cli/install.mdx b/docs-v2/pages/components/contributing/cli/install.mdx similarity index 96% rename from docs-v2/pages/workflows/cli/install.mdx rename to docs-v2/pages/components/contributing/cli/install.mdx index ef80352484eba..77fde2ed28bbc 100644 --- a/docs-v2/pages/workflows/cli/install.mdx +++ b/docs-v2/pages/components/contributing/cli/install.mdx @@ -77,4 +77,4 @@ The `pd` binary is available via Nix flake [here](https://github.com/planet-a-ve Run `pd` to see a list of all commands, or `pd help ` to display help docs for a specific command. -See the [CLI reference](/workflows/cli/reference/) for detailed usage and examples for each command. +See the [CLI reference](/components/contributing/cli/reference/) for detailed usage and examples for each command. diff --git a/docs-v2/pages/workflows/cli/login.mdx b/docs-v2/pages/components/contributing/cli/login.mdx similarity index 70% rename from docs-v2/pages/workflows/cli/login.mdx rename to docs-v2/pages/components/contributing/cli/login.mdx index 0abfcbbad0b3d..c82ac076e3492 100644 --- a/docs-v2/pages/workflows/cli/login.mdx +++ b/docs-v2/pages/components/contributing/cli/login.mdx @@ -12,7 +12,7 @@ If you already have a Pipedream account, run pd login ``` -This will open up a new window in your default browser. If you're already logged into your Pipedream account in this browser, this will immediately link the CLI to your account, writing your API key for that account to your [`pd` config file](/workflows/cli/reference/#cli-config-file). +This will open up a new window in your default browser. If you're already logged into your Pipedream account in this browser, this will immediately link the CLI to your account, writing your API key for that account to your [`pd` config file](/components/contributing/cli/reference/#cli-config-file). Otherwise, you'll be asked to login. @@ -23,7 +23,7 @@ Once you're done, go back to your shell and you should see confirmation that you Logged in as dylburger (dylan@pipedream.com) ``` -Then [follow this guide](/workflows/cli/reference/#creating-a-profile-for-a-workspace) to learn how to find your workspace ID and associate it with a `pd` profile. +Then [follow this guide](/components/contributing/cli/reference/#creating-a-profile-for-a-workspace) to learn how to find your workspace ID and associate it with a `pd` profile. ## Signing up for Pipedream via the CLI @@ -33,7 +33,7 @@ If you haven't signed up for a Pipedream account, you can create an account usin pd signup ``` -This will open up a new window in your default browser. You'll be asked to sign up for Pipedream here. Once you do, your account will be linked to the CLI, writing your API key for that account to your [`pd` config file](/workflows/cli/reference/#cli-config-file). +This will open up a new window in your default browser. You'll be asked to sign up for Pipedream here. Once you do, your account will be linked to the CLI, writing your API key for that account to your [`pd` config file](/components/contributing/cli/reference/#cli-config-file). Once you're done, go back to your shell and you should see confirmation that your account is linked: @@ -50,8 +50,8 @@ You can log out of the CLI by running: pd logout ``` -This will remove your API key from the [`pd` config file](/workflows/cli/reference/#cli-config-file). +This will remove your API key from the [`pd` config file](/components/contributing/cli/reference/#cli-config-file). ## Using the CLI to manage multiple accounts -If you have multiple Pipedream accounts, you can use [profiles](/workflows/cli/reference/#profiles) to ensure the CLI can manage resources for each. +If you have multiple Pipedream accounts, you can use [profiles](/components/contributing/cli/reference/#profiles) to ensure the CLI can manage resources for each. diff --git a/docs-v2/pages/workflows/cli/reference.mdx b/docs-v2/pages/components/contributing/cli/reference.mdx similarity index 93% rename from docs-v2/pages/workflows/cli/reference.mdx rename to docs-v2/pages/components/contributing/cli/reference.mdx index 3b0a247ae7b40..59827af4a8aaa 100644 --- a/docs-v2/pages/workflows/cli/reference.mdx +++ b/docs-v2/pages/components/contributing/cli/reference.mdx @@ -2,7 +2,7 @@ ## Installing the CLI -[See the CLI installation docs](/workflows/cli/install/) to learn how to install the CLI for your OS / architecture. +[See the CLI installation docs](/components/contributing/cli/install/) to learn how to install the CLI for your OS / architecture. ## Command Reference @@ -196,13 +196,13 @@ pd list st ### `pd login` -Log in to Pipedream CLI and persist API key locally. See [Logging into the CLI](/workflows/cli/login/) for more information. +Log in to Pipedream CLI and persist API key locally. See [Logging into the CLI](/components/contributing/cli/login/) for more information. ### `pd logout` Unsets the local API key tied to your account. -Running `pd logout` without any arguments removes the default API key from your [config file](/workflows/cli/reference/#cli-config-file). +Running `pd logout` without any arguments removes the default API key from your [config file](/components/contributing/cli/reference/#cli-config-file). You can remove the API key for a specific profile by running: @@ -234,7 +234,7 @@ pd publish my-action.js ### `pd signup` -Sign up for Pipedream via the CLI and persist your API key locally. See the docs on [Signing up for Pipedream via the CLI](/workflows/cli/login/#signing-up-for-pipedream-via-the-cli) for more information. +Sign up for Pipedream via the CLI and persist your API key locally. See the docs on [Signing up for Pipedream via the CLI](/components/contributing/cli/login/#signing-up-for-pipedream-via-the-cli) for more information. ### `pd unpublish` @@ -279,7 +279,7 @@ Profiles allow you to work with multiple, named Pipedream accounts via the CLI. ### Creating a new profile -When you [login to the CLI](/workflows/cli/login/), the CLI writes the API key for that account to your config file, in the `api_key` field: +When you [login to the CLI](/components/contributing/cli/login/), the CLI writes the API key for that account to your config file, in the `api_key` field: ```bash api_key = abc123 diff --git a/docs-v2/pages/components/contributing/sources-quickstart.mdx b/docs-v2/pages/components/contributing/sources-quickstart.mdx index c9aa3548fb47c..25d8c88bccab0 100644 --- a/docs-v2/pages/components/contributing/sources-quickstart.mdx +++ b/docs-v2/pages/components/contributing/sources-quickstart.mdx @@ -36,15 +36,15 @@ We recommend that you execute the examples in order — each one builds on the c **Step 1.** Create a free account at [https://pipedream.com](https://pipedream.com). Just sign in with your Google or Github account. -**Step 2.** [Download and install the Pipedream CLI](/workflows/cli/install/). +**Step 2.** [Download and install the Pipedream CLI](/components/contributing/cli/install/). -**Step 3.** Once the CLI is installed, [link your Pipedream account to the CLI](/workflows/cli/login/#existing-pipedream-account): +**Step 3.** Once the CLI is installed, [link your Pipedream account to the CLI](/components/contributing/cli/login/#existing-pipedream-account): ```bash pd login ``` -See the [CLI reference](/workflows/cli/reference/) for detailed usage and examples beyond those covered below. +See the [CLI reference](/components/contributing/cli/reference/) for detailed usage and examples beyond those covered below. ## CLI Development Mode @@ -67,7 +67,7 @@ If you need to update a deployed instance of a source, pass it's ID to the `dc` pd dev --dc dc_123456 components/sources/my-source.mjs ``` -See the [CLI reference](/workflows/cli/reference/) for detailed usage and examples beyond those covered below. +See the [CLI reference](/components/contributing/cli/reference/) for detailed usage and examples beyond those covered below. ## Hello World! diff --git a/docs-v2/pages/components/contributing/typescript.mdx b/docs-v2/pages/components/contributing/typescript.mdx index ca3d317c8fbea..47f5b60810dac 100644 --- a/docs-v2/pages/components/contributing/typescript.mdx +++ b/docs-v2/pages/components/contributing/typescript.mdx @@ -44,7 +44,7 @@ The build process should print the compiled JS files to your console and produce For example, if you compile a TypeScript file at `pipedream/components/rss/sources/new-item-in-feed/new-item-in-feed.ts`, the corresponding JS file will be produced at `pipedream/components/rss/dist/sources/new-item-in-feed/new-item-in-feed.js`. -6. Use [the Pipedream CLI](/workflows/cli/reference/) to `pd publish` or `pd dev` the JavaScript components emitted by step 5 by the full path to the file. +6. Use [the Pipedream CLI](/components/contributing/cli/reference/) to `pd publish` or `pd dev` the JavaScript components emitted by step 5 by the full path to the file. ```bash pd publish pipedream/components/rss/dist/sources/new-item-in-feed/new-item-in-feed.js diff --git a/docs-v2/pages/components/index.mdx b/docs-v2/pages/components/index.mdx index 603111efe202d..ca34ed37dc1ec 100644 --- a/docs-v2/pages/components/index.mdx +++ b/docs-v2/pages/components/index.mdx @@ -51,12 +51,12 @@ The Add Single Row action for Google Sheets is a prebuilt component in Pipedream Components may be instantiated or added to workflows via Pipedream's UI. -- Sources may be instantiated and consumed via [UI](https://pipedream.com/sources/new), [CLI](/workflows/cli/reference/#pd-deploy) or API +- Sources may be instantiated and consumed via [UI](https://pipedream.com/sources/new), [CLI](/components/contributing/cli/reference/#pd-deploy) or API - Actions may be added to [workflows](https://pipedream.com/new) ### Using Private Actions -Private action components published from the [CLI](/workflows/cli/reference/#pd-publish) or from a [Node.js Code Step](/workflows/building-workflows/code/nodejs/sharing-code/) are available for use across your workflows. +Private action components published from the [CLI](/components/contributing/cli/reference/#pd-publish) or from a [Node.js Code Step](/workflows/building-workflows/code/nodejs/sharing-code/) are available for use across your workflows. To use a published action, add a new step to your workflow and click **My Actions**. Your privately published action components will appear in this list. @@ -64,7 +64,7 @@ To use a published action, add a new step to your workflow and click **My Action ### Using Private Sources -Private source components deployed from your account via the [CLI](/workflows/cli/reference/#pd-deploy) will automatically create a new Source in your account with the prop configuration you specified. +Private source components deployed from your account via the [CLI](/components/contributing/cli/reference/#pd-deploy) will automatically create a new Source in your account with the prop configuration you specified. Then in the workflow builder, when creating the trigger, select the *Existing* sources tab in the upper right corner to select your deployed source: @@ -76,7 +76,7 @@ You can also deploy new instances of a source from the [Components dashboard](ht ## Developing Components -Develop components locally using your preferred code editor (and maintain your code in your own GitHub repo) and deploy or publish using Pipedream's [CLI](/workflows/cli/reference/#pd-deploy). +Develop components locally using your preferred code editor (and maintain your code in your own GitHub repo) and deploy or publish using Pipedream's [CLI](/components/contributing/cli/reference/#pd-deploy). - Sources may be deployed directly from local code or published to your account and instantiated via Pipedream's UI - Actions may only be published — published actions may be added to workflows via Pipedream's UI @@ -88,7 +88,7 @@ Published components are only available to your own account by default. If publi - A free [Pipedream](https://pipedream.com) account - A free [GitHub](https://github.com) account - Basic proficiency with Node.js or Javascript -- Pipedream [CLI](/workflows/cli/reference/) +- Pipedream [CLI](/components/contributing/cli/reference/) Finally, the target app must be integrated with Pipedream. You can explore all apps supported by Pipedream in the [marketplace](https://pipedream.com/explore). If your app is not listed, please [create a GitHub issue](https://github.com/PipedreamHQ/pipedream/issues/new?assignees=&labels=app%2C+enhancement&template=app---service-integration.md&title=%5BAPP%5D) to request it and [reach out](https://pipedream.com/community/c/dev/11) to our team to let us know that you're blocked on source or action development. diff --git a/docs-v2/pages/connect/api-proxy.mdx b/docs-v2/pages/connect/api-proxy.mdx index 4d82da40869d4..8e613e5a0cd95 100644 --- a/docs-v2/pages/connect/api-proxy.mdx +++ b/docs-v2/pages/connect/api-proxy.mdx @@ -1,8 +1,9 @@ +import { Tabs } from 'nextra/components' import Callout from '@/components/Callout' # Connect API Proxy -Pipedream Connect provides a proxy API that you can use to send authenticated requests to any integrated API on behalf of your users, which is useful in a few scenarios: +Pipedream Connect provides a proxy API that you can use to send authenticated requests to any integrated API on behalf of your users. This is useful in a few scenarios: 1. You need code-level control and you want to use [Pipedream's OAuth](/connect/managed-auth/oauth-clients/#using-pipedream-oauth) instead of [your own OAuth client](/connect/managed-auth/oauth-clients/#using-a-custom-oauth-client) 2. There isn't a [pre-built tool](/connect/components/) (action) for the app, or you need to modify the request @@ -24,7 +25,9 @@ Before getting started with the Connect proxy, make sure you've already gone thr ## Getting started -You can send requests to the Connect proxy using the [Pipedream SDK](#using-the-pipedream-sdk) with a fetch-style interface, or directly to the [Pipedream REST API](#using-the-rest-api). +You can send requests to the Connect proxy using either the Pipedream SDK with a fetch-style interface or the Pipedream REST API.T API. + +### Prerequisites - A [Pipedream OAuth client](/rest-api/auth/#oauth) to make authenticated requests to Pipedream's API - Connect [environment](/connect/managed-auth/environments/) (ex, `production` or `development`) @@ -41,14 +44,17 @@ Since Pipedream has {process.env.PUBLIC_APPS}+ integrated apps, we know how the ### Sending requests +When making requests to the Connect Proxy, you must provide the following parameters: + +#### Request parameters + **URL** - The URL of the API you want to call (ex, `https://slack.com/api/chat.postMessage`) - When using the REST API, this should be a URL-safe Base64 encoded string (ex, `aHR0cHM6Ly9zbGFjay5jb20vYXBpL2NoYXQucG9zdE1lc3NhZ2U`) -- Some APIs like Zendesk, Zoho, and others use dynamic base domains that are account-specific (e.g, `https://foo.zendesk.com`). For any of these apps, you should pass a relative path as the `url` in your proxy request, like `/api/v2/chat/chats` for example. -- Those dynamic fields are typically defined by the end user during the account connection flow, so the domain value will be stored as part of their connected account credentials in Pipedream. +**For apps with dynamic domains** (like Zendesk, Zoho, GitLab), you should use relative paths in your proxy requests. Pipedream automatically resolves the correct domain based on the user's connected account. See [When to use relative vs full URLs](#when-to-use-relative-vs-full-urls) for details. **HTTP method** @@ -64,10 +70,10 @@ Since Pipedream has {process.env.PUBLIC_APPS}+ integrated apps, we know how the - If using the REST API, include the `Authorization` header with your Pipedream OAuth access token (`Bearer {access_token}`) - Headers that contain the prefix `x-pd-proxy` will get forwarded to the upstream API -#### Using the Pipedream SDK - -You can use the [Pipedream SDK](https://www.npmjs.com/package/@pipedream/sdk) to send a fetch-style request: +#### Examples + + ```javascript import { createBackendClient } from "@pipedream/sdk/server"; @@ -106,11 +112,8 @@ const resp = await pd.makeProxyRequest( // Parse and return the data you need console.log(resp); ``` - -#### Using the REST API - -You can also use the Connect REST API directly. If using the REST API, send your Pipedream OAuth access token in the `Authorization` header: - + + ```bash # First, obtain an OAuth access token to authenticate to the Pipedream API @@ -134,10 +137,104 @@ curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/proxy/{url_ # Parse and return the data you need ``` + + + +## Allowed domains + +The vast majority of apps in Pipedream work with the Connect Proxy. To check if an app is supported and what domains are allowed, use `pd.getApps()` or the [`/apps` REST API](/rest-api/#list-apps). + +### Understanding the Connect object + +Each app in the `/apps` API response includes a `connect` object: + +```json +{ + "id": "app_1Z2hw1", + "name_slug": "gitlab", + "name": "GitLab", + // ...other fields... + "connect": { + "proxy_enabled": true, + "allowed_domains": ["gitlab.com"], + "base_proxy_target_url": "https://{{custom_fields.base_api_url}}" + } +} +``` + +| Field | Description | +|-------|--------------| +| `proxy_enabled` | Whether the app supports the Connect Proxy | +| `allowed_domains` | Domains you can send requests to when using full URLs | +| `base_proxy_target_url` | The base URL for proxy requests, may contain placeholders for account-specific values | + +### When to use relative vs full URLs + +The format of `base_proxy_target_url` determines whether you should use a relative path or full URL: + +#### Apps with static domains + +If `base_proxy_target_url` is a standard URL (e.g., `https://slack.com`), you can use either: +- **Full URL**: `https://slack.com/api/chat.postMessage` +- **Relative path**: `/api/chat.postMessage` + +#### Apps with dynamic domains + +If `base_proxy_target_url` contains placeholders like `{{custom_fields.base_api_url}}`, you **must** use relative paths. This applies to: +- Self-hosted instances (GitLab) +- Apps with account-specific subdomains (Zendesk, Zoho) + +For these apps, Pipedream resolves the actual domain from the user's connected account at runtime. + +### Examples + + + +```javascript +// Both work +await pd.makeProxyRequest({...}, { + url: "https://slack.com/api/chat.postMessage" +}) + +await pd.makeProxyRequest({...}, { + url: "/api/chat.postMessage" +}) +``` + + +```javascript +// Must use relative path +await pd.makeProxyRequest({...}, { + url: "/api/v4/projects" // Pipedream resolves to the end user's GitLab instance +}) +``` + + + +### Discovering app support programmatically + + + +```javascript +const apps = await pd.getApps() + +// Filter for apps that support the proxy +const proxyEnabledApps = apps.filter(app => app.connect?.proxy_enabled) +``` + + +```bash +curl https://api.pipedream.com/v1/apps \ + -H "Authorization: Bearer " +``` + +Filter the response for apps where `connect.proxy_enabled` is `true`. + + ## Limits -The Connect proxy limits API requests to, -- 100 requests per minute per project. Requests that surpass this limit will receive a `429` response. -- A maximum timeout of 30 seconds. Requests that take longer than 30 seconds will be terminated, and Pipedream will return a `504` error to the caller. -- Please [let us know](https://pipedream.com/support) if you need higher limits. +- The Connect Proxy limits API requests to 1,000 requests per 5 minutes per project. Requests that surpass this limit will receive a `429` response. +- The maximum timeout for a request is 30 seconds. Requests that take longer than 30 seconds will be terminated, and Pipedream will return a `504` error to the caller. + +Please [let us know](https://pipedream.com/support) if you need higher limits. diff --git a/docs-v2/pages/connect/components/_meta.tsx b/docs-v2/pages/connect/components/_meta.tsx index 8b05a38f5c89b..556cb4fd656d9 100644 --- a/docs-v2/pages/connect/components/_meta.tsx +++ b/docs-v2/pages/connect/components/_meta.tsx @@ -1,4 +1,5 @@ export default { "index": "Overview", "files": "Working with Files", + "custom-tools": "Custom Tools", } as const diff --git a/docs-v2/pages/connect/components/custom-tools.mdx b/docs-v2/pages/connect/components/custom-tools.mdx new file mode 100644 index 0000000000000..2e1195e5e2fdf --- /dev/null +++ b/docs-v2/pages/connect/components/custom-tools.mdx @@ -0,0 +1,100 @@ +import Callout from '@/components/Callout' + +# Using Custom Tools + +In addition to the public triggers and actions in Pipedream's global registry, you can write and publish your own components to your workspace to use with Connect. Custom tools let you add specific functionality or capabilities that are unique to your exact use case. + +## Overview + +Custom tools are Node.js modules that you develop using the [Pipedream Components API](/components/contributing/api/) and publish to your Pipedream workspace. Once published, they become available across [all Connect APIs](/connect/api/#components), including the list, retrieve, run endpoints, etc. + + +Publishing custom tools is available to Pipedream customers on the [Business plan](https://pipedream.com/pricing?plan=Enterprise). + + +## Creating custom tools + +Custom tools use the same development workflow as standard Pipedream components: + +1. **Write your component** using the [Pipedream Components API](/components/contributing/api/) +2. **Follow component guidelines** outlined in the [component development docs](/components/contributing/guidelines/) +3. **Use the Pipedream CLI** to publish your component with a Connect-specific flag + + +Custom tools are either [sources](/components/contributing/sources-quickstart/) (triggers) or [actions](/components/contributing/actions-quickstart/). Check out the respective quickstart guides for step-by-step development instructions. + + +## Publishing for Connect + +To make your custom components available in Connect, use the `pd publish` command with the `--connect-environment` flag: + +```bash +pd publish my-custom-action.mjs --connect-environment development +``` + +### Environments + +The `--connect-environment` flag accepts two values: + +- **`development`**: makes the component available to your Pipedream workspace in Connect in development +- **`production`**: makes the component available to your Pipedream workspace in Connect in production + + +Components published to `development` will only be available in the development environment, and vice versa for `production`. + + +## Using custom tools + +Once published, your custom tools appear alongside public components in Connect APIs: + +- **List endpoints**: Custom tools are included in component listing responses +- **Retrieve endpoints**: You can fetch details about your custom components +- **Run endpoints**: Execute your custom tools with the same API calls used for public components + +### Referencing custom tools + +Custom tools are identified with a `~/` prefix in their component ID. For example, if you publish a component with the key `google_sheets-update-file`, it will appear in Connect APIs as `~/google_sheets-update-file`. + +When making API calls to list, retrieve, or run custom tools, use the prefixed ID: + +```bash +# List all components (includes custom tools with ~/ prefix) +GET /v1/components + +# Retrieve a specific custom tool +GET /v1/components/~/google_sheets-update-file + +# Run a custom tool +POST /v1/components/~/google_sheets-update-file/run +``` + +The Connect API treats custom tools identically to public components, ensuring a consistent integration experience. + +### Custom tools in MCP + +Custom actions that you publish are automatically exposed as tools in the [Pipedream MCP server](/connect/mcp/developer-tools) for the relevant app. + +## Example workflow + +Here's a typical workflow for creating and using a custom tool: + +1. **Develop locally** using your preferred editor +2. **Test your component** using [pd dev](/components/contributing/cli/reference/#pd-dev) for sources or local testing for actions +3. **Publish to Connect** with the appropriate environment flag +4. **Integrate via Connect APIs** in your application + + +Test your custom tools in your application directly or [run Pipedream's SDK playground](https://github.com/PipedreamHQ/pipedream-connect-examples/tree/master/connect-react-demo#pipedream-components-demo-react) locally with your Pipedream credentials. + + +## Best practices + +- **Follow naming conventions**: Use clear, descriptive names for your tools +- **Include proper documentation**: Add helpful descriptions and prop labels for easier configuration +- **Test thoroughly**: Validate your components work as expected before publishing to production +- **Version management**: Update component versions when making changes +- **Environment separation**: Use development environment for testing, production for live integrations + +## Getting help + +For component development questions, visit the [Pipedream Support](https://pipedream.com/support). For Connect-specific integration help, refer to the [Connect docs](/connect/). \ No newline at end of file diff --git a/docs-v2/pages/connect/components/index.mdx b/docs-v2/pages/connect/components/index.mdx index 5f6ffcfa44ce2..79e3812692908 100644 --- a/docs-v2/pages/connect/components/index.mdx +++ b/docs-v2/pages/connect/components/index.mdx @@ -123,7 +123,12 @@ Here's the response: "categories": [ "Developer Tools" ], - "featured_weight": 5000 + "featured_weight": 5000, + "connect": { + "proxy_enabled": true, + "allowed_domains": ["gitlab.com"], + "base_proxy_target_url": "https://{{custom_fields.base_api_url}}" + } } ] } diff --git a/docs-v2/pages/connect/mcp/developers.mdx b/docs-v2/pages/connect/mcp/developers.mdx index 4d5d6a6d9640c..2773225649ff4 100644 --- a/docs-v2/pages/connect/mcp/developers.mdx +++ b/docs-v2/pages/connect/mcp/developers.mdx @@ -422,3 +422,7 @@ If running locally: ``` http://localhost:3010/{external_user_id}/{app_slug} ``` + +## Using custom tools + +Publish [custom tools](/connect/components/custom-tools) to your workspace to use them in the Pipedream MCP server for the relevant app. This lets you add custom and unique functionality that may not be available in the public registry. \ No newline at end of file diff --git a/docs-v2/pages/hidden/scheduling-future-tasks/index.mdx b/docs-v2/pages/hidden/scheduling-future-tasks/index.mdx index ea3a59262e799..8858c212f6bc1 100644 --- a/docs-v2/pages/hidden/scheduling-future-tasks/index.mdx +++ b/docs-v2/pages/hidden/scheduling-future-tasks/index.mdx @@ -175,6 +175,6 @@ Scheduled tasks are emitted by the event source as events, which you can consume - [Pipedream workflows](/workflows/building-workflows/) - [A source-specific SSE stream](/workflows/data-management/destinations/sse/) - [The Pipedream REST API](/rest-api/) -- [The Pipedream CLI](/workflows/cli/reference/#installing-the-cli) +- [The Pipedream CLI](/components/contributing/cli/reference/#installing-the-cli) [See the docs on consuming events from sources](/workflows/building-workflows/sources/#consuming-events-from-sources) for more information. diff --git a/docs-v2/pages/rest-api/auth.mdx b/docs-v2/pages/rest-api/auth.mdx index f0b6263c8a77e..53dd8f1764f03 100644 --- a/docs-v2/pages/rest-api/auth.mdx +++ b/docs-v2/pages/rest-api/auth.mdx @@ -110,4 +110,4 @@ curl 'https://api.pipedream.com/v1/users/me' \ ## Using the Pipedream CLI -You can [link the CLI to your Pipedream account](/workflows/cli/login/), which will automatically pass your API key in the `Authorization` header with every API request. +You can [link the CLI to your Pipedream account](/components/contributing/cli/login/), which will automatically pass your API key in the `Authorization` header with every API request. diff --git a/docs-v2/pages/rest-api/index.mdx b/docs-v2/pages/rest-api/index.mdx index 2eabee31599d6..8f5c729db26b3 100644 --- a/docs-v2/pages/rest-api/index.mdx +++ b/docs-v2/pages/rest-api/index.mdx @@ -391,7 +391,12 @@ curl https://api.pipedream.com/v1/apps "categories": [ "Communication" ], - "featured_weight": 1000000001 + "featured_weight": 1000000001, + "connect": { + "proxy_enabled": true, + "allowed_domains": ["slack.com"], + "base_proxy_target_url": "https://slack.com" + } }, { "id": "app_mWnheL", @@ -404,7 +409,12 @@ curl https://api.pipedream.com/v1/apps "categories": [ "Communication" ], - "featured_weight": 4100 + "featured_weight": 4100, + "connect": { + "proxy_enabled": true, + "allowed_domains": ["slack.com"], + "base_proxy_target_url": "https://slack.com" + } } ] } @@ -443,8 +453,8 @@ curl https://api.pipedream.com/v1/apps/app_OkrhR1 \ #### Example Response ```json -"data": [ - { +{ + "data": { "id": "app_OkrhR1", "name_slug": "slack", "name": "Slack", @@ -454,10 +464,15 @@ curl https://api.pipedream.com/v1/apps/app_OkrhR1 \ "custom_fields_json": "[]", "categories": [ "Communication" - ] - "featured_weight": 1000000001 + ], + "featured_weight": 1000000001, + "connect": { + "proxy_enabled": true, + "allowed_domains": ["slack.com"], + "base_proxy_target_url": "https://slack.com" + } } -] +} ``` ## Components diff --git a/docs-v2/pages/rest-api/webhooks.mdx b/docs-v2/pages/rest-api/webhooks.mdx index c7b974d427876..9d1056f843919 100644 --- a/docs-v2/pages/rest-api/webhooks.mdx +++ b/docs-v2/pages/rest-api/webhooks.mdx @@ -18,7 +18,7 @@ First, you'll need the ID of your source. You can visit [https://pipedream.com/s ![Source ID](/images/rest-api/source-id.png) -You can also find the ID by running `pd list sources` using [the CLI](/workflows/cli/reference/#pd-list). +You can also find the ID by running `pd list sources` using [the CLI](/components/contributing/cli/reference/#pd-list). ### Step 2 - Create a webhook diff --git a/docs-v2/pages/workflows/_meta.tsx b/docs-v2/pages/workflows/_meta.tsx index 407826b07ffbc..68e576ea05d00 100644 --- a/docs-v2/pages/workflows/_meta.tsx +++ b/docs-v2/pages/workflows/_meta.tsx @@ -9,5 +9,4 @@ export default { "domains": "Custom Domains", "vpc": "Virtual Private Clouds", "limits": "Limits", - "cli": "CLI", } as const diff --git a/docs-v2/pages/workflows/building-workflows/sources.mdx b/docs-v2/pages/workflows/building-workflows/sources.mdx index 386ba32f7a406..29c80d8387111 100644 --- a/docs-v2/pages/workflows/building-workflows/sources.mdx +++ b/docs-v2/pages/workflows/building-workflows/sources.mdx @@ -36,7 +36,7 @@ Once you've created a source, you can use it to trigger [Pipedream workflows](/w ### Creating a source from the CLI -[Download the CLI](/workflows/cli/install/) and run: +[Download the CLI](/components/contributing/cli/install/) and run: ```bash pd deploy @@ -55,7 +55,7 @@ You can also trigger a [Pipedream workflow](/workflows/building-workflows/) ever Finally, you can consume events programmatically, outside the Pipedream platform, in a few different ways: - In real-time, using the [SSE stream](/workflows/data-management/destinations/sse/) linked to your source -- In real-time, via the CLI's [`pd events` command](/workflows/cli/reference/#pd-events) +- In real-time, via the CLI's [`pd events` command](/components/contributing/cli/reference/#pd-events) - In batch, using the [REST API](/rest-api/) ## Example: HTTP source diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b601ab54e0094..05626f12ebd94 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -15689,6 +15689,14 @@ importers: specifier: ^6.0.0 version: 6.2.0 + modelcontextprotocol/node_modules2/@modelcontextprotocol/sdk/dist/cjs: {} + + modelcontextprotocol/node_modules2/@modelcontextprotocol/sdk/dist/esm: {} + + modelcontextprotocol/node_modules2/zod-to-json-schema/dist/cjs: {} + + modelcontextprotocol/node_modules2/zod-to-json-schema/dist/esm: {} + packages/ai: dependencies: '@pipedream/sdk':