@nextlytics/core 0.1.0-canary-1

package/dist/backends/ga.cjs

@@ -0,0 +1,207 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ga_exports = {};
+__export(ga_exports, {
+  googleAnalyticsBackend: () => googleAnalyticsBackend
+});
+module.exports = __toCommonJS(ga_exports);
+const GA_TEMPLATE_ID = "ga-gtag";
+function parseGaCookie(cookieValue) {
+  const match = cookieValue.match(/^GA\d+\.\d+\.(.+)$/);
+  return match ? match[1] : null;
+}
+function getClientId(event, gaCookieClientId, source) {
+  if (source === "gaCookie" && gaCookieClientId) {
+    return gaCookieClientId;
+  }
+  if (!event.anonymousUserId) {
+    throw new Error("anonymousUserId is required for GA backend (no _ga cookie available)");
+  }
+  return event.anonymousUserId;
+}
+function toGA4EventName(type) {
+  if (type === "pageView") return "page_view";
+  if (type === "apiCall") return "api_call";
+  return type.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
+}
+function buildEventParams(event) {
+  const params = {
+    // Required for engagement metrics
+    engagement_time_msec: 1
+  };
+  const { serverContext } = event;
+  if (serverContext) {
+    params.page_location = `https://${serverContext.host}${serverContext.path}`;
+  }
+  const { clientContext } = event;
+  if (clientContext) {
+    if (clientContext.referer) {
+      params.page_referrer = clientContext.referer;
+    }
+    if (clientContext.locale) {
+      params.language = clientContext.locale;
+    }
+    if (clientContext.screen?.width && clientContext.screen?.height) {
+      params.screen_resolution = `${clientContext.screen.width}x${clientContext.screen.height}`;
+    }
+  }
+  if (event.properties) {
+    Object.assign(params, event.properties);
+  }
+  return params;
+}
+function getUserAgent(event) {
+  return event.clientContext?.userAgent ?? event.serverContext?.requestHeaders?.["user-agent"];
+}
+function getClientIp(event) {
+  return event.serverContext?.ip;
+}
+async function sendToMeasurementProtocol(opts) {
+  const endpoint = opts.debugMode ? "https://www.google-analytics.com/debug/mp/collect" : "https://www.google-analytics.com/mp/collect";
+  const url = `${endpoint}?measurement_id=${opts.measurementId}&api_secret=${opts.apiSecret}`;
+  const payload = {
+    client_id: opts.clientId,
+    events: [
+      {
+        name: opts.eventName,
+        params: opts.eventParams
+      }
+    ]
+  };
+  if (opts.userId) {
+    payload.user_id = opts.userId;
+  }
+  if (opts.userProperties && Object.keys(opts.userProperties).length > 0) {
+    payload.user_properties = Object.fromEntries(
+      Object.entries(opts.userProperties).map(([k, v]) => [k, { value: v }])
+    );
+  }
+  const headers = {};
+  if (opts.userAgent) {
+    headers["User-Agent"] = opts.userAgent;
+  }
+  if (opts.clientIp) {
+    headers["X-Forwarded-For"] = opts.clientIp;
+  }
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      body: JSON.stringify(payload),
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      console.warn(`[GA] Measurement Protocol error: ${res.status} ${res.statusText}`, body);
+    }
+  } catch (err) {
+    console.warn("[GA] Measurement Protocol request failed:", err);
+  }
+}
+function googleAnalyticsBackend(opts) {
+  const { measurementId, debugMode, apiSecret, clientIdSource = "gaCookie" } = opts;
+  return (ctx) => {
+    const gaCookie = ctx.cookies.get("_ga");
+    const gaCookieClientId = gaCookie ? parseGaCookie(gaCookie.value) : null;
+    return {
+      name: "google-analytics",
+      returnsClientActions: true,
+      supportsUpdates: false,
+      getClientSideTemplates() {
+        return {
+          [GA_TEMPLATE_ID]: {
+            items: [
+              {
+                async: "true",
+                src: "https://www.googletagmanager.com/gtag/js?id={{measurementId}}",
+                singleton: true
+              },
+              {
+                body: [
+                  "window.dataLayer = window.dataLayer || [];",
+                  "function gtag(){dataLayer.push(arguments);}",
+                  "gtag('js', new Date());",
+                  "gtag('config', '{{measurementId}}', {{json(config)}});",
+                  "gtag('event', 'page_view');"
+                ].join("\n")
+              }
+            ]
+          }
+        };
+      },
+      async onEvent(event) {
+        const clientId = getClientId(event, gaCookieClientId, clientIdSource);
+        const userId = event.userContext?.userId;
+        const {
+          email: _email,
+          name: _name,
+          phone: _phone,
+          ...customTraits
+        } = event.userContext?.traits ?? {};
+        const userProperties = Object.keys(customTraits).length > 0 ? customTraits : void 0;
+        if (event.type === "pageView") {
+          const config = {
+            send_page_view: false,
+            client_id: clientId
+          };
+          if (debugMode) {
+            config.debug_mode = true;
+          }
+          if (userId) {
+            config.user_id = userId;
+          }
+          if (userProperties) {
+            config.user_properties = userProperties;
+          }
+          return {
+            items: [
+              {
+                type: "script-template",
+                templateId: GA_TEMPLATE_ID,
+                params: {
+                  measurementId,
+                  config
+                }
+              }
+            ]
+          };
+        }
+        if (apiSecret) {
+          await sendToMeasurementProtocol({
+            measurementId,
+            apiSecret,
+            clientId,
+            userId,
+            userProperties,
+            eventName: toGA4EventName(event.type),
+            eventParams: buildEventParams(event),
+            userAgent: getUserAgent(event),
+            clientIp: getClientIp(event),
+            debugMode
+          });
+        }
+      },
+      updateEvent() {
+      }
+    };
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  googleAnalyticsBackend
+});

