feat(core): add ingestPolicy for per-backend event timing control

- Add BackendWithConfig type with optional ingestPolicy field
- Support "immediate" (default) and "on-client-event" policies
- "immediate" backends receive events in middleware
- "on-client-event" backends wait for client-init with full context
- Enhance Segment backend with proper context.page and properties
- Collect additional client context: title, hash, url, search, host
- Remove deprecated pageViewMode config option

Author: vklimontovich

e2e/test-app/src/nextlytics.ts

@@ -1,12 +1,22 @@
 import { Nextlytics } from "@nextlytics/core/server";
+import type { BackendConfigEntry } from "@nextlytics/core";
 import { postgrestBackend } from "@nextlytics/core/backends/postgrest";
 import { auth } from "./auth";
 
-const backends = [
+const backends: BackendConfigEntry[] = [
+  // Immediate backend - receives events in middleware (no client context initially)
   postgrestBackend({
     url: process.env.POSTGREST_URL || "http://localhost:3001",
     tableName: "analytics",
   }),
+  // Delayed backend - receives events on client-init (has full client context)
+  {
+    backend: postgrestBackend({
+      url: process.env.POSTGREST_URL || "http://localhost:3001",
+      tableName: "analytics_delayed",
+    }),
+    ingestPolicy: "on-client-event",
+  },
 ];
 
 export const { middleware, handlers, analytics } = Nextlytics({

e2e/tests/analytics.test.ts

@@ -139,5 +139,50 @@ describe.each(versions)("%s", (version) => {
 
       await page.close();
     });
+
+    it("on-client-event backend receives events with full client context", async () => {
+      const page = await testApp.newPage();
+
+      await testApp.visitHome(page);
+
+      // Wait for events in both backends
+      const [immediateEvents, delayedEvents] = await Promise.all([
+        testApp.waitForEvents((e) =>
+          e.some((ev) => ev.type === "pageView" && ev.path === testApp.homePath)
+        ),
+        testApp.waitForDelayedEvents((e) =>
+          e.some((ev) => ev.type === "pageView" && ev.path === testApp.homePath)
+        ),
+      ]);
+
+      const immediatePageView = immediateEvents.find(
+        (e) => e.type === "pageView" && e.path === testApp.homePath
+      );
+      const delayedPageView = delayedEvents.find(
+        (e) => e.type === "pageView" && e.path === testApp.homePath
+      );
+
+      expect(immediatePageView).toBeDefined();
+      expect(delayedPageView).toBeDefined();
+
+      // Both should have the same event_id
+      expect(delayedPageView!.event_id).toBe(immediatePageView!.event_id);
+
+      // Delayed backend should have client_context with screen info
+      const delayedClientCtx = delayedPageView!.client_context as Record<string, unknown>;
+      expect(delayedClientCtx).toBeDefined();
+      expect(delayedClientCtx.screen).toBeDefined();
+
+      const screen = delayedClientCtx.screen as Record<string, unknown>;
+      expect(screen.width).toBeGreaterThan(0);
+      expect(screen.height).toBeGreaterThan(0);
+      expect(screen.innerWidth).toBeGreaterThan(0);
+      expect(screen.innerHeight).toBeGreaterThan(0);
+
+      // Delayed backend should have title (from document.title)
+      expect(delayedClientCtx.title).toBeDefined();
+
+      await page.close();
+    });
   });
 });

e2e/tests/test-app.ts

@@ -84,6 +84,25 @@ export class TestApp {
     throw new Error(`Timed out waiting for analytics events after ${timeout}ms`);
   }
 
+  /** Get events from the delayed (on-client-event) backend */
+  async getDelayedAnalyticsEvents(): Promise<AnalyticsEventRow[]> {
+    return this.services.getDelayedAnalyticsEvents();
+  }
+
+  /** Poll until delayed events match the predicate */
+  async waitForDelayedEvents(
+    predicate: (events: AnalyticsEventRow[]) => boolean,
+    { timeout = 5000, interval = 100 } = {}
+  ): Promise<AnalyticsEventRow[]> {
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      const events = await this.getDelayedAnalyticsEvents();
+      if (predicate(events)) return events;
+      await new Promise((r) => setTimeout(r, interval));
+    }
+    throw new Error(`Timed out waiting for delayed analytics events after ${timeout}ms`);
+  }
+
   // Test action helpers
   async login(page: Page): Promise<void> {
     await page.goto(`${this.baseUrl}${this.loginPath}`);

e2e/tests/thirdparty-services.ts

@@ -14,7 +14,10 @@ import {
 
 export type { AnalyticsEventRow };
 
-const INIT_SQL = generatePgCreateTableSQL("analytics");
+const INIT_SQL = [
+  generatePgCreateTableSQL("analytics"),
+  generatePgCreateTableSQL("analytics_delayed"),
+].join("\n");
 
 const PG_ALIAS = "postgres";
 
@@ -109,6 +112,7 @@ export class ThirdpartyServices {
 
   async clearAnalytics(): Promise<void> {
     await this.getPool().query("DELETE FROM analytics");
+    await this.getPool().query("DELETE FROM analytics_delayed");
   }
 
   async getAnalyticsEvents(): Promise<AnalyticsEventRow[]> {
@@ -125,4 +129,12 @@ export class ThirdpartyServices {
     );
     return result.rows;
   }
+
+  /** Get events from the delayed (on-client-event) backend */
+  async getDelayedAnalyticsEvents(): Promise<AnalyticsEventRow[]> {
+    const result = await this.getPool().query<AnalyticsEventRow>(
+      "SELECT * FROM analytics_delayed ORDER BY timestamp ASC"
+    );
+    return result.rows;
+  }
 }

packages/core/src/backends/segment.ts

@@ -54,6 +54,36 @@ export function segmentBackend(config: SegmentBackendConfig): NextlyticsBackend
     }
   }
 
