@upstash/redis-analytics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Upstash, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @upstash/redis-analytics
+
+Unified analytics package for Upstash Redis. Provides both server-side (`AnalyticsBackendClient`) and browser-side (`AnalyticsClient`) functionality in a single package.
+
+## Purpose
+
+This package is the complete analytics solution. It provides:
+
+- Session management (creation, retrieval, validation)
+- Event tracking and capture (standard + custom events)
+- Feature flag management with A/B testing
+- Redis Search index management (blue-green deployment)
+- Custom event schema registry
+- System logging
+- Rate limiting
+- Browser-side client with event batching
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│           Applications              │
+│         (ui, app, user apps)        │
+└──────────────┬──────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────┐
+│     @upstash/redis-analytics        │
+│  AnalyticsBackendClient (server)    │
+│  AnalyticsClient (browser)          │
+└──────────────┬──────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────┐
+│     Upstash Redis + Redis Search    │
+└─────────────────────────────────────┘
+```
+
+## Package Structure
+
+```
+src/
+  index.ts                 # barrel exports
+  backend-client.ts        # AnalyticsBackendClient (server-side)
+  client.ts                # AnalyticsClient (browser-side)
+  types.ts                 # all shared types
+  protocol.ts              # request/response contract
+  utils.ts                 # helpers
+  services/
+    events.ts              # EventService
+    sessions.ts            # SessionService
+    feature-flags.ts       # FeatureFlagService
+    schema-registry.ts     # SchemaRegistry
+    search-index.ts        # SearchIndexService
+    logging.ts             # LoggingService
+```
+
+## Usage
+
+### Server-side (Next.js API route)
+
+```typescript
+import { AnalyticsBackendClient } from "@upstash/redis-analytics";
+
+const client = new AnalyticsBackendClient({
+  redis: {
+    url: process.env.UPSTASH_REDIS_REST_URL!,
+    token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  },
+  config: {
+    // All config is optional — only override what you need
+    session: { expirationMs: 7200000 },
+    schemaValidation: { checkFrequency: 0.01 }, // validate ~1% of events to reduce costs
+  },
+});
+
+// Single endpoint handler for Next.js
+const handler = client.getHandler();
+export const POST = handler;
+export const GET = handler;
+
+// Or use namespaced services directly
+const session = await client.sessions.createSession();
+await client.events.capturePageView(session.id, "/home");
+const flags = await client.featureFlags.getDefinitions();
+const logs = await client.logs.getLogs({ limit: 50 });
+const info = await client.searchIndex.getInfo();
+const schemas = await client.schemas.getAllSchemas();
+```
+
+### Browser-side (React/Next.js)
+
+```typescript
+import { AnalyticsClient } from "@upstash/redis-analytics";
+
+const analytics = new AnalyticsClient({
+  endpoint: "/api/analytics",
+  flushInterval: 2000, // batch events, flush every 2s
+});
+
+const session = await analytics.createSession();
+await analytics.capturePageView(session.id, "/home");
+await analytics.captureClick(session.id, "signup-button");
+```
+
+### Middleware & Session Metadata
+
+Add middleware to `getHandler()` for authentication and to attach metadata to sessions.
+The 3rd generic parameter provides type safety for session metadata.
+
+```typescript
+import { AnalyticsBackendClient } from "@upstash/redis-analytics";
+
+type MyEvents = { "custom:purchase": { productId: string; amount: number } };
+type MyFlags = { theme: "light" | "dark" };
+type MySessionMetadata = { userId: string; plan: string };
+
+const client = new AnalyticsBackendClient<MyEvents, MyFlags, MySessionMetadata>({
+  redis: { url: "...", token: "..." },
+});
+
+const handler = client.getHandler({
+  middleware: async ({ request, analyticsRequest }) => {
+    const token = request.headers.get("authorization");
+    if (!token) {
+      return new Response(JSON.stringify({ success: false, error: "Unauthorized" }), { status: 401 });
+    }
+    const user = await verifyToken(token);
+    // Attach metadata to the session — stored in Redis, included in every event
+    return { sessionMetadata: { userId: user.id, plan: user.plan } };
+  },
+});
+
+export const POST = handler;
+export const GET = handler;
+```
+
+Session metadata is automatically:
+- Stored with the session in Redis
+- Included in every captured event under `sessionMetadata`
+- Registered in the schema registry for search index queryability
+
+### Type Safety
+
+```typescript
+import { AnalyticsBackendClient, AnalyticsClient } from "@upstash/redis-analytics";
+
+type MyEvents = {
+  "custom:purchase": { productId: string; amount: number };
+};
+
+type MyFlags = {
+  theme: "light" | "dark";
+};
+
+type MySessionMetadata = {
+  userId: string;
+  plan: string;
+};
+
+// Backend accepts 3 generic parameters: events, flags, session metadata
+const backend = new AnalyticsBackendClient<MyEvents, MyFlags, MySessionMetadata>({ ... });
+
+// Frontend client accepts events and flags
+const frontend = new AnalyticsClient<MyEvents, MyFlags>({ ... });
+```
+
+## Dependencies
+
+- `@upstash/redis` - Redis client with Redis Search support
+- `@upstash/ratelimit` - Distributed rate limiting
+
+## Development
+
+This package is part of a monorepo using pnpm workspaces.

package/dist/backend-client.d.ts

@@ -0,0 +1,38 @@
+import type { ServerConfig } from "./types";
+import type { AnalyticsRequest } 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";
+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 declare 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;
+    private config;
+    constructor(serverConfig: ServerConfig);
+    getHandler(options?: HandlerOptions<TSessionMetadata>): (request: Request) => Promise<Response>;
+    private handleRequest;
+    private parseGetRequest;
+    private processRequest;
+}

package/dist/backend-client.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsBackendClient = void 0;
+const redis_1 = require("@upstash/redis");
+const logging_1 = require("./services/logging");
+const feature_flags_1 = require("./services/feature-flags");
+const sessions_1 = require("./services/sessions");
+const events_1 = require("./services/events");
+const schema_registry_1 = require("./services/schema-registry");
+const search_index_1 = require("./services/search-index");
+const DEFAULT_CONFIG = {
+    session: {
+        expirationMs: 3600000, // 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(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        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, sourceVal);
+        }
+        else {
+            result[key] = sourceVal;
+        }
+    }
+    return result;
+}
+class AnalyticsBackendClient {
+    constructor(serverConfig) {
+        this.redis = new redis_1.Redis({
+            url: serverConfig.redis.url,
+            token: serverConfig.redis.token,
+        });
+        this.config = deepMerge(DEFAULT_CONFIG, (serverConfig.config ?? {}));
+        this.logs = new logging_1.LoggingService(this.redis, this.config);
+        this.featureFlags = new feature_flags_1.FeatureFlagService(this.redis, this.config, this.logs);
+        this.sessions = new sessions_1.SessionService(this.redis, this.config, this.featureFlags, this.logs);
+        this.schemas = new schema_registry_1.SchemaRegistry(this.redis, this.config, this.logs);
+        this.searchIndex = new search_index_1.SearchIndexService(this.redis, this.config, this.schemas, this.featureFlags, this.logs);
+        this.events = new events_1.EventService(this.redis, this.config, this.schemas, this.logs);
+    }
+    // ─── Handler ──────────────────────────────────────────────────
+    getHandler(options) {
+        return (request) => this.handleRequest(request, options);
+    }
+    async handleRequest(request, options) {
+        try {
+            const method = request.method.toUpperCase();
+            let 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());
+            }
+            // Run middleware
+            let sessionMetadata;
+            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 = { success: false, error: message };
+            return new Response(JSON.stringify(result), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+    }
+    parseGetRequest(requestType, params) {
+        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}`);
+        }
+    }
+    async processRequest(req, sessionMetadata) {
+        switch (req.requestType) {
+            case "captureEvent": {
+                await this.events.captureEvent(req.data);
+                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,
+                    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.requestType}`,
+                };
+            }
+        }
+    }
+}
+exports.AnalyticsBackendClient = AnalyticsBackendClient;

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+import type { CaptureEventInput, ClientConfig, Session, SessionResult } from "./types";
+export declare class AnalyticsClient<TCustomEvents extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>, TFeatureFlags extends Record<string, string> = Record<string, string>> {
+    private endpoint;
+    private flushInterval;
+    private maxBatchSize;
+    private eventQueue;
+    private flushTimer;
+    constructor(config?: ClientConfig);
+    private sendPost;
+    private sendGet;
+    private enqueueEvent;
+    flush(): Promise<void>;
+    createSession(options?: {
+        featureFlags?: {
+            [K in keyof TFeatureFlags]?: TFeatureFlags[K] | Record<string, number>;
+        };
+    }): Promise<Session<TFeatureFlags>>;
+    getSession(sessionId: string): Promise<SessionResult<TFeatureFlags>>;
+    captureEvent(input: CaptureEventInput<TCustomEvents>): 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>;
+    getFeatureFlag<K extends string & keyof TFeatureFlags>(sessionId: string, flagName: K): Promise<TFeatureFlags[K] | null>;
+    getAllFeatureFlags(sessionId: string): Promise<TFeatureFlags>;
+}

package/dist/client.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsClient = void 0;
+class AnalyticsClient {
+    constructor(config) {
+        this.eventQueue = [];
+        this.flushTimer = null;
+        this.endpoint = config?.endpoint ?? "/api/analytics";
+        this.flushInterval = config?.flushInterval ?? 0;
+        this.maxBatchSize = config?.maxBatchSize ?? 20;
+    }
+    async sendPost(request) {
+        const response = await fetch(this.endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(request),
+        });
+        const result = await response.json();
+        if (!result.success) {
+            throw new Error(result.error ?? "Analytics request failed");
+        }
+        return result.data;
+    }
+    async sendGet(requestType, params) {
+        const searchParams = new URLSearchParams({ requestType, ...params });
+        const response = await fetch(`${this.endpoint}?${searchParams}`);
+        const result = await response.json();
+        if (!result.success) {
+            throw new Error(result.error ?? "Analytics request failed");
+        }
+        return result.data;
+    }
+    // ─── Batch Queue ─────────────────────────────────────────────
+    enqueueEvent(event) {
+        this.eventQueue.push(event);
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flush();
+        }, this.flushInterval);
+    }
+    async flush() {
+        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) {
+        return this.sendPost({
+            requestType: "createSession",
+            data: {
+                featureFlags: options?.featureFlags,
+            },
+        });
+    }
+    async getSession(sessionId) {
+        return this.sendGet("getSession", { sessionId });
+    }
+    // ─── Event Tracking ──────────────────────────────────────────
+    async captureEvent(input) {
+        const event = input;
+        if (this.flushInterval > 0) {
+            this.enqueueEvent(event);
+            return;
+        }
+        await this.sendPost({
+            requestType: "captureEvent",
+            data: event,
+        });
+    }
+    async capturePageView(sessionId, path) {
+        const event = { sessionId, eventName: "pageview", properties: { path } };
+        if (this.flushInterval > 0) {
+            this.enqueueEvent(event);
+            return;
+        }
+        await this.sendPost({
+            requestType: "captureEvent",
+            data: event,
+        });
+    }
+    async captureClick(sessionId, element) {
+        const event = { sessionId, eventName: "click", properties: { element } };
+        if (this.flushInterval > 0) {
+            this.enqueueEvent(event);
+            return;
+        }
+        await this.sendPost({
+            requestType: "captureEvent",
+            data: event,
+        });
+    }
+    async captureError(sessionId, message) {
+        const event = { sessionId, eventName: "error", properties: { message } };
+        if (this.flushInterval > 0) {
+            this.enqueueEvent(event);
+            return;
+        }
+        await this.sendPost({
+            requestType: "captureEvent",
+            data: event,
+        });
+    }
+    async captureWarning(sessionId, message) {
+        const event = { sessionId, eventName: "warning", properties: { message } };
+        if (this.flushInterval > 0) {
+            this.enqueueEvent(event);
+            return;
+        }
+        await this.sendPost({
+            requestType: "captureEvent",
+            data: event,
+        });
+    }
+    async captureInfo(sessionId, message) {
+        const event = { sessionId, eventName: "info", properties: { message } };
+        if (this.flushInterval > 0) {
+            this.enqueueEvent(event);
+            return;
+        }
+        await this.sendPost({
+            requestType: "captureEvent",
+            data: event,
+        });
+    }
+    // ─── Feature Flags ───────────────────────────────────────────
+    async getFeatureFlag(sessionId, flagName) {
+        const result = await this.sendGet("getFeatureFlag", { sessionId, flagName });
+        return result.value;
+    }
+    async getAllFeatureFlags(sessionId) {
+        return this.sendGet("getAllFeatureFlags", { sessionId });
+    }
+}
+exports.AnalyticsClient = AnalyticsClient;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { AnalyticsBackendClient } from "./backend-client";
+export type { HandlerOptions, MiddlewareResult } from "./backend-client";
+export { AnalyticsClient } from "./client";
+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";
+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/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoggingService = exports.SearchIndexService = exports.SchemaRegistry = exports.FeatureFlagService = exports.SessionService = exports.EventService = exports.AnalyticsClient = exports.AnalyticsBackendClient = void 0;
+var backend_client_1 = require("./backend-client");
+Object.defineProperty(exports, "AnalyticsBackendClient", { enumerable: true, get: function () { return backend_client_1.AnalyticsBackendClient; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "AnalyticsClient", { enumerable: true, get: function () { return client_1.AnalyticsClient; } });
+// Services (for advanced usage)
+var events_1 = require("./services/events");
+Object.defineProperty(exports, "EventService", { enumerable: true, get: function () { return events_1.EventService; } });
+var sessions_1 = require("./services/sessions");
+Object.defineProperty(exports, "SessionService", { enumerable: true, get: function () { return sessions_1.SessionService; } });
+var feature_flags_1 = require("./services/feature-flags");
+Object.defineProperty(exports, "FeatureFlagService", { enumerable: true, get: function () { return feature_flags_1.FeatureFlagService; } });
+var schema_registry_1 = require("./services/schema-registry");
+Object.defineProperty(exports, "SchemaRegistry", { enumerable: true, get: function () { return schema_registry_1.SchemaRegistry; } });
+var search_index_1 = require("./services/search-index");
+Object.defineProperty(exports, "SearchIndexService", { enumerable: true, get: function () { return search_index_1.SearchIndexService; } });
+var logging_1 = require("./services/logging");
+Object.defineProperty(exports, "LoggingService", { enumerable: true, get: function () { return logging_1.LoggingService; } });