Merge branch 'master' into mcp/returnista

Author: vetrivigneshwaran

.coderabbit.yaml

@@ -19,16 +19,20 @@ reviews:
         Review this file against the Pipedream component model described in
         .github/pipedream-component-guidelines.md.
 
-        - Verify the `version` field is incremented from its previous value and the bump
-          follows semantic versioning (see the Versioning section of the guidelines):
-          new components start at `0.0.1`; bug fixes and non-breaking refactors → patch;
-          new optional props or backwards-compatible additions → minor; removed/renamed props
-          or breaking behavior changes → major; flag any PR where the version was not bumped
-          or where the bump level seems inconsistent with the scope of the change
+        - Only flag a missing version bump when the component's own behavior, interface, or
+          implementation changed — do not flag components that are only transitively touched
+          by a shared-file change (e.g. a new constant added to a constants file) with no
+          effect on the component itself. When a bump is required, verify it is incremented
+          from its previous value and follows semantic versioning (see the Versioning section
+          of the guidelines): new components start at `0.0.1`; bug fixes and non-breaking
+          refactors → patch; new optional props or backwards-compatible additions → minor;
+          removed/renamed props or breaking behavior changes → major; a patch bump added
+          solely to satisfy the CI version check is always acceptable and should not be flagged
         - Verify the app's `package.json` version is also bumped by the same or greater
           semver segment as the component change
-        - All prop names, method names, and local variables must use camelCase; API request
-          parameter names follow the API's own convention and are the only exception
+        - All prop names, method names, and local variables must use camelCase; module-level
+          constants use UPPER_SNAKE_CASE; API request parameter names follow the API's own
+          convention and are the only exception
         - Props used in more than one component must be defined in the app file's
           `propDefinitions` and referenced via `propDefinition` — flag any inline prop
           definition that duplicates one already in the app file

.github/pipedream-component-guidelines.md

