feat: enhance analytics accuracy and privacy compliance

- Replace unique visitors estimation with accurate "soft fingerprint" counting
- Improve IP anonymization to support IPv6 /64 prefix masking for GDPR compliance
- Add API Reference link to main navigation
- Switch PM2 runtime from Node to Bun for better performance
- Update dependencies: better-auth, @funish/basis, @hypequery/clickhouse, and others

Author: DemoMacro

app/composables/useLinkAnalytics.ts

@@ -102,6 +102,13 @@ export function useLinkAnalytics(linkId: string, externalRange?: Ref<Range>) {
         );
       }
 
+      // Handle unique visitors from count result
+      if (countResult.data && "uniqueVisitors" in countResult.data) {
+        uniqueVisitors.value = Number(
+          (countResult.data as { uniqueVisitors: string | number }).uniqueVisitors,
+        );
+      }
+
       // Handle timeseries
       if (timeseriesResult.data && "data" in timeseriesResult.data) {
         timeseries.value = (timeseriesResult.data as { data: TimeseriesData[] }).data;
@@ -136,10 +143,6 @@ export function useLinkAnalytics(linkId: string, externalRange?: Ref<Range>) {
       if (utmSourcesResult.data && "data" in utmSourcesResult.data) {
         utmSources.value = (utmSourcesResult.data as { data: DimensionData[] }).data;
       }
-
-      // Calculate unique visitors (approximate)
-      // Proper implementation needs DISTINCT query, using estimate for now
-      uniqueVisitors.value = Math.floor(totalClicks.value * 0.7);
     } catch (e) {
       error.value = e instanceof Error ? e.message : "Failed to fetch analytics";
     } finally {

app/layouts/app.vue

@@ -22,6 +22,13 @@ const items = computed<NavigationMenuItem[]>(() => {
       active: route.path.startsWith("/dashboard"),
       icon: "i-lucide-layout-dashboard",
     },
+    {
+      label: "API Reference",
+      to: "/api/reference",
+      active: route.path === "/api/reference",
+      icon: "i-lucide-code",
+      target: "_blank",
+    },
   ];
 
   return baseItems;

bun.lock

@@ -27,21 +27,21 @@
     "postinstall": "nuxt prepare && basis git setup"
   },
   "devDependencies": {
-    "@better-auth/api-key": "1.5.3",
+    "@better-auth/api-key": "1.5.4",
     "@clickhouse/client-web": "1.18.1",
-    "@funish/basis": "0.2.9",
-    "@hypequery/clickhouse": "1.5.0",
-    "@iconify-json/lucide": "1.2.95",
+    "@funish/basis": "0.2.13",
+    "@hypequery/clickhouse": "1.6.0",
+    "@iconify-json/lucide": "1.2.96",
     "@iconify-json/simple-icons": "1.2.72",
     "@nuxt/content": "3.12.0",
     "@nuxt/ui": "4.5.1",
     "@nuxtjs/i18n": "10.2.3",
-    "@types/node": "25.3.3",
+    "@types/node": "25.3.5",
     "@types/pg": "8.18.0",
     "@types/ua-parser-js": "0.7.39",
     "@unovis/vue": "1.6.4",
     "@vueuse/nuxt": "14.2.1",
-    "better-auth": "1.5.3",
+    "better-auth": "1.5.4",
     "date-fns": "4.1.0",
     "geoip0": "0.0.12",
     "ioredis": "5.10.0",

package.json

@@ -1,7 +1,7 @@
 export const apps = [
   {
     name: "JS.GS",
-    script: "node",
-    args: "--env-file=.env .output/server/index.mjs",
+    script: "bun",
+    args: "--bun run .output/server/index.mjs",
   },
 ];

pm2.config.mjs

@@ -63,15 +63,62 @@ export function getClientIP(event: H3Event): string {
 }
 
 /**
- * Anonymize IP address by removing the last octet
+ * Anonymize IP address for privacy compliance
+ * - IPv4: Replace last octet with 0 (e.g., 192.168.1.100 -> 192.168.1.0)
+ * - IPv6: Use /64 prefix mask (e.g., 2001:0db8:85a3::8a2e:0370:7334 -> 2001:db8:85a3::)
  */
 function anonymizeIP(ip: string): string {
-  const parts = ip.split(".");
-  if (parts.length === 4) {
-    parts[3] = "0";
-    return parts.join(".");
+  // IPv4 anonymization - replace last octet
+  const ipv4Parts = ip.split(".");
+  if (ipv4Parts.length === 4) {
+    ipv4Parts[3] = "0";
+    return ipv4Parts.join(".");
   }
-  // For IPv6 or other formats, return as-is
+
+  // IPv6 anonymization - use /64 prefix
+  if (ip.includes(":")) {
+    try {
+      // Split IPv6 address by ::
+      const parts = ip.split("::");
+
+      if (parts.length === 2) {
+        // Compressed IPv6 format (contains ::)
+        const prefix = parts[0];
+
+        // Handle case where prefix might be undefined or empty
+        if (!prefix) {
+          // If prefix is empty, the IPv6 starts with ::, return :: (anycast)
+          return "::";
+        }
+
+        const segments = prefix.split(":");
+
+        // Keep first 4 segments (64 bits) for /64 prefix
+        if (segments.length >= 4) {
+          const prefix64 = segments.slice(0, 4).join(":");
+          return `${prefix64}::`;
+        }
+        return `${prefix}::`;
+      } else {
+        // Full IPv6 format
+        const segments = ip.split(":");
+        if (segments.length >= 8) {
+          // Keep first 4 segments (64 bits) for /64 prefix
+          const prefix64 = segments.slice(0, 4).join(":");
+          return `${prefix64}::`;
+        } else if (segments.length >= 4) {
+          // Keep first 4 segments
+          const prefix64 = segments.slice(0, 4).join(":");
+          return `${prefix64}::`;
+        }
+      }
+    } catch {
+      // If parsing fails, return original IP (fallback)
+      console.warn("Failed to anonymize IPv6 address:", ip);
+    }
+  }
+
+  // Fallback: return original IP if anonymization fails
   return ip;
 }
 

server/utils/analytics/track.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 import type { Link } from "../../../../types/link";
 import { canAccessLink } from "../permissions";
 import { chdb } from "../../../../../server/utils/database";
-import { toStartOfInterval } from "@hypequery/clickhouse";
+import { toStartOfInterval, rawAs } from "@hypequery/clickhouse";
 
 // GroupBy options matching Dub.co API
 const AnalyticsGroupBySchema = z.enum([
@@ -39,7 +39,8 @@ export const getAnalytics = () => {
       use: [sessionMiddleware],
       metadata: {
         openapi: {
-          description: "Retrieve analytics for a link",
+          description:
+            "Retrieve analytics for a link. Unique visitors are calculated using a privacy-compliant 'soft fingerprint' combining anonymized IP, browser version, OS version, device vendor, and model. This provides better accuracy than IP-only counting while remaining GDPR compliant.",
           responses: {
             "200": {
               description: "Analytics retrieved successfully",
@@ -93,9 +94,25 @@ export const getAnalytics = () => {
       // Execute query based on groupBy
       switch (groupBy) {
         case "count": {
-          const result = await buildBaseQuery().count("id", "totalClicks").execute();
+          const countResult = await buildBaseQuery().count("id", "totalClicks").execute();
+
+          // Query unique visitors using "soft fingerprint" combination
+          // Combines: ip (anonymized) + browserMajor + osVersion + deviceVendor + deviceModel
+          // This provides better accuracy than IP alone while remaining GDPR compliant
+          const uniqueResult = await buildBaseQuery()
+            .select([
+              rawAs(
+                "uniqExact(concat(ip, '|', browserMajor, '|', osVersion, '|', deviceVendor, '|', deviceModel))",
+                "uniqueVisitors"
+              ),
+            ])
+            .execute();
+
           return ctx.json({
-            totalClicks: result[0]?.totalClicks ?? 0,
+            totalClicks: countResult[0]?.totalClicks ?? 0,
+            uniqueVisitors: uniqueResult[0]?.uniqueVisitors
+              ? Number(uniqueResult[0].uniqueVisitors)
+              : 0,
           });
         }