feat: per-event user override in analytics().sendEvent() (#43)

sendEvent now accepts an optional `user` (UserContext) that identifies the event
explicitly, overriding callbacks.getUser for that event. This covers server
events whose subject isn't the request's session user — e.g. an email recipient
resolved from a tracking link — so they land as real identity (userId/traits)
instead of plain props.

Author: vklimontovich

packages/core/src/server.tsx

@@ -25,6 +25,7 @@ import type {
   NextlyticsResult,
   RequestContext,
   ServerEventContext,
+  UserContext,
 } from "./types";
 import { logConfigWarnings, validateConfig, withDefaults } from "./config-helpers";
 import { createNextlyticsMiddleware } from "./middleware";
@@ -314,7 +315,7 @@ export function Nextlytics(userConfig: NextlyticsConfig): NextlyticsResult {
     return {
       sendEvent: async (
         eventName: string,
-        opts?: { props?: Record<string, unknown> }
+        opts?: { props?: Record<string, unknown>; user?: UserContext }
       ): Promise<{ ok: boolean }> => {
         // In the App Router no-arg path a missing pageRenderId means middleware
         // never ran — keep that as a hard error. With an explicit `req` the
@@ -332,7 +333,9 @@ export function Nextlytics(userConfig: NextlyticsConfig): NextlyticsResult {
           collectedAt: new Date().toISOString(),
           anonymousUserId,
           serverContext,
-          userContext,
+          // An explicit per-event user (e.g. an email recipient resolved from a
+          // link) overrides the request-derived one from callbacks.getUser.
+          userContext: opts?.user ?? userContext,
           properties: { ...propsFromCallback, ...opts?.props },
         };
         // Await full delivery, not just dispatch kickoff. Unlike the middleware

packages/core/src/types.ts

@@ -255,7 +255,13 @@ export type NextlyticsServerSide = {
   /** Send custom event from a server component, server action, or API route */
   sendEvent: (
     eventName: string,
-    opts?: { props?: Record<string, unknown> }
+    opts?: {
+      props?: Record<string, unknown>;
+      /** Identify the event's user explicitly. Overrides callbacks.getUser for
+       * this event — e.g. an email recipient resolved from a link, where the
+       * request has no session to derive identity from. */
+      user?: UserContext;
+    }
   ) => Promise<{ ok: boolean }>;
 };