package/dist/backends/ga.d.mts

@@ -0,0 +1,21 @@
+import { NextlyticsBackendFactory } from '../types.mjs';
+import 'next/dist/server/web/spec-extension/cookies';
+import 'next/server';
+
+type GoogleAnalyticsBackendOptions = {
+    /** GA4 Measurement ID (e.g. "G-XXXXXXXXXX") */
+    measurementId: string;
+    /** Enable GA4 debug mode (shows events in DebugView) */
+    debugMode?: boolean;
+    /** API secret for Measurement Protocol (GA4 Admin → Data Streams → MP secrets) */
+    apiSecret?: string;
+    /**
+     * Source for client_id.
+     * - "gaCookie" (default): Use _ga cookie set by gtag.js, fall back to anonymousUserId
+     * - "anonymousUserId": Always use Nextlytics anonymousUserId
+     */
+    clientIdSource?: "gaCookie" | "anonymousUserId";
+};
+declare function googleAnalyticsBackend(opts: GoogleAnalyticsBackendOptions): NextlyticsBackendFactory;
+
+export { type GoogleAnalyticsBackendOptions, googleAnalyticsBackend };

package/dist/backends/ga.d.ts

@@ -0,0 +1,21 @@
+import { NextlyticsBackendFactory } from '../types.js';
+import 'next/dist/server/web/spec-extension/cookies';
+import 'next/server';
+
+type GoogleAnalyticsBackendOptions = {
+    /** GA4 Measurement ID (e.g. "G-XXXXXXXXXX") */
+    measurementId: string;
+    /** Enable GA4 debug mode (shows events in DebugView) */
+    debugMode?: boolean;
+    /** API secret for Measurement Protocol (GA4 Admin → Data Streams → MP secrets) */
+    apiSecret?: string;
+    /**
+     * Source for client_id.
+     * - "gaCookie" (default): Use _ga cookie set by gtag.js, fall back to anonymousUserId
+     * - "anonymousUserId": Always use Nextlytics anonymousUserId
+     */
+    clientIdSource?: "gaCookie" | "anonymousUserId";
+};
+declare function googleAnalyticsBackend(opts: GoogleAnalyticsBackendOptions): NextlyticsBackendFactory;
+
+export { type GoogleAnalyticsBackendOptions, googleAnalyticsBackend };

package/dist/backends/ga.js

