Document the Connect component API #14931
Conversation
jverce
added
question
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
1 Skipped Deployment
|
|
Warning Rate limit exceeded@jverce has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 0 minutes and 23 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (2)
WalkthroughThe pull request introduces updates across multiple files, including the addition of Changes
Possibly related PRs
Suggested labels
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 (
|
|
@jverce is attempting to deploy a commit to the Pipedreamers Team on Vercel. A member of the Team first needs to authorize it. |
jverce
force-pushed
the
jay/money-1912-docs-api-sdk-action-configure-run-triggerdeploy-etc
branch
4 times, most recently
from
1b56519 to
866bd1a
Compare
* Add new left-nav link to the new docs * Describe how to use the new API to configure and run a component * Document the new API endpoints in the API/SDK reference section * Add the exact `pnpm` entry to `.tool-versions` in the docs directory * Minor fixes in the docstring of the component configuration methods * Update SDK changelog for the previous and this current changes
jverce
force-pushed
the
jay/money-1912-docs-api-sdk-action-configure-run-triggerdeploy-etc
branch
2 times, most recently
from
3afa618 to
a8eed87
Compare
…re-run-triggerdeploy-etc
jverce
force-pushed
the
jay/money-1912-docs-api-sdk-action-configure-run-triggerdeploy-etc
branch
from
a8eed87 to
e03588d
Compare
![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
🧹 Outside diff range and nitpick comments (9)
packages/sdk/CHANGELOG.md (2)
15-15: Consider adding more details about the removed code.The changelog entry "Remove deprecated asynchronous response handling code" could benefit from more context about what was removed and potential migration steps for users.
68-69: Fix hyphenation in "long running".The term should be hyphenated as "long-running" when used as a compound adjective.
-The backend client now correctly uses asynchronous messaging to handle long -running operations. +The backend client now correctly uses asynchronous messaging to handle long- +running operations.🧰 Tools
🪛 LanguageTool
[misspelling] ~68-~68: This word is normally spelled with a hyphen.
Context: ...y uses asynchronous messaging to handle long running operations. - Updated the backend comma...(EN_COMPOUNDS_LONG_RUNNING)
docs-v2/pages/connect/components.mdx (3)
23-23: Use the Steps component for better navigation.The documentation would benefit from using the
Stepscomponent to create numbered sections, similar topages/connect/workflows.mdx.-## How to run components for your end users +<Steps> +## How to run components for your end users
107-109: Fix typo and improve clarity.There's a typo ("not" instead of "note") and the sentence structure could be improved.
-the necessary data, and sending these options back as a response. Please not -that this logic is not implemented by the API itself, but by the component's -code; in particular, the `options` function of the corresponding prop. +the necessary data, and sending these options back as a response. Please note +that this logic is implemented by the component's code (specifically, the +`options` function of the corresponding prop) rather than the API itself.
370-370: Fix punctuation in abbreviation.The abbreviation "etc" should include a period in American English.
-produced by the action (e.g. logs, errors, etc). +produced by the action (e.g. logs, errors, etc.).🧰 Tools
🪛 LanguageTool
[uncategorized] ~370-~370: Loose punctuation mark.
Context: .../nodejs#using-export) component. 2.os: a list of observations produced by the ...(UNLIKELY_OPENING_PUNCTUATION)
[style] ~370-~370: In American English, abbreviations like “etc.” require a period.
Context: ...duced by the action (e.g. logs, errors, etc). 3.ret: the return value of the act...(ETC_PERIOD)
packages/sdk/src/shared/index.ts (1)
Line range hint
1073-1073: Add JSDoc comment for theaddRelationOptsmethod.The private helper method
addRelationOptsis missing documentation explaining its purpose and parameters.+/** + * Adds pagination and limit options to the provided params object. + * + * @param params - The params object to modify + * @param opts - Optional relation options containing pagination cursors and limit + * @param defaultLimit - Optional default limit to use when no limit is provided + */ private addRelationOpts(params: Record<string, string>, opts?: RelationOpts, defaultLimit?: number) {docs-v2/pages/connect/api.mdx (3)
1224-1224: Fix grammatical error: Remove redundant determinerThe phrase "Configure the a component's prop" contains two determiners. This should be corrected.
-Configure the a component's prop +Configure a component's prop🧰 Tools
🪛 LanguageTool
[grammar] ~1224-~1224: Two determiners in a row. Choose either “the” or “a”.
Context: ... #### Configure a component Configure the a component's prop, based on the current ...(DT_DT)
957-970: Enhance section header formattingThe section headers for the components API could be formatted more consistently with other sections. Consider adding a brief description after the header.
### Components #### List components -List all the components in the Pipedream registry. +List all available components in the Pipedream registry. Components can be filtered by app and searched using a query string.
1649-1676: Enhance security warning for action invocationConsider adding a security warning about validating and sanitizing user input before invoking actions, as malicious input could potentially harm the system.
Add the following warning after the parameters section:
<Callout type="warning"> Always validate and sanitize user input before invoking actions to prevent potential security issues. </Callout>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (8)
docs-v2/.tool-versions(1 hunks)docs-v2/pages/connect/_meta.tsx(1 hunks)docs-v2/pages/connect/api.mdx(22 hunks)docs-v2/pages/connect/components.mdx(1 hunks)docs-v2/pages/connect/use-cases.mdx(2 hunks)packages/sdk/CHANGELOG.md(3 hunks)packages/sdk/package.json(1 hunks)packages/sdk/src/shared/index.ts(2 hunks)
✅ Files skipped from review due to trivial changes (4)
- docs-v2/.tool-versions
- packages/sdk/package.json
- docs-v2/pages/connect/use-cases.mdx
- docs-v2/pages/connect/_meta.tsx
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/components.mdx
[style] ~27-~27: Consider a shorter alternative to avoid wordiness.
Context: ...ent's definition The first thing to do in order to run a component for your end users is t...
(IN_ORDER_TO_PREMIUM)
[style] ~104-~104: The word “because” means “for the reason that” and thus introduces redundancy.
Context: ...``` The reason for this back-and-forth is because the options for a prop are usually link...
(REASON_IS_BECAUSE)
[style] ~221-~221: Consider replacing this phrase with the adverb “differently” to avoid wordiness.
Context: ...-props), and they need to be configured in a different way. Props that are dynamic will have a `re...
(IN_A_X_MANNER)
[style] ~222-~222: You can shorten this phrase to improve clarity and avoid wordiness.
Context: ...ed to be configured in a different way. Props that are dynamic will have a reloadProps attribute set...
(NNS_THAT_ARE_JJ)
[style] ~340-~340: Consider using “except” or “except for”
Context: ...to the one used for configuring a prop, with the exception of the prop_name attribute (because we'r...
(WITH_THE_EXCEPTION_OF)
[uncategorized] ~368-~368: Loose punctuation mark.
Context: ...ning the following fields: 1. exports: all the named exports produced by the a...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~369-~369: The official spelling of this programming framework is “Node.js”.
Context: ...when calling $.export in a Node.js component. 2. os: a lis...
(NODE_JS)
[uncategorized] ~370-~370: Loose punctuation mark.
Context: .../nodejs#using-export) component. 2. os: a list of observations produced by the ...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~370-~370: In American English, abbreviations like “etc.” require a period.
Context: ...duced by the action (e.g. logs, errors, etc). 3. ret: the return value of the act...
(ETC_PERIOD)
[uncategorized] ~371-~371: Loose punctuation mark.
Context: ...ction (e.g. logs, errors, etc). 3. ret: the return value of the action, if any....
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~408-~408: Consider a shorter alternative to avoid wordiness.
Context: ...urce is configured, it must be deployed in order to start listening for events. You might b...
(IN_ORDER_TO_PREMIUM)
packages/sdk/CHANGELOG.md
[misspelling] ~68-~68: This word is normally spelled with a hyphen.
Context: ...y uses asynchronous messaging to handle long running operations. - Updated the backend comma...
(EN_COMPOUNDS_LONG_RUNNING)
docs-v2/pages/connect/api.mdx
[grammar] ~1224-~1224: Two determiners in a row. Choose either “the” or “a”.
Context: ... #### Configure a component Configure the a component's prop, based on the current ...
(DT_DT)
🔇 Additional comments (4)
packages/sdk/CHANGELOG.md (2)
4-9: LGTM: Version bump and documentation fix.
The version bump to 1.1.2 and the docstring fix for componentConfigure and reloadComponentProps methods are properly documented.
25-30: LGTM: Clear documentation of renamed methods and types.
The changelog properly documents the renaming of methods and types with clear examples (e.g., componentConfigure -> configureComponent).
packages/sdk/src/shared/index.ts (2)
907-910: LGTM: Improved configuration property structure.
The nested configuration structure under app-specific keys (e.g., slack) improves organization and clarity.
961-964: Consistent configuration structure.
The configuration structure matches the earlier example, maintaining consistency throughout the codebase.
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Outside diff range and nitpick comments (2)
docs-v2/pages/connect/components.mdx (2)
20-21: Consider enhancing the Components guide link with more context.Add a brief description of what readers will find in the Components guide to set proper expectations.
-To learn more about components in detail, please visit our [Components -guide](/components). +To learn more about component development, architecture, and best practices in detail, please visit our [Components +guide](/components).
217-260: Consider adding a visual diagram for dynamic props.The dynamic props section explains a complex concept. A visual diagram showing the relationship between prop configuration and prop reloading would make this easier to understand.
Consider adding a sequence diagram that shows:
- Initial prop configuration
- Dynamic prop update
- Props reloading
- Subsequent prop configuration
🧰 Tools
🪛 LanguageTool
[style] ~221-~221: Consider replacing this phrase with the adverb “differently” to avoid wordiness.
Context: ...-props), and they need to be configured in a different way. Props that are dynamic will have a `re...(IN_A_X_MANNER)
[style] ~222-~222: You can shorten this phrase to improve clarity and avoid wordiness.
Context: ...ed to be configured in a different way. Props that are dynamic will have areloadPropsattribute set...(NNS_THAT_ARE_JJ)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs-v2/pages/connect/_meta.tsx(2 hunks)docs-v2/pages/connect/components.mdx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs-v2/pages/connect/_meta.tsx
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/components.mdx
[style] ~29-~29: Consider a shorter alternative to avoid wordiness.
Context: ...ent's definition The first thing to do in order to run a component for your end users is t...
(IN_ORDER_TO_PREMIUM)
[style] ~221-~221: Consider replacing this phrase with the adverb “differently” to avoid wordiness.
Context: ...-props), and they need to be configured in a different way. Props that are dynamic will have a `re...
(IN_A_X_MANNER)
[style] ~222-~222: You can shorten this phrase to improve clarity and avoid wordiness.
Context: ...ed to be configured in a different way. Props that are dynamic will have a reloadProps attribute set...
(NNS_THAT_ARE_JJ)
[style] ~340-~340: Consider using “except” or “except for”
Context: ...to the one used for configuring a prop, with the exception of the prop_name attribute (because we'r...
(WITH_THE_EXCEPTION_OF)
[uncategorized] ~368-~368: Loose punctuation mark.
Context: ...ning the following fields: 1. exports: all the named exports produced by the a...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~369-~369: The official spelling of this programming framework is “Node.js”.
Context: ...when calling $.export in a Node.js component. 2. os: a lis...
(NODE_JS)
[uncategorized] ~370-~370: Loose punctuation mark.
Context: .../nodejs#using-export) component. 2. os: a list of observations produced by the ...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~370-~370: In American English, abbreviations like “etc.” require a period.
Context: ...duced by the action (e.g. logs, errors, etc). 3. ret: the return value of the act...
(ETC_PERIOD)
[uncategorized] ~371-~371: Loose punctuation mark.
Context: ...ction (e.g. logs, errors, etc). 3. ret: the return value of the action, if any....
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~408-~408: Consider a shorter alternative to avoid wordiness.
Context: ...urce is configured, it must be deployed in order to start listening for events. You might b...
(IN_ORDER_TO_PREMIUM)
🔇 Additional comments (1)
docs-v2/pages/connect/components.mdx (1)
1-5: LGTM! Clean and well-organized imports.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Outside diff range and nitpick comments (2)
docs-v2/pages/connect/components.mdx (2)
14-21: Consider adding a simple code example.While the explanation is clear, adding a basic component code example would help users better understand the concept of "self-contained executable units of code."
Consider adding a simple example like this:
repository](https://github.com/PipedreamHQ/pipedream/tree/master/components). + +For example, here's a simple component that adds two numbers: + +```javascript +export default { + name: "Add Numbers", + version: "0.1.0", + key: "math-add-numbers", + type: "action", + async run({ $ }) { + const sum = this.x + this.y; + $.export("sum", sum); + return sum; + }, +} +```
113-121: Fix list formatting inconsistency.The numbered list formatting is inconsistent with other lists in the document. Consider using consistent indentation.
-1. `external_user_id`: the ID of your user on your end -2. `id`: the component's unique ID (aka **key**) -3. `prop_name`: the name of the prop you want to configure -4. `configured_props`: an object containing the props that have already been - configured. The initial configuration call must contain the ID of the account - (aka `authProvisionId`) that your user has connected to the target app (see - [this section](workflows#configure-accounts-to-use-your-end-users-auth) for - more details on how to create these accounts) +1. `external_user_id`: the ID of your user on your end +2. `id`: the component's unique ID (aka **key**) +3. `prop_name`: the name of the prop you want to configure +4. `configured_props`: an object containing the props that have already been +configured. The initial configuration call must contain the ID of the account +(aka `authProvisionId`) that your user has connected to the target app (see +[this section](workflows#configure-accounts-to-use-your-end-users-auth) for +more details on how to create these accounts)🧰 Tools
🪛 LanguageTool
[uncategorized] ~113-~113: Loose punctuation mark.
Context: ...following fields: 1.external_user_id: the ID of your user on your end 2.id...(UNLIKELY_OPENING_PUNCTUATION)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs-v2/pages/connect/components.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs-v2/pages/connect/components.mdx
[style] ~29-~29: Consider a shorter alternative to avoid wordiness.
Context: ...ent's definition The first thing to do in order to run a component for your end users is t...
(IN_ORDER_TO_PREMIUM)
[uncategorized] ~113-~113: Loose punctuation mark.
Context: ...following fields: 1. external_user_id: the ID of your user on your end 2. id...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~224-~224: Consider replacing this phrase with the adverb “differently” to avoid wordiness.
Context: ...-props), and they need to be configured in a different way. Props that are dynamic will have a `re...
(IN_A_X_MANNER)
[style] ~225-~225: You can shorten this phrase to improve clarity and avoid wordiness.
Context: ...ed to be configured in a different way. Props that are dynamic will have a reloadProps attribute set...
(NNS_THAT_ARE_JJ)
[style] ~343-~343: Consider using “except” or “except for”
Context: ...to the one used for configuring a prop, with the exception of the prop_name attribute (because we'r...
(WITH_THE_EXCEPTION_OF)
[uncategorized] ~371-~371: Loose punctuation mark.
Context: ...ning the following fields: 1. exports: all the named exports produced by the a...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~372-~372: The official spelling of this programming framework is “Node.js”.
Context: ...when calling $.export in a Node.js component. 2. os: a lis...
(NODE_JS)
[uncategorized] ~373-~373: Loose punctuation mark.
Context: .../nodejs#using-export) component. 2. os: a list of observations produced by the ...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~373-~373: In American English, abbreviations like “etc.” require a period.
Context: ...duced by the action (e.g. logs, errors, etc). 3. ret: the return value of the act...
(ETC_PERIOD)
[uncategorized] ~374-~374: Loose punctuation mark.
Context: ...ction (e.g. logs, errors, etc). 3. ret: the return value of the action, if any....
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~411-~411: Consider a shorter alternative to avoid wordiness.
Context: ...urce is configured, it must be deployed in order to start listening for events. You might b...
(IN_ORDER_TO_PREMIUM)
[uncategorized] ~413-~413: Possible missing comma found.
Context: ... That's the reason why when deploying a source you must provide a URL where the source...
(AI_HYDRA_LEO_MISSING_COMMA)
🔇 Additional comments (1)
docs-v2/pages/connect/components.mdx (1)
1-5: LGTM! Well-structured imports.
The imports are clean, organized, and properly separated between external and internal components.
| "title": "Initial commit", | ||
| "message": "Initial commit", | ||
| "author_name": "Jay Vercellone", | ||
| "author_email": "[email protected]", |
There was a problem hiding this comment.
Anonymize email addresses in example responses.
Replace real email addresses with example.com domains to protect privacy.
- "author_email": "[email protected]",
+ "author_email": "[email protected]",
- "committer_email": "[email protected]",
+ "committer_email": "[email protected]",Also applies to: 397-398
| The output of executing the action will be a JSON object containing the | ||
| following fields: | ||
|
|
||
| 1. `exports`: all the named exports produced by the action, like when calling | ||
| [`$.export` in a Node.js](/code/nodejs#using-export) component. | ||
| 2. `os`: a list of observations produced by the action (e.g. logs, errors, etc). | ||
| 3. `ret`: the return value of the action, if any. | ||
|
|
||
| The following (abbreviated) example shows the output of running the action | ||
| above: | ||
|
|
||
| ```json | ||
| { | ||
| "exports": { | ||
| "$summary": "Retrieved 1 commit" | ||
| }, | ||
| "os": [], | ||
| "ret": [ | ||
| { | ||
| "id": "387262aea5d4a6920ac76c1e202bc9fd0841fea5", | ||
| "short_id": "387262ae", | ||
| "created_at": "2023-05-03T03:03:25.000+00:00", | ||
| "parent_ids": [], | ||
| "title": "Initial commit", | ||
| "message": "Initial commit", | ||
| "author_name": "Jay Vercellone", | ||
| "author_email": "[email protected]", | ||
| "authored_date": "2023-05-03T03:03:25.000+00:00", | ||
| "committer_name": "Jay Vercellone", | ||
| "committer_email": "[email protected]", | ||
| "committed_date": "2023-05-03T03:03:25.000+00:00", | ||
| "trailers": {}, | ||
| "extended_trailers": {}, | ||
| "web_url": "https://gitlab.com/jverce/foo-massive-10231-1/-/commit/387262aea5d4a6920ac76c1e202bc9fd0841fea5" | ||
| } | ||
| ] | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add error handling documentation.
The execution section should include information about possible error responses and how to handle them.
Consider adding a subsection about error handling:
}
+
+#### Error Handling
+
+When invoking actions, the API may return error responses in the following scenarios:
+
+```json
+{
+ "error": {
+ "code": "COMPONENT_ERROR",
+ "message": "Error details...",
+ "details": {
+ // Additional error context
+ }
+ }
+}
+```
+
+Common error scenarios include:
+- Invalid component configuration
+- Authentication failures
+- Rate limiting
+- Third-party API errors🧰 Tools
🪛 LanguageTool
[uncategorized] ~371-~371: Loose punctuation mark.
Context: ...ning the following fields: 1. exports: all the named exports produced by the a...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~372-~372: The official spelling of this programming framework is “Node.js”.
Context: ...when calling $.export in a Node.js component. 2. os: a lis...
(NODE_JS)
[uncategorized] ~373-~373: Loose punctuation mark.
Context: .../nodejs#using-export) component. 2. os: a list of observations produced by the ...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~373-~373: In American English, abbreviations like “etc.” require a period.
Context: ...duced by the action (e.g. logs, errors, etc). 3. ret: the return value of the act...
(ETC_PERIOD)
[uncategorized] ~374-~374: Loose punctuation mark.
Context: ...ction (e.g. logs, errors, etc). 3. ret: the return value of the action, if any....
(UNLIKELY_OPENING_PUNCTUATION)
jverce
deleted the
jay/money-1912-docs-api-sdk-action-configure-run-triggerdeploy-etc
branch
Changelog
pnpmentry to.tool-versionsin the docs directorySummary by CodeRabbit
New Features
pnpm 9.14.2support.Documentation
Bug Fixes
Chores
1.1.1to1.1.2.