@oneuptime/common 11.5.8 → 11.5.10

package/Server/Utils/Marketing/Providers/GoogleAds.ts

@@ -0,0 +1,270 @@
+import axios, { AxiosResponse } from "axios";
+import {
+  GoogleAdsApiVersion,
+  GoogleAdsCustomerId,
+  GoogleAdsDeveloperToken,
+  GoogleAdsLoginCustomerId,
+  GoogleAdsOAuthClientId,
+  GoogleAdsOAuthClientSecret,
+  GoogleAdsOAuthRefreshToken,
+  GoogleAdsPaidSubscriptionConversionActionId,
+  GoogleAdsSignUpConversionActionId,
+} from "../../../EnvironmentConfig";
+import ConversionUploadProvider, {
+  ConversionSkip,
+  ConversionUploadBatchResult,
+} from "../ConversionUploadProvider";
+import { JSONObject } from "../../../../Types/JSON";
+import MarketingConversion from "../../../../Models/DatabaseModels/MarketingConversion";
+import logger from "../../Logger";
+
+const REQUEST_TIMEOUT_MS: number = 30000;
+
+// Google Ads accepts click conversions up to 90 days after the click.
+const GOOGLE_MAX_CONVERSION_AGE_IN_DAYS: number = 90;
+
+/*
+ * Google Ads offline click conversions
+ * (customers/{id}:uploadClickConversions) with OAuth2 refresh-token auth.
+ * Supports gclid, wbraid and gbraid click ids. Uses partialFailure so valid
+ * conversions succeed even when others in the batch fail.
+ */
+export default class GoogleAdsProvider extends ConversionUploadProvider {
+  public override readonly key: string = "google";
+  public override readonly displayName: string = "Google Ads";
+
+  private cachedAccessToken: string | null = null;
+  private cachedAccessTokenExpiresAt: number = 0;
+
+  public override isConfigured(): boolean {
+    return Boolean(
+      GoogleAdsDeveloperToken &&
+        GoogleAdsOAuthClientId &&
+        GoogleAdsOAuthClientSecret &&
+        GoogleAdsOAuthRefreshToken &&
+        GoogleAdsCustomerId,
+    );
+  }
+
+  public override getSkipReason(
+    conversion: MarketingConversion,
+  ): ConversionSkip | null {
+    if (!this.getGoogleClickId(conversion)) {
+      return {
+        reason: "No Google click id (gclid/wbraid/gbraid)",
+        isPermanent: true,
+      };
+    }
+
+    if (!this.getConversionActionId(conversion)) {
+      // Config gap — leave pending so it uploads once the id is configured.
+      return {
+        reason:
+          "No Google Ads conversion action id configured for this conversion type",
+        isPermanent: false,
+      };
+    }
+
+    if (this.isOlderThanDays(conversion, GOOGLE_MAX_CONVERSION_AGE_IN_DAYS)) {
+      return {
+        reason: "Conversion older than Google's 90-day click window",
+        isPermanent: true,
+      };
+    }
+
+    return null;
+  }
+
+  private getGoogleClickId(conversion: MarketingConversion): JSONObject | null {
+    const gclid: string | undefined = this.getClickId(conversion, "gclid");
+    if (gclid) {
+      return { gclid: gclid };
+    }
+
+    const wbraid: string | undefined = this.getClickId(conversion, "wbraid");
+    if (wbraid) {
+      return { wbraid: wbraid };
+    }
+
+    const gbraid: string | undefined = this.getClickId(conversion, "gbraid");
+    if (gbraid) {
+      return { gbraid: gbraid };
+    }
+
+    return null;
+  }
+
+  private getConversionActionId(conversion: MarketingConversion): string {
+    return this.isSignUp(conversion)
+      ? GoogleAdsSignUpConversionActionId
+      : GoogleAdsPaidSubscriptionConversionActionId;
+  }
+
+  private async getAccessToken(): Promise<string> {
+    if (
+      this.cachedAccessToken &&
+      Date.now() < this.cachedAccessTokenExpiresAt
+    ) {
+      return this.cachedAccessToken;
+    }
+
+    const params: URLSearchParams = new URLSearchParams();
+    params.append("client_id", GoogleAdsOAuthClientId);
+    params.append("client_secret", GoogleAdsOAuthClientSecret);
+    params.append("refresh_token", GoogleAdsOAuthRefreshToken);
+    params.append("grant_type", "refresh_token");
+
+    const response: AxiosResponse<{
+      access_token?: string;
+      expires_in?: number;
+    }> = await axios.post(
+      "https://oauth2.googleapis.com/token",
+      params.toString(),
+      {
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+        },
+        timeout: REQUEST_TIMEOUT_MS,
+      },
+    );
+
+    const accessToken: string | undefined = response.data?.access_token;
+
+    if (!accessToken) {
+      throw new Error("Google OAuth token response had no access_token");
+    }
+
+    this.cachedAccessToken = accessToken;
+    // Refresh one minute before actual expiry.
+    this.cachedAccessTokenExpiresAt =
+      Date.now() + ((response.data?.expires_in || 3600) - 60) * 1000;
+
+    return accessToken;
+  }
+
+  // Format Google Ads expects: "yyyy-mm-dd hh:mm:ss+00:00".
+  private formatConversionDateTime(date: Date): string {
+    const iso: string = date.toISOString(); // 2026-07-18T12:34:56.789Z
+    return `${iso.slice(0, 10)} ${iso.slice(11, 19)}+00:00`;
+  }
+
+  public override async upload(
+    conversions: Array<MarketingConversion>,
+  ): Promise<ConversionUploadBatchResult> {
+    const accessToken: string = await this.getAccessToken();
+
+    const headers: JSONObject = {
+      Authorization: `Bearer ${accessToken}`,
+      "developer-token": GoogleAdsDeveloperToken,
+    };
+
+    if (GoogleAdsLoginCustomerId) {
+      headers["login-customer-id"] = GoogleAdsLoginCustomerId;
+    }
+
+    const body: JSONObject = {
+      conversions: conversions.map((conversion: MarketingConversion) => {
+        const payload: JSONObject = {
+          ...(this.getGoogleClickId(conversion) || {}),
+          conversionAction: `customers/${GoogleAdsCustomerId}/conversionActions/${this.getConversionActionId(
+            conversion,
+          )}`,
+          conversionDateTime: this.formatConversionDateTime(
+            conversion.conversionAt || new Date(),
+          ),
+        };
+
+        const valueInUSD: number | undefined = this.getValueInUSD(conversion);
+
+        if (valueInUSD !== undefined) {
+          payload["conversionValue"] = valueInUSD;
+          payload["currencyCode"] = "USD";
+        }
+
+        return payload;
+      }),
+      partialFailure: true,
+    };
+
+    const url: string = `https://googleads.googleapis.com/${GoogleAdsApiVersion}/customers/${GoogleAdsCustomerId}:uploadClickConversions`;
+
+    const response: AxiosResponse<JSONObject> = await axios.post(url, body, {
+      headers: headers as Record<string, string>,
+      timeout: REQUEST_TIMEOUT_MS,
+    });
+
+    return this.parsePartialFailure(response.data);
+  }
+
+  /*
+   * partialFailureError.details[].errors[] entries carry the index of the
+   * failing operation in location.fieldPathElements ({fieldName:
+   * "conversions", index: N}).
+   */
+  private parsePartialFailure(
+    responseData: JSONObject,
+  ): ConversionUploadBatchResult {
+    const permanentFailures: Map<number, string> = new Map<number, string>();
+
+    const partialFailureError: JSONObject | undefined = responseData?.[
+      "partialFailureError"
+    ] as JSONObject | undefined;
+
+    if (!partialFailureError) {
+      return { permanentFailures };
+    }
+
+    const details: Array<JSONObject> =
+      (partialFailureError["details"] as Array<JSONObject>) || [];
+
+    let alreadyExistsCount: number = 0;
+
+    for (const detail of details) {
+      const errors: Array<JSONObject> =
+        (detail["errors"] as Array<JSONObject>) || [];
+
+      for (const error of errors) {
+        const message: string =
+          (error["message"] as string) || "Unknown Google Ads error";
+
+        /*
+         * A duplicate rejection means the conversion WAS counted by a prior
+         * run (e.g. crash between upload and status write) — that is a
+         * success, not a failure.
+         */
+        if (JSON.stringify(error).includes("ALREADY_EXISTS")) {
+          alreadyExistsCount++;
+          continue;
+        }
+
+        const fieldPathElements: Array<JSONObject> =
+          ((error["location"] as JSONObject)?.[
+            "fieldPathElements"
+          ] as Array<JSONObject>) || [];
+
+        for (const element of fieldPathElements) {
+          if (
+            element["fieldName"] === "conversions" &&
+            typeof element["index"] === "number"
+          ) {
+            permanentFailures.set(element["index"] as number, message);
+          }
+        }
+      }
+    }
+
+    /*
+     * A partial failure with no parseable indexes should not be silently
+     * treated as full success.
+     */
+    if (permanentFailures.size === 0 && alreadyExistsCount === 0) {
+      logger.error(
+        `Google Ads partial failure with unparseable indexes: ${JSON.stringify(
+          partialFailureError,
+        ).slice(0, 1000)}`,
+      );
+    }
+
+    return { permanentFailures };
+  }
+}

