@junctionjs/destination-ga4 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @junctionjs/destination-ga4
+
+Google Analytics 4 destination for Junction.
+
+## Features
+
+- Client-side via gtag.js (loaded lazily if not present)
+- Server-side via GA4 Measurement Protocol
+- Google Consent Mode v2 — automatically maps Junction consent state to Google's consent signals
+- GA4 recommended event mapping (view_item, add_to_cart, purchase, etc.)
+- Custom event name and parameter overrides
+
+## Install
+
+```bash
+npm install @junctionjs/destination-ga4
+```
+
+## Usage
+
+```typescript
+import { ga4 } from "@junctionjs/destination-ga4";
+
+// In your collector config
+const config = {
+  destinations: [
+    {
+      destination: ga4,
+      config: {
+        measurementId: "G-XXXXXXXXXX",
+        consentMode: true,
+        sendPageView: false, // Junction handles page views
+      },
+      consent: ["analytics"],
+    },
+  ],
+};
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { Destination } from '@junctionjs/core';
+
+/**
+ * @junctionjs/destination-ga4
+ *
+ * Google Analytics 4 destination for Junction.
+ *
+ * Client-side: uses gtag.js (loaded lazily if not present)
+ * Server-side: uses GA4 Measurement Protocol
+ *
+ * Handles Google's consent mode (v2) natively — when consent state
+ * changes, we update gtag's consent settings automatically.
+ */
+
+interface GA4Config {
+    /** GA4 Measurement ID (e.g., "G-XXXXXXXXXX") */
+    measurementId: string;
+    /** Server-side: GA4 Measurement Protocol API secret */
+    apiSecret?: string;
+    /** Whether to load gtag.js if not already present (default: true) */
+    loadScript?: boolean;
+    /** Custom gtag.js URL (for self-hosting or proxy) */
+    gtagUrl?: string;
+    /**
+     * Enable Google Consent Mode v2.
+     * When true, Junction's consent state maps to Google's consent categories.
+     */
+    consentMode?: boolean;
+    /** Send page_view events automatically (default: false — Junction handles this) */
+    sendPageView?: boolean;
+    /** Custom event name mapping */
+    eventNameMap?: Record<string, string>;
+    /** Custom parameter mapping */
+    parameterMap?: Record<string, string>;
+}
+declare const ga4: Destination<GA4Config>;
+
+export { type GA4Config, ga4 as default, ga4 };

package/dist/index.js

@@ -0,0 +1,136 @@
+// src/index.ts
+function mapConsentToGoogle(state) {
+  return {
+    ad_storage: state.marketing ? "granted" : "denied",
+    analytics_storage: state.analytics ? "granted" : "denied",
+    ad_user_data: state.marketing ? "granted" : "denied",
+    ad_personalization: state.personalization ? "granted" : "denied",
+    personalization_storage: state.personalization ? "granted" : "denied",
+    functionality_storage: state.necessary !== false ? "granted" : "denied",
+    security_storage: "granted"
+    // always granted
+  };
+}
+var GA4_EVENT_MAP = {
+  "page:viewed": "page_view",
+  "product:viewed": "view_item",
+  "product:added": "add_to_cart",
+  "product:removed": "remove_from_cart",
+  "product:list_viewed": "view_item_list",
+  "product:clicked": "select_item",
+  "cart:viewed": "view_cart",
+  "checkout:started": "begin_checkout",
+  "checkout:shipping_added": "add_shipping_info",
+  "checkout:payment_added": "add_payment_info",
+  "order:completed": "purchase",
+  "order:refunded": "refund",
+  "promotion:viewed": "view_promotion",
+  "promotion:clicked": "select_promotion",
+  "search:performed": "search",
+  "user:signed_up": "sign_up",
+  "user:logged_in": "login",
+  "content:shared": "share"
+};
+function getGA4EventName(event, config) {
+  const key = `${event.entity}:${event.action}`;
+  return config.eventNameMap?.[key] ?? GA4_EVENT_MAP[key] ?? `${event.entity}_${event.action}`;
+}
+var GA4_PARAM_MAP = {
+  product_id: "item_id",
+  name: "item_name",
+  category: "item_category",
+  brand: "item_brand",
+  variant: "item_variant",
+  price: "price",
+  quantity: "quantity",
+  order_id: "transaction_id",
+  total: "value",
+  revenue: "value",
+  tax: "tax",
+  shipping: "shipping",
+  currency: "currency",
+  coupon: "coupon",
+  search_term: "search_term"
+};
+function mapParameters(properties, config) {
+  const mapped = {};
+  for (const [key, value] of Object.entries(properties)) {
+    const mappedKey = config.parameterMap?.[key] ?? GA4_PARAM_MAP[key] ?? key;
+    mapped[mappedKey] = value;
+  }
+  return mapped;
+}
+function transformEvent(event, config) {
+  return {
+    eventName: getGA4EventName(event, config),
+    parameters: mapParameters(event.properties, config)
+  };
+}
+function loadGtag(measurementId, gtagUrl) {
+  if (typeof window === "undefined") return;
+  if (typeof window.gtag === "function") return;
+  window.dataLayer = window.dataLayer || [];
+  window.gtag = function() {
+    window.dataLayer.push(arguments);
+  };
+  window.gtag("js", /* @__PURE__ */ new Date());
+  const script = document.createElement("script");
+  script.async = true;
+  script.src = gtagUrl ?? `https://www.googletagmanager.com/gtag/js?id=${measurementId}`;
+  document.head.appendChild(script);
+}
+var ga4 = {
+  name: "ga4",
+  description: "Google Analytics 4",
+  version: "0.1.0",
+  consent: ["analytics"],
+  runtime: "both",
+  init(config) {
+    if (!config.measurementId) {
+      throw new Error("[Junction:GA4] measurementId is required");
+    }
+    if (typeof window !== "undefined" && config.loadScript !== false) {
+      loadGtag(config.measurementId, config.gtagUrl);
+      const gtagConfig = {
+        send_page_view: config.sendPageView ?? false
+      };
+      window.gtag?.("config", config.measurementId, gtagConfig);
+    }
+  },
+  transform(event) {
+    if (event.entity === "_system") return null;
+    return transformEvent(event, {});
+  },
+  async send(payload, config) {
+    const ga4Payload = payload;
+    if (typeof window !== "undefined" && typeof window.gtag === "function") {
+      window.gtag("event", ga4Payload.eventName, ga4Payload.parameters);
+    } else if (config.apiSecret) {
+      const url = `https://www.google-analytics.com/mp/collect?measurement_id=${config.measurementId}&api_secret=${config.apiSecret}`;
+      await fetch(url, {
+        method: "POST",
+        body: JSON.stringify({
+          client_id: "server",
+          // should be passed from client
+          events: [
+            {
+              name: ga4Payload.eventName,
+              params: ga4Payload.parameters
+            }
+          ]
+        })
+      });
+    }
+  },
+  onConsent(state) {
+    if (typeof window !== "undefined" && typeof window.gtag === "function") {
+      window.gtag("consent", "update", mapConsentToGoogle(state));
+    }
+  }
+};
+var index_default = ga4;
+export {
+  index_default as default,
+  ga4
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @junctionjs/destination-ga4\n *\n * Google Analytics 4 destination for Junction.\n *\n * Client-side: uses gtag.js (loaded lazily if not present)\n * Server-side: uses GA4 Measurement Protocol\n *\n * Handles Google's consent mode (v2) natively — when consent state\n * changes, we update gtag's consent settings automatically.\n */\n\nimport type { Destination, JctEvent, ConsentState } from \"@junctionjs/core\";\n\n// ─── Configuration ───────────────────────────────────────────────\n\nexport interface GA4Config {\n  /** GA4 Measurement ID (e.g., \"G-XXXXXXXXXX\") */\n  measurementId: string;\n\n  /** Server-side: GA4 Measurement Protocol API secret */\n  apiSecret?: string;\n\n  /** Whether to load gtag.js if not already present (default: true) */\n  loadScript?: boolean;\n\n  /** Custom gtag.js URL (for self-hosting or proxy) */\n  gtagUrl?: string;\n\n  /**\n   * Enable Google Consent Mode v2.\n   * When true, Junction's consent state maps to Google's consent categories.\n   */\n  consentMode?: boolean;\n\n  /** Send page_view events automatically (default: false — Junction handles this) */\n  sendPageView?: boolean;\n\n  /** Custom event name mapping */\n  eventNameMap?: Record<string, string>;\n\n  /** Custom parameter mapping */\n  parameterMap?: Record<string, string>;\n}\n\n// ─── Consent Mode Mapping ────────────────────────────────────────\n\n/**\n * Maps Junction consent categories to Google's consent mode signals.\n * Google's categories:\n *   - ad_storage (marketing)\n *   - analytics_storage (analytics)\n *   - ad_user_data (marketing)\n *   - ad_personalization (personalization)\n *   - personalization_storage (personalization)\n *   - functionality_storage (necessary)\n *   - security_storage (necessary)\n */\nfunction mapConsentToGoogle(state: ConsentState): Record<string, \"granted\" | \"denied\"> {\n  return {\n    ad_storage: state.marketing ? \"granted\" : \"denied\",\n    analytics_storage: state.analytics ? \"granted\" : \"denied\",\n    ad_user_data: state.marketing ? \"granted\" : \"denied\",\n    ad_personalization: state.personalization ? \"granted\" : \"denied\",\n    personalization_storage: state.personalization ? \"granted\" : \"denied\",\n    functionality_storage: state.necessary !== false ? \"granted\" : \"denied\",\n    security_storage: \"granted\", // always granted\n  };\n}\n\n// ─── GA4 Event Mapping ───────────────────────────────────────────\n\n/**\n * Maps Junction entity:action to GA4 recommended events where possible.\n * Falls back to custom event naming for non-standard events.\n *\n * https://developers.google.com/analytics/devguides/collection/ga4/reference/events\n */\nconst GA4_EVENT_MAP: Record<string, string> = {\n  \"page:viewed\": \"page_view\",\n  \"product:viewed\": \"view_item\",\n  \"product:added\": \"add_to_cart\",\n  \"product:removed\": \"remove_from_cart\",\n  \"product:list_viewed\": \"view_item_list\",\n  \"product:clicked\": \"select_item\",\n  \"cart:viewed\": \"view_cart\",\n  \"checkout:started\": \"begin_checkout\",\n  \"checkout:shipping_added\": \"add_shipping_info\",\n  \"checkout:payment_added\": \"add_payment_info\",\n  \"order:completed\": \"purchase\",\n  \"order:refunded\": \"refund\",\n  \"promotion:viewed\": \"view_promotion\",\n  \"promotion:clicked\": \"select_promotion\",\n  \"search:performed\": \"search\",\n  \"user:signed_up\": \"sign_up\",\n  \"user:logged_in\": \"login\",\n  \"content:shared\": \"share\",\n};\n\nfunction getGA4EventName(event: JctEvent, config: GA4Config): string {\n  const key = `${event.entity}:${event.action}`;\n\n  // Check custom mapping first, then default mapping, then generate\n  return (\n    config.eventNameMap?.[key] ??\n    GA4_EVENT_MAP[key] ??\n    `${event.entity}_${event.action}`\n  );\n}\n\n// ─── Parameter Mapping ───────────────────────────────────────────\n\n/**\n * Maps Junction properties to GA4 parameters.\n * GA4 has specific parameter names for e-commerce events.\n */\nconst GA4_PARAM_MAP: Record<string, string> = {\n  product_id: \"item_id\",\n  name: \"item_name\",\n  category: \"item_category\",\n  brand: \"item_brand\",\n  variant: \"item_variant\",\n  price: \"price\",\n  quantity: \"quantity\",\n  order_id: \"transaction_id\",\n  total: \"value\",\n  revenue: \"value\",\n  tax: \"tax\",\n  shipping: \"shipping\",\n  currency: \"currency\",\n  coupon: \"coupon\",\n  search_term: \"search_term\",\n};\n\nfunction mapParameters(\n  properties: Record<string, unknown>,\n  config: GA4Config,\n): Record<string, unknown> {\n  const mapped: Record<string, unknown> = {};\n\n  for (const [key, value] of Object.entries(properties)) {\n    const mappedKey = config.parameterMap?.[key] ?? GA4_PARAM_MAP[key] ?? key;\n    mapped[mappedKey] = value;\n  }\n\n  return mapped;\n}\n\n// ─── Transform ───────────────────────────────────────────────────\n\ninterface GA4Payload {\n  eventName: string;\n  parameters: Record<string, unknown>;\n}\n\nfunction transformEvent(event: JctEvent, config: GA4Config): GA4Payload {\n  return {\n    eventName: getGA4EventName(event, config),\n    parameters: mapParameters(event.properties, config),\n  };\n}\n\n// ─── gtag.js Loader ──────────────────────────────────────────────\n\nfunction loadGtag(measurementId: string, gtagUrl?: string): void {\n  if (typeof window === \"undefined\") return;\n  if (typeof (window as any).gtag === \"function\") return;\n\n  // Initialize dataLayer\n  (window as any).dataLayer = (window as any).dataLayer || [];\n  (window as any).gtag = function () {\n    (window as any).dataLayer.push(arguments);\n  };\n  (window as any).gtag(\"js\", new Date());\n\n  // Load script\n  const script = document.createElement(\"script\");\n  script.async = true;\n  script.src = gtagUrl ?? `https://www.googletagmanager.com/gtag/js?id=${measurementId}`;\n  document.head.appendChild(script);\n}\n\n// ─── Destination Export ──────────────────────────────────────────\n\nexport const ga4: Destination<GA4Config> = {\n  name: \"ga4\",\n  description: \"Google Analytics 4\",\n  version: \"0.1.0\",\n  consent: [\"analytics\"],\n  runtime: \"both\",\n\n  init(config: GA4Config) {\n    if (!config.measurementId) {\n      throw new Error(\"[Junction:GA4] measurementId is required\");\n    }\n\n    // Client-side: load gtag.js if needed\n    if (typeof window !== \"undefined\" && config.loadScript !== false) {\n      loadGtag(config.measurementId, config.gtagUrl);\n\n      // Configure GA4\n      const gtagConfig: Record<string, unknown> = {\n        send_page_view: config.sendPageView ?? false,\n      };\n\n      (window as any).gtag?.(\"config\", config.measurementId, gtagConfig);\n    }\n  },\n\n  transform(event: JctEvent) {\n    if (event.entity === \"_system\") return null;\n    return transformEvent(event, {} as GA4Config);\n  },\n\n  async send(payload: unknown, config: GA4Config) {\n    const ga4Payload = payload as GA4Payload;\n\n    if (typeof window !== \"undefined\" && typeof (window as any).gtag === \"function\") {\n      // Client-side: use gtag\n      (window as any).gtag(\"event\", ga4Payload.eventName, ga4Payload.parameters);\n    } else if (config.apiSecret) {\n      // Server-side: Measurement Protocol\n      const url = `https://www.google-analytics.com/mp/collect?measurement_id=${config.measurementId}&api_secret=${config.apiSecret}`;\n\n      await fetch(url, {\n        method: \"POST\",\n        body: JSON.stringify({\n          client_id: \"server\", // should be passed from client\n          events: [\n            {\n              name: ga4Payload.eventName,\n              params: ga4Payload.parameters,\n            },\n          ],\n        }),\n      });\n    }\n  },\n\n  onConsent(state: ConsentState) {\n    // Update Google Consent Mode\n    if (typeof window !== \"undefined\" && typeof (window as any).gtag === \"function\") {\n      (window as any).gtag(\"consent\", \"update\", mapConsentToGoogle(state));\n    }\n  },\n};\n\nexport default ga4;\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@junctionjs/destination-ga4",
+  "version": "0.1.0",
+  "description": "Google Analytics 4 destination for Junction — gtag.js, Measurement Protocol, Consent Mode v2",
+  "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-ga4"
+  },
+  "keywords": ["analytics", "google-analytics", "ga4", "junction-destination"]
+}