@nextlytics/core 0.1.0-canary-1

package/dist/types.d.ts

@@ -0,0 +1,216 @@
+import { RequestCookies } from 'next/dist/server/web/spec-extension/cookies';
+import { NextRequest, NextMiddleware } from 'next/server';
+
+/** Server-side request context collected in middleware */
+interface ServerEventContext {
+    /** When the event was collected on server */
+    collectedAt: Date;
+    /** Request host (e.g. "example.com") */
+    host: string;
+    /** HTTP method (GET, POST, etc.) */
+    method: string;
+    /** URL pathname (e.g. "/products/123") */
+    path: string;
+    /** Query parameters as key -> values[] */
+    search: Record<string, string[]>;
+    /** Client IP from x-forwarded-for or direct connection */
+    ip: string;
+    /** Request headers (sensitive ones removed) */
+    requestHeaders: Record<string, string>;
+    /** Response headers */
+    responseHeaders: Record<string, string>;
+}
+/** Client-side context collected in browser */
+interface ClientContext {
+    /** When the event was collected on client */
+    collectedAt: Date;
+    /** document.referrer */
+    referer?: string;
+    /** window.location.pathname - may differ from server path in SPAs */
+    path?: string;
+    /** Screen and viewport dimensions */
+    screen: {
+        /** screen.width */
+        width?: number;
+        /** screen.height */
+        height?: number;
+        /** window.innerWidth (viewport) */
+        innerWidth?: number;
+        /** window.innerHeight (viewport) */
+        innerHeight?: number;
+        /** window.devicePixelRatio */
+        density?: number;
+    };
+    /** navigator.userAgent */
+    userAgent?: string;
+    /** navigator.language */
+    locale?: string;
+}
+/** Identified user context */
+interface UserContext {
+    /** Unique user identifier */
+    userId: string;
+    /** User traits for identification */
+    traits: {
+        email?: string;
+        name?: string;
+        phone?: string;
+    } & Record<string, unknown>;
+}
+/** Analytics event sent to backends */
+interface NextlyticsEvent {
+    /** ISO timestamp when event was collected */
+    collectedAt: string;
+    /** Unique event ID */
+    eventId: string;
+    /** Parent event ID (e.g. pageView for client events) */
+    parentEventId?: string;
+    /** Event type (e.g. "pageView", "apiCall", custom events) */
+    type: "pageView" | "apiCall" | string;
+    /** Anonymous user identifier (GDPR-compliant hash or cookie-based) */
+    anonymousUserId?: string;
+    /** Server-side request context */
+    serverContext: ServerEventContext;
+    /** Identified user context */
+    userContext?: UserContext;
+    /** Client-side browser context */
+    clientContext?: ClientContext;
+    /** Custom event properties */
+    properties: Record<string, unknown>;
+}
+
+type AnonymousUserResult = {
+    /** Anonymous user identifier */
+    anonId: string;
+};
+/** Headers and cookies context for backend/plugin factories. Uses Pick for compatibility with both
+ * middleware (RequestCookies) and server components (ReadonlyRequestCookies) */
+type RequestContext = {
+    headers: Headers;
+    cookies: Pick<RequestCookies, "get" | "getAll" | "has">;
+};
+type NextlyticsPlugin = {
+    /**
+     * Called right after event is created but before it's sent to backends.
+     * Plugin can mutate the event to add/modify properties.
+     * @param event - The event to process (can be mutated)
+     */
+    onDispatch(event: NextlyticsEvent): Promise<void>;
+};
+/** Factory to create plugin per-request (for request-scoped plugins) */
+type NextlyticsPluginFactory = (ctx: RequestContext) => NextlyticsPlugin;
+type NextlyticsConfig = {
+    /** Enable debug logging (shows backend stats for each event) */
+    debug?: boolean;
+    anonymousUsers?: {
+        /** Store anonymous ID in cookies */
+        useCookies?: boolean;
+        /** Use hash-based IDs for GDPR compliance (default: true) */
+        gdprMode?: boolean;
+        /** Rotate hash salt daily for shorter-lived IDs (default: true) */
+        dailySalt?: boolean;
+        /** Cookie name when useCookies=true (default: "__nextlytics_anon") */
+        cookieName?: string;
+        /** 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 */
+    excludePaths?: (path: string) => boolean;
+    /** Determine if path is API route. Default: () => false */
+    isApiPath?: (path: string) => boolean;
+    /** Endpoint for client events. Default: "/api/event" */
+    eventEndpoint?: string;
+    callbacks: {
+        /** Resolve authenticated user from request context */
+        getUser?: (ctx: RequestContext) => Promise<UserContext | undefined>;
+        /** Override anonymous user ID generation */
+        getAnonymousUserId?: (opts: {
+            ctx: RequestContext;
+            originalAnonymousUserId?: string;
+        }) => Promise<AnonymousUserResult>;
+    };
+    /** Analytics backends to send events to */
+    backends?: (NextlyticsBackend | NextlyticsBackendFactory)[];
+    plugins?: (NextlyticsPlugin | NextlyticsPluginFactory)[];
+};
+type ClientAction = {
+    items: ClientActionItem[];
+};
+type ClientActionItem = TemplatizedScriptInsertion<unknown>;
+/**
+ * Inserts scripts to a page as
+ * `<script scr={src}></script>` or <script>{body}</script>
+ */
+type TemplatizedScriptInsertion<T> = {
+    type: "script-template";
+    params: T;
+    templateId: string;
+};
+/** Result of dispatching an event (two-phase) */
+type DispatchResult = {
+    /** Resolves quickly with actions from backends with returnsClientActions=true */
+    clientActions: Promise<ClientAction>;
+    /** Resolves when ALL backends complete processing */
+    completion: Promise<void>;
+};
+type JavascriptTemplate = {
+    items: ScriptElement[];
+};
+type ScriptElement = {
+    async?: string;
+    body?: string;
+    src?: string;
+    /** If true, skip insertion if script with same src already exists */
+    singleton?: boolean;
+};
+/** Backend that receives analytics events */
+type NextlyticsBackend = {
+    /** Backend name for logging */
+    name: string;
+    /** Whether backend supports updating existing events */
+    supportsUpdates?: boolean;
+    /**
+     * If onEvent can return client actions
+     */
+    returnsClientActions?: boolean;
+    getClientSideTemplates?: () => Record<string, JavascriptTemplate>;
+    /** Handle new event */
+    onEvent(event: NextlyticsEvent): Promise<void | ClientAction>;
+    /** Update existing event (e.g. add client context to server pageView) */
+    updateEvent(eventId: string, patch: Partial<NextlyticsEvent>): Promise<void> | void;
+};
+/** Factory to create backend per-request (for request-scoped backends) */
+type NextlyticsBackendFactory = (ctx: RequestContext) => NextlyticsBackend;
+/** Server-side analytics API */
+type NextlyticsServerSide = {
+    /** Send custom event from server component/action */
+    sendEvent: (eventName: string, opts?: {
+        props?: Record<string, unknown>;
+    }) => Promise<{
+        ok: boolean;
+    }>;
+};
+type AppRouteHandlers = Record<"GET" | "POST", (req: NextRequest) => Promise<Response>>;
+/** Return value from Nextlytics() */
+type NextlyticsResult = {
+    /** Route handlers for /api/event */
+    handlers: AppRouteHandlers;
+    /** Get server-side analytics API */
+    analytics: () => Promise<NextlyticsServerSide>;
+    /** Middleware to intercept requests */
+    middleware: NextMiddleware;
+    /** Manually dispatch event (returns two-phase result) */
+    dispatchEvent: (event: NextlyticsEvent) => Promise<DispatchResult>;
+    /** Manually update existing event */
+    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 };

package/dist/uitils.cjs

@@ -0,0 +1,94 @@
+"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 uitils_exports = {};
+__export(uitils_exports, {
+  createServerContext: () => createServerContext,
+  generateId: () => generateId,
+  getRequestInfo: () => getRequestInfo
+});
+module.exports = __toCommonJS(uitils_exports);
+var import_headers = require("./headers");
+const BASE62_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+function generateId() {
+  const length = 16;
+  const bytes = new Uint8Array(length * 2);
+  crypto.getRandomValues(bytes);
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    const idx = (bytes[i * 2] * 256 + bytes[i * 2 + 1]) % 62;
+    result += BASE62_CHARS[idx];
+  }
+  return result;
+}
+function getRequestInfo(request) {
+  const headers = request.headers;
+  const pathname = request.nextUrl.pathname;
+  const isNextjsInternal = pathname.startsWith("/_next");
+  const isStaticFile = /\.(ico|png|jpg|jpeg|gif|svg|webp|css|js|woff2?|ttf|eot|map)$/i.test(
+    pathname
+  );
+  const hasStandardPrefetchHeader = headers.get("next-router-prefetch") === "1" || headers.get("purpose") === "prefetch" || headers.get("sec-purpose") === "prefetch";
+  const nextUrl = headers.get("next-url");
+  const isRscPrefetch = nextUrl !== null && nextUrl !== pathname;
+  const isPrefetch = hasStandardPrefetchHeader || isRscPrefetch;
+  const isRsc = !!(nextUrl || headers.get("rsc"));
+  const secFetchDest = headers.get("sec-fetch-dest");
+  const secFetchMode = headers.get("sec-fetch-mode");
+  const accept = headers.get("accept") || "";
+  const isDocumentRequest = secFetchDest === "document" || secFetchMode === "navigate";
+  const acceptsHtml = accept.includes("text/html");
+  const isPageNavigation = isRsc || isDocumentRequest || acceptsHtml;
+  return {
+    isPrefetch,
+    isRsc,
+    isPageNavigation,
+    isStaticFile,
+    isNextjsInternal
+  };
+}
+function createServerContext(request) {
+  const rawHeaders = {};
+  request.headers.forEach((value, key) => {
+    rawHeaders[key] = value;
+  });
+  const requestHeaders = (0, import_headers.removeSensitiveHeaders)(rawHeaders);
+  const searchParams = {};
+  request.nextUrl.searchParams.forEach((value, key) => {
+    if (!searchParams[key]) {
+      searchParams[key] = [];
+    }
+    searchParams[key].push(value);
+  });
+  return {
+    collectedAt: /* @__PURE__ */ new Date(),
+    host: request.headers.get("host") || "",
+    method: request.method,
+    path: request.nextUrl.pathname,
+    search: searchParams,
+    ip: request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || "",
+    requestHeaders,
+    responseHeaders: {}
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createServerContext,
+  generateId,
+  getRequestInfo
+});

