@nextlytics/core 0.3.0 → 0.3.1

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 {
@@ -69,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 */
@@ -109,17 +115,17 @@ type NextlyticsPlugin = {
 };
 /** Factory to create plugin per-request (for request-scoped plugins) */
 type NextlyticsPluginFactory = (ctx: RequestContext) => NextlyticsPlugin;
-/** When to ingest events for a backend */
-type IngestPolicy = 
-/** Dispatch immediately in middleware (default) - faster but no client context */
-"immediate"
-/** Dispatch when client-init is received - has full client context (title, screen, etc) */
- | "on-client-event";
+/** 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: "immediate" */
-    ingestPolicy?: IngestPolicy;
+    /** When to send events. Default: "on-request" */
+    pageViewDelivery?: PageViewDelivery;
 };
 /** Backend config entry - either a backend directly or with config */
 type BackendConfigEntry = NextlyticsBackend | NextlyticsBackendFactory | BackendWithConfig;
@@ -181,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 = {
@@ -201,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;
 };
@@ -216,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 */
@@ -229,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, BackendConfigEntry, BackendWithConfig, ClientAction, ClientActionItem, ClientContext, DispatchResult, IngestPolicy, 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.3.0",
+  "version": "0.3.1",
   "description": "Analytics library for Next.js",
   "license": "MIT",
   "repository": {

package/dist/handlers.d.ts

@@ -1,12 +0,0 @@
-import { NextRequest } from 'next/server';
-
-type AppRouteHandlers = Record<"GET" | "POST", (req: NextRequest) => Promise<Response>>;
-/**
- * Route handlers for /api/event (deprecated - middleware handles this now)
- *
- * Kept for backward compatibility. If you have mounted these handlers at /api/event,
- * the middleware will intercept the request first, so these won't be called.
- */
-declare function createHandlers(): AppRouteHandlers;
-
-export { createHandlers };

package/dist/handlers.js

@@ -1,40 +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);
-function createHandlers() {
-  return {
-    GET: async () => {
-      return Response.json({ status: "ok" });
-    },
-    POST: async () => {
-      return Response.json(
-        { error: "Middleware not configured. Events are handled by nextlyticsMiddleware." },
-        { status: 500 }
-      );
-    }
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createHandlers
-});