@pipedream/linkedin_ads 0.3.0 → 0.3.1

package/actions/common/report.mjs

@@ -0,0 +1,62 @@
+/* eslint-disable no-unused-vars */
+import app from "../../linkedin_ads.app.mjs";
+import utils from "../../common/utils.mjs";
+
+export default {
+  props: {
+    app,
+  },
+  methods: {
+    getDateStr(date) {
+      return [
+        `day:${date.getDate()}`,
+        `month:${date.getMonth() + 1}`,
+        `year:${date.getFullYear()}`,
+      ].join(",");
+    },
+    getDateRangeParam(startStr, endStr) {
+      const { getDateStr } = this;
+      const start = getDateStr(new Date(startStr));
+
+      if (!endStr) {
+        return `(start:(${start}))`;
+      }
+
+      const end = getDateStr(new Date(endStr));
+      return `(start:(${start}),end:(${end}))`;
+    },
+    getListParam(list = []) {
+      return `List(${list?.map(encodeURIComponent).join(",")})`;
+    },
+    getListParams(props = {}) {
+      return Object.entries(props)
+        .reduce((acc, [
+          key,
+          value,
+        ]) => {
+          if (
+            typeof(value) === "function"
+            || value === undefined
+            || value === null
+          ) {
+            return acc;
+          }
+          return {
+            ...acc,
+            [key]: this.getListParam(
+              typeof(value) === "string"
+                ? JSON.parse(value)
+                : value,
+            ),
+          };
+        }, {});
+    },
+    createReport(args = {}) {
+      return this.app._makeRequest({
+        path: "/adAnalytics",
+        paramsSerializer: utils.getParamsSerializer(),
+        ...args,
+      });
+    },
+  },
+};

package/actions/create-report/create-report.mjs

@@ -0,0 +1,105 @@
+/* eslint-disable no-unused-vars */
+import common from "../common/report.mjs";
+
+export default {
+  ...common,
+  key: "linkedin_ads-create-report",
+  name: "Create A Report",
+  description: "Queries the Analytics Finder to get analytics for the specified entity i.e company, account, campaign. [See the docs here](https://docs.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting#analytics-finder)",
+  version: "0.0.4",
+  type: "action",
+  props: {
+    ...common.props,
+    adAccountId: {
+      propDefinition: [
+        common.props.app,
+        "adAccountId",
+      ],
+    },
+    pivot: {
+      propDefinition: [
+        common.props.app,
+        "pivot",
+      ],
+    },
+    timeGranularity: {
+      propDefinition: [
+        common.props.app,
+        "timeGranularity",
+      ],
+    },
+    dateRangeStart: {
+      type: "string",
+      label: "Date Range Start",
+      description: "Represents the inclusive start time range of the analytics. If unset, it indicates an open range up to the end time. Should be in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g. 2022-12-27.",
+    },
+    dateRangeEnd: {
+      type: "string",
+      label: "Date Range End",
+      description: "Represents the inclusive end time range of the analytics. Must be after start time if it's present. If unset, it indicates an open range from start time to everything after. Should be in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, e.g. 2022-12-27.",
+      optional: true,
+    },
+    shares: {
+      type: "string[]",
+      label: "Shares",
+      description: "An [Array of Share URN](https://docs.microsoft.com/en-us/linkedin/marketing/integrations/community-management/shares/share-api). Required unless another facet is provided.",
+      optional: true,
+    },
+    campaigns: {
+      type: "string[]",
+      label: "Campaigns",
+      description: "An [Array of Sponsored Campaign URN](https://docs.microsoft.com/en-us/linkedin/shared/references/v2/ads/adcampaigns?context=linkedin/marketing/context). Required unless another facet is provided.",
+      optional: true,
+    },
+    creatives: {
+      type: "string[]",
+      label: "Creatives",
+      description: "An [Array of Sponsored Creative URN](https://docs.microsoft.com/en-us/linkedin/shared/references/v2/ads/adcreatives?context=linkedin/marketing/context). Required unless another facet is provided.",
+      optional: true,
+    },
+    campaignGroups: {
+      type: "string[]",
+      label: "Campaign Groups",
+      description: "An [Array of Campaign Group URN](https://docs.microsoft.com/en-us/linkedin/shared/references/v2/ads/adcampaigngroups?context=linkedin/marketing/context). Required unless another facet is provided.",
+      optional: true,
+    },
+    accounts: {
+      propDefinition: [
+        common.props.app,
+        "accounts",
+        ({ adAccountId }) => ({
+          adAccountId,
+        }),
+      ],
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      getDateRangeParam,
+      getListParams,
+      createReport,
+      adAccountId,
+      pivot,
+      timeGranularity,
+      dateRangeStart,
+      dateRangeEnd,
+      ...arrayProps
+    } = this;
+
+    const response = await createReport({
+      $,
+      params: {
+        q: "analytics",
+        pivot,
+        timeGranularity,
+        dateRange: getDateRangeParam(dateRangeStart, dateRangeEnd),
+        ...getListParams(arrayProps),
+      },
+    });
+
+    $.export("$summary", `Successfully retrieved analytics information with ${response.elements.length} elements.`);
+
+    return response.elements;
+  },
+};

