@oneuptime/common 12.0.15 → 12.0.17

package/Tests/Server/Utils/Marketing/Reddit.test.ts

@@ -0,0 +1,259 @@
+import Attribution from "../../../../Server/Utils/Attribution";
+import MarketingConversion from "../../../../Models/DatabaseModels/MarketingConversion";
+import RedditProvider from "../../../../Server/Utils/Marketing/Providers/Reddit";
+import { JSONObject } from "../../../../Types/JSON";
+import { MarketingConversionType } from "../../../../Types/Marketing/MarketingConversion";
+import ObjectID from "../../../../Types/ObjectID";
+import axios, { AxiosResponse } from "axios";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  jest,
+  test,
+} from "@jest/globals";
+import { SpyInstance } from "jest-mock";
+
+/*
+ * ---------------------------------------------------------------------------
+ * Reddit Conversions API.
+ *
+ * Reddit's tracking types are the same hazard as Meta's event names: `Purchase`
+ * is the revenue type, and the provider used to reach it for anything that was
+ * not a signup. Reddit has no "meeting booked" type, so both sales-led steps
+ * are `Lead` — which is the honest mapping, not a placeholder.
+ *
+ * Reddit also matches on a hashed email, so a conversion without rdt_cid is
+ * still uploadable.
+ * ---------------------------------------------------------------------------
+ */
+
+jest.mock("../../../../Server/EnvironmentConfig", () => {
+  return {
+    RedditAdsOAuthClientId: "reddit-client-id",
+    RedditAdsOAuthClientSecret: "reddit-client-secret",
+    RedditAdsOAuthRefreshToken: "reddit-refresh-token",
+    RedditAdsAccountId: "reddit-account",
+  };
+});
+
+type MakeConversionFunction = (
+  data?: Partial<MarketingConversion>,
+) => MarketingConversion;
+
+const makeConversion: MakeConversionFunction = (
+  data: Partial<MarketingConversion> = {},
+): MarketingConversion => {
+  return Object.assign(new MarketingConversion(), {
+    id: new ObjectID("22222222-2222-4222-8222-222222222222"),
+    conversionType: MarketingConversionType.SignUp,
+    conversionAt: new Date("2026-07-22T10:11:12.345Z"),
+    clickIds: { rdt_cid: "reddit-click" },
+    ...data,
+  });
+};
+
+type ResponseFunction = (data: JSONObject) => AxiosResponse<JSONObject>;
+
+const response: ResponseFunction = (
+  data: JSONObject,
+): AxiosResponse<JSONObject> => {
+  return { data } as AxiosResponse<JSONObject>;
+};
+
+type UploadedEventFunction = (postSpy: SpyInstance<any>) => JSONObject;
+
+// Call 0 is the OAuth token exchange; call 1 is the conversion upload.
+const uploadedEvent: UploadedEventFunction = (
+  postSpy: SpyInstance<any>,
+): JSONObject => {
+  const body: JSONObject = postSpy.mock.calls[1]?.[1] as JSONObject;
+  return (body["events"] as Array<JSONObject>)[0]!;
+};
+
+type MockUploadFunction = (postSpy: SpyInstance<any>) => void;
+
+const mockUpload: MockUploadFunction = (postSpy: SpyInstance<any>): void => {
+  postSpy
+    .mockResolvedValueOnce(
+      response({ access_token: "access-token", expires_in: 3600 }) as never,
+    )
+    .mockResolvedValueOnce(response({}) as never);
+};
+
+describe("RedditProvider", () => {
+  let provider: RedditProvider;
+  let postSpy: SpyInstance<any>;
+
+  beforeEach(() => {
+    provider = new RedditProvider();
+    postSpy = jest.spyOn(axios, "post") as SpyInstance<any>;
+    // Reddit only accepts events up to 7 days old; freeze inside that window.
+    jest
+      .spyOn(Date, "now")
+      .mockReturnValue(new Date("2026-07-23T10:11:12.345Z").getTime());
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test("reports configured only when the OAuth and account settings exist", () => {
+    expect(provider.isConfigured()).toBe(true);
+  });
+
+  describe("identifiers", () => {
+    test("accepts a conversion with only a click id", () => {
+      expect(provider.getSkipReason(makeConversion())).toBeNull();
+    });
+
+    test("accepts a conversion with only an email", () => {
+      expect(
+        provider.getSkipReason(
+          makeConversion({ clickIds: {}, email: "ada@example.com" }),
+        ),
+      ).toBeNull();
+    });
+
+    test("permanently skips a conversion with neither", () => {
+      expect(provider.getSkipReason(makeConversion({ clickIds: {} }))).toEqual({
+        reason: "No Reddit click id (rdt_cid) and no email to match on",
+        isPermanent: true,
+      });
+    });
+
+    test("permanently skips a conversion outside Reddit's 7-day window", () => {
+      expect(
+        provider.getSkipReason(
+          makeConversion({
+            conversionAt: new Date("2026-07-01T00:00:00.000Z"),
+          }),
+        ),
+      ).toEqual({
+        reason: "Conversion older than Reddit's 7-day upload window",
+        isPermanent: true,
+      });
+    });
+
+    test("sends the click id and the hashed email when both are known", async () => {
+      mockUpload(postSpy);
+
+      await provider.upload([makeConversion({ email: "Ada@Example.com" })]);
+
+      const event: JSONObject = uploadedEvent(postSpy);
+
+      expect(event["click_id"]).toBe("reddit-click");
+      expect(event["user"]).toEqual({
+        email: Attribution.hashEmail("ada@example.com"),
+      });
+    });
+
+    /*
+     * The click id used to be sent as `click_id: "" ` when absent. An empty
+     * string is not "no identifier" to an API, it is an identifier that cannot
+     * match anything — omit the field instead.
+     */
+    test("omits click_id entirely when there is no click id", async () => {
+      mockUpload(postSpy);
+
+      await provider.upload([
+        makeConversion({ clickIds: {}, email: "ada@example.com" }),
+      ]);
+
+      expect(uploadedEvent(postSpy)["click_id"]).toBeUndefined();
+    });
+
+    test("never sends the address in the clear", async () => {
+      mockUpload(postSpy);
+
+      await provider.upload([makeConversion({ email: "ada@example.com" })]);
+
+      expect(JSON.stringify(postSpy.mock.calls[1]?.[1])).not.toContain(
+        "ada@example.com",
+      );
+    });
+  });
+
+  describe("tracking types", () => {
+    test.each([
+      [MarketingConversionType.SignUp, "SignUp"],
+      [MarketingConversionType.MeetingBooked, "Lead"],
+      [MarketingConversionType.PaidSubscription, "Purchase"],
+    ])(
+      "sends %s as %s",
+      async (
+        conversionType: MarketingConversionType,
+        expectedTrackingType: string,
+      ) => {
+        mockUpload(postSpy);
+
+        await provider.upload([
+          makeConversion({ conversionType: conversionType }),
+        ]);
+
+        expect(uploadedEvent(postSpy)["event_type"]).toEqual({
+          tracking_type: expectedTrackingType,
+        });
+      },
+    );
+
+    test.each([MarketingConversionType.MeetingBooked])(
+      "attaches no revenue to %s even when the row holds a value",
+      async (conversionType: MarketingConversionType) => {
+        mockUpload(postSpy);
+
+        await provider.upload([
+          makeConversion({
+            conversionType: conversionType,
+            conversionValueInUSDCents: 500000,
+          }),
+        ]);
+
+        const metadata: JSONObject = uploadedEvent(postSpy)[
+          "event_metadata"
+        ] as JSONObject;
+
+        expect(metadata["value_decimal"]).toBeUndefined();
+        expect(metadata["currency"]).toBeUndefined();
+      },
+    );
+
+    test("attaches revenue to a paid subscription", async () => {
+      mockUpload(postSpy);
+
+      await provider.upload([
+        makeConversion({
+          conversionType: MarketingConversionType.PaidSubscription,
+          conversionValueInUSDCents: 12999,
+        }),
+      ]);
+
+      expect(uploadedEvent(postSpy)["event_metadata"]).toEqual({
+        conversion_id: "22222222-2222-4222-8222-222222222222",
+        value_decimal: 129.99,
+        currency: "USD",
+      });
+    });
+  });
+
+  test("keys the event on the conversion row id so retries dedupe", async () => {
+    mockUpload(postSpy);
+
+    await provider.upload([makeConversion()]);
+
+    expect(
+      (uploadedEvent(postSpy)["event_metadata"] as JSONObject)["conversion_id"],
+    ).toBe("22222222-2222-4222-8222-222222222222");
+  });
+
+  test("posts to the configured ad account", async () => {
+    mockUpload(postSpy);
+
+    await provider.upload([makeConversion()]);
+
+    expect(postSpy.mock.calls[1]?.[0]).toBe(
+      "https://ads-api.reddit.com/api/v2.0/conversions/events/reddit-account",
+    );
+  });
+});

package/Tests/Server/Utils/Measurement/MeasurementDefinitionValidator.test.ts

@@ -0,0 +1,322 @@
+import MeasurementDefinitionValidator from "../../../../Server/Utils/Measurement/MeasurementDefinitionValidator";
+import MeasurementOccurrence from "../../../../Types/Measurement/MeasurementOccurrence";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+
+const STATE_ENTERED: string = "State Entered";
+const STATE_ROLE_ENTERED: string = "State Role Entered";
+const DECLARED_AT: string = "Declared At";
+const IMPACT_STARTED_AT: string = "Impact Started At";
+
+function anchorPair(
+  overrides: Partial<
+    Parameters<typeof MeasurementDefinitionValidator.validateAnchorPair>[0]
+  > = {},
+): Parameters<typeof MeasurementDefinitionValidator.validateAnchorPair>[0] {
+  return {
+    startAnchorType: IMPACT_STARTED_AT,
+    endAnchorType: DECLARED_AT,
+    stateEnteredAnchor: STATE_ENTERED,
+    stateRoleEnteredAnchor: STATE_ROLE_ENTERED,
+    ...overrides,
+  };
+}
+
+describe("MeasurementDefinitionValidator", () => {
+  describe("validateKey", () => {
+    test.each(["time-to-detect", "t", "9lives", "a-b-c-d-e-f", "a".repeat(50)])(
+      "accepts %s",
+      (key: string) => {
+        expect(() => {
+          return MeasurementDefinitionValidator.validateKey(key);
+        }).not.toThrow();
+      },
+    );
+
+    test.each([
+      ["", "empty"],
+      ["Time-To-Detect", "uppercase"],
+      ["time to detect", "spaces"],
+      ["time_to_detect", "underscores"],
+      ["-leading-hyphen", "leading hyphen"],
+      ["time.to.detect", "dots"],
+      ["a".repeat(51), "too long"],
+      ["времени", "non-ascii"],
+    ])("rejects %s (%s)", (key: string) => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateKey(key);
+      }).toThrow(BadDataException);
+    });
+
+    test("rejects an absent key", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateKey(undefined);
+      }).toThrow(BadDataException);
+    });
+
+    test("the rejection message shows a usable example", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateKey("Time To Detect");
+      }).toThrow(/time-to-detect/);
+    });
+  });
+
+  describe("validateAnchorPair — required companions", () => {
+    test("a state-entered anchor needs a state", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({ startAnchorType: STATE_ENTERED }),
+        );
+      }).toThrow(BadDataException);
+    });
+
+    test("a state-entered end anchor needs a state", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({ endAnchorType: STATE_ENTERED }),
+        );
+      }).toThrow(BadDataException);
+    });
+
+    test("a state-role anchor needs a role", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({ endAnchorType: STATE_ROLE_ENTERED }),
+        );
+      }).toThrow(BadDataException);
+    });
+
+    test("accepts a state-entered anchor once the state is supplied", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({
+            startAnchorType: STATE_ENTERED,
+            startStateId: "state-1",
+          }),
+        );
+      }).not.toThrow();
+    });
+
+    test("both ends are required", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({ startAnchorType: undefined }),
+        );
+      }).toThrow(BadDataException);
+
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({ endAnchorType: undefined }),
+        );
+      }).toThrow(BadDataException);
+    });
+  });
+
+  describe("validateAnchorPair — definitions that would always be zero", () => {
+    /*
+     * These rejections are the point of the validator. A definition whose
+     * two ends are the same point charts a flat zero on every entity, which
+     * reads as "we do this instantly" rather than "this is not configured".
+     */
+    test("rejects two identical timestamp anchors", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({
+            startAnchorType: DECLARED_AT,
+            endAnchorType: DECLARED_AT,
+          }),
+        );
+      }).toThrow(/always be zero/);
+    });
+
+    test("rejects the same state at both ends with the same occurrence", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({
+            startAnchorType: STATE_ENTERED,
+            endAnchorType: STATE_ENTERED,
+            startStateId: "state-1",
+            endStateId: "state-1",
+          }),
+        );
+      }).toThrow(/always be zero/);
+    });
+
+    test("allows the same state at both ends when the occurrences differ", () => {
+      /*
+       * First-entered to last-entered of the same state is a real
+       * measurement: how long a reopened incident spent away from it.
+       */
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({
+            startAnchorType: STATE_ENTERED,
+            endAnchorType: STATE_ENTERED,
+            startStateId: "state-1",
+            endStateId: "state-1",
+            startOccurrence: MeasurementOccurrence.First,
+            endOccurrence: MeasurementOccurrence.Last,
+          }),
+        );
+      }).not.toThrow();
+    });
+
+    test("rejects the same role at both ends with the same occurrence", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({
+            startAnchorType: STATE_ROLE_ENTERED,
+            endAnchorType: STATE_ROLE_ENTERED,
+            startStateRole: "Resolved",
+            endStateRole: "Resolved",
+          }),
+        );
+      }).toThrow(/always be zero/);
+    });
+
+    test("allows two different states", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({
+            startAnchorType: STATE_ENTERED,
+            endAnchorType: STATE_ENTERED,
+            startStateId: "state-1",
+            endStateId: "state-2",
+          }),
+        );
+      }).not.toThrow();
+    });
+
+    test("allows two different timestamp anchors", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(anchorPair());
+      }).not.toThrow();
+    });
+  });
+
+  describe("aliased timestamp anchors", () => {
+    /*
+     * Several anchor types read the same column -- an alert's "Timeline
+     * Start" and "Created At" are both createdAt. Comparing enum values
+     * alone waved these through, and the resulting measurement charted a
+     * flat zero on every entity: the exact failure the zero-check exists to
+     * prevent, wearing two different names.
+     */
+    const SOURCES: Record<string, string> = {
+      "Timeline Start": "createdAt",
+      "Created At": "createdAt",
+      "Impact Started At": "impactStartedAt",
+      "Declared At": "declaredAt",
+    };
+
+    test("rejects two anchor types that read the same column", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({
+            startAnchorType: "Created At",
+            endAnchorType: "Timeline Start",
+            timestampAnchorSources: SOURCES,
+          }),
+        );
+      }).toThrow(/always be zero/);
+    });
+
+    test("rejects them in the other direction too", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({
+            startAnchorType: "Timeline Start",
+            endAnchorType: "Created At",
+            timestampAnchorSources: SOURCES,
+          }),
+        );
+      }).toThrow(/always be zero/);
+    });
+
+    test("still allows two anchors that read different columns", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({
+            startAnchorType: "Impact Started At",
+            endAnchorType: "Declared At",
+            timestampAnchorSources: SOURCES,
+          }),
+        );
+      }).not.toThrow();
+    });
+
+    test("without a source map, falls back to comparing the anchor types", () => {
+      // Domains that declare no aliases keep the original behaviour.
+      expect(() => {
+        return MeasurementDefinitionValidator.validateAnchorPair(
+          anchorPair({
+            startAnchorType: "Created At",
+            endAnchorType: "Timeline Start",
+          }),
+        );
+      }).not.toThrow();
+    });
+  });
+
+  describe("validateStateOrder", () => {
+    test("accepts an end state ordered after the start state", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateStateOrder({
+          startStateName: "Identified",
+          startStateOrder: 1,
+          endStateName: "Resolved",
+          endStateOrder: 3,
+        });
+      }).not.toThrow();
+    });
+
+    test("rejects an end state ordered before the start state", () => {
+      /*
+       * States are entered in strictly increasing order, so this describes a
+       * duration that can never complete. Without this check the definition
+       * looks fine and every entity silently reports Not Applicable forever.
+       */
+      expect(() => {
+        return MeasurementDefinitionValidator.validateStateOrder({
+          startStateName: "Resolved",
+          startStateOrder: 3,
+          endStateName: "Identified",
+          endStateOrder: 1,
+        });
+      }).toThrow(/could never complete/);
+    });
+
+    test("rejects two states at the same order", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateStateOrder({
+          startStateName: "A",
+          startStateOrder: 2,
+          endStateName: "B",
+          endStateOrder: 2,
+        });
+      }).toThrow(BadDataException);
+    });
+
+    test("names both states in the message so the fix is obvious", () => {
+      expect(() => {
+        return MeasurementDefinitionValidator.validateStateOrder({
+          startStateName: "Resolved",
+          startStateOrder: 3,
+          endStateName: "Acknowledged",
+          endStateOrder: 2,
+        });
+      }).toThrow(/"Acknowledged" comes before "Resolved"/);
+    });
+
+    test("says nothing when an order is unknown", () => {
+      // A deleted state leaves no order to compare; the evaluator reports it.
+      expect(() => {
+        return MeasurementDefinitionValidator.validateStateOrder({
+          startStateName: "Identified",
+          startStateOrder: undefined,
+          endStateName: "Resolved",
+          endStateOrder: 3,
+        });
+      }).not.toThrow();
+    });
+  });
+});