@nextlytics/core 0.7.1 → 0.8.0-canary.120

package/dist/capture.d.ts

@@ -0,0 +1,33 @@
+import { CaptureRequest } from './types.js';
+import 'next/dist/server/web/spec-extension/cookies';
+import 'next/server';
+import 'next';
+
+/** The mechanical request facts the capture decision needs. */
+type CaptureReqInfo = {
+    /** Browser-initiated sub-request (RSC/XHR/fetch/subresource). */
+    isBrowserSubrequest: boolean;
+    /** Hard document navigation (Sec-Fetch-Dest: document / mode: navigate). */
+    isDocumentRequest: boolean;
+};
+/**
+ * Resolve the event type for a request under `capture` configuration, or `null`
+ * to skip. Pure and side-effect free so it can be unit-tested directly.
+ *
+ * Mechanical noise is filtered first regardless of what `capture` returns:
+ *  - browser sub-requests (RSC soft-nav / XHR / fetch / subresource) — would
+ *    duplicate the client-side pageView, so never recorded here;
+ *  - non-GET requests that aren't document navigations (HEAD probes, webhook
+ *    POSTs, etc.) — not page views.
+ *
+ * Everything else — a real browser navigation, or a direct GET from a
+ * non-browser client — is handed to `capture`, whose return decides:
+ *  `false` → skip, `true` → "pageView", `"<type>"` → that event type.
+ */
+declare function resolveCaptureType(capture: (req: CaptureRequest) => boolean | string, reqInfo: CaptureReqInfo, req: {
+    path: string;
+    method: string;
+    userAgent?: string;
+}): string | null;
+
+export { resolveCaptureType };

package/dist/capture.js

@@ -0,0 +1,39 @@
+"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 capture_exports = {};
+__export(capture_exports, {
+  resolveCaptureType: () => resolveCaptureType
+});
+module.exports = __toCommonJS(capture_exports);
+function resolveCaptureType(capture, reqInfo, req) {
+  if (reqInfo.isBrowserSubrequest) return null;
+  if (req.method !== "GET" && !reqInfo.isDocumentRequest) return null;
+  const result = capture({
+    path: req.path,
+    method: req.method,
+    fromBrowser: reqInfo.isDocumentRequest,
+    userAgent: req.userAgent
+  });
+  if (result === false) return null;
+  return result === true ? "pageView" : result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resolveCaptureType
+});

package/dist/config-helpers.d.ts

@@ -11,7 +11,7 @@ interface ConfigValidationResult {
     valid: boolean;
     warnings: string[];
 }
-declare function validateConfig(_config: NextlyticsConfig): ConfigValidationResult;
+declare function validateConfig(config: NextlyticsConfig): ConfigValidationResult;
 declare function logConfigWarnings(result: ConfigValidationResult): void;
 
 export { type ConfigValidationResult, type NextlyticsConfigWithDefaults, logConfigWarnings, validateConfig, withDefaults };

package/dist/config-helpers.js

@@ -40,8 +40,21 @@ function withDefaults(config) {
     }
   };
 }
