@upstash/redis-analytics 0.1.0

package/dist/protocol.d.ts

@@ -0,0 +1,45 @@
+export type AnalyticsRequest = {
+    requestType: "captureEvent";
+    data: {
+        sessionId: string;
+        eventName: string;
+        properties?: Record<string, unknown>;
+    };
+} | {
+    requestType: "captureBatchEvents";
+    data: {
+        events: Array<{
+            sessionId: string;
+            eventName: string;
+            properties?: Record<string, unknown>;
+        }>;
+    };
+} | {
+    requestType: "getSession";
+    data: {
+        sessionId: string;
+    };
+} | {
+    requestType: "getFeatureFlag";
+    data: {
+        sessionId: string;
+        flagName: string;
+    };
+} | {
+    requestType: "getAllFeatureFlags";
+    data: {
+        sessionId: string;
+    };
+} | {
+    requestType: "createSession";
+    data: {
+        featureFlags?: Record<string, string | Record<string, number>>;
+    };
+};
+export type AnalyticsResponse = {
+    success: true;
+    data?: unknown;
+} | {
+    success: false;
+    error: string;
+};

package/dist/protocol.js

@@ -0,0 +1,4 @@
+"use strict";
+// Protocol types for communication between frontend client and backend server.
+// These define the request/response contract for the single analytics endpoint.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/react.d.ts

@@ -0,0 +1,33 @@
+import { AnalyticsClient } from "./client";
+import type { CaptureEventInput, ClientConfig, Session } from "./types";
+type CreateAnalyticsHookConfig<TFeatureFlags extends Record<string, string> = Record<string, string>> = ClientConfig & {
+    /** Feature flag distributions for auto-created sessions */
+    featureFlags?: {
+        [K in keyof TFeatureFlags]?: TFeatureFlags[K] | Record<string, number>;
+    };
+};
+type UseAnalyticsReturn<TCustomEvents extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>, TFeatureFlags extends Record<string, string> = Record<string, string>> = {
+    client: AnalyticsClient<TCustomEvents, TFeatureFlags>;
+    sessionId: string | null;
+    featureFlags: TFeatureFlags;
+    captureEvent: (input: CaptureEventInput<TCustomEvents>) => void;
+    createSession: (flags?: {
+        [K in keyof TFeatureFlags]?: TFeatureFlags[K] | Record<string, number>;
+    }) => Promise<Session<TFeatureFlags>>;
+};
+/**
+ * Creates a shared analytics hook. Call once at module level,
+ * then use the returned hook in any component — no provider needed.
+ *
+ * ```ts
+ * export const useAnalytics = createAnalyticsHook<MyEvents, MyFlags>({
+ *   endpoint: "/api/analytics",
+ *   flushInterval: 2000,
+ *   featureFlags: { theme: { light: 50, dark: 50 } },
+ * });
+ * ```
+ */
+export declare function createAnalyticsHook<TCustomEvents extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>, TFeatureFlags extends Record<string, string> = Record<string, string>>(config: CreateAnalyticsHookConfig<TFeatureFlags>): (options?: {
+    enabled?: boolean;
+}) => UseAnalyticsReturn<TCustomEvents, TFeatureFlags>;
+export {};

package/dist/react.js

