mytart 0.2.4 → 0.4.0

package/README.md

@@ -50,10 +50,100 @@ 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',
+  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)
+
+#### Google Signals (demographics)
+
+To enable demographic data (age, gender, interests) in GA4 reports, set `signals: true`:
+
 ```typescript
-{ provider: 'google-analytics', measurementId: 'G-XXXXXXXXXX', apiSecret: 'YOUR_SECRET', debug?: boolean }
+{
+  provider: 'google-analytics',
+  measurementId: 'G-XXXXXXXXXX',
+  appType: 'browser',
+  enabled: true,
+  signals: true,
+}
 ```
 
+This does two things automatically:
+
+1. Passes `allow_google_signals: true` and `allow_ad_personalization_signals: true` to `gtag('config')`
+2. Sets Consent Mode v2 defaults granting `ad_personalization`, `ad_user_data`, `ad_storage`, and `analytics_storage`
+
+Set `signals: false` to explicitly disable Google Signals. Omit the flag entirely to use Google's default behaviour.
+
+> **Note**: You must also enable Google Signals in the GA4 admin panel (Admin > Data Settings > Data Collection) for demographic data to appear.
+
+#### Consent Mode v2
+
+For GDPR/privacy compliance you can control Consent Mode v2 directly. Use `defaultConsent` to set the initial consent state (emitted before `gtag('config')`), and `updateConsent()` to change it at runtime when the user interacts with a cookie banner.
+
+```typescript
+const analytics = new Mytart({
+  providers: [{
+    provider: 'google-analytics',
+    measurementId: 'G-XXXXXXXXXX',
+    appType: 'browser',
+    enabled: true,
+    signals: true,
+    defaultConsent: {
+      ad_storage: 'denied',
+      analytics_storage: 'denied',
+      ad_user_data: 'denied',
+      ad_personalization: 'denied',
+    },
+    consentWaitForUpdate: 500, // wait 500ms for consent banner
+  }],
+});
+
+// After the user accepts the cookie banner:
+await analytics.updateConsent({
+  ad_storage: 'granted',
+  analytics_storage: 'granted',
+  ad_user_data: 'granted',
+  ad_personalization: 'granted',
+});
+```
+
+When both `signals: true` and `defaultConsent` are set, the explicit `defaultConsent` takes precedence over the auto-consent that `signals` would generate. This lets you combine `signals: true` (for the config flags) with a GDPR-safe denied-by-default consent flow.
+
+Consent Mode is a no-op in server mode (the Measurement Protocol does not support it).
+
 ### Mixpanel
 
 ```typescript
@@ -148,6 +238,22 @@ interface PageOptions {
 }
 ```
 
+### `analytics.updateConsent(consent: ConsentSettings): Promise<void>`
+
+Updates Google Consent Mode v2 state at runtime. Call this when the user interacts with a cookie/consent banner. Only affects Google Analytics in browser mode; all other providers ignore it.
+
+```typescript
+interface ConsentSettings {
+  ad_storage?: 'granted' | 'denied';
+  analytics_storage?: 'granted' | 'denied';
+  ad_user_data?: 'granted' | 'denied';
+  ad_personalization?: 'granted' | 'denied';
+  functionality_storage?: 'granted' | 'denied';
+  personalization_storage?: 'granted' | 'denied';
+  security_storage?: 'granted' | 'denied';
+}
+```
+
 ### `analytics.addProvider(config: ProviderConfig): void`
 
 Dynamically add a provider at runtime.
@@ -187,8 +293,8 @@ All types are exported:
 ```typescript
 import type {
   MytartConfig, BaseProviderConfig, ProviderConfig, TrackOptions, IdentifyOptions, PageOptions,
-  TrackResult, MytartError, EventContext, ProviderName,
-  GoogleAnalyticsConfig, MixpanelConfig, SegmentConfig,
+  TrackResult, MytartError, EventContext, ProviderName, GoogleAnalyticsAppType,
+  GoogleAnalyticsConfig, ConsentSettings, ConsentState, MixpanelConfig, SegmentConfig,
   AmplitudeConfig, PlausibleConfig, PostHogConfig,
 } from 'mytart';
 ```

package/dist/index.d.mts

@@ -8,6 +8,33 @@ interface BaseProviderConfig {
     /** Whether this provider is active. Defaults to `false` when omitted. */
     enabled?: boolean;
 }
