@junctionjs/destination-meta 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @junctionjs/destination-meta
+
+Meta Pixel + Conversions API destination for Junction.
+
+## Features
+
+- Client-side via Meta Pixel (`fbq`)
+- Server-side via Conversions API (CAPI)
+- Both modes can run simultaneously for redundant delivery with deduplication via `event_id`
+- Standard event mapping (PageView, ViewContent, Purchase, etc.)
+- Advanced matching support
+- Consent management via `fbq("consent", ...)`
+
+## Install
+
+```bash
+npm install @junctionjs/destination-meta
+```
+
+## Usage
+
+```typescript
+import { meta } from "@junctionjs/destination-meta";
+
+// In your collector config
+const config = {
+  destinations: [
+    {
+      destination: meta,
+      config: {
+        pixelId: "YOUR_PIXEL_ID",
+        accessToken: process.env.META_CAPI_TOKEN, // server-side only
+      },
+      consent: ["marketing"],
+    },
+  ],
+};
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { Destination } from '@junctionjs/core';
+
+/**
+ * @junctionjs/destination-meta
+ *
+ * Meta (Facebook) destination for Junction.
+ *
+ * Client-side: Meta Pixel (fbq)
+ * Server-side: Conversions API (CAPI)
+ *
+ * Design: Both modes can run simultaneously for "redundant" event
+ * delivery (Meta recommends this for signal quality + dedup).
+ * The event_id field is shared between pixel and CAPI for deduplication.
+ */
+
+interface MetaConfig {
+    /** Meta Pixel ID */
+    pixelId: string;
+    /** Conversions API access token (server-side only) */
+    accessToken?: string;
+    /** Test event code (for CAPI testing) */
+    testEventCode?: string;
+    /** Whether to load the Meta Pixel script if not present (default: true) */
+    loadScript?: boolean;
+    /** Enable advanced matching (hashed email, phone, etc.) */
+    advancedMatching?: boolean;
+    /** Custom event name mapping */
+    eventNameMap?: Record<string, string>;
+}
+declare const meta: Destination<MetaConfig>;
+
+export { type MetaConfig, meta as default, meta };

package/dist/index.js

@@ -0,0 +1,143 @@
+// src/index.ts
+var META_EVENT_MAP = {
+  "page:viewed": "PageView",
+  "product:viewed": "ViewContent",
+  "product:added": "AddToCart",
+  "product:list_viewed": "ViewContent",
+  "checkout:started": "InitiateCheckout",
+  "checkout:payment_added": "AddPaymentInfo",
+  "order:completed": "Purchase",
+  "search:performed": "Search",
+  "user:signed_up": "CompleteRegistration",
+  "user:subscribed": "Subscribe",
+  "lead:created": "Lead",
+  "content:viewed": "ViewContent",
+  "wishlist:added": "AddToWishlist"
+};
+function getMetaEventName(event, config) {
+  const key = `${event.entity}:${event.action}`;
+  return config.eventNameMap?.[key] ?? META_EVENT_MAP[key] ?? `Custom_${event.entity}_${event.action}`;
+}
+function mapToMetaParams(event) {
+  const props = event.properties;
+  const params = {};
+  if (props.total || props.revenue || props.price) {
+    params.value = props.total ?? props.revenue ?? props.price;
+  }
+  if (props.currency) params.currency = props.currency;
+  if (props.product_id || props.name) {
+    params.content_ids = [props.product_id ?? props.name];
+    params.content_name = props.name;
+    params.content_type = "product";
+  }
+  if (props.category) params.content_category = props.category;
+  if (props.search_term || props.query) params.search_string = props.search_term ?? props.query;
+  if (props.order_id) params.order_id = props.order_id;
+  if (props.quantity) params.num_items = props.quantity;
+  return params;
+}
+function buildCAPIPayload(event, eventName, params, config) {
+  return {
+    data: [
+      {
+        event_name: eventName,
+        event_time: Math.floor(new Date(event.timestamp).getTime() / 1e3),
+        event_id: event.id,
+        // shared with pixel for dedup
+        event_source_url: event.context.page?.url,
+        user_data: {
+          client_user_agent: event.context.device?.userAgent,
+          external_id: event.user.userId
+          // fbc/fbp cookies would be extracted from context
+        },
+        custom_data: params,
+        action_source: "website"
+      }
+    ],
+    ...config.testEventCode ? { test_event_code: config.testEventCode } : {}
+  };
+}
+function loadPixel(pixelId) {
+  if (typeof window === "undefined") return;
+  if (typeof window.fbq === "function") return;
+  const n = window.fbq = function() {
+    n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments);
+  };
+  if (!window._fbq) window._fbq = n;
+  n.push = n;
+  n.loaded = true;
+  n.version = "2.0";
+  n.queue = [];
+  const script = document.createElement("script");
+  script.async = true;
+  script.src = "https://connect.facebook.net/en_US/fbevents.js";
+  document.head.appendChild(script);
+  window.fbq("init", pixelId);
+}
+var meta = {
+  name: "meta",
+  description: "Meta Pixel + Conversions API",
+  version: "0.1.0",
+  consent: ["marketing"],
+  runtime: "both",
+  init(config) {
+    if (!config.pixelId) {
+      throw new Error("[Junction:Meta] pixelId is required");
+    }
+    if (typeof window !== "undefined" && config.loadScript !== false) {
+      loadPixel(config.pixelId);
+    }
+  },
+  transform(event) {
+    if (event.entity === "_system") return null;
+    const eventName = getMetaEventName(event, {});
+    const params = mapToMetaParams(event);
+    return {
+      eventName,
+      params,
+      eventId: event.id,
+      event
+    };
+  },
+  async send(payload, config) {
+    const { eventName, params, eventId, event } = payload;
+    if (typeof window !== "undefined" && typeof window.fbq === "function") {
+      const isStandard = Object.values(META_EVENT_MAP).includes(eventName);
+      if (isStandard) {
+        window.fbq("track", eventName, params, { eventID: eventId });
+      } else {
+        window.fbq("trackCustom", eventName, params, { eventID: eventId });
+      }
+    }
+    if (config.accessToken) {
+      const capiPayload = buildCAPIPayload(event, eventName, params, config);
+      const response = await fetch(
+        `https://graph.facebook.com/v19.0/${config.pixelId}/events?access_token=${config.accessToken}`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(capiPayload)
+        }
+      );
+      if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Meta CAPI error (${response.status}): ${body}`);
+      }
+    }
+  },
+  onConsent(state) {
+    if (typeof window !== "undefined" && typeof window.fbq === "function") {
+      if (state.marketing === false) {
+        window.fbq("consent", "revoke");
+      } else if (state.marketing === true) {
+        window.fbq("consent", "grant");
+      }
+    }
+  }
+};
+var index_default = meta;
+export {
+  index_default as default,
+  meta
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @junctionjs/destination-meta\n *\n * Meta (Facebook) destination for Junction.\n *\n * Client-side: Meta Pixel (fbq)\n * Server-side: Conversions API (CAPI)\n *\n * Design: Both modes can run simultaneously for \"redundant\" event\n * delivery (Meta recommends this for signal quality + dedup).\n * The event_id field is shared between pixel and CAPI for deduplication.\n */\n\nimport type { Destination, JctEvent, ConsentState } from \"@junctionjs/core\";\n\n// ─── Configuration ───────────────────────────────────────────────\n\nexport interface MetaConfig {\n  /** Meta Pixel ID */\n  pixelId: string;\n\n  /** Conversions API access token (server-side only) */\n  accessToken?: string;\n\n  /** Test event code (for CAPI testing) */\n  testEventCode?: string;\n\n  /** Whether to load the Meta Pixel script if not present (default: true) */\n  loadScript?: boolean;\n\n  /** Enable advanced matching (hashed email, phone, etc.) */\n  advancedMatching?: boolean;\n\n  /** Custom event name mapping */\n  eventNameMap?: Record<string, string>;\n}\n\n// ─── Meta Standard Events ────────────────────────────────────────\n\nconst META_EVENT_MAP: Record<string, string> = {\n  \"page:viewed\": \"PageView\",\n  \"product:viewed\": \"ViewContent\",\n  \"product:added\": \"AddToCart\",\n  \"product:list_viewed\": \"ViewContent\",\n  \"checkout:started\": \"InitiateCheckout\",\n  \"checkout:payment_added\": \"AddPaymentInfo\",\n  \"order:completed\": \"Purchase\",\n  \"search:performed\": \"Search\",\n  \"user:signed_up\": \"CompleteRegistration\",\n  \"user:subscribed\": \"Subscribe\",\n  \"lead:created\": \"Lead\",\n  \"content:viewed\": \"ViewContent\",\n  \"wishlist:added\": \"AddToWishlist\",\n};\n\nfunction getMetaEventName(event: JctEvent, config: MetaConfig): string {\n  const key = `${event.entity}:${event.action}`;\n  return config.eventNameMap?.[key] ?? META_EVENT_MAP[key] ?? `Custom_${event.entity}_${event.action}`;\n}\n\n// ─── Meta Parameter Mapping ──────────────────────────────────────\n\nfunction mapToMetaParams(event: JctEvent): Record<string, unknown> {\n  const props = event.properties;\n  const params: Record<string, unknown> = {};\n\n  // Standard Meta parameters\n  if (props.total || props.revenue || props.price) {\n    params.value = props.total ?? props.revenue ?? props.price;\n  }\n  if (props.currency) params.currency = props.currency;\n  if (props.product_id || props.name) {\n    params.content_ids = [props.product_id ?? props.name];\n    params.content_name = props.name;\n    params.content_type = \"product\";\n  }\n  if (props.category) params.content_category = props.category;\n  if (props.search_term || props.query) params.search_string = props.search_term ?? props.query;\n  if (props.order_id) params.order_id = props.order_id;\n  if (props.quantity) params.num_items = props.quantity;\n\n  return params;\n}\n\n// ─── CAPI Payload ────────────────────────────────────────────────\n\ninterface CAPIPayload {\n  data: Array<{\n    event_name: string;\n    event_time: number;\n    event_id: string;\n    event_source_url?: string;\n    user_data: {\n      client_ip_address?: string;\n      client_user_agent?: string;\n      fbc?: string;\n      fbp?: string;\n      external_id?: string;\n      em?: string; // hashed email\n      ph?: string; // hashed phone\n    };\n    custom_data: Record<string, unknown>;\n    action_source: \"website\" | \"email\" | \"app\" | \"phone_call\" | \"chat\" | \"physical_store\" | \"system_generated\" | \"other\";\n  }>;\n  test_event_code?: string;\n}\n\nfunction buildCAPIPayload(\n  event: JctEvent,\n  eventName: string,\n  params: Record<string, unknown>,\n  config: MetaConfig,\n): CAPIPayload {\n  return {\n    data: [\n      {\n        event_name: eventName,\n        event_time: Math.floor(new Date(event.timestamp).getTime() / 1000),\n        event_id: event.id, // shared with pixel for dedup\n        event_source_url: event.context.page?.url,\n        user_data: {\n          client_user_agent: event.context.device?.userAgent,\n          external_id: event.user.userId,\n          // fbc/fbp cookies would be extracted from context\n        },\n        custom_data: params,\n        action_source: \"website\",\n      },\n    ],\n    ...(config.testEventCode ? { test_event_code: config.testEventCode } : {}),\n  };\n}\n\n// ─── Pixel Loader ────────────────────────────────────────────────\n\nfunction loadPixel(pixelId: string): void {\n  if (typeof window === \"undefined\") return;\n  if (typeof (window as any).fbq === \"function\") return;\n\n  // Standard Meta Pixel initialization\n  const n: any = ((window as any).fbq = function () {\n    n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments);\n  });\n  if (!(window as any)._fbq) (window as any)._fbq = n;\n  n.push = n;\n  n.loaded = true;\n  n.version = \"2.0\";\n  n.queue = [];\n\n  const script = document.createElement(\"script\");\n  script.async = true;\n  script.src = \"https://connect.facebook.net/en_US/fbevents.js\";\n  document.head.appendChild(script);\n\n  (window as any).fbq(\"init\", pixelId);\n}\n\n// ─── Destination Export ──────────────────────────────────────────\n\ninterface MetaPayload {\n  eventName: string;\n  params: Record<string, unknown>;\n  eventId: string;\n  event: JctEvent;\n}\n\nexport const meta: Destination<MetaConfig> = {\n  name: \"meta\",\n  description: \"Meta Pixel + Conversions API\",\n  version: \"0.1.0\",\n  consent: [\"marketing\"],\n  runtime: \"both\",\n\n  init(config: MetaConfig) {\n    if (!config.pixelId) {\n      throw new Error(\"[Junction:Meta] pixelId is required\");\n    }\n\n    if (typeof window !== \"undefined\" && config.loadScript !== false) {\n      loadPixel(config.pixelId);\n    }\n  },\n\n  transform(event: JctEvent): MetaPayload | null {\n    if (event.entity === \"_system\") return null;\n\n    const eventName = getMetaEventName(event, {} as MetaConfig);\n    const params = mapToMetaParams(event);\n\n    return {\n      eventName,\n      params,\n      eventId: event.id,\n      event,\n    };\n  },\n\n  async send(payload: unknown, config: MetaConfig) {\n    const { eventName, params, eventId, event } = payload as MetaPayload;\n\n    // Client-side: Meta Pixel\n    if (typeof window !== \"undefined\" && typeof (window as any).fbq === \"function\") {\n      const isStandard = Object.values(META_EVENT_MAP).includes(eventName);\n      if (isStandard) {\n        (window as any).fbq(\"track\", eventName, params, { eventID: eventId });\n      } else {\n        (window as any).fbq(\"trackCustom\", eventName, params, { eventID: eventId });\n      }\n    }\n\n    // Server-side: Conversions API\n    if (config.accessToken) {\n      const capiPayload = buildCAPIPayload(event, eventName, params, config);\n\n      const response = await fetch(\n        `https://graph.facebook.com/v19.0/${config.pixelId}/events?access_token=${config.accessToken}`,\n        {\n          method: \"POST\",\n          headers: { \"Content-Type\": \"application/json\" },\n          body: JSON.stringify(capiPayload),\n        },\n      );\n\n      if (!response.ok) {\n        const body = await response.text();\n        throw new Error(`Meta CAPI error (${response.status}): ${body}`);\n      }\n    }\n  },\n\n  onConsent(state: ConsentState) {\n    // Meta doesn't have a formal consent mode like Google,\n    // but we can revoke pixel if marketing consent is denied\n    if (typeof window !== \"undefined\" && typeof (window as any).fbq === \"function\") {\n      if (state.marketing === false) {\n        (window as any).fbq(\"consent\", \"revoke\");\n      } else if (state.marketing === true) {\n        (window as any).fbq(\"consent\", \"grant\");\n      }\n    }\n  },\n};\n\nexport default meta;\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@junctionjs/destination-meta",
+  "version": "0.1.0",
+  "description": "Meta Pixel + Conversions API destination for Junction",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --sourcemap --target es2022 --no-config --external @junctionjs/core",
+    "dev": "tsup src/index.ts --format esm --dts --watch --no-config --external @junctionjs/core",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@junctionjs/core": "*"
+  },
+  "devDependencies": {
+    "@junctionjs/core": "*",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tyssejc/junction.git",
+    "directory": "packages/destination-meta"
+  },
+  "keywords": ["analytics", "meta", "facebook-pixel", "conversions-api", "junction-destination"]
+}