Add lint rule to avoid direct usage of browser globals (#735)

## Motivation / Description
Our JS SDK can be used in non-browser environments, for example, in Expo
Go. We don't have many tests to make sure we don't break things in one
of these environments.

This PR adds a linter rule that will error when using browser globals
like `window` or `document` directly. Instead, it adds some helpers
`getWindow`, `getNullableWindow`, `getDocument` and
`getNullableDocument` to access these in a more intended mechanism.

Note that all purchase flows do require a browser environment right now,
so we are using the `getWindow` and `getDocument` method in most of
those flows.

Credits for the idea to @nihalgonsalves 🫶 

## Changes introduced

## Linear ticket (if any)

## Additional comments

Author: tonidero

eslint.config.js

@@ -16,6 +16,30 @@ export default [
           prefer: "type-imports",
         },
       ],
+      "no-restricted-globals": [
+        "error",
+        {
+          name: "window",
+          message:
+            "Use getWindow() or getNullableWindow() from helpers/browser-globals instead.",
+        },
+        {
+          name: "document",
+          message:
+            "Use getDocument() or getNullableDocument() from helpers/browser-globals instead.",
+        },
+      ],
+    },
+  },
+  {
+    files: [
+      "**/*.test.{js,ts}",
+      "**/tests/**/*.{js,ts}",
+      "**/vitest.setup.js",
+      "examples/webbilling-demo/**/*.{js,ts,jsx,tsx}",
+    ],
+    rules: {
+      "no-restricted-globals": "off",
     },
   },
 ];

package.json

@@ -41,7 +41,7 @@
     "build:dev": "tsc && vite build --mode development",
     "build:dev-watch": "tsc && vite build --mode development --watch",
     "preview": "vite preview",
-    "lint": "prettier --check .",
+    "lint": "prettier --check . && eslint src/",
     "format": "prettier --write .",
     "pack-build": "npm run build && npm pack",
     "test": "vitest run",

src/behavioural-events/sdk-event-context.ts

@@ -1,5 +1,9 @@
 import { VERSION } from "../helpers/constants";
 import { type EventContext } from "./event";
+import {
+  getNullableDocument,
+  getNullableWindow,
+} from "../helpers/browser-globals";
 
 export type SDKEventContextSource = "sdk" | "wpl" | string;
 