@@ -0,0 +1,95 @@
+"use strict";
+"use client";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAnalyticsHook = createAnalyticsHook;
+const react_1 = require("react");
+const client_1 = require("./client");
+/**
+ * Creates a shared analytics hook. Call once at module level,
+ * then use the returned hook in any component — no provider needed.
+ *
+ * ```ts
+ * export const useAnalytics = createAnalyticsHook<MyEvents, MyFlags>({
+ *   endpoint: "/api/analytics",
+ *   flushInterval: 2000,
+ *   featureFlags: { theme: { light: 50, dark: 50 } },
+ * });
+ * ```
+ */
+function createAnalyticsHook(config) {
+    // ── Shared state across all hook instances ──────────────────
+    let client = null;
+    let currentSessionId = null;
+    let currentFeatureFlags = {};
+    let sessionPromise = null;
+    const listeners = new Set();
+    function getClient() {
+        if (!client) {
+            client = new client_1.AnalyticsClient({
+                endpoint: config.endpoint,
+                flushInterval: config.flushInterval,
+                maxBatchSize: config.maxBatchSize,
+            });
+        }
+        return client;
+    }
+    function notify() {
+        listeners.forEach((l) => l());
+    }
+    async function doCreateSession(flags) {
+        const session = await getClient().createSession({
+            featureFlags: flags,
+        });
+        currentSessionId = session.id;
+        currentFeatureFlags = session.featureFlags;
+        sessionPromise = null;
+        notify();
+        return session;
+    }
+    // Track the last captured path to avoid duplicate pageview events
+    let lastCapturedPath = null;
+    // ── The hook ───────────────────────────────────────────────
+    return function useAnalytics(options) {
+        const enabled = options?.enabled ?? true;
+        const [, rerender] = (0, react_1.useState)(0);
+        const subscribedRef = (0, react_1.useRef)(false);
+        // Subscribe to shared state changes
+        (0, react_1.useEffect)(() => {
+            const listener = () => rerender((n) => n + 1);
+            listeners.add(listener);
+            subscribedRef.current = true;
+            return () => {
+                listeners.delete(listener);
+            };
+        }, []);
+        // Auto-create session
+        (0, react_1.useEffect)(() => {
+            if (enabled && !currentSessionId && !sessionPromise) {
+                sessionPromise = doCreateSession(config.featureFlags);
+            }
+        }, [enabled]);
+        // Auto-capture pageview on path change
+        (0, react_1.useEffect)(() => {
+            if (!enabled || !currentSessionId)
+                return;
+            const path = window.location.pathname;
+            if (path === lastCapturedPath)
+                return;
+            lastCapturedPath = path;
+            getClient().capturePageView(currentSessionId, path);
+        });
+        const createSession = (0, react_1.useCallback)((flags) => doCreateSession(flags), []);
+        const captureEvent = (0, react_1.useCallback)((input) => {
+            if (!currentSessionId)
+                return;
+            getClient().captureEvent(input);
+        }, []);
+        return {
+            client: getClient(),
+            sessionId: currentSessionId,
+            featureFlags: currentFeatureFlags,
+            captureEvent,
+            createSession,
+        };
+    };
+}

package/dist/services/events.d.ts

@@ -0,0 +1,26 @@
+import type { Redis } from "@upstash/redis";
+import type { AnalyticsConfig } from "../types";
+import { LoggingService } from "./logging";
+import { SchemaRegistry } from "./schema-registry";
+export declare class EventService {
+    private redis;
+    private config;
+    private schemaRegistry;
+    private logger;
+    constructor(redis: Redis, config: AnalyticsConfig, schemaRegistry: SchemaRegistry, logger: LoggingService);
+    captureEvent(input: {
+        sessionId: string;
+        eventName: string;
+        properties?: Record<string, unknown>;
+    }): Promise<void>;
+    captureBatchEvents(events: Array<{
+        sessionId: string;
+        eventName: string;
+        properties?: Record<string, unknown>;
+    }>): Promise<void>;
+    capturePageView(sessionId: string, path: string): Promise<void>;
+    captureClick(sessionId: string, element: string): Promise<void>;
+    captureError(sessionId: string, message: string): Promise<void>;
+    captureWarning(sessionId: string, message: string): Promise<void>;
+    captureInfo(sessionId: string, message: string): Promise<void>;
+}

