@litemetrics/node 0.1.2 → 0.1.3

package/dist/index.js

@@ -140,6 +140,18 @@ function generateSecretKey() {
 // src/adapters/clickhouse.ts
 var EVENTS_TABLE = "litemetrics_events";
 var SITES_TABLE = "litemetrics_sites";
+var IDENTITY_MAP_TABLE = "litemetrics_identity_map";
+var CREATE_IDENTITY_MAP_TABLE = `
+CREATE TABLE IF NOT EXISTS ${IDENTITY_MAP_TABLE} (
+    site_id        LowCardinality(String),
+    visitor_id     String,
+    user_id        String,
+    identified_at  DateTime64(3),
+    created_at     DateTime64(3) DEFAULT now64(3)
+) ENGINE = ReplacingMergeTree(created_at)
+  ORDER BY (site_id, visitor_id)
+  SETTINGS index_granularity = 8192
+`;
 var CREATE_EVENTS_TABLE = `
 CREATE TABLE IF NOT EXISTS ${EVENTS_TABLE} (
     event_id       UUID DEFAULT generateUUIDv4(),
@@ -250,6 +262,7 @@ var ClickHouseAdapter = class {
   async init() {
     await this.client.command({ query: CREATE_EVENTS_TABLE });
     await this.client.command({ query: CREATE_SITES_TABLE });
+    await this.client.command({ query: CREATE_IDENTITY_MAP_TABLE });
     await this.client.command({ query: `ALTER TABLE ${EVENTS_TABLE} ADD COLUMN IF NOT EXISTS event_source LowCardinality(Nullable(String))` });
     await this.client.command({ query: `ALTER TABLE ${EVENTS_TABLE} ADD COLUMN IF NOT EXISTS event_subtype LowCardinality(Nullable(String))` });
     await this.client.command({ query: `ALTER TABLE ${EVENTS_TABLE} ADD COLUMN IF NOT EXISTS page_path Nullable(String)` });
@@ -507,8 +520,8 @@ var ClickHouseAdapter = class {
       }
       case "top_exit_pages": {
         const rows = await this.queryRows(
-          `SELECT url AS key, count() AS value FROM (
-             SELECT session_id, argMax(url, timestamp) AS url
+          `SELECT exit_url AS key, count() AS value FROM (
+             SELECT session_id, argMax(url, timestamp) AS exit_url
              FROM ${EVENTS_TABLE}
              WHERE site_id = {siteId:String}
                AND timestamp >= {from:String}
@@ -517,7 +530,7 @@ var ClickHouseAdapter = class {
                AND url IS NOT NULL${filterSql}
              GROUP BY session_id
            )
-           GROUP BY url
+           GROUP BY exit_url
            ORDER BY value DESC
            LIMIT {limit:UInt32}`,
           { ...params, ...filter.params }
@@ -528,9 +541,9 @@ var ClickHouseAdapter = class {
       }
       case "top_transitions": {
         const rows = await this.queryRows(
-          `SELECT concat(prev_url, ' \u2192 ', url) AS key, count() AS value FROM (
-             SELECT session_id, url,
-                    lag(url) OVER (PARTITION BY session_id ORDER BY timestamp) AS prev_url
+          `SELECT concat(prev_url, ' \u2192 ', curr_url) AS key, count() AS value FROM (
+             SELECT session_id, url AS curr_url,
+                    lagInFrame(url, 1) OVER (PARTITION BY session_id ORDER BY timestamp ASC) AS prev_url
              FROM ${EVENTS_TABLE}
              WHERE site_id = {siteId:String}
                AND timestamp >= {from:String}
@@ -538,7 +551,7 @@ var ClickHouseAdapter = class {
                AND type = 'pageview'
                AND url IS NOT NULL${filterSql}
            )
-           WHERE prev_url IS NOT NULL
+           WHERE prev_url IS NOT NULL AND prev_url != ''
            GROUP BY key
            ORDER BY value DESC
            LIMIT {limit:UInt32}`,
@@ -653,6 +666,57 @@ var ClickHouseAdapter = class {
         total = data.reduce((sum, d) => sum + d.value, 0);
         break;
       }
+      case "top_utm_sources": {
+        const rows = await this.queryRows(
+          `SELECT utm_source AS key, uniq(visitor_id) AS value FROM ${EVENTS_TABLE}
+           WHERE site_id = {siteId:String}
+             AND timestamp >= {from:String}
+             AND timestamp <= {to:String}
+             AND utm_source IS NOT NULL AND utm_source != ''
+             ${filterSql}
+           GROUP BY utm_source
+           ORDER BY value DESC
+           LIMIT {limit:UInt32}`,
+          { ...params, ...filter.params }
+        );
+        data = rows.map((r) => ({ key: r.key, value: Number(r.value) }));
+        total = data.reduce((sum, d) => sum + d.value, 0);
+        break;
+      }
+      case "top_utm_mediums": {
+        const rows = await this.queryRows(
+          `SELECT utm_medium AS key, uniq(visitor_id) AS value FROM ${EVENTS_TABLE}
+           WHERE site_id = {siteId:String}
+             AND timestamp >= {from:String}
+             AND timestamp <= {to:String}
+             AND utm_medium IS NOT NULL AND utm_medium != ''
+             ${filterSql}
+           GROUP BY utm_medium
+           ORDER BY value DESC
+           LIMIT {limit:UInt32}`,
+          { ...params, ...filter.params }
+        );
+        data = rows.map((r) => ({ key: r.key, value: Number(r.value) }));
+        total = data.reduce((sum, d) => sum + d.value, 0);
+        break;
+      }
+      case "top_utm_campaigns": {
+        const rows = await this.queryRows(
+          `SELECT utm_campaign AS key, uniq(visitor_id) AS value FROM ${EVENTS_TABLE}
+           WHERE site_id = {siteId:String}
+             AND timestamp >= {from:String}
+             AND timestamp <= {to:String}
+             AND utm_campaign IS NOT NULL AND utm_campaign != ''
+             ${filterSql}
+           GROUP BY utm_campaign
+           ORDER BY value DESC
+           LIMIT {limit:UInt32}`,
+          { ...params, ...filter.params }
+        );
+        data = rows.map((r) => ({ key: r.key, value: Number(r.value) }));
+        total = data.reduce((sum, d) => sum + d.value, 0);
+        break;
+      }
     }
     const result = { metric: q.metric, period, data, total };
     if (q.compare && ["pageviews", "visitors", "sessions", "events", "conversions"].includes(q.metric)) {
@@ -906,45 +970,59 @@ var ClickHouseAdapter = class {
     const where = conditions.join(" AND ");
     const [userRows, countRows] = await Promise.all([
       this.queryRows(
-        `SELECT
-          visitor_id,
-          anyLast(user_id) AS userId,
-          anyLast(traits) AS traits,
-          min(timestamp) AS firstSeen,
-          max(timestamp) AS lastSeen,
+        `WITH identity AS (
+          SELECT visitor_id, user_id
+          FROM ${IDENTITY_MAP_TABLE} FINAL
+          WHERE site_id = {siteId:String}
+        )
+        SELECT
+          if(i.user_id IS NOT NULL AND i.user_id != '', i.user_id, e.visitor_id) AS group_key,
+          anyLast(e.visitor_id) AS visitor_id,
+          anyLast(i.user_id) AS userId,
+          anyLast(e.traits) AS traits,
+          min(e.timestamp) AS firstSeen,
+          max(e.timestamp) AS lastSeen,
           count() AS totalEvents,
-          countIf(type = 'pageview') AS totalPageviews,
-          uniq(session_id) AS totalSessions,
-          anyLast(url) AS lastUrl,
-          anyLast(referrer) AS referrer,
-          anyLast(device_type) AS device_type,
-          anyLast(browser) AS browser,
-          anyLast(os) AS os,
-          anyLast(country) AS country,
-          anyLast(city) AS city,
-          anyLast(region) AS region,
-          anyLast(language) AS language,
-          anyLast(timezone) AS timezone,
-          anyLast(screen_width) AS screen_width,
-          anyLast(screen_height) AS screen_height,
-          anyLast(utm_source) AS utm_source,
-          anyLast(utm_medium) AS utm_medium,
-          anyLast(utm_campaign) AS utm_campaign,
-          anyLast(utm_term) AS utm_term,
-          anyLast(utm_content) AS utm_content
-        FROM ${EVENTS_TABLE}
-        WHERE ${where}
-        GROUP BY visitor_id
+          countIf(e.type = 'pageview') AS totalPageviews,
+          uniq(e.session_id) AS totalSessions,
+          anyLast(e.url) AS lastUrl,
+          anyLast(e.referrer) AS referrer,
+          anyLast(e.device_type) AS device_type,
+          anyLast(e.browser) AS browser,
+          anyLast(e.os) AS os,
+          anyLast(e.country) AS country,
+          anyLast(e.city) AS city,
+          anyLast(e.region) AS region,
+          anyLast(e.language) AS language,
+          anyLast(e.timezone) AS timezone,
+          anyLast(e.screen_width) AS screen_width,
+          anyLast(e.screen_height) AS screen_height,
+          anyLast(e.utm_source) AS utm_source,
+          anyLast(e.utm_medium) AS utm_medium,
+          anyLast(e.utm_campaign) AS utm_campaign,
+          anyLast(e.utm_term) AS utm_term,
+          anyLast(e.utm_content) AS utm_content
+        FROM ${EVENTS_TABLE} e
+        LEFT JOIN identity i ON e.visitor_id = i.visitor_id
+        WHERE e.site_id = {siteId:String}${where.includes("ILIKE") ? ` AND (e.visitor_id ILIKE {search:String} OR i.user_id ILIKE {search:String})` : ""}
+        GROUP BY group_key
         ORDER BY lastSeen DESC
         LIMIT {limit:UInt32}
         OFFSET {offset:UInt32}`,
         queryParams
       ),
       this.queryRows(
-        `SELECT count() AS total FROM (
-          SELECT visitor_id FROM ${EVENTS_TABLE}
-          WHERE ${where}
-          GROUP BY visitor_id
+        `WITH identity AS (
+          SELECT visitor_id, user_id
+          FROM ${IDENTITY_MAP_TABLE} FINAL
+          WHERE site_id = {siteId:String}
+        )
+        SELECT count() AS total FROM (
+          SELECT if(i.user_id IS NOT NULL AND i.user_id != '', i.user_id, e.visitor_id) AS group_key
+          FROM ${EVENTS_TABLE} e
+          LEFT JOIN identity i ON e.visitor_id = i.visitor_id
+          WHERE e.site_id = {siteId:String}${where.includes("ILIKE") ? ` AND (e.visitor_id ILIKE {search:String} OR i.user_id ILIKE {search:String})` : ""}
+          GROUP BY group_key
         )`,
         queryParams
       )
@@ -980,13 +1058,178 @@ var ClickHouseAdapter = class {
       offset
     };
   }
-  async getUserDetail(siteId, visitorId) {
-    const result = await this.listUsers({ siteId, search: visitorId, limit: 1 });
-    const user = result.users.find((u) => u.visitorId === visitorId);
+  async getUserDetail(siteId, identifier) {
+    const visitorIds = await this.getVisitorIdsForUser(siteId, identifier);
+    if (visitorIds.length > 0) {
+      return this.getMergedUserDetail(siteId, identifier, visitorIds);
+    }
+    const userId = await this.getUserIdForVisitor(siteId, identifier);
+    if (userId) {
+      const allVisitorIds = await this.getVisitorIdsForUser(siteId, userId);
+      return this.getMergedUserDetail(siteId, userId, allVisitorIds.length > 0 ? allVisitorIds : [identifier]);
+    }
+    const result = await this.listUsers({ siteId, search: identifier, limit: 1 });
+    const user = result.users.find((u) => u.visitorId === identifier);
     return user ?? null;
   }
-  async getUserEvents(siteId, visitorId, params) {
-    return this.listEvents({ ...params, siteId, visitorId });
+  async getUserEvents(siteId, identifier, params) {
+    const visitorIds = await this.getVisitorIdsForUser(siteId, identifier);
+    if (visitorIds.length > 0) {
+      return this.listEventsForVisitorIds(siteId, visitorIds, params);
+    }
+    const userId = await this.getUserIdForVisitor(siteId, identifier);
+    if (userId) {
+      const allVisitorIds = await this.getVisitorIdsForUser(siteId, userId);
+      if (allVisitorIds.length > 0) {
+        return this.listEventsForVisitorIds(siteId, allVisitorIds, params);
+      }
+    }
+    return this.listEvents({ ...params, siteId, visitorId: identifier });
+  }
+  // ─── Identity Mapping ──────────────────────────────────────
+  async upsertIdentity(siteId, visitorId, userId) {
+    await this.client.insert({
+      table: IDENTITY_MAP_TABLE,
+      values: [{
+        site_id: siteId,
+        visitor_id: visitorId,
+        user_id: userId,
+        identified_at: toCHDateTime(/* @__PURE__ */ new Date())
+      }],
+      format: "JSONEachRow"
+    });
+  }
+  async getVisitorIdsForUser(siteId, userId) {
+    const rows = await this.queryRows(
+      `SELECT visitor_id FROM ${IDENTITY_MAP_TABLE} FINAL
+       WHERE site_id = {siteId:String} AND user_id = {userId:String}`,
+      { siteId, userId }
+    );
+    return rows.map((r) => r.visitor_id);
+  }
+  async getUserIdForVisitor(siteId, visitorId) {
+    const rows = await this.queryRows(
+      `SELECT user_id FROM ${IDENTITY_MAP_TABLE} FINAL
+       WHERE site_id = {siteId:String} AND visitor_id = {visitorId:String}
+       LIMIT 1`,
+      { siteId, visitorId }
+    );
+    return rows.length > 0 ? rows[0].user_id : null;
+  }
+  async getMergedUserDetail(siteId, userId, visitorIds) {
+    const rows = await this.queryRows(
+      `SELECT
+        anyLast(visitor_id) AS visitor_id,
+        anyLast(traits) AS traits,
+        min(timestamp) AS firstSeen,
+        max(timestamp) AS lastSeen,
+        count() AS totalEvents,
+        countIf(type = 'pageview') AS totalPageviews,
+        uniq(session_id) AS totalSessions,
+        anyLast(url) AS lastUrl,
+        anyLast(referrer) AS referrer,
+        anyLast(device_type) AS device_type,
+        anyLast(browser) AS browser,
+        anyLast(os) AS os,
+        anyLast(country) AS country,
+        anyLast(city) AS city,
+        anyLast(region) AS region,
+        anyLast(language) AS language,
+        anyLast(timezone) AS timezone,
+        anyLast(screen_width) AS screen_width,
+        anyLast(screen_height) AS screen_height,
+        anyLast(utm_source) AS utm_source,
+        anyLast(utm_medium) AS utm_medium,
+        anyLast(utm_campaign) AS utm_campaign,
+        anyLast(utm_term) AS utm_term,
+        anyLast(utm_content) AS utm_content
+      FROM ${EVENTS_TABLE}
+      WHERE site_id = {siteId:String}
+        AND visitor_id IN {visitorIds:Array(String)}`,
+      { siteId, visitorIds }
+    );
+    if (rows.length === 0) return null;
+    const u = rows[0];
+    return {
+      visitorId: String(u.visitor_id),
+      visitorIds,
+      userId,
+      traits: this.parseJSON(u.traits),
+      firstSeen: new Date(String(u.firstSeen)).toISOString(),
+      lastSeen: new Date(String(u.lastSeen)).toISOString(),
+      totalEvents: Number(u.totalEvents),
+      totalPageviews: Number(u.totalPageviews),
+      totalSessions: Number(u.totalSessions),
+      lastUrl: u.lastUrl ? String(u.lastUrl) : void 0,
+      referrer: u.referrer ? String(u.referrer) : void 0,
+      device: u.device_type ? { type: String(u.device_type), browser: String(u.browser ?? ""), os: String(u.os ?? "") } : void 0,
+      geo: u.country ? { country: String(u.country), city: u.city ? String(u.city) : void 0, region: u.region ? String(u.region) : void 0 } : void 0,
+      language: u.language ? String(u.language) : void 0,
+      timezone: u.timezone ? String(u.timezone) : void 0,
+      screen: u.screen_width || u.screen_height ? { width: Number(u.screen_width ?? 0), height: Number(u.screen_height ?? 0) } : void 0,
+      utm: u.utm_source ? {
+        source: String(u.utm_source),
+        medium: u.utm_medium ? String(u.utm_medium) : void 0,
+        campaign: u.utm_campaign ? String(u.utm_campaign) : void 0,
+        term: u.utm_term ? String(u.utm_term) : void 0,
+        content: u.utm_content ? String(u.utm_content) : void 0
+      } : void 0
+    };
+  }
+  async listEventsForVisitorIds(siteId, visitorIds, params) {
+    const limit = Math.min(params.limit ?? 50, 200);
+    const offset = params.offset ?? 0;
+    const conditions = [`site_id = {siteId:String}`, `visitor_id IN {visitorIds:Array(String)}`];
+    const queryParams = { siteId, visitorIds, limit, offset };
+    if (params.type) {
+      conditions.push(`type = {type:String}`);
+      queryParams.type = params.type;
+    }
+    if (params.eventName) {
+      conditions.push(`event_name = {eventName:String}`);
+      queryParams.eventName = params.eventName;
+    }
+    if (params.eventNames && params.eventNames.length > 0) {
+      conditions.push(`event_name IN {eventNames:Array(String)}`);
+      queryParams.eventNames = params.eventNames;
+    }
+    if (params.period || params.dateFrom) {
+      const { dateRange } = resolvePeriod({
+        period: params.period,
+        dateFrom: params.dateFrom,
+        dateTo: params.dateTo
+      });
+      conditions.push(`timestamp >= {from:String} AND timestamp <= {to:String}`);
+      queryParams.from = toCHDateTime(dateRange.from);
+      queryParams.to = toCHDateTime(dateRange.to);
+    }
+    const where = conditions.join(" AND ");
+    const [events, countRows] = await Promise.all([
+      this.queryRows(
+        `SELECT event_id, type, timestamp, session_id, visitor_id, url, referrer, title,
+                event_name, properties, event_source, event_subtype, page_path, target_url_path,
+                element_selector, element_text, scroll_depth_pct,
+                user_id, traits, country, city, region,
+                device_type, browser, os, language,
+                utm_source, utm_medium, utm_campaign, utm_term, utm_content
+         FROM ${EVENTS_TABLE}
+         WHERE ${where}
+         ORDER BY timestamp DESC
+         LIMIT {limit:UInt32}
+         OFFSET {offset:UInt32}`,
+        queryParams
+      ),
+      this.queryRows(
+        `SELECT count() AS total FROM ${EVENTS_TABLE} WHERE ${where}`,
+        queryParams
+      )
+    ]);
+    return {
+      events: events.map((e) => this.toEventListItem(e)),
+      total: Number(countRows[0]?.total ?? 0),
+      limit,
+      offset
+    };
   }
   // ─── Site Management ──────────────────────────────────────
   async createSite(data) {
@@ -1237,6 +1480,7 @@ var ClickHouseAdapter = class {
 import { MongoClient } from "mongodb";
 var EVENTS_COLLECTION = "litemetrics_events";
 var SITES_COLLECTION = "litemetrics_sites";
+var IDENTITY_MAP_COLLECTION = "litemetrics_identity_map";
 function buildFilterMatch(filters) {
   if (!filters) return {};
   const map = {
@@ -1272,6 +1516,7 @@ var MongoDBAdapter = class {
   db;
   collection;
   sites;
+  identityMap;
   constructor(url) {
     this.client = new MongoClient(url);
   }
@@ -1280,13 +1525,16 @@ var MongoDBAdapter = class {
     this.db = this.client.db();
     this.collection = this.db.collection(EVENTS_COLLECTION);
     this.sites = this.db.collection(SITES_COLLECTION);
+    this.identityMap = this.db.collection(IDENTITY_MAP_COLLECTION);
     await Promise.all([
       this.collection.createIndex({ site_id: 1, timestamp: -1 }),
       this.collection.createIndex({ site_id: 1, type: 1 }),
       this.collection.createIndex({ site_id: 1, visitor_id: 1 }),
       this.collection.createIndex({ site_id: 1, session_id: 1 }),
       this.sites.createIndex({ site_id: 1 }, { unique: true }),
-      this.sites.createIndex({ secret_key: 1 })
+      this.sites.createIndex({ secret_key: 1 }),
+      this.identityMap.createIndex({ site_id: 1, visitor_id: 1 }, { unique: true }),
+      this.identityMap.createIndex({ site_id: 1, user_id: 1 })
     ]);
   }
   async insertEvents(events) {
@@ -1589,6 +1837,42 @@ var MongoDBAdapter = class {
         total = data.reduce((sum, d) => sum + d.value, 0);
         break;
       }
+      case "top_utm_sources": {
+        const rows = await this.collection.aggregate([
+          { $match: { ...baseMatch, ...filterMatch, utm_source: { $nin: [null, ""] } } },
+          { $group: { _id: "$utm_source", value: { $addToSet: "$visitor_id" } } },
+          { $project: { _id: 1, value: { $size: "$value" } } },
+          { $sort: { value: -1 } },
+          { $limit: limit }
+        ]).toArray();
+        data = rows.map((r) => ({ key: r._id, value: r.value }));
+        total = data.reduce((sum, d) => sum + d.value, 0);
+        break;
+      }
+      case "top_utm_mediums": {
+        const rows = await this.collection.aggregate([
+          { $match: { ...baseMatch, ...filterMatch, utm_medium: { $nin: [null, ""] } } },
+          { $group: { _id: "$utm_medium", value: { $addToSet: "$visitor_id" } } },
+          { $project: { _id: 1, value: { $size: "$value" } } },
+          { $sort: { value: -1 } },
+          { $limit: limit }
+        ]).toArray();
+        data = rows.map((r) => ({ key: r._id, value: r.value }));
+        total = data.reduce((sum, d) => sum + d.value, 0);
+        break;
+      }
+      case "top_utm_campaigns": {
+        const rows = await this.collection.aggregate([
+          { $match: { ...baseMatch, ...filterMatch, utm_campaign: { $nin: [null, ""] } } },
+          { $group: { _id: "$utm_campaign", value: { $addToSet: "$visitor_id" } } },
+          { $project: { _id: 1, value: { $size: "$value" } } },
+          { $sort: { value: -1 } },
+          { $limit: limit }
+        ]).toArray();
+        data = rows.map((r) => ({ key: r._id, value: r.value }));
+        total = data.reduce((sum, d) => sum + d.value, 0);
+        break;
+      }
     }
     const result = { metric: q.metric, period, data, total };
     if (q.compare && ["pageviews", "visitors", "sessions", "events", "conversions"].includes(q.metric)) {
@@ -1777,24 +2061,72 @@ var MongoDBAdapter = class {
       offset
     };
   }
+  // ─── Identity Mapping ──────────────────────────────────────
+  async upsertIdentity(siteId, visitorId, userId) {
+    await this.identityMap.updateOne(
+      { site_id: siteId, visitor_id: visitorId },
+      {
+        $set: { user_id: userId, identified_at: /* @__PURE__ */ new Date() },
+        $setOnInsert: { site_id: siteId, visitor_id: visitorId, created_at: /* @__PURE__ */ new Date() }
+      },
+      { upsert: true }
+    );
+  }
+  async getVisitorIdsForUser(siteId, userId) {
+    const docs = await this.identityMap.find({ site_id: siteId, user_id: userId }).toArray();
+    return docs.map((d) => d.visitor_id);
+  }
+  async getUserIdForVisitor(siteId, visitorId) {
+    const doc = await this.identityMap.findOne({ site_id: siteId, visitor_id: visitorId });
+    return doc?.user_id ?? null;
+  }
   // ─── User Listing ──────────────────────────────────────
   async listUsers(params) {
     const limit = Math.min(params.limit ?? 50, 200);
     const offset = params.offset ?? 0;
     const match = { site_id: params.siteId };
-    if (params.search) {
-      match.$or = [
-        { visitor_id: { $regex: params.search, $options: "i" } },
-        { user_id: { $regex: params.search, $options: "i" } }
-      ];
-    }
     const pipeline = [
       { $match: match },
+      // Join with identity map to resolve visitor → user
+      {
+        $lookup: {
+          from: IDENTITY_MAP_COLLECTION,
+          let: { vid: "$visitor_id", sid: "$site_id" },
+          pipeline: [
+            { $match: { $expr: { $and: [{ $eq: ["$visitor_id", "$$vid"] }, { $eq: ["$site_id", "$$sid"] }] } } }
+          ],
+          as: "_identity"
+        }
+      },
+      {
+        $addFields: {
+          _resolved_id: {
+            $ifNull: [{ $arrayElemAt: ["$_identity.user_id", 0] }, "$visitor_id"]
+          },
+          _resolved_user_id: {
+            $arrayElemAt: ["$_identity.user_id", 0]
+          }
+        }
+      }
+    ];
+    if (params.search) {
+      pipeline.push({
+        $match: {
+          $or: [
+            { visitor_id: { $regex: params.search, $options: "i" } },
+            { user_id: { $regex: params.search, $options: "i" } },
+            { _resolved_user_id: { $regex: params.search, $options: "i" } }
+          ]
+        }
+      });
+    }
+    pipeline.push(
       { $sort: { timestamp: 1 } },
       {
         $group: {
-          _id: "$visitor_id",
-          userId: { $last: "$user_id" },
+          _id: "$_resolved_id",
+          visitorIds: { $addToSet: "$visitor_id" },
+          userId: { $last: { $ifNull: ["$_resolved_user_id", "$user_id"] } },
           traits: { $last: "$traits" },
           firstSeen: { $min: "$timestamp" },
           lastSeen: { $max: "$timestamp" },
@@ -1827,10 +2159,11 @@ var MongoDBAdapter = class {
           count: [{ $count: "total" }]
         }
       }
-    ];
+    );
     const [result] = await this.collection.aggregate(pipeline).toArray();
     const users = (result?.data ?? []).map((u) => ({
-      visitorId: u._id,
+      visitorId: u.visitorIds[0] ?? u._id,
+      visitorIds: u.visitorIds.length > 1 ? u.visitorIds : void 0,
       userId: u.userId ?? void 0,
       traits: u.traits ?? void 0,
       firstSeen: u.firstSeen.toISOString(),
@@ -1860,13 +2193,125 @@ var MongoDBAdapter = class {
       offset
     };
   }
-  async getUserDetail(siteId, visitorId) {
-    const result = await this.listUsers({ siteId, search: visitorId, limit: 1 });
-    const user = result.users.find((u) => u.visitorId === visitorId);
-    return user ?? null;
+  async getUserDetail(siteId, identifier) {
+    const visitorIds = await this.getVisitorIdsForUser(siteId, identifier);
+    if (visitorIds.length > 0) {
+      return this.getMergedUserDetail(siteId, identifier, visitorIds);
+    }
+    const userId = await this.getUserIdForVisitor(siteId, identifier);
+    if (userId) {
+      const allVisitorIds = await this.getVisitorIdsForUser(siteId, userId);
+      return this.getMergedUserDetail(siteId, userId, allVisitorIds);
+    }
+    return this.getMergedUserDetail(siteId, void 0, [identifier]);
+  }
+  async getUserEvents(siteId, identifier, params) {
+    let visitorIds = await this.getVisitorIdsForUser(siteId, identifier);
+    if (visitorIds.length === 0) {
+      const userId = await this.getUserIdForVisitor(siteId, identifier);
+      if (userId) {
+        visitorIds = await this.getVisitorIdsForUser(siteId, userId);
+      }
+    }
+    if (visitorIds.length === 0) {
+      visitorIds = [identifier];
+    }
+    return this.listEventsForVisitorIds(siteId, visitorIds, params);
+  }
+  async getMergedUserDetail(siteId, userId, visitorIds) {
+    const pipeline = [
+      { $match: { site_id: siteId, visitor_id: { $in: visitorIds } } },
+      { $sort: { timestamp: 1 } },
+      {
+        $group: {
+          _id: null,
+          visitorIds: { $addToSet: "$visitor_id" },
+          traits: { $last: "$traits" },
+          firstSeen: { $min: "$timestamp" },
+          lastSeen: { $max: "$timestamp" },
+          totalEvents: { $sum: 1 },
+          totalPageviews: { $sum: { $cond: [{ $eq: ["$type", "pageview"] }, 1, 0] } },
+          sessions: { $addToSet: "$session_id" },
+          lastUrl: { $last: "$url" },
+          referrer: { $last: "$referrer" },
+          device_type: { $last: "$device_type" },
+          browser: { $last: "$browser" },
+          os: { $last: "$os" },
+          country: { $last: "$country" },
+          city: { $last: "$city" },
+          region: { $last: "$region" },
+          language: { $last: "$language" },
+          timezone: { $last: "$timezone" },
+          screen_width: { $last: "$screen_width" },
+          screen_height: { $last: "$screen_height" },
+          utm_source: { $last: "$utm_source" },
+          utm_medium: { $last: "$utm_medium" },
+          utm_campaign: { $last: "$utm_campaign" },
+          utm_term: { $last: "$utm_term" },
+          utm_content: { $last: "$utm_content" }
+        }
+      }
+    ];
+    const [row] = await this.collection.aggregate(pipeline).toArray();
+    if (!row) return null;
+    return {
+      visitorId: visitorIds[0],
+      visitorIds: row.visitorIds.length > 1 ? row.visitorIds : void 0,
+      userId: userId ?? void 0,
+      traits: row.traits ?? void 0,
+      firstSeen: row.firstSeen.toISOString(),
+      lastSeen: row.lastSeen.toISOString(),
+      totalEvents: row.totalEvents,
+      totalPageviews: row.totalPageviews,
+      totalSessions: row.sessions.length,
+      lastUrl: row.lastUrl ?? void 0,
+      referrer: row.referrer ?? void 0,
+      device: row.device_type ? { type: row.device_type, browser: row.browser ?? "", os: row.os ?? "" } : void 0,
+      geo: row.country ? { country: row.country, city: row.city ?? void 0, region: row.region ?? void 0 } : void 0,
+      language: row.language ?? void 0,
+      timezone: row.timezone ?? void 0,
+      screen: row.screen_width || row.screen_height ? { width: row.screen_width ?? 0, height: row.screen_height ?? 0 } : void 0,
+      utm: row.utm_source ? {
+        source: row.utm_source ?? void 0,
+        medium: row.utm_medium ?? void 0,
+        campaign: row.utm_campaign ?? void 0,
+        term: row.utm_term ?? void 0,
+        content: row.utm_content ?? void 0
+      } : void 0
+    };
   }
-  async getUserEvents(siteId, visitorId, params) {
-    return this.listEvents({ ...params, siteId, visitorId });
+  async listEventsForVisitorIds(siteId, visitorIds, params) {
+    const limit = Math.min(params.limit ?? 50, 200);
+    const offset = params.offset ?? 0;
+    const match = {
+      site_id: siteId,
+      visitor_id: { $in: visitorIds }
+    };
+    if (params.type) match.type = params.type;
+    if (params.eventName) {
+      match.event_name = params.eventName;
+    } else if (params.eventNames && params.eventNames.length > 0) {
+      match.event_name = { $in: params.eventNames };
+    }
+    if (params.eventSource) match.event_source = params.eventSource;
+    if (params.period || params.dateFrom) {
+      const { dateRange } = resolvePeriod({
+        period: params.period,
+        dateFrom: params.dateFrom,
+        dateTo: params.dateTo
+      });
+      match.timestamp = { $gte: new Date(dateRange.from), $lte: new Date(dateRange.to) };
+    }
+    const [events, countResult] = await Promise.all([
+      this.collection.find(match).sort({ timestamp: -1 }).skip(offset).limit(limit).toArray(),
+      this.collection.countDocuments(match)
+    ]);
+    return {
+      events: events.map((e) => this.toEventListItem(e)),
+      total: countResult,
+      limit,
+      offset
+    };
   }
   toEventListItem(doc) {
     return {
@@ -2237,6 +2682,51 @@ async function createCollector(config) {
       return { ...event, ip, geo, device };
     });
   }
+  const identityCache = /* @__PURE__ */ new Map();
+  const IDENTITY_CACHE_TTL = 5 * 60 * 1e3;
+  function getCachedUserId(siteId, visitorId) {
+    const key = `${siteId}:${visitorId}`;
+    const entry = identityCache.get(key);
+    if (!entry) return void 0;
+    if (Date.now() > entry.expires) {
+      identityCache.delete(key);
+      return void 0;
+    }
+    return entry.userId;
+  }
+  function setCachedUserId(siteId, visitorId, userId) {
+    const key = `${siteId}:${visitorId}`;
+    identityCache.set(key, { userId, expires: Date.now() + IDENTITY_CACHE_TTL });
+    if (identityCache.size > 1e4) {
+      const now = Date.now();
+      for (const [k, v] of identityCache) {
+        if (now > v.expires) identityCache.delete(k);
+      }
+    }
+  }
+  async function processIdentity(events) {
+    for (const event of events) {
+      if (!event.visitorId || event.visitorId === "server") continue;
+      if (event.type === "identify" && event.userId) {
+        await db.upsertIdentity(event.siteId, event.visitorId, event.userId);
+        setCachedUserId(event.siteId, event.visitorId, event.userId);
+      } else if (!event.userId) {
+        const cached = getCachedUserId(event.siteId, event.visitorId);
+        if (cached) {
+          event.userId = cached;
+        } else {
+          const resolved = await db.getUserIdForVisitor(event.siteId, event.visitorId);
+          if (resolved) {
+            event.userId = resolved;
+            setCachedUserId(event.siteId, event.visitorId, resolved);
+          }
+        }
+      } else if (event.userId) {
+        setCachedUserId(event.siteId, event.visitorId, event.userId);
+        await db.upsertIdentity(event.siteId, event.visitorId, event.userId);
+      }
+    }
+  }
   function extractIp(req) {
     if (config.trustProxy ?? true) {
       const forwarded = req.headers?.["x-forwarded-for"];
@@ -2298,11 +2788,13 @@ async function createCollector(config) {
               sendJson(res, 200, { ok: true });
               return;
             }
+            await processIdentity(filtered);
             await db.insertEvents(filtered);
             sendJson(res, 200, { ok: true });
             return;
           }
         }
+        await processIdentity(enriched);
         await db.insertEvents(enriched);
         sendJson(res, 200, { ok: true });
       } catch (err) {
@@ -2563,11 +3055,11 @@ async function createCollector(config) {
     async listUsers(params) {
       return db.listUsers(params);
     },
-    async getUserDetail(siteId, visitorId) {
-      return db.getUserDetail(siteId, visitorId);
+    async getUserDetail(siteId, identifier) {
+      return db.getUserDetail(siteId, identifier);
     },
-    async getUserEvents(siteId, visitorId, params) {
-      return db.getUserEvents(siteId, visitorId, params);
+    async getUserEvents(siteId, identifier, params) {
+      return db.getUserEvents(siteId, identifier, params);
     },
     async track(siteId, name, properties, options) {
       const event = {