mytart 0.3.0 → 0.5.0

package/README.md

@@ -6,7 +6,7 @@
 
 ## Features
 
-- 🔌 **6 providers out of the box**: Google Analytics 4, Mixpanel, Segment, Amplitude, Plausible, PostHog
+- 🔌 **7 providers out of the box**: Google Analytics 4, Mixpanel, Segment, Amplitude, Plausible, PostHog, Meta Pixel
 - 🌐 **Universal**: works in Node.js, browsers, and any JS framework (Next.js, Remix, Astro, SvelteKit, etc.)
 - 🔷 **TypeScript-first**: precise typings, object-parameter style for great DX
 - 📦 **Dual ESM/CJS output**: works with `import` and `require`
@@ -86,6 +86,64 @@ When `appType: 'browser'` is set:
 - 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',
+  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
@@ -118,6 +176,83 @@ When `appType: 'browser'` is set:
 { provider: 'posthog', apiKey: 'phc_YOUR_KEY', apiUrl?: string }
 ```
 
+### Meta Pixel
+
+Meta Pixel supports two modes via the `appType` option:
+
+#### Server mode (default)
+
+Uses the [Meta Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api) — direct HTTP calls, no browser APIs. Use this for Node.js, API routes, serverless functions, etc.
+
+```typescript
+{
+  provider: 'meta-pixel',
+  pixelId: '123456789',
+  accessToken: 'YOUR_ACCESS_TOKEN',
+  enabled: true,
+  // appType defaults to 'server'
+}
+```
+
+PII fields in `user_data` (`em`, `ph`, `fn`, `ln`, `ge`, `db`, `ct`, `st`, `zp`, `country`) are automatically SHA-256 hashed before being sent to the Conversions API. Already-hashed values are not double-hashed.
+
+#### Browser mode
+
+Injects Meta's official [fbevents.js snippet](https://developers.facebook.com/docs/meta-pixel/get-started) into the page. Use this for client-side tracking in any framework.
+
+```typescript
+{
+  provider: 'meta-pixel',
+  pixelId: '123456789',
+  appType: 'browser',
+  advancedMatching: { em: 'user@example.com' },
+  enabled: true,
+}
+```
+
+When `appType: 'browser'` is set:
+
+- The fbevents.js script is loaded once on the first `track()`, `identify()`, or `page()` call
+- Standard Meta events (e.g. `Purchase`, `AddToCart`, `ViewContent`) use `fbq('track', ...)` — custom events use `fbq('trackCustom', ...)`
+- SSR-safe: silently succeeds when `window` is undefined
+- `accessToken` is not required
+
+#### Event deduplication
+
+Pass `eventId` via context to deduplicate browser + server events:
+
+```typescript
+await analytics.track({
+  event: 'Purchase',
+  properties: { currency: 'USD', value: 42 },
+  context: { eventId: 'order-abc-123' },
+});
+```
+
+In browser mode this passes `{ eventID: 'order-abc-123' }` as the 4th `fbq()` parameter. In server mode it sets the `event_id` field in the Conversions API payload.
+
+#### Identify
+
+In browser mode, `identify()` re-calls `fbq('init', pixelId, newTraits)` to update Advanced Matching data. In server mode, traits are cached in memory and included as `user_data` in all subsequent `track()` / `page()` calls.
+
+#### Consent
+
+Meta Pixel uses a simple binary consent model. Access it directly on the provider instance:
+
+```typescript
+import { MetaPixelProvider } from 'mytart';
+
+// Grant consent
+const metaProvider = analytics.getProviders().includes('meta-pixel')
+  ? (analytics as any) // or access the provider directly
+  : null;
+
+// Or use the provider directly:
+const provider = new MetaPixelProvider({ provider: 'meta-pixel', pixelId: '123', appType: 'browser' });
+await provider.updatePixelConsent(true);   // fbq('consent', 'grant')
+await provider.updatePixelConsent(false);  // fbq('consent', 'revoke')
+```
+
 ## API Reference
 
 ### `new Mytart(config: MytartConfig)`
@@ -180,6 +315,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.
@@ -220,8 +371,9 @@ All types are exported:
 import type {
   MytartConfig, BaseProviderConfig, ProviderConfig, TrackOptions, IdentifyOptions, PageOptions,
   TrackResult, MytartError, EventContext, ProviderName, GoogleAnalyticsAppType,
-  GoogleAnalyticsConfig, MixpanelConfig, SegmentConfig,
-  AmplitudeConfig, PlausibleConfig, PostHogConfig,
+  GoogleAnalyticsConfig, ConsentSettings, ConsentState, MixpanelConfig, SegmentConfig,
+  AmplitudeConfig, PlausibleConfig, PostHogConfig, MetaPixelConfig, MetaPixelAppType,
+  MetaPixelAdvancedMatching,
 } from 'mytart';
 ```
 

