@nextlytics/core 0.1.0-canary-1

package/dist/anonymous-user.cjs

@@ -0,0 +1,118 @@
+"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 anonymous_user_exports = {};
+__export(anonymous_user_exports, {
+  resolveAnonymousUser: () => resolveAnonymousUser
+});
+module.exports = __toCommonJS(anonymous_user_exports);
+const BASE62_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const ANON_ID_LENGTH = 10;
+const DEFAULTS = {
+  gdprMode: true,
+  useCookies: false,
+  dailySalt: true,
+  cookieName: "__nextlytics_anon",
+  cookieMaxAge: 60 * 60 * 24 * 365 * 2
+  // 2 years
+};
+function isSecureRequest(headers) {
+  const proto = headers.get("x-forwarded-proto");
+  if (proto) return proto === "https";
+  return false;
+}
+function getDailySalt() {
+  const now = /* @__PURE__ */ new Date();
+  return `${now.getUTCFullYear()}-${now.getUTCMonth()}-${now.getUTCDate()}`;
+}
+function bytesToBase62(bytes, length) {
+  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;
+}
+async function hashToShortId(input) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(input);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return bytesToBase62(new Uint8Array(hashBuffer), ANON_ID_LENGTH);
+}
+async function generateGdprAnonId(serverContext, useDailySalt) {
+  const ip = serverContext.ip || "unknown";
+  const userAgent = serverContext.requestHeaders["user-agent"] || "unknown";
+  const host = serverContext.host || "unknown";
+  const parts = useDailySalt ? [getDailySalt(), ip, userAgent, host] : [ip, userAgent, host];
+  return hashToShortId(parts.join("|"));
+}
+function generateRandomAnonId() {
+  const bytes = new Uint8Array(ANON_ID_LENGTH * 2);
+  crypto.getRandomValues(bytes);
+  return bytesToBase62(bytes, ANON_ID_LENGTH);
+}
+async function resolveAnonymousUser(params) {
+  const { ctx, serverContext, config, response } = params;
+  const { headers, cookies } = ctx;
+  const gdprMode = config.anonymousUsers?.gdprMode ?? DEFAULTS.gdprMode;
+  const useCookies = config.anonymousUsers?.useCookies ?? DEFAULTS.useCookies;
+  const dailySalt = config.anonymousUsers?.dailySalt ?? DEFAULTS.dailySalt;
+  const cookieName = config.anonymousUsers?.cookieName ?? DEFAULTS.cookieName;
+  const cookieMaxAge = config.anonymousUsers?.cookieMaxAge ?? DEFAULTS.cookieMaxAge;
+  let anonId;
+  let shouldSetCookie = false;
+  if (useCookies) {
+    const existingCookie = cookies.get(cookieName);
+    if (existingCookie?.value) {
+      anonId = existingCookie.value;
+    } else {
+      anonId = gdprMode ? await generateGdprAnonId(serverContext, dailySalt) : generateRandomAnonId();
+      shouldSetCookie = true;
+    }
+  } else {
+    if (gdprMode) {
+      anonId = await generateGdprAnonId(serverContext, dailySalt);
+    } else {
+      anonId = generateRandomAnonId();
+    }
+  }
+  if (config.callbacks?.getAnonymousUserId) {
+    try {
+      const overrideResult = await config.callbacks.getAnonymousUserId({
+        ctx,
+        originalAnonymousUserId: anonId
+      });
+      anonId = overrideResult.anonId;
+    } catch {
+    }
+  }
+  if (shouldSetCookie && response) {
+    response.cookies.set(cookieName, anonId, {
+      maxAge: cookieMaxAge,
+      httpOnly: true,
+      secure: isSecureRequest(headers),
+      sameSite: "lax",
+      path: "/"
+    });
+  }
+  return { anonId };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resolveAnonymousUser
+});

package/dist/anonymous-user.d.mts

