@nextlytics/core 0.1.0-canary-1

package/dist/plugins/vercel-geo.d.ts

@@ -0,0 +1,25 @@
+import { NextlyticsPlugin } from '../types.js';
+import 'next/dist/server/web/spec-extension/cookies';
+import 'next/server';
+
+type VercelGeoPluginOptions = {
+    /** Property name to store geo data under. Default: "geo" */
+    geoPropertyName?: string;
+};
+/**
+ * Plugin that extracts Vercel geo headers and adds them to event properties.
+ * Only works when deployed to Vercel.
+ *
+ * @example
+ * ```ts
+ * import { vercelGeoPlugin } from "@nextlytics/core/plugins/vercel-geo";
+ *
+ * export const { middleware, handlers } = Nextlytics({
+ *   plugins: [vercelGeoPlugin()],
+ *   // ...
+ * });
+ * ```
+ */
+declare function vercelGeoPlugin(options?: VercelGeoPluginOptions): NextlyticsPlugin;
+
+export { type VercelGeoPluginOptions, vercelGeoPlugin };

package/dist/plugins/vercel-geo.js

@@ -0,0 +1,36 @@
+const VERCEL_GEO_HEADERS = {
+  "x-vercel-ip-country": "country",
+  "x-vercel-ip-country-region": "region",
+  "x-vercel-ip-city": "city",
+  "x-vercel-ip-latitude": "latitude",
+  "x-vercel-ip-longitude": "longitude",
+  "x-vercel-ip-timezone": "timezone"
+};
+function vercelGeoPlugin(options) {
+  const geoPropertyName = options?.geoPropertyName ?? "geo";
+  return {
+    async onDispatch(event) {
+      const headers = event.serverContext.requestHeaders;
+      const geo = {};
+      for (const [header, prop] of Object.entries(VERCEL_GEO_HEADERS)) {
+        const value = headers[header];
+        if (value) {
+          if (prop === "latitude" || prop === "longitude") {
+            const num = parseFloat(value);
+            if (!isNaN(num)) {
+              geo[prop] = num;
+            }
+          } else {
+            geo[prop] = value;
+          }
+        }
+      }
+      if (Object.keys(geo).length > 0) {
+        event.properties[geoPropertyName] = geo;
+      }
+    }
+  };
+}
+export {
+  vercelGeoPlugin
+};

package/dist/server-component-context.cjs

@@ -0,0 +1,95 @@
+"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 server_component_context_exports = {};
+__export(server_component_context_exports, {
+  headers: () => headerKeys,
+  restoreServerComponentContext: () => restoreServerComponentContext,
+  serializeServerComponentContext: () => serializeServerComponentContext
+});
+module.exports = __toCommonJS(server_component_context_exports);
+const HEADER_PREFIX = "x-nc-";
+const headerKeys = {
+  pathname: `${HEADER_PREFIX}pathname`,
+  search: `${HEADER_PREFIX}search`,
+  pageRenderId: `${HEADER_PREFIX}page-render-id`,
+  scripts: `${HEADER_PREFIX}scripts`,
+  templates: `${HEADER_PREFIX}templates`
+};
+function serializeServerComponentContext(response, ctx) {
+  response.headers.set(headerKeys.pageRenderId, ctx.pageRenderId);
+  response.headers.set(headerKeys.pathname, ctx.pathname);
+  response.headers.set(headerKeys.search, ctx.search);
+  if (ctx.scripts.length > 0) {
+    const scriptParts = ctx.scripts.filter((item) => item.type === "script-template").map((s) => `${s.templateId}=${JSON.stringify(s.params)}`);
+    if (scriptParts.length > 0) {
+      response.headers.set(headerKeys.scripts, scriptParts.join(";"));
+    }
+  }
+  if (Object.keys(ctx.templates).length > 0) {
+    response.headers.set(headerKeys.templates, JSON.stringify(ctx.templates));
+  }
+}
+function parseScriptsHeader(header) {
+  const scripts = [];
+  for (const part of header.split(";")) {
+    const eqIdx = part.indexOf("=");
+    if (eqIdx === -1) continue;
+    const templateId = part.slice(0, eqIdx);
+    const paramsJson = part.slice(eqIdx + 1);
+    try {
+      const params = JSON.parse(paramsJson);
+      scripts.push({ type: "script-template", templateId, params });
+    } catch {
+      console.warn(`[Nextlytics] Failed to parse script params for ${templateId}`);
+    }
+  }
+  return scripts;
+}
+function restoreServerComponentContext(headersList) {
+  const pageRenderId = headersList.get(headerKeys.pageRenderId);
+  if (!pageRenderId) {
+    return null;
+  }
+  const pathname = headersList.get(headerKeys.pathname) || "";
+  const search = headersList.get(headerKeys.search) || "";
+  const scriptsHeader = headersList.get(headerKeys.scripts);
+  const scripts = scriptsHeader ? parseScriptsHeader(scriptsHeader) : [];
+  let templates = {};
+  const templatesHeader = headersList.get(headerKeys.templates);
+  if (templatesHeader) {
+    try {
+      templates = JSON.parse(templatesHeader);
+    } catch {
+      console.warn("[Nextlytics] Failed to parse templates header");
+    }
+  }
+  return {
+    pageRenderId,
+    pathname,
+    search,
+    scripts,
+    templates
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  headers,
+  restoreServerComponentContext,
+  serializeServerComponentContext
+});