@@ -28,9 +32,9 @@ export function buildEventContext(
   rcSource: string | null,
 ): SDKEventContext & EventContext {
   // Guard against environments where window.location is not available
-  const hasWindowLocation = typeof window !== "undefined" && window.location;
-  const urlParams = hasWindowLocation
-    ? new URLSearchParams(window.location.search)
+  const win = getNullableWindow();
+  const urlParams = win?.location
+    ? new URLSearchParams(win.location.search)
     : new URLSearchParams();
 
   let screenWidth: number | null = null;
@@ -39,12 +43,10 @@ export function buildEventContext(
     screenWidth = screen.width;
     screenHeight = screen.height;
   }
-  let pageReferrer: string | null = null;
-  let pageTitle: string | null = null;
-  if (typeof document !== "undefined" && document) {
-    pageReferrer = document.referrer;
-    pageTitle = document.title;
-  }
+
+  const doc = getNullableDocument();
+  const pageReferrer = doc?.referrer ?? null;
+  const pageTitle = doc?.title ?? null;
 
   return {
     libraryName: "purchases-js",
@@ -60,8 +62,8 @@ export function buildEventContext(
     utmContent: urlParams.get("utm_content") ?? null,
     utmTerm: urlParams.get("utm_term") ?? null,
     pageReferrer: pageReferrer,
-    pageUrl: hasWindowLocation
-      ? `${window.location.origin}${window.location.pathname}`
+    pageUrl: win?.location
+      ? `${win.location.origin}${win.location.pathname}`
       : "",
     pageTitle: pageTitle,
     source: source,

src/helpers/browser-globals.ts

@@ -0,0 +1,62 @@
+/* eslint-disable no-restricted-globals */
+
+/**
+ * Helper functions to safely access browser globals (window, document)
+ * in environments that may not have them available (e.g., Node.js, Expo Go).
+ */
+
+import { ErrorCode, PurchasesError } from "../entities/errors";
+
+/**
+ * Access the `window` global or fail.
+ * @returns The `window` object if defined
+ * @throws PurchasesError if `window` is not available
+ */
+export function getWindow(): Window {
+  if (typeof window !== "undefined") {
+    return window;
+  }
+
+  throw new PurchasesError(
+    ErrorCode.UnsupportedError,
+    "window is not available. This SDK requires a browser environment for this operation.",
+  );
+}
+
+/**
+ * Safely access the `window` global, allowing undefined.
+ * @returns The `window` object or undefined if not available
+ */
+export function getNullableWindow(): Window | undefined {
+  if (typeof window !== "undefined") {
+    return window;
+  }
+  return undefined;
+}
+
+/**
+ * Access the `document` global or fail.
+ * @returns The `document` object if defined
+ * @throws PurchasesError if `document` is not available
+ */
+export function getDocument(): Document {
+  if (typeof document !== "undefined") {
+    return document;
+  }
+
+  throw new PurchasesError(
+    ErrorCode.UnsupportedError,
+    "document is not available. This SDK requires a browser environment for this operation.",
+  );
+}
+
+/**
+ * Safely access the `document` global, allowing undefined.
+ * @returns The `document` object or undefined if not available
+ */
+export function getNullableDocument(): Document | undefined {
+  if (typeof document !== "undefined") {
+    return document;
+  }
+  return undefined;
+}

src/helpers/simulated-store-purchase-helper.ts

@@ -6,6 +6,7 @@ import SimulatedStoreModal from "../ui/molecules/simulated-store-modal.svelte";
 import type { Backend } from "../networking/backend";
 import { postSimulatedStoreReceipt } from "./simulated-store-post-receipt-helper";
 import { Logger } from "./logger";
+import { getDocument } from "./browser-globals";
 
 export function purchaseSimulatedStoreProduct(
   purchaseParams: PurchaseParams,
@@ -27,14 +28,15 @@ export function purchaseSimulatedStoreProduct(
 
   return new Promise((resolve, reject) => {
     // Create a container for the modal
-    const container = document.createElement("div");
-    document.body.appendChild(container);
+    const doc = getDocument();
+    const container = doc.createElement("div");
+    doc.body.appendChild(container);
 
     const cleanup = () => {
       if (component) {
         unmount(component);
       }
-      document.body.removeChild(container);
+      doc.body.removeChild(container);
     };
 
     let component: ReturnType<typeof mount> | null = null;

src/helpers/utm-params.ts

@@ -1,8 +1,10 @@
+import { getNullableWindow } from "./browser-globals";
+
 export const autoParseUTMParams = () => {
   // Guard against environments where window.location is not available
-  const hasWindowLocation = typeof window !== "undefined" && window.location;
-  const params = hasWindowLocation
-    ? new URLSearchParams(window.location.search)
+  const win = getNullableWindow();
+  const params = win?.location
+    ? new URLSearchParams(win.location.search)
     : new URLSearchParams();
 
   const possibleParams = [

src/main.ts

@@ -104,6 +104,7 @@ import type {
   PresentExpressPurchaseButtonParams,
 } from "./entities/present-express-purchase-button-params";
 import { ExpressPurchaseButtonWrapper } from "./ui/express-purchase-button/express-purchase-button-wrapper.svelte";
+import { getWindow, getDocument } from "./helpers/browser-globals";
 
 export { ProductType } from "./entities/offerings";
 export type {
@@ -464,12 +465,12 @@ export class Purchases {
     const htmlTarget = paywallParams.htmlTarget;
     let wasRootAutoCreated = false;
 
-    let resolvedHTMLTarget =
-      htmlTarget ?? document.getElementById("rcb-ui-pw-root");
+    const doc = getDocument();
+    let resolvedHTMLTarget = htmlTarget ?? doc.getElementById("rcb-ui-pw-root");
 
     if (resolvedHTMLTarget === null) {
       wasRootAutoCreated = true;
-      const element = document.createElement("div");
+      const element = doc.createElement("div");
       element.id = "rcb-ui-pw-root";
       element.className = "rcb-ui-pw-root";
       // one point less than the purchase flow modal.
@@ -481,14 +482,14 @@ export class Purchases {
       element.style.height = "100%";
       element.style.overflow = "auto";
       element.style.backgroundColor = "rgba(0, 0, 0, 0.4)";
-      if (document.body.offsetWidth > 968) {
+      if (doc.body.offsetWidth > 968) {
         element.style.display = "flex";
         element.style.justifyContent = "center";
         element.style.alignItems = "center";
       }
       element.style.transition = "opacity 0.3s";
       element.style.opacity = "0";
-      document.body.appendChild(element);
+      doc.body.appendChild(element);
       resolvedHTMLTarget = element;
     }
 
@@ -598,7 +599,8 @@ export class Purchases {
 
       // Opinionated approach:
       // navigating to the URL in a new tab.
-      window.open(url, "_blank")?.focus();
+      const win = getWindow();
+      win.open(url, "_blank")?.focus();
     };
 
     const onRestorePurchasesClicked = () => {
@@ -1036,8 +1038,9 @@ export class Purchases {
     const isInElement = htmlTarget !== undefined;
 
     return new Promise((resolve, reject) => {
+      const win = getWindow();
       if (!isInElement) {
-        window.history.pushState({ checkoutOpen: true }, "");
+        win.history.pushState({ checkoutOpen: true }, "");
       }
 
       const unmountPurchaseUi = () => {
@@ -1053,7 +1056,7 @@ export class Purchases {
       );
 
       if (!isInElement && onClose) {
-        window.addEventListener("popstate", onClose as EventListener);
+        win.addEventListener("popstate", onClose as EventListener);
       }
 
       const onFinished = this.createCheckoutOnFinishedHandler(
@@ -1147,8 +1150,9 @@ export class Purchases {
     const isInElement = htmlTarget !== undefined;
 
     return new Promise((resolve, reject) => {
+      const win = getWindow();
       if (!isInElement) {
-        window.history.pushState({ checkoutOpen: true }, "");
+        win.history.pushState({ checkoutOpen: true }, "");
       }
 
       const unmountPaddlePurchaseUi = () => {
@@ -1209,13 +1213,13 @@ export class Purchases {
    * If no element is found, creates a new div with className "rcb-ui-root".
    */
   private resolveHTMLTarget(htmlTarget?: HTMLElement): HTMLElement {
-    let resolvedHTMLTarget =
-      htmlTarget ?? document.getElementById("rcb-ui-root");
+    const doc = getDocument();
+    let resolvedHTMLTarget = htmlTarget ?? doc.getElementById("rcb-ui-root");
 
     if (resolvedHTMLTarget === null) {
-      const element = document.createElement("div");
+      const element = doc.createElement("div");
       element.className = "rcb-ui-root";
-      document.body.appendChild(element);
+      doc.body.appendChild(element);
       resolvedHTMLTarget = element;
     }
 
@@ -1242,7 +1246,8 @@ export class Purchases {
     const onClose = () => {
       const event = createCheckoutSessionEndClosedEvent();
       this.eventsTracker.trackSDKEvent(event);
-      window.removeEventListener("popstate", onClose as EventListener);
+      const win = getWindow();
+      win.removeEventListener("popstate", onClose as EventListener);
 
       callback?.();