package/dist/uitils.d.mts

@@ -0,0 +1,22 @@
+import { NextRequest } from 'next/server';
+import { ServerEventContext } from './types.mjs';
+import 'next/dist/server/web/spec-extension/cookies';
+
+/** Generate a random base62 ID (16 chars = 62^16 ≈ 4.7 × 10^28 combinations) */
+declare function generateId(): string;
+type RequestInfo = {
+    /** True if this is a prefetch request (browser or Next.js router prefetch) */
+    isPrefetch: boolean;
+    /** True if this is an RSC (React Server Components) navigation */
+    isRsc: boolean;
+    /** True if this is a standard document or RSC navigation */
+    isPageNavigation: boolean;
+    /** True if this is a static file (ico, png, css, js, etc.) */
+    isStaticFile: boolean;
+    /** True if this is a Next.js internal path (/_next/*) */
+    isNextjsInternal: boolean;
+};
+declare function getRequestInfo(request: NextRequest): RequestInfo;
+declare function createServerContext(request: NextRequest): ServerEventContext;
+
+export { type RequestInfo, createServerContext, generateId, getRequestInfo };

package/dist/uitils.d.ts

@@ -0,0 +1,22 @@
+import { NextRequest } from 'next/server';
+import { ServerEventContext } from './types.js';
+import 'next/dist/server/web/spec-extension/cookies';
+
+/** Generate a random base62 ID (16 chars = 62^16 ≈ 4.7 × 10^28 combinations) */
+declare function generateId(): string;
+type RequestInfo = {
+    /** True if this is a prefetch request (browser or Next.js router prefetch) */
+    isPrefetch: boolean;
+    /** True if this is an RSC (React Server Components) navigation */
+    isRsc: boolean;
+    /** True if this is a standard document or RSC navigation */
+    isPageNavigation: boolean;
+    /** True if this is a static file (ico, png, css, js, etc.) */
+    isStaticFile: boolean;
+    /** True if this is a Next.js internal path (/_next/*) */
+    isNextjsInternal: boolean;
+};
+declare function getRequestInfo(request: NextRequest): RequestInfo;
+declare function createServerContext(request: NextRequest): ServerEventContext;
+
+export { type RequestInfo, createServerContext, generateId, getRequestInfo };

