(docs) Invoke workflows for external users #14589
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
WalkthroughThe pull request introduces several enhancements to the documentation for Pipedream Connect and related APIs. Key additions include new sections for workflows and troubleshooting, updates to existing documentation for clarity and security, and the introduction of new parameters in code examples. The changes aim to improve user guidance, particularly regarding the handling of OAuth tokens, account connections, and workflow management. Changes
Possibly related PRs
Suggested labels
Suggested reviewers
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: 0
🧹 Outside diff range and nitpick comments (8)
docs-v2/pages/connect/workflows.mdx (3)
73-73: Fix grammatical error in the conditional statement.There's a grammatical error in the sentence.
-If you've don't have a test account, create one: +If you don't have a test account, create one:🧰 Tools
🪛 LanguageTool
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...(VE_DIDNT)
111-121: Improve TypeScript example formatting and add error handling.The TypeScript example could be improved for better readability and robustness:
- Add missing comma after the user ID parameter
- Include error handling example
await pd.invokeWorkflowForExternalUser( "{your_endpoint_url}", // pass the endpoint ID or full URL here - "{your_external_user_id}" // The end user's ID in your system + "{your_external_user_id}", // The end user's ID in your system { method: "POST", body: { message: "Hello World" } }, HTTPAuthType.OAuth // Will automatically send the Authorization header with a fresh token -) +).catch(error => { + console.error('Workflow invocation failed:', error); + // Handle error appropriately +});
101-109: Add security best practices note for credential handling.While the code correctly uses placeholders for sensitive information, it would be helpful to add a note about secure credential storage best practices.
Add a comment block above the client initialization:
// SECURITY BEST PRACTICES: // 1. Never hardcode credentials in your source code // 2. Use environment variables or a secure secret management service // 3. Rotate client secrets periodically // 4. Use the minimum required permissions for your OAuth clientdocs-v2/pages/connect/quickstart.mdx (2)
177-182: Consider enhancing environment configuration guidance.While the environment comment is helpful, consider adding a callout or note section above the code example to emphasize the importance of environment configuration and provide guidance on determining the correct environment.
Add a note section before the code example:
+<Callout type="info"> +The `environment` parameter should match your deployment environment: +- Use "development" when testing with development credentials +- Use "production" when deploying to production or testing with production credentials + +Ensure you're using the correct environment to avoid authentication issues. +</Callout>
Line range hint
187-195: Consider adding security best practices for credential handling.While the code examples and flow are clear, consider adding more explicit guidance on secure credential handling, particularly for the
include_credentialsparameter.Add security notes in the comments:
// Parse and return the data you need. These may contain credentials, - // which you should never return to the client + // SECURITY: Never expose raw credentials to the client. Instead: + // 1. Store credentials securely (e.g., encrypted in your database) + // 2. Return only necessary metadata (e.g., account ID, user email) + // 3. Use environment variables or a secure secrets managerAlso applies to: 213-221
docs-v2/pages/connect/api.mdx (2)
193-198: Excellent improvements to security and consistency in client initialization examples.The changes across all client initialization examples demonstrate several improvements:
- Added environment context for better clarity
- Standardized sensitive information placeholders for better security
- Consistent structure across all examples
- Added projectId parameter for proper scoping
Consider adding a note about the importance of securing these credentials in production environments, perhaps recommending environment variables or secure credential management systems.
Also applies to: 212-217, 301-306, 469-474, 490-495, 613-618, 631-636, 697-702, 715-720, 781-786, 799-804, 861-866, 879-884
Line range hint
1-924: Consider enhancing error response documentation.While the documentation is comprehensive, it would be beneficial to include specific error response examples and status codes for each endpoint, helping developers handle error cases more effectively.
docs-v2/pages/workflows/triggers.mdx (1)
Line range hint
146-215: LGTM! Well-structured code examples for OAuth authentication.The examples effectively demonstrate OAuth authentication across TypeScript, Node.js, and cURL. The progression from obtaining an access token to using it in requests is clear and helpful.
Consider adding a note about securely storing the OAuth credentials, perhaps referencing Pipedream's built-in secret management capabilities.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (7)
docs-v2/pages/connect/_meta.json(1 hunks)docs-v2/pages/connect/api.mdx(17 hunks)docs-v2/pages/connect/quickstart.mdx(2 hunks)docs-v2/pages/connect/workflows.mdx(1 hunks)docs-v2/pages/rest-api/index.mdx(2 hunks)docs-v2/pages/workflows/index.mdx(1 hunks)docs-v2/pages/workflows/triggers.mdx(3 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs-v2/pages/workflows/index.mdx
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/workflows.mdx
[uncategorized] ~57-~57: Possible missing article found.
Context: ...nt — you can select the option to Use end user's auth via Connect: <div classN...
(AI_HYDRA_LEO_MISSING_THE)
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...
(VE_DIDNT)
🔇 Additional comments (9)
docs-v2/pages/connect/_meta.json (1)
11-13: LGTM! The new section is well-positioned.
The addition of the "workflows" section follows a logical progression in the documentation structure, placed appropriately after the quickstart guide and before the API reference.
Let's verify that the corresponding documentation file exists:
✅ Verification successful
Workflows documentation file exists as expected ✅
The verification confirms that docs-v2/pages/connect/workflows.mdx exists, which aligns with the navigation structure defined in _meta.json.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Check if the workflows documentation file exists
# Expected: Should find the corresponding .mdx file
fd -e mdx workflows docs-v2/pages/connect/
Length of output: 80
docs-v2/pages/connect/workflows.mdx (2)
1-29: Well-structured introduction with clear explanations!
The introduction effectively explains workflows, their capabilities, and features while maintaining good readability with appropriate visual aids and links to detailed documentation.
1-176: Excellent documentation structure and content!
The documentation is well-organized, comprehensive, and provides clear instructions with appropriate examples. The use of visual aids, code examples, and step-by-step guides makes it very user-friendly.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~57-~57: Possible missing article found.
Context: ...nt — you can select the option to Use end user's auth via Connect: <div classN...
(AI_HYDRA_LEO_MISSING_THE)
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...
(VE_DIDNT)
docs-v2/pages/connect/quickstart.mdx (1)
203-208: LGTM!
The JavaScript implementation maintains consistency with the TypeScript example and follows the same secure practices for handling sensitive information.
docs-v2/pages/connect/api.mdx (2)
126-126: LGTM! Clear and well-structured documentation.
The new workflows section effectively directs users to the dedicated documentation while maintaining a clear and concise overview.
243-243: LGTM! Consistent placeholder usage in API examples.
The API endpoint examples maintain consistency with the new placeholder format, making the documentation more uniform and easier to follow.
Also applies to: 870-870, 888-888
docs-v2/pages/workflows/triggers.mdx (2)
154-155: LGTM! Consistent use of placeholders for sensitive information.
The placeholders for OAuth credentials follow a clear, consistent format that helps users understand what values to insert.
Also applies to: 178-179, 202-203
197-214: LGTM! Clear and comprehensive cURL example for OAuth flow.
The cURL example effectively demonstrates the complete OAuth flow, from token generation to API usage, with helpful comments guiding users through each step.
docs-v2/pages/rest-api/index.mdx (1)
Line range hint 687-700: LGTM! Clear and well-documented search example.
The example effectively demonstrates how to search for components using natural language queries, with a clear request and response format.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (5)
docs-v2/pages/connect/workflows.mdx (5)
11-13: Consider using versioned image URLs.The current image URL contains what appears to be a timestamp (
v1730935490). To ensure long-term reliability, consider using a versioned URL or storing images in the repository's assets directory.
73-73: Fix grammatical error.The sentence "If you've don't have a test account" contains incorrect grammar.
-If you've don't have a test account, create one: +If you don't have a test account, create one:🧰 Tools
🪛 LanguageTool
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...(VE_DIDNT)
103-104: Enhance environment selection guidance.The environment selection comments could be more explicit about when to use each environment. Consider adding a note explaining that:
- 'development' is for testing and development purposes
- 'production' is for live/production deployments
- environment: "development", // change to production if running for a test production account, or in production + environment: "development", // Use 'development' for testing, 'production' for live deploymentsAlso applies to: 130-131, 167-167
176-176: Complete the Errors section.The "Errors" section appears to be incomplete. This section should include:
- Common error scenarios
- Error response formats
- Troubleshooting guidance
- Error handling best practices
Would you like me to help draft content for the Errors section?
101-102: Add security best practices section.Consider adding security recommendations for handling client credentials and tokens:
- Secure storage of OAuth credentials
- Token rotation practices
- Rate limiting considerations
- Access control best practices
Would you like me to help draft a security best practices section?
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
docs-v2/pages/connect/workflows.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/workflows.mdx
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...
(VE_DIDNT)
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (2)
docs-v2/pages/connect/workflows.mdx (2)
73-73: Fix grammatical error in the test account section.There's a grammatical error in the sentence.
-If you've don't have a test account, create one: +If you don't have a test account, create one:🧰 Tools
🪛 LanguageTool
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...(VE_DIDNT)
101-109: Add security note about credential handling.Consider adding a comment about secure credential storage best practices, particularly for production environments.
// These secrets should be saved securely and passed to your environment +// IMPORTANT: Never hardcode these values or commit them to version control const pd = createBackendClient({
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
docs-v2/pages/connect/workflows.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/workflows.mdx
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...
(VE_DIDNT)
🔇 Additional comments (2)
docs-v2/pages/connect/workflows.mdx (2)
1-29: Well-structured introduction and overview section!
The introduction effectively explains workflows and their capabilities, with good use of visual aids and clear organization of information.
17-17: Verify environment variable configuration.
The documentation uses {process.env.PUBLIC_APPS} to display the number of integrated apps.
✅ Verification successful
Environment variable PUBLIC_APPS is properly configured
The environment variable is correctly configured in next.config.js with a value of "2,200" and is consistently used across multiple documentation files to display the number of integrated apps. This is a valid usage pattern for Next.js documentation.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Verify the environment variable usage in other documentation files
rg -l "PUBLIC_APPS" docs-v2/
Length of output: 504
Script:
#!/bin/bash
# Check how PUBLIC_APPS is configured in next.config.js
cat docs-v2/next.config.js
# Check a few examples of how it's used in documentation
echo "=== Usage in index.mdx ==="
rg "PUBLIC_APPS" docs-v2/pages/index.mdx -C 2
echo "=== Usage in connected-accounts/index.mdx ==="
rg "PUBLIC_APPS" docs-v2/pages/connected-accounts/index.mdx -C 2
Length of output: 3473
docs-v2/pages/connect/workflows.mdx
Outdated
| </Tabs> | ||
| </Steps> | ||
|
|
||
| ## Errors |
There was a problem hiding this comment.
Complete the Errors section.
The "Errors" section is currently empty. This section should include:
- Common error scenarios
- Error codes and their meanings
- Troubleshooting steps
- Example error responses
This information is crucial for users to handle errors properly in their implementations.
Would you like me to help draft the content for the Errors section?
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Outside diff range and nitpick comments (5)
docs-v2/pages/connect/environments.mdx (2)
8-8: Consider adding OAuth client usage detailsWhile the explanation is good, it would be helpful to clarify:
- Which OAuth clients are available
- Any limitations on OAuth client usage
- Whether this applies to all integrations or specific ones
18-20: Enhance warning with security implicationsWhile the warning is clear about usage, consider adding security implications:
- Development mode might expose sensitive OAuth scopes
- Test data could be mixed with production data if not careful
docs-v2/pages/connect/workflows.mdx (3)
73-73: Fix grammatical error.There's a grammatical error in the sentence: "If you've don't have a test account".
Apply this correction:
-If you've don't have a test account, create one: +If you don't have a test account, create one:🧰 Tools
🪛 LanguageTool
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...(VE_DIDNT)
102-104: Consider using environment constants.The environment value is hardcoded as "development" with a comment to change it for production. Consider using a constant or configuration value to prevent potential errors from forgotten manual changes.
Consider refactoring to use an environment variable or configuration constant:
const environment = process.env.PIPEDREAM_ENVIRONMENT || "development"; const pd = createBackendClient({ environment, // ... rest of the config });Also applies to: 130-131
187-187: Fix missing preposition in error description.The sentence is missing the preposition "to" after "connected an account".
Apply this correction:
-but the user hasn't connected an account one or more of the apps +but the user hasn't connected an account to one or more of the apps🧰 Tools
🪛 LanguageTool
[uncategorized] ~187-~187: Possible missing preposition found.
Context: ...ut the user hasn't connected an account one or more of the apps that are configured...(AI_HYDRA_LEO_MISSING_TO)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (3)
docs-v2/pages/connect/_meta.json(2 hunks)docs-v2/pages/connect/environments.mdx(1 hunks)docs-v2/pages/connect/workflows.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs-v2/pages/connect/_meta.json
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/workflows.mdx
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...
(VE_DIDNT)
[uncategorized] ~187-~187: Possible missing preposition found.
Context: ...ut the user hasn't connected an account one or more of the apps that are configured...
(AI_HYDRA_LEO_MISSING_TO)
🔇 Additional comments (2)
docs-v2/pages/connect/environments.mdx (1)
1-7: LGTM!
The import statement and introduction are clear and well-structured.
docs-v2/pages/connect/workflows.mdx (1)
17-17: Verify the environment variable interpolation.
The line references {process.env.PUBLIC_APPS} which needs verification to ensure it's properly configured in the build environment.
Let's check for the environment variable usage:
#!/bin/bash
# Search for PUBLIC_APPS environment variable definition
rg "PUBLIC_APPS.*=" --type-add config:*.{json,env,yaml,yml} --type config|
|
||
| ## How to specify environment | ||
|
|
||
| You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the enviromment is set to `production`. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `project_environment`. | ||
| You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the enviromment is set to `production`. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `environment`. |
There was a problem hiding this comment.
Fix typos in environment specification
There are two typos in this line:
- "enviromment" should be "environment"
- "succesfully" should be "successfully"
-You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the enviromment is set to `production`. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `environment`.
+You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the environment is set to `production`. When users successfully connect their account, Pipedream saves it for that `external_user_id` in the specified `environment`.📝 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.
| You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the enviromment is set to `production`. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `environment`. | |
| You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the environment is set to `production`. When users successfully connect their account, Pipedream saves it for that `external_user_id` in the specified `environment`. |
| import Callout from '@/components/Callout' | ||
|
|
||
| # Environments | ||
|
|
||
| Pipedream Connect projects support two environments: `development` and `production`. | ||
|
|
||
| 1. Connected accounts and credentials stored in `development` remain separate from `production`. | ||
| 2. In `development`, you can use the official Pipedream OAuth apps, so you can test integrations without creating your own OAuth client. | ||
| 2. In `development`, you can use the official Pipedream OAuth clients, so you can test integrations without creating your own OAuth client, and you can also use features that are typically only available on higher paid tiers, like [running workflows on behalf of your end users](/connect/workflows). | ||
|
|
||
| ## How to specify environment | ||
|
|
||
| You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the enviromment is set to `production`. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `project_environment`. | ||
| You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. By default, the enviromment is set to `production`. When users succesfully connect their account, Pipedream saves it for that `external_user_id` in the specified `environment`. | ||
|
|
||
| ## Using development mode | ||
|
|
||
| When connecting an account in `development` mode, the end user who is connecting their account must be signed in to pipedream.com. | ||
|
|
||
| <Callout type="warning"> | ||
| `development` mode should only be used by you and your team for testing. When you're ready to test with real users, switch to `production`. | ||
| </Callout> |
There was a problem hiding this comment.
💡 Codebase verification
Missing referenced documentation file
- The file
docs-v2/pages/connect/api/.mdxreferenced in/connect/api/#create-a-new-tokendoes not exist.
🔗 Analysis chain
Verify documentation cross-references
Let's ensure all referenced documentation sections exist and are accessible.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Verify that referenced documentation sections exist
# Check for referenced documentation files
echo "Checking for referenced documentation files..."
for path in "/connect/workflows" "/connect/api/#create-a-new-token"; do
# Remove the hash part for file checking
file_path="docs-v2/pages${path%#*}.mdx"
if ! fd -t f "${file_path##*/}" | grep -q "$file_path"; then
echo "Warning: Referenced file not found: $file_path"
fi
done
Length of output: 602
| <div className="mt-4"> | ||
| <img width="500px" src="https://res.cloudinary.com/pipedreamin/image/upload/v1730935490/docs/pCBdtm7Ca9CdPHTe76PwfzddY_qowz2v.avif" /> | ||
| </div> |
There was a problem hiding this comment.
💡 Codebase verification
Multiple Image URLs Contain Expiring Timestamps
Several image URLs in the documentation use timestamped Cloudinary URLs, which may lead to broken images in the future. Consider using permanent URL structures or implementing a stable versioning strategy.
🔗 Analysis chain
Consider using a more permanent image URL structure.
The current Cloudinary URL contains what appears to be a timestamp (v1730935490). To ensure long-term stability, consider using a more permanent URL structure or implementing a versioning strategy that doesn't rely on timestamps.
Let's verify if this image URL pattern is consistent across the documentation:
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Search for similar Cloudinary URLs with timestamps
rg -l "cloudinary.*v[0-9]{10}" --type mdx
Length of output: 268
Script:
#!/bin/bash
# Display lines 11-13 of the specified MDX file
sed -n '11,13p' docs-v2/pages/connect/workflows.mdx
Length of output: 216
Script:
#!/bin/bash
# Search for Cloudinary URLs with a timestamp pattern in the specified MDX file
rg 'https://res\.cloudinary\.com/.*/v\d+/.+\.avif' docs-v2/pages/connect/workflows.mdx
Length of output: 223
Script:
#!/bin/bash
# Search for all Cloudinary URLs with a versioning timestamp in MDX files
rg 'https://res\.cloudinary\.com/.*/v\d+/.+\.(avif|png|jpg|jpeg|gif)' --type mdx
Length of output: 110
Script:
#!/bin/bash
# Search for all Cloudinary URLs with a versioning timestamp in MDX files
rg 'https://res\.cloudinary\.com/.*/v\d+/.+\.(avif|png|jpg|jpeg|gif)' -g '*.mdx'
Length of output: 32589
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (1)
docs-v2/pages/connect/workflows.mdx (1)
73-73: Fix grammatical errorChange "If you've don't have" to "If you don't have"
-If you've don't have a test account, create one: +If you don't have a test account, create one:🧰 Tools
🪛 LanguageTool
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...(VE_DIDNT)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
docs-v2/pages/connect/troubleshooting.mdx(1 hunks)docs-v2/pages/connect/workflows.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs-v2/pages/connect/troubleshooting.mdx
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/workflows.mdx
[uncategorized] ~57-~57: Possible missing article found.
Context: ...nt — you can select the option to Use end user's auth via Connect: <div classN...
(AI_HYDRA_LEO_MISSING_THE)
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...
(VE_DIDNT)
🔇 Additional comments (2)
docs-v2/pages/connect/workflows.mdx (2)
98-171: LGTM! Well-structured code examples
The code examples are well-organized, properly documented, and follow security best practices:
- Consistent use of placeholders for sensitive information
- Clear comments about secure credential handling
- Comprehensive examples in multiple languages
176-192: LGTM! Comprehensive error documentation
The Errors section is now complete and well-structured, covering:
- Common error scenarios
- Clear explanations of causes
- Actionable resolution steps
- Links to relevant documentation
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (5)
docs-v2/pages/connect/troubleshooting.mdx (5)
5-9: Consider using a code block for the error message.While the content is good, the error message would be more readable in a code block format.
-### Error creating a Connect token ->Error creating token: Error: Failed to obtain OAuth token: Response Error: 401 Unauthorized +### Error creating a Connect token +``` +Error creating token: Error: Failed to obtain OAuth token: Response Error: 401 Unauthorized +```
10-12: Consider adding common scenarios.The section would benefit from a brief list of typical situations where these errors occur.
### Error connecting an account Most errors when connecting an account are related to the [Connect token](/connect/tokens), which Pipedream validates from the Connect iFrame. +Common scenarios include: +- Attempting to reuse an expired token +- Using an invalid or malformed token +- Incorrect app configuration
13-16: Improve error message formatting.The error messages would be more readable with consistent formatting and without HTML tags.
#### Possible errors ->- This link has expired. Please request a new one from the app developer. <br /> ->- This session has expired. Please refresh the page to try again. +``` +This link has expired. Please request a new one from the app developer. +``` + +``` +This session has expired. Please refresh the page to try again. +```
24-26: Improve sentence structure and clarity.The explanation could be more concise and active.
-Connect tokens have explicit expiries, and are only able to be used once. Try generating a new token and trying again. +Connect tokens have explicit expiries and can only be used once. Generate a new token and try again.🧰 Tools
🪛 LanguageTool
[style] ~25-~25: As a shorter alternative for ‘able to’, consider using “can only”.
Context: ...nect tokens have explicit expiries, and are only able to be used once. Try generating a new toke...(BE_ABLE_TO)
[style] ~25-~25: Avoid the passive voice after ‘to be able to’.
Context: ...explicit expiries, and are only able to be used once. Try generating a new token and tr...(ABLE_TO_PASSIVE)
31-33: Enhance the connection failure section.Consider adding more troubleshooting steps and potential solutions.
### Connection failed. Please retry or contact support. - The user may have closed the OAuth popup window without completing authorization. +- Check if: + - Pop-up blockers are disabled + - The OAuth provider's service is available + - The OAuth configuration is correct +- Recommend users to: + - Clear browser cache and cookies + - Try a different browser + - Ensure stable internet connection
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
docs-v2/pages/connect/tokens.mdx(2 hunks)docs-v2/pages/connect/troubleshooting.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/troubleshooting.mdx
[style] ~25-~25: As a shorter alternative for ‘able to’, consider using “can only”.
Context: ...nect tokens have explicit expiries, and are only able to be used once. Try generating a new toke...
(BE_ABLE_TO)
[style] ~25-~25: Avoid the passive voice after ‘to be able to’.
Context: ...explicit expiries, and are only able to be used once. Try generating a new token and tr...
(ABLE_TO_PASSIVE)
🔇 Additional comments (3)
docs-v2/pages/connect/tokens.mdx (2)
1-2: LGTM: Clean import statement
The import follows standard MDX practices and is properly placed at the top of the file.
14-16: Important limitation is clearly documented
The callout effectively communicates critical token limitations. The placement is appropriate, ensuring users understand these constraints before implementing token creation.
Let's verify this limitation is consistently documented across the API reference:
✅ Verification successful
Token limitations are consistently documented
The token expiry time and single-use restrictions are properly detailed across all relevant documentation sections.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Check if token limitations are consistently documented
# Expected results: Find mentions of token expiry time and single-use limitation
# Search for token expiry documentation
echo "Checking token expiry documentation..."
rg -i "token.*expiry|expir.*token|4.?hour" docs-v2/pages/connect/
# Search for single-use token documentation
echo "Checking single-use token documentation..."
rg -i "token.*once|single.?use.*token" docs-v2/pages/connect/
# Check API reference for these limitations
echo "Checking API reference..."
rg -i "token" docs-v2/pages/connect/api.mdx
Length of output: 5075
docs-v2/pages/connect/troubleshooting.mdx (1)
1-4: LGTM! Clear and concise introduction.
The introduction effectively sets the context for the troubleshooting guide.
| #### Troubleshooting steps | ||
| - Pipedream typically returns an explicit error message in the HTTP response of the token validation network call directly from the iFrame in the client. | ||
| - To check for errors, start the account connection flow in a browser and open the developer console to view the network requests. | ||
| - Look for `https://api.pipedream.com/v1/connect/tokens/{connect_token}/validate?app_id{app_slug}` and check the response for any error messages. |
There was a problem hiding this comment.
Fix the API endpoint format.
There's a formatting issue in the URL parameters.
-Look for `https://api.pipedream.com/v1/connect/tokens/{connect_token}/validate?app_id{app_slug}` and check the response for any error messages.
+Look for `https://api.pipedream.com/v1/connect/tokens/{connect_token}/validate?app_id={app_slug}` and check the response for any error messages.📝 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.
| - Look for `https://api.pipedream.com/v1/connect/tokens/{connect_token}/validate?app_id{app_slug}` and check the response for any error messages. | |
| Look for `https://api.pipedream.com/v1/connect/tokens/{connect_token}/validate?app_id={app_slug}` and check the response for any error messages. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
docs-v2/pages/connect/workflows.mdx (3)
19-27: Consider enhancing the features list with examplesThe built-in features list would be more helpful with brief examples or descriptions. For instance:
- What kind of flow control is available?
- What are the concurrency limits?
- What types of data can be stored in key-value stores?
73-73: Fix grammatical errorChange "If you've don't have" to "If you don't have"
🧰 Tools
🪛 LanguageTool
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...(VE_DIDNT)
111-121: Improve TypeScript example consistency and documentationThe TypeScript example could be improved:
- Add type annotations for the parameters
- Document the return type
- Add comments explaining the parameters
-await pd.invokeWorkflowForExternalUser( +// Invoke a workflow for an external user +// @param endpointUrl - The workflow's HTTP endpoint URL +// @param externalUserId - The user's ID in your system +// @param options - Request options including method and body +// @returns Promise<Response> +await pd.invokeWorkflowForExternalUser( "{your_endpoint_url}", // pass the endpoint ID or full URL here "{your_external_user_id}" // The end user's ID in your system { method: "POST", body: { message: "Hello World" } }, HTTPAuthType.OAuth // Will automatically send the Authorization header with a fresh token )
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (4)
docs-v2/pages/connect/api.mdx(18 hunks)docs-v2/pages/connect/environments.mdx(1 hunks)docs-v2/pages/connect/tokens.mdx(3 hunks)docs-v2/pages/connect/workflows.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (3)
- docs-v2/pages/connect/api.mdx
- docs-v2/pages/connect/environments.mdx
- docs-v2/pages/connect/tokens.mdx
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/workflows.mdx
[uncategorized] ~57-~57: Possible missing article found.
Context: ...nt — you can select the option to Use end user's auth via Connect: <div classN...
(AI_HYDRA_LEO_MISSING_THE)
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...
(VE_DIDNT)
🔇 Additional comments (2)
docs-v2/pages/connect/workflows.mdx (2)
176-192: LGTM! Comprehensive error documentation
The errors section is well-structured with:
- Clear error descriptions
- Actionable resolution steps
- Relevant documentation links
1-192: Overall documentation is well-structured and comprehensive
The documentation provides a clear guide for running workflows for end users, with:
- Clear step-by-step instructions
- Multiple code examples
- Comprehensive error handling
- Proper cross-linking to related documentation
The suggested improvements are minor and don't impact the overall quality of the documentation.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~57-~57: Possible missing article found.
Context: ...nt — you can select the option to Use end user's auth via Connect: <div classN...
(AI_HYDRA_LEO_MISSING_THE)
[grammar] ~73-~73: The text is not correct, but LanguageTool has no suggestions about how to correct the text.
Context: ...he workflow](#invoke-the-workflow). If you've don't have a test account, create one: - If ...
(VE_DIDNT)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (6)
docs-v2/pages/connect/troubleshooting.mdx (6)
5-10: Consider enhancing the troubleshooting guidance.While the error message and basic solution are provided, users would benefit from:
- Step-by-step verification process for client credentials
- Example of correct client ID/secret format
- Common causes of 401 errors
Would you like me to help draft the additional content?
23-23: Add missing comma for better readability.-Pipedream typically returns an explicit error message in the HTTP response of the token validation network call directly from the iFrame in the client. +Pipedream typically returns an explicit error message in the HTTP response of the token validation network call, directly from the iFrame in the client.🧰 Tools
🪛 LanguageTool
[uncategorized] ~23-~23: Possible missing comma found.
Context: ...esponse of the token validation network call directly from the iFrame in the client....(AI_HYDRA_LEO_MISSING_COMMA)
27-29: Enhance code block formatting.Add language specification to the code block for better syntax highlighting.
-``` +```http https://api.pipedream.com/v1/connect/tokens--- `37-37`: **Improve sentence structure and clarity.** ```diff -Connect tokens expire, and are only able to be used once. +Connect tokens expire and can only be used once.🧰 Tools
🪛 LanguageTool
[style] ~37-~37: As a shorter alternative for ‘able to’, consider using “can only”.
Context: ...try again._ Connect tokens expire, and are only able to be used once. Try generating a new toke...(BE_ABLE_TO)
[style] ~37-~37: Avoid the passive voice after ‘to be able to’.
Context: ...ect tokens expire, and are only able to be used once. Try generating a new token and tr...(ABLE_TO_PASSIVE)
43-45: Expand the connection failure guidance.This section would benefit from:
- Additional scenarios that might cause connection failures
- Steps to prevent premature window closure
- Recovery steps for users
- Best practices for implementing the OAuth flow
Would you like me to help draft the expanded content?
1-45: Consider enhancing the documentation structure.To improve the troubleshooting guide's effectiveness, consider:
- Adding a table of contents for easy navigation
- Including a "Common Solutions" quick reference section at the top
- Adding code examples for each error scenario
- Including a decision tree or flowchart for problem diagnosis
Would you like assistance in implementing these structural improvements?
🧰 Tools
🪛 LanguageTool
[uncategorized] ~23-~23: Possible missing comma found.
Context: ...esponse of the token validation network call directly from the iFrame in the client....(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~37-~37: As a shorter alternative for ‘able to’, consider using “can only”.
Context: ...try again._ Connect tokens expire, and are only able to be used once. Try generating a new toke...(BE_ABLE_TO)
[style] ~37-~37: Avoid the passive voice after ‘to be able to’.
Context: ...ect tokens expire, and are only able to be used once. Try generating a new token and tr...(ABLE_TO_PASSIVE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
docs-v2/pages/connect/troubleshooting.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/troubleshooting.mdx
[uncategorized] ~23-~23: Possible missing comma found.
Context: ...esponse of the token validation network call directly from the iFrame in the client....
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~37-~37: As a shorter alternative for ‘able to’, consider using “can only”.
Context: ...try again._ Connect tokens expire, and are only able to be used once. Try generating a new toke...
(BE_ABLE_TO)
[style] ~37-~37: Avoid the passive voice after ‘to be able to’.
Context: ...ect tokens expire, and are only able to be used once. Try generating a new token and tr...
(ABLE_TO_PASSIVE)
🔇 Additional comments (1)
docs-v2/pages/connect/troubleshooting.mdx (1)
1-4: LGTM! Clear and concise introduction.
The introduction effectively sets up the document's purpose and scope.
…ws-for-external-user
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
docs-v2/pages/connect/workflows.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/workflows.mdx
[style] ~216-~216: As a shorter alternative for ‘able to’, consider using “can”.
Context: ...on requires a higher tier plan - Anyone is able to run workflows for your end users in `de...
(BE_ABLE_TO)
🔇 Additional comments (3)
docs-v2/pages/connect/workflows.mdx (3)
14-16: Consider using a permanent image URL structure
The Cloudinary URL contains a timestamp (v1730935490) which may lead to broken images in the future.
Consider implementing a more permanent URL structure or versioning strategy that doesn't rely on timestamps.
201-217: Error section is now complete and well-documented
The error section has been properly populated with common scenarios, their causes, and resolution steps. This addresses the previous review comment about the empty error section.
Consider this minor language improvement:
-Anyone is able to run workflows for your end users in `development`.
+Anyone can run workflows for your end users in `development`.🧰 Tools
🪛 LanguageTool
[style] ~216-~216: As a shorter alternative for ‘able to’, consider using “can”.
Context: ...on requires a higher tier plan - Anyone is able to run workflows for your end users in `de...
(BE_ABLE_TO)
1-217: Documentation is comprehensive and well-structured
The documentation successfully covers all aspects of running workflows for end users, including:
- Clear step-by-step instructions
- Security considerations with OAuth
- Multiple code examples
- Comprehensive error handling
🧰 Tools
🪛 LanguageTool
[style] ~216-~216: As a shorter alternative for ‘able to’, consider using “can”.
Context: ...on requires a higher tier plan - Anyone is able to run workflows for your end users in `de...
(BE_ABLE_TO)
| ```javascript | ||
| import { createBackendClient } from "@pipedream/sdk"; | ||
|
|
||
| // These secrets should be saved securely and passed to your environment | ||
| const client = 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 response = await client.invokeWorkflowForExternalUser( | ||
| "{your_endpoint_url}", // pass the endpoint ID or full URL here | ||
| "{your_external_user_id}" // The end user's ID in your system | ||
| { | ||
| method: "POST", | ||
| body: { | ||
| message: "Hello World" | ||
| } | ||
| } | ||
| ) | ||
| ``` | ||
| </Tabs.Tab> |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add error handling to Node.js example
The Node.js example should include try-catch blocks to handle potential errors, similar to best practices shown in other examples.
Consider updating the example:
import { createBackendClient } from "@pipedream/sdk";
// These secrets should be saved securely and passed to your environment
const client = 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 response = await client.invokeWorkflowForExternalUser(
- "{your_endpoint_url}", // pass the endpoint ID or full URL here
- "{your_external_user_id}" // The end user's ID in your system
- {
- method: "POST",
- body: {
- message: "Hello World"
- }
- }
-)
+try {
+ const response = await client.invokeWorkflowForExternalUser(
+ "{your_endpoint_url}", // pass the endpoint ID or full URL here
+ "{your_external_user_id}", // The end user's ID in your system
+ {
+ method: "POST",
+ body: {
+ message: "Hello World"
+ }
+ }
+ );
+ console.log('Workflow executed successfully:', response);
+} catch (error) {
+ console.error('Error executing workflow:', error);
+ // Handle specific error types as needed
+}📝 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.
| ```javascript | |
| import { createBackendClient } from "@pipedream/sdk"; | |
| // These secrets should be saved securely and passed to your environment | |
| const client = 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 response = await client.invokeWorkflowForExternalUser( | |
| "{your_endpoint_url}", // pass the endpoint ID or full URL here | |
| "{your_external_user_id}" // The end user's ID in your system | |
| { | |
| method: "POST", | |
| body: { | |
| message: "Hello World" | |
| } | |
| } | |
| ) | |
| ``` | |
| </Tabs.Tab> | |
| ```javascript | |
| import { createBackendClient } from "@pipedream/sdk"; | |
| // These secrets should be saved securely and passed to your environment | |
| const client = 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}" | |
| }); | |
| try { | |
| const response = await client.invokeWorkflowForExternalUser( | |
| "{your_endpoint_url}", // pass the endpoint ID or full URL here | |
| "{your_external_user_id}", // The end user's ID in your system | |
| { | |
| method: "POST", | |
| body: { | |
| message: "Hello World" | |
| } | |
| } | |
| ); | |
| console.log('Workflow executed successfully:', response); | |
| } catch (error) { | |
| console.error('Error executing workflow:', error); | |
| // Handle specific error types as needed | |
| } | |
| ``` | |
| </Tabs.Tab> |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (1)
docs-v2/pages/connect/index.mdx (1)
56-60: Consider enhancing the warning with additional context and placement.The warning effectively communicates the account connection limitation. However, consider these enhancements:
- Move this warning earlier in the document, possibly right after the "Getting started" section, as it's a critical limitation that affects implementation decisions.
- Add guidance on potential workarounds or best practices for handling multiple accounts.
- Include a link to the troubleshooting documentation for related issues.
Consider updating the callout with additional context:
<Callout type="warning"> Connect currently supports one connected account per user / app / environment combination. So if user `abc-123` in your application connects their Slack account in `production`, then that same user connects a different Slack workspace (also in `production`), the first connected account will get overwritten in Pipedream and replaced by the second. + +For applications requiring multiple accounts: +- Consider using separate environments for different account connections +- See our [troubleshooting guide](/connect/troubleshooting) for common issues +- Contact support for guidance on enterprise solutions </Callout>
| <Callout type="warning"> | ||
| Connect currently supports one connected account per user / app / environment combination. | ||
|
|
||
| So if user `abc-123` in your application connects their Slack account in `production`, then that same user connects a different Slack workspace (also in `production`), the first connected account will get overwritten in Pipedream and replaced by the second. | ||
| </Callout> |
There was a problem hiding this comment.
💡 Codebase verification
Documentation inconsistency found regarding account connection limitations
The warning about one connected account per user/app/environment is only mentioned in the Connect documentation, but this important limitation should be documented in other relevant sections. Key areas needing attention:
- The general Connected Accounts documentation (
docs-v2/pages/connected-accounts/index.mdx) doesn't mention this limitation, despite being the primary reference for account connections - The FAQ section in Connected Accounts discusses various account-related questions but misses this key limitation
- The Troubleshooting sections don't address this common scenario where users might try to connect multiple accounts
🔗 Analysis chain
Verify documentation consistency regarding account limitations.
Let's ensure this limitation is consistently documented across related sections.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Search for related mentions of account limitations in other documentation files
echo "Searching for related documentation about account limitations..."
rg -t md -t mdx "account.*limitation|one.*account.*per|multiple.*account" docs-v2/
# Check if the troubleshooting guide exists and contains relevant information
echo "Verifying troubleshooting documentation..."
rg -t md -t mdx "troubleshooting" docs-v2/pages/connect/
Length of output: 431
Script:
#!/bin/bash
# Search for related mentions of account limitations using ripgrep without file type filters
echo "Searching for related documentation about account limitations..."
rg "account.*limitation|one.*account.*per|multiple.*account" docs-v2/
# Check for any mentions of connected accounts and their limitations
echo "Checking for connected account mentions..."
rg "connected account" docs-v2/
# Look for any troubleshooting sections
echo "Verifying troubleshooting documentation..."
rg "troubleshooting" docs-v2/
Length of output: 22822
Summary by CodeRabbit
Release Notes
New Features
Documentation Enhancements
Bug Fixes