locallytics 0.1.3 → 0.1.5

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAGpE,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,SAAS,EACT,UAAU,EACV,aAAa,EACb,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// Server exports
+export { locallytics, LocallyticsData } from "./server/index.js";
+// Client exports
+export { LocallyticsGrabber } from "./client/LocallyticsGrabber.js";
+export { LocallyticsError } from "./types/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEjE,iBAAiB;AACjB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAapE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/server/handlers.d.ts

@@ -0,0 +1,10 @@
+import type { AnalyticsDB, LocallyticsConfig, RouteHandler } from "../types/index.js";
+/**
+ * Create route handlers for analytics API
+ *
+ * @param db - Database instance
+ * @param config - Locallytics configuration
+ * @returns GET and POST handlers
+ */
+export declare function createHandlers(db: AnalyticsDB, config: LocallyticsConfig): RouteHandler;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/server/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/server/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,YAAY,EAEb,MAAM,mBAAmB,CAAC;AAmC3B;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,iBAAiB,GACxB,YAAY,CAiGd"}

package/dist/server/handlers.js

@@ -0,0 +1,105 @@
+import { LocallyticsError } from "../types/index.js";
+import { RateLimiter } from "../utils/rate-limit.js";
+import { hashIP, getIPFromRequest } from "../utils/hash.js";
+import { validatePageviewBatch, checkDNT } from "./validator.js";
+import { getAnalyticsData } from "./queries.js";
+/**
+ * Parse date range from query string
+ */
+function parseDateRange(value) {
+    if (!value || value === "last7d") {
+        return "last7d";
+    }
+    if (value === "last24h" || value === "last30d") {
+        return value;
+    }
+    // Try to parse custom range (format: start,end as ISO strings)
+    if (value.includes(",")) {
+        const [startStr, endStr] = value.split(",");
+        if (startStr && endStr) {
+            const start = new Date(startStr);
+            const end = new Date(endStr);
+            if (!isNaN(start.getTime()) && !isNaN(end.getTime())) {
+                return { start, end };
+            }
+        }
+    }
+    return "last7d";
+}
+/**
+ * Create route handlers for analytics API
+ *
+ * @param db - Database instance
+ * @param config - Locallytics configuration
+ * @returns GET and POST handlers
+ */
+export function createHandlers(db, config) {
+    const rateLimiter = new RateLimiter(100, 60000);
+    /**
+     * POST handler - track pageview events
+     */
+    async function POST(request) {
+        try {
+            // Check DNT - respect user privacy preference
+            if (checkDNT(request)) {
+                return Response.json({ success: true, tracked: false });
+            }
+            // Rate limiting by IP
+            const ip = getIPFromRequest(request);
+            const rateLimitKey = ip ?? "unknown";
+            if (!rateLimiter.check(rateLimitKey)) {
+                const error = LocallyticsError.rateLimit();
+                return Response.json({ error: error.message, code: error.code }, { status: error.statusCode });
+            }
+            // Parse and validate batch
+            const body = await request.json();
+            const events = validatePageviewBatch(body);
+            // Hash IP for privacy
+            const ipHash = ip ? hashIP(ip) : null;
+            // Insert all events
+            await Promise.all(events.map((event) => db.insertPageview(event, ipHash)));
+            return Response.json({
+                success: true,
+                tracked: true,
+                count: events.length,
+            });
+        }
+        catch (error) {
+            if (error instanceof LocallyticsError) {
+                return Response.json({ error: error.message, code: error.code }, { status: error.statusCode });
+            }
+            // Log unexpected errors but don't expose details
+            console.error("[Locallytics] POST error:", error);
+            return Response.json({ error: "Internal server error", code: "INTERNAL_ERROR" }, { status: 500 });
+        }
+    }
+    /**
+     * GET handler - fetch analytics data
+     */
+    async function GET(request) {
+        try {
+            // Check API key authentication if configured
+            if (config.apiKey) {
+                const authHeader = request.headers.get("authorization");
+                const providedKey = authHeader?.replace("Bearer ", "");
+                if (providedKey !== config.apiKey) {
+                    const error = LocallyticsError.unauthorized();
+                    return Response.json({ error: error.message, code: error.code }, { status: error.statusCode });
+                }
+            }
+            // Parse date range from query params
+            const url = new URL(request.url);
+            const dateRange = parseDateRange(url.searchParams.get("range"));
+            // Fetch analytics data
+            const data = await getAnalyticsData(db, dateRange);
+            return Response.json(data);
+        }
+        catch (error) {
+            // Log unexpected errors but don't expose details
+            console.error("[Locallytics] GET error:", error);
+            return Response.json({ error: "Internal server error", code: "INTERNAL_ERROR" }, { status: 500 });
+        }
+    }
+    return { GET, POST };
+}
+//# sourceMappingURL=handlers.js.map