package/dist/services/events.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventService = void 0;
+const utils_1 = require("../utils");
+const SESSION_PREFIX = "analytics:session:";
+class EventService {
+    constructor(redis, config, schemaRegistry, logger) {
+        this.redis = redis;
+        this.config = config;
+        this.schemaRegistry = schemaRegistry;
+        this.logger = logger;
+    }
+    async captureEvent(input) {
+        // Get session data
+        const sessionKey = `${SESSION_PREFIX}${input.sessionId}`;
+        const sessionData = await this.redis.get(sessionKey);
+        if (!sessionData) {
+            throw new Error(`Session "${input.sessionId}" not found or expired`);
+        }
+        const session = typeof sessionData === "string"
+            ? JSON.parse(sessionData)
+            : sessionData;
+        // Build event data
+        const now = new Date();
+        const eventData = {
+            sessionCreationTimestamp: session.createdAt,
+            sessionId: input.sessionId,
+            eventTime: now.toISOString(),
+            eventTimeMs: now.getTime(),
+            eventName: input.eventName,
+            featureFlags: session.featureFlags,
+            ...(session.metadata ? { sessionMetadata: session.metadata } : {}),
+            properties: input.properties,
+        };
+        // Store event as JSON
+        const eventKey = (0, utils_1.generateEventKey)();
+        await this.redis.json.set(eventKey, "$", eventData);
+        // Track schema for events with properties
+        if (input.properties) {
+            await this.schemaRegistry.validateAndUpdateSchema(input.eventName, input.properties);
+        }
+        // Track first-seen timestamp for custom events
+        if (input.eventName.startsWith("custom:")) {
+            await this.schemaRegistry.trackCustomEventFirstSeen(input.eventName);
+        }
+    }
+    async captureBatchEvents(events) {
+        if (events.length === 0)
+            return;
+        const maxBatchSize = this.config.events.maxBatchSize;
+        if (events.length > maxBatchSize) {
+            throw new Error(`Batch size ${events.length} exceeds maximum of ${maxBatchSize}`);
+        }
+        // Group events by sessionId
+        const bySession = new Map();
+        for (const event of events) {
+            const existing = bySession.get(event.sessionId) ?? [];
+            existing.push(event);
+            bySession.set(event.sessionId, existing);
+        }
+        // Fetch all unique sessions
+        const sessionIds = [...bySession.keys()];
+        const sessionPipeline = this.redis.pipeline();
+        for (const sid of sessionIds) {
+            sessionPipeline.get(`${SESSION_PREFIX}${sid}`);
+        }
+        const sessionResults = await sessionPipeline.exec();
+        const sessions = new Map();
+        for (let i = 0; i < sessionIds.length; i++) {
+            const raw = sessionResults[i];
+            if (!raw) {
+                throw new Error(`Session "${sessionIds[i]}" not found or expired`);
+            }
+            const session = typeof raw === "string" ? JSON.parse(raw) : raw;
+            sessions.set(sessionIds[i], session);
+        }
+        // Store all events in a pipeline
+        const eventPipeline = this.redis.pipeline();
+        for (const event of events) {
+            const session = sessions.get(event.sessionId);
+            const now = new Date();
+            const eventData = {
+                sessionCreationTimestamp: session.createdAt,
+                sessionId: event.sessionId,
+                eventTime: now.toISOString(),
+                eventTimeMs: now.getTime(),
+                eventName: event.eventName,
+                featureFlags: session.featureFlags,
+                ...(session.metadata ? { sessionMetadata: session.metadata } : {}),
+                properties: event.properties,
+            };
+            const eventKey = (0, utils_1.generateEventKey)();
+            eventPipeline.json.set(eventKey, "$", eventData);
+        }
+        await eventPipeline.exec();
+        // Track schemas for events with properties
+        for (const event of events) {
+            if (event.properties) {
+                await this.schemaRegistry.validateAndUpdateSchema(event.eventName, event.properties);
+            }
+            if (event.eventName.startsWith("custom:")) {
+                await this.schemaRegistry.trackCustomEventFirstSeen(event.eventName);
+            }
+        }
+    }
+    // Convenience methods
+    async capturePageView(sessionId, path) {
+        await this.captureEvent({
+            sessionId,
+            eventName: "pageview",
+            properties: { path },
+        });
+    }
+    async captureClick(sessionId, element) {
+        await this.captureEvent({
+            sessionId,
+            eventName: "click",
+            properties: { element },
+        });
+    }
+    async captureError(sessionId, message) {
+        await this.captureEvent({
+            sessionId,
+            eventName: "error",
+            properties: { message },
+        });
+    }
+    async captureWarning(sessionId, message) {
+        await this.captureEvent({
+            sessionId,
+            eventName: "warning",
+            properties: { message },
+        });
+    }
+    async captureInfo(sessionId, message) {
+        await this.captureEvent({
+            sessionId,
+            eventName: "info",
+            properties: { message },
+        });
+    }
+}
+exports.EventService = EventService;