package/dist/uitils.js

@@ -0,0 +1,68 @@
+import { removeSensitiveHeaders } from "./headers";
+const BASE62_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+function generateId() {
+  const length = 16;
+  const bytes = new Uint8Array(length * 2);
+  crypto.getRandomValues(bytes);
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    const idx = (bytes[i * 2] * 256 + bytes[i * 2 + 1]) % 62;
+    result += BASE62_CHARS[idx];
+  }
+  return result;
+}
+function getRequestInfo(request) {
+  const headers = request.headers;
+  const pathname = request.nextUrl.pathname;
+  const isNextjsInternal = pathname.startsWith("/_next");
+  const isStaticFile = /\.(ico|png|jpg|jpeg|gif|svg|webp|css|js|woff2?|ttf|eot|map)$/i.test(
+    pathname
+  );
+  const hasStandardPrefetchHeader = headers.get("next-router-prefetch") === "1" || headers.get("purpose") === "prefetch" || headers.get("sec-purpose") === "prefetch";
+  const nextUrl = headers.get("next-url");
+  const isRscPrefetch = nextUrl !== null && nextUrl !== pathname;
+  const isPrefetch = hasStandardPrefetchHeader || isRscPrefetch;
+  const isRsc = !!(nextUrl || headers.get("rsc"));
+  const secFetchDest = headers.get("sec-fetch-dest");
+  const secFetchMode = headers.get("sec-fetch-mode");
+  const accept = headers.get("accept") || "";
+  const isDocumentRequest = secFetchDest === "document" || secFetchMode === "navigate";
+  const acceptsHtml = accept.includes("text/html");
+  const isPageNavigation = isRsc || isDocumentRequest || acceptsHtml;
+  return {
+    isPrefetch,
+    isRsc,
+    isPageNavigation,
+    isStaticFile,
+    isNextjsInternal
+  };
+}
+function createServerContext(request) {
+  const rawHeaders = {};
+  request.headers.forEach((value, key) => {
+    rawHeaders[key] = value;
+  });
+  const requestHeaders = removeSensitiveHeaders(rawHeaders);
+  const searchParams = {};
+  request.nextUrl.searchParams.forEach((value, key) => {
+    if (!searchParams[key]) {
+      searchParams[key] = [];
+    }
+    searchParams[key].push(value);
+  });
+  return {
+    collectedAt: /* @__PURE__ */ new Date(),
+    host: request.headers.get("host") || "",
+    method: request.method,
+    path: request.nextUrl.pathname,
+    search: searchParams,
+    ip: request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || "",
+    requestHeaders,
+    responseHeaders: {}
+  };
+}
+export {
+  createServerContext,
+  generateId,
+  getRequestInfo
+};

