@mulingai-npm/redis 3.30.0 → 3.30.2

package/dist/managers/credit-session-manager.d.ts

@@ -0,0 +1,112 @@
+import { RedisClient } from '../redis-client';
+/**
+ * Credit session data stored in Redis during streaming
+ */
+export interface CreditSessionData {
+    sessionId: string;
+    userId: string;
+    roomId: number;
+    serviceCode: string;
+    sourceLanguage: string;
+    targetLanguages: string[];
+    keywordsEnabled: boolean;
+    speculativeEnabled: boolean;
+    creditsPerMinute: number;
+    initialBalance: number;
+    creditsUsed: number;
+    totalDurationMs: number;
+    multiplierExtraLanguage: number;
+    multiplierKeywords: number;
+    multiplierSpeculative: number;
+    sessionStart: number;
+    lastUpdated: number;
+}
+/**
+ * Credit Session Manager
+ *
+ * Tracks credit usage during streaming sessions in Redis (USAGE_DATA db).
+ * Similar to UsageDataManager but tracks credits instead of milliseconds.
+ *
+ * Key structure:
+ * - credit:session:{sessionId} - Hash with session credit data
+ * - credit:session:user:{userId} - String with current sessionId (for lookup)
+ * - credit:pending:users - Set of user IDs with active credit sessions
+ *
+ * Flow:
+ * 1. Session starts: credit-service creates session in Redis
+ * 2. Every 5 seconds: pipeline-service increments creditsUsed
+ * 3. Session ends: credit-service flushes to DB, clears Redis
+ *
+ * Crash recovery:
+ * - If session not closed properly, orphan cleanup job will flush to DB
+ * - TTL: 24 hours (safety net)
+ *
+ * @example
+ * ```typescript
+ * const manager = new CreditSessionManager(UsageDataRedisClient);
+ * await manager.startSession(sessionData);
+ * await manager.recordUsage(sessionId, creditsDelta, durationDeltaMs);
+ * const session = await manager.getSession(sessionId);
+ * await manager.endSession(sessionId);
+ * ```
+ */
+export declare class CreditSessionManager {
+    private redisClient;
+    private readonly EXPIRATION;
+    constructor(redisClient: RedisClient);
+    /**
+     * Key for a session's credit data
+     */
+    private sessionKey;
+    /**
+     * Key to look up user's current session
+     */
+    private userSessionKey;
+    /**
+     * Key for the set of users with active credit sessions
+     */
+    private pendingUsersKey;
+    /**
+     * Start a new credit session
+     */
+    startSession(data: Omit<CreditSessionData, 'creditsUsed' | 'totalDurationMs' | 'lastUpdated'>): Promise<void>;
+    /**
+     * Record credit usage during a session
+     * Called by pipeline-service every 5 seconds
+     */
+    recordUsage(sessionId: string, creditsDelta: number, durationDeltaMs: number): Promise<{
+        success: boolean;
+        creditsUsed: number;
+        totalDurationMs: number;
+    }>;
+    /**
+     * Get session data
+     */
+    getSession(sessionId: string): Promise<CreditSessionData | null>;
+    /**
+     * Get session by user ID
+     */
+    getSessionByUserId(userId: string): Promise<CreditSessionData | null>;
+    /**
+     * End a session and get final data (for DB flush)
+     */
+    endSession(sessionId: string): Promise<CreditSessionData | null>;
+    /**
+     * Get all users with active credit sessions (for orphan cleanup)
+     */
+    getUsersWithActiveSessions(): Promise<string[]>;
+    /**
+     * Get all stale sessions (lastUpdated > staleThresholdMs ago)
+     * Used by orphan cleanup job
+     */
+    getStaleSessions(staleThresholdMs: number): Promise<CreditSessionData[]>;
+    /**
+     * Check remaining credits for a session
+     */
+    checkBalance(sessionId: string): Promise<{
+        creditsUsed: number;
+        creditsRemaining: number;
+        limitReached: boolean;
+        lowBalance: boolean;
+    } | null>;
+}