+  function buildUrl(event: NextlyticsEvent): string {
+    // Prefer client-provided URL if available
+    if (event.clientContext?.url) return event.clientContext.url;
+
+    const { host, path, search } = event.serverContext;
+    const protocol = host.includes("localhost") || host.match(/^[\d.:]+$/) ? "http" : "https";
+    const searchStr = Object.entries(search)
+      .flatMap(([k, vals]) => vals.map((v) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`))
+      .join("&");
+    return `${protocol}://${host}${path}${searchStr ? `?${searchStr}` : ""}`;
+  }
+
+  function getSearchString(event: NextlyticsEvent): string {
+    // Prefer client-provided search if available
+    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?: string): string | undefined {
+    if (!referer) return undefined;
+    try {
+      return new URL(referer).hostname;
+    } catch {
+      return undefined;
+    }
+  }
+
   function buildContext(event: NextlyticsEvent) {
     const ctx: Record<string, unknown> = {
       ip: event.serverContext.ip,
@@ -63,20 +93,29 @@ export function segmentBackend(config: SegmentBackendConfig): NextlyticsBackend
       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,
         };
       }
     }
@@ -85,12 +124,19 @@ export function segmentBackend(config: SegmentBackendConfig): NextlyticsBackend
   }
 
   function buildProperties(event: NextlyticsEvent) {
+    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,
     };
   }

packages/core/src/client.tsx

@@ -32,6 +32,11 @@ function createClientContext(): ClientContext {
     collectedAt: new Date(),
     referer: isBrowser ? document.referrer || undefined : undefined,
     path: isBrowser ? window.location.pathname : undefined,
+    url: isBrowser ? window.location.href : undefined,
+    host: isBrowser ? window.location.host : undefined,
+    search: isBrowser ? window.location.search : undefined,
+    hash: isBrowser ? window.location.hash : undefined,
+    title: isBrowser ? document.title : undefined,
     screen: {
       width: isBrowser ? window.screen.width : undefined,
       height: isBrowser ? window.screen.height : undefined,

packages/core/src/config-helpers.ts

@@ -1,10 +1,7 @@
 import type { NextlyticsConfig } from "./types";
 
 export type NextlyticsConfigWithDefaults = Required<
-  Pick<
-    NextlyticsConfig,
-    "pageViewMode" | "excludeApiCalls" | "eventEndpoint" | "isApiPath" | "backends"
-  >
+  Pick<NextlyticsConfig, "excludeApiCalls" | "eventEndpoint" | "isApiPath" | "backends">
 > &
   NextlyticsConfig & {
     anonymousUsers: Required<NonNullable<NextlyticsConfig["anonymousUsers"]>>;
@@ -13,7 +10,6 @@ export type NextlyticsConfigWithDefaults = Required<
 export function withDefaults(config: NextlyticsConfig): NextlyticsConfigWithDefaults {
   return {
     ...config,
-    pageViewMode: config.pageViewMode ?? "server",
     excludeApiCalls: config.excludeApiCalls ?? false,
     eventEndpoint: config.eventEndpoint ?? "/api/event",
     isApiPath: config.isApiPath ?? (() => false),
@@ -33,27 +29,9 @@ export interface ConfigValidationResult {
   warnings: string[];
 }
 
-export function validateConfig(config: NextlyticsConfig): ConfigValidationResult {
-  const warnings: string[] = [];
-
-  if (config.pageViewMode === "client-init" && config.backends?.length) {
-    // Only check non-factory backends (factories are resolved at runtime)
-    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,
-  };
+export function validateConfig(_config: NextlyticsConfig): ConfigValidationResult {
+  // Currently no validations - can add backend-specific checks here
+  return { valid: true, warnings: [] };
 }
 
 export function logConfigWarnings(result: ConfigValidationResult): void {