@oneuptime/common 12.0.17 → 12.0.19

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

@@ -0,0 +1,259 @@
+import { beforeEach, describe, expect, test } from "@jest/globals";
+
+let mockConfigured: boolean = true;
+let mockMisconfigured: boolean = false;
+
+jest.mock("../../../../Server/Utils/Marketing/MarketingEventWebhook", () => {
+  return {
+    __esModule: true,
+    default: {
+      isConfigured: (): boolean => {
+        return mockConfigured;
+      },
+      isMisconfigured: (): boolean => {
+        return mockMisconfigured;
+      },
+    },
+  };
+});
+
+jest.mock("../../../../Server/Utils/Logger", () => {
+  return {
+    __esModule: true,
+    default: { debug: jest.fn(), error: jest.fn(), warn: jest.fn() },
+  };
+});
+
+const mockAddJob: jest.Mock = jest.fn();
+
+jest.mock("../../../../Server/Infrastructure/Queue", () => {
+  return {
+    __esModule: true,
+    QueueName: { MarketingEvent: "MarketingEvent" },
+    default: {
+      addJob: (...args: Array<unknown>): unknown => {
+        return mockAddJob(...args);
+      },
+    },
+  };
+});
+
+import MarketingEventUtil from "../../../../Server/Utils/Marketing/MarketingEventUtil";
+import Attribution from "../../../../Server/Utils/Attribution";
+import {
+  MarketingEvent,
+  MarketingEventType,
+} from "../../../../Types/Marketing/MarketingEvent";
+
+describe("MarketingEventUtil", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockConfigured = true;
+    mockMisconfigured = false;
+    mockAddJob.mockResolvedValue({} as never);
+  });
+
+  describe("buildEvent", () => {
+    test("stamps the schema version so a receiver can branch on it", () => {
+      const event: MarketingEvent = MarketingEventUtil.buildEvent({
+        eventType: MarketingEventType.SignUp,
+        eventId: "sign_up:u1",
+        occurredAt: new Date("2026-08-24T10:00:00.000Z"),
+      });
+
+      expect(event.schemaVersion).toBe(1);
+      expect(event.eventType).toBe("sign_up");
+      expect(event.eventId).toBe("sign_up:u1");
+      expect(event.occurredAt).toBe("2026-08-24T10:00:00.000Z");
+    });
+
+    /*
+     * Both identity forms travel together: the address for a direct CRM join
+     * and the digest for anywhere that wants one. The digest must match what
+     * every other part of OneUptime produces, or the join it exists for fails.
+     */
+    test("carries the address and a matching SHA-256", () => {
+      const event: MarketingEvent = MarketingEventUtil.buildEvent({
+        eventType: MarketingEventType.MeetingBooked,
+        eventId: "meeting_booked:b1",
+        occurredAt: new Date(),
+        email: "Buyer@Example.com",
+      });
+
+      expect(event.email).toBe("Buyer@Example.com");
+      expect(event.emailHash).toBe(Attribution.hashEmail("Buyer@Example.com"));
+      // Normalisation is case-insensitive, so a differently cased address joins.
+      expect(event.emailHash).toBe(Attribution.hashEmail("buyer@example.com"));
+    });
+
+    test("omits both identity fields when there is no email", () => {
+      const event: MarketingEvent = MarketingEventUtil.buildEvent({
+        eventType: MarketingEventType.EnterpriseLicenseIssued,
+        eventId: "enterprise_license_issued:l1",
+        occurredAt: new Date(),
+      });
+
+      expect(event.email).toBeUndefined();
+      expect(event.emailHash).toBeUndefined();
+    });
+
+    test("copies every attribution column off the source row", () => {
+      const event: MarketingEvent = MarketingEventUtil.buildEvent({
+        eventType: MarketingEventType.SignUp,
+        eventId: "sign_up:u1",
+        occurredAt: new Date(),
+        attributionSource: {
+          utmSource: "google",
+          utmMedium: "cpc",
+          utmCampaign: "brand",
+          utmTerm: "oneuptime",
+          utmContent: "hero-b",
+          utmUrl: "https://oneuptime.com/?gclid=x",
+          clickIds: { gclid: "x" },
+          firstTouchAttribution: { utmSource: "linkedin" },
+        },
+      });
+
+      expect(event.attribution).toEqual({
+        utmSource: "google",
+        utmMedium: "cpc",
+        utmCampaign: "brand",
+        utmTerm: "oneuptime",
+        utmContent: "hero-b",
+        utmUrl: "https://oneuptime.com/?gclid=x",
+        clickIds: { gclid: "x" },
+        firstTouch: { utmSource: "linkedin" },
+      });
+    });
+
+    /*
+     * A conversion carrying no attribution is still a conversion. The two
+     * container fields default to empty objects rather than undefined so a
+     * receiver can always read .clickIds without a guard.
+     */
+    test("always gives attribution containers, even with no source", () => {
+      const event: MarketingEvent = MarketingEventUtil.buildEvent({
+        eventType: MarketingEventType.SignUp,
+        eventId: "sign_up:u1",
+        occurredAt: new Date(),
+      });
+
+      expect(event.attribution.clickIds).toEqual({});
+      expect(event.attribution.firstTouch).toEqual({});
+      expect(event.data).toEqual({});
+    });
+  });
+
+  describe("emit", () => {
+    test("queues the event under its own id with retries", async () => {
+      const event: MarketingEvent = MarketingEventUtil.buildEvent({
+        eventType: MarketingEventType.SignUp,
+        eventId: "sign_up:u1",
+        occurredAt: new Date(),
+      });
+
+      await MarketingEventUtil.emit(event);
+
+      expect(mockAddJob).toHaveBeenCalledTimes(1);
+
+      const call: Array<unknown> = mockAddJob.mock.calls[0] as Array<unknown>;
+
+      expect(call[0]).toBe("MarketingEvent");
+      expect(call[1]).toBe("sign_up:u1");
+      expect(call[2]).toBe("sign_up");
+      expect(call[3]).toEqual(event);
+      expect(call[4]).toEqual(
+        expect.objectContaining({ attempts: 5, backoffDelayInMs: 30_000 }),
+      );
+    });
+
+    test("does nothing when no endpoint is configured", async () => {
+      mockConfigured = false;
+
+      await MarketingEventUtil.emit(
+        MarketingEventUtil.buildEvent({
+          eventType: MarketingEventType.SignUp,
+          eventId: "sign_up:u1",
+          occurredAt: new Date(),
+        }),
+      );
+
+      expect(mockAddJob).not.toHaveBeenCalled();
+    });
+
+    /*
+     * A URL with no secret must not silently behave like "not configured" —
+     * the operator meant to send these somewhere and needs to be told why
+     * nothing arrived.
+     */
+    test("refuses to queue when a url is set without a secret", async () => {
+      mockConfigured = false;
+      mockMisconfigured = true;
+
+      await MarketingEventUtil.emit(
+        MarketingEventUtil.buildEvent({
+          eventType: MarketingEventType.SignUp,
+          eventId: "sign_up:u1",
+          occurredAt: new Date(),
+        }),
+      );
+
+      expect(mockAddJob).not.toHaveBeenCalled();
+    });
+
+    test("swallows a queue failure rather than failing its caller", async () => {
+      mockAddJob.mockRejectedValue(new Error("redis down") as never);
+
+      await expect(
+        MarketingEventUtil.emit(
+          MarketingEventUtil.buildEvent({
+            eventType: MarketingEventType.SignUp,
+            eventId: "sign_up:u1",
+            occurredAt: new Date(),
+          }),
+        ),
+      ).resolves.toBeUndefined();
+    });
+  });
+
+  /*
+   * Every caller is a commercial transaction that has already succeeded — a
+   * user created, a plan changed, a booking verified. Emitting must never be
+   * able to turn one of those into a failure, on either the synchronous or the
+   * asynchronous path.
+   */
+  describe("emitInBackground", () => {
+    test("never throws when the queue rejects", async () => {
+      mockAddJob.mockRejectedValue(new Error("redis down") as never);
+
+      expect(() => {
+        MarketingEventUtil.emitInBackground(
+          MarketingEventUtil.buildEvent({
+            eventType: MarketingEventType.SignUp,
+            eventId: "sign_up:u1",
+            occurredAt: new Date(),
+          }),
+        );
+      }).not.toThrow();
+
+      // Let the swallowed rejection settle so it cannot surface as unhandled.
+      await Promise.resolve();
+    });
+
+    test("never throws when the queue throws synchronously", () => {
+      mockAddJob.mockImplementation((): never => {
+        throw new Error("boom");
+      });
+
+      expect(() => {
+        MarketingEventUtil.emitInBackground(
+          MarketingEventUtil.buildEvent({
+            eventType: MarketingEventType.SignUp,
+            eventId: "sign_up:u1",
+            occurredAt: new Date(),
+          }),
+        );
+      }).not.toThrow();
+    });
+  });
+});

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

