Merge branch 'master' into 21608-google-business-profile

Author: vetrivigneshwaran

components/amplitude/actions/create-cohort/create-cohort.mjs

@@ -0,0 +1,89 @@
+// x-pd-ai: optimized
+import app from "../../amplitude.app.mjs";
+import { COHORT_ID_TYPES } from "../../common/constants.mjs";
+
+export default {
+  key: "amplitude-create-cohort",
+  name: "Create Cohort",
+  description: "Create a static cohort in Amplitude from an explicit list of user or Amplitude IDs via `POST /api/3/cohorts/upload` (the only REST-documented cohort creation endpoint; behavioral/dynamic cohorts cannot be created via REST). Use **List Cohorts** to find an existing cohort ID if updating. Example: call with `cohortName=\"Power Users Q3\"`, `appId=849238`, `idType=\"BY_USER_ID\"`, `ids=[\"user@example.com\"]`, `owner=\"admin@example.com\"` -> returns `{cohortId: \"abc123\"}`. [See the documentation](https://amplitude.com/docs/apis/analytics/behavioral-cohorts#upload-cohort).",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+  },
+  props: {
+    app,
+    cohortName: {
+      type: "string",
+      label: "Name",
+      description: "Name of the cohort (the `name` field). Example: `Power Users Q3`.",
+    },
+    appId: {
+      type: "integer",
+      label: "App ID",
+      description: "The numeric Amplitude project ID that owns the cohort (the `app_id` field). This isn't retrievable through any Amplitude REST API — find it in Amplitude under Settings > Projects, or in the project's Getting Started page. Example: `849238`.",
+    },
+    idType: {
+      type: "string",
+      label: "ID Type",
+      description: "The type of identifiers provided in Ids (the `id_type` field). One of `BY_AMP_ID`, `BY_USER_ID`.",
+      options: COHORT_ID_TYPES,
+    },
+    ids: {
+      type: "string[]",
+      label: "IDs",
+      description: "Array of user or Amplitude IDs to include in the cohort (the `ids` field), matching the chosen ID Type. Example: `[\"12345678\",\"87654321\"]`.",
+    },
+    owner: {
+      type: "string",
+      label: "Owner",
+      description: "Login email of the cohort owner (the `owner` field). Example: `user@example.com`.",
+    },
+    published: {
+      type: "boolean",
+      label: "Published",
+      description: "Whether the cohort is published/shared (the `published` field).",
+      optional: true,
+    },
+    groupName: {
+      type: "string",
+      label: "Group Name",
+      description: "Optional group name for the cohort (the `cg` field).",
+      optional: true,
+    },
+    skipInvalidIds: {
+      type: "boolean",
+      label: "Skip Invalid IDs",
+      description: "When `true`, silently skip IDs that cannot be resolved instead of failing (the `skip_invalid_ids` field).",
+      optional: true,
+    },
+    existingCohortId: {
+      type: "string",
+      label: "Existing Cohort ID",
+      description: "Optional ID of an existing cohort to overwrite instead of creating a new one (the `existing_cohort_id` field). Use **List Cohorts** to find valid cohort IDs.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.createCohort({
+      $,
+      data: {
+        name: this.cohortName,
+        app_id: this.appId,
+        id_type: this.idType,
+        ids: this.ids,
+        owner: this.owner,
+        published: this.published,
+        cg: this.groupName,
+        skip_invalid_ids: this.skipInvalidIds,
+        existing_cohort_id: this.existingCohortId,
+      },
+    });
+    $.export("$summary", `Successfully created cohort "${this.cohortName}"${response.cohortId
+      ? ` with ID ${response.cohortId}`
+      : ""}`);
+    return response;
+  },
+};

components/amplitude/actions/download-cohort-file/download-cohort-file.mjs

