mytart 0.2.3 → 0.3.0

package/README.md

@@ -50,10 +50,42 @@ await analytics.page({ url: 'https://example.com/pricing', name: 'Pricing' });
 
 ### Google Analytics 4
 
+GA4 supports two modes via the `appType` option:
+
+#### Server mode (default)
+
+Uses the [GA4 Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4) — direct HTTP calls, no browser APIs. Use this for Node.js, API routes, serverless functions, etc.
+
+```typescript
+{
+  provider: 'google-analytics',
+  measurementId: 'G-XXXXXXXXXX',
+  apiSecret: 'YOUR_SECRET',
+  enabled: true,
+  // appType defaults to 'server'
+}
+```
+
+#### Browser mode
+
+Injects Google's official [gtag.js snippet](https://developers.google.com/tag-platform/gtagjs) into the page. Use this for client-side tracking in any framework (React, Vue, Svelte, plain HTML, etc.). No `apiSecret` needed.
+
 ```typescript
-{ provider: 'google-analytics', measurementId: 'G-XXXXXXXXXX', apiSecret: 'YOUR_SECRET', debug?: boolean }
+{
+  provider: 'google-analytics',
+  measurementId: 'G-XXXXXXXXXX',
+  appType: 'browser',
+  enabled: true,
+}
 ```
 
+When `appType: 'browser'` is set:
+
+- The gtag.js script is loaded once on the first `track()`, `identify()`, or `page()` call
+- All calls use the standard `gtag()` API — compatible with Google Tag Tester and Tag Assistant
+- SSR-safe: silently succeeds when `window` is undefined (e.g. during server-side rendering)
+- `apiSecret` is not required (and not used)
+
 ### Mixpanel
 
 ```typescript
@@ -187,7 +219,7 @@ All types are exported:
 ```typescript
 import type {
   MytartConfig, BaseProviderConfig, ProviderConfig, TrackOptions, IdentifyOptions, PageOptions,
-  TrackResult, MytartError, EventContext, ProviderName,
+  TrackResult, MytartError, EventContext, ProviderName, GoogleAnalyticsAppType,
   GoogleAnalyticsConfig, MixpanelConfig, SegmentConfig,
   AmplitudeConfig, PlausibleConfig, PostHogConfig,
 } from 'mytart';

package/dist/index.d.mts

@@ -126,34 +126,44 @@ declare global {
         dataLayer: unknown[];
     }
 }
-interface GtagFn {
-    (command: 'config', measurementId: string, config?: GtagConfig): void;
-    (command: 'event', eventName: string, params?: Record<string, unknown>): void;
-    (command: 'set', config: Record<string, unknown>): void;
-    (command: string, ...args: unknown[]): void;
-}
-interface GtagConfig {
-    send_page_view?: boolean;
-    page_title?: string;
-    page_location?: string;
-    page_referrer?: string;
-    user_id?: string;
-    [key: string]: unknown;
-}
+type GtagFn = (...args: unknown[]) => void;
 declare class GoogleAnalyticsProvider extends BaseProvider {
     readonly name = "google-analytics";
     private readonly config;
     private readonly http;
     private readonly endpoint;
     private readonly isBrowser;
-    private gtagInitialized;
+    private gtagReady;
     constructor(config: GoogleAnalyticsConfig);
-    private ensureGtagLoaded;
-    private injectGtagScript;
-    private buildGtagResult;
+    /**
+     * Initializes the gtag.js snippet exactly as Google's official documentation
+     * specifies. This mirrors the standard snippet:
+     *
+     *   <script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
+     *   <script>
+     *     window.dataLayer = window.dataLayer || [];
+     *     function gtag(){dataLayer.push(arguments);}
+     *     gtag('js', new Date());
+     *     gtag('config', 'TAG_ID');
+     *   </script>
+     *
+     * Key details:
+     * - The script URL MUST include ?id=TAG_ID for Google Tag Tester detection
+     * - dataLayer and the gtag shim are set up BEFORE the script loads
+     * - gtag('js') and gtag('config') are called synchronously — they queue
+     *   into dataLayer and are processed once the real script loads
+     * - The returned promise resolves when the script finishes loading
+     */
+    private initGtag;
+    /**
+     * Ensures gtag is initialized exactly once. Subsequent calls return the
+     * same promise so the script is never injected twice.
+     */
+    private ensureGtag;
     private trackBrowser;
     private identifyBrowser;
     private pageBrowser;
+    private buildGtagResult;
     track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
     identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
     page({ name, url, referrer, userId, anonymousId }: PageOptions): Promise<TrackResult>;

package/dist/index.d.ts

@@ -126,34 +126,44 @@ declare global {
         dataLayer: unknown[];
     }
 }
