mytart 0.1.2 → 0.1.4

package/README.md

@@ -11,6 +11,7 @@
 - 🔷 **TypeScript-first**: precise typings, object-parameter style for great DX
 - 📦 **Dual ESM/CJS output**: works with `import` and `require`
 - 🪶 **Lightweight**: direct HTTP via axios, no SDK overhead
+- ⚡ **SPA-ready**: automatic page view tracking on route changes (Vercel Analytics)
 - ✅ **Node.js ≥ 18**
 
 ## Installation
@@ -89,11 +90,22 @@ await analytics.page({ url: 'https://example.com/pricing', name: 'Pricing' });
 ### Vercel Analytics
 
 ```typescript
-{ provider: 'vercel-analytics', analyticsId: 'YOUR_ANALYTICS_ID', apiUrl?: string }
+{ provider: 'vercel-analytics', analyticsId?: string, apiUrl?: string }
 ```
 
-`analyticsId` is your `VERCEL_ANALYTICS_ID` environment variable (or the ID in your Vercel project's Analytics settings).  
-For on-Vercel deployments you can override `apiUrl` to `/_vercel/insights/event`.
+**Auto-configuration**: When deployed on Vercel with Web Analytics enabled, `analyticsId` is automatically retrieved from `window.__VERCEL_ANALYTICS_ID__`. No configuration needed — just add the provider:
+
+```typescript
+// On Vercel — no config needed
+{ provider: 'vercel-analytics', enabled: true }
+
+// Self-hosted or offline — provide ID explicitly
+{ provider: 'vercel-analytics', analyticsId: 'YOUR_ANALYTICS_ID', enabled: true }
+```
+
+**SPA Support**: Page view tracking via `history.pushState` and `popstate` is enabled by default. Use `analytics.disableSPA()` to opt out.
+
+**Endpoints**: By default, events are sent to `https://vitals.vercel-insights.com/v1/vitals`. On Vercel infrastructure, set `apiUrl: '/_vercel/insights/event'` for optimal routing.
 
 > **Note**: Vercel Analytics does not support `identify()` — it returns an error result (privacy-first by design).
 
@@ -171,6 +183,14 @@ Remove a provider by name.
 
 Returns the list of active provider names.
 
+### `analytics.enableSPA(): void`
+
+Enable automatic SPA page view tracking. Automatically called on initialization for providers that support it (Vercel Analytics). Tracks page views on `history.pushState` and `popstate` events.
+
+### `analytics.disableSPA(): void`
+
+Disable automatic SPA page view tracking and clean up event listeners. Call this if you handle page views manually or are on a multi-page app.
+
 ### `TrackResult`
 
 Every method returns `Promise<TrackResult[]>` — one result per provider:

package/dist/index.d.mts

@@ -122,6 +122,15 @@ declare class Mytart {
     addProvider(config: ProviderConfig): void;
     removeProvider(name: string): void;
     getProviders(): string[];
+    /**
+     * Enable automatic SPA page view tracking for all supported providers.
+     * Should be called once in your app's entry point after initialization.
+     */
+    enableSPA(): void;
+    /**
+     * Disable SPA page view tracking and clean up event listeners.
+     */
+    disableSPA(): void;
 }
 
 declare abstract class BaseProvider {
@@ -206,11 +215,24 @@ declare class VercelAnalyticsProvider extends BaseProvider {
     private readonly config;
     private readonly http;
     private readonly endpoint;
+    private readonly spaListeners;
+    private spaEnabled;
     constructor(config: VercelAnalyticsConfig);
-    /** Check if Vercel analytics can be used (running on Vercel or analytics ID available). */
+    /**
+     * Check if Vercel analytics can be used.
+     * In browsers, checks for the injected global. In Node.js, also checks process.env.VERCEL.
+     */
     isAvailable(): boolean;
     /** Get the analytics ID, attempting to resolve from config or injected global. */
     private resolveAnalyticsId;
+    /**
+     * Enable automatic SPA page view tracking by listening to browser history changes.
+     * Call this once after initialization in your app's entry point.
+     * Uses `window.location.href` for URL and `document.referrer` for referrer.
+     */
+    enableSPA(): void;
+    /** Disable SPA tracking and clean up event listeners. */
+    disableSPA(): void;
     track({ event, properties, timestamp, context }: TrackOptions): Promise<TrackResult>;
     /**
      * Vercel Analytics is privacy-focused and does not support traditional user

package/dist/index.d.ts

@@ -122,6 +122,15 @@ declare class Mytart {
     addProvider(config: ProviderConfig): void;
     removeProvider(name: string): void;
     getProviders(): string[];
+    /**
+     * Enable automatic SPA page view tracking for all supported providers.
+     * Should be called once in your app's entry point after initialization.
+     */
+    enableSPA(): void;
+    /**
+     * Disable SPA page view tracking and clean up event listeners.
+     */
+    disableSPA(): void;
 }
 
 declare abstract class BaseProvider {
@@ -206,11 +215,24 @@ declare class VercelAnalyticsProvider extends BaseProvider {
     private readonly config;
     private readonly http;
     private readonly endpoint;
+    private readonly spaListeners;
+    private spaEnabled;
     constructor(config: VercelAnalyticsConfig);
-    /** Check if Vercel analytics can be used (running on Vercel or analytics ID available). */
+    /**
+     * Check if Vercel analytics can be used.
+     * In browsers, checks for the injected global. In Node.js, also checks process.env.VERCEL.
+     */
     isAvailable(): boolean;
     /** Get the analytics ID, attempting to resolve from config or injected global. */
     private resolveAnalyticsId;
+    /**
+     * Enable automatic SPA page view tracking by listening to browser history changes.
+     * Call this once after initialization in your app's entry point.
+     * Uses `window.location.href` for URL and `document.referrer` for referrer.
+     */
+    enableSPA(): void;
+    /** Disable SPA tracking and clean up event listeners. */
+    disableSPA(): void;
     track({ event, properties, timestamp, context }: TrackOptions): Promise<TrackResult>;
     /**
      * Vercel Analytics is privacy-focused and does not support traditional user

package/dist/index.js

@@ -624,24 +624,67 @@ var VercelAnalyticsProvider = class extends BaseProvider {
   constructor(config) {
     super();
     this.name = "vercel-analytics";
+    this.spaListeners = [];
+    this.spaEnabled = false;
     this.config = config;
     this.http = createHttpClient();
     this.endpoint = config.apiUrl ?? VERCEL_ENDPOINT;
   }
-  /** Check if Vercel analytics can be used (running on Vercel or analytics ID available). */
+  /**
+   * Check if Vercel analytics can be used.
+   * In browsers, checks for the injected global. In Node.js, also checks process.env.VERCEL.
+   */
   isAvailable() {
-    if (!isRunningOnVercel()) {
-      return false;
-    }
     if (this.config.analyticsId) {
       return true;
     }
+    if (isRunningOnVercel()) {
+      return true;
+    }
     return typeof getInjectedAnalyticsId() === "string";
   }
   /** Get the analytics ID, attempting to resolve from config or injected global. */
   resolveAnalyticsId() {
     return this.config.analyticsId ?? getInjectedAnalyticsId();
   }
+  /**
+   * Enable automatic SPA page view tracking by listening to browser history changes.
+   * Call this once after initialization in your app's entry point.
+   * Uses `window.location.href` for URL and `document.referrer` for referrer.
+   */
+  enableSPA() {
+    if (typeof window === "undefined" || this.spaEnabled) {
+      return;
+    }
+    this.spaEnabled = true;
+    const trackPageView = () => {
+      const url = window.location.href;
+      const referrer = document.referrer || void 0;
+      this.page({ name: "pageview", url, referrer }).catch(() => {
+      });
+    };
+    const originalPushState = window.history.pushState.bind(window.history);
+    const originalReplaceState = window.history.replaceState.bind(window.history);
+    window.history.pushState = function(...args) {
+      originalPushState(...args);
+      trackPageView();
+    };
+    window.history.replaceState = function(...args) {
+      originalReplaceState(...args);
+    };
+    window.addEventListener("popstate", trackPageView);
+    this.spaListeners.push(() => {
+      window.history.pushState = originalPushState;
+      window.history.replaceState = originalReplaceState;
+      window.removeEventListener("popstate", trackPageView);
+    });
+  }
+  /** Disable SPA tracking and clean up event listeners. */
+  disableSPA() {
+    this.spaListeners.forEach((cleanup) => cleanup());
+    this.spaListeners.length = 0;
+    this.spaEnabled = false;
+  }
   async track({ event, properties, timestamp, context }) {
     const analyticsId = this.resolveAnalyticsId();
     if (!analyticsId) {
@@ -766,6 +809,7 @@ var Mytart = class {
       }
       return true;
     });
+    this.enableSPA();
   }
   async track(options) {
     const enriched = {
@@ -799,6 +843,27 @@ var Mytart = class {
   getProviders() {
     return this.providers.map((p) => p.name);
   }
+  /**
+   * Enable automatic SPA page view tracking for all supported providers.
+   * Should be called once in your app's entry point after initialization.
+   */
+  enableSPA() {
+    for (const provider of this.providers) {
+      if (provider.name === "vercel-analytics") {
+        provider.enableSPA();
+      }
+    }
+  }
+  /**
+   * Disable SPA page view tracking and clean up event listeners.
+   */
+  disableSPA() {
+    for (const provider of this.providers) {
+      if (provider.name === "vercel-analytics") {
+        provider.disableSPA();
+      }
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -580,24 +580,67 @@ var VercelAnalyticsProvider = class extends BaseProvider {
   constructor(config) {
     super();
     this.name = "vercel-analytics";
+    this.spaListeners = [];
+    this.spaEnabled = false;
     this.config = config;
     this.http = createHttpClient();
     this.endpoint = config.apiUrl ?? VERCEL_ENDPOINT;
   }
-  /** Check if Vercel analytics can be used (running on Vercel or analytics ID available). */
+  /**
+   * Check if Vercel analytics can be used.
+   * In browsers, checks for the injected global. In Node.js, also checks process.env.VERCEL.
+   */
   isAvailable() {
-    if (!isRunningOnVercel()) {
-      return false;
-    }
     if (this.config.analyticsId) {
       return true;
     }
+    if (isRunningOnVercel()) {
+      return true;
+    }
     return typeof getInjectedAnalyticsId() === "string";
   }
   /** Get the analytics ID, attempting to resolve from config or injected global. */
   resolveAnalyticsId() {
     return this.config.analyticsId ?? getInjectedAnalyticsId();
   }
+  /**
+   * Enable automatic SPA page view tracking by listening to browser history changes.
+   * Call this once after initialization in your app's entry point.
+   * Uses `window.location.href` for URL and `document.referrer` for referrer.
+   */
+  enableSPA() {
+    if (typeof window === "undefined" || this.spaEnabled) {
+      return;
+    }
+    this.spaEnabled = true;
+    const trackPageView = () => {
+      const url = window.location.href;
+      const referrer = document.referrer || void 0;
+      this.page({ name: "pageview", url, referrer }).catch(() => {
+      });
+    };
+    const originalPushState = window.history.pushState.bind(window.history);
+    const originalReplaceState = window.history.replaceState.bind(window.history);
+    window.history.pushState = function(...args) {
+      originalPushState(...args);
+      trackPageView();
+    };
+    window.history.replaceState = function(...args) {
+      originalReplaceState(...args);
+    };
+    window.addEventListener("popstate", trackPageView);
+    this.spaListeners.push(() => {
+      window.history.pushState = originalPushState;
+      window.history.replaceState = originalReplaceState;
+      window.removeEventListener("popstate", trackPageView);
+    });
+  }
+  /** Disable SPA tracking and clean up event listeners. */
+  disableSPA() {
+    this.spaListeners.forEach((cleanup) => cleanup());
+    this.spaListeners.length = 0;
+    this.spaEnabled = false;
+  }
   async track({ event, properties, timestamp, context }) {
     const analyticsId = this.resolveAnalyticsId();
     if (!analyticsId) {
@@ -722,6 +765,7 @@ var Mytart = class {
       }
       return true;
     });
+    this.enableSPA();
   }
   async track(options) {
     const enriched = {
@@ -755,6 +799,27 @@ var Mytart = class {
   getProviders() {
     return this.providers.map((p) => p.name);
   }
+  /**
+   * Enable automatic SPA page view tracking for all supported providers.
+   * Should be called once in your app's entry point after initialization.
+   */
+  enableSPA() {
+    for (const provider of this.providers) {
+      if (provider.name === "vercel-analytics") {
+        provider.enableSPA();
+      }
+    }
+  }
+  /**
+   * Disable SPA page view tracking and clean up event listeners.
+   */
+  disableSPA() {
+    for (const provider of this.providers) {
+      if (provider.name === "vercel-analytics") {
+        provider.disableSPA();
+      }
+    }
+  }
 };
 export {
   AmplitudeProvider,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mytart",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Multi-Yield Tracking & Analytics Relay Tool — framework-agnostic analytics for any project",
   "keywords": [
     "analytics",