@oneuptime/common 12.0.18 → 12.0.20

package/Server/Utils/Marketing/ConversionUploadProvider.ts

@@ -1,215 +0,0 @@
-import { AxiosError } from "axios";
-import Attribution from "../Attribution";
-import { JSONObject } from "../../../Types/JSON";
-import {
-  AdUploadableMarketingConversionTypes,
-  LeadMarketingConversionTypes,
-  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 (conversion type with no ad-platform
- *   mapping, no identifier this platform can match on, outside the platform's
- *   upload window, provider not configured for this conversion type). Null
- *   means uploadable. It is implemented here and must not be overridden —
- *   providers implement getProviderSkipReason instead, which only runs for
- *   conversion types that are ad-uploadable at all.
- * - 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.
- *
- * IDENTIFIERS
- *
- * A conversion can be matched to an ad click two ways, and most platforms
- * accept either:
- *
- *   - the click id the visitor carried (gclid, fbclid, msclkid, ...), which is
- *     exact but only survives as far as the browser storage that held it; and
- *   - the SHA-256 of the person's email, which every platform calls "enhanced
- *     conversions"/"enhanced matching" and which survives a change of device,
- *     a cleared browser, and the weeks between a demo and the deal it led to.
- *
- * Providers must consider a conversion uploadable when EITHER is present.
- * Requiring the click id — which is what every provider here used to do — threw
- * away exactly the sales-led conversions the enhanced-matching mechanism was
- * designed for.
- */
-
-export interface ConversionUploadBatchResult {
-  // Index into the submitted batch -> permanent failure message.
-  permanentFailures: Map<number, string>;
-}
-
-export interface ConversionSkip {
-  reason: string;
-  /*
-   * Permanent skips (no usable identifier, 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;
-}
-
-/*
- * A per-conversion-type mapping. Written as a Record over the enum rather than
- * a switch or a two-way branch on purpose: the compiler refuses a Record that
- * omits a member, so adding a MarketingConversionType is a build error in every
- * provider until that provider states what the new type means on its platform.
- *
- * That is the guarantee Docs/analytics/enterprise-conversion-tracking.md asks
- * for. Before it existed, providers chose their conversion action with
- * `isSignUp(conversion) ? signUp : paidSubscription`, so a booked meeting added
- * to the uploadable list would have been reported to every ad platform as a
- * purchase.
- */
-export type ConversionTypeMapping<T> = Record<MarketingConversionType, T>;
-
-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;
-
-  /*
-   * Screens conversion types the ledger records but no ad platform has a
-   * mapping for, before any provider sees them.
-   */
-  public getSkipReason(conversion: MarketingConversion): ConversionSkip | null {
-    if (
-      !AdUploadableMarketingConversionTypes.includes(
-        conversion.conversionType as MarketingConversionType,
-      )
-    ) {
-      return {
-        reason: `Conversion type ${
-          conversion.conversionType || "unknown"
-        } has no ad platform conversion mapping`,
-        isPermanent: true,
-      };
-    }
-
-    return this.getProviderSkipReason(conversion);
-  }
-
-  protected abstract getProviderSkipReason(
-    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;
-  }
-
-  /*
-   * The hashed email this conversion can be matched on, or undefined.
-   *
-   * Prefers the stored emailHash and falls back to hashing the email column,
-   * so rows written before emailHash existed still match. Both paths go
-   * through Attribution so the digest is identical whichever one produced it.
-   */
-  protected getHashedEmail(
-    conversion: MarketingConversion,
-  ): string | undefined {
-    if (conversion.emailHash) {
-      return conversion.emailHash;
-    }
-
-    return Attribution.hashEmail(conversion.email) || undefined;
-  }
-
-  /*
-   * Resolve a per-type value, or undefined when the column holds a string that
-   * is not a known conversion type. The column is a plain varchar, so this
-   * cannot be assumed away even though the mapping itself is exhaustive.
-   */
-  protected resolveByConversionType<T>(
-    conversion: MarketingConversion,
-    mapping: ConversionTypeMapping<T>,
-  ): T | undefined {
-    const conversionType: MarketingConversionType =
-      conversion.conversionType as MarketingConversionType;
-
-    if (!Object.values(MarketingConversionType).includes(conversionType)) {
-      return undefined;
-    }
-
-    return mapping[conversionType];
-  }
-
-  /*
-   * A sales-led lead (booked meeting, enterprise licence request) rather than
-   * a completed transaction.
-   */
-  protected isLead(conversion: MarketingConversion): boolean {
-    return LeadMarketingConversionTypes.includes(
-      conversion.conversionType as MarketingConversionType,
-    );
-  }
-
-  /*
-   * The revenue to report for this conversion, in USD.
-   *
-   * Leads return undefined regardless of what the row holds. A booked meeting
-   * is not money, and reporting one as revenue would let a bidding algorithm
-   * optimise towards booking meetings that never close.
-   */
-  protected getValueInUSD(conversion: MarketingConversion): number | undefined {
-    if (this.isLead(conversion)) {
-      return undefined;
-    }
-
-    if (
-      conversion.conversionValueInUSDCents === undefined ||
-      conversion.conversionValueInUSDCents === null ||
-      conversion.conversionValueInUSDCents <= 0
-    ) {
-      return undefined;
-    }
-    return conversion.conversionValueInUSDCents / 100;
-  }
-
-  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

@@ -1,22 +0,0 @@
-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

@@ -1,333 +0,0 @@
-import axios, { AxiosResponse } from "axios";
-import {
-  GoogleAdsApiVersion,
-  GoogleAdsCustomerId,
-  GoogleAdsDeveloperToken,
-  GoogleAdsEnhancedConversionsForLeadsEnabled,
-  GoogleAdsLoginCustomerId,
-  GoogleAdsMeetingBookedConversionActionId,
-  GoogleAdsOAuthClientId,
-  GoogleAdsOAuthClientSecret,
-  GoogleAdsOAuthRefreshToken,
-  GoogleAdsPaidSubscriptionConversionActionId,
-  GoogleAdsSignUpConversionActionId,
-} 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";
-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, plus enhanced conversions — a
- * SHA-256 email in userIdentifiers. Uses partialFailure so valid conversions
- * succeed even when others in the batch fail.
- *
- * A hashed email is attached to EVERY upload that has one, which only improves
- * matching. Uploading a conversion that has ONLY a hashed email — enhanced
- * conversions for leads, and the only way a sales-led deal months after the
- * click is ever attributed — additionally requires the account to be set up
- * for it, so it is gated on
- * GOOGLE_ADS_ENHANCED_CONVERSIONS_FOR_LEADS_ENABLED.
- */
-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,
-    );
-  }
-
-  protected override getProviderSkipReason(
-    conversion: MarketingConversion,
-  ): ConversionSkip | null {
-    if (
-      !this.getGoogleClickId(conversion) &&
-      !this.canUploadAsLead(conversion)
-    ) {
-      return {
-        reason: GoogleAdsEnhancedConversionsForLeadsEnabled
-          ? "No Google click id (gclid/wbraid/gbraid) and no email to match on"
-          : "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;
-  }
-
-  /*
-   * Enhanced conversions for leads: this conversion has no click id, but it
-   * has an email and the account is configured to match on one.
-   */
-  private canUploadAsLead(conversion: MarketingConversion): boolean {
-    return Boolean(
-      GoogleAdsEnhancedConversionsForLeadsEnabled &&
-        this.getHashedEmail(conversion),
-    );
-  }
-
-  /*
-   * userIdentifiers per the enhanced-conversions spec. FIRST_PARTY is the
-   * correct source: the address was given to OneUptime directly, not bought or
-   * inferred.
-   */
-  private getUserIdentifiers(
-    conversion: MarketingConversion,
-  ): Array<JSONObject> {
-    const hashedEmail: string | undefined = this.getHashedEmail(conversion);
-
-    if (!hashedEmail) {
-      return [];
-    }
-
-    return [
-      {
-        hashedEmail: hashedEmail,
-        userIdentifierSource: "FIRST_PARTY",
-      },
-    ];
-  }
-
-  private getConversionActionId(conversion: MarketingConversion): string {
-    const mapping: ConversionTypeMapping<string> = {
-      [MarketingConversionType.SignUp]: GoogleAdsSignUpConversionActionId,
-      [MarketingConversionType.MeetingBooked]:
-        GoogleAdsMeetingBookedConversionActionId,
-      [MarketingConversionType.PaidSubscription]:
-        GoogleAdsPaidSubscriptionConversionActionId,
-    };
-
-    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", 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 userIdentifiers: Array<JSONObject> =
-          this.getUserIdentifiers(conversion);
-
-        if (userIdentifiers.length > 0) {
-          payload["userIdentifiers"] = userIdentifiers;
-        }
-
-        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 };
-  }
-}