package/dist/server-component-context.d.mts

@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server';
+import { TemplatizedScriptInsertion, JavascriptTemplate } from './types.mjs';
+import 'next/dist/server/web/spec-extension/cookies';
+
+declare const headerKeys: {
+    readonly pathname: "x-nc-pathname";
+    readonly search: "x-nc-search";
+    readonly pageRenderId: "x-nc-page-render-id";
+    readonly scripts: "x-nc-scripts";
+    readonly templates: "x-nc-templates";
+};
+/** Context passed from middleware to server components via headers */
+type ServerComponentContext = {
+    /** Unique page render ID (event ID) */
+    pageRenderId: string;
+    /** Request pathname */
+    pathname: string;
+    /** Query string */
+    search: string;
+    /** Script actions to execute on client */
+    scripts: TemplatizedScriptInsertion<unknown>[];
+    /** Template definitions for scripts */
+    templates: Record<string, JavascriptTemplate>;
+};
+/** Serialize context to response headers (called in middleware) */
+declare function serializeServerComponentContext(response: NextResponse, ctx: ServerComponentContext): void;
+/** Restore context from request headers (called in server components) */
+declare function restoreServerComponentContext(headersList: Headers): ServerComponentContext | null;
+
+export { type ServerComponentContext, headerKeys as headers, restoreServerComponentContext, serializeServerComponentContext };

package/dist/server-component-context.d.ts

@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server';
+import { TemplatizedScriptInsertion, JavascriptTemplate } from './types.js';
+import 'next/dist/server/web/spec-extension/cookies';
+
+declare const headerKeys: {
+    readonly pathname: "x-nc-pathname";
+    readonly search: "x-nc-search";
+    readonly pageRenderId: "x-nc-page-render-id";
+    readonly scripts: "x-nc-scripts";
+    readonly templates: "x-nc-templates";
+};
+/** Context passed from middleware to server components via headers */
+type ServerComponentContext = {
+    /** Unique page render ID (event ID) */
+    pageRenderId: string;
+    /** Request pathname */
+    pathname: string;
+    /** Query string */
+    search: string;
+    /** Script actions to execute on client */
+    scripts: TemplatizedScriptInsertion<unknown>[];
+    /** Template definitions for scripts */
+    templates: Record<string, JavascriptTemplate>;
+};
+/** Serialize context to response headers (called in middleware) */
+declare function serializeServerComponentContext(response: NextResponse, ctx: ServerComponentContext): void;
+/** Restore context from request headers (called in server components) */
+declare function restoreServerComponentContext(headersList: Headers): ServerComponentContext | null;
+
+export { type ServerComponentContext, headerKeys as headers, restoreServerComponentContext, serializeServerComponentContext };