@@ -35,7 +35,7 @@ export default {
   key: "app-action-name",       // globally unique; kebab-case; prefixed with app slug
   name: "Human Readable Name",  // shown in UI and as the MCP tool name
   description: "...",           // shown in UI and used as MCP tool documentation
-  version: "0.0.1",            // semantic versioning; must be incremented on every change
+  version: "0.0.1",            // semantic versioning; increment when the component's own behavior, interface, or implementation changes
   type: "action",               // or "source"
   props: { ... },              // configuration inputs
   async run({ $ }) { ... },    // execution entry point (signature differs for sources)
@@ -49,8 +49,9 @@ values are **semantically correct**, not whether properties exist.
 
 ## Versioning
 
-Every component has a `version` field that must be incremented on every change. New
-components always start at `0.0.1`. Follow semantic versioning:
+Every component has a `version` field that must be incremented whenever the component's
+own behavior, interface, or implementation changes. New components always start at
+`0.0.1`. Follow semantic versioning:
 
 | Change type | Version segment | Examples |
 |---|---|---|
@@ -62,13 +63,36 @@ The app's `package.json` must also be bumped by the same or greater segment when
 component in that app changes — patch for patch, minor for minor (or higher), major for
 major (or higher).
 
+### CI version check and false positives
+
+A CI workflow flags components whose files — or whose shared dependency files — were
+modified without a corresponding version bump. This check is **advisory**: it is not
+required to pass for a PR to merge.
+
+The check can produce false positives. For example, adding a new constant to a shared
+constants file does not affect existing consumers, so those components do not strictly
+need a version bump. In cases like this, a **patch bump is always acceptable** as a
+way to satisfy the workflow — reviewers should not block a PR solely because a component
+received a patch bump that was not otherwise necessary. Conversely, do not require
+authors to bump versions for components that are only transitively touched by a
+non-behavioral shared-file change; the CI warning is informational in those cases.
+
 ---
 
 ## Naming Conventions
 
 All prop names, method names, and local variables must use **camelCase**. This applies
 throughout component files and app files alike.
 
+Module-level constants (values that are fixed at import time and reused across the file)
+must use **`UPPER_SNAKE_CASE`**:
+
+```javascript
+const DEFAULT_LIMIT = 100;
+const MAX_RETRIES = 3;
+const EVENT_TYPES = Object.freeze(["created", "updated", "deleted"]);
+```
+
 The only exception is API request parameters — use whatever casing the API itself
 requires (often `snake_case` or `PascalCase`). Map prop values to API parameter names
 at the point of the request:

components/apexverify/actions/unit-verification/unit-verification.mjs

@@ -0,0 +1,127 @@
+import apexverify from "../../apexverify.app.mjs";
+import {
+  COUNTRY_OPTIONS,
+  TARGET_AUDIENCE_OPTIONS,
+  TARGET_MARKET_INDUSTRY_OPTIONS,
+  TARGET_OBJECTIVE_OPTIONS,
+} from "../../common/constants.mjs";
+
+export default {
+  key: "apexverify-unit-verification",
+  name: "ApexVerify - Email/Phone B2B Data Verification",
+  description: "Verify a single email address or phone number using ApexVerify. [See the documentation](https://documentation.apexverify.com/api-reference/apex-verify-api/unit)",
+  version: "0.0.1",
+  type: "action",
+  props: {
+    apexverify,
+
+    type: {
+      type: "string",
+      label: "Data Type",
+      description: "Which kind of contact data is being verified. Allowed values: `email` (verify an email address) or `phone` (verify a phone number). The value of `unit` must match this type — pass `email` here when `unit` is an email address, and `phone` when `unit` is a phone number.",
+      options: [
+        {
+          label: "Email Address",
+          value: "email",
+        },
+        {
+          label: "Phone Number",
+          value: "phone",
+        },
+      ],
+    },
+    unit: {
+      type: "string",
+      label: "Email or Phone to Verify",
+      description: "The single email address or phone number to verify. Format must match `type`: for `type=email`, pass a full RFC 5322 email like `jane.doe@example.com`. For `type=phone`, pass a number in E.164 format with the leading `+` and country code — e.g. `+14155552671` (US) or `+442071234567` (UK). Hyphens and spaces are tolerated but not required. Only one address/number per call.",
+    },
+    targetCountry: {
+      type: "string",
+      label: "Target Country",
+      description: "Country against which the email or phone should be processed.",
+      default: "US",
+      options: COUNTRY_OPTIONS,
+    },
+    targetAudience: {
+      type: "string",
+      label: "Target Audience",
+      description: "Optional target audience context for the verification. Accepted values include `1` for Agency / Consultants, `4` for Developers & Technical Leads, `8` for Founders & C-Level Executives, and `17` for Marketing & Sales Professionals.",
+      optional: true,
+      options: TARGET_AUDIENCE_OPTIONS,
+    },
+    targetMarketIndustry: {
+      type: "string",
+      label: "Target Market Industry",
+      description: "Optional market industry context for the verification. Accepted values include `18` for Construction, `29` for Finance and Insurance, `42` for Health Care and Social Assistance, `46` for Information, and `91` for Retail Trade.",
+      optional: true,
+      options: TARGET_MARKET_INDUSTRY_OPTIONS,
+    },
+    targetObjective: {
+      type: "string",
+      label: "Target Objective",
+      description: "Optional campaign or business objective context for the verification. Accepted values include `4` for Customer Acquisition / Sales, `6` for Lead Generation (Top/Mid-Funnel), `12` for Sales-Ready Leads, and `16` for Website / App Traffic Acquisition.",
+      optional: true,
+      options: TARGET_OBJECTIVE_OPTIONS,
+    },
+    useAccountCache: {
+      type: "boolean",
+      label: "Use Account Cache",
+      description: "Use previous verification results from your ApexVerify account cache when available.",
+      optional: true,
+      default: true,
+    },
+    maxAccountCacheBackoff: {
+      type: "integer",
+      label: "Max Account Cache Backoff",
+      description: "Maximum number of days to look back in account cache. Min: 1. Max: 180.",
+      optional: true,
+      default: 30,
+    },
+    useGlobalCache: {
+      type: "boolean",
+      label: "Use Global Cache",
+      description: "Use anonymized global cache results when available.",
+      optional: true,
+      default: true,
+    },
+    maxGlobalCacheBackoff: {
+      type: "integer",
+      label: "Max Global Cache Backoff",
+      description: "Maximum number of days to look back in global cache. Min: 1. Max: 180.",
+      optional: true,
+      default: 30,
+    },
+  },
+  annotations: {
+    openWorldHint: true,
+    readOnlyHint: false,
+    destructiveHint: false,
+  },
+
+  async run({ $ }) {
+    const payload = {
+      type: this.type,
+      target_country: this.targetCountry,
+      unit: this.unit,
+      target_audience: this.targetAudience,
+      target_market_industry: this.targetMarketIndustry,
+      target_objective: this.targetObjective,
+      use_account_cache: this.useAccountCache,
+      max_account_cache_backoff: this.maxAccountCacheBackoff,
+      use_global_cache: this.useGlobalCache,
+      max_global_cache_backoff: this.maxGlobalCacheBackoff,
+    };
+
+    Object.keys(payload).forEach((key) => {
+      if (payload[key] === "" || payload[key] === null || payload[key] === undefined) {
+        delete payload[key];
+      }
+    });
+
+    const response = await this.apexverify.verifyUnit($, payload);
+
+    $.export("$summary", `Successfully verified ${this.type}`);
+
+    return response;
+  },
+};

components/apexverify/apexverify.app.mjs

@@ -0,0 +1,56 @@
+import { axios } from "@pipedream/platform";
+
+export default {
+  type: "app",
+  app: "apexverify",
+  propDefinitions: {},
+  methods: {
+    _baseUrl() {
+      return "https://api.apexverify.com";
+    },
+
+    _headers() {
+      return {
+        "X-API-Key": this.$auth.api_key,
+        "Accept": "application/json",
+      };
+    },
+
+    async _makeRequest($, {
+      method = "GET",
+      path,
+      data,
+      params,
+      headers = {},
+    }) {
+      return await axios($, {
+        method,
+        url: `${this._baseUrl()}${path}`,
+        headers: {
+          ...this._headers(),
+          ...headers,
+        },
+        data,
+        params,
+      });
+    },
+
+    async testConnection($) {
+      return this._makeRequest($, {
+        method: "GET",
+        path: "/v1/account/credits",
+      });
+    },
+
+    async verifyUnit($, payload) {
+      return this._makeRequest($, {
+        method: "POST",
+        path: "/v1/unit",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        data: payload,
+      });
+    },
+  },
+};