@nextlytics/core 0.2.2 → 0.3.0-canary.70

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
     };
   }

package/dist/client.js

@@ -39,6 +39,11 @@ function createClientContext() {
     collectedAt: /* @__PURE__ */ new Date(),
     referer: isBrowser ? document.referrer || void 0 : void 0,
     path: isBrowser ? window.location.pathname : void 0,
+    url: isBrowser ? window.location.href : void 0,
+    host: isBrowser ? window.location.host : void 0,
+    search: isBrowser ? window.location.search : void 0,
+    hash: isBrowser ? window.location.hash : void 0,
+    title: isBrowser ? document.title : void 0,
     screen: {
       width: isBrowser ? window.screen.width : void 0,
       height: isBrowser ? window.screen.height : void 0,

package/dist/config-helpers.d.ts

@@ -2,7 +2,7 @@ import { NextlyticsConfig } from './types.js';
 import 'next/dist/server/web/spec-extension/cookies';
 import 'next/server';
 
-type NextlyticsConfigWithDefaults = Required<Pick<NextlyticsConfig, "pageViewMode" | "excludeApiCalls" | "eventEndpoint" | "isApiPath" | "backends">> & NextlyticsConfig & {
+type NextlyticsConfigWithDefaults = Required<Pick<NextlyticsConfig, "excludeApiCalls" | "eventEndpoint" | "isApiPath" | "backends">> & NextlyticsConfig & {
     anonymousUsers: Required<NonNullable<NextlyticsConfig["anonymousUsers"]>>;
 };
 declare function withDefaults(config: NextlyticsConfig): NextlyticsConfigWithDefaults;
@@ -10,7 +10,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

@@ -26,7 +26,6 @@ module.exports = __toCommonJS(config_helpers_exports);
 function withDefaults(config) {
   return {
     ...config,
-    pageViewMode: config.pageViewMode ?? "server",
     excludeApiCalls: config.excludeApiCalls ?? false,
     eventEndpoint: config.eventEndpoint ?? "/api/event",
     isApiPath: config.isApiPath ?? (() => false),
@@ -41,22 +40,8 @@ function withDefaults(config) {
     }
   };
 }
-function validateConfig(config) {
-  const warnings = [];
-  if (config.pageViewMode === "client-init" && config.backends?.length) {
-    const staticBackends = config.backends.filter((b) => typeof b !== "function");
-    const backendsWithoutUpdates = staticBackends.filter((b) => !b.supportsUpdates);
-    if (backendsWithoutUpdates.length > 0) {
-      const backendNames = backendsWithoutUpdates.map((b) => `"${b.name}"`).join(", ");
-      warnings.push(
-        `[Nextlytics] pageViewMode="client-init" requires backends that support updates. These don't: ${backendNames}`
-      );
-    }
-  }
-  return {
-    valid: warnings.length === 0,
-    warnings
-  };
+function validateConfig(_config) {
+  return { valid: true, warnings: [] };
 }
 function logConfigWarnings(result) {
   for (const warning of result.warnings) {

package/dist/handlers.d.ts

@@ -1,9 +1,12 @@
 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;
+/**
+ * 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

@@ -21,99 +21,16 @@ __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) {
+function createHandlers() {
   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 });
+    POST: async () => {
+      return Response.json(
+        { error: "Middleware not configured. Events are handled by nextlyticsMiddleware." },
+        { status: 500 }
+      );
     }
   };
 }

package/dist/index.d.ts

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

package/dist/middleware.d.ts

@@ -1,9 +1,9 @@
 import { NextMiddleware } from 'next/server';
-import { NextlyticsEvent, RequestContext, DispatchResult } from './types.js';
+import { NextlyticsEvent, RequestContext, IngestPolicy, DispatchResult } from './types.js';
 import { NextlyticsConfigWithDefaults } from './config-helpers.js';
 import 'next/dist/server/web/spec-extension/cookies';
 
-type DispatchEvent = (event: NextlyticsEvent, ctx: RequestContext) => DispatchResult;
+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;
 

package/dist/middleware.js

@@ -25,13 +25,23 @@ 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 isBackendWithConfig(entry) {
+  return typeof entry === "object" && entry !== null && "backend" in entry;
+}
 function resolveBackends(config, ctx) {
-  const backends = config.backends || [];
-  return backends.map((backend) => typeof backend === "function" ? backend(ctx) : backend).filter((b) => b !== null);
+  const entries = config.backends || [];
+  return entries.map((entry) => {
+    if (isBackendWithConfig(entry)) {
+      const backend2 = typeof entry.backend === "function" ? entry.backend(ctx) : entry.backend;
+      return backend2 ? { backend: backend2, ingestPolicy: entry.ingestPolicy ?? "immediate" } : null;
+    }
+    const backend = typeof entry === "function" ? entry(ctx) : entry;
+    return backend ? { backend, ingestPolicy: "immediate" } : null;
+  }).filter((b) => b !== null);
 }
 function collectTemplates(backends) {
   const templates = {};
-  for (const backend of backends) {
+  for (const { backend } of backends) {
     if (backend.getClientSideTemplates) {
       Object.assign(templates, backend.getClientSideTemplates());
     }
@@ -65,44 +75,41 @@ function createNextlyticsMiddleware(config, dispatchEvent, updateEvent) {
     const { anonId } = await (0, import_anonymous_user.resolveAnonymousUser)({ ctx, serverContext, config, response });
     const backends = resolveBackends(config, ctx);
     const templates = collectTemplates(backends);
-    let scripts = [];
-    if (config.pageViewMode !== "client-init") {
-      if (config.excludePaths?.(pathname)) {
-        (0, import_server_component_context.serializeServerComponentContext)(response, {
-          pageRenderId,
-          pathname: request.nextUrl.pathname,
-          search: request.nextUrl.search,
-          scripts,
-          templates
-        });
-        return response;
-      }
-      const isApiPath = config.isApiPath(pathname);
-      if (isApiPath && config.excludeApiCalls) {
-        (0, import_server_component_context.serializeServerComponentContext)(response, {
-          pageRenderId,
-          pathname: request.nextUrl.pathname,
-          search: request.nextUrl.search,
-          scripts,
-          templates
-        });
-        return response;
-      }
-      const userContext = await getUserContext(config, ctx);
-      const pageViewEvent = createPageViewEvent(
+    if (config.excludePaths?.(pathname)) {
+      (0, import_server_component_context.serializeServerComponentContext)(response, {
         pageRenderId,
-        serverContext,
-        isApiPath,
-        userContext,
-        anonId
-      );
-      const { clientActions, completion } = dispatchEvent(pageViewEvent, ctx);
-      const actions = await clientActions;
-      scripts = actions.items.filter(
-        (i) => i.type === "script-template"
-      );
-      (0, import_server.after)(() => completion);
+        pathname: request.nextUrl.pathname,
+        search: request.nextUrl.search,
+        scripts: [],
+        templates
+      });
+      return response;
     }
+    const isApiPath = config.isApiPath(pathname);
+    if (isApiPath && config.excludeApiCalls) {
+      (0, import_server_component_context.serializeServerComponentContext)(response, {
+        pageRenderId,
+        pathname: request.nextUrl.pathname,
+        search: request.nextUrl.search,
+        scripts: [],
+        templates
+      });
+      return response;
+    }
+    const userContext = await getUserContext(config, ctx);
+    const pageViewEvent = createPageViewEvent(
+      pageRenderId,
+      serverContext,
+      isApiPath,
+      userContext,
+      anonId
+    );
+    const { clientActions, completion } = dispatchEvent(pageViewEvent, ctx, "immediate");
+    const actions = await clientActions;
+    const scripts = actions.items.filter(
+      (i) => i.type === "script-template"
+    );
+    (0, import_server.after)(() => completion);
     (0, import_server_component_context.serializeServerComponentContext)(response, {
       pageRenderId,
       pathname: request.nextUrl.pathname,
@@ -133,6 +140,25 @@ async function getUserContext(config, ctx) {
     return void 0;
   }
 }
+function reconstructServerContext(apiCallContext, clientInit) {
+  const searchParams = {};
+  if (clientInit.search) {
+    const params = new URLSearchParams(clientInit.search);
+    params.forEach((value, key) => {
+      if (!searchParams[key]) searchParams[key] = [];
+      searchParams[key].push(value);
+    });
+  }
+  return {
+    ...apiCallContext,
+    // Override with client-provided values
+    host: clientInit.host || apiCallContext.host,
+    path: clientInit.path || apiCallContext.path,
+    search: Object.keys(searchParams).length > 0 ? searchParams : apiCallContext.search,
+    method: "GET"
+    // Page loads are always GET
+  };
+}
 async function handleEventPost(request, config, dispatchEvent, updateEvent) {
   const pageRenderId = request.headers.get(import_server_component_context.headers.pageRenderId);
   if (!pageRenderId) {
@@ -146,39 +172,40 @@ async function handleEventPost(request, config, dispatchEvent, updateEvent) {
   }
   const { type, payload } = body;
   const ctx = createRequestContext(request);
-  const serverContext = (0, import_uitils.createServerContext)(request);
+  const apiCallServerContext = (0, import_uitils.createServerContext)(request);
   const userContext = await getUserContext(config, ctx);
-  const { anonId: anonymousUserId } = await (0, import_anonymous_user.resolveAnonymousUser)({ ctx, serverContext, config });
   if (type === "client-init") {
     const clientContext = payload;
-    if (clientContext?.path) {
-      serverContext.path = clientContext.path;
-    }
-    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;
-      (0, import_server.after)(() => completion);
-      const scripts = actions.items.filter((i) => i.type === "script-template");
-      return Response.json({ ok: true, scripts: scripts.length > 0 ? scripts : void 0 });
-    } else {
-      (0, import_server.after)(() => updateEvent(pageRenderId, { clientContext, userContext, anonymousUserId }, ctx));
-      return Response.json({ ok: true });
-    }
+    const serverContext = reconstructServerContext(apiCallServerContext, clientContext);
+    const { anonId: anonymousUserId } = await (0, import_anonymous_user.resolveAnonymousUser)({
+      ctx,
+      serverContext,
+      config
+    });
+    const event = {
+      eventId: pageRenderId,
+      type: "pageView",
+      collectedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      anonymousUserId,
+      serverContext,
+      clientContext,
+      userContext,
+      properties: {}
+    };
+    const { clientActions, completion } = dispatchEvent(event, ctx, "on-client-event");
+    const actions = await clientActions;
+    (0, import_server.after)(() => completion);
+    (0, import_server.after)(() => updateEvent(pageRenderId, { clientContext, userContext, anonymousUserId }, ctx));
+    const scripts = actions.items.filter((i) => i.type === "script-template");
+    return Response.json({ ok: true, scripts: scripts.length > 0 ? scripts : void 0 });
   } else if (type === "client-event") {
     const clientContext = payload.clientContext || void 0;
-    if (clientContext?.path) {
-      serverContext.path = clientContext.path;
-    }
+    const serverContext = clientContext ? reconstructServerContext(apiCallServerContext, clientContext) : apiCallServerContext;
+    const { anonId: anonymousUserId } = await (0, import_anonymous_user.resolveAnonymousUser)({
+      ctx,
+      serverContext,
+      config
+    });
     const event = {
       eventId: (0, import_uitils.generateId)(),
       parentEventId: pageRenderId,

package/dist/server.js

@@ -33,14 +33,19 @@ var import_handlers = require("./handlers");
 var import_config_helpers = require("./config-helpers");
 var import_middleware = require("./middleware");
 var import_uitils = require("./uitils");
-function resolveBackends(config, ctx) {
-  const backends = config.backends || [];
-  return backends.map((backend) => {
-    if (typeof backend === "function") {
-      return backend(ctx);
+function isBackendWithConfig(entry) {
+  return typeof entry === "object" && entry !== null && "backend" in entry;
+}
+function resolveBackends(config, ctx, policyFilter) {
+  const entries = config.backends || [];
+  return entries.map((entry) => {
+    if (isBackendWithConfig(entry)) {
+      const backend2 = typeof entry.backend === "function" ? entry.backend(ctx) : entry.backend;
+      return backend2 ? { backend: backend2, ingestPolicy: entry.ingestPolicy ?? "immediate" } : null;
     }
-    return backend;
-  }).filter((b) => b !== null);
+    const backend = typeof entry === "function" ? entry(ctx) : entry;
+    return backend ? { backend, ingestPolicy: "immediate" } : null;
+  }).filter((b) => b !== null).filter((b) => !policyFilter || b.ingestPolicy === policyFilter);
 }
 function resolvePlugins(config, ctx) {
   const plugins = config.plugins || [];
@@ -85,9 +90,9 @@ function Nextlytics(userConfig) {
   const config = (0, import_config_helpers.withDefaults)(userConfig);
   const validationResult = (0, import_config_helpers.validateConfig)(config);
   (0, import_config_helpers.logConfigWarnings)(validationResult);
-  const dispatchEventInternal = (event, ctx) => {
+  const dispatchEventInternal = (event, ctx, policyFilter) => {
     const plugins = resolvePlugins(config, ctx);
-    const backends = resolveBackends(config, ctx);
+    const resolved = resolveBackends(config, ctx, policyFilter);
     const pluginsDone = (async () => {
       for (const plugin of plugins) {
         try {
@@ -98,7 +103,7 @@ function Nextlytics(userConfig) {
       }
     })();
     const backendResults = pluginsDone.then(() => {
-      return backends.map((backend) => {
+      return resolved.map(({ backend }) => {
         const start = Date.now();
         const promise = backend.onEvent(event).then((result) => ({ ok: true, ms: Date.now() - start, result })).catch((err) => {
           console.error(`[Nextlytics] Backend "${backend.name}" failed on onEvent:`, err);
@@ -116,7 +121,7 @@ function Nextlytics(userConfig) {
     const completion = backendResults.then(async (results) => {
       const settled = await Promise.all(results.map((r) => r.promise));
       if (config.debug) {
-        const nameWidth = Math.max(...results.map((r) => r.backend.name.length));
+        const nameWidth = Math.max(...results.map((r) => r.backend.name.length), 1);
         console.log(
           `[Nextlytics] dispatchEvent ${event.type} ${event.eventId} (${results.length} backends)`
         );
@@ -131,9 +136,11 @@ function Nextlytics(userConfig) {
     return { clientActions, completion };
   };
   const updateEventInternal = async (eventId, patch, ctx) => {
-    const backends = resolveBackends(config, ctx).filter((backend) => backend.supportsUpdates);
+    const resolved = resolveBackends(config, ctx, "immediate").filter(
+      ({ backend }) => backend.supportsUpdates
+    );
     const results = await Promise.all(
-      backends.map(async (backend) => {
+      resolved.map(async ({ backend }) => {
         const start = Date.now();
         try {
           await backend.updateEvent(eventId, patch);
@@ -145,9 +152,9 @@ function Nextlytics(userConfig) {
         }
       })
     );
-    if (config.debug && backends.length > 0) {
-      const nameWidth = Math.max(...backends.map((b) => b.name.length));
-      console.log(`[Nextlytics] updateEvent ${eventId} (${backends.length} backends)`);
+    if (config.debug && resolved.length > 0) {
+      const nameWidth = Math.max(...resolved.map(({ backend }) => backend.name.length));
+      console.log(`[Nextlytics] updateEvent ${eventId} (${resolved.length} backends)`);
       results.forEach((r) => {
         const status = r.ok ? "ok" : "fail";
         console.log(`  ${r.backend.name.padEnd(nameWidth)}  ${status.padEnd(4)}  ${r.ms}ms`);
@@ -163,7 +170,7 @@ function Nextlytics(userConfig) {
     return updateEventInternal(eventId, patch, ctx);
   };
   const middleware = (0, import_middleware.createNextlyticsMiddleware)(config, dispatchEventInternal, updateEventInternal);
-  const handlers = (0, import_handlers.createHandlers)(config, dispatchEventInternal, updateEventInternal);
+  const handlers = (0, import_handlers.createHandlers)();
   const analytics = async () => {
     const headersList = await (0, import_headers.headers)();
     const cookieStore = await (0, import_headers.cookies)();

package/dist/types.d.ts

@@ -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 */
@@ -99,6 +109,20 @@ 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";
+/** Backend with configuration options */
+type BackendWithConfig = {
+    backend: NextlyticsBackend | NextlyticsBackendFactory;
+    /** When to send events. Default: "immediate" */
+    ingestPolicy?: IngestPolicy;
+};
+/** 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 +138,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 +156,7 @@ type NextlyticsConfig = {
         }) => Promise<AnonymousUserResult>;
     };
     /** Analytics backends to send events to */
-    backends?: (NextlyticsBackend | NextlyticsBackendFactory)[];
+    backends?: BackendConfigEntry[];
     plugins?: (NextlyticsPlugin | NextlyticsPluginFactory)[];
 };
 type ClientAction = {
@@ -213,4 +231,4 @@ type NextlyticsResult = {
     updateEvent: (eventId: string, patch: Partial<NextlyticsEvent>) => Promise<void>;
 };
 
-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, DispatchResult, IngestPolicy, JavascriptTemplate, NextlyticsBackend, NextlyticsBackendFactory, NextlyticsConfig, NextlyticsEvent, NextlyticsPlugin, NextlyticsPluginFactory, NextlyticsResult, NextlyticsServerSide, RequestContext, ScriptElement, ServerEventContext, TemplatizedScriptInsertion, UserContext };

package/package.json

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