package/Server/Utils/Marketing/Providers/LinkedIn.ts

@@ -0,0 +1,147 @@
+import axios, { AxiosError } from "axios";
+import {
+  LinkedInApiVersion,
+  LinkedInConversionsAccessToken,
+  LinkedInPaidSubscriptionConversionId,
+  LinkedInSignUpConversionId,
+} from "../../../EnvironmentConfig";
+import ConversionUploadProvider, {
+  ConversionSkip,
+  ConversionUploadBatchResult,
+} from "../ConversionUploadProvider";
+import { JSONObject } from "../../../../Types/JSON";
+import MarketingConversion from "../../../../Models/DatabaseModels/MarketingConversion";
+
+const REQUEST_TIMEOUT_MS: number = 30000;
+
+// LinkedIn accepts conversions up to 90 days after the interaction.
+const LINKEDIN_MAX_CONVERSION_AGE_IN_DAYS: number = 90;
+
+/*
+ * LinkedIn Conversions API (api.linkedin.com/rest/conversionEvents) using
+ * the li_fat_id first-party click id. Conversion rules are referenced by
+ * urn:lla:llaPartnerConversion:{id}. Events are posted one at a time (small
+ * volumes); auth-level failures abort the batch for retry, other per-event
+ * rejections are recorded as permanent.
+ *
+ * Note: LinkedIn access tokens expire (typically 60 days) — the token in
+ * LINKEDIN_CONVERSIONS_ACCESS_TOKEN must be rotated externally.
+ */
+export default class LinkedInProvider extends ConversionUploadProvider {
+  public override readonly key: string = "linkedin";
+  public override readonly displayName: string = "LinkedIn";
+
+  /*
+   * LinkedIn has no batch endpoint, so upload() issues one request per
+   * conversion — keep runs short enough to finish inside the job timeout.
+   */
+  public override readonly maxBatchSize: number = 50;
+
+  public override isConfigured(): boolean {
+    return Boolean(LinkedInConversionsAccessToken);
+  }
+
+  public override getSkipReason(
+    conversion: MarketingConversion,
+  ): ConversionSkip | null {
+    if (!this.getClickId(conversion, "li_fat_id")) {
+      return {
+        reason: "No LinkedIn click id (li_fat_id)",
+        isPermanent: true,
+      };
+    }
+
+    if (!this.getConversionRuleId(conversion)) {
+      // Config gap — leave pending so it uploads once the id is configured.
+      return {
+        reason:
+          "No LinkedIn conversion rule id configured for this conversion type",
+        isPermanent: false,
+      };
+    }
+
+    if (this.isOlderThanDays(conversion, LINKEDIN_MAX_CONVERSION_AGE_IN_DAYS)) {
+      return {
+        reason: "Conversion older than LinkedIn's 90-day window",
+        isPermanent: true,
+      };
+    }
+
+    return null;
+  }
+
+  private getConversionRuleId(conversion: MarketingConversion): string {
+    return this.isSignUp(conversion)
+      ? LinkedInSignUpConversionId
+      : LinkedInPaidSubscriptionConversionId;
+  }
+
+  public override async upload(
+    conversions: Array<MarketingConversion>,
+  ): Promise<ConversionUploadBatchResult> {
+    const permanentFailures: Map<number, string> = new Map<number, string>();
+
+    for (let i: number = 0; i < conversions.length; i++) {
+      const conversion: MarketingConversion = conversions[i]!;
+
+      const body: JSONObject = {
+        conversion: `urn:lla:llaPartnerConversion:${this.getConversionRuleId(
+          conversion,
+        )}`,
+        conversionHappenedAt: (conversion.conversionAt || new Date()).getTime(),
+        // Dedup key: a retried batch must not double-count conversions.
+        eventId: conversion.id!.toString(),
+        user: {
+          userIds: [
+            {
+              idType: "LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID",
+              idValue: this.getClickId(conversion, "li_fat_id") || "",
+            },
+          ],
+        },
+      };
+
+      const valueInUSD: number | undefined = this.getValueInUSD(conversion);
+
+      if (valueInUSD !== undefined) {
+        body["conversionValue"] = {
+          currencyCode: "USD",
+          amount: valueInUSD.toFixed(2),
+        };
+      }
+
+      try {
+        await axios.post(
+          "https://api.linkedin.com/rest/conversionEvents",
+          body,
+          {
+            headers: {
+              Authorization: `Bearer ${LinkedInConversionsAccessToken}`,
+              "LinkedIn-Version": LinkedInApiVersion,
+              "X-Restli-Protocol-Version": "2.0.0",
+              "Content-Type": "application/json",
+            },
+            timeout: REQUEST_TIMEOUT_MS,
+          },
+        );
+      } catch (err) {
+        const status: number | undefined = (err as AxiosError).response?.status;
+
+        /*
+         * Only definitive per-event validation rejections are permanent.
+         * Everything else — auth/token problems, rate limits, 5xx, and
+         * network errors (no response, so no status) — is transport-level:
+         * throw so the whole batch stays pending and is retried. eventId
+         * makes redelivery idempotent on LinkedIn's side.
+         */
+        if (status !== 400 && status !== 422) {
+          throw err;
+        }
+
+        permanentFailures.set(i, ConversionUploadProvider.getErrorMessage(err));
+      }
+    }
+
+    return { permanentFailures };
+  }
+}

