@upstash/redis-analytics 0.1.0

package/src/react.ts

@@ -0,0 +1,163 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { AnalyticsClient } from "./client";
+import type {
+  CaptureEventInput,
+  ClientConfig,
+  FeatureFlagAssignment,
+  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 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>
+) {
+  // ── Shared state across all hook instances ──────────────────
+  let client: AnalyticsClient<TCustomEvents, TFeatureFlags> | null = null;
+  let currentSessionId: string | null = null;
+  let currentFeatureFlags: TFeatureFlags = {} as TFeatureFlags;
+  let sessionPromise: Promise<Session<TFeatureFlags>> | null = null;
+  const listeners = new Set<() => void>();
+
+  function getClient(): AnalyticsClient<TCustomEvents, TFeatureFlags> {
+    if (!client) {
+      client = new AnalyticsClient<TCustomEvents, TFeatureFlags>({
+        endpoint: config.endpoint,
+        flushInterval: config.flushInterval,
+        maxBatchSize: config.maxBatchSize,
+      });
+    }
+    return client;
+  }
+
+  function notify() {
+    listeners.forEach((l) => l());
+  }
+
+  async function doCreateSession(
+    flags?: {
+      [K in keyof TFeatureFlags]?: TFeatureFlags[K] | Record<string, number>;
+    }
+  ): Promise<Session<TFeatureFlags>> {
+    const session = await getClient().createSession({
+      featureFlags: flags as
+        | { [K in keyof TFeatureFlags]?: TFeatureFlags[K] | Record<string, number> }
+        | undefined,
+    });
+    currentSessionId = session.id;
+    currentFeatureFlags = session.featureFlags;
+    sessionPromise = null;
+    notify();
+    return session;
+  }
+
+  // Track the last captured path to avoid duplicate pageview events
+  let lastCapturedPath: string | null = null;
+
+  // ── The hook ───────────────────────────────────────────────
+  return function useAnalytics(
+    options?: { enabled?: boolean }
+  ): UseAnalyticsReturn<TCustomEvents, TFeatureFlags> {
+    const enabled = options?.enabled ?? true;
+    const [, rerender] = useState(0);
+    const subscribedRef = useRef(false);
+
+    // Subscribe to shared state changes
+    useEffect(() => {
+      const listener = () => rerender((n) => n + 1);
+      listeners.add(listener);
+      subscribedRef.current = true;
+      return () => {
+        listeners.delete(listener);
+      };
+    }, []);
+
+    // Auto-create session
+    useEffect(() => {
+      if (enabled && !currentSessionId && !sessionPromise) {
+        sessionPromise = doCreateSession(
+          config.featureFlags as
+            | { [K in keyof TFeatureFlags]?: TFeatureFlags[K] | Record<string, number> }
+            | undefined
+        );
+      }
+    }, [enabled]);
+
+    // Auto-capture pageview on path change
+    useEffect(() => {
+      if (!enabled || !currentSessionId) return;
+
+      const path = window.location.pathname;
+      if (path === lastCapturedPath) return;
+
+      lastCapturedPath = path;
+      getClient().capturePageView(currentSessionId, path);
+    });
+
+    const createSession = useCallback(
+      (flags?: {
+        [K in keyof TFeatureFlags]?: TFeatureFlags[K] | Record<string, number>;
+      }) => doCreateSession(flags),
+      []
+    );
+
+    const captureEvent = useCallback(
+      (input: CaptureEventInput<TCustomEvents>) => {
+        if (!currentSessionId) return;
+        getClient().captureEvent(input);
+      },
+      []
+    );
+
+    return {
+      client: getClient(),
+      sessionId: currentSessionId,
+      featureFlags: currentFeatureFlags,
+      captureEvent,
+      createSession,
+    };
+  };
+}

package/src/services/events.ts

