@oneuptime/common 11.5.9 → 11.5.11

package/Server/Utils/Attribution.ts

@@ -0,0 +1,99 @@
+import { JSONObject, JSONValue } from "../../Types/JSON";
+
+/*
+ * Sanitizers for the publicly-creatable attribution jsonb columns on User
+ * (clickIds, firstTouchAttribution). Unauthenticated signup can submit these,
+ * so — unlike the varchar(500)-bounded utm columns — they must be whitelisted
+ * and size-bounded here before they are persisted, copied onto projects, and
+ * forwarded to analytics.
+ */
+
+const MAX_VALUE_LENGTH: number = 500;
+
+const CLICK_ID_KEYS: Array<string> = [
+  "gclid",
+  "wbraid",
+  "gbraid",
+  "fbclid",
+  "msclkid",
+  "li_fat_id",
+  "twclid",
+  "rdt_cid",
+];
+
+const FIRST_TOUCH_STRING_KEYS: Array<string> = [
+  "utmSource",
+  "utmMedium",
+  "utmCampaign",
+  "utmTerm",
+  "utmContent",
+  "landingUrl",
+  "referrer",
+  "timestamp",
+];
+
+type SanitizeStringValueFunction = (value: JSONValue) => string | null;
+
+const sanitizeStringValue: SanitizeStringValueFunction = (
+  value: JSONValue,
+): string | null => {
+  if (typeof value === "string" && value.length > 0) {
+    return value.slice(0, MAX_VALUE_LENGTH);
+  }
+
+  if (typeof value === "number") {
+    return value.toString().slice(0, MAX_VALUE_LENGTH);
+  }
+
+  return null;
+};
+
+export default class Attribution {
+  // Whitelist known ad-platform click id keys; bound each value to 500 chars.
+  public static sanitizeClickIds(value: JSONValue): JSONObject | undefined {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return undefined;
+    }
+
+    const input: JSONObject = value as JSONObject;
+    const result: JSONObject = {};
+
+    for (const key of CLICK_ID_KEYS) {
+      const sanitized: string | null = sanitizeStringValue(input[key]);
+      if (sanitized) {
+        result[key] = sanitized;
+      }
+    }
+
+    return Object.keys(result).length > 0 ? result : undefined;
+  }
+
+  // Whitelist the first-touch shape written by the marketing site.
+  public static sanitizeFirstTouchAttribution(
+    value: JSONValue,
+  ): JSONObject | undefined {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return undefined;
+    }
+
+    const input: JSONObject = value as JSONObject;
+    const result: JSONObject = {};
+
+    for (const key of FIRST_TOUCH_STRING_KEYS) {
+      const sanitized: string | null = sanitizeStringValue(input[key]);
+      if (sanitized) {
+        result[key] = sanitized;
+      }
+    }
+
+    const clickIds: JSONObject | undefined = this.sanitizeClickIds(
+      input["clickIds"],
+    );
+
+    if (clickIds) {
+      result["clickIds"] = clickIds;
+    }
+
+    return Object.keys(result).length > 0 ? result : undefined;
+  }
+}

package/Server/Utils/Marketing/ConversionUploadProvider.ts