package/dist/managers/credit-session-manager.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreditSessionManager = void 0;
+/**
+ * Credit Session Manager
+ *
+ * Tracks credit usage during streaming sessions in Redis (USAGE_DATA db).
+ * Similar to UsageDataManager but tracks credits instead of milliseconds.
+ *
+ * Key structure:
+ * - credit:session:{sessionId} - Hash with session credit data
+ * - credit:session:user:{userId} - String with current sessionId (for lookup)
+ * - credit:pending:users - Set of user IDs with active credit sessions
+ *
+ * Flow:
+ * 1. Session starts: credit-service creates session in Redis
+ * 2. Every 5 seconds: pipeline-service increments creditsUsed
+ * 3. Session ends: credit-service flushes to DB, clears Redis
+ *
+ * Crash recovery:
+ * - If session not closed properly, orphan cleanup job will flush to DB
+ * - TTL: 24 hours (safety net)
+ *
+ * @example
+ * ```typescript
+ * const manager = new CreditSessionManager(UsageDataRedisClient);
+ * await manager.startSession(sessionData);
+ * await manager.recordUsage(sessionId, creditsDelta, durationDeltaMs);
+ * const session = await manager.getSession(sessionId);
+ * await manager.endSession(sessionId);
+ * ```
+ */
+class CreditSessionManager {
+    constructor(redisClient) {
+        this.EXPIRATION = 24 * 60 * 60; // 24 hours TTL
+        this.redisClient = redisClient;
+    }
+    /**
+     * Key for a session's credit data
+     */
+    sessionKey(sessionId) {
+        return `credit:session:${sessionId}`;
+    }
+    /**
+     * Key to look up user's current session
+     */
+    userSessionKey(userId) {
+        return `credit:session:user:${userId}`;
+    }
+    /**
+     * Key for the set of users with active credit sessions
+     */
+    pendingUsersKey() {
+        return 'credit:pending:users';
+    }
+    /**
+     * Start a new credit session
+     */
+    async startSession(data) {
+        const sessionKey = this.sessionKey(data.sessionId);
+        const userSessionKey = this.userSessionKey(data.userId);
+        await this.redisClient.hset(sessionKey, {
+            sessionId: data.sessionId,
+            userId: data.userId,
+            roomId: data.roomId.toString(),
+            serviceCode: data.serviceCode,
+            sourceLanguage: data.sourceLanguage,
+            targetLanguages: JSON.stringify(data.targetLanguages),
+            keywordsEnabled: data.keywordsEnabled ? '1' : '0',
+            speculativeEnabled: data.speculativeEnabled ? '1' : '0',
+            creditsPerMinute: data.creditsPerMinute.toString(),
+            initialBalance: data.initialBalance.toString(),
+            creditsUsed: '0',
+            totalDurationMs: '0',
+            multiplierExtraLanguage: data.multiplierExtraLanguage.toString(),
+            multiplierKeywords: data.multiplierKeywords.toString(),
+            multiplierSpeculative: data.multiplierSpeculative.toString(),
+            sessionStart: data.sessionStart.toString(),
+            lastUpdated: Date.now().toString()
+        });
+        await this.redisClient.expire(sessionKey, this.EXPIRATION);
+        // Store user's current session ID for lookup
+        await this.redisClient.set(userSessionKey, data.sessionId);
+        await this.redisClient.expire(userSessionKey, this.EXPIRATION);
+        // Add user to the set of users with active sessions
+        await this.redisClient.sadd(this.pendingUsersKey(), data.userId);
+        await this.redisClient.expire(this.pendingUsersKey(), this.EXPIRATION);
+    }
+    /**
+     * Record credit usage during a session
+     * Called by pipeline-service every 5 seconds
+     */
+    async recordUsage(sessionId, creditsDelta, durationDeltaMs) {
+        const sessionKey = this.sessionKey(sessionId);
+        // Check if session exists
+        const exists = await this.redisClient.exists(sessionKey);
+        if (exists !== 1) {
+            return { success: false, creditsUsed: 0, totalDurationMs: 0 };
+        }
+        // Increment credits used
+        await this.redisClient.hincrbyfloat(sessionKey, 'creditsUsed', creditsDelta);
+        // Increment duration
+        await this.redisClient.hincrby(sessionKey, 'totalDurationMs', durationDeltaMs);
+        // Update timestamp
+        await this.redisClient.hset(sessionKey, { lastUpdated: Date.now().toString() });
+        // Refresh TTL
+        await this.redisClient.expire(sessionKey, this.EXPIRATION);
+        // Get updated values
+        const data = await this.redisClient.hgetall(sessionKey);
+        return {
+            success: true,
+            creditsUsed: parseFloat((data === null || data === void 0 ? void 0 : data.creditsUsed) || '0'),
+            totalDurationMs: parseInt((data === null || data === void 0 ? void 0 : data.totalDurationMs) || '0', 10)
+        };
+    }
+    /**
+     * Get session data
+     */
+    async getSession(sessionId) {
+        const sessionKey = this.sessionKey(sessionId);
+        const data = await this.redisClient.hgetall(sessionKey);
+        if (!data || Object.keys(data).length === 0) {
+            return null;
+        }
+        return {
+            sessionId: data.sessionId,
+            userId: data.userId,
+            roomId: parseInt(data.roomId, 10),
+            serviceCode: data.serviceCode,
+            sourceLanguage: data.sourceLanguage,
+            targetLanguages: JSON.parse(data.targetLanguages || '[]'),
+            keywordsEnabled: data.keywordsEnabled === '1',
+            speculativeEnabled: data.speculativeEnabled === '1',
+            creditsPerMinute: parseFloat(data.creditsPerMinute || '0'),
+            initialBalance: parseFloat(data.initialBalance || '0'),
+            creditsUsed: parseFloat(data.creditsUsed || '0'),
+            totalDurationMs: parseInt(data.totalDurationMs || '0', 10),
+            multiplierExtraLanguage: parseFloat(data.multiplierExtraLanguage || '1'),
+            multiplierKeywords: parseFloat(data.multiplierKeywords || '1'),
+            multiplierSpeculative: parseFloat(data.multiplierSpeculative || '1'),
+            sessionStart: parseInt(data.sessionStart || '0', 10),
+            lastUpdated: parseInt(data.lastUpdated || '0', 10)
+        };
+    }
+    /**
+     * Get session by user ID
+     */
+    async getSessionByUserId(userId) {
+        const userSessionKey = this.userSessionKey(userId);
+        const sessionId = await this.redisClient.get(userSessionKey);
+        if (!sessionId) {
+            return null;
+        }
+        return this.getSession(sessionId);
+    }
+    /**
+     * End a session and get final data (for DB flush)
+     */
+    async endSession(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (session) {
+            const sessionKey = this.sessionKey(sessionId);
+            const userSessionKey = this.userSessionKey(session.userId);
+            await this.redisClient.del(sessionKey);
+            await this.redisClient.del(userSessionKey);
+            await this.redisClient.srem(this.pendingUsersKey(), session.userId);
+        }
+        return session;
+    }
+    /**
+     * Get all users with active credit sessions (for orphan cleanup)
+     */
+    async getUsersWithActiveSessions() {
+        const members = await this.redisClient.smembers(this.pendingUsersKey());
+        return members || [];
+    }
+    /**
+     * Get all stale sessions (lastUpdated > staleThresholdMs ago)
+     * Used by orphan cleanup job
+     */
+    async getStaleSessions(staleThresholdMs) {
+        const now = Date.now();
+        const userIds = await this.getUsersWithActiveSessions();
+        const staleSessions = [];
+        for (const userId of userIds) {
+            const session = await this.getSessionByUserId(userId);
+            if (session && (now - session.lastUpdated) > staleThresholdMs) {
+                staleSessions.push(session);
+            }
+        }
+        return staleSessions;
+    }
+    /**
+     * Check remaining credits for a session
+     */
+    async checkBalance(sessionId) {
+        const session = await this.getSession(sessionId);
+        if (!session) {
+            return null;
+        }
+        const creditsRemaining = session.initialBalance - session.creditsUsed;
+        const percentUsed = session.creditsUsed / session.initialBalance;
+        return {
+            creditsUsed: session.creditsUsed,
+            creditsRemaining: Math.max(0, creditsRemaining),
+            limitReached: creditsRemaining <= 0,
+            lowBalance: percentUsed >= 0.75
+        };
+    }
+}
+exports.CreditSessionManager = CreditSessionManager;