package/dist/services/feature-flags.d.ts

@@ -0,0 +1,14 @@
+import type { Redis } from "@upstash/redis";
+import type { AnalyticsConfig, FeatureFlagAssignment, FeatureFlagConfig, FeatureFlagDefinition, FeatureFlagDefinitions } from "../types";
+import { LoggingService } from "./logging";
+export declare class FeatureFlagService {
+    private redis;
+    private config;
+    private logger;
+    constructor(redis: Redis, config: AnalyticsConfig, logger: LoggingService);
+    getDefinitions(): Promise<FeatureFlagDefinitions>;
+    defineFlag(flagConfig: FeatureFlagConfig): Promise<void>;
+    updateFlag(name: string, update: Partial<FeatureFlagDefinition>): Promise<void>;
+    resolveFlags(assignments?: Record<string, FeatureFlagAssignment>): Promise<Record<string, string>>;
+    private validateFlagValue;
+}

package/dist/services/feature-flags.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlagService = void 0;
+const utils_1 = require("../utils");
+const FEATURE_FLAGS_KEY = "analytics:feature-flags";
+class FeatureFlagService {
+    constructor(redis, config, logger) {
+        this.redis = redis;
+        this.config = config;
+        this.logger = logger;
+    }
+    async getDefinitions() {
+        const stored = await this.redis.get(FEATURE_FLAGS_KEY);
+        return stored ?? this.config.featureFlags;
+    }
+    async defineFlag(flagConfig) {
+        const definitions = await this.getDefinitions();
+        const before = definitions[flagConfig.name];
+        const { name, ...definition } = flagConfig;
+        definitions[name] = definition;
+        await this.redis.set(FEATURE_FLAGS_KEY, JSON.stringify(definitions));
+        await this.logger.log({
+            logType: "feature_flag_update",
+            eventName: name,
+            changes: {
+                before: before ?? null,
+                after: definition,
+            },
+        });
+    }
+    async updateFlag(name, update) {
+        const definitions = await this.getDefinitions();
+        const existing = definitions[name];
+        if (!existing) {
+            throw new Error(`Feature flag "${name}" does not exist`);
+        }
+        const before = { ...existing };
+        definitions[name] = { ...existing, ...update };
+        await this.redis.set(FEATURE_FLAGS_KEY, JSON.stringify(definitions));
+        await this.logger.log({
+            logType: "feature_flag_update",
+            eventName: name,
+            changes: { before, after: definitions[name] },
+        });
+    }
+    async resolveFlags(assignments) {
+        const definitions = await this.getDefinitions();
+        const resolved = {};
+        for (const [flagName, definition] of Object.entries(definitions)) {
+            const assignment = assignments?.[flagName];
+            if (assignment === undefined) {
+                // Use default value
+                resolved[flagName] = definition.defaultValue;
+            }
+            else if (typeof assignment === "string") {
+                // Explicit value - validate
+                if (!definition.possibleValues.includes(assignment)) {
+                    throw new Error(`Invalid value "${assignment}" for feature flag "${flagName}". ` +
+                        `Possible values: ${definition.possibleValues.join(", ")}`);
+                }
+                resolved[flagName] = assignment;
+            }
+            else {
+                // Distribution-based assignment
+                const distributionValues = Object.keys(assignment);
+                for (const v of distributionValues) {
+                    if (!definition.possibleValues.includes(v)) {
+                        throw new Error(`Invalid distribution value "${v}" for feature flag "${flagName}". ` +
+                            `Possible values: ${definition.possibleValues.join(", ")}`);
+                    }
+                }
+                resolved[flagName] = (0, utils_1.selectByDistribution)(assignment);
+            }
+        }
+        return resolved;
+    }
+    validateFlagValue(flagName, value, definitions) {
+        const definition = definitions[flagName];
+        if (!definition) {
+            throw new Error(`Feature flag "${flagName}" does not exist`);
+        }
+        if (!definition.possibleValues.includes(value)) {
+            throw new Error(`Invalid value "${value}" for feature flag "${flagName}". ` +
+                `Possible values: ${definition.possibleValues.join(", ")}`);
+        }
+    }
+}
+exports.FeatureFlagService = FeatureFlagService;