-interface GtagFn {
-    (command: 'config', measurementId: string, config?: GtagConfig): void;
-    (command: 'event', eventName: string, params?: Record<string, unknown>): void;
-    (command: 'set', config: Record<string, unknown>): void;
-    (command: string, ...args: unknown[]): void;
-}
-interface GtagConfig {
-    send_page_view?: boolean;
-    page_title?: string;
-    page_location?: string;
-    page_referrer?: string;
-    user_id?: string;
-    [key: string]: unknown;
-}
+type GtagFn = (...args: unknown[]) => void;
 declare class GoogleAnalyticsProvider extends BaseProvider {
     readonly name = "google-analytics";
     private readonly config;
     private readonly http;
     private readonly endpoint;
     private readonly isBrowser;
-    private gtagInitialized;
+    private gtagReady;
     constructor(config: GoogleAnalyticsConfig);
-    private ensureGtagLoaded;
-    private injectGtagScript;
-    private buildGtagResult;
+    /**
+     * Initializes the gtag.js snippet exactly as Google's official documentation
+     * specifies. This mirrors the standard snippet:
+     *
+     *   <script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
+     *   <script>
+     *     window.dataLayer = window.dataLayer || [];
+     *     function gtag(){dataLayer.push(arguments);}
+     *     gtag('js', new Date());
+     *     gtag('config', 'TAG_ID');
+     *   </script>
+     *
+     * Key details:
+     * - The script URL MUST include ?id=TAG_ID for Google Tag Tester detection
+     * - dataLayer and the gtag shim are set up BEFORE the script loads
+     * - gtag('js') and gtag('config') are called synchronously — they queue
+     *   into dataLayer and are processed once the real script loads
+     * - The returned promise resolves when the script finishes loading
+     */
+    private initGtag;
+    /**
+     * Ensures gtag is initialized exactly once. Subsequent calls return the
+     * same promise so the script is never injected twice.
+     */
+    private ensureGtag;
     private trackBrowser;
     private identifyBrowser;
     private pageBrowser;
+    private buildGtagResult;
     track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
     identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
     page({ name, url, referrer, userId, anonymousId }: PageOptions): Promise<TrackResult>;

package/dist/index.js

@@ -82,73 +82,87 @@ function isAxiosError(error) {
 // src/providers/google-analytics.ts
 var GA4_ENDPOINT = "https://www.google-analytics.com/mp/collect";
 var GA4_DEBUG_ENDPOINT = "https://www.google-analytics.com/debug/mp/collect";
-var GTAG_URL = "https://www.googletagmanager.com/gtag/js";
+var GTAG_SCRIPT_URL = "https://www.googletagmanager.com/gtag/js";
 var GoogleAnalyticsProvider = class extends BaseProvider {
   constructor(config) {
     super();
     this.name = "google-analytics";
-    this.gtagInitialized = false;
+    this.gtagReady = null;
     this.config = config;
     this.http = createHttpClient();
     this.endpoint = config.debug ? GA4_DEBUG_ENDPOINT : GA4_ENDPOINT;
     this.isBrowser = config.appType === "browser";
   }
-  async ensureGtagLoaded() {
-    if (typeof window === "undefined") {
-      return;
-    }
-    if (typeof window.gtag === "function") {
-      return;
+  /**
+   * Initializes the gtag.js snippet exactly as Google's official documentation
+   * specifies. This mirrors the standard snippet:
+   *
+   *   <script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
+   *   <script>
+   *     window.dataLayer = window.dataLayer || [];
+   *     function gtag(){dataLayer.push(arguments);}
+   *     gtag('js', new Date());
+   *     gtag('config', 'TAG_ID');
+   *   </script>
+   *
+   * Key details:
+   * - The script URL MUST include ?id=TAG_ID for Google Tag Tester detection
+   * - dataLayer and the gtag shim are set up BEFORE the script loads
+   * - gtag('js') and gtag('config') are called synchronously — they queue
+   *   into dataLayer and are processed once the real script loads
+   * - The returned promise resolves when the script finishes loading
+   */
+  initGtag() {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return Promise.resolve();
     }
-    await this.injectGtagScript();
-  }
-  injectGtagScript() {
+    window.dataLayer = window.dataLayer || [];
+    window.gtag = function gtag() {
+      window.dataLayer.push(arguments);
+    };
+    window.gtag("js", /* @__PURE__ */ new Date());
+    window.gtag("config", this.config.measurementId);
     return new Promise((resolve) => {
-      window.dataLayer = window.dataLayer || [];
-      window.gtag = window.gtag || function gtag(...args) {
-        window.dataLayer.push(args);
-      };
       const script = document.createElement("script");
       script.async = true;
-      script.src = `${GTAG_URL}?id=${this.config.measurementId}`;
-      script.onload = () => {
-        window.gtag("js", /* @__PURE__ */ new Date());
-        window.gtag("config", this.config.measurementId);
-        resolve();
-      };
+      script.src = `${GTAG_SCRIPT_URL}?id=${this.config.measurementId}`;
+      script.onload = () => resolve();
       script.onerror = () => resolve();
-      const firstScript = document.getElementsByTagName("script")[0];
-      firstScript.parentNode?.insertBefore(script, firstScript);
+      document.head.appendChild(script);
     });
   }
-  buildGtagResult() {
-    return {
-      provider: this.name,
-      success: true,
-      statusCode: 200
-    };
+  /**
+   * Ensures gtag is initialized exactly once. Subsequent calls return the
+   * same promise so the script is never injected twice.
+   */
+  ensureGtag() {
+    if (!this.gtagReady) {
+      this.gtagReady = this.initGtag();
+    }
+    return this.gtagReady;
   }
+  // ---------------------------------------------------------------------------
+  // Browser mode methods — delegate to gtag()
+  // ---------------------------------------------------------------------------
   async trackBrowser({ event, properties, userId }) {
     if (typeof window === "undefined") {
       return this.buildGtagResult();
     }
-    await this.ensureGtagLoaded();
+    await this.ensureGtag();
     if (userId) {
       window.gtag("set", { user_id: userId });
     }
-    window.gtag("event", event, properties || {});
+    window.gtag("event", event, properties ?? {});
     return this.buildGtagResult();
   }
   async identifyBrowser({ userId, traits }) {
     if (typeof window === "undefined") {
       return this.buildGtagResult();
     }
-    await this.ensureGtagLoaded();
+    await this.ensureGtag();
     window.gtag("set", { user_id: userId });
     if (traits) {
-      Object.entries(traits).forEach(([key, value]) => {
-        window.gtag("set", { [key]: value });
-      });
+      window.gtag("set", "user_properties", traits);
     }
     return this.buildGtagResult();
   }
@@ -156,31 +170,39 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
     if (typeof window === "undefined") {
       return this.buildGtagResult();
     }
-    await this.ensureGtagLoaded();
-    const config = {
-      page_title: name,
-      page_location: url,
-      page_referrer: referrer,
-      send_page_view: true
-    };
+    await this.ensureGtag();
     if (userId) {
-      config.user_id = userId;
+      window.gtag("set", { user_id: userId });
     }
-    window.gtag("config", this.config.measurementId, config);
+    window.gtag("event", "page_view", {
+      page_title: name,
+      page_location: url,
+      page_referrer: referrer
+    });
     return this.buildGtagResult();
   }
+  buildGtagResult() {
+    return {
+      provider: this.name,
+      success: true,
+      statusCode: 200
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Public API — routes to browser or server mode
+  // ---------------------------------------------------------------------------
   async track({ event, properties, userId, anonymousId, timestamp }) {
     if (this.isBrowser) {
       return this.trackBrowser({ event, properties, userId, anonymousId, timestamp });
     }
     try {
-      const client_id = anonymousId ?? this.config.clientId ?? "anonymous";
+      const clientId = anonymousId ?? this.config.clientId ?? "anonymous";
       const params = { ...properties };
       if (timestamp) {
         params["timestamp_micros"] = timestamp.getTime() * 1e3;
       }
       const body = {
-        client_id,
+        client_id: clientId,
         events: [{ name: event, params }]
       };
       if (userId) {

package/dist/index.mjs

@@ -39,73 +39,87 @@ function isAxiosError(error) {
 // src/providers/google-analytics.ts
 var GA4_ENDPOINT = "https://www.google-analytics.com/mp/collect";
 var GA4_DEBUG_ENDPOINT = "https://www.google-analytics.com/debug/mp/collect";
-var GTAG_URL = "https://www.googletagmanager.com/gtag/js";
+var GTAG_SCRIPT_URL = "https://www.googletagmanager.com/gtag/js";
 var GoogleAnalyticsProvider = class extends BaseProvider {
   constructor(config) {
     super();
     this.name = "google-analytics";
-    this.gtagInitialized = false;
+    this.gtagReady = null;
     this.config = config;
     this.http = createHttpClient();
     this.endpoint = config.debug ? GA4_DEBUG_ENDPOINT : GA4_ENDPOINT;
     this.isBrowser = config.appType === "browser";
   }
-  async ensureGtagLoaded() {
-    if (typeof window === "undefined") {
-      return;
-    }
-    if (typeof window.gtag === "function") {
-      return;
+  /**
+   * Initializes the gtag.js snippet exactly as Google's official documentation
+   * specifies. This mirrors the standard snippet:
+   *
+   *   <script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
+   *   <script>
+   *     window.dataLayer = window.dataLayer || [];
+   *     function gtag(){dataLayer.push(arguments);}
+   *     gtag('js', new Date());
+   *     gtag('config', 'TAG_ID');
+   *   </script>
+   *
+   * Key details:
+   * - The script URL MUST include ?id=TAG_ID for Google Tag Tester detection
+   * - dataLayer and the gtag shim are set up BEFORE the script loads
+   * - gtag('js') and gtag('config') are called synchronously — they queue
+   *   into dataLayer and are processed once the real script loads
+   * - The returned promise resolves when the script finishes loading
+   */
+  initGtag() {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return Promise.resolve();
     }
-    await this.injectGtagScript();
-  }
-  injectGtagScript() {
+    window.dataLayer = window.dataLayer || [];
+    window.gtag = function gtag() {
+      window.dataLayer.push(arguments);
+    };
+    window.gtag("js", /* @__PURE__ */ new Date());
+    window.gtag("config", this.config.measurementId);
     return new Promise((resolve) => {
-      window.dataLayer = window.dataLayer || [];
-      window.gtag = window.gtag || function gtag(...args) {
-        window.dataLayer.push(args);
-      };
       const script = document.createElement("script");
       script.async = true;
-      script.src = `${GTAG_URL}?id=${this.config.measurementId}`;
-      script.onload = () => {
-        window.gtag("js", /* @__PURE__ */ new Date());
-        window.gtag("config", this.config.measurementId);
-        resolve();
-      };
+      script.src = `${GTAG_SCRIPT_URL}?id=${this.config.measurementId}`;
+      script.onload = () => resolve();
       script.onerror = () => resolve();
-      const firstScript = document.getElementsByTagName("script")[0];
-      firstScript.parentNode?.insertBefore(script, firstScript);
+      document.head.appendChild(script);
     });
   }
-  buildGtagResult() {
-    return {
-      provider: this.name,
-      success: true,
-      statusCode: 200
-    };
+  /**
+   * Ensures gtag is initialized exactly once. Subsequent calls return the
+   * same promise so the script is never injected twice.
+   */
+  ensureGtag() {
+    if (!this.gtagReady) {
+      this.gtagReady = this.initGtag();
+    }
+    return this.gtagReady;
   }
+  // ---------------------------------------------------------------------------
+  // Browser mode methods — delegate to gtag()
+  // ---------------------------------------------------------------------------
   async trackBrowser({ event, properties, userId }) {
     if (typeof window === "undefined") {
       return this.buildGtagResult();
     }
-    await this.ensureGtagLoaded();
+    await this.ensureGtag();
     if (userId) {
       window.gtag("set", { user_id: userId });
     }
-    window.gtag("event", event, properties || {});
+    window.gtag("event", event, properties ?? {});
     return this.buildGtagResult();
   }
   async identifyBrowser({ userId, traits }) {
     if (typeof window === "undefined") {
       return this.buildGtagResult();
     }
-    await this.ensureGtagLoaded();
+    await this.ensureGtag();
     window.gtag("set", { user_id: userId });
     if (traits) {
-      Object.entries(traits).forEach(([key, value]) => {
-        window.gtag("set", { [key]: value });
-      });
+      window.gtag("set", "user_properties", traits);
     }
     return this.buildGtagResult();
   }
@@ -113,31 +127,39 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
     if (typeof window === "undefined") {
       return this.buildGtagResult();
     }
-    await this.ensureGtagLoaded();
-    const config = {
-      page_title: name,
-      page_location: url,
-      page_referrer: referrer,
-      send_page_view: true
-    };
+    await this.ensureGtag();
     if (userId) {
-      config.user_id = userId;
+      window.gtag("set", { user_id: userId });
     }
-    window.gtag("config", this.config.measurementId, config);
+    window.gtag("event", "page_view", {
+      page_title: name,
+      page_location: url,
+      page_referrer: referrer
+    });
     return this.buildGtagResult();
   }
+  buildGtagResult() {
+    return {
+      provider: this.name,
+      success: true,
+      statusCode: 200
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Public API — routes to browser or server mode
+  // ---------------------------------------------------------------------------
   async track({ event, properties, userId, anonymousId, timestamp }) {
     if (this.isBrowser) {
       return this.trackBrowser({ event, properties, userId, anonymousId, timestamp });
     }
     try {
-      const client_id = anonymousId ?? this.config.clientId ?? "anonymous";
+      const clientId = anonymousId ?? this.config.clientId ?? "anonymous";
       const params = { ...properties };
       if (timestamp) {
         params["timestamp_micros"] = timestamp.getTime() * 1e3;
       }
       const body = {
-        client_id,
+        client_id: clientId,
         events: [{ name: event, params }]
       };
       if (userId) {

package/package.json

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