package/dist/server/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/server/handlers.ts"],"names":[],"mappings":"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"}

package/dist/server/index.d.ts

@@ -0,0 +1,42 @@
+import type { LocallyticsConfig, RouteHandler, AnalyticsResult, AnalyticsDataOptions } from "../types/index.js";
+/**
+ * Initialize Locallytics and create route handlers
+ *
+ * @param config - Locallytics configuration
+ * @returns GET and POST route handlers for Next.js App Router
+ *
+ * @example
+ * ```typescript
+ * // app/api/analytics/route.ts
+ * import { locallytics } from 'locallytics';
+ *
+ * const analytics = await locallytics({
+ *   database: process.env.DATABASE_URL!,
+ *   apiKey: process.env.ANALYTICS_API_KEY,
+ * });
+ *
+ * export const { GET, POST } = analytics;
+ * ```
+ */
+export declare function locallytics(config: LocallyticsConfig): Promise<RouteHandler>;
+/**
+ * Server-side helper to fetch analytics data
+ * Use in React Server Components
+ *
+ * @param options - Options including date range (optional)
+ * @returns Analytics data
+ *
+ * @example
+ * ```tsx
+ * // app/dashboard/page.tsx
+ * import { LocallyticsData } from 'locallytics';
+ *
+ * export default async function Dashboard() {
+ *   const data = await LocallyticsData(); // No arguments needed!
+ *
+ *   return <div>{data.pageviews} pageviews</div>;
+ * }
+ * ```
+ */
+export declare function LocallyticsData(options?: AnalyticsDataOptions): Promise<AnalyticsResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAI3B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,YAAY,CAAC,CAGvB;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,eAAe,CAAC,CAiE1B"}

package/dist/server/index.js