package/dist/services/logging.d.ts

@@ -0,0 +1,13 @@
+import type { Redis } from "@upstash/redis";
+import type { AnalyticsConfig, LogType, SystemLog } from "../types";
+export declare class LoggingService {
+    private redis;
+    private config;
+    constructor(redis: Redis, config: AnalyticsConfig);
+    log(log: Omit<SystemLog, "timestamp">): Promise<void>;
+    getLogs(options?: {
+        type?: LogType;
+        limit?: number;
+        offset?: number;
+    }): Promise<SystemLog[]>;
+}

package/dist/services/logging.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoggingService = void 0;
+const utils_1 = require("../utils");
+class LoggingService {
+    constructor(redis, config) {
+        this.redis = redis;
+        this.config = config;
+    }
+    async log(log) {
+        if (!this.config.logging.enabledTypes.includes(log.logType)) {
+            return;
+        }
+        const key = (0, utils_1.generateLogKey)();
+        const logEntry = {
+            ...log,
+            timestamp: Date.now(),
+        };
+        const retentionMs = this.config.logging.retentionDays * 24 * 60 * 60 * 1000;
+        const px = Math.max(retentionMs, 1000);
+        await this.redis.set(key, JSON.stringify(logEntry), { px });
+    }
+    async getLogs(options) {
+        const limit = options?.limit ?? 50;
+        const offset = options?.offset ?? 0;
+        // Scan for log keys
+        const keys = [];
+        let cursor = 0;
+        const maxScan = 1000; // safety limit
+        let scanned = 0;
+        do {
+            const [nextCursor, batch] = await this.redis.scan(cursor, {
+                match: "system-log-*",
+                count: 100,
+            });
+            cursor = typeof nextCursor === "string" ? parseInt(nextCursor) : nextCursor;
+            keys.push(...batch);
+            scanned += batch.length;
+        } while (cursor !== 0 && scanned < maxScan);
+        if (keys.length === 0)
+            return [];
+        // Sort by key (timestamp is embedded in key)
+        keys.sort().reverse();
+        // Paginate
+        const paginatedKeys = keys.slice(offset, offset + limit);
+        if (paginatedKeys.length === 0)
+            return [];
+        // Fetch logs
+        const pipeline = this.redis.pipeline();
+        for (const key of paginatedKeys) {
+            pipeline.get(key);
+        }
+        const results = await pipeline.exec();
+        const logs = [];
+        for (const result of results) {
+            if (result) {
+                const log = typeof result === "string" ? JSON.parse(result) : result;
+                if (!options?.type || log.logType === options.type) {
+                    logs.push(log);
+                }
+            }
+        }
+        return logs;
+    }
+}
+exports.LoggingService = LoggingService;

package/dist/services/schema-registry.d.ts

