@nextlytics/core 0.2.2 → 0.3.0-canary.80

package/dist/api-handler.d.ts

@@ -0,0 +1,11 @@
+import { NextRequest } from 'next/server';
+import { NextlyticsEvent, RequestContext, PageViewDelivery, DispatchResult, UserContext } from './types.js';
+import { NextlyticsConfigWithDefaults } from './config-helpers.js';
+import 'next/dist/server/web/spec-extension/cookies';
+
+type DispatchEvent = (event: NextlyticsEvent, ctx: RequestContext, policyFilter?: PageViewDelivery | "client-actions") => DispatchResult;
+type UpdateEvent = (eventId: string, patch: Partial<NextlyticsEvent>, ctx: RequestContext) => Promise<void>;
+declare function getUserContext(config: NextlyticsConfigWithDefaults, ctx: RequestContext): Promise<UserContext | undefined>;
+declare function handleEventPost(request: NextRequest, config: NextlyticsConfigWithDefaults, dispatchEvent: DispatchEvent, updateEvent: UpdateEvent): Promise<Response>;
+
+export { type DispatchEvent, type UpdateEvent, getUserContext, handleEventPost };

package/dist/api-handler.js

@@ -0,0 +1,182 @@
+"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 api_handler_exports = {};
+__export(api_handler_exports, {
+  getUserContext: () => getUserContext,
+  handleEventPost: () => handleEventPost
+});
+module.exports = __toCommonJS(api_handler_exports);
+var import_server = require("next/server");
+var import_server_component_context = require("./server-component-context");
+var import_uitils = require("./uitils");
+var import_anonymous_user = require("./anonymous-user");
+function createRequestContext(request) {
+  return {
+    headers: request.headers,
+    cookies: request.cookies
+  };
+}
+async function getUserContext(config, ctx) {
+  if (!config.callbacks.getUser) return void 0;
+  try {
+    return await config.callbacks.getUser(ctx) || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function reconstructServerContext(apiCallContext, clientContext) {
+  const searchParams = {};
+  if (clientContext.search) {
+    const params = new URLSearchParams(clientContext.search);
+    params.forEach((value, key) => {
+      if (!searchParams[key]) searchParams[key] = [];
+      searchParams[key].push(value);
+    });
+  }
+  return {
+    ...apiCallContext,
+    host: clientContext.host || apiCallContext.host,
+    path: clientContext.path || apiCallContext.path,
+    search: Object.keys(searchParams).length > 0 ? searchParams : apiCallContext.search,
+    method: "GET"
+  };
+}
+function filterScripts(actions) {
+  const scripts = actions.items.filter((i) => i.type === "script-template");
+  return scripts.length > 0 ? scripts : void 0;
+}
+async function handleClientInit(request, hctx) {
+  const {
+    pageRenderId,
+    ctx,
+    apiCallServerContext,
+    userContext,
+    config,
+    dispatchEvent,
+    updateEvent
+  } = hctx;
+  const { clientContext } = request;
+  const serverContext = reconstructServerContext(apiCallServerContext, clientContext);
+  const { anonId: anonymousUserId } = await (0, import_anonymous_user.resolveAnonymousUser)({
+    ctx,
+    serverContext,
+    config
+  });
+  const isSoftNavigation = hctx.isSoftNavigation;
+  const eventId = isSoftNavigation ? (0, import_uitils.generateId)() : pageRenderId;
+  const event = {
+    origin: "client",
+    eventId,
+    parentEventId: isSoftNavigation ? pageRenderId : void 0,
+    type: "pageView",
+    collectedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    anonymousUserId,
+    serverContext,
+    clientContext,
+    userContext,
+    properties: {}
+  };
+  if (isSoftNavigation) {
+    const { clientActions, completion: completion2 } = dispatchEvent(event, ctx);
+    const actions = await clientActions;
+    (0, import_server.after)(() => completion2);
+    return Response.json({
+      ok: true,
+      items: filterScripts(actions)
+    });
+  }
+  const { completion } = dispatchEvent(event, ctx, "client-actions");
+  (0, import_server.after)(() => completion);
+  (0, import_server.after)(() => updateEvent(pageRenderId, { clientContext, userContext, anonymousUserId }, ctx));
+  return Response.json({ ok: true });
+}
+async function handleClientEvent(request, hctx) {
+  const { pageRenderId, ctx, apiCallServerContext, userContext, config, dispatchEvent } = hctx;
+  const { clientContext, name, props, collectedAt } = request;
+  const serverContext = clientContext ? reconstructServerContext(apiCallServerContext, clientContext) : apiCallServerContext;
+  const { anonId: anonymousUserId } = await (0, import_anonymous_user.resolveAnonymousUser)({
+    ctx,
+    serverContext,
+    config
+  });
+  const event = {
+    origin: "client",
+    eventId: (0, import_uitils.generateId)(),
+    parentEventId: pageRenderId,
+    type: name,
+    collectedAt: collectedAt || (/* @__PURE__ */ new Date()).toISOString(),
+    anonymousUserId,
+    serverContext,
+    clientContext,
+    userContext,
+    properties: props || {}
+  };
+  const { clientActions, completion } = dispatchEvent(event, ctx);
+  const actions = await clientActions;
+  (0, import_server.after)(() => completion);
+  return Response.json({ ok: true, items: filterScripts(actions) });
+}
+async function handleEventPost(request, config, dispatchEvent, updateEvent) {
+  const softNavHeader = request.headers.get(import_server_component_context.headerNames.isSoftNavigation);
+  const isSoftNavigation = softNavHeader === "1";
+  const pageRenderIdHeader = request.headers.get(import_server_component_context.headerNames.pageRenderId);
+  if (!pageRenderIdHeader) {
+    return Response.json({ error: "Missing page render ID" }, { status: 400 });
+  }
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return Response.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  const ctx = createRequestContext(request);
+  const apiCallServerContext = (0, import_uitils.createServerContext)(request);
+  const userContext = await getUserContext(config, ctx);
+  const cookiePageRenderId = request.cookies.get(import_server_component_context.LAST_PAGE_RENDER_ID_COOKIE)?.value;
+  const pageRenderId = isSoftNavigation ? cookiePageRenderId ?? (0, import_uitils.generateId)() : pageRenderIdHeader;
+  if (isSoftNavigation && !cookiePageRenderId && config.debug) {
+    console.warn(
+      "[Nextlytics] Missing last-page-render-id cookie on soft navigation; using a new id."
+    );
+  }
+  const hctx = {
+    pageRenderId,
+    isSoftNavigation,
+    ctx,
+    apiCallServerContext,
+    userContext,
+    config,
+    dispatchEvent,
+    updateEvent
+  };
+  const bodyType = body.type;
+  switch (bodyType) {
+    case "page-view":
+      return handleClientInit(body, hctx);
+    case "custom-event":
+      return handleClientEvent(body, hctx);
+    default:
+      return Response.json({ ok: false, error: `Unknown body type ${bodyType}` }, { status: 400 });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getUserContext,
+  handleEventPost
+});

package/dist/backends/ga.d.ts

@@ -15,6 +15,11 @@ type GoogleAnalyticsBackendOptions = {
      * - "anonymousUserId": Always use Nextlytics anonymousUserId
      */
     clientIdSource?: "gaCookie" | "anonymousUserId";
+    /**
+     * Prefer sending client-origin events from the browser (gtag) instead of Measurement Protocol.
+     * Default: true. Set to false to force Measurement Protocol when apiSecret is provided.
+     */
+    preferClientSideForClientEvents?: boolean;
 };
 declare function googleAnalyticsBackend(opts: GoogleAnalyticsBackendOptions): NextlyticsBackendFactory;
 

package/dist/backends/ga.js

@@ -21,7 +21,9 @@ __export(ga_exports, {
   googleAnalyticsBackend: () => googleAnalyticsBackend
 });
 module.exports = __toCommonJS(ga_exports);
-const GA_TEMPLATE_ID = "ga-gtag";
+const GA_INIT_TEMPLATE = "ga-gtag";
+const GA_PROPERTIES_TEMPLATE = "ga-properties";
+const GA_EVENT_TEMPLATE = "ga-event";
 function parseGaCookie(cookieValue) {
   const match = cookieValue.match(/^GA\d+\.\d+\.(.+)$/);
   return match ? match[1] : null;
@@ -118,27 +120,51 @@ function googleAnalyticsBackend(opts) {
   return (ctx) => {
     const gaCookie = ctx.cookies.get("_ga");
     const gaCookieClientId = gaCookie ? parseGaCookie(gaCookie.value) : null;
+    const preferClientSideForClientEvents = opts.preferClientSideForClientEvents ?? true;
     return {
       name: "google-analytics",
       returnsClientActions: true,
       supportsUpdates: false,
       getClientSideTemplates() {
         return {
-          [GA_TEMPLATE_ID]: {
+          [GA_EVENT_TEMPLATE]: {
+            deps: "{{eventId}}",
             items: [
+              // Update user properties for this event (if provided)
+              {
+                body: [
+                  "gtag('set', {{json(properties)}});",
+                  "gtag('event', '{{eventName}}', {{json(eventParams)}});"
+                ]
+              }
+            ]
+          },
+          [GA_INIT_TEMPLATE]: {
+            deps: "{{measurementId}}{{json(initial_config)}}",
+            items: [
+              // External gtag.js - load once
               {
-                async: "true",
                 src: "https://www.googletagmanager.com/gtag/js?id={{measurementId}}",
-                singleton: true
+                async: true
               },
+              // gtag definition and initialization - run once
               {
                 body: [
                   "window.dataLayer = window.dataLayer || [];",
-                  "function gtag(){dataLayer.push(arguments);}",
+                  opts.debugMode ? "function gtag(){ console.log('[gtag() call]', arguments); dataLayer.push(arguments); }" : "function gtag(){dataLayer.push(arguments);}",
+                  "window.gtag = gtag;",
                   "gtag('js', new Date());",
-                  "gtag('config', '{{measurementId}}', {{json(config)}});",
-                  "gtag('event', 'page_view');"
-                ].join("\n")
+                  "gtag('config', '{{measurementId}}', {{json(initial_config)}});"
+                ]
+              }
+            ]
+          },
+          [GA_PROPERTIES_TEMPLATE]: {
+            deps: "{{json(properties)}}",
+            items: [
+              // Updates that should NOT trigger page_view (e.g., user_id, user_properties)
+              {
+                body: "gtag('set', {{json(properties)}});"
               }
             ]
           }
@@ -155,33 +181,66 @@ function googleAnalyticsBackend(opts) {
         } = event.userContext?.traits ?? {};
         const userProperties = Object.keys(customTraits).length > 0 ? customTraits : void 0;
         if (event.type === "pageView") {
-          const config = {
-            send_page_view: false,
+          const initial_config = {
+            // Rely on GA auto page_view (including SPA history changes).
+            send_page_view: true,
             client_id: clientId
           };
           if (debugMode) {
-            config.debug_mode = true;
+            initial_config.debug_mode = true;
           }
+          const properties2 = {};
           if (userId) {
-            config.user_id = userId;
+            properties2.user_id = userId;
           }
           if (userProperties) {
-            config.user_properties = userProperties;
+            properties2.user_properties = userProperties;
           }
           return {
             items: [
               {
                 type: "script-template",
-                templateId: GA_TEMPLATE_ID,
+                templateId: GA_INIT_TEMPLATE,
                 params: {
                   measurementId,
-                  config
+                  initial_config
+                }
+              },
+              {
+                type: "script-template",
+                templateId: GA_PROPERTIES_TEMPLATE,
+                params: {
+                  properties: properties2
                 }
               }
             ]
           };
         }
-        if (apiSecret) {
+        const eventParams = buildEventParams(event);
+        const properties = {};
+        if (userId) {
+          properties.user_id = userId;
+        }
+        if (userProperties) {
+          properties.user_properties = userProperties;
+        }
+        if (event.origin === "client") {
+          if (preferClientSideForClientEvents || !apiSecret) {
+            return {
+              items: [
+                {
+                  type: "script-template",
+                  templateId: GA_EVENT_TEMPLATE,
+                  params: {
+                    eventId: event.eventId,
+                    eventName: toGA4EventName(event.type),
+                    eventParams,
+                    properties
+                  }
+                }
+              ]
+            };
+          }
           await sendToMeasurementProtocol({
             measurementId,
             apiSecret,
@@ -189,12 +248,29 @@ function googleAnalyticsBackend(opts) {
             userId,
             userProperties,
             eventName: toGA4EventName(event.type),
-            eventParams: buildEventParams(event),
+            eventParams,
             userAgent: getUserAgent(event),
             clientIp: getClientIp(event),
             debugMode
           });
+          return void 0;
+        }
+        if (!apiSecret) {
+          return void 0;
         }
+        await sendToMeasurementProtocol({
+          measurementId,
+          apiSecret,
+          clientId,
+          userId,
+          userProperties,
+          eventName: toGA4EventName(event.type),
+          eventParams,
+          userAgent: getUserAgent(event),
+          clientIp: getClientIp(event),
+          debugMode
+        });
+        return void 0;
       },
       updateEvent() {
       }

package/dist/backends/gtm.js

@@ -22,6 +22,7 @@ __export(gtm_exports, {
 });
 module.exports = __toCommonJS(gtm_exports);
 const GTM_INIT_TEMPLATE_ID = "gtm-init";
+const GTM_INIT_DATA_TEMPLATE_ID = "gtm-init-data";
 const GTM_PAGEVIEW_TEMPLATE_ID = "gtm-pageview";
 const GTM_EVENT_TEMPLATE_ID = "gtm-event";
 function toSnakeCase(str) {
@@ -37,21 +38,27 @@ function googleTagManagerBackend(opts) {
       return {
         [GTM_INIT_TEMPLATE_ID]: {
           items: [
+            // GTM script loader - run once
             {
               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}}');",
-                "}"
+                "(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_INIT_DATA_TEMPLATE_ID]: {
+          items: [
+            // Initial data push - run when params change (e.g., user logs in)
+            {
+              body: "dataLayer.push({{json(initialData)}});"
+            }
+          ]
+        },
         [GTM_PAGEVIEW_TEMPLATE_ID]: {
           items: [
             {
@@ -122,6 +129,11 @@ function googleTagManagerBackend(opts) {
       if (event.clientContext) {
         return {
           items: [
+            {
+              type: "script-template",
+              templateId: GTM_INIT_DATA_TEMPLATE_ID,
+              params: { initialData }
+            },
             {
               type: "script-template",
               templateId: GTM_PAGEVIEW_TEMPLATE_ID,
@@ -137,6 +149,11 @@ function googleTagManagerBackend(opts) {
             templateId: GTM_INIT_TEMPLATE_ID,
             params: { containerId, initialData }
           },
+          {
+            type: "script-template",
+            templateId: GTM_INIT_DATA_TEMPLATE_ID,
+            params: { initialData }
+          },
           {
             type: "script-template",
             templateId: GTM_PAGEVIEW_TEMPLATE_ID,

package/dist/backends/logging.js

@@ -21,10 +21,24 @@ __export(logging_exports, {
   loggingBackend: () => loggingBackend
 });
 module.exports = __toCommonJS(logging_exports);
+const LOG_TEMPLATE_ID = "log-console";
 function loggingBackend() {
   return {
     name: "logging",
     supportsUpdates: true,
+    returnsClientActions: true,
+    getClientSideTemplates() {
+      return {
+        [LOG_TEMPLATE_ID]: {
+          deps: "{{eventId}}",
+          items: [
+            {
+              body: "console.log('[Nextlytics Log][client]', {{json(event)}});"
+            }
+          ]
+        }
+      };
+    },
     async onEvent(event) {
       const { type, eventId, serverContext, ...rest } = event;
       const method = serverContext?.method || "";
@@ -32,6 +46,25 @@ function loggingBackend() {
       const route = method && path ? `${method} ${path}` : "";
       console.log(`[Nextlytics Log] ${type}${route ? ` ${route}` : ""} (${eventId})`);
       console.log(JSON.stringify({ serverContext, ...rest }, null, 2));
+      if (event.origin === "client") {
+        return {
+          items: [
+            {
+              type: "script-template",
+              templateId: LOG_TEMPLATE_ID,
+              params: {
+                eventId: event.eventId,
+                event: {
+                  type: event.type,
+                  eventProps: event.properties,
+                  userProps: event.userContext
+                }
+              }
+            }
+          ]
+        };
+      }
+      return void 0;
     },
     updateEvent(eventId, patch) {
       console.log(`[Nextlytics Log] Update ${eventId}`);

package/dist/backends/segment.js

@@ -37,6 +37,25 @@ function segmentBackend(config) {
       throw new Error(`Segment error ${res.status}: ${text}`);
     }
   }
+  function buildUrl(event) {
+    if (event.clientContext?.url) return event.clientContext.url;
+    const { host: host2, path, search } = event.serverContext;
+    const protocol = host2.includes("localhost") || host2.match(/^[\d.:]+$/) ? "http" : "https";
+    const searchStr = Object.entries(search).flatMap(([k, vals]) => vals.map((v) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)).join("&");
+    return `${protocol}://${host2}${path}${searchStr ? `?${searchStr}` : ""}`;
+  }
+  function getSearchString(event) {
+    if (event.clientContext?.search) return event.clientContext.search;
+    return Object.entries(event.serverContext.search).flatMap(([k, vals]) => vals.map((v) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)).join("&");
+  }
+  function getReferringDomain(referer) {
+    if (!referer) return void 0;
+    try {
+      return new URL(referer).hostname;
+    } catch {
+      return void 0;
+    }
+  }
   function buildContext(event) {
     const ctx = {
       ip: event.serverContext.ip
@@ -44,32 +63,45 @@ function segmentBackend(config) {
     if (event.userContext?.traits) {
       ctx.traits = event.userContext.traits;
     }
-    if (event.clientContext) {
-      ctx.userAgent = event.clientContext.userAgent;
-      ctx.locale = event.clientContext.locale;
-      ctx.page = {
-        path: event.clientContext.path,
-        referrer: event.clientContext.referer
-      };
-      if (event.clientContext.screen) {
+    const cc = event.clientContext;
+    const sc = event.serverContext;
+    ctx.page = {
+      path: cc?.path ?? sc.path,
+      referrer: cc?.referer,
+      referring_domain: getReferringDomain(cc?.referer),
+      host: cc?.host ?? sc.host,
+      search: getSearchString(event),
+      title: cc?.title,
+      url: buildUrl(event)
+    };
+    if (cc) {
+      ctx.userAgent = cc.userAgent;
+      ctx.locale = cc.locale;
+      if (cc.screen) {
         ctx.screen = {
-          width: event.clientContext.screen.width,
-          height: event.clientContext.screen.height,
-          innerWidth: event.clientContext.screen.innerWidth,
-          innerHeight: event.clientContext.screen.innerHeight,
-          density: event.clientContext.screen.density
+          width: cc.screen.width,
+          height: cc.screen.height,
+          innerWidth: cc.screen.innerWidth,
+          innerHeight: cc.screen.innerHeight,
+          density: cc.screen.density
         };
       }
     }
     return ctx;
   }
   function buildProperties(event) {
+    const cc = event.clientContext;
+    const sc = event.serverContext;
     return {
       parentEventId: event.parentEventId,
-      path: event.serverContext.path,
-      host: event.serverContext.host,
-      method: event.serverContext.method,
-      search: event.serverContext.search,
+      path: cc?.path ?? sc.path,
+      url: buildUrl(event),
+      search: getSearchString(event),
+      hash: cc?.hash,
+      title: cc?.title,
+      referrer: cc?.referer,
+      width: cc?.screen?.innerWidth,
+      height: cc?.screen?.innerHeight,
       ...event.properties
     };
   }
@@ -92,6 +124,7 @@ function segmentBackend(config) {
       } else {
         await send([{ type: "track", event: event.type, ...basePayload }]);
       }
+      return void 0;
     },
     updateEvent() {
     }

package/dist/client-utils.d.ts

@@ -0,0 +1,35 @@
+import * as react from 'react';
+
+declare const debug: (...args: unknown[]) => void;
+type NavigationEvent = {
+    softNavigation: boolean;
+    signal?: AbortSignal;
+};
+declare function usePathnameSafe(): string | null;
+/**
+ * Hook that detects page navigations and calls the callback once per navigation.
+ *
+ * - App Router: initial load = hard nav, subsequent pathname changes = soft nav
+ * - Pages Router: every navigation changes requestId = always hard nav
+ *
+ * Provides an AbortSignal for soft navigations to cancel in-flight requests.
+ */
+declare function useNavigation(requestId: string, onNavigate: (event: NavigationEvent) => void): void;
+/** Props for the InjectScript utility component */
+type InjectScriptProps = {
+    /** Inline script body (mutually exclusive with src) */
+    body?: string;
+    /** External script URL (mutually exclusive with body) */
+    src?: string;
+    /** Load external script async */
+    async?: boolean;
+    /** Dependencies that control re-injection. Empty/undefined = once, changes trigger re-injection */
+    deps?: unknown[];
+};
+/**
+ * Pure utility component that injects a script into the document head.
+ * Agnostic to templates, combining logic - just handles the injection lifecycle.
+ */
+declare const InjectScript: react.NamedExoticComponent<InjectScriptProps>;
+
+export { InjectScript, type InjectScriptProps, type NavigationEvent, debug, useNavigation, usePathnameSafe };