package/dist/server-component-context.js

@@ -0,0 +1,69 @@
+const HEADER_PREFIX = "x-nc-";
+const headerKeys = {
+  pathname: `${HEADER_PREFIX}pathname`,
+  search: `${HEADER_PREFIX}search`,
+  pageRenderId: `${HEADER_PREFIX}page-render-id`,
+  scripts: `${HEADER_PREFIX}scripts`,
+  templates: `${HEADER_PREFIX}templates`
+};
+function serializeServerComponentContext(response, ctx) {
+  response.headers.set(headerKeys.pageRenderId, ctx.pageRenderId);
+  response.headers.set(headerKeys.pathname, ctx.pathname);
+  response.headers.set(headerKeys.search, ctx.search);
+  if (ctx.scripts.length > 0) {
+    const scriptParts = ctx.scripts.filter((item) => item.type === "script-template").map((s) => `${s.templateId}=${JSON.stringify(s.params)}`);
+    if (scriptParts.length > 0) {
+      response.headers.set(headerKeys.scripts, scriptParts.join(";"));
+    }
+  }
+  if (Object.keys(ctx.templates).length > 0) {
+    response.headers.set(headerKeys.templates, JSON.stringify(ctx.templates));
+  }
+}
+function parseScriptsHeader(header) {
+  const scripts = [];
+  for (const part of header.split(";")) {
+    const eqIdx = part.indexOf("=");
+    if (eqIdx === -1) continue;
+    const templateId = part.slice(0, eqIdx);
+    const paramsJson = part.slice(eqIdx + 1);
+    try {
+      const params = JSON.parse(paramsJson);
+      scripts.push({ type: "script-template", templateId, params });
+    } catch {
+      console.warn(`[Nextlytics] Failed to parse script params for ${templateId}`);
+    }
+  }
+  return scripts;
+}
+function restoreServerComponentContext(headersList) {
+  const pageRenderId = headersList.get(headerKeys.pageRenderId);
+  if (!pageRenderId) {
+    return null;
+  }
+  const pathname = headersList.get(headerKeys.pathname) || "";
+  const search = headersList.get(headerKeys.search) || "";
+  const scriptsHeader = headersList.get(headerKeys.scripts);
+  const scripts = scriptsHeader ? parseScriptsHeader(scriptsHeader) : [];
+  let templates = {};
+  const templatesHeader = headersList.get(headerKeys.templates);
+  if (templatesHeader) {
+    try {
+      templates = JSON.parse(templatesHeader);
+    } catch {
+      console.warn("[Nextlytics] Failed to parse templates header");
+    }
+  }
+  return {
+    pageRenderId,
+    pathname,
+    search,
+    scripts,
+    templates
+  };
+}
+export {
+  headerKeys as headers,
+  restoreServerComponentContext,
+  serializeServerComponentContext
+};

package/dist/server.cjs