@@ -0,0 +1,187 @@
+import type { Redis } from "@upstash/redis";
+import type { AnalyticsConfig, EventData, SessionMetadata } from "../types";
+import { LoggingService } from "./logging";
+import { SchemaRegistry } from "./schema-registry";
+import { generateEventKey } from "../utils";
+
+const SESSION_PREFIX = "analytics:session:";
+
+export class EventService {
+  constructor(
+    private redis: Redis,
+    private config: AnalyticsConfig,
+    private schemaRegistry: SchemaRegistry,
+    private logger: LoggingService
+  ) {}
+
+  async captureEvent(input: {
+    sessionId: string;
+    eventName: string;
+    properties?: Record<string, unknown>;
+  }): Promise<void> {
+    // Get session data
+    const sessionKey = `${SESSION_PREFIX}${input.sessionId}`;
+    const sessionData = await this.redis.get<SessionMetadata | string>(
+      sessionKey
+    );
+
+    if (!sessionData) {
+      throw new Error(`Session "${input.sessionId}" not found or expired`);
+    }
+
+    const session: SessionMetadata =
+      typeof sessionData === "string"
+        ? JSON.parse(sessionData)
+        : sessionData;
+
+    // Build event data
+    const now = new Date();
+    const eventData: 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 = generateEventKey();
+    await this.redis.json.set(eventKey, "$", eventData as never);
+
+    // 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: Array<{
+      sessionId: string;
+      eventName: string;
+      properties?: Record<string, unknown>;
+    }>
+  ): Promise<void> {
+    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<string, typeof events>();
+    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<string, SessionMetadata>();
+    for (let i = 0; i < sessionIds.length; i++) {
+      const raw = sessionResults[i] as SessionMetadata | string | null;
+      if (!raw) {
+        throw new Error(
+          `Session "${sessionIds[i]}" not found or expired`
+        );
+      }
+      const session: SessionMetadata =
+        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: 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 = generateEventKey();
+      eventPipeline.json.set(eventKey, "$", eventData as never);
+    }
+    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: string, path: string): Promise<void> {
+    await this.captureEvent({
+      sessionId,
+      eventName: "pageview",
+      properties: { path },
+    });
+  }
+
+  async captureClick(sessionId: string, element: string): Promise<void> {
+    await this.captureEvent({
+      sessionId,
+      eventName: "click",
+      properties: { element },
+    });
+  }
+
+  async captureError(sessionId: string, message: string): Promise<void> {
+    await this.captureEvent({
+      sessionId,
+      eventName: "error",
+      properties: { message },
+    });
+  }
+
+  async captureWarning(sessionId: string, message: string): Promise<void> {
+    await this.captureEvent({
+      sessionId,
+      eventName: "warning",
+      properties: { message },
+    });
+  }
+
+  async captureInfo(sessionId: string, message: string): Promise<void> {
+    await this.captureEvent({
+      sessionId,
+      eventName: "info",
+      properties: { message },
+    });
+  }
+}

package/src/services/feature-flags.ts