@@ -0,0 +1,22 @@
+import { NextResponse } from 'next/server';
+import { RequestContext, ServerEventContext, NextlyticsConfig, AnonymousUserResult } from './types.mjs';
+import 'next/dist/server/web/spec-extension/cookies';
+
+type ResolveAnonymousUserParams = {
+    ctx: RequestContext;
+    serverContext: ServerEventContext;
+    config: NextlyticsConfig;
+    /** Optional response for setting cookies. If not provided, cookies won't be set. */
+    response?: NextResponse | null;
+};
+/**
+ * Resolve anonymous user ID based on config.
+ *
+ * Modes:
+ * - gdprMode=true (default): Hash-based ID (Fathom-like)
+ * - gdprMode=false + useCookies=true: Persistent cookie-based ID
+ * - gdprMode=false + useCookies=false: Random ID per request
+ */
+declare function resolveAnonymousUser(params: ResolveAnonymousUserParams): Promise<AnonymousUserResult>;
+
+export { type ResolveAnonymousUserParams, resolveAnonymousUser };

package/dist/anonymous-user.d.ts

@@ -0,0 +1,22 @@
+import { NextResponse } from 'next/server';
+import { RequestContext, ServerEventContext, NextlyticsConfig, AnonymousUserResult } from './types.js';
+import 'next/dist/server/web/spec-extension/cookies';
+
+type ResolveAnonymousUserParams = {
+    ctx: RequestContext;
+    serverContext: ServerEventContext;
+    config: NextlyticsConfig;
+    /** Optional response for setting cookies. If not provided, cookies won't be set. */
+    response?: NextResponse | null;
+};
+/**
+ * Resolve anonymous user ID based on config.
+ *
+ * Modes:
+ * - gdprMode=true (default): Hash-based ID (Fathom-like)
+ * - gdprMode=false + useCookies=true: Persistent cookie-based ID
+ * - gdprMode=false + useCookies=false: Random ID per request
+ */
+declare function resolveAnonymousUser(params: ResolveAnonymousUserParams): Promise<AnonymousUserResult>;
+
+export { type ResolveAnonymousUserParams, resolveAnonymousUser };

package/dist/anonymous-user.js

@@ -0,0 +1,94 @@
+const BASE62_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const ANON_ID_LENGTH = 10;
+const DEFAULTS = {
+  gdprMode: true,
+  useCookies: false,
+  dailySalt: true,
+  cookieName: "__nextlytics_anon",
+  cookieMaxAge: 60 * 60 * 24 * 365 * 2
+  // 2 years
+};
+function isSecureRequest(headers) {
+  const proto = headers.get("x-forwarded-proto");
+  if (proto) return proto === "https";
+  return false;
+}
+function getDailySalt() {
+  const now = /* @__PURE__ */ new Date();
+  return `${now.getUTCFullYear()}-${now.getUTCMonth()}-${now.getUTCDate()}`;
+}
+function bytesToBase62(bytes, length) {
+  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;
+}
+async function hashToShortId(input) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(input);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return bytesToBase62(new Uint8Array(hashBuffer), ANON_ID_LENGTH);
+}
+async function generateGdprAnonId(serverContext, useDailySalt) {
+  const ip = serverContext.ip || "unknown";
+  const userAgent = serverContext.requestHeaders["user-agent"] || "unknown";
+  const host = serverContext.host || "unknown";
+  const parts = useDailySalt ? [getDailySalt(), ip, userAgent, host] : [ip, userAgent, host];
+  return hashToShortId(parts.join("|"));
+}
+function generateRandomAnonId() {
+  const bytes = new Uint8Array(ANON_ID_LENGTH * 2);
+  crypto.getRandomValues(bytes);
+  return bytesToBase62(bytes, ANON_ID_LENGTH);
+}
+async function resolveAnonymousUser(params) {
+  const { ctx, serverContext, config, response } = params;
+  const { headers, cookies } = ctx;
+  const gdprMode = config.anonymousUsers?.gdprMode ?? DEFAULTS.gdprMode;
+  const useCookies = config.anonymousUsers?.useCookies ?? DEFAULTS.useCookies;
+  const dailySalt = config.anonymousUsers?.dailySalt ?? DEFAULTS.dailySalt;
+  const cookieName = config.anonymousUsers?.cookieName ?? DEFAULTS.cookieName;
+  const cookieMaxAge = config.anonymousUsers?.cookieMaxAge ?? DEFAULTS.cookieMaxAge;
+  let anonId;
+  let shouldSetCookie = false;
+  if (useCookies) {
+    const existingCookie = cookies.get(cookieName);
+    if (existingCookie?.value) {
+      anonId = existingCookie.value;
+    } else {
+      anonId = gdprMode ? await generateGdprAnonId(serverContext, dailySalt) : generateRandomAnonId();
+      shouldSetCookie = true;
+    }
+  } else {
+    if (gdprMode) {
+      anonId = await generateGdprAnonId(serverContext, dailySalt);
+    } else {
+      anonId = generateRandomAnonId();
+    }
+  }
+  if (config.callbacks?.getAnonymousUserId) {
+    try {
+      const overrideResult = await config.callbacks.getAnonymousUserId({
+        ctx,
+        originalAnonymousUserId: anonId
+      });
+      anonId = overrideResult.anonId;
+    } catch {
+    }
+  }
+  if (shouldSetCookie && response) {
+    response.cookies.set(cookieName, anonId, {
+      maxAge: cookieMaxAge,
+      httpOnly: true,
+      secure: isSecureRequest(headers),
+      sameSite: "lax",
+      path: "/"
+    });
+  }
+  return { anonId };
+}
+export {
+  resolveAnonymousUser
+};