@@ -0,0 +1,236 @@
+"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 server_exports = {};
+__export(server_exports, {
+  Nextlytics: () => Nextlytics,
+  NextlyticsServer: () => NextlyticsServer,
+  createRequestContext: () => createRequestContext
+});
+module.exports = __toCommonJS(server_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var import_headers = require("next/headers");
+var import_headers2 = require("./headers");
+var import_server_component_context = require("./server-component-context");
+var import_anonymous_user = require("./anonymous-user");
+var import_client = require("./client");
+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);
+    }
+    return backend;
+  }).filter((b) => b !== null);
+}
+function resolvePlugins(config, ctx) {
+  const plugins = config.plugins || [];
+  return plugins.map((plugin) => {
+    if (typeof plugin === "function") {
+      if (!ctx) {
+        return null;
+      }
+      return plugin(ctx);
+    }
+    return plugin;
+  }).filter((p) => p !== null);
+}
+function mergeClientActions(actions) {
+  const items = [];
+  for (const action of actions) {
+    if (action?.items) {
+      items.push(...action.items);
+    }
+  }
+  return { items };
+}
+async function createRequestContext() {
+  const [_cookies, _headers] = await Promise.all([(0, import_headers.cookies)(), (0, import_headers.headers)()]);
+  return {
+    cookies: _cookies,
+    headers: _headers
+  };
+}
+async function NextlyticsServer({ children }) {
+  const headersList = await (0, import_headers.headers)();
+  const ctx = (0, import_server_component_context.restoreServerComponentContext)(headersList);
+  if (!ctx) {
+    console.warn(
+      "[Nextlytics] nextlyticsMiddleware should be added in order for NextlyticsServer to work"
+    );
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_client.NextlyticsClient, { requestId: ctx.pageRenderId, scripts: ctx.scripts, templates: ctx.templates, children });
+}
+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 plugins = resolvePlugins(config, ctx);
+    const backends = resolveBackends(config, ctx);
+    const pluginsDone = (async () => {
+      for (const plugin of plugins) {
+        try {
+          await plugin.onDispatch(event);
+        } catch (err) {
+          console.warn("[Nextlytics] Plugin failed on onDispatch:", err);
+        }
+      }
+    })();
+    const backendResults = pluginsDone.then(() => {
+      return backends.map((backend) => {
+        const start = Date.now();
+        const promise = backend.onEvent(event).then((result) => ({ ok: true, ms: Date.now() - start, result })).catch((err) => {
+          console.warn(`[Nextlytics] Backend "${backend.name}" failed on onEvent:`, err);
+          return { ok: false, ms: Date.now() - start, result: void 0 };
+        });
+        return { backend, promise };
+      });
+    });
+    const clientActions = backendResults.then(async (results) => {
+      const actionResults = results.filter((r) => r.backend.returnsClientActions);
+      const actions = await Promise.all(actionResults.map((r) => r.promise));
+      return mergeClientActions(actions.map((a) => a.result));
+    });
+    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));
+        console.log(
+          `[Nextlytics] dispatchEvent ${event.type} ${event.eventId} (${results.length} backends)`
+        );
+        results.forEach((r, i) => {
+          const s = settled[i];
+          const status = s.ok ? "ok" : "fail";
+          console.log(`  ${r.backend.name.padEnd(nameWidth)}  ${status.padEnd(4)}  ${s.ms}ms`);
+        });
+      }
+    }).then(() => {
+    });
+    return { clientActions, completion };
+  };
+  const updateEventInternal = async (eventId, patch, ctx) => {
+    const backends = resolveBackends(config, ctx).filter((backend) => backend.supportsUpdates);
+    const results = await Promise.all(
+      backends.map(async (backend) => {
+        const start = Date.now();
+        try {
+          await backend.updateEvent(eventId, patch);
+          return { backend, ok: true, ms: Date.now() - start };
+        } catch (err) {
+          console.warn(`[Nextlytics] Backend "${backend.name}" failed on updateEvent:`, err);
+          return { backend, ok: false, ms: Date.now() - start };
+        }
+      })
+    );
+    if (config.debug && backends.length > 0) {
+      const nameWidth = Math.max(...backends.map((b) => b.name.length));
+      console.log(`[Nextlytics] updateEvent ${eventId} (${backends.length} backends)`);
+      results.forEach((r) => {
+        const status = r.ok ? "ok" : "fail";
+        console.log(`  ${r.backend.name.padEnd(nameWidth)}  ${status.padEnd(4)}  ${r.ms}ms`);
+      });
+    }
+  };
+  const dispatchEvent = async (event) => {
+    const ctx = await createRequestContext();
+    return dispatchEventInternal(event, ctx);
+  };
+  const updateEvent = async (eventId, patch) => {
+    const ctx = await createRequestContext();
+    return updateEventInternal(eventId, patch, ctx);
+  };
+  const middleware = (0, import_middleware.createNextlyticsMiddleware)(config, dispatchEventInternal, updateEventInternal);
+  const handlers = (0, import_handlers.createHandlers)(config, dispatchEventInternal, updateEventInternal);
+  const analytics = async () => {
+    const headersList = await (0, import_headers.headers)();
+    const cookieStore = await (0, import_headers.cookies)();
+    const pageRenderId = headersList.get(import_server_component_context.headers.pageRenderId);
+    const serverContext = createServerContextFromHeaders(headersList);
+    const ctx = { headers: headersList, cookies: cookieStore };
+    const { anonId: anonymousUserId } = await (0, import_anonymous_user.resolveAnonymousUser)({ ctx, serverContext, config });
+    let userContext;
+    if (config.callbacks.getUser) {
+      try {
+        userContext = await config.callbacks.getUser(ctx) || void 0;
+      } catch {
+      }
+    }
+    return {
+      sendEvent: async (eventName, opts) => {
+        if (!pageRenderId) {
+          console.error("[Nextlytics] analytics() requires nextlyticsMiddleware");
+          return { ok: false };
+        }
+        const event = {
+          eventId: (0, import_uitils.generateId)(),
+          parentEventId: pageRenderId,
+          type: eventName,
+          collectedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          anonymousUserId,
+          serverContext,
+          userContext,
+          properties: opts?.props || {}
+        };
+        await dispatchEventInternal(event, ctx);
+        return { ok: true };
+      }
+    };
+  };
+  return { middleware, handlers, analytics, dispatchEvent, updateEvent };
+}
+function createServerContextFromHeaders(headersList) {
+  const rawHeaders = {};
+  headersList.forEach((value, key) => {
+    rawHeaders[key] = value;
+  });
+  const requestHeaders = (0, import_headers2.removeSensitiveHeaders)(rawHeaders);
+  const pathname = headersList.get(import_server_component_context.headers.pathname) || "";
+  const search = headersList.get(import_server_component_context.headers.search) || "";
+  const searchParams = {};
+  if (search) {
+    const params = new URLSearchParams(search);
+    params.forEach((value, key) => {
+      if (!searchParams[key]) {
+        searchParams[key] = [];
+      }
+      searchParams[key].push(value);
+    });
+  }
+  return {
+    collectedAt: /* @__PURE__ */ new Date(),
+    host: headersList.get("host") || "",
+    method: "GET",
+    path: pathname,
+    search: searchParams,
+    ip: headersList.get("x-forwarded-for")?.split(",")[0]?.trim() || "",
+    requestHeaders,
+    responseHeaders: {}
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Nextlytics,
+  NextlyticsServer,
+  createRequestContext
+});

package/dist/server.d.mts

@@ -0,0 +1,13 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { NextlyticsConfig, NextlyticsResult, RequestContext } from './types.mjs';
+import 'next/dist/server/web/spec-extension/cookies';
+import 'next/server';
+
+declare function createRequestContext(): Promise<RequestContext>;
+declare function NextlyticsServer({ children }: {
+    children: ReactNode;
+}): Promise<react_jsx_runtime.JSX.Element>;
+declare function Nextlytics(userConfig: NextlyticsConfig): NextlyticsResult;
+
+export { Nextlytics, NextlyticsServer, createRequestContext };

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { NextlyticsConfig, NextlyticsResult, RequestContext } from './types.js';
+import 'next/dist/server/web/spec-extension/cookies';
+import 'next/server';
+
+declare function createRequestContext(): Promise<RequestContext>;
+declare function NextlyticsServer({ children }: {
+    children: ReactNode;
+}): Promise<react_jsx_runtime.JSX.Element>;
+declare function Nextlytics(userConfig: NextlyticsConfig): NextlyticsResult;
+
+export { Nextlytics, NextlyticsServer, createRequestContext };