+type ConsentState = 'granted' | 'denied';
+/**
+ * Google Consent Mode v2 settings.
+ * Controls how Google tags behave based on user consent.
+ *
+ * Key fields for Google Signals demographics (age, gender, interests):
+ * - `ad_personalization` — must be `'granted'` for Google Signals to attribute
+ *   demographic data to sessions.
+ * - `ad_user_data` — must be `'granted'` for user data to be sent to Google
+ *   for advertising purposes.
+ */
+interface ConsentSettings {
+    /** Controls storage of advertising-related cookies. */
+    ad_storage?: ConsentState;
+    /** Controls storage of analytics-related cookies. */
+    analytics_storage?: ConsentState;
+    /** Controls whether user data can be sent to Google for advertising. */
+    ad_user_data?: ConsentState;
+    /** Controls whether data can be used for personalized advertising. */
+    ad_personalization?: ConsentState;
+    /** Controls storage for functional purposes (e.g. language settings). */
+    functionality_storage?: ConsentState;
+    /** Controls storage for personalization (e.g. video recommendations). */
+    personalization_storage?: ConsentState;
+    /** Controls storage for security purposes (e.g. authentication). */
+    security_storage?: ConsentState;
+}
 type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog';
 type GoogleAnalyticsAppType = 'browser' | 'server';
 interface GoogleAnalyticsConfig extends BaseProviderConfig {
@@ -17,6 +44,44 @@ interface GoogleAnalyticsConfig extends BaseProviderConfig {
     clientId?: string;
     debug?: boolean;
     appType?: GoogleAnalyticsAppType;
+    /**
+     * Default consent state set before gtag('config'). In browser mode this
+     * emits `gtag('consent', 'default', ...)` so Google tags respect user
+     * consent from the very first hit. Use `Mytart.updateConsent()` to change
+     * consent at runtime (e.g. after a cookie banner interaction).
+     *
+     * For Google Signals demographics, `ad_personalization` and `ad_user_data`
+     * must eventually be set to `'granted'`.
+     */
+    defaultConsent?: ConsentSettings;
+    /**
+     * When `true`, sets `wait_for_update` (in milliseconds) on the default
+     * consent command. This tells Google tags to wait the specified number of
+     * milliseconds for a consent update before sending the first hit. Useful
+     * when a consent management platform loads asynchronously.
+     * Defaults to `undefined` (no wait).
+     */
+    consentWaitForUpdate?: number;
+    /**
+     * Convenience flag to enable or disable Google Signals for demographics
+     * (age, gender, interests).
+     *
+     * - `true`  — passes `allow_google_signals: true` and
+     *   `allow_ad_personalization_signals: true` in the `gtag('config')`
+     *   call. If `defaultConsent` is not explicitly set, automatically
+     *   configures Consent Mode v2 to grant `ad_personalization`,
+     *   `ad_user_data`, `ad_storage`, and `analytics_storage`.
+     * - `false` — passes `allow_google_signals: false` and
+     *   `allow_ad_personalization_signals: false` to explicitly disable
+     *   Google Signals.
+     * - `undefined` (default) — uses Google's default behaviour (Signals
+     *   enabled when the GA4 property has it turned on in Admin).
+     *
+     * **Note**: Google Signals must also be enabled in the GA4 admin panel
+     * (Admin › Data Settings › Data Collection) for demographic data to
+     * appear. This flag controls the client-side consent and config only.
+     */
+    signals?: boolean;
 }
 interface MixpanelConfig extends BaseProviderConfig {
     provider: 'mixpanel';
@@ -106,6 +171,16 @@ declare class Mytart {
     track(options: TrackOptions): Promise<TrackResult[]>;
     identify(options: IdentifyOptions): Promise<TrackResult[]>;
     page(options: PageOptions): Promise<TrackResult[]>;
+    /**
+     * Update consent state across all providers that support consent management.
+     * Currently this is meaningful for Google Analytics (Consent Mode v2) in
+     * browser mode. Call this when the user interacts with a cookie/consent
+     * banner.
+     *
+     * To enable Google Signals demographics (age, gender, interests), grant
+     * at least `ad_personalization` and `ad_user_data`.
+     */
+    updateConsent(consent: ConsentSettings): Promise<void>;
     addProvider(config: ProviderConfig): void;
     removeProvider(name: string): void;
     getProviders(): string[];
@@ -116,6 +191,11 @@ declare abstract class BaseProvider {
     abstract track(options: TrackOptions): Promise<TrackResult>;
     abstract identify(options: IdentifyOptions): Promise<TrackResult>;
     abstract page(options: PageOptions): Promise<TrackResult>;
+    /**
+     * Update consent state. Only meaningful for providers that support consent
+     * management (e.g. Google Analytics Consent Mode v2). Default is a no-op.
+     */
+    updateConsent(_consent: ConsentSettings): Promise<void>;
     protected buildError(message: string, code: string, originalError?: unknown): TrackResult;
     protected buildSuccess(statusCode?: number): TrackResult;
 }
@@ -126,34 +206,60 @@ 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>
+     *
+     * When `defaultConsent` is configured, a `gtag('consent', 'default', ...)`
+     * call is emitted **before** `gtag('js')` and `gtag('config')`, as required
+     * by Google's Consent Mode v2 specification.
+     *
+     * 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;
+    /**
+     * Updates the consent state at runtime. In browser mode this emits
+     * `gtag('consent', 'update', ...)`. Call this when the user interacts
+     * with a cookie/consent banner.
+     *
+     * To enable Google Signals demographics (age, gender, interests), grant
+     * at least `ad_personalization` and `ad_user_data`.
+     *
+     * In server mode this is a no-op — the Measurement Protocol does not
+     * support Consent Mode.
+     */
+    updateConsent(consent: ConsentSettings): Promise<void>;
     track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
     identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
     page({ name, url, referrer, userId, anonymousId }: PageOptions): Promise<TrackResult>;
@@ -216,4 +322,4 @@ declare class PostHogProvider extends BaseProvider {
     page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
 }
 
-export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };

package/dist/index.d.ts

@@ -8,6 +8,33 @@ interface BaseProviderConfig {
     /** Whether this provider is active. Defaults to `false` when omitted. */
     enabled?: boolean;
 }
+type ConsentState = 'granted' | 'denied';
+/**
+ * Google Consent Mode v2 settings.
+ * Controls how Google tags behave based on user consent.
+ *
+ * Key fields for Google Signals demographics (age, gender, interests):
+ * - `ad_personalization` — must be `'granted'` for Google Signals to attribute
+ *   demographic data to sessions.
+ * - `ad_user_data` — must be `'granted'` for user data to be sent to Google
+ *   for advertising purposes.
+ */
+interface ConsentSettings {
+    /** Controls storage of advertising-related cookies. */
+    ad_storage?: ConsentState;
+    /** Controls storage of analytics-related cookies. */
+    analytics_storage?: ConsentState;
+    /** Controls whether user data can be sent to Google for advertising. */
+    ad_user_data?: ConsentState;
+    /** Controls whether data can be used for personalized advertising. */
+    ad_personalization?: ConsentState;
+    /** Controls storage for functional purposes (e.g. language settings). */
+    functionality_storage?: ConsentState;
+    /** Controls storage for personalization (e.g. video recommendations). */
+    personalization_storage?: ConsentState;
+    /** Controls storage for security purposes (e.g. authentication). */
+    security_storage?: ConsentState;
+}
 type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog';
 type GoogleAnalyticsAppType = 'browser' | 'server';
 interface GoogleAnalyticsConfig extends BaseProviderConfig {
@@ -17,6 +44,44 @@ interface GoogleAnalyticsConfig extends BaseProviderConfig {
     clientId?: string;
     debug?: boolean;
     appType?: GoogleAnalyticsAppType;
+    /**
+     * Default consent state set before gtag('config'). In browser mode this
+     * emits `gtag('consent', 'default', ...)` so Google tags respect user
+     * consent from the very first hit. Use `Mytart.updateConsent()` to change
+     * consent at runtime (e.g. after a cookie banner interaction).
+     *
+     * For Google Signals demographics, `ad_personalization` and `ad_user_data`
+     * must eventually be set to `'granted'`.
+     */
+    defaultConsent?: ConsentSettings;
+    /**
+     * When `true`, sets `wait_for_update` (in milliseconds) on the default
+     * consent command. This tells Google tags to wait the specified number of
+     * milliseconds for a consent update before sending the first hit. Useful
+     * when a consent management platform loads asynchronously.
+     * Defaults to `undefined` (no wait).
+     */
+    consentWaitForUpdate?: number;
+    /**
+     * Convenience flag to enable or disable Google Signals for demographics
+     * (age, gender, interests).
+     *
+     * - `true`  — passes `allow_google_signals: true` and
+     *   `allow_ad_personalization_signals: true` in the `gtag('config')`
+     *   call. If `defaultConsent` is not explicitly set, automatically
+     *   configures Consent Mode v2 to grant `ad_personalization`,
+     *   `ad_user_data`, `ad_storage`, and `analytics_storage`.
+     * - `false` — passes `allow_google_signals: false` and
+     *   `allow_ad_personalization_signals: false` to explicitly disable
+     *   Google Signals.
+     * - `undefined` (default) — uses Google's default behaviour (Signals
+     *   enabled when the GA4 property has it turned on in Admin).
+     *
+     * **Note**: Google Signals must also be enabled in the GA4 admin panel
+     * (Admin › Data Settings › Data Collection) for demographic data to
+     * appear. This flag controls the client-side consent and config only.
+     */
+    signals?: boolean;
 }
 interface MixpanelConfig extends BaseProviderConfig {
     provider: 'mixpanel';
@@ -106,6 +171,16 @@ declare class Mytart {
     track(options: TrackOptions): Promise<TrackResult[]>;
     identify(options: IdentifyOptions): Promise<TrackResult[]>;
     page(options: PageOptions): Promise<TrackResult[]>;
+    /**
+     * Update consent state across all providers that support consent management.
+     * Currently this is meaningful for Google Analytics (Consent Mode v2) in
+     * browser mode. Call this when the user interacts with a cookie/consent
+     * banner.
+     *
+     * To enable Google Signals demographics (age, gender, interests), grant
+     * at least `ad_personalization` and `ad_user_data`.
+     */
+    updateConsent(consent: ConsentSettings): Promise<void>;
     addProvider(config: ProviderConfig): void;
     removeProvider(name: string): void;
     getProviders(): string[];
@@ -116,6 +191,11 @@ declare abstract class BaseProvider {
     abstract track(options: TrackOptions): Promise<TrackResult>;
     abstract identify(options: IdentifyOptions): Promise<TrackResult>;
     abstract page(options: PageOptions): Promise<TrackResult>;
+    /**
+     * Update consent state. Only meaningful for providers that support consent
+     * management (e.g. Google Analytics Consent Mode v2). Default is a no-op.
+     */
+    updateConsent(_consent: ConsentSettings): Promise<void>;
     protected buildError(message: string, code: string, originalError?: unknown): TrackResult;
     protected buildSuccess(statusCode?: number): TrackResult;
 }
@@ -126,34 +206,60 @@ 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>
+     *
+     * When `defaultConsent` is configured, a `gtag('consent', 'default', ...)`
+     * call is emitted **before** `gtag('js')` and `gtag('config')`, as required
+     * by Google's Consent Mode v2 specification.
+     *
+     * 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;
+    /**
+     * Updates the consent state at runtime. In browser mode this emits
+     * `gtag('consent', 'update', ...)`. Call this when the user interacts
+     * with a cookie/consent banner.
+     *
+     * To enable Google Signals demographics (age, gender, interests), grant
+     * at least `ad_personalization` and `ad_user_data`.
+     *
+     * In server mode this is a no-op — the Measurement Protocol does not
+     * support Consent Mode.
+     */
+    updateConsent(consent: ConsentSettings): Promise<void>;
     track({ event, properties, userId, anonymousId, timestamp }: TrackOptions): Promise<TrackResult>;
     identify({ userId, traits }: IdentifyOptions): Promise<TrackResult>;
     page({ name, url, referrer, userId, anonymousId }: PageOptions): Promise<TrackResult>;
@@ -216,4 +322,4 @@ declare class PostHogProvider extends BaseProvider {
     page({ name, url, userId, anonymousId, properties }: PageOptions): Promise<TrackResult>;
 }
 
-export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MixpanelConfig, MixpanelProvider, Mytart, type MytartConfig, type MytartError, type PageOptions, type PlausibleConfig, PlausibleProvider, type PostHogConfig, PostHogProvider, type ProviderConfig, type ProviderName, type SegmentConfig, SegmentProvider, type TrackOptions, type TrackResult };

package/dist/index.js

@@ -43,6 +43,13 @@ module.exports = __toCommonJS(index_exports);
 
 // src/providers/base.ts
 var BaseProvider = class {
+  /**
+   * Update consent state. Only meaningful for providers that support consent
+   * management (e.g. Google Analytics Consent Mode v2). Default is a no-op.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async updateConsent(_consent) {
+  }
   buildError(message, code, originalError) {
     return {
       provider: this.name,
@@ -82,75 +89,116 @@ 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;
+  /**
+   * 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>
+   *
+   * When `defaultConsent` is configured, a `gtag('consent', 'default', ...)`
+   * call is emitted **before** `gtag('js')` and `gtag('config')`, as required
+   * by Google's Consent Mode v2 specification.
+   *
+   * 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();
     }
-    if (typeof window.gtag === "function") {
-      return;
+    window.dataLayer = window.dataLayer || [];
+    window.gtag = function gtag() {
+      window.dataLayer.push(arguments);
+    };
+    const resolvedConsent = this.config.defaultConsent ?? (this.config.signals === true ? {
+      ad_storage: "granted",
+      analytics_storage: "granted",
+      ad_user_data: "granted",
+      ad_personalization: "granted"
+    } : void 0);
+    if (resolvedConsent) {
+      const consentParams = { ...resolvedConsent };
+      if (this.config.consentWaitForUpdate !== void 0) {
+        consentParams["wait_for_update"] = this.config.consentWaitForUpdate;
+      }
+      window.gtag("consent", "default", consentParams);
+    }
+    window.gtag("js", /* @__PURE__ */ new Date());
+    const configParams = {};
+    if (this.config.signals === true) {
+      configParams["allow_google_signals"] = true;
+      configParams["allow_ad_personalization_signals"] = true;
+    } else if (this.config.signals === false) {
+      configParams["allow_google_signals"] = false;
+      configParams["allow_ad_personalization_signals"] = false;
+    }
+    if (Object.keys(configParams).length > 0) {
+      window.gtag("config", this.config.measurementId, configParams);
+    } else {
+      window.gtag("config", this.config.measurementId);
     }
-    await this.injectGtagScript();
-  }
-  injectGtagScript() {
     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;
-      script.onload = () => {
-        window.gtag("js", /* @__PURE__ */ new Date());
-        window.gtag("config", this.config.measurementId, {
-          send_page_view: false
-        });
-        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();
   }
@@ -158,31 +206,60 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
     if (typeof window === "undefined") {
       return this.buildGtagResult();
     }
-    await this.ensureGtagLoaded();
-    const config = {
+    await this.ensureGtag();
+    if (userId) {
+      window.gtag("set", { user_id: userId });
+    }
+    window.gtag("event", "page_view", {
       page_title: name,
       page_location: url,
-      page_referrer: referrer,
-      send_page_view: true
+      page_referrer: referrer
+    });
+    return this.buildGtagResult();
+  }
+  buildGtagResult() {
+    return {
+      provider: this.name,
+      success: true,
+      statusCode: 200
     };
-    if (userId) {
-      config.user_id = userId;
+  }
+  // ---------------------------------------------------------------------------
+  // Consent Mode v2
+  // ---------------------------------------------------------------------------
+  /**
+   * Updates the consent state at runtime. In browser mode this emits
+   * `gtag('consent', 'update', ...)`. Call this when the user interacts
+   * with a cookie/consent banner.
+   *
+   * To enable Google Signals demographics (age, gender, interests), grant
+   * at least `ad_personalization` and `ad_user_data`.
+   *
+   * In server mode this is a no-op — the Measurement Protocol does not
+   * support Consent Mode.
+   */
+  async updateConsent(consent) {
+    if (!this.isBrowser || typeof window === "undefined") {
+      return;
     }
-    window.gtag("config", this.config.measurementId, config);
-    return this.buildGtagResult();
+    await this.ensureGtag();
+    window.gtag("consent", "update", consent);
   }
+  // ---------------------------------------------------------------------------
+  // 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) {
@@ -728,6 +805,18 @@ var Mytart = class {
     };
     return Promise.all(this.providers.map((p) => p.page(enriched)));
   }
+  /**
+   * Update consent state across all providers that support consent management.
+   * Currently this is meaningful for Google Analytics (Consent Mode v2) in
+   * browser mode. Call this when the user interacts with a cookie/consent
+   * banner.
+   *
+   * To enable Google Signals demographics (age, gender, interests), grant
+   * at least `ad_personalization` and `ad_user_data`.
+   */
+  async updateConsent(consent) {
+    await Promise.all(this.providers.map((p) => p.updateConsent(consent)));
+  }
   addProvider(config) {
     if (config.enabled !== true) return;
     this.providers.push(createProvider(config));

package/dist/index.mjs

@@ -1,5 +1,12 @@
 // src/providers/base.ts
 var BaseProvider = class {
+  /**
+   * Update consent state. Only meaningful for providers that support consent
+   * management (e.g. Google Analytics Consent Mode v2). Default is a no-op.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async updateConsent(_consent) {
+  }
   buildError(message, code, originalError) {
     return {
       provider: this.name,
@@ -39,75 +46,116 @@ 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;
+  /**
+   * 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>
+   *
+   * When `defaultConsent` is configured, a `gtag('consent', 'default', ...)`
+   * call is emitted **before** `gtag('js')` and `gtag('config')`, as required
+   * by Google's Consent Mode v2 specification.
+   *
+   * 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();
     }
-    if (typeof window.gtag === "function") {
-      return;
+    window.dataLayer = window.dataLayer || [];
+    window.gtag = function gtag() {
+      window.dataLayer.push(arguments);
+    };
+    const resolvedConsent = this.config.defaultConsent ?? (this.config.signals === true ? {
+      ad_storage: "granted",
+      analytics_storage: "granted",
+      ad_user_data: "granted",
+      ad_personalization: "granted"
+    } : void 0);
+    if (resolvedConsent) {
+      const consentParams = { ...resolvedConsent };
+      if (this.config.consentWaitForUpdate !== void 0) {
+        consentParams["wait_for_update"] = this.config.consentWaitForUpdate;
+      }
+      window.gtag("consent", "default", consentParams);
+    }
+    window.gtag("js", /* @__PURE__ */ new Date());
+    const configParams = {};
+    if (this.config.signals === true) {
+      configParams["allow_google_signals"] = true;
+      configParams["allow_ad_personalization_signals"] = true;
+    } else if (this.config.signals === false) {
+      configParams["allow_google_signals"] = false;
+      configParams["allow_ad_personalization_signals"] = false;
+    }
+    if (Object.keys(configParams).length > 0) {
+      window.gtag("config", this.config.measurementId, configParams);
+    } else {
+      window.gtag("config", this.config.measurementId);
     }
-    await this.injectGtagScript();
-  }
-  injectGtagScript() {
     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;
-      script.onload = () => {
-        window.gtag("js", /* @__PURE__ */ new Date());
-        window.gtag("config", this.config.measurementId, {
-          send_page_view: false
-        });
-        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();
   }
@@ -115,31 +163,60 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
     if (typeof window === "undefined") {
       return this.buildGtagResult();
     }
-    await this.ensureGtagLoaded();
-    const config = {
+    await this.ensureGtag();
+    if (userId) {
+      window.gtag("set", { user_id: userId });
+    }
+    window.gtag("event", "page_view", {
       page_title: name,
       page_location: url,
-      page_referrer: referrer,
-      send_page_view: true
+      page_referrer: referrer
+    });
+    return this.buildGtagResult();
+  }
+  buildGtagResult() {
+    return {
+      provider: this.name,
+      success: true,
+      statusCode: 200
     };
-    if (userId) {
-      config.user_id = userId;
+  }
+  // ---------------------------------------------------------------------------
+  // Consent Mode v2
+  // ---------------------------------------------------------------------------
+  /**
+   * Updates the consent state at runtime. In browser mode this emits
+   * `gtag('consent', 'update', ...)`. Call this when the user interacts
+   * with a cookie/consent banner.
+   *
+   * To enable Google Signals demographics (age, gender, interests), grant
+   * at least `ad_personalization` and `ad_user_data`.
+   *
+   * In server mode this is a no-op — the Measurement Protocol does not
+   * support Consent Mode.
+   */
+  async updateConsent(consent) {
+    if (!this.isBrowser || typeof window === "undefined") {
+      return;
     }
-    window.gtag("config", this.config.measurementId, config);
-    return this.buildGtagResult();
+    await this.ensureGtag();
+    window.gtag("consent", "update", consent);
   }
+  // ---------------------------------------------------------------------------
+  // 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) {
@@ -685,6 +762,18 @@ var Mytart = class {
     };
     return Promise.all(this.providers.map((p) => p.page(enriched)));
   }
+  /**
+   * Update consent state across all providers that support consent management.
+   * Currently this is meaningful for Google Analytics (Consent Mode v2) in
+   * browser mode. Call this when the user interacts with a cookie/consent
+   * banner.
+   *
+   * To enable Google Signals demographics (age, gender, interests), grant
+   * at least `ad_personalization` and `ad_user_data`.
+   */
+  async updateConsent(consent) {
+    await Promise.all(this.providers.map((p) => p.updateConsent(consent)));
+  }
   addProvider(config) {
     if (config.enabled !== true) return;
     this.providers.push(createProvider(config));

package/package.json

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