@wxt-dev/analytics 0.2.8 → 0.4.1

package/dist/module.mjs

@@ -0,0 +1,61 @@
+import 'wxt';
+import 'wxt/sandbox';
+import { defineWxtModule, addAlias, addWxtPlugin, addViteConfig } from 'wxt/modules';
+import { resolve } from 'node:path';
+
+const index = defineWxtModule({
+  name: "analytics",
+  imports: [{ name: "analytics", from: "#analytics" }],
+  setup(wxt) {
+    const wxtAnalyticsFolder = resolve(wxt.config.wxtDir, "analytics");
+    const wxtAnalyticsIndex = resolve(wxtAnalyticsFolder, "index.ts");
+    const clientModuleId = "@wxt-dev/analytics" ;
+    const pluginModuleId = "@wxt-dev/analytics/background-plugin" ;
+    wxt.hook("build:manifestGenerated", (_, manifest) => {
+      manifest.permissions ?? (manifest.permissions = []);
+      if (!manifest.permissions.includes("storage")) {
+        manifest.permissions.push("storage");
+      }
+    });
+    const wxtAnalyticsCode = [
+      `import { createAnalytics } from '${clientModuleId }';`,
+      `import { useAppConfig } from 'wxt/client';`,
+      ``,
+      `export const analytics = createAnalytics(useAppConfig().analytics);`,
+      ``
+    ].join("\n");
+    addAlias(wxt, "#analytics", wxtAnalyticsIndex);
+    wxt.hook("prepare:types", async (_, entries) => {
+      entries.push({
+        path: wxtAnalyticsIndex,
+        text: wxtAnalyticsCode
+      });
+    });
+    wxt.hook("entrypoints:resolved", (_, entrypoints) => {
+      const hasBackground = entrypoints.find(
+        (entry) => entry.type === "background"
+      );
+      if (!hasBackground) {
+        entrypoints.push({
+          type: "background",
+          inputPath: "virtual:user-background",
+          name: "background",
+          options: {},
+          outputDir: wxt.config.outDir,
+          skipped: false
+        });
+      }
+    });
+    addWxtPlugin(wxt, pluginModuleId);
+    addViteConfig(wxt, () => ({
+      optimizeDeps: {
+        // Ensure the "#analytics" import is processed by vite in the background plugin
+        exclude: ["@wxt-dev/analytics"],
+        // Ensure the CJS subdependency is preprocessed into ESM
+        include: ["@wxt-dev/analytics > ua-parser-js"]
+      }
+    }));
+  }
+});
+
+export { index as default };

package/dist/providers/google-analytics-4.d.mts

@@ -1,9 +1,9 @@
-import { b as AnalyticsProvider } from '../shared/analytics.2893a879.mjs';
+import { AnalyticsProvider } from '../types.mjs';
 