@@ -0,0 +1,125 @@
+import type { Redis } from "@upstash/redis";
+import type {
+  AnalyticsConfig,
+  FeatureFlagAssignment,
+  FeatureFlagConfig,
+  FeatureFlagDefinition,
+  FeatureFlagDefinitions,
+} from "../types";
+import { LoggingService } from "./logging";
+import { selectByDistribution } from "../utils";
+
+const FEATURE_FLAGS_KEY = "analytics:feature-flags";
+
+export class FeatureFlagService {
+  constructor(
+    private redis: Redis,
+    private config: AnalyticsConfig,
+    private logger: LoggingService
+  ) {}
+
+  async getDefinitions(): Promise<FeatureFlagDefinitions> {
+    const stored = await this.redis.get<FeatureFlagDefinitions>(
+      FEATURE_FLAGS_KEY
+    );
+    return stored ?? this.config.featureFlags;
+  }
+
+  async defineFlag(flagConfig: FeatureFlagConfig): Promise<void> {
+    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: string,
+    update: Partial<FeatureFlagDefinition>
+  ): Promise<void> {
+    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?: Record<string, FeatureFlagAssignment>
+  ): Promise<Record<string, string>> {
+    const definitions = await this.getDefinitions();
+    const resolved: Record<string, string> = {};
+
+    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] = selectByDistribution(assignment);
+      }
+    }
+
+    return resolved;
+  }
+
+  private validateFlagValue(
+    flagName: string,
+    value: string,
+    definitions: FeatureFlagDefinitions
+  ): void {
+    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(", ")}`
+      );
+    }
+  }
+}

package/src/services/logging.ts

@@ -0,0 +1,81 @@
+import type { Redis } from "@upstash/redis";
+import type { AnalyticsConfig, LogType, SystemLog } from "../types";
+import { generateLogKey } from "../utils";
+
+export class LoggingService {
+  constructor(
+    private redis: Redis,
+    private config: AnalyticsConfig
+  ) {}
+
+  async log(log: Omit<SystemLog, "timestamp">): Promise<void> {
+    if (!this.config.logging.enabledTypes.includes(log.logType)) {
+      return;
+    }
+
+    const key = generateLogKey();
+    const logEntry: SystemLog = {
+      ...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?: {
+    type?: LogType;
+    limit?: number;
+    offset?: number;
+  }): Promise<SystemLog[]> {
+    const limit = options?.limit ?? 50;
+    const offset = options?.offset ?? 0;
+
+    // Scan for log keys
+    const keys: string[] = [];
+    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<(string | null)[]>();
+
+    const logs: SystemLog[] = [];
+    for (const result of results) {
+      if (result) {
+        const log: SystemLog =
+          typeof result === "string" ? JSON.parse(result) : (result as SystemLog);
+        if (!options?.type || log.logType === options.type) {
+          logs.push(log);
+        }
+      }
+    }
+
+    return logs;
+  }
+}

package/src/services/schema-registry.ts

@@ -0,0 +1,125 @@
+import type { Redis } from "@upstash/redis";
+import type { AnalyticsConfig, EventSchema, SchemaProperty } from "../types";
+import { LoggingService } from "./logging";
+import { inferPropertyType } from "../utils";
+
+const SCHEMA_REGISTRY_KEY = "analytics:schema-registry";
+const CUSTOM_EVENT_FIRST_SEEN_KEY = "analytics:custom-events-first-seen";
+
+export class SchemaRegistry {
+  constructor(
+    private redis: Redis,
+    private config: AnalyticsConfig,
+    private logger: LoggingService
+  ) {}
+
+  async getSchema(eventName: string): Promise<EventSchema | null> {
+    const data = await this.redis.hget<EventSchema | string>(
+      SCHEMA_REGISTRY_KEY,
+      eventName
+    );
+    if (!data) return null;
+    return typeof data === "string" ? JSON.parse(data) : data;
+  }
+
+  async getAllSchemas(): Promise<Record<string, EventSchema>> {
+    const data = await this.redis.hgetall<
+      Record<string, EventSchema | string>
+    >(SCHEMA_REGISTRY_KEY);
+    if (!data) return {};
+
+    const result: Record<string, EventSchema> = {};
+    for (const [key, value] of Object.entries(data)) {
+      result[key] = typeof value === "string" ? JSON.parse(value) : value;
+    }
+    return result;
+  }
+
+  async trackCustomEventFirstSeen(eventName: string): Promise<void> {
+    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(): Promise<Record<string, number>> {
+    const data = await this.redis.hgetall<Record<string, number>>(
+      CUSTOM_EVENT_FIRST_SEEN_KEY
+    );
+    return data ?? {};
+  }
+
+  shouldValidate(): boolean {
+    const freq = this.config.schemaValidation.checkFrequency;
+    if (freq >= 1) return true;
+    if (freq <= 0) return false;
+    return Math.random() < freq;
+  }
+
+  async validateAndUpdateSchema(
+    eventName: string,
+    properties: Record<string, unknown>
+  ): Promise<void> {
+    if (!this.shouldValidate()) return;
+
+    const currentSchema = await this.getSchema(eventName);
+    const inferredProperties: Record<string, SchemaProperty> = {};
+
+    for (const [key, value] of Object.entries(properties)) {
+      inferredProperties[key] = { type: inferPropertyType(value) };
+    }
+
+    const newSchema: EventSchema = {
+      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),
+    });
+  }
+}
+
+function schemasEqual(
+  a: Record<string, SchemaProperty>,
+  b: Record<string, SchemaProperty>
+): boolean {
+  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;
+}