@nextlytics/core 0.2.2 → 0.3.0-canary.80

package/dist/stable-hash.js

@@ -0,0 +1,76 @@
+"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 stable_hash_exports = {};
+__export(stable_hash_exports, {
+  stableHash: () => stableHash
+});
+module.exports = __toCommonJS(stable_hash_exports);
+const FNV_OFFSET_BASIS = 2166136261;
+const FNV_PRIME = 16777619;
+function stableStringify(value, seen) {
+  if (value === null) return "null";
+  const valueType = typeof value;
+  if (valueType === "string") return JSON.stringify(value);
+  if (valueType === "number") return Number.isFinite(value) ? String(value) : "null";
+  if (valueType === "boolean") return value ? "true" : "false";
+  if (valueType === "bigint") {
+    throw new TypeError("Do not know how to serialize a BigInt");
+  }
+  if (valueType === "undefined" || valueType === "function" || valueType === "symbol") {
+    return void 0;
+  }
+  if (typeof value.toJSON === "function") {
+    return stableStringify(value.toJSON(), seen);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((item) => stableStringify(item, seen) ?? "null");
+    return `[${items.join(",")}]`;
+  }
+  const obj = value;
+  if (seen.has(obj)) {
+    throw new TypeError("Converting circular structure to JSON");
+  }
+  seen.add(obj);
+  const keys = Object.keys(obj).sort();
+  const parts = [];
+  for (const key of keys) {
+    const next = stableStringify(obj[key], seen);
+    if (next !== void 0) {
+      parts.push(`${JSON.stringify(key)}:${next}`);
+    }
+  }
+  seen.delete(obj);
+  return `{${parts.join(",")}}`;
+}
+function fnv1aHash(input) {
+  let hash = FNV_OFFSET_BASIS;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, FNV_PRIME) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+function stableHash(value) {
+  const stable = stableStringify(value, /* @__PURE__ */ new WeakSet()) ?? "null";
+  return fnv1aHash(stable);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  stableHash
+});

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import { RequestCookies } from 'next/dist/server/web/spec-extension/cookies';
-import { NextRequest, NextMiddleware } from 'next/server';
+import { NextMiddleware } from 'next/server';
 
 /** Server-side request context collected in middleware */
 interface ServerEventContext {
@@ -28,6 +28,16 @@ interface ClientContext {
     referer?: string;
     /** window.location.pathname - may differ from server path in SPAs */
     path?: string;
+    /** window.location.href */
+    url?: string;
+    /** window.location.host */
+    host?: string;
+    /** window.location.search (as string, e.g. "?foo=bar") */
+    search?: string;
+    /** window.location.hash */
+    hash?: string;
+    /** document.title */
+    title?: string;
     /** Screen and viewport dimensions */
     screen: {
         /** screen.width */
@@ -59,6 +69,12 @@ interface UserContext {
 }
 /** Analytics event sent to backends */
 interface NextlyticsEvent {
+    /**
+     * Where the event was triggered?
+     *  - server — on server, e.g in route or server side component
+     *  - client — on client
+     */
+    origin: "server" | "client";
     /** ISO timestamp when event was collected */
     collectedAt: string;
     /** Unique event ID */
@@ -99,6 +115,20 @@ type NextlyticsPlugin = {
 };
 /** Factory to create plugin per-request (for request-scoped plugins) */
 type NextlyticsPluginFactory = (ctx: RequestContext) => NextlyticsPlugin;
+/** When to deliver page view events for a backend */
+type PageViewDelivery = 
+/** Dispatch on server request in middleware (default) - faster but no client context */
+"on-request"
+/** Dispatch on page load (client-side) - has full client context (title, screen, etc) */
+ | "on-page-load";
+/** Backend with configuration options */
+type BackendWithConfig = {
+    backend: NextlyticsBackend | NextlyticsBackendFactory;
+    /** When to send events. Default: "on-request" */
+    pageViewDelivery?: PageViewDelivery;
+};
+/** Backend config entry - either a backend directly or with config */
+type BackendConfigEntry = NextlyticsBackend | NextlyticsBackendFactory | BackendWithConfig;
 type NextlyticsConfig = {
     /** Enable debug logging (shows backend stats for each event) */
     debug?: boolean;
@@ -114,12 +144,6 @@ type NextlyticsConfig = {
         /** Cookie max age in seconds (default: 2 years) */
         cookieMaxAge?: number;
     };
-    /**
-     * When to record pageView:
-     * - "server": in middleware (default, more reliable)
-     * - "client-init": when JS loads (has client context) - NOT SUPPORTED CURRENTLU
-     */
-    pageViewMode?: "server" | "client-init";
     /** Skip tracking for API routes */
     excludeApiCalls?: boolean;
     /** Skip tracking for specific paths */
@@ -138,7 +162,7 @@ type NextlyticsConfig = {
         }) => Promise<AnonymousUserResult>;
     };
     /** Analytics backends to send events to */
-    backends?: (NextlyticsBackend | NextlyticsBackendFactory)[];
+    backends?: BackendConfigEntry[];
     plugins?: (NextlyticsPlugin | NextlyticsPluginFactory)[];
 };
 type ClientAction = {
@@ -163,13 +187,16 @@ type DispatchResult = {
 };
 type JavascriptTemplate = {
     items: ScriptElement[];
+    /**
+     * Optional dependency key template. When this value changes, the script re-injects.
+     * If omitted, the template is treated as "once".
+     */
+    deps?: string | string[];
 };
 type ScriptElement = {
-    async?: string;
-    body?: string;
+    async?: boolean;
+    body?: string | string[];
     src?: string;
-    /** If true, skip insertion if script with same src already exists */
-    singleton?: boolean;
 };
 /** Backend that receives analytics events */
 type NextlyticsBackend = {
@@ -183,7 +210,7 @@ type NextlyticsBackend = {
     returnsClientActions?: boolean;
     getClientSideTemplates?: () => Record<string, JavascriptTemplate>;
     /** Handle new event */
-    onEvent(event: NextlyticsEvent): Promise<void | ClientAction>;
+    onEvent(event: NextlyticsEvent): Promise<ClientAction | void | undefined>;
     /** Update existing event (e.g. add client context to server pageView) */
     updateEvent(eventId: string, patch: Partial<NextlyticsEvent>): Promise<void> | void;
 };
@@ -198,11 +225,41 @@ type NextlyticsServerSide = {
         ok: boolean;
     }>;
 };
-type AppRouteHandlers = Record<"GET" | "POST", (req: NextRequest) => Promise<Response>>;
+/** Context for Pages Router _app.tsx */
+type PagesRouterContext = {
+    req: {
+        headers: Record<string, string | string[] | undefined>;
+        cookies?: Record<string, string>;
+    };
+};
+/** Context passed to NextlyticsClient */
+type NextlyticsClientContext = {
+    requestId: string;
+    scripts?: TemplatizedScriptInsertion<unknown>[];
+    templates?: Record<string, JavascriptTemplate>;
+};
+/** Client-to-server request types (discriminated union) */
+type ClientRequest = {
+    type: "page-view";
+    clientContext: ClientContext;
+    /** If true, only update existing event (soft navigation - no dispatch, no scripts) */
+    softNavigation?: boolean;
+} | {
+    type: "custom-event";
+    name: string;
+    props?: Record<string, unknown>;
+    collectedAt: string;
+    clientContext: ClientContext;
+};
+/**
+ * Result of any /api/event call
+ */
+type ClientRequestResult = {
+    ok: boolean;
+    items?: ClientActionItem[];
+};
 /** Return value from Nextlytics() */
 type NextlyticsResult = {
-    /** Route handlers for /api/event */
-    handlers: AppRouteHandlers;
     /** Get server-side analytics API */
     analytics: () => Promise<NextlyticsServerSide>;
     /** Middleware to intercept requests */
@@ -211,6 +268,10 @@ type NextlyticsResult = {
     dispatchEvent: (event: NextlyticsEvent) => Promise<DispatchResult>;
     /** Manually update existing event */
     updateEvent: (eventId: string, patch: Partial<NextlyticsEvent>) => Promise<void>;
+    /** Server component that wraps your app to provide analytics context (App Router) */
+    NextlyticsServer: (props: {
+        children: React.ReactNode;
+    }) => Promise<React.ReactElement>;
 };
 
-export type { AnonymousUserResult, ClientAction, ClientActionItem, ClientContext, DispatchResult, JavascriptTemplate, NextlyticsBackend, NextlyticsBackendFactory, NextlyticsConfig, NextlyticsEvent, NextlyticsPlugin, NextlyticsPluginFactory, NextlyticsResult, NextlyticsServerSide, RequestContext, ScriptElement, ServerEventContext, TemplatizedScriptInsertion, UserContext };
+export type { AnonymousUserResult, BackendConfigEntry, BackendWithConfig, ClientAction, ClientActionItem, ClientContext, ClientRequest, ClientRequestResult, DispatchResult, JavascriptTemplate, NextlyticsBackend, NextlyticsBackendFactory, NextlyticsClientContext, NextlyticsConfig, NextlyticsEvent, NextlyticsPlugin, NextlyticsPluginFactory, NextlyticsResult, NextlyticsServerSide, PageViewDelivery, PagesRouterContext, RequestContext, ScriptElement, ServerEventContext, TemplatizedScriptInsertion, UserContext };

package/dist/uitils.d.ts

@@ -2,6 +2,12 @@ import { NextRequest } from 'next/server';
 import { ServerEventContext } from './types.js';
 import 'next/dist/server/web/spec-extension/cookies';
 
+/** Returns the full installed Next.js version string (e.g. "16.1.6"), or undefined. */
+declare function getNextVersion(): string | undefined;
+/** True if the installed Next.js major version is 15. */
+declare function isNext15(): boolean;
+/** True if the installed Next.js major version is 16. */
+declare function isNext16(): boolean;
 /** Generate a random base62 ID (16 chars = 62^16 ≈ 4.7 × 10^28 combinations) */
 declare function generateId(): string;
 type RequestInfo = {
@@ -19,4 +25,4 @@ type RequestInfo = {
 declare function getRequestInfo(request: NextRequest): RequestInfo;
 declare function createServerContext(request: NextRequest): ServerEventContext;
 
-export { type RequestInfo, createServerContext, generateId, getRequestInfo };
+export { type RequestInfo, createServerContext, generateId, getNextVersion, getRequestInfo, isNext15, isNext16 };

package/dist/uitils.js

@@ -20,10 +20,41 @@ var uitils_exports = {};
 __export(uitils_exports, {
   createServerContext: () => createServerContext,
   generateId: () => generateId,
-  getRequestInfo: () => getRequestInfo
+  getNextVersion: () => getNextVersion,
+  getRequestInfo: () => getRequestInfo,
+  isNext15: () => isNext15,
+  isNext16: () => isNext16
 });
 module.exports = __toCommonJS(uitils_exports);
 var import_headers = require("./headers");
+let _nextVersion;
+function detectNextVersion() {
+  if (_nextVersion !== void 0) return _nextVersion;
+  try {
+    const pkg = require("next/package.json");
+    _nextVersion = pkg.version;
+  } catch {
+    console.warn(
+      "[Nextlytics] Could not read Next.js version from next/package.json.\nThis can happen if your bundler does not support JSON imports from\nnode_modules. Ensure `resolveJsonModule: true` is set in tsconfig\nand your bundler can resolve peer-dependency subpath imports.\nTurbopack and webpack (default Next.js bundlers) both support this."
+    );
+    _nextVersion = "";
+  }
+  return _nextVersion || void 0;
+}
+function parseMajor(version) {
+  if (!version) return void 0;
+  const major = parseInt(version.split(".")[0], 10);
+  return Number.isFinite(major) ? major : void 0;
+}
+function getNextVersion() {
+  return detectNextVersion();
+}
+function isNext15() {
+  return parseMajor(detectNextVersion()) === 15;
+}
+function isNext16() {
+  return parseMajor(detectNextVersion()) === 16;
+}
 const BASE62_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 function generateId() {
   const length = 16;
@@ -45,15 +76,15 @@ function getRequestInfo(request) {
   );
   const hasStandardPrefetchHeader = headers.get("next-router-prefetch") === "1" || headers.get("purpose") === "prefetch" || headers.get("sec-purpose") === "prefetch";
   const nextUrl = headers.get("next-url");
-  const isRscPrefetch = nextUrl !== null && nextUrl !== pathname;
-  const isPrefetch = hasStandardPrefetchHeader || isRscPrefetch;
   const isRsc = !!(nextUrl || headers.get("rsc"));
   const secFetchDest = headers.get("sec-fetch-dest");
   const secFetchMode = headers.get("sec-fetch-mode");
   const accept = headers.get("accept") || "";
   const isDocumentRequest = secFetchDest === "document" || secFetchMode === "navigate";
   const acceptsHtml = accept.includes("text/html");
-  const isPageNavigation = isRsc || isDocumentRequest || acceptsHtml;
+  const isPageNavigation = isDocumentRequest || acceptsHtml;
+  const isRscPrefetch = nextUrl !== null && nextUrl !== pathname;
+  const isPrefetch = hasStandardPrefetchHeader || isRscPrefetch && !isPageNavigation;
   return {
     isPrefetch,
     isRsc,
@@ -90,5 +121,8 @@ function createServerContext(request) {
 0 && (module.exports = {
   createServerContext,
   generateId,
-  getRequestInfo
+  getNextVersion,
+  getRequestInfo,
+  isNext15,
+  isNext16
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextlytics/core",
-  "version": "0.2.2",
+  "version": "0.3.0-canary.80",
   "description": "Analytics library for Next.js",
   "license": "MIT",
   "repository": {

package/dist/handlers.d.ts

@@ -1,9 +0,0 @@
-import { NextRequest } from 'next/server';
-import { NextlyticsEvent, RequestContext, DispatchResult } from './types.js';
-import { NextlyticsConfigWithDefaults } from './config-helpers.js';
-import 'next/dist/server/web/spec-extension/cookies';
-
-type AppRouteHandlers = Record<"GET" | "POST", (req: NextRequest) => Promise<Response>>;
-declare function createHandlers(config: NextlyticsConfigWithDefaults, dispatchEvent: (event: NextlyticsEvent, ctx: RequestContext) => DispatchResult, updateEvent: (eventId: string, patch: Partial<NextlyticsEvent>, ctx: RequestContext) => Promise<void>): AppRouteHandlers;
-
-export { createHandlers };

package/dist/handlers.js

@@ -1,123 +0,0 @@
-"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 handlers_exports = {};
-__export(handlers_exports, {
-  createHandlers: () => createHandlers
-});
-module.exports = __toCommonJS(handlers_exports);
-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;
-  return await config.callbacks.getUser(ctx) || void 0;
-}
-function createHandlers(config, dispatchEvent, updateEvent) {
-  return {
-    GET: async () => {
-      return Response.json({ status: "ok" });
-    },
-    POST: async (req) => {
-      const pageRenderId = req.headers.get(import_server_component_context.headers.pageRenderId);
-      if (!pageRenderId) {
-        return Response.json({ error: "Missing page render ID" }, { status: 400 });
-      }
-      let body;
-      try {
-        body = await req.json();
-      } catch {
-        return Response.json({ error: "Invalid JSON" }, { status: 400 });
-      }
-      const { type, payload } = body;
-      const ctx = createRequestContext(req);
-      if (type === "client-init") {
-        const clientContext = payload;
-        const serverContext = (0, import_uitils.createServerContext)(req);
-        if (clientContext?.path) {
-          serverContext.path = clientContext.path;
-        }
-        const userContext = await getUserContext(config, ctx);
-        const { anonId: anonymousUserId } = await (0, import_anonymous_user.resolveAnonymousUser)({
-          ctx,
-          serverContext,
-          config
-        });
-        if (config.pageViewMode === "client-init") {
-          const event = {
-            eventId: pageRenderId,
-            type: "pageView",
-            collectedAt: (/* @__PURE__ */ new Date()).toISOString(),
-            anonymousUserId,
-            serverContext,
-            clientContext,
-            userContext,
-            properties: {}
-          };
-          const { clientActions, completion } = dispatchEvent(event, ctx);
-          const actions = await clientActions;
-          completion.catch((err) => console.warn("[Nextlytics] Dispatch completion error:", err));
-          const scripts = actions.items.filter((i) => i.type === "script-template");
-          return Response.json({ ok: true, scripts: scripts.length > 0 ? scripts : void 0 });
-        } else {
-          await updateEvent(pageRenderId, { clientContext, userContext, anonymousUserId }, ctx);
-          return Response.json({ ok: true });
-        }
-      } else if (type === "client-event") {
-        const clientContext = payload.clientContext || void 0;
-        const serverContext = (0, import_uitils.createServerContext)(req);
-        if (clientContext?.path) {
-          serverContext.path = clientContext.path;
-        }
-        const userContext = await getUserContext(config, ctx);
-        const { anonId: anonymousUserId } = await (0, import_anonymous_user.resolveAnonymousUser)({
-          ctx,
-          serverContext,
-          config
-        });
-        const event = {
-          eventId: (0, import_uitils.generateId)(),
-          parentEventId: pageRenderId,
-          type: payload.name || type,
-          collectedAt: payload.collectedAt || (/* @__PURE__ */ new Date()).toISOString(),
-          anonymousUserId,
-          serverContext,
-          clientContext,
-          userContext,
-          properties: payload.props || {}
-        };
-        const { clientActions, completion } = dispatchEvent(event, ctx);
-        const actions = await clientActions;
-        completion.catch((err) => console.warn("[Nextlytics] Dispatch completion error:", err));
-        const scripts = actions.items.filter((i) => i.type === "script-template");
-        return Response.json({ ok: true, scripts: scripts.length > 0 ? scripts : void 0 });
-      }
-      return Response.json({ ok: true });
-    }
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createHandlers
-});