@@ -0,0 +1,55 @@
+// x-pd-ai: optimized
+import app from "../../amplitude.app.mjs";
+import { COHORT_DOWNLOAD_MAX_MEMBERS } from "../../common/constants.mjs";
+import { parseCohortDownload } from "../../common/utils.mjs";
+
+export default {
+  key: "amplitude-download-cohort-file",
+  name: "Download Cohort File",
+  description: "Download a completed cohort export's member list (step 3 of 3: request -> status -> download). Call **Request Cohort Download** then **Get Cohort Download Status** first, and only call this once status is `JOB COMPLETED` — calling it earlier will fail. Returns one record per member (`amplitude_id`/`user_id`, plus any requested user properties) — not the cohort's own metadata (name, size, definition); use **List Cohorts** for that. Example: call with `requestId=\"req_456\"` -> returns `{requestId: \"req_456\", memberCount: 4200, returnedCount: 4200, truncated: false, members: [{amplitude_id: \"123456789\", user_id: \"user@example.com\"}, ...]}`. [See the documentation](https://amplitude.com/docs/apis/analytics/behavioral-cohorts#download-cohort).",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    app,
+    requestId: {
+      propDefinition: [
+        app,
+        "requestId",
+      ],
+      description: "The `request_id` returned by **Request Cohort Download**, after **Get Cohort Download Status** reports `JOB COMPLETED`. Example: `req_456`.",
+    },
+    maxMembers: {
+      type: "integer",
+      label: "Max Members",
+      description: `Maximum number of member records to return. Defaults to ${COHORT_DOWNLOAD_MAX_MEMBERS}. The true total is always reported in \`memberCount\`, with \`truncated: true\` if it exceeds this cap.`,
+      min: 0,
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const file = await this.app.downloadCohortFile({
+      $,
+      requestId: this.requestId,
+    });
+    const {
+      records: members, totalCount, truncated,
+    } = await parseCohortDownload(file, {
+      maxRecords: this.maxMembers ?? COHORT_DOWNLOAD_MAX_MEMBERS,
+    });
+    $.export("$summary", `Successfully downloaded ${members.length} of ${totalCount} member(s) for request ${this.requestId}${truncated
+      ? " (truncated)"
+      : ""}`);
+    return {
+      requestId: this.requestId,
+      memberCount: totalCount,
+      returnedCount: members.length,
+      truncated,
+      members,
+    };
+  },
+};

components/amplitude/actions/get-cohort-download-status/get-cohort-download-status.mjs

@@ -0,0 +1,32 @@
+// x-pd-ai: optimized
+import app from "../../amplitude.app.mjs";
+
+export default {
+  key: "amplitude-get-cohort-download-status",
+  name: "Get Cohort Download Status",
+  description: "Check whether a cohort download job has finished (step 2 of 3: request -> status -> download). Call **Request Cohort Download** first to get a `requestId`. This action polls internally for up to ~35 seconds before returning, since Amplitude's export jobs commonly take 30-60+ seconds regardless of cohort size. If the returned `async_status` is still `JOB INPROGRESS`, call this action again with the same request ID (it may take a few calls) — do not call **Download Cohort File** until `async_status` is `JOB COMPLETED`. Example: call with `requestId=\"req_456\"` -> returns `{request_id: \"req_456\", cohort_id: \"abc123\", async_status: \"JOB COMPLETED\"}`. [See the documentation](https://amplitude.com/docs/apis/analytics/behavioral-cohorts#get-request-status).",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    app,
+    requestId: {
+      propDefinition: [
+        app,
+        "requestId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.pollCohortDownloadStatus({
+      $,
+      requestId: this.requestId,
+    });
+    $.export("$summary", `Cohort download request ${this.requestId} status: ${response.async_status}`);
+    return response;
+  },
+};

components/amplitude/actions/get-event-segmentation/get-event-segmentation.mjs