@@ -0,0 +1,100 @@
+import { PostgresDB } from "../db/postgres.js";
+import { createHandlers } from "./handlers.js";
+/**
+ * Initialize Locallytics and create route handlers
+ *
+ * @param config - Locallytics configuration
+ * @returns GET and POST route handlers for Next.js App Router
+ *
+ * @example
+ * ```typescript
+ * // app/api/analytics/route.ts
+ * import { locallytics } from 'locallytics';
+ *
+ * const analytics = await locallytics({
+ *   database: process.env.DATABASE_URL!,
+ *   apiKey: process.env.ANALYTICS_API_KEY,
+ * });
+ *
+ * export const { GET, POST } = analytics;
+ * ```
+ */
+export async function locallytics(config) {
+    const db = new PostgresDB(config.database);
+    return createHandlers(db, config);
+}
+import { headers } from "next/headers";
+/**
+ * Server-side helper to fetch analytics data
+ * Use in React Server Components
+ *
+ * @param options - Options including date range (optional)
+ * @returns Analytics data
+ *
+ * @example
+ * ```tsx
+ * // app/dashboard/page.tsx
+ * import { LocallyticsData } from 'locallytics';
+ *
+ * export default async function Dashboard() {
+ *   const data = await LocallyticsData(); // No arguments needed!
+ *
+ *   return <div>{data.pageviews} pageviews</div>;
+ * }
+ * ```
+ */
+export async function LocallyticsData(options = {}) {
+    const { dateRange = "last7d", endpoint = "/api/analytics" } = options;
+    // Get headers to extract host for URL construction
+    const headersList = await Promise.resolve(headers());
+    const host = headersList.get("host") ?? "localhost:3000";
+    const protocol = headersList.get("x-forwarded-proto") ?? "http";
+    // Build the range query parameter
+    let rangeParam;
+    if (typeof dateRange === "string") {
+        rangeParam = dateRange;
+    }
+    else {
+        rangeParam = `${dateRange.start.toISOString()},${dateRange.end.toISOString()}`;
+    }
+    // Construct the full URL
+    const url = `${protocol}://${host}${endpoint}?range=${encodeURIComponent(rangeParam)}`;
+    // Forward authorization header if present
+    const authHeader = headersList.get("authorization");
+    const fetchHeaders = {};
+    if (authHeader) {
+        fetchHeaders["authorization"] = authHeader;
+    }
+    try {
+        const response = await fetch(url, {
+            headers: fetchHeaders,
+            cache: "no-store",
+        });
+        if (!response.ok) {
+            const errorData = (await response.json().catch(() => ({})));
+            const errorMessage = errorData["message"] ??
+                errorData["error"] ??
+                `Failed to fetch analytics: ${response.status}`;
+            return {
+                pageviews: 0,
+                uniqueVisitors: 0,
+                topPages: [],
+                topReferrers: [],
+                dailyStats: [],
+                error: errorMessage,
+            };
+        }
+        return response.json();
+    }
+    catch (error) {
+        return {
+            pageviews: 0,
+            uniqueVisitors: 0,
+            topPages: [],
+            topReferrers: [],
+            dailyStats: [],
+            error: error instanceof Error ? error.message : "Unknown error occurred",
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}

package/dist/server/queries.d.ts

@@ -0,0 +1,10 @@
+import type { AnalyticsDB, AnalyticsResult, DateRange } from "../types/index.js";
+/**
+ * Fetch all analytics data in parallel
+ *
+ * @param db - Database instance
+ * @param dateRange - Date range for the query
+ * @returns Complete analytics data
+ */
+export declare function getAnalyticsData(db: AnalyticsDB, dateRange: DateRange): Promise<AnalyticsResult>;
+//# sourceMappingURL=queries.d.ts.map

package/dist/server/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/server/queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,SAAS,EACV,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,WAAW,EACf,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,eAAe,CAAC,CAiB1B"}

package/dist/server/queries.js

@@ -0,0 +1,24 @@
+/**
+ * Fetch all analytics data in parallel
+ *
+ * @param db - Database instance
+ * @param dateRange - Date range for the query
+ * @returns Complete analytics data
+ */
+export async function getAnalyticsData(db, dateRange) {
+    const [pageviews, uniqueVisitors, topPages, topReferrers, dailyStats] = await Promise.all([
+        db.getPageviews(dateRange),
+        db.getUniqueVisitors(dateRange),
+        db.getTopPages(dateRange, 10),
+        db.getTopReferrers(dateRange, 10),
+        db.getDailyStats(dateRange),
+    ]);
+    return {
+        pageviews,
+        uniqueVisitors,
+        topPages,
+        topReferrers,
+        dailyStats,
+    };
+}
+//# sourceMappingURL=queries.js.map

package/dist/server/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../src/server/queries.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,EAAe,EACf,SAAoB;IAEpB,MAAM,CAAC,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,CAAC,GACnE,MAAM,OAAO,CAAC,GAAG,CAAC;QAChB,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC;QAC1B,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC;QAC/B,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,EAAE,CAAC;QAC7B,EAAE,CAAC,eAAe,CAAC,SAAS,EAAE,EAAE,CAAC;QACjC,EAAE,CAAC,aAAa,CAAC,SAAS,CAAC;KAC5B,CAAC,CAAC;IAEL,OAAO;QACL,SAAS;QACT,cAAc;QACd,QAAQ;QACR,YAAY;QACZ,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/server/validator.d.ts

@@ -0,0 +1,32 @@
+import type { PageviewEvent } from "../types/index.js";
+/**
+ * Sanitize a URL by extracting pathname and search, removing credentials
+ *
+ * @param url - Raw URL string
+ * @returns Sanitized URL (pathname + search only)
+ */
+export declare function sanitizeUrl(url: string): string;
+/**
+ * Check if Do Not Track is enabled in the request
+ *
+ * @param request - Incoming request
+ * @returns true if DNT is enabled
+ */
+export declare function checkDNT(request: Request): boolean;
+/**
+ * Validate a single pageview event
+ *
+ * @param data - Unknown input data
+ * @returns Validated PageviewEvent
+ * @throws LocallyticsError if validation fails
+ */
+export declare function validatePageviewEvent(data: unknown): PageviewEvent;
+/**
+ * Validate a batch of pageview events
+ *
+ * @param data - Unknown input data
+ * @returns Array of validated PageviewEvents
+ * @throws LocallyticsError if validation fails
+ */
+export declare function validatePageviewBatch(data: unknown): PageviewEvent[];
+//# sourceMappingURL=validator.d.ts.map

package/dist/server/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/server/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAQvD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkB/C;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAgBlD;AASD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa,CA6ElE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa,EAAE,CA2BpE"}

package/dist/server/validator.js

@@ -0,0 +1,149 @@
+import { LocallyticsError } from "../types/index.js";
+const MAX_SESSION_ID_LENGTH = 255;
+const MAX_USER_AGENT_LENGTH = 512;
+const MAX_URL_LENGTH = 2048;
+const MAX_BATCH_SIZE = 100;
+/**
+ * Sanitize a URL by extracting pathname and search, removing credentials
+ *
+ * @param url - Raw URL string
+ * @returns Sanitized URL (pathname + search only)
+ */
+export function sanitizeUrl(url) {
+    try {
+        // Handle relative URLs by adding a base
+        const parsed = new URL(url, "http://localhost");
+        // Extract pathname and search only (no origin, hash, credentials)
+        let sanitized = parsed.pathname + parsed.search;
+        // Limit length
+        if (sanitized.length > MAX_URL_LENGTH) {
+            sanitized = sanitized.slice(0, MAX_URL_LENGTH);
+        }
+        return sanitized;
+    }
+    catch {
+        // On parse error, return root
+        return "/";
+    }
+}
+/**
+ * Check if Do Not Track is enabled in the request
+ *
+ * @param request - Incoming request
+ * @returns true if DNT is enabled
+ */
+export function checkDNT(request) {
+    const headers = request.headers;
+    // Check DNT header
+    const dnt = headers.get("dnt");
+    if (dnt === "1") {
+        return true;
+    }
+    // Check Sec-GPC header (Global Privacy Control)
+    const gpc = headers.get("sec-gpc");
+    if (gpc === "1") {
+        return true;
+    }
+    return false;
+}
+/**
+ * Type guard to check if value is a record
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Validate a single pageview event
+ *
+ * @param data - Unknown input data
+ * @returns Validated PageviewEvent
+ * @throws LocallyticsError if validation fails
+ */
+export function validatePageviewEvent(data) {
+    if (!isRecord(data)) {
+        throw LocallyticsError.validation("Event must be an object");
+    }
+    // sessionId
+    if (typeof data["sessionId"] !== "string" || data["sessionId"].length === 0) {
+        throw LocallyticsError.validation("sessionId must be a non-empty string");
+    }
+    if (data["sessionId"].length > MAX_SESSION_ID_LENGTH) {
+        throw LocallyticsError.validation(`sessionId must be at most ${MAX_SESSION_ID_LENGTH} characters`);
+    }
+    // pageUrl
+    if (typeof data["pageUrl"] !== "string" || data["pageUrl"].length === 0) {
+        throw LocallyticsError.validation("pageUrl must be a non-empty string");
+    }
+    // referrer (nullable)
+    if (data["referrer"] !== null &&
+        data["referrer"] !== undefined &&
+        typeof data["referrer"] !== "string") {
+        throw LocallyticsError.validation("referrer must be a string or null");
+    }
+    // userAgent
+    if (typeof data["userAgent"] !== "string") {
+        throw LocallyticsError.validation("userAgent must be a string");
+    }
+    // screenWidth
+    if (typeof data["screenWidth"] !== "number" ||
+        data["screenWidth"] <= 0 ||
+        !Number.isFinite(data["screenWidth"])) {
+        throw LocallyticsError.validation("screenWidth must be a positive number");
+    }
+    // screenHeight
+    if (typeof data["screenHeight"] !== "number" ||
+        data["screenHeight"] <= 0 ||
+        !Number.isFinite(data["screenHeight"])) {
+        throw LocallyticsError.validation("screenHeight must be a positive number");
+    }
+    // timestamp
+    if (typeof data["timestamp"] !== "string") {
+        throw LocallyticsError.validation("timestamp must be a string");
+    }
+    // Validate ISO 8601 format
+    const timestampDate = new Date(data["timestamp"]);
+    if (isNaN(timestampDate.getTime())) {
+        throw LocallyticsError.validation("timestamp must be a valid ISO 8601 date");
+    }
+    return {
+        sessionId: data["sessionId"],
+        pageUrl: sanitizeUrl(data["pageUrl"]),
+        referrer: typeof data["referrer"] === "string"
+            ? sanitizeUrl(data["referrer"])
+            : null,
+        userAgent: data["userAgent"].slice(0, MAX_USER_AGENT_LENGTH),
+        screenWidth: Math.round(data["screenWidth"]),
+        screenHeight: Math.round(data["screenHeight"]),
+        timestamp: data["timestamp"],
+    };
+}
+/**
+ * Validate a batch of pageview events
+ *
+ * @param data - Unknown input data
+ * @returns Array of validated PageviewEvents
+ * @throws LocallyticsError if validation fails
+ */
+export function validatePageviewBatch(data) {
+    if (!Array.isArray(data)) {
+        throw LocallyticsError.validation("Batch must be an array");
+    }
+    if (data.length === 0) {
+        throw LocallyticsError.validation("Batch cannot be empty");
+    }
+    if (data.length > MAX_BATCH_SIZE) {
+        throw LocallyticsError.validation(`Batch cannot exceed ${MAX_BATCH_SIZE} events`);
+    }
+    return data.map((event, index) => {
+        try {
+            return validatePageviewEvent(event);
+        }
+        catch (error) {
+            if (error instanceof LocallyticsError) {
+                throw LocallyticsError.validation(`Event at index ${index}: ${error.message}`);
+            }
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=validator.js.map

package/dist/server/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/server/validator.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Configuration for the locallytics() function
+ */
+export interface LocallyticsConfig {
+    /** PostgreSQL connection string */
+    database: string;
+    /** Optional API key for GET endpoint authentication */
+    apiKey?: string;
+}
+/**
+ * Pageview event sent from client
+ */
+export interface PageviewEvent {
+    /** Client-generated session ID (ephemeral) */
+    sessionId: string;
+    /** Sanitized page URL (pathname + search) */
+    pageUrl: string;
+    /** Sanitized referrer URL (nullable) */
+    referrer: string | null;
+    /** User agent string (limited to 512 chars) */
+    userAgent: string;
+    /** Screen width in pixels */
+    screenWidth: number;
+    /** Screen height in pixels */
+    screenHeight: number;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+/**
+ * Pageview as stored in database
+ */
+export interface StoredPageview extends PageviewEvent {
+    /** UUID primary key */
+    id: string;
+    /** SHA-256 hashed IP address (nullable) */
+    ipHash: string | null;
+}
+/**
+ * Date range for analytics queries
+ */
+export type DateRange = "last24h" | "last7d" | "last30d" | {
+    start: Date;
+    end: Date;
+};
+/**
+ * Page statistics
+ */
+export interface PageStats {
+    /** Page URL */
+    pageUrl: string;
+    /** Number of pageviews */
+    count: number;
+}
+/**
+ * Daily statistics
+ */
+export interface DailyStats {
+    /** Date in YYYY-MM-DD format */
+    date: string;
+    /** Total pageviews */
+    pageviews: number;
+    /** Unique visitors (distinct sessions) */
+    uniqueVisitors: number;
+}
+/**
+ * Complete analytics data response
+ */
+export interface AnalyticsResult {
+    /** Total pageviews in date range */
+    pageviews: number;
+    /** Unique visitors (distinct sessions) in date range */
+    uniqueVisitors: number;
+    /** Top pages by pageview count */
+    topPages: PageStats[];
+    /** Top referrers by pageview count */
+    topReferrers: PageStats[];
+    /** Daily breakdown of stats */
+    dailyStats: DailyStats[];
+    /** Error message if fetch failed */
+    error?: string;
+}
+/**
+ * Database interface for analytics operations
+ */
+export interface AnalyticsDB {
+    /** Insert a pageview event */
+    insertPageview(event: PageviewEvent, ipHash: string | null): Promise<void>;
+    /** Get total pageview count */
+    getPageviews(dateRange: DateRange): Promise<number>;
+    /** Get unique visitor count (distinct sessions) */
+    getUniqueVisitors(dateRange: DateRange): Promise<number>;
+    /** Get top pages by pageview count */
+    getTopPages(dateRange: DateRange, limit: number): Promise<PageStats[]>;
+    /** Get top referrers by pageview count */
+    getTopReferrers(dateRange: DateRange, limit: number): Promise<PageStats[]>;
+    /** Get daily stats breakdown */
+    getDailyStats(dateRange: DateRange): Promise<DailyStats[]>;
+    /** Close database connection */
+    close(): Promise<void>;
+}
+/**
+ * Route handler type for Next.js App Router
+ */
+export interface RouteHandler {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+}
+/**
+ * Options for AnalyticsJSON helper
+ */
+export interface AnalyticsDataOptions {
+    /** Optional date range for analytics data (default: last7d) */
+    dateRange?: DateRange;
+    /** API endpoint URL (defaults to /api/analytics) */
+    endpoint?: string;
+}
+/**
+ * Custom error class for Locallytics errors
+ */
+export declare class LocallyticsError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(message: string, code: string, statusCode?: number);
+    static validation(message: string): LocallyticsError;
+    static rateLimit(): LocallyticsError;
+    static unauthorized(): LocallyticsError;
+    static database(message: string): LocallyticsError;
+}
+//# sourceMappingURL=index.d.ts.map