@oneuptime/common 11.5.9 → 11.5.10

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

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

@@ -0,0 +1,196 @@
+import axios, { AxiosResponse } from "axios";
+import {
+  MicrosoftAdsAccountId,
+  MicrosoftAdsCustomerId,
+  MicrosoftAdsDeveloperToken,
+  MicrosoftAdsOAuthClientId,
+  MicrosoftAdsOAuthClientSecret,
+  MicrosoftAdsOAuthRefreshToken,
+  MicrosoftAdsPaidSubscriptionConversionName,
+  MicrosoftAdsSignUpConversionName,
+} 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;
+
+// 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) using msclkid.
+ * 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,
+    );
+  }
+
+  public override getSkipReason(
+    conversion: MarketingConversion,
+  ): ConversionSkip | null {
+    if (!this.getClickId(conversion, "msclkid")) {
+      return {
+        reason: "No Microsoft click id (msclkid)",
+        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 {
+    return this.isSignUp(conversion)
+      ? MicrosoftAdsSignUpConversionName
+      : MicrosoftAdsPaidSubscriptionConversionName;
+  }
+
+  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 = {
+          MicrosoftClickId: this.getClickId(conversion, "msclkid") || "",
+          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 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 };
+  }
+}

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

@@ -0,0 +1,178 @@
+import axios, { AxiosResponse } from "axios";
+import crypto from "crypto";
+import {
+  RedditAdsAccountId,
+  RedditAdsOAuthClientId,
+  RedditAdsOAuthClientSecret,
+  RedditAdsOAuthRefreshToken,
+} 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;
+
+// Reddit accepts conversion events up to 7 days old.
+const REDDIT_MAX_EVENT_AGE_IN_DAYS: number = 7;
+
+/*
+ * Reddit Conversions API
+ * (ads-api.reddit.com/api/v2.0/conversions/events/{accountId}) using the
+ * rdt_cid click id. conversion_id (the conversion row id) makes retried
+ * uploads idempotent on Reddit's side. OAuth2 refresh-token flow with HTTP
+ * basic auth against reddit.com.
+ */
+export default class RedditProvider extends ConversionUploadProvider {
+  public override readonly key: string = "reddit";
+  public override readonly displayName: string = "Reddit";
+
+  private cachedAccessToken: string | null = null;
+  private cachedAccessTokenExpiresAt: number = 0;
+
+  public override isConfigured(): boolean {
+    return Boolean(
+      RedditAdsOAuthClientId &&
+        RedditAdsOAuthClientSecret &&
+        RedditAdsOAuthRefreshToken &&
+        RedditAdsAccountId,
+    );
+  }
+
+  public override getSkipReason(
+    conversion: MarketingConversion,
+  ): ConversionSkip | null {
+    if (!this.getClickId(conversion, "rdt_cid")) {
+      return {
+        reason: "No Reddit click id (rdt_cid)",
+        isPermanent: true,
+      };
+    }
+
+    if (this.isOlderThanDays(conversion, REDDIT_MAX_EVENT_AGE_IN_DAYS)) {
+      return {
+        reason: "Conversion older than Reddit's 7-day upload window",
+        isPermanent: true,
+      };
+    }
+
+    return null;
+  }
+
+  private hashEmail(email: string): string {
+    return crypto
+      .createHash("sha256")
+      .update(email.trim().toLowerCase())
+      .digest("hex");
+  }
+
+  private async getAccessToken(): Promise<string> {
+    if (
+      this.cachedAccessToken &&
+      Date.now() < this.cachedAccessTokenExpiresAt
+    ) {
+      return this.cachedAccessToken;
+    }
+
+    const params: URLSearchParams = new URLSearchParams();
+    params.append("grant_type", "refresh_token");
+    params.append("refresh_token", RedditAdsOAuthRefreshToken);
+
+    const response: AxiosResponse<{
+      access_token?: string;
+      expires_in?: number;
+    }> = await axios.post(
+      "https://www.reddit.com/api/v1/access_token",
+      params.toString(),
+      {
+        auth: {
+          username: RedditAdsOAuthClientId,
+          password: RedditAdsOAuthClientSecret,
+        },
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          // Reddit throttles/blocks requests without a descriptive User-Agent.
+          "User-Agent": "OneUptime-ConversionsUpload/1.0",
+        },
+        timeout: REQUEST_TIMEOUT_MS,
+      },
+    );
+
+    const accessToken: string | undefined = response.data?.access_token;
+
+    if (!accessToken) {
+      throw new Error("Reddit 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 events: Array<JSONObject> = conversions.map(
+      (conversion: MarketingConversion) => {
+        const eventAt: Date = conversion.conversionAt || new Date();
+
+        const eventMetadata: JSONObject = {
+          // Dedup key: retried uploads are idempotent on Reddit's side.
+          conversion_id: conversion.id!.toString(),
+        };
+
+        const valueInUSD: number | undefined = this.getValueInUSD(conversion);
+
+        if (valueInUSD !== undefined) {
+          eventMetadata["value_decimal"] = valueInUSD;
+          eventMetadata["currency"] = "USD";
+        }
+
+        const payload: JSONObject = {
+          event_at: eventAt.toISOString(),
+          click_id: this.getClickId(conversion, "rdt_cid") || "",
+          event_type: {
+            tracking_type: this.isSignUp(conversion) ? "SignUp" : "Purchase",
+          },
+          event_metadata: eventMetadata,
+        };
+
+        if (conversion.email) {
+          payload["user"] = {
+            email: this.hashEmail(conversion.email),
+          };
+        }
+
+        return payload;
+      },
+    );
+
+    await axios.post(
+      `https://ads-api.reddit.com/api/v2.0/conversions/events/${RedditAdsAccountId}`,
+      {
+        test_mode: false,
+        events: events,
+      },
+      {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+        },
+        timeout: REQUEST_TIMEOUT_MS,
+      },
+    );
+
+    /*
+     * Reddit accepts or rejects the request as a whole; request-level
+     * failures throw and the batch is retried (idempotent via
+     * conversion_id).
+     */
+    return { permanentFailures: new Map<number, string>() };
+  }
+}