-function validateConfig(_config) {
-  return { valid: true, warnings: [] };
+function validateConfig(config) {
+  const warnings = [];
+  const deprecated = ["isApiPath", "excludeApiCalls", "excludePaths"].filter(
+    (k) => config[k] !== void 0
+  );
+  if (config.capture && deprecated.length > 0) {
+    warnings.push(
+      `[Nextlytics] \`capture\` is set, so the deprecated option(s) ${deprecated.join(", ")} are ignored. Move that logic into \`capture\`.`
+    );
+  } else if (deprecated.length > 0) {
+    warnings.push(
+      `[Nextlytics] ${deprecated.join(", ")} are deprecated; prefer \`capture\` (return false / true / "<eventType>").`
+    );
+  }
+  return { valid: true, warnings };
 }
 function logConfigWarnings(result) {
   for (const warning of result.warnings) {

package/dist/middleware.js

@@ -24,6 +24,7 @@ module.exports = __toCommonJS(middleware_exports);
 var import_server = require("next/server");
 var import_server_component_context = require("./server-component-context");
 var import_uitils = require("./uitils");
+var import_capture = require("./capture");
 var import_anonymous_user = require("./anonymous-user");
 var import_api_handler = require("./api-handler");
 function createRequestContext(request) {
@@ -78,6 +79,47 @@ function createNextlyticsMiddleware(config, dispatchEvent, updateEvent, collectT
       response2.headers.set(import_server_component_context.headerNames.active, "1");
       return response2;
     }
+    if (config.capture) {
+      const eventType = (0, import_capture.resolveCaptureType)(config.capture, reqInfo, {
+        path: pathname,
+        method: request.method,
+        userAgent: request.headers.get("user-agent") ?? void 0
+      });
+      if (eventType === null) {
+        const response3 = import_server.NextResponse.next();
+        response3.headers.set(import_server_component_context.headerNames.active, "1");
+        return response3;
+      }
+      const pageRenderId2 = (0, import_uitils.generateId)();
+      const serverContext2 = (0, import_uitils.createServerContext)(request);
+      const response2 = import_server.NextResponse.next();
+      const ctx2 = createRequestContext(request);
+      response2.cookies.set(import_server_component_context.LAST_PAGE_RENDER_ID_COOKIE, pageRenderId2, { path: "/" });
+      const { anonId: anonId2 } = await (0, import_anonymous_user.resolveAnonymousUser)({ ctx: ctx2, serverContext: serverContext2, config, response: response2 });
+      const userContext2 = await (0, import_api_handler.getUserContext)(config, ctx2);
+      const extraProps2 = await (0, import_api_handler.getEventProps)(config, ctx2, userContext2);
+      const event = createEvent(
+        pageRenderId2,
+        serverContext2,
+        eventType,
+        userContext2,
+        anonId2,
+        extraProps2
+      );
+      const { clientActions: clientActions2, completion: completion2 } = dispatchEvent(event, ctx2, "on-request");
+      const actions2 = await clientActions2;
+      const scripts2 = actions2.items.filter(
+        (i) => i.type === "script-template"
+      );
+      (0, import_server.after)(() => completion2);
+      (0, import_server_component_context.serializeServerComponentContext)(response2, {
+        pageRenderId: pageRenderId2,
+        pathname: request.nextUrl.pathname,
+        search: request.nextUrl.search,
+        scripts: scripts2
+      });
+      return response2;
+    }
     if (reqInfo.isBrowserSubrequest && !config.isApiPath(pathname)) {
       const response2 = import_server.NextResponse.next();
       response2.headers.set(import_server_component_context.headerNames.active, "1");
@@ -115,10 +157,10 @@ function createNextlyticsMiddleware(config, dispatchEvent, updateEvent, collectT
     }
     const userContext = await (0, import_api_handler.getUserContext)(config, ctx);
     const extraProps = await (0, import_api_handler.getEventProps)(config, ctx, userContext);
-    const pageViewEvent = createPageViewEvent(
+    const pageViewEvent = createEvent(
       pageRenderId,
       serverContext,
-      isApiPath,
+      isApiPath ? "apiCall" : "pageView",
       userContext,
       anonId,
       extraProps
@@ -138,8 +180,7 @@ function createNextlyticsMiddleware(config, dispatchEvent, updateEvent, collectT
     return response;
   };
 }
-function createPageViewEvent(pageRenderId, serverContext, isApiPath, userContext, anonymousUserId, extraProps) {
-  const eventType = isApiPath ? "apiCall" : "pageView";
+function createEvent(pageRenderId, serverContext, eventType, userContext, anonymousUserId, extraProps) {
   return {
     origin: "server",
     collectedAt: serverContext.collectedAt.toISOString(),

package/dist/types.d.ts

@@ -131,9 +131,39 @@ type BackendWithConfig = {
 };
 /** Backend config entry - either a backend directly or with config */
 type BackendConfigEntry = NextlyticsBackend | NextlyticsBackendFactory | BackendWithConfig;
+/** The request `capture` decides on. Only real browser navigations and direct
+ * (non-browser) requests reach `capture`; RSC/XHR sub-requests, prefetches,
+ * static assets, and non-GET non-navigation writes are skipped before it. */
+type CaptureRequest = {
+    /** URL pathname, e.g. "/docs/quick-start.md" */
+    path: string;
+    /** HTTP method (GET, POST, …) */
+    method: string;
+    /** True when a real browser navigated here (Sec-Fetch-Dest: document). False
+     * for programmatic clients — agents, crawlers, curl, server-to-server — which
+     * omit Sec-Fetch-* headers. */
+    fromBrowser: boolean;
+    /** User-Agent header, if present. */
+    userAgent?: string;
+};
 type NextlyticsConfig = {
     /** Enable debug logging (shows backend stats for each event) */
     debug?: boolean;
+    /**
+     * Decide whether — and as what event type — to record a request.
+     *
+     *  - `false`    → don't record
+     *  - `true`     → record as the default type ("pageView")
+     *  - `"<type>"` → record with this string as `event.type` (e.g. "apiCall")
+     *
+     * Real browser users are the common case; programmatic clients (agents,
+     * crawlers, curl) are identified by `fromBrowser: false`. Defaults to
+     * `({ fromBrowser }) => fromBrowser` — i.e. track browser navigations only.
+     *
+     * When set, this is the single source of truth and the deprecated
+     * `isApiPath` / `excludeApiCalls` / `excludePaths` options are ignored.
+     */
+    capture?: (req: CaptureRequest) => boolean | string;
     anonymousUsers?: {
         /** Store anonymous ID in cookies */
         useCookies?: boolean;
@@ -146,11 +176,11 @@ type NextlyticsConfig = {
         /** Cookie max age in seconds (default: 2 years) */
         cookieMaxAge?: number;
     };
-    /** Skip tracking for API routes */
+    /** @deprecated Use `capture` instead — return `false` for API paths. Skip tracking for API routes. */
     excludeApiCalls?: boolean;
-    /** Skip tracking for specific paths */
+    /** @deprecated Use `capture` instead — return `false` for the paths you want to skip. */
     excludePaths?: (path: string) => boolean;
-    /** Determine if path is API route. Default: () => false */
+    /** @deprecated Use `capture` instead — return `"apiCall"` (or `false`) for API paths. */
     isApiPath?: (path: string) => boolean;
     /** Endpoint for client events. Default: "/api/event" */
     eventEndpoint?: string;
@@ -298,4 +328,4 @@ type NextlyticsResult = {
     }) => Promise<React.ReactElement>;
 };
 
-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 };
+export type { AnonymousUserResult, BackendConfigEntry, BackendWithConfig, CaptureRequest, ClientAction, ClientActionItem, ClientContext, ClientRequest, ClientRequestResult, DispatchResult, JavascriptTemplate, NextlyticsBackend, NextlyticsBackendFactory, NextlyticsClientContext, NextlyticsConfig, NextlyticsEvent, NextlyticsPlugin, NextlyticsPluginFactory, NextlyticsResult, NextlyticsServerSide, PageViewDelivery, PagesRouterContext, RequestContext, ScriptElement, ServerEventContext, TemplatizedScriptInsertion, UserContext };

package/package.json

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