package/actions/create-report-by-advertiser-account/create-report-by-advertiser-account.mjs

@@ -0,0 +1,60 @@
+/* eslint-disable no-unused-vars */
+import common from "../common/report.mjs";
+
+export default {
+  ...common,
+  key: "linkedin_ads-create-report-by-advertiser-account",
+  name: "Create Report By Advertiser Account",
+  description: "Sample query using analytics finder that gets analytics for a particular account for date range starting in a given year. [See the docs here](https://docs.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting#sample-request)",
+  version: "0.0.4",
+  type: "action",
+  props: {
+    ...common.props,
+    startYear: {
+      propDefinition: [
+        common.props.app,
+        "startYear",
+      ],
+    },
+    timeGranularity: {
+      propDefinition: [
+        common.props.app,
+        "timeGranularity",
+      ],
+    },
+    adAccountId: {
+      propDefinition: [
+        common.props.app,
+        "adAccountId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      getDateRangeParam,
+      startYear,
+      timeGranularity,
+      adAccountId,
+      getListParam,
+      createReport,
+    } = this;
+
+    const response = await createReport({
+      $,
+      params: {
+        "q": "analytics",
+        "pivot": "ACCOUNT",
+        "dateRange": getDateRangeParam(`${startYear}-01-01`),
+        timeGranularity,
+        "accounts": getListParam([
+          app.getSponsoredAccountUrn(adAccountId),
+        ]),
+      },
+    });
+
+    $.export("$summary", "Successfully retrieved analytics");
+
+    return response;
+  },
+};

package/actions/create-report-by-campaign/create-report-by-campaign.mjs

@@ -0,0 +1,69 @@
+/* eslint-disable no-unused-vars */
+import common from "../common/report.mjs";
+
+export default {
+  ...common,
+  key: "linkedin_ads-create-report-by-campaign",
+  name: "Query Analytics Finder Campaign Sample",
+  description: "Sample query using analytics finder that gets analytics for a particular campaign in a date range starting in a given year. [See the docs here](https://docs.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting#analytics-finder)",
+  version: "0.0.4",
+  type: "action",
+  props: {
+    ...common.props,
+    startYear: {
+      propDefinition: [
+        common.props.app,
+        "startYear",
+      ],
+    },
+    timeGranularity: {
+      propDefinition: [
+        common.props.app,
+        "timeGranularity",
+      ],
+    },
+    adAccountId: {
+      propDefinition: [
+        common.props.app,
+        "adAccountId",
+      ],
+    },
+    campaignId: {
+      propDefinition: [
+        common.props.app,
+        "campaignId",
+        ({ adAccountId }) => ({
+          adAccountId,
+        }),
+      ],
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      getDateRangeParam,
+      startYear,
+      timeGranularity,
+      campaignId,
+      getListParam,
+      createReport,
+    } = this;
+
+    const response = await createReport({
+      $,
+      params: {
+        "q": "analytics",
+        "pivot": "CAMPAIGN",
+        "dateRange": getDateRangeParam(`${startYear}-01-01`),
+        timeGranularity,
+        "campaigns": getListParam([
+          app.getSponsoredCampaignUrn(campaignId),
+        ]),
+      },
+    });
+
+    $.export("$summary", "Successfully retrieved analytics");
+
+    return response;
+  },
+};

package/actions/send-conversion-event/send-conversion-event.mjs

@@ -0,0 +1,149 @@
+import { createHash } from "crypto";
+import app from "../../linkedin_ads.app.mjs";
+
+export default {
+  key: "linkedin_ads-send-conversion-event",
+  name: "Send Conversion Event",
+  description: "Sends a conversion event to LinkedIn Ads. [See the documentation](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversions-api?view=li-lms-2024-01&tabs=http#streaming-conversion-events)",
+  version: "0.0.3",
+  type: "action",
+  props: {
+    app,
+    adAccountId: {
+      propDefinition: [
+        app,
+        "adAccountId",
+      ],
+    },
+    conversionId: {
+      propDefinition: [
+        app,
+        "conversionId",
+        ({ adAccountId }) => ({
+          adAccountId,
+        }),
+      ],
+    },
+    conversionHappenedAt: {
+      type: "string",
+      label: "Conversion Happened At",
+      description: "Epoch timestamp in milliseconds at which the conversion event happened. Note: If your source records conversion timestamp in seconds, please insert 000 at the end to transform it to milliseconds. Eg. `1590739275000`.",
+    },
+    email: {
+      type: "string",
+      label: "Email",
+      description: "Email address of the contact associated with the conversion event which needs to be in SHA256 format, a HEX encoded string with a maximum length of 64 characters. Eg. `test@example.com`.",
+    },
+    firstName: {
+      type: "string",
+      label: "First Name",
+      description: "The first name of the contact to match the conversion.",
+    },
+    lastName: {
+      type: "string",
+      label: "Last Name",
+      description: "The last name of the contact to match the conversion.",
+    },
+    conversionValueCurrencyCode: {
+      type: "string",
+      label: "Conversion Value Currency Code",
+      description: "The currency code of the conversion value in ISO format. Eg. `USD`.",
+    },
+    conversionValueAmount: {
+      type: "string",
+      label: "Conversion Value Amount",
+      description: "The value of the conversion in decimal string. If you set this field, you must also set in the **Conversion Value Currency Code** field. Eg. `100.05`.",
+    },
+    companyName: {
+      type: "string",
+      label: "Company Name",
+      description: "A plain text string representing the company of the contact to match.",
+      optional: true,
+    },
+    title: {
+      type: "string",
+      label: "Title",
+      description: "A plain text string representing the title name of the contact to match. Eg. `Software Engineer`.",
+      optional: true,
+    },
+    countryCode: {
+      type: "string",
+      label: "Country Code",
+      description: "An ISO standardized [two letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) representing the country of the contact to match. Eg. `US`.",
+      optional: true,
+    },
+    eventId: {
+      type: "string",
+      label: "Event ID",
+      description: "The unique id generated by advertisers to indicate each event. This field is used for [deduplication](https://learn.microsoft.com/en-us/linkedin/marketing/conversions/deduplication?view=li-lms-2024-01).",
+      optional: true,
+    },
+  },
+  methods: {
+    emailToSha256(email) {
+      return createHash("sha256")
+        .update(email)
+        .digest("hex");
+    },
+    sendConversionEvent(args = {}) {
+      return this.app._makeRequest({
+        debug: true,
+        method: "POST",
+        path: "/conversionEvents",
+        ...args,
+      });
+    },
+  },
+  async run({ $ }) {
+    const {
+      app,
+      emailToSha256,
+      sendConversionEvent,
+      conversionId,
+      conversionHappenedAt,
+      conversionValueCurrencyCode,
+      conversionValueAmount,
+      email,
+      firstName,
+      lastName,
+      companyName,
+      title,
+      countryCode,
+      eventId,
+    } = this;
+
+    await sendConversionEvent({
+      $,
+      data: {
+        conversion: app.getConversionUrn(conversionId),
+        conversionHappenedAt: Number(conversionHappenedAt),
+        conversionValue: {
+          currencyCode: conversionValueCurrencyCode,
+          amount: conversionValueAmount,
+        },
+        user: {
+          userIds: [
+            {
+              idType: "SHA256_EMAIL",
+              idValue: emailToSha256(email),
+            },
+          ],
+          userInfo: {
+            firstName,
+            lastName,
+            companyName,
+            title,
+            countryCode,
+          },
+        },
+        eventId,
+      },
+    });
+
+    $.export("$summary", "Successfully sent conversion event to LinkedIn Ads");
+
+    return {
+      success: true,
+    };
+  },
+};

package/common/utils.mjs

@@ -0,0 +1,54 @@
+function encodeParamKeys(keys = []) {
+  return (key, value) => {
+    if (!keys.includes(key)) {
+      return `${key}=${value}`;
+    }
+    const [
+      firstPart,
+      ...otherParts
+    ] = value.split(":");
+
+    if (!firstPart?.startsWith("(")) {
+      const encoded = encodeURIComponent(value)
+        .replace("(", "%28")
+        .replace(")", "%29");
+      return `${key}=${encoded}`;
+    }
+
+    return `${key}=${firstPart}:${encodeURIComponent(otherParts.join(":"))}`;
+  };
+}
+
+function defaultEncodeFn(key, value) {
+  return `${key}=${value}`;
+}
+
+function encodeFn(key, value) {
+  return `${key}=${encodeURIComponent(value)}`;
+}
+
+function getParamsSerializer(encodeFn = defaultEncodeFn) {
+  return (params) => {
+    return Object.entries(params)
+      .map(([
+        key,
+        value,
+      ]) => encodeFn(key, value))
+      .join("&");
+  };
+}
+
+function transformResponse(jsonStr) {
+  // Regex to target specifically "id" fields, capturing
+  // the number to convert it into a string
+  // Because the number can be a long number or big integer
+  const response = jsonStr.replace(/("id"\s*:\s*)(\d+)/g, "$1\"$2\"");
+  return JSON.parse(response);
+}
+
+export default {
+  encodeParamKeys,
+  encodeFn,
+  getParamsSerializer,
+  transformResponse,
+};

package/linkedin_ads.app.mjs

@@ -132,7 +132,6 @@ export default {
       }) {
         const count = 20;
         const { elements } = await this.searchLeadForms({
-          debug: true,
           params: {
             q: "owner",
             owner: `(sponsoredAccount:${this.getSponsoredAccountUrn(adAccountId)})`,
@@ -192,7 +191,6 @@ export default {
       leadFormId, ...args
     } = {}) {
       return this._makeRequest({
-        debug: true,
         path: `/leadForms/${leadFormId}`,
         ...args,
       });
@@ -202,7 +200,6 @@ export default {
         "organizer",
       ];
       return this._makeRequest({
-        debug: true,
         path: "/events",
         paramsSerializer: utils.getParamsSerializer(utils.encodeParamKeys(keys)),
         transformResponse: utils.transformResponse,
@@ -211,7 +208,6 @@ export default {
     },
     searchConversions(args = {}) {
       return this._makeRequest({
-        debug: true,
         path: "/conversions",
         paramsSerializer: utils.getParamsSerializer(utils.encodeFn),
         ...args,
@@ -224,7 +220,6 @@ export default {
         "associatedEntity",
       ];
       return this._makeRequest({
-        debug: true,
         path: "/leadFormResponses",
         paramsSerializer: utils.getParamsSerializer(utils.encodeParamKeys(keys)),
         ...args,

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@pipedream/linkedin_ads",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Pipedream LinkedIn Ads Components",
   "main": "linkedin_ads.app.mjs",
   "keywords": [
     "pipedream",
     "linkedin_ads"
   ],
-  "files": [
-    "dist"
-  ],
   "homepage": "https://pipedream.com/apps/linkedin_ads",
   "author": "Pipedream <support@pipedream.com> (https://pipedream.com/)",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@pipedream/platform": "^3.0.3"
   }
 }

package/sources/new-event-registration-form-response/new-event-registration-form-response.mjs

@@ -0,0 +1,62 @@
+import { DEFAULT_POLLING_SOURCE_TIMER_INTERVAL } from "@pipedream/platform";
+import app from "../../linkedin_ads.app.mjs";
+
+export default {
+  key: "linkedin_ads-new-event-registration-form-response",
+  name: "New Event Registration Form Response",
+  description: "Emit new event when a fresh response is received on the event registration form. User needs to configure the prop of the specific event. [See the documentation](https://learn.microsoft.com/en-us/linkedin/marketing/community-management/organizations/events?view=li-lms-2024-01&tabs=http)",
+  version: "0.0.3",
+  type: "source",
+  dedupe: "unique",
+  props: {
+    app,
+    timer: {
+      type: "$.interface.timer",
+      default: {
+        intervalSeconds: DEFAULT_POLLING_SOURCE_TIMER_INTERVAL,
+      },
+    },
+    organizationId: {
+      propDefinition: [
+        app,
+        "organizationId",
+      ],
+    },
+    eventId: {
+      propDefinition: [
+        app,
+        "eventId",
+        ({ organizationId }) => ({
+          organizationId,
+        }),
+      ],
+    },
+  },
+  async run() {
+    const {
+      app,
+      organizationId,
+      eventId,
+    } = this;
+
+    const { elements } = await app.searchLeadFormResponses({
+      params: {
+        q: "owner",
+        owner: `(organization:${app.getOrganizationUrn(organizationId)})`,
+        leadType: "(leadType:EVENT)",
+        limitedToTestLeads: false,
+        associatedEntity: app.getEventUrn(eventId),
+      },
+    });
+
+    elements
+      .reverse()
+      .forEach((event) => {
+        this.$emit(event, {
+          id: event.id,
+          summary: `New Event Registration: ${event.id}`,
+          ts: event.submittedAt,
+        });
+      });
+  },
+};

package/sources/new-lead-gen-form-created/new-lead-gen-form-created.mjs

@@ -0,0 +1,68 @@
+import { DEFAULT_POLLING_SOURCE_TIMER_INTERVAL } from "@pipedream/platform";
+import app from "../../linkedin_ads.app.mjs";
+import sampleEmit from "./test-event.mjs";
+
+export default {
+  key: "linkedin_ads-new-lead-gen-form-created",
+  name: "New Lead Gen Form Created",
+  description: "Emit new event when a new lead is captured through a form. [See the documentation](https://learn.microsoft.com/en-us/linkedin/marketing/lead-sync/leadsync?view=li-lms-2023-07&tabs=http#find-lead-form-responses-by-owner)",
+  version: "0.0.2",
+  type: "source",
+  dedupe: "unique",
+  props: {
+    app,
+    timer: {
+      type: "$.interface.timer",
+      default: {
+        intervalSeconds: DEFAULT_POLLING_SOURCE_TIMER_INTERVAL,
+      },
+    },
+    adAccountId: {
+      propDefinition: [
+        app,
+        "adAccountId",
+      ],
+    },
+    leadFormId: {
+      propDefinition: [
+        app,
+        "leadFormId",
+        ({ adAccountId }) => ({
+          adAccountId,
+        }),
+      ],
+    },
+  },
+  async run() {
+    const {
+      app,
+      adAccountId,
+      leadFormId,
+    } = this;
+
+    const { versionId: leadFormVersionId } = await app.getLeadForm({
+      leadFormId,
+    });
+
+    const { elements } = await app.searchLeadFormResponses({
+      params: {
+        q: "owner",
+        owner: `(sponsoredAccount:${app.getSponsoredAccountUrn(adAccountId)})`,
+        leadType: "(leadType:SPONSORED)",
+        limitedToTestLeads: false,
+        versionedLeadGenFormUrn: app.getVersionedLeadGenFormUrn(leadFormId, leadFormVersionId),
+      },
+    });
+
+    elements
+      .reverse()
+      .forEach((event) => {
+        this.$emit(event, {
+          id: event.id,
+          summary: `New Lead Gen: ${event.id}`,
+          ts: event.submittedAt,
+        });
+      });
+  },
+  sampleEmit,
+};

package/sources/new-lead-gen-form-created/test-event.mjs

@@ -0,0 +1,48 @@
+export default {
+  "owner": {
+    "sponsoredAccount": "urn:li:sponsoredAccount:1232131"
+  },
+  "submitter": "urn:li:person:0",
+  "leadType": "SPONSORED",
+  "leadMetadata": {
+    "sponsoredLeadMetadata": {
+      "campaign": "urn:li:sponsoredCampaign:32131231"
+    }
+  },
+  "versionedLeadGenFormUrn": "urn:li:versionedLeadGenForm:(urn:li:leadGenForm:3213,1)",
+  "id": "52dcb737-26f9-4af3-b1fc-935b3e93f838-4",
+  "submittedAt": 1706741502694,
+  "testLead": true,
+  "associatedEntity": {
+    "associatedCreative": "urn:li:sponsoredCreative:369799186"
+  },
+  "formResponse": {
+    "consentResponses": [],
+    "answers": [
+      {
+        "answerDetails": {
+          "textQuestionAnswer": {
+            "answer": "test1@gmail.com"
+          }
+        },
+        "questionId": 20502584796
+      },
+      {
+        "answerDetails": {
+          "textQuestionAnswer": {
+            "answer": "Test 1"
+          }
+        },
+        "questionId": 20502643516
+      },
+      {
+        "answerDetails": {
+          "textQuestionAnswer": {
+            "answer": "Test 1"
+          }
+        },
+        "questionId": 20502667260
+      }
+    ]
+  }
+};