@oneuptime/common 12.0.17 → 12.0.19

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

@@ -1,185 +0,0 @@
-import axios, { AxiosError } from "axios";
-import {
-  LinkedInApiVersion,
-  LinkedInConversionsAccessToken,
-  LinkedInMeetingBookedConversionId,
-  LinkedInPaidSubscriptionConversionId,
-  LinkedInSignUpConversionId,
-} from "../../../EnvironmentConfig";
-import ConversionUploadProvider, {
-  ConversionSkip,
-  ConversionTypeMapping,
-  ConversionUploadBatchResult,
-} from "../ConversionUploadProvider";
-import { JSONObject } from "../../../../Types/JSON";
-import { MarketingConversionType } from "../../../../Types/Marketing/MarketingConversion";
-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) matching
- * on the li_fat_id first-party click id, a SHA-256 email, or both — LinkedIn
- * accepts several userIds and resolves whichever it can. 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);
-  }
-
-  protected override getProviderSkipReason(
-    conversion: MarketingConversion,
-  ): ConversionSkip | null {
-    if (this.getUserIds(conversion).length === 0) {
-      return {
-        reason: "No LinkedIn click id (li_fat_id) and no email to match on",
-        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 {
-    const mapping: ConversionTypeMapping<string> = {
-      [MarketingConversionType.SignUp]: LinkedInSignUpConversionId,
-      [MarketingConversionType.MeetingBooked]:
-        LinkedInMeetingBookedConversionId,
-      [MarketingConversionType.PaidSubscription]:
-        LinkedInPaidSubscriptionConversionId,
-    };
-
-    return this.resolveByConversionType(conversion, mapping) || "";
-  }
-
-  /*
-   * Every identifier LinkedIn can resolve this person by. Sending both when
-   * both exist raises the match rate; sending only the email is how a demo
-   * booked on one device and a licence signed on another are still joined to
-   * the click that started it.
-   */
-  private getUserIds(conversion: MarketingConversion): Array<JSONObject> {
-    const userIds: Array<JSONObject> = [];
-
-    const clickId: string | undefined = this.getClickId(
-      conversion,
-      "li_fat_id",
-    );
-
-    if (clickId) {
-      userIds.push({
-        idType: "LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID",
-        idValue: clickId,
-      });
-    }
-
-    const hashedEmail: string | undefined = this.getHashedEmail(conversion);
-
-    if (hashedEmail) {
-      userIds.push({
-        idType: "SHA256_EMAIL",
-        idValue: hashedEmail,
-      });
-    }
-
-    return userIds;
-  }
-
-  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: this.getUserIds(conversion),
-        },
-      };
-
-      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

@@ -1,182 +0,0 @@
-import axios, { AxiosResponse } from "axios";
-import {
-  MetaConversionsAccessToken,
-  MetaConversionsPixelId,
-  MetaGraphApiVersion,
-} from "../../../EnvironmentConfig";
-import ConversionUploadProvider, {
-  ConversionSkip,
-  ConversionTypeMapping,
-  ConversionUploadBatchResult,
-} from "../ConversionUploadProvider";
-import { JSONObject } from "../../../../Types/JSON";
-import { MarketingConversionType } from "../../../../Types/Marketing/MarketingConversion";
-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.
- *
- * An event is uploadable with a click id, a hashed email, or both — Meta
- * matches on either. Requiring fbclid, as this provider used to, discarded
- * every conversion whose click id had not survived to the moment of
- * conversion, which is most of a sales-led funnel.
- */
-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);
-  }
-
-  protected override getProviderSkipReason(
-    conversion: MarketingConversion,
-  ): ConversionSkip | null {
-    if (
-      !this.getClickId(conversion, "fbclid") &&
-      !this.getHashedEmail(conversion)
-    ) {
-      return {
-        reason: "No Meta click id (fbclid) and no email to match on",
-        isPermanent: true,
-      };
-    }
-
-    if (!this.getEventName(conversion)) {
-      return {
-        reason: "No Meta event name mapped for this conversion type",
-        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;
-  }
-
-  /*
-   * Standard Meta event names. `Schedule` is Meta's own name for a booked
-   * meeting, and it carries no revenue — which is what keeps a demo out of the
-   * Purchase optimisation pool.
-   */
-  private getEventName(conversion: MarketingConversion): string | undefined {
-    const mapping: ConversionTypeMapping<string> = {
-      [MarketingConversionType.SignUp]: "CompleteRegistration",
-      [MarketingConversionType.MeetingBooked]: "Schedule",
-      [MarketingConversionType.PaidSubscription]: "Purchase",
-    };
-
-    return this.resolveByConversionType(conversion, mapping);
-  }
-
-  /*
-   * 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 | undefined = this.getClickId(
-          conversion,
-          "fbclid",
-        );
-
-        const userData: JSONObject = {};
-
-        // Only send fbc when there is a click id to build it from.
-        if (fbclid) {
-          userData["fbc"] = this.buildFbc(fbclid, eventAt);
-        }
-
-        const hashedEmail: string | undefined = this.getHashedEmail(conversion);
-
-        if (hashedEmail) {
-          userData["em"] = [hashedEmail];
-        }
-
-        const eventName: string = this.getEventName(conversion) || "Lead";
-
-        const payload: JSONObject = {
-          event_name: eventName,
-          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. Lead-shaped events
-         * (Schedule, Lead) never carry a value: getValueInUSD returns
-         * undefined for them, so no custom_data is attached at all.
-         */
-        if (eventName === "Purchase" || 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>() };
-  }
-}

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