@@ -0,0 +1,183 @@
+const GA_TEMPLATE_ID = "ga-gtag";
+function parseGaCookie(cookieValue) {
+  const match = cookieValue.match(/^GA\d+\.\d+\.(.+)$/);
+  return match ? match[1] : null;
+}
+function getClientId(event, gaCookieClientId, source) {
+  if (source === "gaCookie" && gaCookieClientId) {
+    return gaCookieClientId;
+  }
+  if (!event.anonymousUserId) {
+    throw new Error("anonymousUserId is required for GA backend (no _ga cookie available)");
+  }
+  return event.anonymousUserId;
+}
+function toGA4EventName(type) {
+  if (type === "pageView") return "page_view";
+  if (type === "apiCall") return "api_call";
+  return type.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
+}
+function buildEventParams(event) {
+  const params = {
+    // Required for engagement metrics
+    engagement_time_msec: 1
+  };
+  const { serverContext } = event;
+  if (serverContext) {
+    params.page_location = `https://${serverContext.host}${serverContext.path}`;
+  }
+  const { clientContext } = event;
+  if (clientContext) {
+    if (clientContext.referer) {
+      params.page_referrer = clientContext.referer;
+    }
+    if (clientContext.locale) {
+      params.language = clientContext.locale;
+    }
+    if (clientContext.screen?.width && clientContext.screen?.height) {
+      params.screen_resolution = `${clientContext.screen.width}x${clientContext.screen.height}`;
+    }
+  }
+  if (event.properties) {
+    Object.assign(params, event.properties);
+  }
+  return params;
+}
+function getUserAgent(event) {
+  return event.clientContext?.userAgent ?? event.serverContext?.requestHeaders?.["user-agent"];
+}
+function getClientIp(event) {
+  return event.serverContext?.ip;
+}
+async function sendToMeasurementProtocol(opts) {
+  const endpoint = opts.debugMode ? "https://www.google-analytics.com/debug/mp/collect" : "https://www.google-analytics.com/mp/collect";
+  const url = `${endpoint}?measurement_id=${opts.measurementId}&api_secret=${opts.apiSecret}`;
+  const payload = {
+    client_id: opts.clientId,
+    events: [
+      {
+        name: opts.eventName,
+        params: opts.eventParams
+      }
+    ]
+  };
+  if (opts.userId) {
+    payload.user_id = opts.userId;
+  }
+  if (opts.userProperties && Object.keys(opts.userProperties).length > 0) {
+    payload.user_properties = Object.fromEntries(
+      Object.entries(opts.userProperties).map(([k, v]) => [k, { value: v }])
+    );
+  }
+  const headers = {};
+  if (opts.userAgent) {
+    headers["User-Agent"] = opts.userAgent;
+  }
+  if (opts.clientIp) {
+    headers["X-Forwarded-For"] = opts.clientIp;
+  }
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      body: JSON.stringify(payload),
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      console.warn(`[GA] Measurement Protocol error: ${res.status} ${res.statusText}`, body);
+    }
+  } catch (err) {
+    console.warn("[GA] Measurement Protocol request failed:", err);
+  }
+}
+function googleAnalyticsBackend(opts) {
+  const { measurementId, debugMode, apiSecret, clientIdSource = "gaCookie" } = opts;
+  return (ctx) => {
+    const gaCookie = ctx.cookies.get("_ga");
+    const gaCookieClientId = gaCookie ? parseGaCookie(gaCookie.value) : null;
+    return {
+      name: "google-analytics",
+      returnsClientActions: true,
+      supportsUpdates: false,
+      getClientSideTemplates() {
+        return {
+          [GA_TEMPLATE_ID]: {
+            items: [
+              {
+                async: "true",
+                src: "https://www.googletagmanager.com/gtag/js?id={{measurementId}}",
+                singleton: true
+              },
+              {
+                body: [
+                  "window.dataLayer = window.dataLayer || [];",
+                  "function gtag(){dataLayer.push(arguments);}",
+                  "gtag('js', new Date());",
+                  "gtag('config', '{{measurementId}}', {{json(config)}});",
+                  "gtag('event', 'page_view');"
+                ].join("\n")
+              }
+            ]
+          }
+        };
+      },
+      async onEvent(event) {
+        const clientId = getClientId(event, gaCookieClientId, clientIdSource);
+        const userId = event.userContext?.userId;
+        const {
+          email: _email,
+          name: _name,
+          phone: _phone,
+          ...customTraits
+        } = event.userContext?.traits ?? {};
+        const userProperties = Object.keys(customTraits).length > 0 ? customTraits : void 0;
+        if (event.type === "pageView") {
+          const config = {
+            send_page_view: false,
+            client_id: clientId
+          };
+          if (debugMode) {
+            config.debug_mode = true;
+          }
+          if (userId) {
+            config.user_id = userId;
+          }
+          if (userProperties) {
+            config.user_properties = userProperties;
+          }
+          return {
+            items: [
+              {
+                type: "script-template",
+                templateId: GA_TEMPLATE_ID,
+                params: {
+                  measurementId,
+                  config
+                }
+              }
+            ]
+          };
+        }
+        if (apiSecret) {
+          await sendToMeasurementProtocol({
+            measurementId,
+            apiSecret,
+            clientId,
+            userId,
+            userProperties,
+            eventName: toGA4EventName(event.type),
+            eventParams: buildEventParams(event),
+            userAgent: getUserAgent(event),
+            clientIp: getClientIp(event),
+            debugMode
+          });
+        }
+      },
+      updateEvent() {
+      }
+    };
+  };
+}
+export {
+  googleAnalyticsBackend
+};

package/dist/backends/gtm.cjs