@@ -0,0 +1,257 @@
+import crypto from "crypto";
+import { beforeEach, describe, expect, test } from "@jest/globals";
+
+let mockUrl: string = "";
+let mockSecret: string = "";
+
+jest.mock("../../../../Server/EnvironmentConfig", () => {
+  return {
+    __esModule: true,
+    get MarketingWebhookUrl(): string {
+      return mockUrl;
+    },
+    get MarketingWebhookSecret(): string {
+      return mockSecret;
+    },
+  };
+});
+
+jest.mock("../../../../Server/Utils/Logger", () => {
+  return {
+    __esModule: true,
+    default: { debug: jest.fn(), error: jest.fn(), warn: jest.fn() },
+  };
+});
+
+const mockPost: jest.Mock = jest.fn();
+
+jest.mock("axios", () => {
+  class MockAxiosError extends Error {
+    public response?: { status: number; data: unknown } | undefined;
+  }
+
+  return {
+    __esModule: true,
+    default: {
+      post: (...args: Array<unknown>): unknown => {
+        return mockPost(...args);
+      },
+    },
+    AxiosError: MockAxiosError,
+  };
+});
+
+import MarketingEventWebhook from "../../../../Server/Utils/Marketing/MarketingEventWebhook";
+import {
+  MarketingEvent,
+  MarketingEventType,
+} from "../../../../Types/Marketing/MarketingEvent";
+
+const URL: string = "https://receiver.example.com/oneuptime";
+const SECRET: string = "test-secret-not-for-production";
+
+type MakeEventFunction = () => MarketingEvent;
+
+const makeEvent: MakeEventFunction = (): MarketingEvent => {
+  return {
+    schemaVersion: 1,
+    eventId: "sign_up:user-1",
+    eventType: MarketingEventType.SignUp,
+    occurredAt: "2026-08-24T10:00:00.000Z",
+    email: "buyer@example.com",
+    emailHash: "hash",
+    attribution: { clickIds: {}, firstTouch: {} },
+    data: {},
+  };
+};
+
+type PostCallFunction = () => {
+  url: string;
+  body: string;
+  config: { headers: Record<string, string> };
+};
+
+const postCall: PostCallFunction = (): {
+  url: string;
+  body: string;
+  config: { headers: Record<string, string> };
+} => {
+  const call: Array<unknown> = mockPost.mock.calls[0] as Array<unknown>;
+
+  return {
+    url: call[0] as string,
+    body: call[1] as string,
+    config: call[2] as { headers: Record<string, string> },
+  };
+};
+
+describe("MarketingEventWebhook", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockUrl = URL;
+    mockSecret = SECRET;
+    mockPost.mockResolvedValue({ status: 200 } as never);
+  });
+
+  describe("configuration", () => {
+    test("needs both a url and a secret", () => {
+      expect(MarketingEventWebhook.isConfigured()).toBe(true);
+
+      mockSecret = "";
+      expect(MarketingEventWebhook.isConfigured()).toBe(false);
+
+      mockSecret = SECRET;
+      mockUrl = "";
+      expect(MarketingEventWebhook.isConfigured()).toBe(false);
+    });
+
+    /*
+     * A URL with no secret is the dangerous shape: it looks configured, and
+     * sending to it would put email addresses on the wire with nothing for the
+     * receiver to authenticate. It has to be distinguishable from "not set up",
+     * so a caller can say so out loud instead of silently dropping events.
+     */
+    test("reports a url without a secret as misconfigured, not unconfigured", () => {
+      mockSecret = "";
+
+      expect(MarketingEventWebhook.isMisconfigured()).toBe(true);
+      expect(MarketingEventWebhook.isConfigured()).toBe(false);
+    });
+
+    test("is not misconfigured when nothing is set at all", () => {
+      mockUrl = "";
+      mockSecret = "";
+
+      expect(MarketingEventWebhook.isMisconfigured()).toBe(false);
+    });
+
+    test("sends nothing when unconfigured", async () => {
+      mockUrl = "";
+
+      await MarketingEventWebhook.deliver(makeEvent());
+
+      expect(mockPost).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("signing", () => {
+    test("signs the exact bytes it sends", async () => {
+      await MarketingEventWebhook.deliver(makeEvent());
+
+      const { body, config } = postCall();
+
+      const expected: string = crypto
+        .createHmac("sha256", SECRET)
+        .update(body, "utf8")
+        .digest("hex");
+
+      expect(config.headers["x-oneuptime-signature-256"]).toBe(expected);
+    });
+
+    /*
+     * The body has to go out as the pre-serialised string. If it were handed
+     * over as an object, the HTTP client would serialise it again and any
+     * difference in key order or spacing would make the digest unverifiable —
+     * the single most likely way for this integration to break silently.
+     */
+    test("sends the body as a string, not an object", async () => {
+      await MarketingEventWebhook.deliver(makeEvent());
+
+      const { body, config } = postCall();
+
+      expect(typeof body).toBe("string");
+      expect(JSON.parse(body)).toEqual(makeEvent());
+      expect(config.headers["content-type"]).toBe("application/json");
+    });
+
+    test("a digest computed over re-serialised JSON does not match", async () => {
+      await MarketingEventWebhook.deliver(makeEvent());
+
+      const { body, config } = postCall();
+
+      // Same data, different bytes — reordered and re-spaced.
+      const reSerialised: string = JSON.stringify(JSON.parse(body), null, 2);
+
+      const naive: string = crypto
+        .createHmac("sha256", SECRET)
+        .update(reSerialised, "utf8")
+        .digest("hex");
+
+      expect(naive).not.toBe(config.headers["x-oneuptime-signature-256"]);
+    });
+
+    test("different secrets produce different signatures", () => {
+      const body: string = JSON.stringify(makeEvent());
+
+      const first: string = MarketingEventWebhook.sign(body);
+
+      mockSecret = "a-different-secret";
+
+      expect(MarketingEventWebhook.sign(body)).not.toBe(first);
+    });
+
+    test("routes on id and type headers as well as the body", async () => {
+      await MarketingEventWebhook.deliver(makeEvent());
+
+      const { url, config } = postCall();
+
+      expect(url).toBe(URL);
+      expect(config.headers["x-oneuptime-event-id"]).toBe("sign_up:user-1");
+      expect(config.headers["x-oneuptime-event-type"]).toBe("sign_up");
+    });
+  });
+
+  describe("failure handling", () => {
+    /*
+     * Nothing stores these events, so the queue's retry is the only backstop.
+     * A delivery that fails has to throw — swallowing it loses the conversion
+     * with no row anywhere to reconcile against later.
+     */
+    test("throws on a transport failure so the queue retries", async () => {
+      mockPost.mockRejectedValue(new Error("ECONNREFUSED") as never);
+
+      await expect(MarketingEventWebhook.deliver(makeEvent())).rejects.toThrow(
+        /ECONNREFUSED/,
+      );
+    });
+
+    test("names the event in the failure so a log line is actionable", async () => {
+      mockPost.mockRejectedValue(new Error("boom") as never);
+
+      await expect(MarketingEventWebhook.deliver(makeEvent())).rejects.toThrow(
+        /sign_up:user-1/,
+      );
+    });
+
+    test("resolves quietly on a 2xx", async () => {
+      mockPost.mockResolvedValue({ status: 202 } as never);
+
+      await expect(
+        MarketingEventWebhook.deliver(makeEvent()),
+      ).resolves.toBeUndefined();
+    });
+
+    /*
+     * Non-2xx must reach the catch rather than resolving, which is what the
+     * explicit validateStatus is for — the default would resolve on a 4xx and
+     * the event would be reported as delivered when it was rejected.
+     */
+    test("treats only 2xx as success", async () => {
+      const { config } = await MarketingEventWebhook.deliver(makeEvent()).then(
+        () => {
+          return postCall();
+        },
+      );
+
+      const validateStatus: (status: number) => boolean = (
+        config as unknown as { validateStatus: (status: number) => boolean }
+      ).validateStatus;
+
+      expect(validateStatus(200)).toBe(true);
+      expect(validateStatus(299)).toBe(true);
+      expect(validateStatus(400)).toBe(false);
+      expect(validateStatus(500)).toBe(false);
+      expect(validateStatus(302)).toBe(false);
+    });
+  });
+});