Update docs for the components API #15387
Conversation
* Add missing SDK examples for the triggers API * Document the deployed trigger events API * Document the new endpoints to manipulate listeners of a deployed trigger
jverce
added
enhancement
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎ 2 Skipped Deployments
|
|
@jverce is attempting to deploy a commit to the Pipedreamers Team on Vercel. A member of the Team first needs to authorize it. |
WalkthroughThis pull request enhances the Pipedream Connect API documentation by introducing methods for managing deployed triggers. It includes detailed guidance and examples for retrieving and updating information related to deployed triggers, such as their emitted events, associated webhooks, and workflows. The changes also introduce new types and interfaces to support the updated functionality, ensuring clarity and usability for developers. Changes
Possibly related PRs
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (9)
docs-v2/pages/connect/api.mdx (9)
2062-2085: Consider demonstrating error handling for a more robust example.
This snippet effectively illustrates how to list deployed triggers. However, adding a quick try/catch or promise rejection handling example in the documentation would help developers understand how best to manage unexpected errors.
2088-2109: Consider demonstrating error handling for a more robust example.
This snippet effectively illustrates how to list deployed triggers in Node.js code. However, adding a quick try/catch or error-handling snippet would help users manage HTTP or network failures gracefully.
2306-2355: Consider demonstrating error handling for a more robust example.
The snippet for retrieving a single deployed trigger is correct. Demonstrating how to handle errors (e.g., a missing trigger) would provide additional clarity and completeness.
2480-2527: Consider demonstrating error handling for a more robust example.
The snippet for deleting a deployed trigger is concise and clear. Providing minimal error handling guidance (e.g., checking for invalid IDs) would strengthen the example.
2588-2637: Consider demonstrating error handling for a more robust example.
The snippet for retrieving emitted events is straightforward. Showing how to handle scenarios when no events are found or network errors occur would make it more comprehensive.
2772-2817: Consider demonstrating error handling for a more robust example.
Retrieving webhooks listening to a deployed trigger appears to work well. An example that handles missing triggers or permission errors would be beneficial.
2886-2914: Consider demonstrating error handling for a more robust example.
The code for updating webhooks is accurate. Including a quick snippet on dealing with invalid webhook URLs or network errors would help users build robust applications.
2917-2945: Consider demonstrating error handling for a more robust example.
Similarly, this Node.js snippet for updating webhooks is correct. Adding advice on how to handle any unexpected response from the server would improve usability.
3008-3053: Consider demonstrating error handling for a more robust example.
This snippet for retrieving workflows listening to a trigger is functionally correct. Including error handling (e.g., dealing with invalid workflow IDs) would make the example more robust.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs-v2/pages/connect/api.mdx(6 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: Lint Code Base
- GitHub Check: validate-links
| ```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}" | ||
| }); | ||
|
|
||
| // The new list of workflow IDs that will listen to the deployed trigger | ||
| const workflowIds = [ | ||
| "p_ERRCzw", | ||
| "p_2LniLm", | ||
| ]; | ||
|
|
||
| // Update the list of workflows listening to the deployed trigger | ||
| const { workflow_ids: confirmedIds } = await pd.updateTriggerWorkflows({ | ||
| id: "dc_gzumK2e", | ||
| externalUserId: "jverce", | ||
| webhookUrls, | ||
| }); | ||
|
|
||
| // `workflowIds` will match `confirmedIds` if the update was successful | ||
| ``` |
There was a problem hiding this comment.
Fix incorrect parameter name for updating workflows.
This Node.js version of the same snippet also contains the same mismatch (webhookUrls instead of workflowIds). Replace the incorrect reference to avoid runtime errors.
Apply this diff to correct the code:
-const { workflow_ids: confirmedIds } = await pd.updateTriggerWorkflows({
- id: "dc_gzumK2e",
- externalUserId: "jverce",
- webhookUrls,
-});
+const { workflow_ids: confirmedIds } = await pd.updateTriggerWorkflows({
+ id: "dc_gzumK2e",
+ externalUserId: "jverce",
+ workflowIds,
+});| <Tabs.Tab> | ||
| ```typescript | ||
| import { | ||
| createBackendClient, | ||
| } from "@pipedream/sdk/server"; | ||
|
|
||
| const pd = createBackendClient({ | ||
| environment: "development", // change to production if running for a test production account, or in production | ||
| credentials: { | ||
| clientId: "{oauth_client_id}", | ||
| clientSecret: "{oauth_client_secret}", | ||
| }, | ||
| projectId: "{your_project_id}" | ||
| }); | ||
|
|
||
| // The new list of workflow IDs that will listen to the deployed trigger | ||
| const workflowIds = [ | ||
| "p_ERRCzw", | ||
| "p_2LniLm", | ||
| ]; | ||
|
|
||
| // Update the list of workflows listening to the deployed trigger | ||
| const { workflow_ids: confirmedIds } = await pd.updateTriggerWorkflows({ | ||
| id: "dc_gzumK2e", | ||
| externalUserId: "jverce", | ||
| webhookUrls, | ||
| }); | ||
|
|
||
| // `workflowIds` will match `confirmedIds` if the update was successful | ||
| ``` |
There was a problem hiding this comment.
Fix incorrect parameter name for updating workflows.
In this snippet, the code mistakenly passes webhookUrls instead of workflowIds, which will cause a runtime error. Use workflowIds to match the method signature and variable name.
Apply this diff to correct the code:
-const { workflow_ids: confirmedIds } = await pd.updateTriggerWorkflows({
- id: "dc_gzumK2e",
- externalUserId: "jverce",
- webhookUrls,
-});
+const { workflow_ids: confirmedIds } = await pd.updateTriggerWorkflows({
+ id: "dc_gzumK2e",
+ externalUserId: "jverce",
+ workflowIds,
+});📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <Tabs.Tab> | |
| ```typescript | |
| import { | |
| createBackendClient, | |
| } from "@pipedream/sdk/server"; | |
| const pd = createBackendClient({ | |
| environment: "development", // change to production if running for a test production account, or in production | |
| credentials: { | |
| clientId: "{oauth_client_id}", | |
| clientSecret: "{oauth_client_secret}", | |
| }, | |
| projectId: "{your_project_id}" | |
| }); | |
| // The new list of workflow IDs that will listen to the deployed trigger | |
| const workflowIds = [ | |
| "p_ERRCzw", | |
| "p_2LniLm", | |
| ]; | |
| // Update the list of workflows listening to the deployed trigger | |
| const { workflow_ids: confirmedIds } = await pd.updateTriggerWorkflows({ | |
| id: "dc_gzumK2e", | |
| externalUserId: "jverce", | |
| webhookUrls, | |
| }); | |
| // `workflowIds` will match `confirmedIds` if the update was successful | |
| ``` | |
| <Tabs.Tab> |
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs-v2/pages/connect/api.mdx (1)
3371-3375:⚠️ Potential issueFix incorrect parameter name for updating workflows.
The example uses
webhookUrlsinstead ofworkflowIdsin the updateTriggerWorkflows method call, which will cause a runtime error.Apply this diff to fix the parameter name:
-const { workflow_ids: confirmedIds } = await pd.updateTriggerWorkflows({ - id: "dc_gzumK2e", - externalUserId: "jverce", - webhookUrls, -}); +const { workflow_ids: confirmedIds } = await pd.updateTriggerWorkflows({ + id: "dc_gzumK2e", + externalUserId: "jverce", + workflowIds, +});
🧹 Nitpick comments (3)
docs-v2/pages/connect/api.mdx (3)
362-391: Consider adding error handling examples.While the account management examples are well-documented, it would be beneficial to include examples of error handling scenarios (e.g., handling non-existent accounts, network errors, etc.).
Add error handling examples like this:
try { const response: GetAccountsResponse = await pd.getAccounts(requestOpts); // Handle success } catch (error) { if (error.response?.status === 404) { console.error('Account not found'); } else { console.error('Failed to fetch accounts:', error.message); } }
1055-1084: Add pagination handling examples.The component listing examples should demonstrate how to handle pagination using the
page_infoobject returned in the response.Add pagination handling example:
async function getAllComponents(pd: BackendClient, opts: GetComponentsOpts) { let allComponents: V1Component[] = []; let hasMore = true; let cursor = undefined; while (hasMore) { const response = await pd.getComponents({ ...opts, after: cursor, }); allComponents = [...allComponents, ...response.data]; cursor = response.page_info.end_cursor; hasMore = response.data.length === response.page_info.count; } return allComponents; }
Line range hint
1788-1828: Add input validation examples.The action invocation examples would benefit from showing how to validate inputs before making the API call.
Add input validation example:
function validateActionInput(opts: RunActionOpts) { if (!opts.actionId?.key) { throw new Error('Action ID is required'); } if (!opts.externalUserId) { throw new Error('External user ID is required'); } if (!opts.configuredProps) { throw new Error('Configured props are required'); } } // Usage const requestOpts: RunActionOpts = { actionId: { key: "gitlab-list-commits" }, configuredProps: {/*...*/}, externalUserId: "jverce", }; validateActionInput(requestOpts); const response = await pd.runAction(requestOpts);
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs-v2/pages/connect/api.mdx(25 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (4)
- GitHub Check: Lint Code Base
- GitHub Check: test
- GitHub Check: pnpm publish
- GitHub Check: validate-links
🔇 Additional comments (2)
docs-v2/pages/connect/api.mdx (2)
222-223: Well-structured type declarations!The TypeScript type declarations are clear, well-organized, and provide good type safety for the SDK client configuration.
Also applies to: 229-255
Line range hint
2170-3414: Comprehensive trigger management documentation!The documentation for trigger management is thorough and well-structured, covering all aspects of deployed triggers including events, webhooks, and workflows.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
docs-v2/pages/connect/api.mdx (3)
316-321: Consider adding URL validation for allowed origins.While the implementation is correct, consider adding validation to ensure that the allowed origins are valid URLs and follow the required format (e.g., proper protocol, no trailing slashes).
const validateUrl = (url: string): boolean => { try { new URL(url); return true; } catch { return false; } }; const requestOpts: ConnectTokenCreateOpts = { external_user_id: "{your_external_user_id}", allowed_origins: ["http://localhost:3000", "https://example.com"].filter(validateUrl), };
Line range hint
2077-2089: Consider making the webhook URL configurable.Instead of hardcoding the webhook URL, consider:
- Loading it from environment variables
- Making it configurable through a configuration file
- Generating it dynamically based on the environment
const requestOpts: DeployTriggerOpts = { triggerId: { key: "gitlab-new-issue", }, configuredProps: { gitlab: { authProvisionId: "apn_kVh9AoD", }, projectId: 45672541, }, externalUserId: "jverce", webhookUrl: process.env.WEBHOOK_URL || "https://events.example.com/gitlab-new-issue", };
3417-3422: Add explicit validation for workflow update success.Consider adding explicit validation to ensure that all provided workflow IDs were successfully updated:
const response: UpdateTriggerWorkflowsResponse = await pd.updateTriggerWorkflows(requestOpts); const { workflow_ids: confirmedIds, }: { workflow_ids: string[], } = response; // Verify that all workflow IDs were successfully updated const missingIds = workflowIds.filter(id => !confirmedIds.includes(id)); if (missingIds.length) { console.warn(`Some workflow IDs were not updated: ${missingIds.join(', ')}`); }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs-v2/pages/connect/api.mdx(25 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (4)
- GitHub Check: pnpm publish
- GitHub Check: test
- GitHub Check: Lint Code Base
- GitHub Check: validate-links
🔇 Additional comments (5)
docs-v2/pages/connect/api.mdx (5)
299-300: LGTM!The type declarations follow TypeScript naming conventions and provide proper type safety for the backend client.
306-313: LGTM!The client configuration is well-structured with clear comments about environment settings and required credentials.
324-332: LGTM!The response handling is well-typed and follows TypeScript best practices for object destructuring.
3485-3490: LGTM!The example response correctly demonstrates the expected format with realistic workflow IDs.
456-460: Handle credentials with caution when include_credentials is true.When
include_credentialsis set to true, ensure that:
- The credentials are never exposed in client-side code or logs
- The credentials are stored securely
- Access to the credentials is properly authenticated and authorized
✅ Verification successful
Secure credential handling practices verified
The codebase implements proper security measures for handling credentials:
- Credentials are processed server-side only
- OAuth and token-based authentication are properly implemented
- No evidence of credentials being exposed in logs or client-side code
- Documentation emphasizes secure credential handling practices
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Check for potential credential leaks in console.log statements rg -i "console\.(log|debug|info|warn|error).*credentials"Length of output: 59
Script:
#!/bin/bash # Search for credential-related patterns in code echo "=== Searching for credential handling patterns ===" rg -i "credentials?" -A 2 -B 2 echo "=== Checking security-related files ===" fd -i "security|auth" --type f --exec cat {} echo "=== Checking documentation for credential handling ===" fd "README|SECURITY" --type f --exec cat {}Length of output: 67529
| // The new list of workflow IDs that will listen to the deployed trigger | ||
| const workflowIds: string[] = [ | ||
| "p_ERRCzw", | ||
| "p_2LniLm", | ||
| ]; | ||
| const requestOpts: UpdateTriggerWorkflowsOpts = { | ||
| id: "dc_gzumK2e", | ||
| externalUserId: "jverce", | ||
| workflowIds, | ||
| }; |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add validation for workflow IDs.
Consider adding validation to ensure that:
- The workflow IDs array is not empty
- Each workflow ID follows the expected format (e.g., starts with 'p_')
- The workflow IDs exist in the system
const validateWorkflowId = (id: string): boolean => /^p_[A-Za-z0-9]{6}$/.test(id);
const workflowIds = [
"p_ERRCzw",
"p_2LniLm",
].filter(validateWorkflowId);
if (!workflowIds.length) {
throw new Error("No valid workflow IDs provided");
}| curl -X PUT \ | ||
| "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/webhooks/" \ | ||
| -H "Authorization: Bearer {access_token}" \ | ||
| -H "Content-Type: application/json" \ | ||
| -H "x-pd-environment: development" \ | ||
| -d '{"external_user_id": "{external_user_id}", "workflow_ids": ["p_ERRCzw", "p_2LniLm"]}' |
There was a problem hiding this comment.
Fix incorrect endpoint path in cURL example.
The cURL command uses /webhooks/ in the endpoint path but should use /workflows/ since this is updating workflow IDs:
- "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/webhooks/" \
+ "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/workflows/" \📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| curl -X PUT \ | |
| "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/webhooks/" \ | |
| -H "Authorization: Bearer {access_token}" \ | |
| -H "Content-Type: application/json" \ | |
| -H "x-pd-environment: development" \ | |
| -d '{"external_user_id": "{external_user_id}", "workflow_ids": ["p_ERRCzw", "p_2LniLm"]}' | |
| curl -X PUT \ | |
| "https://api.pipedream.com/v1/connect/{your_project_id}/deployed-triggers/{dcid}/workflows/" \ | |
| -H "Authorization: Bearer {access_token}" \ | |
| -H "Content-Type: application/json" \ | |
| -H "x-pd-environment: development" \ | |
| -d '{"external_user_id": "{external_user_id}", "workflow_ids": ["p_ERRCzw", "p_2LniLm"]}' |
2 participants
Changelog
WHY
To keep the docs up to date.
Summary by CodeRabbit
@pipedream/sdkpackage from1.2.0to1.2.1.