@nextlytics/core 0.3.0 → 0.3.1

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/neon.js

@@ -73,10 +73,17 @@ function neonBackend(config) {
       }
       if (sets.length > 0) {
         params.push(eventId);
-        await sql.query(
-          `UPDATE ${table} SET ${sets.join(", ")} WHERE event_id = $${paramIndex}`,
-          params
-        );
+        try {
+          await sql.query(
+            `UPDATE ${table} SET ${sets.join(", ")} WHERE event_id = $${paramIndex}`,
+            params
+          );
+        } catch (err) {
+          if ((0, import_db.isPgTableNotFoundError)(err)) {
+            printCreateTableStatement();
+          }
+          throw err;
+        }
       }
     }
   };

package/dist/backends/segment.js

@@ -124,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 };

package/dist/client-utils.js

@@ -0,0 +1,121 @@
+"use strict";
+"use client";
+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 client_utils_exports = {};
+__export(client_utils_exports, {
+  InjectScript: () => InjectScript,
+  debug: () => debug,
+  useNavigation: () => useNavigation,
+  usePathnameSafe: () => usePathnameSafe
+});
+module.exports = __toCommonJS(client_utils_exports);
+var import_react = require("react");
+const DEBUG_KEY = "nextlytics:debug";
+function isDebugEnabled() {
+  if (typeof window === "undefined") return false;
+  try {
+    return localStorage.getItem(DEBUG_KEY) === "true";
+  } catch {
+    return false;
+  }
+}
+const debug = (...args) => {
+  if (!isDebugEnabled()) return;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().split("T")[1].slice(0, -1);
+  console.log(`[${timestamp}] [Nextlytics]`, ...args);
+};
+let usePathnameImpl = null;
+try {
+  usePathnameImpl = require("next/navigation").usePathname;
+} catch {
+}
+function usePathnameSafe() {
+  if (!usePathnameImpl) return null;
+  return usePathnameImpl();
+}
+function useNavigation(requestId, onNavigate) {
+  const pathname = usePathnameSafe();
+  const stateRef = (0, import_react.useRef)(null);
+  const onNavigateRef = (0, import_react.useRef)(onNavigate);
+  onNavigateRef.current = onNavigate;
+  (0, import_react.useEffect)(() => {
+    const prev = stateRef.current;
+    const isInitial = prev === null;
+    const requestIdChanged = !isInitial && prev.requestId !== requestId;
+    const pathnameChanged = !isInitial && pathname !== null && prev.pathname !== pathname;
+    stateRef.current = { requestId, pathname };
+    if (!isInitial && !requestIdChanged && !pathnameChanged) {
+      return;
+    }
+    const softNavigation = !isInitial && !requestIdChanged && pathnameChanged;
+    debug("Navigation", {
+      isInitial,
+      softNavigation,
+      requestId,
+      pathname,
+      requestIdChanged,
+      pathnameChanged
+    });
+    if (softNavigation) {
+      const controller = new AbortController();
+      onNavigateRef.current({ softNavigation: true, signal: controller.signal });
+      return () => {
+        debug("Aborting previous soft navigation request");
+        controller.abort();
+      };
+    } else {
+      onNavigateRef.current({ softNavigation: false });
+    }
+  }, [requestId, pathname]);
+}
+function arraysEqual(a, b) {
+  if (a === b) return true;
+  if (!a || !b || a.length !== b.length) return false;
+  return a.every((v, i) => v === b[i]);
+}
+const InjectScript = (0, import_react.memo)(
+  function InjectScript2({ body, src, async: isAsync, deps = [] }) {
+    const depsKey = deps.map(String).join("\0");
+    (0, import_react.useEffect)(() => {
+      const el = document.createElement("script");
+      if (src) {
+        el.src = src;
+        if (isAsync) el.async = true;
+        debug("Inject external", { src, deps });
+      } else if (body) {
+        el.textContent = body;
+        debug("Inject inline", { body: body.slice(0, 100), deps });
+      }
+      document.head.appendChild(el);
+      return () => {
+        debug("Remove script", { deps });
+        el.remove();
+      };
+    }, [depsKey]);
+    return null;
+  },
+  (prev, next) => prev.body === next.body && prev.src === next.src && prev.async === next.async && arraysEqual(prev.deps, next.deps)
+);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InjectScript,
+  debug,
+  useNavigation,
+  usePathnameSafe
+});