package/Server/Utils/Monitor/MonitorAlert.ts

@@ -24,6 +24,9 @@ import AlertService from "../../Services/AlertService";
 import AlertSeverityService from "../../Services/AlertSeverityService";
 import AlertStateTimelineService from "../../Services/AlertStateTimelineService";
 import HostService from "../../Services/HostService";
+import NetworkDeviceOwnerUserService, {
+  NetworkDeviceOwners,
+} from "../../Services/NetworkDeviceOwnerUserService";
 import ServiceService from "../../Services/ServiceService";
 import logger, { LogAttributes } from "../Logger";
 import CaptureSpan from "../Telemetry/CaptureSpan";
@@ -300,6 +303,15 @@ export default class MonitorAlert {
         ? input.matchesPerSeries
         : [undefined];
 
+    /*
+     * Owners of the network device this monitor watches (if any), resolved
+     * lazily on first alert creation and reused for the rest of the
+     * evaluation — the device is configured per monitor step, so it is
+     * constant across the criteria/series loops below. Merged into every
+     * created alert's owners alongside the criteria-configured ones.
+     */
+    let networkDeviceOwners: NetworkDeviceOwners | null = null;
+
     for (const criteriaAlert of input.criteriaInstance.data?.alerts || []) {
       for (const seriesMatch of seriesToProcess) {
         const seriesFingerprint: string | undefined = seriesMatch?.fingerprint;
@@ -627,16 +639,38 @@ export default class MonitorAlert {
           },
         });
 
-        // Add owner teams and users after alert creation
-        if (
-          criteriaAlert.ownerTeamIds?.length ||
-          criteriaAlert.ownerUserIds?.length
-        ) {
+        /*
+         * Add owner teams and users after alert creation. Owners configured
+         * on the criteria template are merged (deduped) with the owners of
+         * the network device this monitor watches, so device ownership flows
+         * into the alerts its monitor raises.
+         */
+        if (networkDeviceOwners === null) {
+          networkDeviceOwners =
+            await NetworkDeviceOwnerUserService.getDeviceOwnersForMonitor({
+              monitor: input.monitor,
+              monitorStepId: (
+                input.dataToProcess as ProbeMonitorResponse
+              ).monitorStepId?.toString(),
+            });
+        }
+
+        const ownerUserIds: Array<ObjectID> = this.mergeOwnerIds(
+          criteriaAlert.ownerUserIds || [],
+          networkDeviceOwners.ownerUserIds,
+        );
+
+        const ownerTeamIds: Array<ObjectID> = this.mergeOwnerIds(
+          criteriaAlert.ownerTeamIds || [],
+          networkDeviceOwners.ownerTeamIds,
+        );
+
+        if (ownerTeamIds.length || ownerUserIds.length) {
           await AlertService.addOwners(
             input.monitor.projectId!,
             createdAlert.id!,
-            criteriaAlert.ownerUserIds || [],
-            criteriaAlert.ownerTeamIds || [],
+            ownerUserIds,
+            ownerTeamIds,
             true, // notify owners
             {
               isRoot: true,
@@ -658,6 +692,36 @@ export default class MonitorAlert {
     }
   }
 
+  /*
+   * Merges two owner id lists, deduping by string value. Criteria-authored
+   * ids can arrive as plain strings from stored JSON, so normalise through
+   * toString() for both the comparison and the returned ObjectIDs.
+   */
+  private static mergeOwnerIds(
+    primary: Array<ObjectID>,
+    additional: Array<ObjectID>,
+  ): Array<ObjectID> {
+    const seenIds: Set<string> = new Set<string>();
+    const mergedIds: Array<ObjectID> = [];
+
+    for (const ownerId of [...primary, ...additional]) {
+      if (!ownerId) {
+        continue;
+      }
+
+      const ownerIdAsString: string = ownerId.toString();
+
+      if (!ownerIdAsString || seenIds.has(ownerIdAsString)) {
+        continue;
+      }
+
+      seenIds.add(ownerIdAsString);
+      mergedIds.push(new ObjectID(ownerIdAsString));
+    }
+
+    return mergedIds;
+  }
+
   private static async resolveOpenAlert(input: {
     openAlert: Alert;
     rootCause: string;