@oneuptime/common 12.0.14 → 12.0.16

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

@@ -1,5 +1,4 @@
 import axios, { AxiosResponse } from "axios";
-import crypto from "crypto";
 import {
   MetaConversionsAccessToken,
   MetaConversionsPixelId,
@@ -7,9 +6,11 @@ import {
 } 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;
@@ -23,6 +24,11 @@ const META_MAX_EVENT_AGE_IN_DAYS: number = 7;
  * 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";
@@ -32,12 +38,22 @@ export default class MetaProvider extends ConversionUploadProvider {
     return Boolean(MetaConversionsPixelId && MetaConversionsAccessToken);
   }
 
-  public override getSkipReason(
+  protected override getProviderSkipReason(
     conversion: MarketingConversion,
   ): ConversionSkip | null {
-    if (!this.getClickId(conversion, "fbclid")) {
+    if (
+      !this.getClickId(conversion, "fbclid") &&
+      !this.getHashedEmail(conversion)
+    ) {
       return {
-        reason: "No Meta click id (fbclid)",
+        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,
       };
     }
@@ -52,11 +68,19 @@ export default class MetaProvider extends ConversionUploadProvider {
     return null;
   }
 
-  private hashEmail(email: string): string {
-    return crypto
-      .createHash("sha256")
-      .update(email.trim().toLowerCase())
-      .digest("hex");
+  /*
+   * 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);
   }
 
   /*
@@ -74,20 +98,28 @@ export default class MetaProvider extends ConversionUploadProvider {
     const data: Array<JSONObject> = conversions.map(
       (conversion: MarketingConversion) => {
         const eventAt: Date = conversion.conversionAt || new Date();
-        const fbclid: string = this.getClickId(conversion, "fbclid") || "";
+        const fbclid: string | undefined = this.getClickId(
+          conversion,
+          "fbclid",
+        );
 
-        const userData: JSONObject = {
-          fbc: this.buildFbc(fbclid, eventAt),
-        };
+        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 (conversion.email) {
-          userData["em"] = [this.hashEmail(conversion.email)];
+        if (hashedEmail) {
+          userData["em"] = [hashedEmail];
         }
 
-        const isSignUp: boolean = this.isSignUp(conversion);
+        const eventName: string = this.getEventName(conversion) || "Lead";
 
         const payload: JSONObject = {
-          event_name: isSignUp ? "CompleteRegistration" : "Purchase",
+          event_name: eventName,
           event_time: Math.floor(eventAt.getTime() / 1000),
           event_id: conversion.id!.toString(),
           /*
@@ -104,9 +136,11 @@ export default class MetaProvider extends ConversionUploadProvider {
         /*
          * 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.
+         * 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 (!isSignUp || valueInUSD !== undefined) {
+        if (eventName === "Purchase" || valueInUSD !== undefined) {
           payload["custom_data"] = {
             value: valueInUSD ?? 0,
             currency: "USD",

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

@@ -3,6 +3,7 @@ import {
   MicrosoftAdsAccountId,
   MicrosoftAdsCustomerId,
   MicrosoftAdsDeveloperToken,
+  MicrosoftAdsMeetingBookedConversionName,
   MicrosoftAdsOAuthClientId,
   MicrosoftAdsOAuthClientSecret,
   MicrosoftAdsOAuthRefreshToken,
@@ -11,9 +12,11 @@ import {
 } 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;
@@ -23,10 +26,11 @@ 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.
+ * 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";
@@ -45,12 +49,15 @@ export default class MicrosoftAdsProvider extends ConversionUploadProvider {
     );
   }
 
-  public override getSkipReason(
+  protected override getProviderSkipReason(
     conversion: MarketingConversion,
   ): ConversionSkip | null {
-    if (!this.getClickId(conversion, "msclkid")) {
+    if (
+      !this.getClickId(conversion, "msclkid") &&
+      !this.getHashedEmail(conversion)
+    ) {
       return {
-        reason: "No Microsoft click id (msclkid)",
+        reason: "No Microsoft click id (msclkid) and no email to match on",
         isPermanent: true,
       };
     }
@@ -77,9 +84,15 @@ export default class MicrosoftAdsProvider extends ConversionUploadProvider {
   }
 
   private getConversionName(conversion: MarketingConversion): string {
-    return this.isSignUp(conversion)
-      ? MicrosoftAdsSignUpConversionName
-      : MicrosoftAdsPaidSubscriptionConversionName;
+    const mapping: ConversionTypeMapping<string> = {
+      [MarketingConversionType.SignUp]: MicrosoftAdsSignUpConversionName,
+      [MarketingConversionType.MeetingBooked]:
+        MicrosoftAdsMeetingBookedConversionName,
+      [MarketingConversionType.PaidSubscription]:
+        MicrosoftAdsPaidSubscriptionConversionName,
+    };
+
+    return this.resolveByConversionType(conversion, mapping) || "";
   }
 
   private async getAccessToken(): Promise<string> {
@@ -137,7 +150,6 @@ export default class MicrosoftAdsProvider extends ConversionUploadProvider {
     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())
@@ -145,6 +157,21 @@ export default class MicrosoftAdsProvider extends ConversionUploadProvider {
             .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) {

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

@@ -1,5 +1,4 @@
 import axios, { AxiosResponse } from "axios";
-import crypto from "crypto";
 import {
   RedditAdsAccountId,
   RedditAdsOAuthClientId,
@@ -8,9 +7,11 @@ import {
 } 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;
@@ -21,9 +22,10 @@ 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.
+ * rdt_cid click id or a SHA-256 email, whichever the conversion carries.
+ * 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";
@@ -41,12 +43,22 @@ export default class RedditProvider extends ConversionUploadProvider {
     );
   }
 
-  public override getSkipReason(
+  protected override getProviderSkipReason(
     conversion: MarketingConversion,
   ): ConversionSkip | null {
-    if (!this.getClickId(conversion, "rdt_cid")) {
+    if (
+      !this.getClickId(conversion, "rdt_cid") &&
+      !this.getHashedEmail(conversion)
+    ) {
       return {
-        reason: "No Reddit click id (rdt_cid)",
+        reason: "No Reddit click id (rdt_cid) and no email to match on",
+        isPermanent: true,
+      };
+    }
+
+    if (!this.getTrackingType(conversion)) {
+      return {
+        reason: "No Reddit tracking type mapped for this conversion type",
         isPermanent: true,
       };
     }
@@ -61,11 +73,19 @@ export default class RedditProvider extends ConversionUploadProvider {
     return null;
   }
 
-  private hashEmail(email: string): string {
-    return crypto
-      .createHash("sha256")
-      .update(email.trim().toLowerCase())
-      .digest("hex");
+  /*
+   * Reddit standard tracking types. A booked meeting is `Lead`: Reddit has no
+   * distinct "meeting booked" type, and reporting it as Purchase would put a
+   * demo into the same optimisation pool as revenue.
+   */
+  private getTrackingType(conversion: MarketingConversion): string | undefined {
+    const mapping: ConversionTypeMapping<string> = {
+      [MarketingConversionType.SignUp]: "SignUp",
+      [MarketingConversionType.MeetingBooked]: "Lead",
+      [MarketingConversionType.PaidSubscription]: "Purchase",
+    };
+
+    return this.resolveByConversionType(conversion, mapping);
   }
 
   private async getAccessToken(): Promise<string> {
@@ -136,16 +156,26 @@ export default class RedditProvider extends ConversionUploadProvider {
 
         const payload: JSONObject = {
           event_at: eventAt.toISOString(),
-          click_id: this.getClickId(conversion, "rdt_cid") || "",
           event_type: {
-            tracking_type: this.isSignUp(conversion) ? "SignUp" : "Purchase",
+            tracking_type: this.getTrackingType(conversion) || "Lead",
           },
           event_metadata: eventMetadata,
         };
 
-        if (conversion.email) {
+        const clickId: string | undefined = this.getClickId(
+          conversion,
+          "rdt_cid",
+        );
+
+        if (clickId) {
+          payload["click_id"] = clickId;
+        }
+
+        const hashedEmail: string | undefined = this.getHashedEmail(conversion);
+
+        if (hashedEmail) {
           payload["user"] = {
-            email: this.hashEmail(conversion.email),
+            email: hashedEmail,
           };
         }
 

package/Server/Utils/Measurement/MeasurementDefinitionValidator.ts

@@ -0,0 +1,209 @@
+import BadDataException from "../../../Types/Exception/BadDataException";
+import MeasurementOccurrence from "../../../Types/Measurement/MeasurementOccurrence";
+
+/*
+ * Validation shared by the incident, alert and scheduled maintenance
+ * measurement services.
+ *
+ * Every rule here exists to stop a definition that would silently produce a
+ * confidently wrong number -- a constant zero, or a duration that can never
+ * complete with nothing anywhere saying so.
+ */
+export default class MeasurementDefinitionValidator {
+  /*
+   * The key becomes part of the metric name, which lands in ClickHouse, in
+   * the dashboard chart picker and in the API. It is immutable after
+   * creation, so it is worth rejecting a bad one loudly at the only moment
+   * it can still be changed.
+   */
+  public static readonly KEY_PATTERN: RegExp = /^[a-z0-9][a-z0-9-]{0,49}$/;
+
+  public static validateKey(key: string | undefined): void {
+    if (!key) {
+      throw new BadDataException(
+        "A measurement needs a key. Use lowercase letters, numbers and hyphens, for example: time-to-detect",
+      );
+    }
+
+    if (!MeasurementDefinitionValidator.KEY_PATTERN.test(key)) {
+      throw new BadDataException(
+        `"${key}" is not a valid measurement key. Keys start with a lowercase letter or number, contain only lowercase letters, numbers and hyphens, and are at most 50 characters. For example: time-to-detect`,
+      );
+    }
+  }
+
+  public static validateAnchorPair(data: {
+    startAnchorType?: string | undefined;
+    endAnchorType?: string | undefined;
+    stateEnteredAnchor: string;
+    stateRoleEnteredAnchor: string;
+    /*
+     * Maps each timestamp anchor type onto the column it actually reads.
+     * Several anchors are aliases -- an alert's "Timeline Start" and
+     * "Created At" are both createdAt -- so comparing the enum values alone
+     * would wave through a definition that is a constant zero by
+     * construction.
+     */
+    timestampAnchorSources?: Record<string, string> | undefined;
+    startStateId?: string | undefined;
+    endStateId?: string | undefined;
+    startStateRole?: string | undefined;
+    endStateRole?: string | undefined;
+    startOccurrence?: string | undefined;
+    endOccurrence?: string | undefined;
+  }): void {
+    if (!data.startAnchorType) {
+      throw new BadDataException("A measurement needs a starting point.");
+    }
+
+    if (!data.endAnchorType) {
+      throw new BadDataException("A measurement needs an ending point.");
+    }
+
+    if (
+      data.startAnchorType === data.stateEnteredAnchor &&
+      !data.startStateId
+    ) {
+      throw new BadDataException(
+        "Pick the state this measurement starts from.",
+      );
+    }
+
+    if (data.endAnchorType === data.stateEnteredAnchor && !data.endStateId) {
+      throw new BadDataException("Pick the state this measurement ends at.");
+    }
+
+    if (
+      data.startAnchorType === data.stateRoleEnteredAnchor &&
+      !data.startStateRole
+    ) {
+      throw new BadDataException(
+        "Pick the kind of state this measurement starts from.",
+      );
+    }
+
+    if (
+      data.endAnchorType === data.stateRoleEnteredAnchor &&
+      !data.endStateRole
+    ) {
+      throw new BadDataException(
+        "Pick the kind of state this measurement ends at.",
+      );
+    }
+
+    MeasurementDefinitionValidator.rejectIdenticalAnchors(data);
+  }
+
+  /*
+   * Two identical endpoints always measure zero. Shipping that produces a
+   * chart that reads "we do this instantly" on every incident -- which is
+   * strictly worse than having no chart, because it looks like an answer.
+   */
+  private static rejectIdenticalAnchors(data: {
+    startAnchorType?: string | undefined;
+    endAnchorType?: string | undefined;
+    stateEnteredAnchor: string;
+    stateRoleEnteredAnchor: string;
+    timestampAnchorSources?: Record<string, string> | undefined;
+    startStateId?: string | undefined;
+    endStateId?: string | undefined;
+    startStateRole?: string | undefined;
+    endStateRole?: string | undefined;
+    startOccurrence?: string | undefined;
+    endOccurrence?: string | undefined;
+  }): void {
+    const startSource: string =
+      MeasurementDefinitionValidator.resolveAnchorSource(
+        data.startAnchorType,
+        data.timestampAnchorSources,
+      );
+    const endSource: string =
+      MeasurementDefinitionValidator.resolveAnchorSource(
+        data.endAnchorType,
+        data.timestampAnchorSources,
+      );
+
+    if (startSource !== endSource) {
+      return;
+    }
+
+    const startOccurrence: string =
+      data.startOccurrence || MeasurementOccurrence.First;
+    const endOccurrence: string =
+      data.endOccurrence || MeasurementOccurrence.First;
+
+    if (data.startAnchorType === data.stateEnteredAnchor) {
+      if (
+        data.startStateId === data.endStateId &&
+        startOccurrence === endOccurrence
+      ) {
+        throw new BadDataException(
+          "This measurement starts and ends at the same point, so it would always be zero. Pick two different points.",
+        );
+      }
+
+      return;
+    }
+
+    if (data.startAnchorType === data.stateRoleEnteredAnchor) {
+      if (
+        data.startStateRole === data.endStateRole &&
+        startOccurrence === endOccurrence
+      ) {
+        throw new BadDataException(
+          "This measurement starts and ends at the same point, so it would always be zero. Pick two different points.",
+        );
+      }
+
+      return;
+    }
+
+    // Two identical timestamp anchors. Always zero, no exceptions.
+    throw new BadDataException(
+      "This measurement starts and ends at the same point, so it would always be zero. Pick two different points.",
+    );
+  }
+
+  /*
+   * The column an anchor reads, so two differently-named anchors that read
+   * the same column are recognised as the same point in time.
+   */
+  private static resolveAnchorSource(
+    anchorType: string | undefined,
+    sources: Record<string, string> | undefined,
+  ): string {
+    if (!anchorType) {
+      return "";
+    }
+
+    return sources?.[anchorType] || anchorType;
+  }
+
+  /*
+   * States are entered in strictly increasing order, so an end state ordered
+   * at or before the start state describes a duration that can never
+   * complete. Without this the definition looks fine and every incident
+   * reports "not applicable" forever.
+   */
+  public static validateStateOrder(data: {
+    startStateName?: string | undefined;
+    startStateOrder?: number | undefined;
+    endStateName?: string | undefined;
+    endStateOrder?: number | undefined;
+  }): void {
+    if (
+      data.startStateOrder === undefined ||
+      data.endStateOrder === undefined
+    ) {
+      return;
+    }
+
+    if (data.endStateOrder > data.startStateOrder) {
+      return;
+    }
+
+    throw new BadDataException(
+      `"${data.endStateName}" comes before "${data.startStateName}" in this project's state order, so this measurement could never complete. Swap the two, or pick a later ending state.`,
+    );
+  }
+}