package/dist/client.d.ts

@@ -11,10 +11,7 @@ type NextlyticsContext = {
     templates?: Record<string, JavascriptTemplate>;
 };
 declare function NextlyticsClient(props: {
-    ctx?: NextlyticsContext;
-    requestId?: string;
-    scripts?: TemplatizedScriptInsertion<unknown>[];
-    templates?: Record<string, JavascriptTemplate>;
+    ctx: NextlyticsContext;
     children?: ReactNode;
 }): react_jsx_runtime.JSX.Element;
 type NextlyticsClientApi = {

package/dist/client.js

@@ -25,13 +25,15 @@ __export(client_exports, {
 module.exports = __toCommonJS(client_exports);
 var import_jsx_runtime = require("react/jsx-runtime");
 var import_react = require("react");
+var import_client_utils = require("./client-utils");
 var import_server_component_context = require("./server-component-context");
 var import_template = require("./template");
+var import_stable_hash = require("./stable-hash");
 const templateFunctions = {
   q: (v) => JSON.stringify(v ?? null),
-  json: (v) => JSON.stringify(v ?? null)
+  json: (v) => JSON.stringify(v ?? null),
+  stableHash: (v) => (0, import_stable_hash.stableHash)(v)
 };
-const compiledCache = {};
 const NextlyticsContext = (0, import_react.createContext)(null);
 function createClientContext() {
   const isBrowser = typeof window !== "undefined";
@@ -55,94 +57,165 @@ function createClientContext() {
     locale: isBrowser ? navigator.language : void 0
   };
 }
-function getCompiledTemplate(templateId, itemIndex, item) {
-  const cacheKey = `${templateId}:${itemIndex}`;
-  if (!compiledCache[cacheKey]) {
-    compiledCache[cacheKey] = {
-      src: item.src ? (0, import_template.compile)(item.src) : void 0,
-      body: item.body ? (0, import_template.compile)(item.body) : void 0
-    };
-  }
-  return compiledCache[cacheKey];
-}
-function executeTemplatedScripts(scripts, templates) {
-  if (!scripts || typeof window === "undefined") return;
+function deduplicateScripts(scripts, templates) {
+  const result = [];
+  const firstSeenByDeps = /* @__PURE__ */ new Set();
   for (const script of scripts) {
-    if (script.type !== "script-template") {
-      console.warn(`[Nextlytics] unsupported script type ${script.type} `);
+    if (script.type !== "script-template") continue;
+    const template = templates[script.templateId];
+    if (!template) continue;
+    if (!template.deps) {
+      result.push(script);
       continue;
     }
+    const paramsRecord = script.params || {};
+    const deps = compileTemplateDeps(template, paramsRecord);
+    const depsKey = `${script.templateId}\0${deps.join("\0")}`;
+    if (firstSeenByDeps.has(depsKey)) continue;
+    firstSeenByDeps.add(depsKey);
+    result.push(script);
+  }
+  return result;
+}
+function compileScripts(scripts, templates) {
+  const result = [];
+  for (const [scriptIndex, script] of scripts.entries()) {
+    if (script.type !== "script-template") continue;
     const template = templates[script.templateId];
     if (!template) {
-      console.warn(`[Nextlytics] Missing template: ${script.templateId}`);
+      console.warn(`[Nextlytics] Template "${script.templateId}" not found`);
       continue;
     }
-    const params = script.params;
-    for (let i = 0; i < template.items.length; i++) {
-      const item = template.items[i];
-      const compiled = getCompiledTemplate(script.templateId, i, item);
-      const src = compiled.src ? (0, import_template.apply)(compiled.src, params, templateFunctions) : void 0;
-      if (item.singleton && src && document.querySelector(`script[src="${src}"]`)) {
+    const paramsRecord = script.params || {};
+    const deps = compileTemplateDeps(template, paramsRecord);
+    let itemIndex = 0;
+    for (const item of template.items) {
+      const keyPrefix = `${script.templateId}:${scriptIndex}:${item.src ? "ext" : "body"}:${itemIndex}`;
+      if (item.src) {
+        const compiledSrc = (0, import_template.compile)(item.src);
+        const src = (0, import_template.apply)(compiledSrc, paramsRecord, templateFunctions);
+        result.push({
+          key: keyPrefix,
+          src,
+          async: item.async,
+          deps
+        });
+        itemIndex++;
         continue;
       }
-      const el = document.createElement("script");
-      if (src) {
-        el.src = src;
-      }
-      if (compiled.body) {
-        el.textContent = (0, import_template.apply)(compiled.body, params, templateFunctions);
-      }
-      if (item.async) {
-        el.async = true;
+      if (!item.body) {
+        itemIndex++;
+        continue;
       }
-      document.head.appendChild(el);
+      const bodyText = Array.isArray(item.body) ? item.body.join("\n") : item.body;
+      const compiled = (0, import_template.compile)(bodyText);
+      const body = (0, import_template.apply)(compiled, paramsRecord, templateFunctions);
+      result.push({ key: keyPrefix, body, deps });
+      itemIndex++;
     }
   }
+  return result;
+}
+function compileTemplateDeps(template, paramsRecord) {
+  if (!template.deps) return [];
+  const rawDeps = Array.isArray(template.deps) ? template.deps : [template.deps];
+  return rawDeps.map((dep) => (0, import_template.apply)((0, import_template.compile)(dep), paramsRecord, templateFunctions));
 }
-async function sendEvent(requestId, type, payload) {
+function NextlyticsScripts({
+  initialScripts
+}) {
+  const context = (0, import_react.useContext)(NextlyticsContext);
+  if (!context) {
+    throw new Error("NextlyticsScripts should be called within NextlyticsContext");
+  }
+  const { scriptsRef, subscribersRef, templates } = context;
+  const [, forceUpdate] = (0, import_react.useReducer)((x) => x + 1, 0);
+  (0, import_react.useEffect)(() => {
+    subscribersRef.current.add(forceUpdate);
+    return () => {
+      subscribersRef.current.delete(forceUpdate);
+    };
+  }, [subscribersRef]);
+  const allScripts = [...initialScripts, ...scriptsRef.current];
+  const dedupedScripts = (0, import_react.useMemo)(
+    () => deduplicateScripts(allScripts, templates),
+    [allScripts, templates]
+  );
+  const compiled = (0, import_react.useMemo)(
+    () => compileScripts(dedupedScripts, templates),
+    [dedupedScripts, templates]
+  );
+  (0, import_client_utils.debug)("Rendering scripts", {
+    initialCount: initialScripts.length,
+    dynamicCount: scriptsRef.current.length,
+    totalCount: allScripts.length,
+    compiledCount: compiled.length
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: compiled.map(({ key, ...props }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_client_utils.InjectScript, { ...props }, key)) });
+}
+async function sendEventToServer(requestId, request, { signal, isSoftNavigation } = {}) {
   try {
+    const headers = {
+      "Content-Type": "application/json",
+      [import_server_component_context.headerNames.pageRenderId]: requestId
+    };
+    if (isSoftNavigation) {
+      headers[import_server_component_context.headerNames.isSoftNavigation] = "1";
+    }
     const response = await fetch("/api/event", {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        [import_server_component_context.headers.pageRenderId]: requestId
-      },
-      body: JSON.stringify({ type, payload })
+      headers,
+      body: JSON.stringify(request),
+      signal
     });
     if (response.status === 404) {
       console.error(
-        "[Nextlytics] In order for NextlyticsClient to work, you must mount nextlyticsRouteHandler to /api/event"
+        "[Nextlytics] In order for NextlyticsClient to work, you must install nextlytics middleware"
       );
       return { ok: false };
     }
     const data = await response.json().catch(() => ({ ok: response.ok }));
-    return { ok: data.ok ?? response.ok, scripts: data.scripts };
+    return { ok: data.ok ?? response.ok, items: data.items };
   } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      return { ok: false };
+    }
     console.error("[Nextlytics] Failed to send event:", error);
     return { ok: false };
   }
 }
-const initializedRequestIds = /* @__PURE__ */ new Set();
 function NextlyticsClient(props) {
-  const requestId = props.ctx?.requestId ?? props.requestId ?? "";
-  const scripts = props.ctx?.scripts ?? props.scripts;
-  const templates = props.ctx?.templates ?? props.templates ?? {};
-  (0, import_react.useEffect)(() => {
-    if (initializedRequestIds.has(requestId)) return;
-    initializedRequestIds.add(requestId);
-    if (scripts && Object.keys(templates).length > 0) {
-      executeTemplatedScripts(scripts, templates);
-    }
+  const { requestId, scripts: initialScripts = [], templates = {} } = props.ctx;
+  const scriptsRef = (0, import_react.useRef)([]);
+  const subscribersRef = (0, import_react.useRef)(/* @__PURE__ */ new Set());
+  const addScripts = (0, import_react.useCallback)((newScripts) => {
+    (0, import_client_utils.debug)("Adding scripts", {
+      newCount: newScripts.length,
+      templateIds: newScripts.map((s) => s.templateId)
+    });
+    scriptsRef.current = [...scriptsRef.current, ...newScripts];
+    subscribersRef.current.forEach((cb) => cb());
+  }, []);
+  const contextValue = (0, import_react.useMemo)(
+    () => ({ requestId, templates, addScripts, scriptsRef, subscribersRef }),
+    [requestId, templates, addScripts]
+  );
+  (0, import_client_utils.useNavigation)(requestId, ({ softNavigation, signal }) => {
+    (0, import_client_utils.debug)("Sending page-view", { requestId, softNavigation });
     const clientContext = createClientContext();
-    sendEvent(requestId, "client-init", clientContext).then(
-      ({ scripts: responseScripts }) => {
-        if (responseScripts) {
-          executeTemplatedScripts(responseScripts, templates);
-        }
-      }
-    );
-  }, [requestId, scripts, templates]);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(NextlyticsContext.Provider, { value: { requestId, templates }, children: props.children });
+    sendEventToServer(
+      requestId,
+      { type: "page-view", clientContext, softNavigation: softNavigation || void 0 },
+      { signal, isSoftNavigation: softNavigation }
+    ).then(({ items }) => {
+      (0, import_client_utils.debug)("page-view response", { scriptsCount: items?.length ?? 0 });
+      if (items?.length) addScripts(items);
+    });
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(NextlyticsContext.Provider, { value: contextValue, children: [
+    props.children,
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(NextlyticsScripts, { initialScripts })
+  ] });
 }
 function useNextlytics() {
   const context = (0, import_react.useContext)(NextlyticsContext);
@@ -151,23 +224,24 @@ function useNextlytics() {
       "[Nextlytics] useNextlytics() must be used within a component wrapped by <NextlyticsServer>. Add <NextlyticsServer> at the top of your layout.tsx file."
     );
   }
-  const { requestId, templates } = context;
-  const send = (0, import_react.useCallback)(
+  const { requestId, addScripts } = context;
+  const sendEvent = (0, import_react.useCallback)(
     async (eventName, opts) => {
-      const result = await sendEvent(requestId, "client-event", {
+      const result = await sendEventToServer(requestId, {
+        type: "custom-event",
         name: eventName,
         props: opts?.props,
         collectedAt: (/* @__PURE__ */ new Date()).toISOString(),
         clientContext: createClientContext()
       });
-      if (result.scripts) {
-        executeTemplatedScripts(result.scripts, templates);
+      if (result.items && result.items.length > 0) {
+        addScripts(result.items);
       }
       return { ok: result.ok };
     },
-    [requestId, templates]
+    [requestId, addScripts]
   );
-  return { sendEvent: send };
+  return { sendEvent };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/config-helpers.js

@@ -28,7 +28,7 @@ function withDefaults(config) {
     ...config,
     excludeApiCalls: config.excludeApiCalls ?? false,
     eventEndpoint: config.eventEndpoint ?? "/api/event",
-    isApiPath: config.isApiPath ?? (() => false),
+    isApiPath: config.isApiPath ?? ((str) => str.startsWith("/api")),
     backends: config.backends ?? [],
     anonymousUsers: {
       gdprMode: config.anonymousUsers?.gdprMode ?? true,

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { Nextlytics, NextlyticsServer } from './server.js';
-export { NextlyticsClient, NextlyticsContext, useNextlytics } from './client.js';
+export { Nextlytics } from './server.js';
 export { getNextlyticsProps } from './pages-router.js';
+export { NextlyticsClient, NextlyticsContext, useNextlytics } from './client.js';
 export { loggingBackend } from './backends/logging.js';
-export { AnonymousUserResult, BackendConfigEntry, BackendWithConfig, ClientContext, IngestPolicy, NextlyticsBackend, NextlyticsBackendFactory, NextlyticsConfig, NextlyticsEvent, NextlyticsPlugin, NextlyticsPluginFactory, NextlyticsResult, NextlyticsServerSide, RequestContext, ServerEventContext, UserContext } from './types.js';
+export { AnonymousUserResult, BackendConfigEntry, BackendWithConfig, ClientAction, ClientContext, ClientRequest, JavascriptTemplate, NextlyticsBackend, NextlyticsBackendFactory, NextlyticsClientContext, NextlyticsConfig, NextlyticsEvent, NextlyticsPlugin, NextlyticsPluginFactory, NextlyticsResult, NextlyticsServerSide, PageViewDelivery, PagesRouterContext, RequestContext, ServerEventContext, UserContext } from './types.js';
 import 'react/jsx-runtime';
 import 'react';
 import 'next/dist/server/web/spec-extension/cookies';

package/dist/index.js

@@ -20,21 +20,19 @@ var index_exports = {};
 __export(index_exports, {
   Nextlytics: () => import_server.Nextlytics,
   NextlyticsClient: () => import_client.NextlyticsClient,
-  NextlyticsServer: () => import_server.NextlyticsServer,
   getNextlyticsProps: () => import_pages_router.getNextlyticsProps,
   loggingBackend: () => import_logging.loggingBackend,
   useNextlytics: () => import_client.useNextlytics
 });
 module.exports = __toCommonJS(index_exports);
 var import_server = require("./server");
-var import_client = require("./client");
 var import_pages_router = require("./pages-router");
+var import_client = require("./client");
 var import_logging = require("./backends/logging");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Nextlytics,
   NextlyticsClient,
-  NextlyticsServer,
   getNextlyticsProps,
   loggingBackend,
   useNextlytics

package/dist/middleware.d.ts

@@ -1,10 +1,9 @@
 import { NextMiddleware } from 'next/server';
-import { NextlyticsEvent, RequestContext, IngestPolicy, DispatchResult } from './types.js';
 import { NextlyticsConfigWithDefaults } from './config-helpers.js';
+import { DispatchEvent, UpdateEvent } from './api-handler.js';
+import './types.js';
 import 'next/dist/server/web/spec-extension/cookies';
 
-type DispatchEvent = (event: NextlyticsEvent, ctx: RequestContext, policyFilter?: IngestPolicy) => DispatchResult;
-type UpdateEvent = (eventId: string, patch: Partial<NextlyticsEvent>, ctx: RequestContext) => Promise<void>;
 declare function createNextlyticsMiddleware(config: NextlyticsConfigWithDefaults, dispatchEvent: DispatchEvent, updateEvent: UpdateEvent): NextMiddleware;
 
 export { createNextlyticsMiddleware };