package/dist/backends/clickhouse.cjs

@@ -0,0 +1,110 @@
+"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 clickhouse_exports = {};
+__export(clickhouse_exports, {
+  clickhouseBackend: () => clickhouseBackend
+});
+module.exports = __toCommonJS(clickhouse_exports);
+var import_db = require("./lib/db");
+function clickhouseBackend(config) {
+  const baseUrl = config.url.replace(/\/$/, "");
+  const database = config.database ?? "default";
+  const table = config.tableName ?? "analytics";
+  const asyncInsert = config.asyncInsert ?? true;
+  const acceptUpdates = config.acceptUpdates ?? false;
+  const updateLookbackMinutes = config.updateLookbackMinutes ?? 60;
+  const authHeader = "Basic " + btoa((config.username ?? "default") + ":" + (config.password ?? ""));
+  function printCreateTableStatement() {
+    console.error(`[Nextlytics ClickHouse] Table "${database}.${table}" does not exist. Run:
+`);
+    console.error((0, import_db.generateChCreateTableSQL)(database, table));
+  }
+  async function query(sql) {
+    const params = new URLSearchParams({
+      database,
+      query: sql
+    });
+    const res = await fetch(`${baseUrl}/?${params}`, {
+      method: "GET",
+      headers: { Authorization: authHeader }
+    });
+    if (!res.ok) {
+      throw new Error(`ClickHouse query error ${res.status}: ${await res.text()}`);
+    }
+    const text = await res.text();
+    if (!text.trim()) return [];
+    return text.trim().split("\n").map((line) => JSON.parse(line));
+  }
+  async function insert(row) {
+    const params = new URLSearchParams({
+      database,
+      query: `INSERT INTO ${table} FORMAT JSONEachRow`,
+      date_time_input_format: "best_effort"
+    });
+    if (asyncInsert) {
+      params.set("async_insert", "1");
+      params.set("wait_for_async_insert", "0");
+    }
+    const res = await fetch(`${baseUrl}/?${params}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: authHeader
+      },
+      body: JSON.stringify(row)
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      if ((0, import_db.isChTableNotFoundError)(text)) {
+        printCreateTableStatement();
+      }
+      throw new Error(`ClickHouse error ${res.status}: ${text}`);
+    }
+  }
+  return {
+    name: "clickhouse",
+    supportsUpdates: acceptUpdates,
+    async onEvent(event) {
+      const row = (0, import_db.eventToJsonRow)(event);
+      await insert(row);
+    },
+    async updateEvent(eventId, patch) {
+      if (!acceptUpdates || !patch.clientContext) return;
+      const cols = import_db.tableColumns.map((c) => c.name).join(", ");
+      const rows = await query(
+        `SELECT ${cols} FROM ${table} WHERE event_id = '${eventId}' AND timestamp > now() - INTERVAL ${updateLookbackMinutes} MINUTE FORMAT JSONEachRow`
+      );
+      if (rows.length === 0) return;
+      const existing = rows[0];
+      const clientCtx = (0, import_db.extractClientContext)(patch.clientContext);
+      const updated = {
+        ...existing,
+        referer: clientCtx.referer ?? existing.referer,
+        user_agent: clientCtx.user_agent ?? existing.user_agent,
+        locale: clientCtx.locale ?? existing.locale,
+        client_context: clientCtx.rest ?? existing.client_context
+      };
+      await insert(updated);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clickhouseBackend
+});

package/dist/backends/clickhouse.d.mts

@@ -0,0 +1,58 @@
+import { NextlyticsBackend } from '../types.mjs';
+import 'next/dist/server/web/spec-extension/cookies';
+import 'next/server';
+
+/**
+ * ClickHouse backend for Nextlytics
+ *
+ * Sends events to ClickHouse via HTTP API with async inserts.
+ *
+ * ## ClickHouse Cloud Usage
+ *
+ * ```typescript
+ * import { clickhouseBackend } from "@nextlytics/core/backends/clickhouse"
+ *
+ * const analytics = Nextlytics({
+ *   backends: [
+ *     clickhouseBackend({
+ *       url: "https://xxx.clickhouse.cloud:8443",
+ *       username: "default",
+ *       password: process.env.CLICKHOUSE_PASSWORD!,
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * ## Self-hosted ClickHouse
+ *
+ * ```typescript
+ * clickhouseBackend({
+ *   url: "http://localhost:8123",
+ *   username: "default",
+ *   password: "",
+ *   database: "analytics",
+ * })
+ * ```
+ */
+
+type ClickHouseBackendConfig = {
+    /** ClickHouse HTTP API URL */
+    url: string;
+    /** Username (default: "default") */
+    username?: string;
+    /** Password */
+    password?: string;
+    /** Database name (default: "default") */
+    database?: string;
+    /** Table name (default: "analytics") */
+    tableName?: string;
+    /** Enable async inserts (default: true) */
+    asyncInsert?: boolean;
+    /** Enable updates via select+insert (uses ReplacingMergeTree deduplication) */
+    acceptUpdates?: boolean;
+    /** Lookback window in minutes for update SELECT queries (default: 60) */
+    updateLookbackMinutes?: number;
+};
+declare function clickhouseBackend(config: ClickHouseBackendConfig): NextlyticsBackend;
+
+export { type ClickHouseBackendConfig, clickhouseBackend };

package/dist/backends/clickhouse.d.ts

@@ -0,0 +1,58 @@
+import { NextlyticsBackend } from '../types.js';
+import 'next/dist/server/web/spec-extension/cookies';
+import 'next/server';
+
+/**
+ * ClickHouse backend for Nextlytics
+ *
+ * Sends events to ClickHouse via HTTP API with async inserts.
+ *
+ * ## ClickHouse Cloud Usage
+ *
+ * ```typescript
+ * import { clickhouseBackend } from "@nextlytics/core/backends/clickhouse"
+ *
+ * const analytics = Nextlytics({
+ *   backends: [
+ *     clickhouseBackend({
+ *       url: "https://xxx.clickhouse.cloud:8443",
+ *       username: "default",
+ *       password: process.env.CLICKHOUSE_PASSWORD!,
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * ## Self-hosted ClickHouse
+ *
+ * ```typescript
+ * clickhouseBackend({
+ *   url: "http://localhost:8123",
+ *   username: "default",
+ *   password: "",
+ *   database: "analytics",
+ * })
+ * ```
+ */
+
+type ClickHouseBackendConfig = {
+    /** ClickHouse HTTP API URL */
+    url: string;
+    /** Username (default: "default") */
+    username?: string;
+    /** Password */
+    password?: string;
+    /** Database name (default: "default") */
+    database?: string;
+    /** Table name (default: "analytics") */
+    tableName?: string;
+    /** Enable async inserts (default: true) */
+    asyncInsert?: boolean;
+    /** Enable updates via select+insert (uses ReplacingMergeTree deduplication) */
+    acceptUpdates?: boolean;
+    /** Lookback window in minutes for update SELECT queries (default: 60) */
+    updateLookbackMinutes?: number;
+};
+declare function clickhouseBackend(config: ClickHouseBackendConfig): NextlyticsBackend;
+
+export { type ClickHouseBackendConfig, clickhouseBackend };

package/dist/backends/clickhouse.js

@@ -0,0 +1,92 @@
+import {
+  tableColumns,
+  eventToJsonRow,
+  generateChCreateTableSQL,
+  isChTableNotFoundError,
+  extractClientContext
+} from "./lib/db";
+function clickhouseBackend(config) {
+  const baseUrl = config.url.replace(/\/$/, "");
+  const database = config.database ?? "default";
+  const table = config.tableName ?? "analytics";
+  const asyncInsert = config.asyncInsert ?? true;
+  const acceptUpdates = config.acceptUpdates ?? false;
+  const updateLookbackMinutes = config.updateLookbackMinutes ?? 60;
+  const authHeader = "Basic " + btoa((config.username ?? "default") + ":" + (config.password ?? ""));
+  function printCreateTableStatement() {
+    console.error(`[Nextlytics ClickHouse] Table "${database}.${table}" does not exist. Run:
+`);
+    console.error(generateChCreateTableSQL(database, table));
+  }
+  async function query(sql) {
+    const params = new URLSearchParams({
+      database,
+      query: sql
+    });
+    const res = await fetch(`${baseUrl}/?${params}`, {
+      method: "GET",
+      headers: { Authorization: authHeader }
+    });
+    if (!res.ok) {
+      throw new Error(`ClickHouse query error ${res.status}: ${await res.text()}`);
+    }
+    const text = await res.text();
+    if (!text.trim()) return [];
+    return text.trim().split("\n").map((line) => JSON.parse(line));
+  }
+  async function insert(row) {
+    const params = new URLSearchParams({
+      database,
+      query: `INSERT INTO ${table} FORMAT JSONEachRow`,
+      date_time_input_format: "best_effort"
+    });
+    if (asyncInsert) {
+      params.set("async_insert", "1");
+      params.set("wait_for_async_insert", "0");
+    }
+    const res = await fetch(`${baseUrl}/?${params}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: authHeader
+      },
+      body: JSON.stringify(row)
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      if (isChTableNotFoundError(text)) {
+        printCreateTableStatement();
+      }
+      throw new Error(`ClickHouse error ${res.status}: ${text}`);
+    }
+  }
+  return {
+    name: "clickhouse",
+    supportsUpdates: acceptUpdates,
+    async onEvent(event) {
+      const row = eventToJsonRow(event);
+      await insert(row);
+    },
+    async updateEvent(eventId, patch) {
+      if (!acceptUpdates || !patch.clientContext) return;
+      const cols = tableColumns.map((c) => c.name).join(", ");
+      const rows = await query(
+        `SELECT ${cols} FROM ${table} WHERE event_id = '${eventId}' AND timestamp > now() - INTERVAL ${updateLookbackMinutes} MINUTE FORMAT JSONEachRow`
+      );
+      if (rows.length === 0) return;
+      const existing = rows[0];
+      const clientCtx = extractClientContext(patch.clientContext);
+      const updated = {
+        ...existing,
+        referer: clientCtx.referer ?? existing.referer,
+        user_agent: clientCtx.user_agent ?? existing.user_agent,
+        locale: clientCtx.locale ?? existing.locale,
+        client_context: clientCtx.rest ?? existing.client_context
+      };
+      await insert(updated);
+    }
+  };
+}
+export {
+  clickhouseBackend
+};