@@ -0,0 +1,113 @@
+// x-pd-ai: optimized
+import { ConfigurationError } from "@pipedream/platform";
+import app from "../../amplitude.app.mjs";
+import {
+  SEGMENTATION_METRICS,
+  INTERVAL_OPTIONS,
+} from "../../common/constants.mjs";
+
+export default {
+  key: "amplitude-get-event-segmentation",
+  name: "Get Event Segmentation",
+  description: "Query event segmentation data (counts, uniques, and other metrics) for one or more events over a date range from the Amplitude Dashboard REST API. Use this to analyze how an event trends over time, optionally broken down by user properties. Example: call with `event={\"event_type\":\"Purchase\"}`, `startDate=\"20240706\"`, `endDate=\"20240805\"`, `metric=\"uniques\"` -> returns `{data: {xValues: [\"2024-07-06\", ...], series: [[42, 51, ...]]}}` (one value per day per requested series). [See the documentation](https://amplitude.com/docs/apis/analytics/dashboard-rest#event-segmentation).",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    app,
+    event: {
+      type: "string",
+      label: "Event",
+      description: "A single JSON-encoded event definition (the `e` param). `event_type` is required; `filters` and `group_by` are optional. Use a real event name from your project (e.g. `Purchase`, `Sign Up`), or Amplitude's built-in `_active`/`_new` events to query overall activity. Example: `{\"event_type\":\"_active\"}` (Amplitude's built-in \"any active event\" — do NOT use the literal string \"Any Active Event\", which is Amplitude UI label text, not a valid `event_type` value, and returns a 400).",
+    },
+    startDate: {
+      propDefinition: [
+        app,
+        "startDate",
+      ],
+    },
+    endDate: {
+      propDefinition: [
+        app,
+        "endDate",
+      ],
+    },
+    metric: {
+      type: "string",
+      label: "Metric",
+      description: "Metric to compute (the `m` param). One of: `uniques`, `totals`, `pct_dau`, `average`, `histogram`, `sums`, `value_avg`, `formula`. Defaults to `uniques`.",
+      options: SEGMENTATION_METRICS,
+      optional: true,
+    },
+    interval: {
+      type: "integer",
+      label: "Interval",
+      description: "Time interval (the `i` param). One of `-300000` (realtime), `-3600000` (hourly), `1` (daily), `7` (weekly), `30` (monthly). Defaults to `1`.",
+      options: INTERVAL_OPTIONS,
+      optional: true,
+    },
+    segmentDefinitions: {
+      propDefinition: [
+        app,
+        "segmentDefinitions",
+      ],
+    },
+    groupBy: {
+      type: "string",
+      label: "Group By",
+      description: "A user or event property name to group results by (the `g` param).",
+      optional: true,
+    },
+    groupBy2: {
+      type: "string",
+      label: "Group By 2",
+      description: "A second property name to group results by (the `g2` param). Only used together with Group By.",
+      optional: true,
+    },
+    secondEvent: {
+      type: "string",
+      label: "Second Event",
+      description: "A second JSON-encoded event definition (the `e2` param) for a derived/comparison metric. Example: `{\"event_type\":\"Purchase\"}`.",
+      optional: true,
+    },
+    limit: {
+      propDefinition: [
+        app,
+        "limit",
+      ],
+    },
+    formula: {
+      type: "string",
+      label: "Formula",
+      description: "Custom formula metric expression (the `formula` param). Required if Metric is set to `formula`. Example: `UNIQUES(A)/UNIQUES(B)`.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    if (this.metric === "formula" && !this.formula?.trim()) {
+      throw new ConfigurationError("**Formula** is required when Metric is set to `formula`. Example: `UNIQUES(A)/UNIQUES(B)`.");
+    }
+    const response = await this.app.getEventSegmentation({
+      $,
+      params: {
+        e: this.event,
+        start: this.startDate,
+        end: this.endDate,
+        m: this.metric,
+        i: this.interval,
+        s: this.segmentDefinitions,
+        g: this.groupBy,
+        g2: this.groupBy2,
+        e2: this.secondEvent,
+        limit: this.limit,
+        formula: this.formula,
+      },
+    });
+    $.export("$summary", `Successfully retrieved event segmentation data from ${this.startDate} to ${this.endDate}`);
+    return response;
+  },
+};