@oneuptime/common 12.0.33 → 13.0.0

package/Tests/Types/Rum/SessionReplayCustomEvents.test.ts

@@ -0,0 +1,434 @@
+import { describe, expect, it } from "@jest/globals";
+import {
+  SESSION_REPLAY_CUSTOM_EVENT_TAGS,
+  SESSION_REPLAY_RRWEB_CUSTOM_EVENT_TYPE,
+  SessionReplayCustomEventTag,
+  SessionReplayNetworkPayload,
+  SessionReplayPerformanceBudgetPayload,
+  SessionReplayWebVitalPayload,
+  isSessionReplayBfcacheRestorePayload,
+  isSessionReplayClickDroppedPayload,
+  isSessionReplayClickPayload,
+  isSessionReplayConsolePayload,
+  isSessionReplayCustomDroppedPayload,
+  isSessionReplayCustomEventData,
+  isSessionReplayCustomEventTag,
+  isSessionReplayCustomPayload,
+  isSessionReplayErrorPayload,
+  isSessionReplayFrustrationPayload,
+  isSessionReplayIdentifyPayload,
+  isSessionReplayNetworkPayload,
+  isSessionReplayPerformanceBudgetPayload,
+  isSessionReplayPerformancePayload,
+  isSessionReplayRoutePayload,
+  isSessionReplaySessionRotatedPayload,
+  isSessionReplayTagsPayload,
+  isSessionReplayVisibilityPayload,
+  isSessionReplayWebVitalPayload,
+} from "../../../Types/Rum/SessionReplayCustomEvents";
+import { CONSOLE_CUSTOM_EVENT_TAG } from "../../../../App/FeatureSet/BrowserRecorder/src/ConsoleRecorder";
+import { NETWORK_CUSTOM_EVENT_TAG } from "../../../../App/FeatureSet/BrowserRecorder/src/NetworkRecorder";
+import { ROUTE_CUSTOM_EVENT_TAG } from "../../../../App/FeatureSet/BrowserRecorder/src/RouteRecorder";
+import { ERROR_CUSTOM_EVENT_TAG } from "../../../../App/FeatureSet/BrowserRecorder/src/ErrorRecorder";
+import { FRUSTRATION_CUSTOM_EVENT_TAG } from "../../../../App/FeatureSet/BrowserRecorder/src/FrustrationDetector";
+import {
+  PERFORMANCE_CUSTOM_EVENT_TAG,
+  PerformanceIssue,
+  WebVitalEvent,
+} from "../../../../App/FeatureSet/BrowserRecorder/src/PerformanceRecorder";
+
+/*
+ * The tag vocabulary is quoted by stored payloads and by the recorder's
+ * own constants. Two things are pinned: the shared constants equal the
+ * strings the recorder emits today, so the player extracts what the
+ * recorder wrote; and every guard accepts the payload the recorder
+ * actually builds while rejecting the minimum-field violations.
+ */
+
+describe("SessionReplayCustomEventTag", () => {
+  it("matches the strings the recorder emits today, character for character", () => {
+    expect(SessionReplayCustomEventTag.Console).toBe(CONSOLE_CUSTOM_EVENT_TAG);
+    expect(SessionReplayCustomEventTag.Network).toBe(NETWORK_CUSTOM_EVENT_TAG);
+    expect(SessionReplayCustomEventTag.Route).toBe(ROUTE_CUSTOM_EVENT_TAG);
+    expect(SessionReplayCustomEventTag.Error).toBe(ERROR_CUSTOM_EVENT_TAG);
+    expect(SessionReplayCustomEventTag.Frustration).toBe(
+      FRUSTRATION_CUSTOM_EVENT_TAG,
+    );
+    expect(SessionReplayCustomEventTag.Performance).toBe(
+      PERFORMANCE_CUSTOM_EVENT_TAG,
+    );
+    /*
+     * Recorder.ts owns these two but imports rrweb at the top level, which
+     * Common's jest cannot resolve, so the strings are pinned literally
+     * against BFCACHE_CUSTOM_EVENT_TAG / SESSION_ROTATED_CUSTOM_EVENT_TAG.
+     */
+    expect(SessionReplayCustomEventTag.BfcacheRestore).toBe(
+      "oneuptime.bfcache-restore",
+    );
+    expect(SessionReplayCustomEventTag.SessionRotated).toBe(
+      "oneuptime.session-rotated",
+    );
+  });
+
+  it("names the new engagement tags under the oneuptime. prefix", () => {
+    expect(SessionReplayCustomEventTag.Click).toBe("oneuptime.click");
+    expect(SessionReplayCustomEventTag.ClickDropped).toBe(
+      "oneuptime.click-dropped",
+    );
+    expect(SessionReplayCustomEventTag.Visibility).toBe("oneuptime.visibility");
+    expect(SessionReplayCustomEventTag.Custom).toBe("oneuptime.custom");
+    expect(SessionReplayCustomEventTag.CustomDropped).toBe(
+      "oneuptime.custom-dropped",
+    );
+    expect(SessionReplayCustomEventTag.Identify).toBe("oneuptime.identify");
+    expect(SessionReplayCustomEventTag.Tags).toBe("oneuptime.tags");
+  });
+
+  it("every tag is unique and prefixed", () => {
+    expect(new Set(SESSION_REPLAY_CUSTOM_EVENT_TAGS).size).toBe(
+      SESSION_REPLAY_CUSTOM_EVENT_TAGS.length,
+    );
+    expect(SESSION_REPLAY_CUSTOM_EVENT_TAGS).toHaveLength(15);
+
+    for (const tag of SESSION_REPLAY_CUSTOM_EVENT_TAGS) {
+      expect(tag.startsWith("oneuptime.")).toBe(true);
+      expect(isSessionReplayCustomEventTag(tag)).toBe(true);
+    }
+
+    expect(isSessionReplayCustomEventTag("oneuptime.nope")).toBe(false);
+    expect(SESSION_REPLAY_RRWEB_CUSTOM_EVENT_TYPE).toBe(5);
+  });
+
+  it("isSessionReplayCustomEventData needs a string tag", () => {
+    expect(isSessionReplayCustomEventData({ tag: "x", payload: {} })).toBe(
+      true,
+    );
+    expect(isSessionReplayCustomEventData({ tag: "x" })).toBe(true);
+    expect(isSessionReplayCustomEventData({ payload: {} })).toBe(false);
+    expect(isSessionReplayCustomEventData(null)).toBe(false);
+  });
+});
+
+describe("payload guards accept what the recorder builds", () => {
+  it("console: ConsoleRecorder's { level, message }", () => {
+    expect(
+      isSessionReplayConsolePayload({ level: "error", message: "x" }),
+    ).toBe(true);
+    expect(isSessionReplayConsolePayload({ level: "warn", message: "" })).toBe(
+      true,
+    );
+    expect(isSessionReplayConsolePayload({ level: "log", message: "x" })).toBe(
+      false,
+    );
+    expect(isSessionReplayConsolePayload({ level: "error" })).toBe(false);
+  });
+
+  it("network: NetworkRecorder's RecordedRequest, with and without traceId", () => {
+    const request: Record<string, unknown> = {
+      method: "POST",
+      url: "https://acme.com/api/orders",
+      status: 500,
+      durationMs: 220,
+      responseBytes: 1200,
+      isError: true,
+    };
+
+    expect(isSessionReplayNetworkPayload(request)).toBe(true);
+    expect(isSessionReplayNetworkPayload({ ...request, traceId: "abc" })).toBe(
+      true,
+    );
+    expect(
+      isSessionReplayNetworkPayload({
+        ...request,
+        initiator: "xhr",
+        requestBytes: 3,
+      }),
+    ).toBe(true);
+    expect(isSessionReplayNetworkPayload({ ...request, status: "500" })).toBe(
+      false,
+    );
+    expect(isSessionReplayNetworkPayload({ method: "GET" })).toBe(false);
+
+    /*
+     * A cancelled request is not a failed one (status 0, isError false),
+     * and the cap marker is one empty entry saying where capture stopped.
+     * Both are declared so the rail can render them as themselves instead
+     * of painting every navigation-away red.
+     */
+    const cancelled: SessionReplayNetworkPayload = {
+      method: "GET",
+      url: "https://acme.com/api/search",
+      status: 0,
+      durationMs: 12,
+      responseBytes: 0,
+      isError: false,
+      aborted: true,
+    };
+
+    const capMarker: SessionReplayNetworkPayload = {
+      method: "",
+      url: "",
+      status: 0,
+      durationMs: 0,
+      responseBytes: 0,
+      isError: false,
+      isCapMarker: true,
+    };
+
+    expect(isSessionReplayNetworkPayload(cancelled)).toBe(true);
+    expect(isSessionReplayNetworkPayload(capMarker)).toBe(true);
+  });
+
+  it("route: RouteRecorder's { from, to, kind }", () => {
+    expect(
+      isSessionReplayRoutePayload({ from: "/a", to: "/b", kind: "pushState" }),
+    ).toBe(true);
+    expect(
+      isSessionReplayRoutePayload({ from: "/a", to: "/b", kind: "hashchange" }),
+    ).toBe(true);
+    expect(
+      isSessionReplayRoutePayload({ from: "/a", to: "/b", kind: "nav" }),
+    ).toBe(false);
+  });
+
+  it("error: ErrorRecorder's masked RecordedError plus optional occurredAtUnixMs", () => {
+    expect(
+      isSessionReplayErrorPayload({ kind: "error", message: "boom" }),
+    ).toBe(true);
+    expect(
+      isSessionReplayErrorPayload({
+        kind: "unhandledrejection",
+        message: "boom",
+        source: "https://acme.com/app.js",
+        lineNumber: 1,
+        columnNumber: 2,
+        stack: "Error: boom",
+        occurredAtUnixMs: 1700000000000,
+      }),
+    ).toBe(true);
+    expect(isSessionReplayErrorPayload({ kind: "panic", message: "x" })).toBe(
+      false,
+    );
+  });
+
+  it("frustration: FrustrationDetector's signal shapes", () => {
+    expect(
+      isSessionReplayFrustrationPayload({
+        kind: "rage-click",
+        atUnixMs: 1,
+        x: 10,
+        y: 20,
+        clickCount: 4,
+      }),
+    ).toBe(true);
+    expect(
+      isSessionReplayFrustrationPayload({
+        kind: "refresh-rage",
+        atUnixMs: 1,
+        reloadCount: 3,
+      }),
+    ).toBe(true);
+    expect(isSessionReplayFrustrationPayload({ kind: "rage-click" })).toBe(
+      false,
+    );
+  });
+
+  it("performance: the budget variant PerformanceRecorder emits, and the web-vital variant", () => {
+    const budget: Record<string, unknown> = {
+      kind: "lcp",
+      durationMs: 4800,
+      budgetMs: 4000,
+    };
+    const vital: Record<string, unknown> = {
+      kind: "web-vital",
+      metric: "INP",
+      value: 320,
+      rating: "poor",
+    };
+
+    expect(isSessionReplayPerformanceBudgetPayload(budget)).toBe(true);
+    expect(isSessionReplayWebVitalPayload(budget)).toBe(false);
+    expect(isSessionReplayWebVitalPayload(vital)).toBe(true);
+    expect(isSessionReplayPerformanceBudgetPayload(vital)).toBe(false);
+    expect(isSessionReplayPerformancePayload(budget)).toBe(true);
+    expect(isSessionReplayPerformancePayload(vital)).toBe(true);
+    expect(isSessionReplayPerformancePayload({ ...vital, metric: "FID" })).toBe(
+      false,
+    );
+    expect(isSessionReplayPerformancePayload({ ...vital, rating: "meh" })).toBe(
+      false,
+    );
+  });
+
+  /*
+   * PerformanceRecorder stamps every performance payload with the
+   * wall-clock time the entry HAPPENED (performance.timeOrigin +
+   * entry.startTime), never the time the observer delivered it: with
+   * buffered:true an LCP callback fires when the recorder boots and long
+   * tasks are batched after they end, so the emit time would draw the
+   * marker after the jank it explains. The contract has to declare the
+   * field - the recorder's own types extend these interfaces - and it has
+   * to stay optional, because a recorder older than it sends none. These
+   * literals are the compile-time half of that; an undeclared field is an
+   * excess-property error under ts-jest.
+   */
+  it("performance: both variants carry the optional occurredAtUnixMs the recorder stamps", () => {
+    const budget: SessionReplayPerformanceBudgetPayload = {
+      kind: "long-task",
+      durationMs: 320,
+      budgetMs: 200,
+      occurredAtUnixMs: 1757000000000,
+    };
+
+    const vital: SessionReplayWebVitalPayload = {
+      kind: "web-vital",
+      metric: "LCP",
+      value: 4800,
+      rating: "poor",
+      occurredAtUnixMs: 1757000000123,
+    };
+
+    /* What PerformanceRecorder builds is assignable to what it crosses on. */
+    const recorderIssue: PerformanceIssue = budget;
+    const recorderVital: WebVitalEvent = {
+      ...vital,
+      occurredAtUnixMs: 1757000000123,
+    };
+
+    expect(recorderIssue.occurredAtUnixMs).toBe(1757000000000);
+    expect(recorderVital.occurredAtUnixMs).toBe(1757000000123);
+
+    /* The guards ignore it: an older recorder's payload is still valid. */
+    expect(isSessionReplayPerformanceBudgetPayload(budget)).toBe(true);
+    expect(isSessionReplayWebVitalPayload(vital)).toBe(true);
+    expect(
+      isSessionReplayPerformanceBudgetPayload({
+        kind: "long-task",
+        durationMs: 320,
+        budgetMs: 200,
+      }),
+    ).toBe(true);
+  });
+
+  it("bfcache-restore and session-rotated: Recorder's payloads", () => {
+    expect(isSessionReplayBfcacheRestorePayload({ restoredAtUnixMs: 1 })).toBe(
+      true,
+    );
+    expect(isSessionReplayBfcacheRestorePayload({})).toBe(false);
+
+    expect(
+      isSessionReplaySessionRotatedPayload({
+        previousSessionId: "old",
+        rotationReason: "idle",
+        rotatedAtUnixMs: 1,
+      }),
+    ).toBe(true);
+    expect(
+      isSessionReplaySessionRotatedPayload({
+        previousSessionId: "old",
+        rotationReason: "because",
+        rotatedAtUnixMs: 1,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("payload guards for the engagement events", () => {
+  it("click: selector, x, y and atUnixMs required; text optional and string", () => {
+    expect(
+      isSessionReplayClickPayload({
+        selector: "button#buy.primary",
+        text: "Place order",
+        x: 1,
+        y: 2,
+        atUnixMs: 3,
+      }),
+    ).toBe(true);
+    expect(
+      isSessionReplayClickPayload({ selector: "div", x: 1, y: 2, atUnixMs: 3 }),
+    ).toBe(true);
+    expect(
+      isSessionReplayClickPayload({
+        selector: "div",
+        x: 1,
+        y: 2,
+        atUnixMs: 3,
+        text: 9,
+      }),
+    ).toBe(false);
+    expect(isSessionReplayClickPayload({ selector: "div", x: 1, y: 2 })).toBe(
+      false,
+    );
+  });
+
+  it("click-dropped / custom-dropped: a finite count", () => {
+    expect(isSessionReplayClickDroppedPayload({ count: 12 })).toBe(true);
+    expect(isSessionReplayClickDroppedPayload({ count: "12" })).toBe(false);
+    expect(isSessionReplayCustomDroppedPayload({ count: 0 })).toBe(true);
+    expect(isSessionReplayCustomDroppedPayload({})).toBe(false);
+  });
+
+  it("visibility: hidden|visible with a time", () => {
+    expect(
+      isSessionReplayVisibilityPayload({ state: "hidden", atUnixMs: 1 }),
+    ).toBe(true);
+    expect(
+      isSessionReplayVisibilityPayload({ state: "prerender", atUnixMs: 1 }),
+    ).toBe(false);
+  });
+
+  it("custom: a non-empty name and, when present, a string map of properties", () => {
+    expect(isSessionReplayCustomPayload({ name: "checkout" })).toBe(true);
+    expect(
+      isSessionReplayCustomPayload({
+        name: "checkout",
+        properties: { step: "2" },
+      }),
+    ).toBe(true);
+    expect(isSessionReplayCustomPayload({ name: "" })).toBe(false);
+    expect(
+      isSessionReplayCustomPayload({
+        name: "checkout",
+        properties: { step: 2 },
+      }),
+    ).toBe(false);
+  });
+
+  it("identify: hasTraits boolean, and nothing else is required (never the ref)", () => {
+    expect(isSessionReplayIdentifyPayload({ hasTraits: true })).toBe(true);
+    expect(isSessionReplayIdentifyPayload({ hasTraits: "yes" })).toBe(false);
+  });
+
+  it("tags: a string map", () => {
+    expect(isSessionReplayTagsPayload({ tags: { build: "1" } })).toBe(true);
+    expect(isSessionReplayTagsPayload({ tags: {} })).toBe(true);
+    expect(isSessionReplayTagsPayload({ tags: ["a"] })).toBe(false);
+    expect(isSessionReplayTagsPayload({})).toBe(false);
+  });
+
+  it("every guard rejects non-objects without throwing", () => {
+    const guards: Array<(value: unknown) => boolean> = [
+      isSessionReplayConsolePayload,
+      isSessionReplayNetworkPayload,
+      isSessionReplayRoutePayload,
+      isSessionReplayErrorPayload,
+      isSessionReplayFrustrationPayload,
+      isSessionReplayPerformancePayload,
+      isSessionReplayBfcacheRestorePayload,
+      isSessionReplaySessionRotatedPayload,
+      isSessionReplayClickPayload,
+      isSessionReplayClickDroppedPayload,
+      isSessionReplayVisibilityPayload,
+      isSessionReplayCustomPayload,
+      isSessionReplayCustomDroppedPayload,
+      isSessionReplayIdentifyPayload,
+      isSessionReplayTagsPayload,
+    ];
+
+    for (const guard of guards) {
+      for (const value of [null, undefined, 1, "x", [], (): void => {}]) {
+        expect(guard(value)).toBe(false);
+      }
+    }
+  });
+});

package/Tests/Types/Telemetry/InventoryLiveness.test.ts

@@ -0,0 +1,99 @@
+import EntitySource from "../../../Types/Telemetry/EntitySource";
+import {
+  InventoryLiveness,
+  INVENTORY_LIVE_WINDOW_MINUTES,
+  INVENTORY_STALE_AFTER_MINUTES,
+  getInventoryLivenessState,
+} from "../../../Types/Telemetry/InventoryLiveness";
+
+const NOW: Date = new Date("2026-09-07T12:00:00.000Z");
+
+describe("inventory heartbeat classification", () => {
+  test.each([
+    [-60_000, InventoryLiveness.Live],
+    [0, InventoryLiveness.Live],
+    [30 * 60_000, InventoryLiveness.Live],
+    [31 * 60_000 - 1, InventoryLiveness.Live],
+    [31 * 60_000, InventoryLiveness.Recent],
+    [31 * 60_000 + 1, InventoryLiveness.Recent],
+    [1440 * 60_000, InventoryLiveness.Recent],
+    [1441 * 60_000 - 1, InventoryLiveness.Recent],
+    [1441 * 60_000, InventoryLiveness.Stale],
+    [1441 * 60_000 + 1, InventoryLiveness.Stale],
+    [365 * 24 * 60 * 60_000, InventoryLiveness.Stale],
+  ])(
+    "an age of %s ms has status %s",
+    (age: number, status: InventoryLiveness) => {
+      expect(
+        getInventoryLivenessState({
+          source: EntitySource.Discovered,
+          lastSeenAt: new Date(NOW.getTime() - age),
+          now: NOW,
+        }),
+      ).toBe(status);
+    },
+  );
+
+  test.each([undefined, null, "not-a-date", new Date(NaN)])(
+    "an absent or invalid discovered heartbeat is never seen (%s)",
+    (lastSeenAt: Date | string | undefined | null) => {
+      expect(
+        getInventoryLivenessState({
+          source: EntitySource.Discovered,
+          lastSeenAt,
+          now: NOW,
+        }),
+      ).toBe(InventoryLiveness.Never);
+    },
+  );
+
+  test.each([
+    EntitySource.Inventory,
+    EntitySource.Manual,
+    "unknown",
+    undefined,
+  ])("%s is never aged as telemetry", (source: string | undefined) => {
+    for (const lastSeenAt of [
+      undefined,
+      null,
+      "not-a-date",
+      NOW,
+      new Date("2000-01-01T00:00:00.000Z"),
+    ]) {
+      expect(getInventoryLivenessState({ source, lastSeenAt, now: NOW })).toBe(
+        InventoryLiveness.NotTracked,
+      );
+    }
+  });
+
+  test("serialized dates and Date objects classify identically", () => {
+    for (const minutes of [0, 30, 31, 1440, 1441]) {
+      const lastSeenAt: Date = new Date(NOW.getTime() - minutes * 60_000);
+      expect(
+        getInventoryLivenessState({
+          source: EntitySource.Discovered,
+          lastSeenAt: lastSeenAt.toISOString(),
+          now: NOW,
+        }),
+      ).toBe(
+        getInventoryLivenessState({
+          source: EntitySource.Discovered,
+          lastSeenAt,
+          now: NOW,
+        }),
+      );
+    }
+  });
+
+  test("thresholds retain the established inventory badge vocabulary", () => {
+    expect(INVENTORY_LIVE_WINDOW_MINUTES).toBe(30);
+    expect(INVENTORY_STALE_AFTER_MINUTES).toBe(1440);
+    expect(Object.values(InventoryLiveness)).toEqual([
+      "live",
+      "recent",
+      "stale",
+      "never",
+      "not-tracked",
+    ]);
+  });
+});