mytart 0.4.0 → 0.5.1

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`
@@ -176,6 +176,83 @@ Consent Mode is a no-op in server mode (the Measurement Protocol does not suppor
 { 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)`
@@ -295,7 +372,8 @@ import type {
   MytartConfig, BaseProviderConfig, ProviderConfig, TrackOptions, IdentifyOptions, PageOptions,
   TrackResult, MytartError, EventContext, ProviderName, GoogleAnalyticsAppType,
   GoogleAnalyticsConfig, ConsentSettings, ConsentState, MixpanelConfig, SegmentConfig,
-  AmplitudeConfig, PlausibleConfig, PostHogConfig,
+  AmplitudeConfig, PlausibleConfig, PostHogConfig, MetaPixelConfig, MetaPixelAppType,
+  MetaPixelAdvancedMatching,
 } from 'mytart';
 ```
 

package/dist/index.d.mts

@@ -35,7 +35,7 @@ interface ConsentSettings {
     /** Controls storage for security purposes (e.g. authentication). */
     security_storage?: ConsentState;
 }
-type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog';
+type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog' | 'meta-pixel';
 type GoogleAnalyticsAppType = 'browser' | 'server';
 interface GoogleAnalyticsConfig extends BaseProviderConfig {
     provider: 'google-analytics';
@@ -110,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;
@@ -322,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 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 };
+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 };

package/dist/index.d.ts

@@ -35,7 +35,7 @@ interface ConsentSettings {
     /** Controls storage for security purposes (e.g. authentication). */
     security_storage?: ConsentState;
 }
-type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog';
+type ProviderName = 'google-analytics' | 'mixpanel' | 'segment' | 'amplitude' | 'plausible' | 'posthog' | 'meta-pixel';
 type GoogleAnalyticsAppType = 'browser' | 'server';
 interface GoogleAnalyticsConfig extends BaseProviderConfig {
     provider: 'google-analytics';
@@ -110,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;
@@ -322,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 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 };
+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 };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   AmplitudeProvider: () => AmplitudeProvider,
   BaseProvider: () => BaseProvider,
   GoogleAnalyticsProvider: () => GoogleAnalyticsProvider,
+  MetaPixelProvider: () => MetaPixelProvider,
   MixpanelProvider: () => MixpanelProvider,
   Mytart: () => Mytart,
   PlausibleProvider: () => PlausibleProvider,
@@ -145,7 +146,9 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
       window.gtag("consent", "default", consentParams);
     }
     window.gtag("js", /* @__PURE__ */ new Date());
-    const configParams = {};
+    const configParams = {
+      send_page_view: false
+    };
     if (this.config.signals === true) {
       configParams["allow_google_signals"] = true;
       configParams["allow_ad_personalization_signals"] = true;
@@ -153,11 +156,7 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
       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);
-    }
+    window.gtag("config", this.config.measurementId, configParams);
     return new Promise((resolve) => {
       const script = document.createElement("script");
       script.async = true;
@@ -760,6 +759,330 @@ var PostHogProvider = class extends BaseProvider {
   }
 };
 
+// src/utils/hash.ts
+var import_crypto = require("crypto");
+function sha256(value) {
+  if (/^[a-f0-9]{64}$/.test(value)) {
+    return value;
+  }
+  return (0, import_crypto.createHash)("sha256").update(value).digest("hex");
+}
+var PII_FIELDS = /* @__PURE__ */ new Set([
+  "em",
+  "ph",
+  "fn",
+  "ln",
+  "ge",
+  "db",
+  "ct",
+  "st",
+  "zp",
+  "country"
+]);
+function hashUserData(userData) {
+  const result = {};
+  for (const [key, value] of Object.entries(userData)) {
+    if (PII_FIELDS.has(key) && typeof value === "string" && value.length > 0) {
+      result[key] = sha256(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// src/providers/meta-pixel.ts
+var FBEVENTS_SCRIPT_URL = "https://connect.facebook.net/en_US/fbevents.js";
+var DEFAULT_API_VERSION = "v21.0";
+var STANDARD_EVENTS = /* @__PURE__ */ new Set([
+  "PageView",
+  "Purchase",
+  "AddToCart",
+  "ViewContent",
+  "InitiateCheckout",
+  "Search",
+  "Lead",
+  "CompleteRegistration",
+  "AddPaymentInfo",
+  "AddToWishlist",
+  "Contact",
+  "StartTrial",
+  "Subscribe",
+  "Donate",
+  "Schedule",
+  "SubmitApplication",
+  "CustomizeProduct",
+  "FindLocation"
+]);
+var MetaPixelProvider = class extends BaseProvider {
+  constructor(config) {
+    super();
+    this.name = "meta-pixel";
+    this.fbqReady = null;
+    /**
+     * Cached user data for the Conversions API. Updated by `identify()` so
+     * that subsequent `track()` and `page()` calls include user information.
+     */
+    this.cachedUserData = {};
+    this.config = config;
+    this.http = createHttpClient();
+    this.isBrowser = config.appType === "browser";
+    this.apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
+    if (config.advancedMatching) {
+      this.cachedUserData = { ...config.advancedMatching };
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Browser mode — fbevents.js injection & fbq() calls
+  // ---------------------------------------------------------------------------
+  /**
+   * 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
+   */
+  initFbq() {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return Promise.resolve();
+    }
+    if (!window.fbq) {
+      const queue = [];
+      const fbq = Object.assign(
+        function fbq2(...args) {
+          if (fbq2.callMethod) {
+            fbq2.callMethod(...args);
+          } else {
+            queue.push(args);
+          }
+        },
+        {
+          push: void 0,
+          loaded: true,
+          version: "2.0",
+          queue,
+          callMethod: void 0
+        }
+      );
+      fbq.push = fbq;
+      window.fbq = fbq;
+      window._fbq = fbq;
+    }
+    if (this.config.autoConfig === false) {
+      window.fbq("set", "autoConfig", false, this.config.pixelId);
+    }
+    if (this.config.debug) {
+      window.fbq("set", "debug", true);
+    }
+    const matchData = this.config.advancedMatching;
+    if (matchData && Object.keys(matchData).length > 0) {
+      window.fbq("init", this.config.pixelId, matchData);
+    } else {
+      window.fbq("init", this.config.pixelId);
+    }
+    return new Promise((resolve) => {
+      const script = document.createElement("script");
+      script.async = true;
+      script.src = FBEVENTS_SCRIPT_URL;
+      script.onload = () => resolve();
+      script.onerror = () => resolve();
+      document.head.appendChild(script);
+    });
+  }
+  /**
+   * Ensures the Pixel is initialised exactly once. Subsequent calls return
+   * the same promise so the script is never injected twice.
+   */
+  ensureFbq() {
+    if (!this.fbqReady) {
+      this.fbqReady = this.initFbq();
+    }
+    return this.fbqReady;
+  }
+  // -- browser track --
+  async trackBrowser(options) {
+    if (typeof window === "undefined") {
+      return this.buildFbqResult();
+    }
+    await this.ensureFbq();
+    const { event, properties, context } = options;
+    const eventId = context?.eventId;
+    const isStandard = STANDARD_EVENTS.has(event);
+    const command = isStandard ? "track" : "trackCustom";
+    if (eventId) {
+      window.fbq(command, event, properties ?? {}, { eventID: eventId });
+    } else {
+      window.fbq(command, event, properties ?? {});
+    }
+    return this.buildFbqResult();
+  }
+  // -- browser identify --
+  async identifyBrowser(options) {
+    if (typeof window === "undefined") {
+      return this.buildFbqResult();
+    }
+    await this.ensureFbq();
+    const matchData = {};
+    if (options.traits) {
+      Object.assign(matchData, options.traits);
+    }
+    matchData["external_id"] = options.userId;
+    window.fbq("init", this.config.pixelId, matchData);
+    return this.buildFbqResult();
+  }
+  // -- browser page --
+  async pageBrowser(options) {
+    if (typeof window === "undefined") {
+      return this.buildFbqResult();
+    }
+    await this.ensureFbq();
+    window.fbq("track", "PageView");
+    return this.buildFbqResult();
+  }
+  buildFbqResult() {
+    return {
+      provider: this.name,
+      success: true,
+      statusCode: 200
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Server mode — Meta Conversions API (CAPI)
+  // ---------------------------------------------------------------------------
+  get capiEndpoint() {
+    return `https://graph.facebook.com/${this.apiVersion}/${this.config.pixelId}/events`;
+  }
+  /**
+   * 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.
+   */
+  buildUserData(overrides) {
+    const merged = { ...this.cachedUserData, ...overrides };
+    return hashUserData(merged);
+  }
+  // -- server track --
+  async trackServer(options) {
+    try {
+      const { event, properties, context, timestamp, userId } = options;
+      const eventId = context?.eventId;
+      const userDataOverrides = {};
+      if (userId) {
+        userDataOverrides["external_id"] = userId;
+      }
+      const eventData = {
+        event_name: event,
+        event_time: timestamp ? Math.floor(timestamp.getTime() / 1e3) : Math.floor(Date.now() / 1e3),
+        action_source: "website",
+        user_data: this.buildUserData(userDataOverrides)
+      };
+      if (eventId) {
+        eventData["event_id"] = eventId;
+      }
+      const pageUrl = context?.page?.url;
+      if (pageUrl) {
+        eventData["event_source_url"] = pageUrl;
+      }
+      if (properties && Object.keys(properties).length > 0) {
+        eventData["custom_data"] = properties;
+      }
+      const body = {
+        data: [eventData]
+      };
+      if (this.config.testEventCode) {
+        body["test_event_code"] = this.config.testEventCode;
+      }
+      const response = await this.http.post(this.capiEndpoint, body, {
+        params: { access_token: this.config.accessToken }
+      });
+      return this.buildSuccess(response.status);
+    } catch (error) {
+      if (isAxiosError(error)) {
+        return this.buildError(
+          error.message,
+          `META_PIXEL_HTTP_${error.response?.status ?? "ERROR"}`,
+          error
+        );
+      }
+      return this.buildError(String(error), "META_PIXEL_UNKNOWN_ERROR", error);
+    }
+  }
+  // -- server identify --
+  async identifyServer(options) {
+    if (options.traits) {
+      Object.assign(this.cachedUserData, options.traits);
+    }
+    this.cachedUserData["external_id"] = options.userId;
+    return this.buildSuccess(200);
+  }
+  // -- server page --
+  async pageServer(options) {
+    return this.trackServer({
+      event: "PageView",
+      properties: options.properties,
+      userId: options.userId,
+      anonymousId: options.anonymousId,
+      timestamp: options.timestamp,
+      context: {
+        page: {
+          url: options.url,
+          referrer: options.referrer
+        }
+      }
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Consent — Meta Pixel's simple grant / revoke model
+  // ---------------------------------------------------------------------------
+  /**
+   * 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')`.
+   */
+  async updatePixelConsent(granted) {
+    if (!this.isBrowser || typeof window === "undefined") {
+      return;
+    }
+    await this.ensureFbq();
+    window.fbq("consent", granted ? "grant" : "revoke");
+  }
+  // ---------------------------------------------------------------------------
+  // Public API — routes to browser or server mode
+  // ---------------------------------------------------------------------------
+  async track(options) {
+    if (this.isBrowser) {
+      return this.trackBrowser(options);
+    }
+    return this.trackServer(options);
+  }
+  async identify(options) {
+    if (this.isBrowser) {
+      return this.identifyBrowser(options);
+    }
+    return this.identifyServer(options);
+  }
+  async page(options) {
+    if (this.isBrowser) {
+      return this.pageBrowser(options);
+    }
+    return this.pageServer(options);
+  }
+};
+
 // src/mytart.ts
 function createProvider(config) {
   switch (config.provider) {
@@ -775,6 +1098,8 @@ function createProvider(config) {
       return new PlausibleProvider(config);
     case "posthog":
       return new PostHogProvider(config);
+    case "meta-pixel":
+      return new MetaPixelProvider(config);
     default: {
       const exhaustive = config;
       throw new Error(`Unknown provider: ${exhaustive.provider}`);
@@ -836,6 +1161,7 @@ var Mytart = class {
   AmplitudeProvider,
   BaseProvider,
   GoogleAnalyticsProvider,
+  MetaPixelProvider,
   MixpanelProvider,
   Mytart,
   PlausibleProvider,

package/dist/index.mjs

@@ -102,7 +102,9 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
       window.gtag("consent", "default", consentParams);
     }
     window.gtag("js", /* @__PURE__ */ new Date());
-    const configParams = {};
+    const configParams = {
+      send_page_view: false
+    };
     if (this.config.signals === true) {
       configParams["allow_google_signals"] = true;
       configParams["allow_ad_personalization_signals"] = true;
@@ -110,11 +112,7 @@ var GoogleAnalyticsProvider = class extends BaseProvider {
       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);
-    }
+    window.gtag("config", this.config.measurementId, configParams);
     return new Promise((resolve) => {
       const script = document.createElement("script");
       script.async = true;
@@ -717,6 +715,330 @@ var PostHogProvider = class extends BaseProvider {
   }
 };
 
+// src/utils/hash.ts
+import { createHash } from "crypto";
+function sha256(value) {
+  if (/^[a-f0-9]{64}$/.test(value)) {
+    return value;
+  }
+  return createHash("sha256").update(value).digest("hex");
+}
+var PII_FIELDS = /* @__PURE__ */ new Set([
+  "em",
+  "ph",
+  "fn",
+  "ln",
+  "ge",
+  "db",
+  "ct",
+  "st",
+  "zp",
+  "country"
+]);
+function hashUserData(userData) {
+  const result = {};
+  for (const [key, value] of Object.entries(userData)) {
+    if (PII_FIELDS.has(key) && typeof value === "string" && value.length > 0) {
+      result[key] = sha256(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// src/providers/meta-pixel.ts
+var FBEVENTS_SCRIPT_URL = "https://connect.facebook.net/en_US/fbevents.js";
+var DEFAULT_API_VERSION = "v21.0";
+var STANDARD_EVENTS = /* @__PURE__ */ new Set([
+  "PageView",
+  "Purchase",
+  "AddToCart",
+  "ViewContent",
+  "InitiateCheckout",
+  "Search",
+  "Lead",
+  "CompleteRegistration",
+  "AddPaymentInfo",
+  "AddToWishlist",
+  "Contact",
+  "StartTrial",
+  "Subscribe",
+  "Donate",
+  "Schedule",
+  "SubmitApplication",
+  "CustomizeProduct",
+  "FindLocation"
+]);
+var MetaPixelProvider = class extends BaseProvider {
+  constructor(config) {
+    super();
+    this.name = "meta-pixel";
+    this.fbqReady = null;
+    /**
+     * Cached user data for the Conversions API. Updated by `identify()` so
+     * that subsequent `track()` and `page()` calls include user information.
+     */
+    this.cachedUserData = {};
+    this.config = config;
+    this.http = createHttpClient();
+    this.isBrowser = config.appType === "browser";
+    this.apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
+    if (config.advancedMatching) {
+      this.cachedUserData = { ...config.advancedMatching };
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Browser mode — fbevents.js injection & fbq() calls
+  // ---------------------------------------------------------------------------
+  /**
+   * 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
+   */
+  initFbq() {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return Promise.resolve();
+    }
+    if (!window.fbq) {
+      const queue = [];
+      const fbq = Object.assign(
+        function fbq2(...args) {
+          if (fbq2.callMethod) {
+            fbq2.callMethod(...args);
+          } else {
+            queue.push(args);
+          }
+        },
+        {
+          push: void 0,
+          loaded: true,
+          version: "2.0",
+          queue,
+          callMethod: void 0
+        }
+      );
+      fbq.push = fbq;
+      window.fbq = fbq;
+      window._fbq = fbq;
+    }
+    if (this.config.autoConfig === false) {
+      window.fbq("set", "autoConfig", false, this.config.pixelId);
+    }
+    if (this.config.debug) {
+      window.fbq("set", "debug", true);
+    }
+    const matchData = this.config.advancedMatching;
+    if (matchData && Object.keys(matchData).length > 0) {
+      window.fbq("init", this.config.pixelId, matchData);
+    } else {
+      window.fbq("init", this.config.pixelId);
+    }
+    return new Promise((resolve) => {
+      const script = document.createElement("script");
+      script.async = true;
+      script.src = FBEVENTS_SCRIPT_URL;
+      script.onload = () => resolve();
+      script.onerror = () => resolve();
+      document.head.appendChild(script);
+    });
+  }
+  /**
+   * Ensures the Pixel is initialised exactly once. Subsequent calls return
+   * the same promise so the script is never injected twice.
+   */
+  ensureFbq() {
+    if (!this.fbqReady) {
+      this.fbqReady = this.initFbq();
+    }
+    return this.fbqReady;
+  }
+  // -- browser track --
+  async trackBrowser(options) {
+    if (typeof window === "undefined") {
+      return this.buildFbqResult();
+    }
+    await this.ensureFbq();
+    const { event, properties, context } = options;
+    const eventId = context?.eventId;
+    const isStandard = STANDARD_EVENTS.has(event);
+    const command = isStandard ? "track" : "trackCustom";
+    if (eventId) {
+      window.fbq(command, event, properties ?? {}, { eventID: eventId });
+    } else {
+      window.fbq(command, event, properties ?? {});
+    }
+    return this.buildFbqResult();
+  }
+  // -- browser identify --
+  async identifyBrowser(options) {
+    if (typeof window === "undefined") {
+      return this.buildFbqResult();
+    }
+    await this.ensureFbq();
+    const matchData = {};
+    if (options.traits) {
+      Object.assign(matchData, options.traits);
+    }
+    matchData["external_id"] = options.userId;
+    window.fbq("init", this.config.pixelId, matchData);
+    return this.buildFbqResult();
+  }
+  // -- browser page --
+  async pageBrowser(options) {
+    if (typeof window === "undefined") {
+      return this.buildFbqResult();
+    }
+    await this.ensureFbq();
+    window.fbq("track", "PageView");
+    return this.buildFbqResult();
+  }
+  buildFbqResult() {
+    return {
+      provider: this.name,
+      success: true,
+      statusCode: 200
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Server mode — Meta Conversions API (CAPI)
+  // ---------------------------------------------------------------------------
+  get capiEndpoint() {
+    return `https://graph.facebook.com/${this.apiVersion}/${this.config.pixelId}/events`;
+  }
+  /**
+   * 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.
+   */
+  buildUserData(overrides) {
+    const merged = { ...this.cachedUserData, ...overrides };
+    return hashUserData(merged);
+  }
+  // -- server track --
+  async trackServer(options) {
+    try {
+      const { event, properties, context, timestamp, userId } = options;
+      const eventId = context?.eventId;
+      const userDataOverrides = {};
+      if (userId) {
+        userDataOverrides["external_id"] = userId;
+      }
+      const eventData = {
+        event_name: event,
+        event_time: timestamp ? Math.floor(timestamp.getTime() / 1e3) : Math.floor(Date.now() / 1e3),
+        action_source: "website",
+        user_data: this.buildUserData(userDataOverrides)
+      };
+      if (eventId) {
+        eventData["event_id"] = eventId;
+      }
+      const pageUrl = context?.page?.url;
+      if (pageUrl) {
+        eventData["event_source_url"] = pageUrl;
+      }
+      if (properties && Object.keys(properties).length > 0) {
+        eventData["custom_data"] = properties;
+      }
+      const body = {
+        data: [eventData]
+      };
+      if (this.config.testEventCode) {
+        body["test_event_code"] = this.config.testEventCode;
+      }
+      const response = await this.http.post(this.capiEndpoint, body, {
+        params: { access_token: this.config.accessToken }
+      });
+      return this.buildSuccess(response.status);
+    } catch (error) {
+      if (isAxiosError(error)) {
+        return this.buildError(
+          error.message,
+          `META_PIXEL_HTTP_${error.response?.status ?? "ERROR"}`,
+          error
+        );
+      }
+      return this.buildError(String(error), "META_PIXEL_UNKNOWN_ERROR", error);
+    }
+  }
+  // -- server identify --
+  async identifyServer(options) {
+    if (options.traits) {
+      Object.assign(this.cachedUserData, options.traits);
+    }
+    this.cachedUserData["external_id"] = options.userId;
+    return this.buildSuccess(200);
+  }
+  // -- server page --
+  async pageServer(options) {
+    return this.trackServer({
+      event: "PageView",
+      properties: options.properties,
+      userId: options.userId,
+      anonymousId: options.anonymousId,
+      timestamp: options.timestamp,
+      context: {
+        page: {
+          url: options.url,
+          referrer: options.referrer
+        }
+      }
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Consent — Meta Pixel's simple grant / revoke model
+  // ---------------------------------------------------------------------------
+  /**
+   * 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')`.
+   */
+  async updatePixelConsent(granted) {
+    if (!this.isBrowser || typeof window === "undefined") {
+      return;
+    }
+    await this.ensureFbq();
+    window.fbq("consent", granted ? "grant" : "revoke");
+  }
+  // ---------------------------------------------------------------------------
+  // Public API — routes to browser or server mode
+  // ---------------------------------------------------------------------------
+  async track(options) {
+    if (this.isBrowser) {
+      return this.trackBrowser(options);
+    }
+    return this.trackServer(options);
+  }
+  async identify(options) {
+    if (this.isBrowser) {
+      return this.identifyBrowser(options);
+    }
+    return this.identifyServer(options);
+  }
+  async page(options) {
+    if (this.isBrowser) {
+      return this.pageBrowser(options);
+    }
+    return this.pageServer(options);
+  }
+};
+
 // src/mytart.ts
 function createProvider(config) {
   switch (config.provider) {
@@ -732,6 +1054,8 @@ function createProvider(config) {
       return new PlausibleProvider(config);
     case "posthog":
       return new PostHogProvider(config);
+    case "meta-pixel":
+      return new MetaPixelProvider(config);
     default: {
       const exhaustive = config;
       throw new Error(`Unknown provider: ${exhaustive.provider}`);
@@ -792,6 +1116,7 @@ export {
   AmplitudeProvider,
   BaseProvider,
   GoogleAnalyticsProvider,
+  MetaPixelProvider,
   MixpanelProvider,
   Mytart,
   PlausibleProvider,

package/package.json

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