@@ -0,0 +1,103 @@
+import { AxiosError } from "axios";
+import { JSONObject } from "../../../Types/JSON";
+import { MarketingConversionType } from "../../../Types/Marketing/MarketingConversion";
+import MarketingConversion from "../../../Models/DatabaseModels/MarketingConversion";
+
+/*
+ * One implementation per ad platform. The MarketingConversions worker job
+ * iterates all configured providers and uploads every pending conversion to
+ * each of them, tracking per-provider status in
+ * MarketingConversion.uploadState (keyed by `key`).
+ *
+ * Contract:
+ * - getSkipReason returns a human-readable reason when this conversion can
+ *   never be uploaded to this platform (wrong/missing click id, outside the
+ *   platform's upload window, provider not configured for this conversion
+ *   type). Null means uploadable.
+ * - upload() sends one batch. Per-conversion PERMANENT rejections are
+ *   returned in the result keyed by array index; they will not be retried.
+ *   Transport/auth-level failures must THROW — the whole batch stays pending
+ *   and is retried on the next run (bounded by the job's attempt cap), so
+ *   providers should be safe against duplicate delivery where the platform
+ *   supports an idempotency/dedup key.
+ */
+
+export interface ConversionUploadBatchResult {
+  // Index into the submitted batch -> permanent failure message.
+  permanentFailures: Map<number, string>;
+}
+
+export interface ConversionSkip {
+  reason: string;
+  /*
+   * Permanent skips (missing click id, outside the platform's upload window)
+   * are recorded as Skipped and never revisited. Non-permanent skips
+   * (missing provider configuration such as a conversion action id) leave
+   * the conversion pending so it uploads once the configuration is added.
+   */
+  isPermanent: boolean;
+}
+
+export default abstract class ConversionUploadProvider {
+  // Stable key used in MarketingConversion.uploadState. Never change it.
+  public abstract readonly key: string;
+  public abstract readonly displayName: string;
+
+  /*
+   * Max conversions this provider accepts in one upload() call. Providers
+   * that issue one HTTP request per conversion must keep this small so a
+   * single run finishes well inside the worker job timeout.
+   */
+  public readonly maxBatchSize: number = 500;
+
+  public abstract isConfigured(): boolean;
+
+  public abstract getSkipReason(
+    conversion: MarketingConversion,
+  ): ConversionSkip | null;
+
+  public abstract upload(
+    conversions: Array<MarketingConversion>,
+  ): Promise<ConversionUploadBatchResult>;
+
+  protected getClickId(
+    conversion: MarketingConversion,
+    clickIdKey: string,
+  ): string | undefined {
+    const clickIds: JSONObject = conversion.clickIds || {};
+    const value: unknown = clickIds[clickIdKey];
+    return typeof value === "string" && value ? value : undefined;
+  }
+
+  protected getValueInUSD(conversion: MarketingConversion): number | undefined {
+    if (
+      conversion.conversionValueInUSDCents === undefined ||
+      conversion.conversionValueInUSDCents === null ||
+      conversion.conversionValueInUSDCents <= 0
+    ) {
+      return undefined;
+    }
+    return conversion.conversionValueInUSDCents / 100;
+  }
+
+  protected isSignUp(conversion: MarketingConversion): boolean {
+    return conversion.conversionType === MarketingConversionType.SignUp;
+  }
+
+  protected isOlderThanDays(
+    conversion: MarketingConversion,
+    days: number,
+  ): boolean {
+    const conversionAt: Date = conversion.conversionAt || new Date();
+    return Date.now() - conversionAt.getTime() > days * 24 * 60 * 60 * 1000;
+  }
+
+  public static getErrorMessage(err: unknown): string {
+    if (err instanceof AxiosError) {
+      return `HTTP ${err.response?.status || "?"}: ${JSON.stringify(
+        err.response?.data || err.message,
+      ).slice(0, 900)}`;
+    }
+    return (err as Error)?.message || "Unknown error";
+  }
+}

package/Server/Utils/Marketing/ConversionUploadProviders.ts

@@ -0,0 +1,22 @@
+import ConversionUploadProvider from "./ConversionUploadProvider";
+import GoogleAdsProvider from "./Providers/GoogleAds";
+import LinkedInProvider from "./Providers/LinkedIn";
+import MetaProvider from "./Providers/Meta";
+import MicrosoftAdsProvider from "./Providers/MicrosoftAds";
+import RedditProvider from "./Providers/Reddit";
+
+/*
+ * All ad platforms OneUptime can upload offline conversions to. To add a
+ * platform: implement ConversionUploadProvider (one file under Providers/),
+ * add its env config to EnvironmentConfig, and list it here — no schema or
+ * worker changes needed. Unconfigured providers are ignored at runtime.
+ */
+const AllConversionUploadProviders: Array<ConversionUploadProvider> = [
+  new GoogleAdsProvider(),
+  new MetaProvider(),
+  new MicrosoftAdsProvider(),
+  new LinkedInProvider(),
+  new RedditProvider(),
+];
+
+export default AllConversionUploadProviders;

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 };
+  }
+}