@@ -1,223 +0,0 @@
-import axios, { AxiosResponse } from "axios";
-import {
-  MicrosoftAdsAccountId,
-  MicrosoftAdsCustomerId,
-  MicrosoftAdsDeveloperToken,
-  MicrosoftAdsMeetingBookedConversionName,
-  MicrosoftAdsOAuthClientId,
-  MicrosoftAdsOAuthClientSecret,
-  MicrosoftAdsOAuthRefreshToken,
-  MicrosoftAdsPaidSubscriptionConversionName,
-  MicrosoftAdsSignUpConversionName,
-} from "../../../EnvironmentConfig";
-import ConversionUploadProvider, {
-  ConversionSkip,
-  ConversionTypeMapping,
-  ConversionUploadBatchResult,
-} from "../ConversionUploadProvider";
-import { JSONObject } from "../../../../Types/JSON";
-import { MarketingConversionType } from "../../../../Types/Marketing/MarketingConversion";
-import MarketingConversion from "../../../../Models/DatabaseModels/MarketingConversion";
-
-const REQUEST_TIMEOUT_MS: number = 30000;
-
-// Microsoft accepts offline conversions up to 90 days after the click.
-const MICROSOFT_MAX_CONVERSION_AGE_IN_DAYS: number = 90;
-
-/*
- * Microsoft Advertising (Bing Ads) offline conversions via the Campaign
- * Management v13 REST surface (OfflineConversions/Apply), matching on msclkid
- * or on a SHA-256 email (Microsoft's enhanced conversions). Offline conversion
- * goals are matched by conversion NAME configured in the Microsoft Advertising
- * UI. OAuth2 refresh-token flow against Microsoft identity platform with the
- * msads.manage scope.
- */
-export default class MicrosoftAdsProvider extends ConversionUploadProvider {
-  public override readonly key: string = "microsoft";
-  public override readonly displayName: string = "Microsoft Advertising";
-
-  private cachedAccessToken: string | null = null;
-  private cachedAccessTokenExpiresAt: number = 0;
-
-  public override isConfigured(): boolean {
-    return Boolean(
-      MicrosoftAdsDeveloperToken &&
-        MicrosoftAdsOAuthClientId &&
-        MicrosoftAdsOAuthRefreshToken &&
-        MicrosoftAdsCustomerId &&
-        MicrosoftAdsAccountId,
-    );
-  }
-
-  protected override getProviderSkipReason(
-    conversion: MarketingConversion,
-  ): ConversionSkip | null {
-    if (
-      !this.getClickId(conversion, "msclkid") &&
-      !this.getHashedEmail(conversion)
-    ) {
-      return {
-        reason: "No Microsoft click id (msclkid) and no email to match on",
-        isPermanent: true,
-      };
-    }
-
-    if (!this.getConversionName(conversion)) {
-      // Config gap — leave pending so it uploads once the name is configured.
-      return {
-        reason:
-          "No Microsoft Advertising conversion name configured for this conversion type",
-        isPermanent: false,
-      };
-    }
-
-    if (
-      this.isOlderThanDays(conversion, MICROSOFT_MAX_CONVERSION_AGE_IN_DAYS)
-    ) {
-      return {
-        reason: "Conversion older than Microsoft's 90-day click window",
-        isPermanent: true,
-      };
-    }
-
-    return null;
-  }
-
-  private getConversionName(conversion: MarketingConversion): string {
-    const mapping: ConversionTypeMapping<string> = {
-      [MarketingConversionType.SignUp]: MicrosoftAdsSignUpConversionName,
-      [MarketingConversionType.MeetingBooked]:
-        MicrosoftAdsMeetingBookedConversionName,
-      [MarketingConversionType.PaidSubscription]:
-        MicrosoftAdsPaidSubscriptionConversionName,
-    };
-
-    return this.resolveByConversionType(conversion, mapping) || "";
-  }
-
-  private async getAccessToken(): Promise<string> {
-    if (
-      this.cachedAccessToken &&
-      Date.now() < this.cachedAccessTokenExpiresAt
-    ) {
-      return this.cachedAccessToken;
-    }
-
-    const params: URLSearchParams = new URLSearchParams();
-    params.append("client_id", MicrosoftAdsOAuthClientId);
-    if (MicrosoftAdsOAuthClientSecret) {
-      params.append("client_secret", MicrosoftAdsOAuthClientSecret);
-    }
-    params.append("refresh_token", MicrosoftAdsOAuthRefreshToken);
-    params.append("grant_type", "refresh_token");
-    params.append(
-      "scope",
-      "https://ads.microsoft.com/msads.manage offline_access",
-    );
-
-    const response: AxiosResponse<{
-      access_token?: string;
-      expires_in?: number;
-    }> = await axios.post(
-      "https://login.microsoftonline.com/common/oauth2/v2.0/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("Microsoft OAuth token response had no access_token");
-    }
-
-    this.cachedAccessToken = accessToken;
-    this.cachedAccessTokenExpiresAt =
-      Date.now() + ((response.data?.expires_in || 3600) - 60) * 1000;
-
-    return accessToken;
-  }
-
-  public override async upload(
-    conversions: Array<MarketingConversion>,
-  ): Promise<ConversionUploadBatchResult> {
-    const accessToken: string = await this.getAccessToken();
-
-    const body: JSONObject = {
-      OfflineConversions: conversions.map((conversion: MarketingConversion) => {
-        const payload: JSONObject = {
-          ConversionName: this.getConversionName(conversion),
-          // ISO 8601 UTC, e.g. 2026-07-18T12:34:56Z.
-          ConversionTime: (conversion.conversionAt || new Date())
-            .toISOString()
-            .replace(/\.\d{3}Z$/, "Z"),
-        };
-
-        const clickId: string | undefined = this.getClickId(
-          conversion,
-          "msclkid",
-        );
-
-        if (clickId) {
-          payload["MicrosoftClickId"] = clickId;
-        }
-
-        const hashedEmail: string | undefined = this.getHashedEmail(conversion);
-
-        if (hashedEmail) {
-          payload["HashedEmailAddress"] = hashedEmail;
-        }
-
-        const valueInUSD: number | undefined = this.getValueInUSD(conversion);
-
-        if (valueInUSD !== undefined) {
-          payload["ConversionValue"] = valueInUSD;
-          payload["ConversionCurrencyCode"] = "USD";
-        }
-
-        return payload;
-      }),
-    };
-
-    const response: AxiosResponse<JSONObject> = await axios.post(
-      "https://campaign.api.bingads.microsoft.com/CampaignManagement/v13/OfflineConversions/Apply",
-      body,
-      {
-        headers: {
-          Authorization: `Bearer ${accessToken}`,
-          DeveloperToken: MicrosoftAdsDeveloperToken,
-          CustomerId: MicrosoftAdsCustomerId,
-          CustomerAccountId: MicrosoftAdsAccountId,
-          "Content-Type": "application/json",
-        },
-        timeout: REQUEST_TIMEOUT_MS,
-      },
-    );
-
-    /*
-     * The Apply response reports per-item failures in PartialErrors, each
-     * carrying the Index of the failing item in the submitted array.
-     */
-    const permanentFailures: Map<number, string> = new Map<number, string>();
-
-    const partialErrors: Array<JSONObject> =
-      (response.data?.["PartialErrors"] as Array<JSONObject>) || [];
-
-    for (const partialError of partialErrors) {
-      if (typeof partialError?.["Index"] === "number") {
-        permanentFailures.set(
-          partialError["Index"] as number,
-          `${partialError["ErrorCode"] || ""} ${
-            partialError["Message"] || "Unknown Microsoft Advertising error"
-          }`.trim(),
-        );
-      }
-    }
-
-    return { permanentFailures };
-  }
-}