package/package.json

@@ -0,0 +1,162 @@
+{
+  "name": "@nextlytics/core",
+  "version": "0.1.0-canary-1",
+  "description": "Analytics library for Next.js",
+  "license": "MIT",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client.d.ts",
+        "default": "./dist/client.js"
+      },
+      "require": {
+        "types": "./dist/client.d.ts",
+        "default": "./dist/client.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      },
+      "require": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./backends/logging": {
+      "import": {
+        "types": "./dist/backends/logging.d.ts",
+        "default": "./dist/backends/logging.js"
+      },
+      "require": {
+        "types": "./dist/backends/logging.d.ts",
+        "default": "./dist/backends/logging.cjs"
+      }
+    },
+    "./backends/posthog": {
+      "import": {
+        "types": "./dist/backends/posthog.d.ts",
+        "default": "./dist/backends/posthog.js"
+      },
+      "require": {
+        "types": "./dist/backends/posthog.d.ts",
+        "default": "./dist/backends/posthog.cjs"
+      }
+    },
+    "./backends/neon": {
+      "import": {
+        "types": "./dist/backends/neon.d.ts",
+        "default": "./dist/backends/neon.js"
+      },
+      "require": {
+        "types": "./dist/backends/neon.d.ts",
+        "default": "./dist/backends/neon.cjs"
+      }
+    },
+    "./backends/postgrest": {
+      "import": {
+        "types": "./dist/backends/postgrest.d.ts",
+        "default": "./dist/backends/postgrest.js"
+      },
+      "require": {
+        "types": "./dist/backends/postgrest.d.ts",
+        "default": "./dist/backends/postgrest.cjs"
+      }
+    },
+    "./backends/segment": {
+      "import": {
+        "types": "./dist/backends/segment.d.ts",
+        "default": "./dist/backends/segment.js"
+      },
+      "require": {
+        "types": "./dist/backends/segment.d.ts",
+        "default": "./dist/backends/segment.cjs"
+      }
+    },
+    "./backends/clickhouse": {
+      "import": {
+        "types": "./dist/backends/clickhouse.d.ts",
+        "default": "./dist/backends/clickhouse.js"
+      },
+      "require": {
+        "types": "./dist/backends/clickhouse.d.ts",
+        "default": "./dist/backends/clickhouse.cjs"
+      }
+    },
+    "./backends/gtm": {
+      "import": {
+        "types": "./dist/backends/gtm.d.ts",
+        "default": "./dist/backends/gtm.js"
+      },
+      "require": {
+        "types": "./dist/backends/gtm.d.ts",
+        "default": "./dist/backends/gtm.cjs"
+      }
+    },
+    "./backends/ga": {
+      "import": {
+        "types": "./dist/backends/ga.d.ts",
+        "default": "./dist/backends/ga.js"
+      },
+      "require": {
+        "types": "./dist/backends/ga.d.ts",
+        "default": "./dist/backends/ga.cjs"
+      }
+    },
+    "./plugins/vercel-geo": {
+      "import": {
+        "types": "./dist/plugins/vercel-geo.d.ts",
+        "default": "./dist/plugins/vercel-geo.js"
+      },
+      "require": {
+        "types": "./dist/plugins/vercel-geo.d.ts",
+        "default": "./dist/plugins/vercel-geo.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "bun tsc --noEmit",
+    "build": "rm -rf dist && tsup && find dist -name '*.d.cts' -delete",
+    "lint": "bun eslint src",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "bun run build",
+    "pub": "npm publish --access public"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0",
+    "@neondatabase/serverless": ">=0.10.0"
+  },
+  "peerDependenciesMeta": {
+    "@neondatabase/serverless": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@neondatabase/serverless": "^0.10.0",
+    "@types/react": "^19.0.0",
+    "eslint": "^9.0.0",
+    "next": "^15.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^4.0.18"
+  }
+}