@upstash/redis-analytics 0.1.0

package/src/backend-client.ts

@@ -0,0 +1,301 @@
+import { Redis } from "@upstash/redis";
+import type {
+  AnalyticsConfig,
+  CaptureEventInput,
+  DeepPartial,
+  EventSchema,
+  FeatureFlagAssignment,
+  FeatureFlagConfig,
+  FeatureFlagDefinition,
+  LogType,
+  SearchIndexInfo,
+  ServerConfig,
+  Session,
+  SessionResult,
+  SystemLog,
+} from "./types";
+import type { AnalyticsRequest, AnalyticsResponse } from "./protocol";
+import { LoggingService } from "./services/logging";
+import { FeatureFlagService } from "./services/feature-flags";
+import { SessionService } from "./services/sessions";
+import { EventService } from "./services/events";
+import { SchemaRegistry } from "./services/schema-registry";
+import { SearchIndexService } from "./services/search-index";
+
+const DEFAULT_CONFIG: AnalyticsConfig = {
+  session: {
+    expirationMs: 3_600_000, // 1 hour
+  },
+  featureFlags: {},
+  events: {
+    customEventRetentionDays: 7,
+    maxBatchSize: 20,
+  },
+  schemaValidation: {
+    checkFrequency: 1,
+  },
+  logging: {
+    retentionDays: 30,
+    enabledTypes: [
+      "schema_update",
+      "feature_flag_update",
+      "system_error",
+      "index_update",
+    ],
+  },
+  search: {
+    indexName: "events-idx",
+    autoUpdate: true,
+    rebuildOnStartup: false,
+  },
+};
+
+function deepMerge<T extends Record<string, unknown>>(
+  target: T,
+  source: DeepPartial<T>
+): T {
+  const result = { ...target };
+  for (const key of Object.keys(source) as Array<keyof T>) {
+    const sourceVal = source[key];
+    if (sourceVal === undefined) continue;
+    const targetVal = result[key];
+    if (
+      targetVal &&
+      typeof targetVal === "object" &&
+      !Array.isArray(targetVal) &&
+      typeof sourceVal === "object" &&
+      !Array.isArray(sourceVal)
+    ) {
+      result[key] = deepMerge(
+        targetVal as Record<string, unknown>,
+        sourceVal as Record<string, unknown>
+      ) as T[keyof T];
+    } else {
+      result[key] = sourceVal as T[keyof T];
+    }
+  }
+  return result;
+}
+
+export type MiddlewareResult<
+  TSessionMetadata extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  sessionMetadata: TSessionMetadata;
+};
+
+export type HandlerOptions<
+  TSessionMetadata extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  /**
+   * Middleware that runs before each request is processed.
+   * Return a Response to short-circuit (e.g. 401 Unauthorized).
+   * Return void to let the request proceed.
+   * Return { sessionMetadata } to attach metadata to the session (createSession only).
+   */
+  middleware?: (context: {
+    request: Request;
+    analyticsRequest: AnalyticsRequest;
+  }) =>
+    | Response
+    | void
+    | MiddlewareResult<TSessionMetadata>
+    | Promise<Response | void | MiddlewareResult<TSessionMetadata>>;
+};
+
+export class AnalyticsBackendClient<
+  TCustomEvents extends Record<string, Record<string, unknown>> = Record<
+    string,
+    Record<string, unknown>
+  >,
+  TFeatureFlags extends Record<string, string> = Record<string, string>,
+  TSessionMetadata extends Record<string, unknown> = Record<string, unknown>,
+> {
+  readonly events: EventService;
+  readonly sessions: SessionService;
+  readonly featureFlags: FeatureFlagService;
+  readonly schemas: SchemaRegistry;
+  readonly logs: LoggingService;
+  readonly searchIndex: SearchIndexService;
+
+  private redis: Redis;
+  private config: AnalyticsConfig;
+
+  constructor(serverConfig: ServerConfig) {
+    this.redis = new Redis({
+      url: serverConfig.redis.url,
+      token: serverConfig.redis.token,
+    });
+    this.config = deepMerge(
+      DEFAULT_CONFIG,
+      (serverConfig.config ?? {}) as DeepPartial<AnalyticsConfig>
+    );
+
+    this.logs = new LoggingService(this.redis, this.config);
+    this.featureFlags = new FeatureFlagService(this.redis, this.config, this.logs);
+    this.sessions = new SessionService(
+      this.redis,
+      this.config,
+      this.featureFlags,
+      this.logs
+    );
+    this.schemas = new SchemaRegistry(this.redis, this.config, this.logs);
+    this.searchIndex = new SearchIndexService(
+      this.redis,
+      this.config,
+      this.schemas,
+      this.featureFlags,
+      this.logs
+    );
+    this.events = new EventService(
+      this.redis,
+      this.config,
+      this.schemas,
+      this.logs
+    );
+  }
+
+  // ─── Handler ──────────────────────────────────────────────────
+
+  getHandler(options?: HandlerOptions<TSessionMetadata>): (request: Request) => Promise<Response> {
+    return (request: Request) => this.handleRequest(request, options);
+  }
+
+  private async handleRequest(
+    request: Request,
+    options?: HandlerOptions<TSessionMetadata>
+  ): Promise<Response> {
+    try {
+      const method = request.method.toUpperCase();
+      let analyticsRequest: AnalyticsRequest;
+
+      if (method === "GET") {
+        const url = new URL(request.url);
+        const requestType = url.searchParams.get("requestType");
+
+        if (!requestType) {
+          return new Response(
+            JSON.stringify({
+              success: false,
+              error: "Missing requestType query parameter",
+            }),
+            { status: 400, headers: { "Content-Type": "application/json" } }
+          );
+        }
+
+        analyticsRequest = this.parseGetRequest(requestType, url.searchParams);
+      } else {
+        analyticsRequest = (await request.json()) as AnalyticsRequest;
+      }
+
+      // Run middleware
+      let sessionMetadata: TSessionMetadata | undefined;
+      if (options?.middleware) {
+        const middlewareResult = await options.middleware({
+          request,
+          analyticsRequest,
+        });
+        if (middlewareResult instanceof Response) {
+          return middlewareResult;
+        }
+        if (middlewareResult && typeof middlewareResult === "object" && "sessionMetadata" in middlewareResult) {
+          sessionMetadata = middlewareResult.sessionMetadata;
+        }
+      }
+
+      const result = await this.processRequest(analyticsRequest, sessionMetadata);
+      return new Response(JSON.stringify(result), {
+        status: result.success ? 200 : 400,
+        headers: { "Content-Type": "application/json" },
+      });
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Unknown error";
+      const result: AnalyticsResponse = { success: false, error: message };
+      return new Response(JSON.stringify(result), {
+        status: 400,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+  }
+
+  private parseGetRequest(
+    requestType: string,
+    params: URLSearchParams
+  ): AnalyticsRequest {
+    switch (requestType) {
+      case "getSession":
+        return {
+          requestType: "getSession",
+          data: { sessionId: params.get("sessionId")! },
+        };
+      case "getFeatureFlag":
+        return {
+          requestType: "getFeatureFlag",
+          data: {
+            sessionId: params.get("sessionId")!,
+            flagName: params.get("flagName")!,
+          },
+        };
+      case "getAllFeatureFlags":
+        return {
+          requestType: "getAllFeatureFlags",
+          data: { sessionId: params.get("sessionId")! },
+        };
+      default:
+        throw new Error(`Unknown GET request type: ${requestType}`);
+    }
+  }
+
+  private async processRequest(
+    req: AnalyticsRequest,
+    sessionMetadata?: Record<string, unknown>
+  ): Promise<AnalyticsResponse> {
+    switch (req.requestType) {
+      case "captureEvent": {
+        await this.events.captureEvent(req.data as any);
+        return { success: true };
+      }
+      case "captureBatchEvents": {
+        await this.events.captureBatchEvents(req.data.events);
+        return { success: true };
+      }
+      case "getSession": {
+        const session = await this.sessions.getSession(req.data.sessionId);
+        return { success: true, data: session };
+      }
+      case "getFeatureFlag": {
+        const value = await this.sessions.getFeatureFlag(
+          req.data.sessionId,
+          req.data.flagName
+        );
+        return { success: true, data: { value } };
+      }
+      case "getAllFeatureFlags": {
+        const flags = await this.sessions.getAllFeatureFlags(req.data.sessionId);
+        return { success: true, data: flags };
+      }
+      case "createSession": {
+        const session = await this.sessions.createSession({
+          featureFlags: req.data.featureFlags as
+            | Record<string, FeatureFlagAssignment>
+            | undefined,
+          metadata: sessionMetadata,
+        });
+        // Register session metadata schema so it's available in search index
+        if (sessionMetadata && Object.keys(sessionMetadata).length > 0) {
+          await this.schemas.validateAndUpdateSchema(
+            "__session_metadata__",
+            sessionMetadata
+          );
+        }
+        return { success: true, data: session };
+      }
+      default: {
+        return {
+          success: false,
+          error: `Unknown request type: ${(req as any).requestType}`,
+        };
+      }
+    }
+  }
+}

package/src/client.ts

@@ -0,0 +1,245 @@
+import type {
+  AnalyticsRequest,
+  AnalyticsResponse,
+} from "./protocol";
+import type {
+  CaptureEventInput,
+  ClientConfig,
+  Session,
+  SessionResult,
+} from "./types";
+
+export class AnalyticsClient<
+  TCustomEvents extends Record<string, Record<string, unknown>> = Record<
+    string,
+    Record<string, unknown>
+  >,
+  TFeatureFlags extends Record<string, string> = Record<string, string>,
+> {
+  private endpoint: string;
+  private flushInterval: number;
+  private maxBatchSize: number;
+  private eventQueue: Array<{
+    sessionId: string;
+    eventName: string;
+    properties?: Record<string, unknown>;
+  }> = [];
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(config?: ClientConfig) {
+    this.endpoint = config?.endpoint ?? "/api/analytics";
+    this.flushInterval = config?.flushInterval ?? 0;
+    this.maxBatchSize = config?.maxBatchSize ?? 20;
+  }
+
+  private async sendPost<T = unknown>(
+    request: AnalyticsRequest
+  ): Promise<T> {
+    const response = await fetch(this.endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(request),
+    });
+
+    const result: AnalyticsResponse = await response.json();
+
+    if (!result.success) {
+      throw new Error(result.error ?? "Analytics request failed");
+    }
+
+    return result.data as T;
+  }
+
+  private async sendGet<T = unknown>(
+    requestType: string,
+    params: Record<string, string>
+  ): Promise<T> {
+    const searchParams = new URLSearchParams({ requestType, ...params });
+    const response = await fetch(`${this.endpoint}?${searchParams}`);
+
+    const result: AnalyticsResponse = await response.json();
+
+    if (!result.success) {
+      throw new Error(result.error ?? "Analytics request failed");
+    }
+
+    return result.data as T;
+  }
+
+  // ─── Batch Queue ─────────────────────────────────────────────
+
+  private enqueueEvent(event: {
+    sessionId: string;
+    eventName: string;
+    properties?: Record<string, unknown>;
+  }): void {
+    this.eventQueue.push(event);
+
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+    }
+
+    this.flushTimer = setTimeout(() => {
+      this.flush();
+    }, this.flushInterval);
+  }
+
+  async flush(): Promise<void> {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    if (this.eventQueue.length === 0) return;
+
+    const events = [...this.eventQueue];
+    this.eventQueue = [];
+
+    if (events.length === 1) {
+      await this.sendPost({
+        requestType: "captureEvent",
+        data: events[0],
+      });
+    } else {
+      // Send in chunks of maxBatchSize
+      for (let i = 0; i < events.length; i += this.maxBatchSize) {
+        const chunk = events.slice(i, i + this.maxBatchSize);
+        await this.sendPost({
+          requestType: "captureBatchEvents",
+          data: { events: chunk },
+        });
+      }
+    }
+  }
+
+  // ─── Session Management ──────────────────────────────────────
+
+  async createSession(options?: {
+    featureFlags?: { [K in keyof TFeatureFlags]?: TFeatureFlags[K] | Record<string, number> };
+  }): Promise<Session<TFeatureFlags>> {
+    return this.sendPost<Session<TFeatureFlags>>({
+      requestType: "createSession",
+      data: {
+        featureFlags: options?.featureFlags as Record<string, string | Record<string, number>> | undefined,
+      },
+    });
+  }
+
+  async getSession(sessionId: string): Promise<SessionResult<TFeatureFlags>> {
+    return this.sendGet<SessionResult<TFeatureFlags>>("getSession", { sessionId });
+  }
+
+  // ─── Event Tracking ──────────────────────────────────────────
+
+  async captureEvent(
+    input: CaptureEventInput<TCustomEvents>
+  ): Promise<void> {
+    const event = input as {
+      sessionId: string;
+      eventName: string;
+      properties?: Record<string, unknown>;
+    };
+
+    if (this.flushInterval > 0) {
+      this.enqueueEvent(event);
+      return;
+    }
+
+    await this.sendPost({
+      requestType: "captureEvent",
+      data: event,
+    });
+  }
+
+  async capturePageView(sessionId: string, path: string): Promise<void> {
+    const event = { sessionId, eventName: "pageview" as const, properties: { path } };
+
+    if (this.flushInterval > 0) {
+      this.enqueueEvent(event);
+      return;
+    }
+
+    await this.sendPost({
+      requestType: "captureEvent",
+      data: event,
+    });
+  }
+
+  async captureClick(sessionId: string, element: string): Promise<void> {
+    const event = { sessionId, eventName: "click" as const, properties: { element } };
+
+    if (this.flushInterval > 0) {
+      this.enqueueEvent(event);
+      return;
+    }
+
+    await this.sendPost({
+      requestType: "captureEvent",
+      data: event,
+    });
+  }
+
+  async captureError(sessionId: string, message: string): Promise<void> {
+    const event = { sessionId, eventName: "error" as const, properties: { message } };
+
+    if (this.flushInterval > 0) {
+      this.enqueueEvent(event);
+      return;
+    }
+
+    await this.sendPost({
+      requestType: "captureEvent",
+      data: event,
+    });
+  }
+
+  async captureWarning(sessionId: string, message: string): Promise<void> {
+    const event = { sessionId, eventName: "warning" as const, properties: { message } };
+
+    if (this.flushInterval > 0) {
+      this.enqueueEvent(event);
+      return;
+    }
+
+    await this.sendPost({
+      requestType: "captureEvent",
+      data: event,
+    });
+  }
+
+  async captureInfo(sessionId: string, message: string): Promise<void> {
+    const event = { sessionId, eventName: "info" as const, properties: { message } };
+
+    if (this.flushInterval > 0) {
+      this.enqueueEvent(event);
+      return;
+    }
+
+    await this.sendPost({
+      requestType: "captureEvent",
+      data: event,
+    });
+  }
+
+  // ─── Feature Flags ───────────────────────────────────────────
+
+  async getFeatureFlag<K extends string & keyof TFeatureFlags>(
+    sessionId: string,
+    flagName: K
+  ): Promise<TFeatureFlags[K] | null> {
+    const result = await this.sendGet<{ value: TFeatureFlags[K] | null }>(
+      "getFeatureFlag",
+      { sessionId, flagName }
+    );
+    return result.value;
+  }
+
+  async getAllFeatureFlags(
+    sessionId: string
+  ): Promise<TFeatureFlags> {
+    return this.sendGet<TFeatureFlags>(
+      "getAllFeatureFlags",
+      { sessionId }
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+export { AnalyticsBackendClient } from "./backend-client";
+export type { HandlerOptions, MiddlewareResult } from "./backend-client";
+export { AnalyticsClient } from "./client";
+
+// Services (for advanced usage)
+export { EventService } from "./services/events";
+export { SessionService } from "./services/sessions";
+export { FeatureFlagService } from "./services/feature-flags";
+export { SchemaRegistry } from "./services/schema-registry";
+export { SearchIndexService } from "./services/search-index";
+export { LoggingService } from "./services/logging";
+
+// Types
+export type {
+  AnalyticsConfig,
+  CaptureEventInput,
+  ClientConfig,
+  DeepPartial,
+  EventData,
+  EventSchema,
+  FeatureFlagAssignment,
+  FeatureFlagConfig,
+  FeatureFlagDefinition,
+  FeatureFlagDefinitions,
+  LogType,
+  SchemaProperty,
+  SchemaPropertyType,
+  SearchIndexInfo,
+  SDKOptions,
+  ServerConfig,
+  Session,
+  SessionMetadata,
+  SessionResult,
+  StandardEventMap,
+  StandardEventName,
+  SystemLog,
+} from "./types";
+
+export type { AnalyticsRequest, AnalyticsResponse } from "./protocol";

package/src/protocol.ts

@@ -0,0 +1,57 @@
+// Protocol types for communication between frontend client and backend server.
+// These define the request/response contract for the single analytics endpoint.
+
+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;
+    };