package/dist/index.d.mts

@@ -8,7 +8,34 @@ interface BaseProviderConfig {
     /** Whether this provider is active. Defaults to `false` when omitted. */
     enabled?: boolean;
 }
-type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog';
+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' | 'meta-pixel';
 type GoogleAnalyticsAppType = 'browser' | 'server';
 interface GoogleAnalyticsConfig extends BaseProviderConfig {
     provider: 'google-analytics';
@@ -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';
@@ -45,7 +110,77 @@ interface PostHogConfig extends BaseProviderConfig {
     apiKey: string;
     apiUrl?: string;
 }
-type ProviderConfig = GoogleAnalyticsConfig | MixpanelConfig | SegmentConfig | AmplitudeConfig | PlausibleConfig | PostHogConfig;
+/**
+ * Advanced Matching data for the Meta Pixel.
+ * In browser mode these fields are passed to `fbq('init', pixelId, matchData)`.
+ * In server mode they are included in the `user_data` object sent to the
+ * Conversions API — plain-text values are automatically SHA-256 hashed before
+ * sending.
+ */
+interface MetaPixelAdvancedMatching {
+    /** Email address */
+    em?: string;
+    /** Phone number */
+    ph?: string;
+    /** First name */
+    fn?: string;
+    /** Last name */
+    ln?: string;
+    /** Gender (m or f) */
+    ge?: string;
+    /** Date of birth (YYYYMMDD) */
+    db?: string;
+    /** City */
+    ct?: string;
+    /** State / province (2-letter code) */
+    st?: string;
+    /** Zip / postal code */
+    zp?: string;
+    /** Country (2-letter ISO code) */
+    country?: string;
+    /** External ID */
+    external_id?: string;
+}
+type MetaPixelAppType = 'browser' | 'server';
+interface MetaPixelConfig extends BaseProviderConfig {
+    provider: 'meta-pixel';
+    /** The Meta Pixel ID (numeric string). */
+    pixelId: string;
+    /**
+     * Access token for the Conversions API. Required when `appType` is
+     * `'server'` — ignored in browser mode.
+     */
+    accessToken?: string;
+    /**
+     * `'browser'` injects the official fbevents.js snippet and calls `window.fbq()`.
+     * `'server'` (default) sends events via the Conversions API HTTP endpoint.
+     */
+    appType?: MetaPixelAppType;
+    /**
+     * Graph API version to use for the Conversions API.
+     * Defaults to `'v21.0'`.
+     */
+    apiVersion?: string;
+    /**
+     * Test Event Code for the Events Manager Test Events tool.
+     * Only used in server mode (Conversions API).
+     */
+    testEventCode?: string;
+    /**
+     * Advanced Matching data passed to `fbq('init')` in browser mode.
+     * In server mode this populates the initial `user_data` for all events.
+     */
+    advancedMatching?: MetaPixelAdvancedMatching;
+    /**
+     * When `true` (default), the Pixel uses Automatic Configuration
+     * (auto-detects button clicks, page metadata, etc.).
+     * Set to `false` to disable.
+     */
+    autoConfig?: boolean;
+    /** Enable Meta Pixel debug mode (`fbq('set', 'debug', true)`). */
+    debug?: boolean;
+}
+type ProviderConfig = GoogleAnalyticsConfig | MixpanelConfig | SegmentConfig | AmplitudeConfig | PlausibleConfig | PostHogConfig | MetaPixelConfig;
 interface MytartConfig {
     providers: ProviderConfig[];
     defaultUserId?: string;
@@ -106,6 +241,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 +261,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;
 }
@@ -147,6 +297,10 @@ declare class GoogleAnalyticsProvider extends BaseProvider {
      *     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
@@ -164,6 +318,18 @@ declare class GoogleAnalyticsProvider extends BaseProvider {
     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>;
@@ -226,4 +392,82 @@ 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 };
+declare global {
+    interface Window {
+        fbq: FbqFn & {
+            callMethod?: FbqFn;
+            queue?: unknown[];
+            loaded?: boolean;
+            version?: string;
+            push?: FbqFn;
+        };
+        _fbq: Window['fbq'];
+    }
+}
+type FbqFn = (...args: unknown[]) => void;
+declare class MetaPixelProvider extends BaseProvider {
+    readonly name = "meta-pixel";
+    private readonly config;
+    private readonly http;
+    private readonly isBrowser;
+    private readonly apiVersion;
+    private fbqReady;
+    /**
+     * Cached user data for the Conversions API. Updated by `identify()` so
+     * that subsequent `track()` and `page()` calls include user information.
+     */
+    private cachedUserData;
+    constructor(config: MetaPixelConfig);
+    /**
+     * Initialises the Meta Pixel snippet. This mirrors the official snippet from
+     * https://developers.facebook.com/docs/meta-pixel/get-started:
+     *
+     *   !function(f,b,e,v,n,t,s){...}(window, document,'script',
+     *     'https://connect.facebook.net/en_US/fbevents.js');
+     *   fbq('init', 'PIXEL_ID');
+     *   fbq('track', 'PageView');
+     *
+     * Key details:
+     * - The fbq shim queue is set up synchronously before the script loads
+     * - `fbq('init', pixelId, advancedMatching?)` is called immediately
+     * - autoConfig is respected via `fbq('set', 'autoConfig', false, pixelId)`
+     * - debug mode via `fbq('set', 'debug', true)`
+     * - The returned promise resolves when the script finishes loading
+     */
+    private initFbq;
+    /**
+     * Ensures the Pixel is initialised exactly once. Subsequent calls return
+     * the same promise so the script is never injected twice.
+     */
+    private ensureFbq;
+    private trackBrowser;
+    private identifyBrowser;
+    private pageBrowser;
+    private buildFbqResult;
+    private get capiEndpoint();
+    /**
+     * Build the `user_data` object for a CAPI event.
+     * Merges cached user data (from `identify()` / config) with any per-event
+     * overrides, then SHA-256 hashes known PII fields.
+     */
+    private buildUserData;
+    private trackServer;
+    private identifyServer;
+    private pageServer;
+    /**
+     * Meta Pixel consent is a binary grant/revoke model, not the granular
+     * settings of Google Consent Mode v2. This method accepts the standard
+     * `ConsentSettings` type but is a no-op — use `updatePixelConsent()` for
+     * Meta-specific consent control in browser mode.
+     */
+    /**
+     * Grant or revoke consent for the Meta Pixel in browser mode.
+     * Calls `fbq('consent', 'grant')` or `fbq('consent', 'revoke')`.
+     */
+    updatePixelConsent(granted: boolean): Promise<void>;
+    track(options: TrackOptions): Promise<TrackResult>;
+    identify(options: IdentifyOptions): Promise<TrackResult>;
+    page(options: PageOptions): Promise<TrackResult>;
+}
+
+export { type AmplitudeConfig, AmplitudeProvider, BaseProvider, type BaseProviderConfig, type ConsentSettings, type ConsentState, type EventContext, type GoogleAnalyticsAppType, type GoogleAnalyticsConfig, GoogleAnalyticsProvider, type IdentifyOptions, type MetaPixelAdvancedMatching, type MetaPixelAppType, type MetaPixelConfig, MetaPixelProvider, 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 };