-interface GoogleAnalyticsProviderOptions {
+interface GoogleAnalytics4ProviderOptions {
     apiSecret: string;
     measurementId: string;
 }
-declare const googleAnalytics4: (options: GoogleAnalyticsProviderOptions) => AnalyticsProvider;
+declare const googleAnalytics4: (options: GoogleAnalytics4ProviderOptions) => AnalyticsProvider;
 
-export { type GoogleAnalyticsProviderOptions, googleAnalytics4 };
+export { type GoogleAnalytics4ProviderOptions, googleAnalytics4 };

package/dist/providers/google-analytics-4.d.ts

@@ -1,9 +1,9 @@
-import { b as AnalyticsProvider } from '../shared/analytics.2893a879.js';
+import { AnalyticsProvider } from '../types.js';
 
-interface GoogleAnalyticsProviderOptions {
+interface GoogleAnalytics4ProviderOptions {
     apiSecret: string;
     measurementId: string;
 }
-declare const googleAnalytics4: (options: GoogleAnalyticsProviderOptions) => AnalyticsProvider;
+declare const googleAnalytics4: (options: GoogleAnalytics4ProviderOptions) => AnalyticsProvider;
 
-export { type GoogleAnalyticsProviderOptions, googleAnalytics4 };
+export { type GoogleAnalytics4ProviderOptions, googleAnalytics4 };

package/dist/providers/google-analytics-4.mjs

@@ -1,56 +1,61 @@
+import { defineAnalyticsProvider } from '../index.mjs';
+import 'ua-parser-js';
+
 const DEFAULT_ENGAGEMENT_TIME_IN_MSEC = 100;
-const googleAnalytics4 = (options) => (_, config) => {
-  const send = async (data, eventName, eventProperties) => {
-    const url = new URL(
-      config?.debug ? "/debug/mp/collect" : "/mp/collect",
-      "https://www.google-analytics.com"
-    );
-    if (options.apiSecret)
-      url.searchParams.set("api_secret", options.apiSecret);
-    if (options.measurementId)
-      url.searchParams.set("measurement_id", options.measurementId);
-    const userProperties = {
-      language: data.meta.language,
-      screen: data.meta.screen,
-      ...data.user.properties
-    };
-    const mappedUserProperties = Object.fromEntries(
-      Object.entries(userProperties).map(([name, value]) => [
-        name,
-        value == null ? void 0 : { value }
-      ])
-    );
-    await fetch(url.href, {
-      method: "POST",
-      body: JSON.stringify({
-        client_id: data.user.id,
-        consent: {
-          ad_user_data: "DENIED",
-          ad_personalization: "DENIED"
-        },
-        user_properties: mappedUserProperties,
-        events: [
-          {
-            name: eventName,
-            params: {
-              session_id: data.meta.sessionId,
-              engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
-              ...eventProperties
+const googleAnalytics4 = defineAnalyticsProvider(
+  (_, config, options) => {
+    const send = async (data, eventName, eventProperties) => {
+      const url = new URL(
+        config?.debug ? "/debug/mp/collect" : "/mp/collect",
+        "https://www.google-analytics.com"
+      );
+      if (options.apiSecret)
+        url.searchParams.set("api_secret", options.apiSecret);
+      if (options.measurementId)
+        url.searchParams.set("measurement_id", options.measurementId);
+      const userProperties = {
+        language: data.meta.language,
+        screen: data.meta.screen,
+        ...data.user.properties
+      };
+      const mappedUserProperties = Object.fromEntries(
+        Object.entries(userProperties).map(([name, value]) => [
+          name,
+          value == null ? void 0 : { value }
+        ])
+      );
+      await fetch(url.href, {
+        method: "POST",
+        body: JSON.stringify({
+          client_id: data.user.id,
+          consent: {
+            ad_user_data: "DENIED",
+            ad_personalization: "DENIED"
+          },
+          user_properties: mappedUserProperties,
+          events: [
+            {
+              name: eventName,
+              params: {
+                session_id: data.meta.sessionId,
+                engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
+                ...eventProperties
+              }
             }
-          }
-        ]
-      })
-    });
-  };
-  return {
-    identify: () => Promise.resolve(),
-    // No-op, user data uploaded in page/track
-    page: (event) => send(event, "page_view", {
-      page_title: event.page.title,
-      page_location: event.page.location
-    }),
-    track: (event) => send(event, event.event.name, event.event.properties)
-  };
-};
+          ]
+        })
+      });
+    };
+    return {
+      identify: () => Promise.resolve(),
+      // No-op, user data uploaded in page/track
+      page: (event) => send(event, "page_view", {
+        page_title: event.page.title,
+        page_location: event.page.location
+      }),
+      track: (event) => send(event, event.event.name, event.event.properties)
+    };
+  }
+);
 
 export { googleAnalytics4 };

package/dist/providers/umami.d.mts

@@ -1,9 +1,9 @@
-import { b as AnalyticsProvider } from '../shared/analytics.2893a879.mjs';
+import { AnalyticsProvider } from '../types.mjs';
 
 interface UmamiProviderOptions {
-    baseUrl: string;
+    apiUrl: string;
     websiteId: string;
-    hostname: string;
+    domain: string;
 }
 declare const umami: (options: UmamiProviderOptions) => AnalyticsProvider;
 

package/dist/providers/umami.d.ts

@@ -1,9 +1,9 @@
-import { b as AnalyticsProvider } from '../shared/analytics.2893a879.js';
+import { AnalyticsProvider } from '../types.js';
 
 interface UmamiProviderOptions {
-    baseUrl: string;
+    apiUrl: string;
     websiteId: string;
-    hostname: string;
+    domain: string;
 }
 declare const umami: (options: UmamiProviderOptions) => AnalyticsProvider;
 

package/dist/providers/umami.mjs

@@ -1,44 +1,54 @@
-const umami = (options) => (analytics, config) => {
-  const send = (payload) => fetch(`${options.baseUrl}/api/send`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify({ type: "event", payload })
-  });
-  return {
-    identify: () => Promise.resolve(),
-    // No-op, user data uploaded in page/track
-    page: async (event) => {
-      await send({
-        name: "page_view",
-        website: options.websiteId,
-        url: event.page.url,
-        hostname: options.hostname,
-        language: event.meta.language ?? "",
-        referrer: event.meta.referrer ?? "",
-        screen: event.meta.screen ?? "",
-        title: event.page.title ?? "<blank>",
-        data: event.user.properties
-      });
-    },
-    track: async (event) => {
-      await send({
-        name: event.event.name,
-        website: options.websiteId,
-        url: event.meta.url ?? "/",
-        title: "<blank>",
-        hostname: options.hostname,
-        language: event.meta.language ?? "",
-        referrer: event.meta.referrer ?? "",
-        screen: event.meta.screen ?? "",
-        data: {
-          ...event.event.properties,
-          ...event.user.properties
-        }
+import { defineAnalyticsProvider } from '../index.mjs';
+import 'ua-parser-js';
+
+const umami = defineAnalyticsProvider(
+  (_, config, options) => {
+    const send = (payload) => {
+      if (config.debug) {
+        console.debug("[@wxt-dev/analytics] Sending event to Umami:", payload);
+      }
+      return fetch(`${options.apiUrl}/send`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ type: "event", payload })
       });
-    }
-  };
-};
+    };
+    return {
+      identify: () => Promise.resolve(),
+      // No-op, user data uploaded in page/track
+      page: async (event) => {
+        await send({
+          name: "page_view",
+          website: options.websiteId,
+          url: event.page.url,
+          hostname: options.domain,
+          language: event.meta.language ?? "",
+          referrer: event.meta.referrer ?? "",
+          screen: event.meta.screen ?? "",
+          title: event.page.title ?? "<blank>",
+          data: event.user.properties
+        });
+      },
+      track: async (event) => {
+        await send({
+          name: event.event.name,
+          website: options.websiteId,
+          url: event.meta.url ?? "/",
+          title: "<blank>",
+          hostname: options.domain,
+          language: event.meta.language ?? "",
+          referrer: event.meta.referrer ?? "",
+          screen: event.meta.screen ?? "",
+          data: {
+            ...event.event.properties,
+            ...event.user.properties
+          }
+        });
+      }
+    };
+  }
+);
 
 export { umami };

package/dist/{shared/analytics.2893a879.d.ts → types.d.mts}

@@ -1,13 +1,13 @@
 interface Analytics {
-    /** Report a page change */
+    /** Report a page change. */
     page: (url: string) => void;
-    /** Report a custom event */
+    /** Report a custom event. */
     track: (eventName: string, eventProperties?: Record<string, string>) => void;
-    /** Save information about the user */
+    /** Save information about the user. */
     identify: (userId: string, userProperties?: Record<string, string>) => void;
     /** Automatically setup and track user interactions, returning a function to remove any listeners that were setup. */
     autoTrack: (root: Document | ShadowRoot | Element) => () => void;
-    /** Calls `config.enabled.setValue` */
+    /** Calls `config.enabled.setValue`. */
     setEnabled: (enabled: boolean) => void;
 }
 interface AnalyticsConfig {
@@ -20,19 +20,20 @@ interface AnalyticsConfig {
      */
     debug?: boolean;
     /**
-     * Extension version, defaults to `browser.runtime.getManifest().version`.
+     * Your extension's version, reported alongside events.
+     * @default browser.runtime.getManifest().version`.
      */
     version?: string;
     /**
-     * Configure how the enabled flag is persisted. Defaults to using `""` in local extension storage.
+     * Configure how the enabled flag is persisted. Defaults to using `browser.storage.local`.
      */
     enabled?: AnalyticsStorageItem<boolean>;
     /**
-     * Configure how the user Id is persisted
+     * Configure how the user Id is persisted. Defaults to using `browser.storage.local`.
      */
     userId?: AnalyticsStorageItem<string>;
     /**
-     * Configure how user properties are persisted
+     * Configure how user properties are persisted. Defaults to using `browser.storage.local`.
      */
     userProperties?: AnalyticsStorageItem<Record<string, string>>;
 }
@@ -41,11 +42,11 @@ interface AnalyticsStorageItem<T> {
     setValue?: (newValue: T) => void | Promise<void>;
 }
 type AnalyticsProvider = (analytics: Analytics, config: AnalyticsConfig) => {
-    /** Upload a page view event */
+    /** Upload a page view event. */
     page: (event: AnalyticsPageViewEvent) => Promise<void>;
-    /** Upload a custom event */
+    /** Upload a custom event. */
     track: (event: AnalyticsTrackEvent) => Promise<void>;
-    /** Upload or save information about the user */
+    /** Upload information about the user. */
     identify: (event: BaseAnalyticsEvent) => Promise<void>;
 };
 interface BaseAnalyticsEvent {
@@ -56,11 +57,11 @@ interface BaseAnalyticsEvent {
     };
 }
 interface AnalyticsEventMetadata {
-    /** Identifier of the session the event was fired from */
+    /** Identifier of the session the event was fired from. */
     sessionId: number | undefined;
-    /** `Date.now()` of when the event was reported */
+    /** `Date.now()` of when the event was reported. */
     timestamp: number;
-    /** `"1920x1080"` */
+    /** Ex: `"1920x1080"`. */
     screen: string | undefined;
     /** `document.referrer` */
     referrer: string | undefined;
@@ -86,4 +87,4 @@ interface AnalyticsTrackEvent extends BaseAnalyticsEvent {
     };
 }
 
-export type { AnalyticsConfig as A, Analytics as a, AnalyticsProvider as b };
+export type { Analytics, AnalyticsConfig, AnalyticsEventMetadata, AnalyticsPageInfo, AnalyticsPageViewEvent, AnalyticsProvider, AnalyticsStorageItem, AnalyticsTrackEvent, BaseAnalyticsEvent };

package/dist/{shared/analytics.2893a879.d.mts → types.d.ts}

@@ -1,13 +1,13 @@
 interface Analytics {
-    /** Report a page change */
+    /** Report a page change. */
     page: (url: string) => void;
-    /** Report a custom event */
+    /** Report a custom event. */
     track: (eventName: string, eventProperties?: Record<string, string>) => void;
-    /** Save information about the user */
+    /** Save information about the user. */
     identify: (userId: string, userProperties?: Record<string, string>) => void;
     /** Automatically setup and track user interactions, returning a function to remove any listeners that were setup. */
     autoTrack: (root: Document | ShadowRoot | Element) => () => void;
-    /** Calls `config.enabled.setValue` */
+    /** Calls `config.enabled.setValue`. */
     setEnabled: (enabled: boolean) => void;
 }
 interface AnalyticsConfig {
@@ -20,19 +20,20 @@ interface AnalyticsConfig {
      */
     debug?: boolean;
     /**
-     * Extension version, defaults to `browser.runtime.getManifest().version`.
+     * Your extension's version, reported alongside events.
+     * @default browser.runtime.getManifest().version`.
      */
     version?: string;
     /**
-     * Configure how the enabled flag is persisted. Defaults to using `""` in local extension storage.
+     * Configure how the enabled flag is persisted. Defaults to using `browser.storage.local`.
      */
     enabled?: AnalyticsStorageItem<boolean>;
     /**
-     * Configure how the user Id is persisted
+     * Configure how the user Id is persisted. Defaults to using `browser.storage.local`.
      */
     userId?: AnalyticsStorageItem<string>;
     /**
-     * Configure how user properties are persisted
+     * Configure how user properties are persisted. Defaults to using `browser.storage.local`.
      */
     userProperties?: AnalyticsStorageItem<Record<string, string>>;
 }
@@ -41,11 +42,11 @@ interface AnalyticsStorageItem<T> {
     setValue?: (newValue: T) => void | Promise<void>;
 }
 type AnalyticsProvider = (analytics: Analytics, config: AnalyticsConfig) => {
-    /** Upload a page view event */
+    /** Upload a page view event. */
     page: (event: AnalyticsPageViewEvent) => Promise<void>;
-    /** Upload a custom event */
+    /** Upload a custom event. */
     track: (event: AnalyticsTrackEvent) => Promise<void>;
-    /** Upload or save information about the user */
+    /** Upload information about the user. */
     identify: (event: BaseAnalyticsEvent) => Promise<void>;
 };
 interface BaseAnalyticsEvent {
@@ -56,11 +57,11 @@ interface BaseAnalyticsEvent {
     };
 }
 interface AnalyticsEventMetadata {
-    /** Identifier of the session the event was fired from */
+    /** Identifier of the session the event was fired from. */
     sessionId: number | undefined;
-    /** `Date.now()` of when the event was reported */
+    /** `Date.now()` of when the event was reported. */
     timestamp: number;
-    /** `"1920x1080"` */
+    /** Ex: `"1920x1080"`. */
     screen: string | undefined;
     /** `document.referrer` */
     referrer: string | undefined;
@@ -86,4 +87,4 @@ interface AnalyticsTrackEvent extends BaseAnalyticsEvent {
     };
 }
 
-export type { AnalyticsConfig as A, Analytics as a, AnalyticsProvider as b };
+export type { Analytics, AnalyticsConfig, AnalyticsEventMetadata, AnalyticsPageInfo, AnalyticsPageViewEvent, AnalyticsProvider, AnalyticsStorageItem, AnalyticsTrackEvent, BaseAnalyticsEvent };

package/dist/types.mjs

@@ -0,0 +1 @@
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wxt-dev/analytics",
-  "version": "0.2.8",
+  "version": "0.4.1",
   "description": "Add analytics to your web extension",
   "repository": {
     "type": "git",
@@ -14,9 +14,16 @@
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
     },
-    "./client": {
-      "types": "./dist/client.d.mts",
-      "default": "./dist/client.mjs"
+    "./module": {
+      "types": "./dist/module.d.mts",
+      "default": "./dist/module.mjs"
+    },
+    "./background-plugin": {
+      "types": "./dist/background-plugin.d.mts",
+      "default": "./dist/background-plugin.mjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.mts"
     },
     "./providers/google-analytics-4": {
       "types": "./dist/providers/google-analytics-4.d.mts",
@@ -33,17 +40,16 @@
     "dist"
   ],
   "peerDependencies": {
-    "wxt": ">=0.19.9"
+    "wxt": ">=0.19.23"
   },
   "devDependencies": {
-    "@aklinker1/check": "^1.3.1",
+    "@aklinker1/check": "^1.4.5",
     "@types/chrome": "^0.0.268",
     "@types/ua-parser-js": "^0.7.39",
-    "prettier": "^3.3.2",
-    "publint": "^0.2.8",
-    "typescript": "^5.5.2",
+    "publint": "^0.2.12",
+    "typescript": "^5.6.3",
     "unbuild": "^2.0.0",
-    "wxt": "0.19.13"
+    "wxt": "0.19.23"
   },
   "dependencies": {
     "ua-parser-js": "^1.0.38"
@@ -51,7 +57,7 @@
   "scripts": {
     "dev": "buildc --deps-only -- wxt",
     "dev:build": "buildc --deps-only -- wxt build",
-    "check": "buildc --deps-only -- check",
+    "check": "pnpm build && check",
     "build": "buildc -- unbuild"
   }
 }

package/dist/client.d.mts

@@ -1,5 +0,0 @@
-import { A as AnalyticsConfig, a as Analytics } from './shared/analytics.2893a879.mjs';
-
-declare function createAnalytics(config?: AnalyticsConfig): Analytics;
-
-export { createAnalytics };

package/dist/client.d.ts

@@ -1,5 +0,0 @@
-import { A as AnalyticsConfig, a as Analytics } from './shared/analytics.2893a879.js';
-
-declare function createAnalytics(config?: AnalyticsConfig): Analytics;
-
-export { createAnalytics };