package/Server/Utils/Marketing/Providers/Meta.ts

@@ -0,0 +1,148 @@
+import axios, { AxiosResponse } from "axios";
+import crypto from "crypto";
+import {
+  MetaConversionsAccessToken,
+  MetaConversionsPixelId,
+  MetaGraphApiVersion,
+} from "../../../EnvironmentConfig";
+import ConversionUploadProvider, {
+  ConversionSkip,
+  ConversionUploadBatchResult,
+} from "../ConversionUploadProvider";
+import { JSONObject } from "../../../../Types/JSON";
+import MarketingConversion from "../../../../Models/DatabaseModels/MarketingConversion";
+
+const REQUEST_TIMEOUT_MS: number = 30000;
+
+// Meta rejects website events older than 7 days at upload time.
+const META_MAX_EVENT_AGE_IN_DAYS: number = 7;
+
+/*
+ * Meta (Facebook) Conversions API
+ * (graph.facebook.com/{version}/{pixelId}/events). Emails are SHA-256 hashed
+ * per Meta's customer-information matching spec; the raw email never leaves
+ * OneUptime. event_id is the conversion row id, so Meta deduplicates
+ * retried uploads (and browser-pixel duplicates) server-side.
+ */
+export default class MetaProvider extends ConversionUploadProvider {
+  public override readonly key: string = "meta";
+  public override readonly displayName: string = "Meta";
+
+  public override isConfigured(): boolean {
+    return Boolean(MetaConversionsPixelId && MetaConversionsAccessToken);
+  }
+
+  public override getSkipReason(
+    conversion: MarketingConversion,
+  ): ConversionSkip | null {
+    if (!this.getClickId(conversion, "fbclid")) {
+      return {
+        reason: "No Meta click id (fbclid)",
+        isPermanent: true,
+      };
+    }
+
+    if (this.isOlderThanDays(conversion, META_MAX_EVENT_AGE_IN_DAYS)) {
+      return {
+        reason: "Conversion older than Meta's 7-day upload window",
+        isPermanent: true,
+      };
+    }
+
+    return null;
+  }
+
+  private hashEmail(email: string): string {
+    return crypto
+      .createHash("sha256")
+      .update(email.trim().toLowerCase())
+      .digest("hex");
+  }
+
+  /*
+   * fbc format per Meta spec: fb.1.{creationTimeMs}.{fbclid}. We use the
+   * conversion time as creation time since the original click timestamp is
+   * not stored.
+   */
+  private buildFbc(fbclid: string, eventAt: Date): string {
+    return `fb.1.${eventAt.getTime()}.${fbclid}`;
+  }
+
+  public override async upload(
+    conversions: Array<MarketingConversion>,
+  ): Promise<ConversionUploadBatchResult> {
+    const data: Array<JSONObject> = conversions.map(
+      (conversion: MarketingConversion) => {
+        const eventAt: Date = conversion.conversionAt || new Date();
+        const fbclid: string = this.getClickId(conversion, "fbclid") || "";
+
+        const userData: JSONObject = {
+          fbc: this.buildFbc(fbclid, eventAt),
+        };
+
+        if (conversion.email) {
+          userData["em"] = [this.hashEmail(conversion.email)];
+        }
+
+        const isSignUp: boolean = this.isSignUp(conversion);
+
+        const payload: JSONObject = {
+          event_name: isSignUp ? "CompleteRegistration" : "Purchase",
+          event_time: Math.floor(eventAt.getTime() / 1000),
+          event_id: conversion.id!.toString(),
+          /*
+           * Not "website": website events REQUIRE client_user_agent and
+           * event_source_url, which a server-side backfill does not have —
+           * Meta rejects the whole batch without them.
+           */
+          action_source: "other",
+          user_data: userData,
+        };
+
+        const valueInUSD: number | undefined = this.getValueInUSD(conversion);
+
+        /*
+         * Purchase events REQUIRE custom_data.value and currency — one
+         * valueless Purchase (custom-pricing plan) would 400 the entire
+         * batch. Send 0 when the value is unknown.
+         */
+        if (!isSignUp || valueInUSD !== undefined) {
+          payload["custom_data"] = {
+            value: valueInUSD ?? 0,
+            currency: "USD",
+          };
+        }
+
+        return payload;
+      },
+    );
+
+    const url: string = `https://graph.facebook.com/${MetaGraphApiVersion}/${MetaConversionsPixelId}/events`;
+
+    const response: AxiosResponse<JSONObject> = await axios.post(
+      url,
+      {
+        data: data,
+        access_token: MetaConversionsAccessToken,
+      },
+      {
+        timeout: REQUEST_TIMEOUT_MS,
+      },
+    );
+
+    const eventsReceived: number =
+      (response.data?.["events_received"] as number) || 0;
+
+    if (eventsReceived !== conversions.length) {
+      /*
+       * Retrying the whole batch is safe: event_id makes redelivery
+       * idempotent on Meta's side.
+       */
+      throw new Error(
+        `Meta accepted ${eventsReceived} of ${conversions.length} events`,
+      );
+    }
+
+    return { permanentFailures: new Map<number, string>() };
+  }
+}