fix: prevent "document is not defined" error in non-DOM environments

.eslintrc.js

@@ -45,6 +45,8 @@ module.exports = {
         'EIP6963.test.ts',
         'CAIP294.test.ts',
         'initializeInpageProvider.test.ts',
+        'MetaMaskInpageProvider.test.ts',
+        'siteMetadata.test.ts',
         'jest.setup.browser.js',
       ],
       rules: {

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Prevent `document is not defined` error when constructing the provider in non-DOM environments, such as extension background pages and service workers ([#428](https://github.com/MetaMask/providers/pull/428))
+
 ## [22.1.1]
 
 ### Changed

jest.config.js

@@ -227,6 +227,7 @@ const browserConfig = {
     '**/*ExtensionProvider.test.ts',
     '**/EIP6963.test.ts',
     '**/CAIP294.test.ts',
+    '**/siteMetadata.test.ts',
   ],
   setupFilesAfterEnv: ['./jest.setup.browser.js'],
 };

src/MetaMaskInpageProvider.test.ts

@@ -8,6 +8,7 @@ import {
   MetaMaskInpageProviderStreamName,
   MetaMaskInpageProvider,
 } from './MetaMaskInpageProvider';
+import * as siteMetadata from './siteMetadata';
 import { MockConnectionStream } from '../test/mocks/MockConnectionStream';
 
 /**
@@ -1127,6 +1128,62 @@ describe('MetaMaskInpageProvider: Miscellanea', () => {
       expect(inpageProvider.selectedAddress).toBe('0xabc');
       expect(inpageProvider.isConnected()).toBe(true);
     });
+
+    describe('site metadata', () => {
+      it('sends site metadata immediately if the document has already loaded', () => {
+        const sendSiteMetadataSpy = jest
+          .spyOn(siteMetadata, 'sendSiteMetadata')
+          .mockResolvedValue(undefined);
+
+        expect(
+          () =>
+            new MetaMaskInpageProvider(new MockConnectionStream(), {
+              shouldSendMetadata: true,
+            }),
+        ).not.toThrow();
+
+        expect(sendSiteMetadataSpy).toHaveBeenCalledTimes(1);
+      });
+
+      it('sends site metadata on DOMContentLoaded if the document is still loading', () => {
+        const sendSiteMetadataSpy = jest
+          .spyOn(siteMetadata, 'sendSiteMetadata')
+          .mockResolvedValue(undefined);
+        jest
+          .spyOn(globalThis.document, 'readyState', 'get')
+          .mockReturnValue('loading');
+
+        expect(
+          () =>
+            new MetaMaskInpageProvider(new MockConnectionStream(), {
+              shouldSendMetadata: true,
+            }),
+        ).not.toThrow();
+        expect(sendSiteMetadataSpy).not.toHaveBeenCalled();
+
+        globalThis.window.dispatchEvent(new Event('DOMContentLoaded'));
+        expect(sendSiteMetadataSpy).toHaveBeenCalledTimes(1);
+      });
+
+      it('sends site metadata immediately if there is no document, e.g. in an extension background script', () => {
+        const sendSiteMetadataSpy = jest
+          .spyOn(siteMetadata, 'sendSiteMetadata')
+          .mockResolvedValue(undefined);
+        const documentSpy = jest
+          .spyOn(globalThis, 'document', 'get')
+          .mockReturnValue(undefined as unknown as Document);
+
+        expect(
+          () =>
+            new MetaMaskInpageProvider(new MockConnectionStream(), {
+              shouldSendMetadata: true,
+            }),
+        ).not.toThrow();
+        expect(sendSiteMetadataSpy).toHaveBeenCalledTimes(1);
+
+        documentSpy.mockRestore();
+      });
+    });
   });
 
   describe('isConnected', () => {

src/MetaMaskInpageProvider.ts

@@ -135,7 +135,14 @@ export class MetaMaskInpageProvider extends AbstractStreamProvider {
 
     // send website metadata
     if (shouldSendMetadata) {
-      if (document.readyState === 'complete') {
+      // The `document` global is not available in non-DOM environments, such
+      // as extension background pages and service workers. In such
+      // environments, there is nothing to wait for, so we treat the site
+      // metadata as immediately available.
+      if (
+        typeof document === 'undefined' ||
+        document.readyState === 'complete'
+      ) {
         // eslint-disable-next-line @typescript-eslint/no-floating-promises
         sendSiteMetadata(this._rpcEngine, this._log);
       } else {

src/siteMetadata.test.ts

@@ -0,0 +1,50 @@
+import type { JsonRpcEngine } from '@metamask/json-rpc-engine';
+
+import { sendSiteMetadata } from './siteMetadata';
+
+describe('sendSiteMetadata', () => {
+  it('sends site metadata from the DOM', async () => {
+    const meta = globalThis.document.createElement('meta');
+    meta.setAttribute('property', 'og:site_name');
+    meta.content = 'Test Site';
+    globalThis.document.head.appendChild(meta);
+
+    const handle = jest.fn();
+    await sendSiteMetadata({ handle } as unknown as JsonRpcEngine, console);
+
+    expect(handle).toHaveBeenCalledTimes(1);
+    expect(handle).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: 'metamask_sendDomainMetadata',
+        params: {
+          name: 'Test Site',
+          icon: null,
+        },
+      }),
+      expect.any(Function),
+    );
+  });
+
+  it('falls back to the hostname if there is no document, e.g. in an extension background script', async () => {
+    const documentSpy = jest
+      .spyOn(globalThis, 'document', 'get')
+      .mockReturnValue(undefined as unknown as Document);
+
+    const handle = jest.fn();
+    await sendSiteMetadata({ handle } as unknown as JsonRpcEngine, console);
+
+    expect(handle).toHaveBeenCalledTimes(1);
+    expect(handle).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: 'metamask_sendDomainMetadata',
+        params: {
+          name: globalThis.location.hostname,
+          icon: null,
+        },
+      }),
+      expect.any(Function),
+    );
+
+    documentSpy.mockRestore();
+  });
+});

src/siteMetadata.ts

@@ -41,8 +41,8 @@ export async function sendSiteMetadata(
  */
 async function getSiteMetadata() {
   return {
-    name: getSiteName(window),
-    icon: await getSiteIcon(window),
+    name: getSiteName(globalThis),
+    icon: await getSiteIcon(globalThis),
   };
 }
 
@@ -52,8 +52,13 @@ async function getSiteMetadata() {
  * @param windowObject - The window object to extract the site name from.
  * @returns The site name.
  */
-function getSiteName(windowObject: typeof window): string {
+function getSiteName(windowObject: typeof globalThis): string {
   const { document } = windowObject;
+  // The `document` global is not available in non-DOM environments, such as
+  // extension background pages and service workers.
+  if (typeof document === 'undefined') {
+    return windowObject.location.hostname;
+  }
 
   const siteName: HTMLMetaElement | null = document.querySelector(
     'head > meta[property="og:site_name"]',
@@ -73,7 +78,7 @@ function getSiteName(windowObject: typeof window): string {
     return document.title;
   }
 
-  return window.location.hostname;
+  return windowObject.location.hostname;
 }
 
 /**
@@ -83,9 +88,14 @@ function getSiteName(windowObject: typeof window): string {
  * @returns An icon URL, if one exists.
  */
 async function getSiteIcon(
-  windowObject: typeof window,
+  windowObject: typeof globalThis,
 ): Promise<string | null> {
   const { document } = windowObject;
+  // The `document` global is not available in non-DOM environments, such as
+  // extension background pages and service workers.
+  if (typeof document === 'undefined') {
+    return null;
+  }
 
   const icons: NodeListOf<HTMLLinkElement> = document.querySelectorAll(
     'head > link[rel~="icon"]',