@@ -0,0 +1,15 @@
+import type { Redis } from "@upstash/redis";
+import type { AnalyticsConfig, EventSchema } from "../types";
+import { LoggingService } from "./logging";
+export declare class SchemaRegistry {
+    private redis;
+    private config;
+    private logger;
+    constructor(redis: Redis, config: AnalyticsConfig, logger: LoggingService);
+    getSchema(eventName: string): Promise<EventSchema | null>;
+    getAllSchemas(): Promise<Record<string, EventSchema>>;
+    trackCustomEventFirstSeen(eventName: string): Promise<void>;
+    getCustomEventFirstSeen(): Promise<Record<string, number>>;
+    shouldValidate(): boolean;
+    validateAndUpdateSchema(eventName: string, properties: Record<string, unknown>): Promise<void>;
+}

package/dist/services/schema-registry.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaRegistry = void 0;
+const utils_1 = require("../utils");
+const SCHEMA_REGISTRY_KEY = "analytics:schema-registry";
+const CUSTOM_EVENT_FIRST_SEEN_KEY = "analytics:custom-events-first-seen";
+class SchemaRegistry {
+    constructor(redis, config, logger) {
+        this.redis = redis;
+        this.config = config;
+        this.logger = logger;
+    }
+    async getSchema(eventName) {
+        const data = await this.redis.hget(SCHEMA_REGISTRY_KEY, eventName);
+        if (!data)
+            return null;
+        return typeof data === "string" ? JSON.parse(data) : data;
+    }
+    async getAllSchemas() {
+        const data = await this.redis.hgetall(SCHEMA_REGISTRY_KEY);
+        if (!data)
+            return {};
+        const result = {};
+        for (const [key, value] of Object.entries(data)) {
+            result[key] = typeof value === "string" ? JSON.parse(value) : value;
+        }
+        return result;
+    }
+    async trackCustomEventFirstSeen(eventName) {
+        if (!this.shouldValidate())
+            return;
+        const exists = await this.redis.hexists(CUSTOM_EVENT_FIRST_SEEN_KEY, eventName);
+        if (!exists) {
+            await this.redis.hset(CUSTOM_EVENT_FIRST_SEEN_KEY, {
+                [eventName]: Date.now(),
+            });
+        }
+    }
+    async getCustomEventFirstSeen() {
+        const data = await this.redis.hgetall(CUSTOM_EVENT_FIRST_SEEN_KEY);
+        return data ?? {};
+    }
+    shouldValidate() {
+        const freq = this.config.schemaValidation.checkFrequency;
+        if (freq >= 1)
+            return true;
+        if (freq <= 0)
+            return false;
+        return Math.random() < freq;
+    }
+    async validateAndUpdateSchema(eventName, properties) {
+        if (!this.shouldValidate())
+            return;
+        const currentSchema = await this.getSchema(eventName);
+        const inferredProperties = {};
+        for (const [key, value] of Object.entries(properties)) {
+            inferredProperties[key] = { type: (0, utils_1.inferPropertyType)(value) };
+        }
+        const newSchema = {
+            properties: inferredProperties,
+            lastUpdated: Date.now(),
+            version: currentSchema ? currentSchema.version + 1 : 1,
+        };
+        // Check if schema has changed
+        if (currentSchema) {
+            const hasChanged = !schemasEqual(currentSchema.properties, inferredProperties);
+            if (!hasChanged)
+                return;
+            // Log schema change
+            await this.logger.log({
+                logType: "schema_update",
+                eventName,
+                changes: {
+                    before: currentSchema,
+                    after: newSchema,
+                },
+            });
+        }
+        await this.redis.hset(SCHEMA_REGISTRY_KEY, {
+            [eventName]: JSON.stringify(newSchema),
+        });
+    }
+}
+exports.SchemaRegistry = SchemaRegistry;
+function schemasEqual(a, b) {
+    const keysA = Object.keys(a).sort();
+    const keysB = Object.keys(b).sort();
+    if (keysA.length !== keysB.length)
+        return false;
+    for (let i = 0; i < keysA.length; i++) {
+        if (keysA[i] !== keysB[i])
+            return false;
+        if (a[keysA[i]].type !== b[keysB[i]].type)
+            return false;
+    }
+    return true;
+}