package/dist/managers/plan-entitlements-manager.d.ts

@@ -0,0 +1,66 @@
+import { RedisClient } from '../redis-client';
+/**
+ * Plan multipliers cached in Redis
+ */
+export interface CachedPlanMultipliers {
+    userId: string;
+    planId: string | null;
+    multiplierExtraLanguage: number;
+    multiplierKeywords: number;
+    multiplierSpeculative: number;
+    featureKeywords: boolean;
+    featureSpeculative: boolean;
+    quotaCredits: number;
+    cachedAt: number;
+}
+/**
+ * Plan Entitlements Manager
+ *
+ * Caches user plan multipliers in Redis (USAGE_DATA db) for fast access
+ * during streaming sessions. Avoids repeated DB queries for plan entitlements.
+ *
+ * Key structure:
+ * - plan:multipliers:{userId} - Hash with all multiplier values
+ *
+ * Cache invalidation:
+ * - On plan change: billing-service publishes event → credit-service clears cache
+ * - TTL: 24 hours (safety net if event missed)
+ *
+ * @example
+ * ```typescript
+ * const manager = new PlanEntitlementsManager(UsageDataRedisClient);
+ * await manager.setMultipliers(userId, multipliers);
+ * const cached = await manager.getMultipliers(userId);
+ * await manager.clearMultipliers(userId); // On plan change
+ * ```
+ */
+export declare class PlanEntitlementsManager {
+    private redisClient;
+    private readonly EXPIRATION;
+    constructor(redisClient: RedisClient);
+    /**
+     * Key for a user's plan multipliers
+     */
+    private userKey;
+    /**
+     * Cache plan multipliers for a user
+     */
+    setMultipliers(userId: string, data: Omit<CachedPlanMultipliers, 'userId' | 'cachedAt'>): Promise<void>;
+    /**
+     * Get cached plan multipliers for a user
+     * Returns null if not cached (caller should fetch from DB and cache)
+     */
+    getMultipliers(userId: string): Promise<CachedPlanMultipliers | null>;
+    /**
+     * Clear cached multipliers for a user (call on plan change)
+     */
+    clearMultipliers(userId: string): Promise<void>;
+    /**
+     * Check if user has cached multipliers
+     */
+    hasMultipliers(userId: string): Promise<boolean>;
+    /**
+     * Refresh TTL for a user's cached multipliers (call during active session)
+     */
+    refreshTTL(userId: string): Promise<void>;
+}

