@mulingai-npm/redis 3.40.48 → 3.40.50

package/dist/managers/mulingstream-listener-manager.d.ts

@@ -52,6 +52,36 @@ export declare class MulingstreamListenerManager {
      */
     getReceivingCount(roomId: string): Promise<number>;
     private capKey;
+    private previewKey;
+    private previewCountKey;
+    /** Open a preview window on one language. Re-pressing simply extends it. */
+    openPreview(roomId: string, language: string, windowSeconds: number): Promise<void>;
+    /** Seconds left on a language's preview window, or 0 when none is open. */
+    getPreviewRemaining(roomId: string, language: string): Promise<number>;
+    /**
+     * Which of `candidates` currently have a preview open.
+     *
+     * Takes the candidate list rather than scanning for a pattern on purpose:
+     * KEYS and SCAN against a live Redis to answer a question asked on every
+     * audio chunk is the kind of thing that is fine until it is not.
+     */
+    getPreviewLanguages(roomId: string, candidates: string[]): Promise<string[]>;
+    /**
+     * Count one press against the room's allowance and say whether it is allowed.
+     *
+     * The cap exists because a preview translates for real. Without it, holding
+     * the button open is a way to run a translation service for nothing, and the
+     * obvious abuse is someone using a speaker preview as a free manual
+     * translation tool. The counter's own TTL resets the allowance, so a church
+     * running a genuine service every week is never permanently locked out.
+     */
+    consumePreviewAllowance(roomId: string, maxPresses: number, resetSeconds: number): Promise<{
+        allowed: boolean;
+        used: number;
+        remaining: number;
+    }>;
+    /** Presses already spent in the current window. Read only, never increments. */
+    getPreviewUsage(roomId: string): Promise<number>;
     /**
      * Cache the room's listener cap. Called by the speaker service at go-live and
      * on reconnect; `ttlSeconds` should comfortably exceed a session so the key

package/dist/managers/mulingstream-listener-manager.js

@@ -268,6 +268,82 @@ class MulingstreamListenerManager {
     capKey(roomId) {
         return `room:${roomId}:listener-cap`;
     }
+    /*
+     * SPEAKER PREVIEW
+     *
+     * A speaker looking at their own translation feed is a consumer of
+     * translation but must never be a payer for it: nobody should be able to
+     * spend a church's pass, or their own credits, by watching their own screen.
+     * So a preview is a short window they open deliberately, not a state they
+     * fall into by leaving a tab open.
+     *
+     * In Redis rather than in the pipeline's memory because the request arrives
+     * at the room service and the decision is read by the pipeline service, and
+     * because a pipeline replica restarting mid window must not silently start
+     * translating for nobody. The TTL IS the expiry: nothing has to remember to
+     * close it, and a crash fails in the safe direction.
+     */
+    previewKey(roomId, language) {
+        return `room:${roomId}:preview:${language}`;
+    }
+    previewCountKey(roomId) {
+        return `room:${roomId}:preview-count`;
+    }
+    /** Open a preview window on one language. Re-pressing simply extends it. */
+    async openPreview(roomId, language, windowSeconds) {
+        if (!roomId || !language || windowSeconds <= 0)
+            return;
+        const key = this.previewKey(roomId, language);
+        await this.redisClient.set(key, '1');
+        await this.redisClient.expire(key, Math.floor(windowSeconds));
+    }
+    /** Seconds left on a language's preview window, or 0 when none is open. */
+    async getPreviewRemaining(roomId, language) {
+        const ttl = await this.redisClient.ttl(this.previewKey(roomId, language));
+        return ttl > 0 ? ttl : 0;
+    }
+    /**
+     * Which of `candidates` currently have a preview open.
+     *
+     * Takes the candidate list rather than scanning for a pattern on purpose:
+     * KEYS and SCAN against a live Redis to answer a question asked on every
+     * audio chunk is the kind of thing that is fine until it is not.
+     */
+    async getPreviewLanguages(roomId, candidates) {
+        if (!roomId || candidates.length === 0)
+            return [];
+        const open = [];
+        for (const language of candidates) {
+            if (await this.redisClient.get(this.previewKey(roomId, language)))
+                open.push(language);
+        }
+        return open;
+    }
+    /**
+     * Count one press against the room's allowance and say whether it is allowed.
+     *
+     * The cap exists because a preview translates for real. Without it, holding
+     * the button open is a way to run a translation service for nothing, and the
+     * obvious abuse is someone using a speaker preview as a free manual
+     * translation tool. The counter's own TTL resets the allowance, so a church
+     * running a genuine service every week is never permanently locked out.
+     */
+    async consumePreviewAllowance(roomId, maxPresses, resetSeconds) {
+        const key = this.previewCountKey(roomId);
+        const used = await this.redisClient.incr(key);
+        // Only the first press starts the clock, so the window is a fixed period
+        // from first use rather than one that slides forward on every press.
+        if (used === 1)
+            await this.redisClient.expire(key, Math.floor(resetSeconds));
+        const allowed = used <= maxPresses;
+        return { allowed, used, remaining: Math.max(0, maxPresses - used) };
+    }
+    /** Presses already spent in the current window. Read only, never increments. */
+    async getPreviewUsage(roomId) {
+        const raw = await this.redisClient.get(this.previewCountKey(roomId));
+        const used = raw ? parseInt(raw, 10) : 0;
+        return Number.isFinite(used) && used > 0 ? used : 0;
+    }
     /**
      * Cache the room's listener cap. Called by the speaker service at go-live and
      * on reconnect; `ttlSeconds` should comfortably exceed a session so the key

package/package.json

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