Adding 'annotations' to component typing for actions

[GTFalcao]

Summary by CodeRabbit

• New Features
  • Actions gain optional annotations to indicate destructive, idempotent, open‑world, or read‑only hints—improving clarity in UIs and integrations.
• Chores
  • Package version bumped to 0.3.3.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
pipedream-docs	Ignored			Oct 4, 2025 4:35pm
pipedream-docs-redirect-do-not-edit	Ignored			Oct 4, 2025 4:35pm

[coderabbitai]

Walkthrough

Adds an optional annotations property with four optional boolean hints to the Action interface in types/src/index.ts. Increments @pipedream/types package version from 0.3.2 to 0.3.3. No behavioral or control-flow changes.

Changes

Cohort / File(s)	Summary of Changes
Action type annotations types/src/index.ts	Added annotations?: { destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint?: boolean; readOnlyHint?: boolean } to Action interface.
Package metadata bump types/package.json	Version updated from "0.3.2" to "0.3.3".

Sequence Diagram(s)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I twitch my whiskers at four small lights,
Flags for actions in the quiet nights.
A hop from .2 to .3 with glee,
Types updated, the fields agree.
Carrots stacked and schemas bright—🥕✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The pull request description is empty and does not follow the repository’s required template which mandates a “## WHY” section to explain the reasoning behind the changes.	Please add a description following the template, including a “## WHY” section that outlines the motivation and use cases for adding annotations to the Action interface.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly and accurately describes the primary change of adding an annotations property to action typings, clearly reflecting the main update to the Action interface without extraneous detail.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch component-types-update-annotations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[dannyroosevelt]

you should add idempotentHint? while you're at it, even though we aren't backfilling that value for any components right now

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

types/src/index.ts (1)

387-392: LGTM! The annotations property addresses the previous feedback.

The addition of the annotations property with the four boolean hints (including idempotentHint as suggested in the previous review) is well-structured. All fields are optional, ensuring no breaking changes.

Consider adding JSDoc documentation to clarify the purpose of each hint:

   props?: ActionPropDefinitions;
+  /**
+   * Optional metadata hints about action behavior characteristics.
+   * These hints help categorize and optimize action execution.
+   */
   annotations?: {
+    /** Indicates the action modifies or deletes external resources */
     destructiveHint?: boolean;
+    /** Indicates the action can be safely retried without side effects */
     idempotentHint?: boolean;
+    /** Indicates the action interacts with external systems or APIs */
     openWorldHint?: boolean;
+    /** Indicates the action only reads data without modifications */
     readOnlyHint?: boolean;
   }
   additionalProps?: (

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6707441 and d6f2059.

📒 Files selected for processing (1)

• types/src/index.ts (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Lint Code Base
• GitHub Check: pnpm publish

[js07]

I might be doing something wrong, but I get some TypeScript errors when trying to run this package's tests (via npm run test).

./node_modules/@types/cacheable-request/index.d.ts:26:42 - error TS2709: Cannot use namespace 'ResponseLike' as a type.
        cb?: (response: ServerResponse | ResponseLike) => void

Since those don't seem to cause the build to fail, I think they shouldn't be blocking. LGTM!

Edit: Looks like the pnpm publish actually failed in this check.

To fix this issue, I think you can tell TypeScript to use only type definitions in the current directory, rather than looking for type definitions up the directory tree (e.g. in ../node_modules/@types). For example, in types/tsconfig.json, add the following to compilerOptions:

    "typeRoots": ["./node_modules/@types"]