package/dist/managers/plan-entitlements-manager.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlanEntitlementsManager = void 0;
+/**
+ * Plan Entitlements Manager
+ *
+ * Caches user plan multipliers in Redis (USAGE_DATA db) for fast access
+ * during streaming sessions. Avoids repeated DB queries for plan entitlements.
+ *
+ * Key structure:
+ * - plan:multipliers:{userId} - Hash with all multiplier values
+ *
+ * Cache invalidation:
+ * - On plan change: billing-service publishes event → credit-service clears cache
+ * - TTL: 24 hours (safety net if event missed)
+ *
+ * @example
+ * ```typescript
+ * const manager = new PlanEntitlementsManager(UsageDataRedisClient);
+ * await manager.setMultipliers(userId, multipliers);
+ * const cached = await manager.getMultipliers(userId);
+ * await manager.clearMultipliers(userId); // On plan change
+ * ```
+ */
+class PlanEntitlementsManager {
+    constructor(redisClient) {
+        this.EXPIRATION = 24 * 60 * 60; // 24 hours TTL (safety net)
+        this.redisClient = redisClient;
+    }
+    /**
+     * Key for a user's plan multipliers
+     */
+    userKey(userId) {
+        return `plan:multipliers:${userId}`;
+    }
+    /**
+     * Cache plan multipliers for a user
+     */
+    async setMultipliers(userId, data) {
+        const key = this.userKey(userId);
+        await this.redisClient.hset(key, {
+            planId: data.planId || '',
+            multiplierExtraLanguage: data.multiplierExtraLanguage.toString(),
+            multiplierKeywords: data.multiplierKeywords.toString(),
+            multiplierSpeculative: data.multiplierSpeculative.toString(),
+            featureKeywords: data.featureKeywords ? '1' : '0',
+            featureSpeculative: data.featureSpeculative ? '1' : '0',
+            quotaCredits: data.quotaCredits.toString(),
+            cachedAt: Date.now().toString()
+        });
+        await this.redisClient.expire(key, this.EXPIRATION);
+    }
+    /**
+     * Get cached plan multipliers for a user
+     * Returns null if not cached (caller should fetch from DB and cache)
+     */
+    async getMultipliers(userId) {
+        const key = this.userKey(userId);
+        const data = await this.redisClient.hgetall(key);
+        if (!data || Object.keys(data).length === 0) {
+            return null;
+        }
+        return {
+            userId,
+            planId: data.planId || null,
+            multiplierExtraLanguage: parseFloat(data.multiplierExtraLanguage || '1.0'),
+            multiplierKeywords: parseFloat(data.multiplierKeywords || '1.5'),
+            multiplierSpeculative: parseFloat(data.multiplierSpeculative || '1.4'),
+            featureKeywords: data.featureKeywords === '1',
+            featureSpeculative: data.featureSpeculative === '1',
+            quotaCredits: parseInt(data.quotaCredits || '60', 10),
+            cachedAt: parseInt(data.cachedAt || '0', 10)
+        };
+    }
+    /**
+     * Clear cached multipliers for a user (call on plan change)
+     */
+    async clearMultipliers(userId) {
+        const key = this.userKey(userId);
+        await this.redisClient.del(key);
+    }
+    /**
+     * Check if user has cached multipliers
+     */
+    async hasMultipliers(userId) {
+        const key = this.userKey(userId);
+        const exists = await this.redisClient.exists(key);
+        return exists === 1;
+    }
+    /**
+     * Refresh TTL for a user's cached multipliers (call during active session)
+     */
+    async refreshTTL(userId) {
+        const key = this.userKey(userId);
+        await this.redisClient.expire(key, this.EXPIRATION);
+    }
+}
+exports.PlanEntitlementsManager = PlanEntitlementsManager;

package/dist/redis-client.d.ts

@@ -20,6 +20,7 @@ export declare class RedisClient {
     hset(key: string, data: Record<string, string>): Promise<number>;
     hgetall(key: string): Promise<Record<string, string>>;
     hincrby(key: string, field: string, increment: number): Promise<number>;
+    hincrbyfloat(key: string, field: string, increment: number): Promise<string>;
     zadd(key: string, score: number, member: string): Promise<number>;
     zrange(key: string, start: number, stop: number): Promise<string[]>;
     zremrangebyrank(key: string, start: number, stop: number): Promise<number>;

package/dist/redis-client.js

@@ -55,6 +55,9 @@ class RedisClient {
     async hincrby(key, field, increment) {
         return this.client.hincrby(key, field, increment);
     }
+    async hincrbyfloat(key, field, increment) {
+        return this.client.hincrbyfloat(key, field, increment);
+    }
     async zadd(key, score, member) {
         return this.client.zadd(key, score, member);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mulingai-npm/redis",
-    "version": "3.30.0",
+    "version": "3.30.2",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "repository": {