@@ -0,0 +1,155 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var gtm_exports = {};
+__export(gtm_exports, {
+  googleTagManagerBackend: () => googleTagManagerBackend
+});
+module.exports = __toCommonJS(gtm_exports);
+const GTM_INIT_TEMPLATE_ID = "gtm-init";
+const GTM_PAGEVIEW_TEMPLATE_ID = "gtm-pageview";
+const GTM_EVENT_TEMPLATE_ID = "gtm-event";
+function toSnakeCase(str) {
+  return str.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
+}
+function googleTagManagerBackend(opts) {
+  const { containerId } = opts;
+  return {
+    name: "google-tag-manager",
+    returnsClientActions: true,
+    supportsUpdates: false,
+    getClientSideTemplates() {
+      return {
+        [GTM_INIT_TEMPLATE_ID]: {
+          items: [
+            {
+              body: [
+                "window.dataLayer = window.dataLayer || [];",
+                "dataLayer.push({{json(initialData)}});",
+                "if (!window.google_tag_manager || !window.google_tag_manager['{{containerId}}']) {",
+                "  (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':",
+                "  new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],",
+                "  j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=",
+                "  'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);",
+                "  })(window,document,'script','dataLayer','{{containerId}}');",
+                "}"
+              ].join("\n")
+            }
+          ]
+        },
+        [GTM_PAGEVIEW_TEMPLATE_ID]: {
+          items: [
+            {
+              body: [
+                "window.dataLayer = window.dataLayer || [];",
+                "dataLayer.push({{json(pageData)}});"
+              ].join("\n")
+            }
+          ]
+        },
+        [GTM_EVENT_TEMPLATE_ID]: {
+          items: [
+            {
+              body: [
+                "window.dataLayer = window.dataLayer || [];",
+                "dataLayer.push({{json(eventData)}});"
+              ].join("\n")
+            }
+          ]
+        }
+      };
+    },
+    async onEvent(event) {
+      if (event.type !== "pageView") {
+        const eventData = {
+          event: toSnakeCase(event.type),
+          eventId: event.eventId,
+          ...event.properties
+        };
+        if (event.userContext?.userId) {
+          eventData.userId = event.userContext.userId;
+        }
+        if (event.anonymousUserId) {
+          eventData.anonymousUserId = event.anonymousUserId;
+        }
+        const traits2 = event.userContext?.traits;
+        if (traits2 && Object.keys(traits2).length > 0) {
+          eventData.userTraits = traits2;
+        }
+        return {
+          items: [
+            {
+              type: "script-template",
+              templateId: GTM_EVENT_TEMPLATE_ID,
+              params: { eventData }
+            }
+          ]
+        };
+      }
+      const initialData = {};
+      if (event.userContext?.userId) {
+        initialData.userId = event.userContext.userId;
+      }
+      if (event.anonymousUserId) {
+        initialData.anonymousUserId = event.anonymousUserId;
+      }
+      const traits = event.userContext?.traits;
+      if (traits && Object.keys(traits).length > 0) {
+        initialData.userTraits = traits;
+      }
+      const pageData = {
+        event: "page_view",
+        eventId: event.eventId,
+        page_path: event.serverContext.path,
+        page_title: event.properties.title ?? void 0,
+        page_location: `${event.serverContext.host}${event.serverContext.path}`
+      };
+      if (event.clientContext) {
+        return {
+          items: [
+            {
+              type: "script-template",
+              templateId: GTM_PAGEVIEW_TEMPLATE_ID,
+              params: { pageData }
+            }
+          ]
+        };
+      }
+      return {
+        items: [
+          {
+            type: "script-template",
+            templateId: GTM_INIT_TEMPLATE_ID,
+            params: { containerId, initialData }
+          },
+          {
+            type: "script-template",
+            templateId: GTM_PAGEVIEW_TEMPLATE_ID,
+            params: { pageData }
+          }
+        ]
+      };
+    },
+    updateEvent() {
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  googleTagManagerBackend
+});

package/dist/backends/gtm.d.mts

@@ -0,0 +1,11 @@
+import { NextlyticsBackend } from '../types.mjs';
+import 'next/dist/server/web/spec-extension/cookies';
+import 'next/server';
+
+type GoogleTagManagerBackendOptions = {
+    /** GTM Container ID (e.g. "GTM-XXXXXXX") */
+    containerId: string;
+};
+declare function googleTagManagerBackend(opts: GoogleTagManagerBackendOptions): NextlyticsBackend;
+
+export { type GoogleTagManagerBackendOptions, googleTagManagerBackend };

package/dist/backends/gtm.d.ts

@@ -0,0 +1,11 @@
+import { NextlyticsBackend } from '../types.js';
+import 'next/dist/server/web/spec-extension/cookies';
+import 'next/server';
+
+type GoogleTagManagerBackendOptions = {
+    /** GTM Container ID (e.g. "GTM-XXXXXXX") */
+    containerId: string;
+};
+declare function googleTagManagerBackend(opts: GoogleTagManagerBackendOptions): NextlyticsBackend;
+
+export { type GoogleTagManagerBackendOptions, googleTagManagerBackend };