vidspotai-shared 1.0.81 → 1.0.82

package/lib/services/rateLimiter/distributedRateLimiter.service.js

@@ -3,15 +3,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DistributedRateLimiter = void 0;
+exports.DistributedRateLimiter = exports.DAILY_NEAR_RESET_MS = exports.MAX_ACCEPTABLE_WAIT_MS = void 0;
 exports.getAiGenModelRateLimiter = getAiGenModelRateLimiter;
 exports.getTtsProviderRateLimiter = getTtsProviderRateLimiter;
 exports.snapshotAllRateLimiters = snapshotAllRateLimiters;
 const crypto_1 = __importDefault(require("crypto"));
 const aiModels_1 = require("../../globals/aiModels");
 const ttsModels_1 = require("../../globals/ttsModels");
+const googleApiKeys_1 = require("../aiGen/providers/google/googleApiKeys");
+const errors_1 = require("../../utils/errors");
 const logger_1 = require("../../utils/logger");
 const redis_service_1 = require("../redis.service");
+/**
+ * Capacity-planning thresholds (used by previewCapacity + the bounded gate).
+ *
+ * MAX_ACCEPTABLE_WAIT_MS — a model whose projected wait for a submit slot
+ *   exceeds this is considered "not available" by previewCapacity, so the
+ *   job-start selector spills to a less-loaded model in the same tier chain.
+ * DAILY_NEAR_RESET_MS — when a model's per-day cap is exhausted, we only wait
+ *   it out if the UTC-midnight reset is within this window; otherwise the
+ *   bounded gate fast-fails (VIDEO_PROVIDER_RATE_LIMITED) so the caller can
+ *   fall back rather than block for hours.
+ */
+exports.MAX_ACCEPTABLE_WAIT_MS = 180000; // 3 min
+exports.DAILY_NEAR_RESET_MS = 120000; // 2 min
 // Module-level throttle so Redis outages don't fire a Slack error every
 // request. First failure goes through; subsequent failures within the
 // window log at warn level (Console + Loki only) until the window resets.
@@ -62,9 +77,14 @@ end
 
 redis.call('ZADD', minKey, nowMs, uniqueId)
 redis.call('PEXPIRE', minKey, 90000)
-local newDay = redis.call('INCR', dayKey)
-if newDay == 1 then
-  redis.call('EXPIRE', dayKey, secsTilMidnight)
+-- Only touch the day counter when a day limit applies. With dayLimit <= 0
+-- (skipDay poll path, or a model with no per-day cap) we must NOT increment —
+-- otherwise polls would burn the daily SUBMIT budget they're meant to bypass.
+if dayLimit > 0 then
+  local newDay = redis.call('INCR', dayKey)
+  if newDay == 1 then
+    redis.call('EXPIRE', dayKey, secsTilMidnight)
+  end
 end
 
 return { 1, 0, 'ok' }
@@ -83,11 +103,18 @@ class DistributedRateLimiter {
      * a slot in each. Caller MUST call releaseSlot() when the in-flight task
      * settles — per-min / per-day auto-expire but the concurrent counter does
      * not. Mirrors the old AiGenModelRateLimiter API.
+     *
+     * `opts.maxWaitMs` bounds the rate-budget wait: if satisfying the per-day /
+     * per-minute gate would take longer than this, the call throws a
+     * `UserFacingError(VIDEO_PROVIDER_RATE_LIMITED)` instead of sleep-looping for
+     * hours. This is the backstop that stops jobs from piling up in-process when
+     * a daily cap is hit — the submit path passes it; legacy callers that omit
+     * it keep the original (unbounded) behavior.
      */
-    async waitUntilAvailable() {
+    async waitUntilAvailable(opts) {
         await this.acquireConcurrent();
         try {
-            await this.consumeRedisGates();
+            await this.consumeRedisGates({ maxWaitMs: opts?.maxWaitMs });
         }
         catch (err) {
             this.releaseConcurrent();
@@ -95,13 +122,99 @@ class DistributedRateLimiter {
         }
     }
     /**
-     * Bumps per-min + per-day only — does NOT count toward the concurrent cap.
-     * Use for short-lived calls that share a provider's rate budget but aren't
-     * "in-flight tasks" (status polls, sync image/TTS gens that complete in the
-     * same call). No release is needed — Redis auto-expires the counters.
+     * Bumps per-MINUTE only — does NOT count toward the concurrent cap and does
+     * NOT consume/await the per-day gate. Use for short-lived calls that share a
+     * provider's per-minute budget but must not be blocked by the daily SUBMIT
+     * cap: status polls of already-running tasks (failing a poll on daily quota
+     * would abandon a video that's already generating), plus sync image/TTS gens
+     * (which have no per-day limit configured anyway). No release needed — Redis
+     * auto-expires the counters.
      */
     async waitUntilAvailableForOneShot() {
-        await this.consumeRedisGates();
+        await this.consumeRedisGates({ skipDay: true });
+    }
+    /**
+     * Read-only capacity estimate — does NOT consume a slot. Reads current
+     * per-minute / per-day usage and concurrency pressure from Redis and
+     * projects how long a new submission would wait. Fails open (available:true,
+     * wait:0) on Redis errors / no client, matching the gate's fail-open policy.
+     */
+    async previewCapacity(maxAcceptableWaitMs = exports.MAX_ACCEPTABLE_WAIT_MS) {
+        const secsUntilDayReset = secsUntilMidnight();
+        const base = {
+            modelKey: this.modelKey,
+            perMinLimit: this.perMinLimit,
+            perDayLimit: this.perDayLimit,
+            concurrentLimit: this.concurrentLimit,
+            concurrentActive: this.activeRequests,
+            concurrentQueueDepth: this.waitQueue.length,
+            secsUntilDayReset,
+        };
+        const failOpen = {
+            ...base,
+            perMinUsed: 0,
+            perDayUsed: 0,
+            projectedWaitMs: 0,
+            available: true,
+            dailyExhausted: false,
+        };
+        const client = redis_service_1.redis.getClient();
+        if (!client)
+            return failOpen;
+        const minKey = `ratelimit:${this.modelKey}:min`;
+        const dayKey = `ratelimit:${this.modelKey}:day:${utcDateKey()}`;
+        let perMinUsed = 0;
+        let perDayUsed = 0;
+        try {
+            const now = Date.now();
+            const [minCount, dayRaw] = await Promise.all([
+                client.zcount(minKey, now - 60000, "+inf"),
+                client.get(dayKey),
+            ]);
+            perMinUsed = minCount;
+            perDayUsed = dayRaw ? Number(dayRaw) : 0;
+        }
+        catch (err) {
+            logger_1.logger.warn("distributedRateLimiter: previewCapacity read failed, assuming available", {
+                modelKey: this.modelKey,
+                err: err instanceof Error ? err.message : String(err),
+            });
+            return failOpen;
+        }
+        const dailyExhausted = this.perDayLimit > 0 && perDayUsed >= this.perDayLimit;
+        // Project the wait for a new submit slot.
+        let projectedWaitMs = 0;
+        if (dailyExhausted) {
+            projectedWaitMs = secsUntilDayReset * 1000;
+        }
+        else if (this.perMinLimit > 0) {
+            // Requests already queued on the concurrency gate are "ahead" of a new
+            // arrival competing for per-minute slots. Estimate how many 60s windows
+            // it takes to drain them past the per-minute throughput.
+            const pendingAhead = this.waitQueue.length;
+            const freeThisWindow = Math.max(0, this.perMinLimit - perMinUsed);
+            if (pendingAhead < freeThisWindow) {
+                projectedWaitMs = 0;
+            }
+            else {
+                const slotsNeeded = pendingAhead - freeThisWindow + 1;
+                const windowsNeeded = Math.ceil(slotsNeeded / this.perMinLimit);
+                projectedWaitMs = windowsNeeded * 60000;
+            }
+        }
+        // No per-minute gate (perMinLimit === 0): wait is concurrency-only; those
+        // models churn fast, so we treat backlog as drainable (projectedWaitMs 0).
+        const available = dailyExhausted
+            ? secsUntilDayReset * 1000 <= exports.DAILY_NEAR_RESET_MS
+            : projectedWaitMs <= maxAcceptableWaitMs;
+        return {
+            ...base,
+            perMinUsed,
+            perDayUsed,
+            projectedWaitMs,
+            available,
+            dailyExhausted,
+        };
     }
     /** Free a concurrent slot acquired via waitUntilAvailable(). */
     releaseSlot() {
@@ -165,8 +278,11 @@ class DistributedRateLimiter {
         if (next)
             next();
     }
-    async consumeRedisGates() {
-        if (!this.perMinLimit && !this.perDayLimit)
+    async consumeRedisGates(opts) {
+        // skipDay ignores the per-day cap entirely (poll path) — see
+        // waitUntilAvailableForOneShot.
+        const effectiveDayLimit = opts?.skipDay ? 0 : this.perDayLimit;
+        if (!this.perMinLimit && !effectiveDayLimit)
             return;
         const client = redis_service_1.redis.getClient();
         if (!client) {
@@ -179,6 +295,8 @@ class DistributedRateLimiter {
         const minKey = `ratelimit:${this.modelKey}:min`;
         const secsTilMidnight = secsUntilMidnight();
         const uniqueId = `${Date.now()}-${crypto_1.default.randomBytes(4).toString("hex")}`;
+        const startedAt = Date.now();
+        const maxWaitMs = opts?.maxWaitMs;
         while (true) {
             const nowMs = Date.now();
             // Day key resolved per-iteration so a retry across midnight UTC
@@ -186,7 +304,7 @@ class DistributedRateLimiter {
             const dayKey = `ratelimit:${this.modelKey}:day:${utcDateKey()}`;
             let result;
             try {
-                result = (await client.eval(CONSUME_SCRIPT, 2, minKey, dayKey, String(nowMs), String(this.perMinLimit), String(this.perDayLimit), String(secsTilMidnight), uniqueId));
+                result = (await client.eval(CONSUME_SCRIPT, 2, minKey, dayKey, String(nowMs), String(this.perMinLimit), String(effectiveDayLimit), String(secsTilMidnight), uniqueId));
             }
             catch (err) {
                 // Redis blip — fail open rather than blocking the pipeline. Throttle
@@ -210,6 +328,43 @@ class DistributedRateLimiter {
             }
             if (result[0] === 1)
                 return;
+            // Bounded-wait backstop. Without it, a per-day-exhausted gate sleep-loops
+            // (60s cap per iteration) until UTC midnight — jobs pile up in-process,
+            // hold a worker + concurrency slot, and block graceful shutdown. When the
+            // caller passes maxWaitMs, fast-fail instead so the scene can fall back to
+            // another model (or surface a clean rate-limit error).
+            if (maxWaitMs != null) {
+                const reason = result[2];
+                // A 'day' block's TRUE wait is until midnight (result[1] is 60s-capped
+                // for sleep granularity, not the real ETA) — decide against the real ETA.
+                const trueWaitMs = reason === "day" ? secsTilMidnight * 1000 : Date.now() - startedAt + result[1];
+                if (trueWaitMs > maxWaitMs) {
+                    // This is the terminal case: no fallback model had headroom either, so
+                    // the scene fails with a clean rate-limit error. logger.error → Slack
+                    // (error-only transport). Model + provider + cause live in the MESSAGE
+                    // because the Slack dedup key is the message's first 80 chars — so each
+                    // model fails its own alert (deduped to ~1/5min) and `day` vs `min`
+                    // causes don't collapse into each other. This + the spill alert are
+                    // the only signals Ammar gets that a provider is chronically over
+                    // quota and needs more capacity. Provider-agnostic (every model + TTS).
+                    const provider = this.modelKey.startsWith("tts:")
+                        ? this.modelKey.slice(4)
+                        : this.modelKey.split("-")[0];
+                    logger_1.logger.error(`distributedRateLimiter: ${this.modelKey} hard rate-limit ${reason === "day" ? "daily-cap" : "throughput"} fail (provider ${provider})`, {
+                        modelKey: this.modelKey,
+                        provider,
+                        cause: reason,
+                        trueWaitMs,
+                        maxWaitMs,
+                        perMinLimit: this.perMinLimit,
+                        perDayLimit: this.perDayLimit,
+                        secsUntilDayReset: secsTilMidnight,
+                    });
+                    throw new errors_1.UserFacingError(reason === "day"
+                        ? "This model has reached its daily generation limit."
+                        : "This model is at capacity right now. Please try again shortly.", errors_1.USER_FACING_ERROR_CODES.VIDEO_PROVIDER_RATE_LIMITED);
+                }
+            }
             const waitMs = Math.max(50, Math.min(1000, result[1]));
             await sleep(waitMs);
         }
@@ -237,10 +392,23 @@ function getAiGenModelRateLimiter(modelKey) {
         if (!config) {
             throw new Error(`No model config for model key: ${modelKey}`);
         }
+        // Google model configs hold the SINGLE-KEY Tier-2 baseline. With a
+        // multi-key pool (separate GCP projects/billing accounts, see
+        // googleKeyPool), the real aggregate budget is the SUM of each key's
+        // tier-scaled budget — so scale the model-level gate up to match, else it
+        // would throttle at one key's worth while the pool has more headroom.
+        // Single/legacy key → factor 1 (unchanged).
+        const isGoogle = modelKey.startsWith("google-");
+        const rpmFactor = isGoogle ? (0, googleApiKeys_1.googleAggregateFactor)("rpm") : 1;
+        const rpdFactor = isGoogle ? (0, googleApiKeys_1.googleAggregateFactor)("rpd") : 1;
         aiModelLimiters[modelKey] = new DistributedRateLimiter(modelKey, {
             concurrentRequests: config.concurrentRequests,
-            requestPerMin: config.requestPerMin,
-            requestPerDay: config.requestPerDay,
+            requestPerMin: config.requestPerMin
+                ? Math.round(config.requestPerMin * rpmFactor)
+                : config.requestPerMin,
+            requestPerDay: config.requestPerDay
+                ? Math.round(config.requestPerDay * rpdFactor)
+                : config.requestPerDay,
         });
     }
     return aiModelLimiters[modelKey];

package/lib/services/translation/index.d.ts

@@ -0,0 +1,2 @@
+export { translationService } from "./translation.service";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/translation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/translation/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/lib/services/translation/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translationService = void 0;
+// Only the new API is exported from the services barrel. The legacy aliases
+// (getTranslationWrapper / detectLang / TRANSLATION_FAILED) are re-exported via
+// utils/helpers instead, so each name reaches the package root through exactly
+// one star-export path (no ambiguous duplicate re-export).
+var translation_service_1 = require("./translation.service");
+Object.defineProperty(exports, "translationService", { enumerable: true, get: function () { return translation_service_1.translationService; } });

package/lib/services/translation/translation.service.d.ts

@@ -0,0 +1,50 @@
+import { ELANGUAGE_CODE, IDetectLang } from "../../globals/types";
+/**
+ * Translation service — single abstraction over language detection + translation.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Translation used to be a bare axios call to a custom Cloud Function
+ * (`translation-service-3931b`). That endpoint times out constantly
+ * (`timeout of 8000ms exceeded`, ~24s of retries), and every exhaustion threw
+ * `TRANSLATION_FAILED` — which broke /v1/video and /v1/text prompt generation
+ * AND flooded Slack with `error`-level alerts.
+ *
+ * Now there are TWO layers behind one interface:
+ *   1. PRIMARY  — the existing Cloud Function (free; just flaky).
+ *   2. FALLBACK — a cheap, reliable LLM (gpt-4o-mini) via our own provider
+ *      factory. It is NOT on the Google quota that the video pipeline competes
+ *      for, costs a fraction of a cent per short prompt, and is a single API we
+ *      already operate.
+ *
+ * A primary timeout that the LLM recovers from logs at WARN (Console + Loki, no
+ * Slack) — so the common flaky-primary case no longer floods the channel. Only
+ * when BOTH layers fail do we log ERROR (→ Slack) and throw, so the alert that
+ * survives is a real, rare outage rather than noise.
+ *
+ * Callers should use `translationService.translate()` / `.detectLanguage()`.
+ * The legacy `getTranslationWrapper` / `detectLang` names are kept as thin
+ * aliases (re-exported from utils/helpers) so existing callsites keep working.
+ */
+export declare const TRANSLATION_FAILED = "TRANSLATION_FAILED";
+/**
+ * Translate `text` from → to (default English). Primary CF first (with a couple
+ * of quick retries), then a cheap LLM. Throws Error(TRANSLATION_FAILED) only if
+ * BOTH layers fail; `.cause` carries the last error.
+ */
+declare function translate(text: string, from: ELANGUAGE_CODE, to?: ELANGUAGE_CODE, version?: "v1" | "v2"): Promise<string>;
+/**
+ * Detect the language of `text`. Primary CF; on failure fails OPEN to English
+ * (matches prior behavior — language detection must never block generation).
+ */
+declare function detectLanguage(text: string): Promise<IDetectLang>;
+export declare const translationService: {
+    translate: typeof translate;
+    detectLanguage: typeof detectLanguage;
+};
+/** @deprecated use `translationService.translate` */
+export declare const getTranslationWrapper: typeof translate;
+/** @deprecated use `translationService.detectLanguage` */
+export declare const detectLang: typeof detectLanguage;
+export {};
+//# sourceMappingURL=translation.service.d.ts.map

package/lib/services/translation/translation.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation.service.d.ts","sourceRoot":"","sources":["../../../src/services/translation/translation.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AA+EvD;;;;GAIG;AACH,iBAAe,SAAS,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,cAAc,EACpB,EAAE,GAAE,cAAkC,EACtC,OAAO,GAAE,IAAI,GAAG,IAAW,GAC1B,OAAO,CAAC,MAAM,CAAC,CAsCjB;AAED;;;GAGG;AACH,iBAAe,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAwBhE;AAOD,eAAO,MAAM,kBAAkB;;;CAG9B,CAAC;AAGF,qDAAqD;AACrD,eAAO,MAAM,qBAAqB,kBAAY,CAAC;AAC/C,0DAA0D;AAC1D,eAAO,MAAM,UAAU,uBAAiB,CAAC"}

package/lib/services/translation/translation.service.js

@@ -0,0 +1,211 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectLang = exports.getTranslationWrapper = exports.translationService = exports.TRANSLATION_FAILED = void 0;
+const axios_1 = __importDefault(require("axios"));
+const enums_1 = require("../../globals/aiModels/enums");
+const types_1 = require("../../globals/types");
+const logger_1 = require("../../utils/logger");
+/**
+ * Translation service — single abstraction over language detection + translation.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Translation used to be a bare axios call to a custom Cloud Function
+ * (`translation-service-3931b`). That endpoint times out constantly
+ * (`timeout of 8000ms exceeded`, ~24s of retries), and every exhaustion threw
+ * `TRANSLATION_FAILED` — which broke /v1/video and /v1/text prompt generation
+ * AND flooded Slack with `error`-level alerts.
+ *
+ * Now there are TWO layers behind one interface:
+ *   1. PRIMARY  — the existing Cloud Function (free; just flaky).
+ *   2. FALLBACK — a cheap, reliable LLM (gpt-4o-mini) via our own provider
+ *      factory. It is NOT on the Google quota that the video pipeline competes
+ *      for, costs a fraction of a cent per short prompt, and is a single API we
+ *      already operate.
+ *
+ * A primary timeout that the LLM recovers from logs at WARN (Console + Loki, no
+ * Slack) — so the common flaky-primary case no longer floods the channel. Only
+ * when BOTH layers fail do we log ERROR (→ Slack) and throw, so the alert that
+ * survives is a real, rare outage rather than noise.
+ *
+ * Callers should use `translationService.translate()` / `.detectLanguage()`.
+ * The legacy `getTranslationWrapper` / `detectLang` names are kept as thin
+ * aliases (re-exported from utils/helpers) so existing callsites keep working.
+ */
+exports.TRANSLATION_FAILED = "TRANSLATION_FAILED";
+const PRIMARY_BASE = "https://us-central1-translation-service-3931b.cloudfunctions.net";
+// Shorter than the old 8s so we fail over to the LLM faster (the old 3×8s =
+// 24s user-facing stall was itself part of the problem).
+const PRIMARY_TIMEOUT_MS = 6000;
+const PRIMARY_MAX_ATTEMPTS = 2;
+// gpt-4o-mini: cheap (~$0.15/1M in, $0.60/1M out → fractions of a cent per
+// prompt), reliable, and independent of the Google video quota. Swap here if a
+// cheaper effective model becomes available.
+const FALLBACK_MODEL = enums_1.ETextGenModels.OPENAI_GPT_4O_MINI;
+/** Human-readable target name for the LLM prompt; falls back to the raw code. */
+const LANGUAGE_NAMES = {
+    en: "English",
+};
+function languageLabel(code) {
+    return LANGUAGE_NAMES[code] ?? `the language with ISO code "${code}"`;
+}
+/** PRIMARY: one POST to the custom translation Cloud Function. Throws on error. */
+async function callPrimaryTranslate(text, from, to, version) {
+    const res = await axios_1.default.post(`${PRIMARY_BASE}/translate`, { text, from, to, version }, {
+        headers: { "internal-key": process.env.TRANSLATION_SERVICE_KEY || "" },
+        timeout: PRIMARY_TIMEOUT_MS,
+    });
+    const translated = res.data?.translated;
+    if (typeof translated !== "string" || !translated.length) {
+        throw new Error("primary translation returned empty payload");
+    }
+    return translated;
+}
+/**
+ * FALLBACK: translate via a cheap LLM. Lazy-imports the provider factory so this
+ * module stays light (utils/helpers re-exports it) and to avoid an import cycle
+ * with the aiGen layer.
+ */
+async function callLlmTranslate(text, from, to) {
+    const { getAiGenProviderService } = await Promise.resolve().then(() => __importStar(require("../aiGen/aiGenFactory.service")));
+    const service = getAiGenProviderService(FALLBACK_MODEL);
+    const target = languageLabel(to);
+    const system = `You are a professional translation engine. Translate the user's text into ${target}. ` +
+        `Preserve meaning, tone, names, numbers, hashtags, emojis and line breaks. ` +
+        `Output ONLY the translated text — no quotes, no language labels, no commentary. ` +
+        `If the text is already in ${target}, return it unchanged.`;
+    const { text: out } = await service.generateText({
+        input: [
+            { role: "system", content: system },
+            { role: "user", content: text },
+        ],
+        modelKey: FALLBACK_MODEL,
+        options: { temperature: 0 },
+    });
+    const trimmed = (out ?? "").trim();
+    if (!trimmed || trimmed === "No response") {
+        throw new Error("LLM fallback returned empty translation");
+    }
+    return trimmed;
+}
+/**
+ * Translate `text` from → to (default English). Primary CF first (with a couple
+ * of quick retries), then a cheap LLM. Throws Error(TRANSLATION_FAILED) only if
+ * BOTH layers fail; `.cause` carries the last error.
+ */
+async function translate(text, from, to = types_1.ELANGUAGE_CODE.en, version = "v2") {
+    if (!text || !text.trim())
+        return text;
+    // ── Layer 1: primary Cloud Function ──────────────────────────────────────
+    let primaryErr;
+    for (let attempt = 1; attempt <= PRIMARY_MAX_ATTEMPTS; attempt++) {
+        try {
+            return await callPrimaryTranslate(text, from, to, version);
+        }
+        catch (err) {
+            primaryErr = err;
+            if (attempt < PRIMARY_MAX_ATTEMPTS) {
+                await new Promise((r) => setTimeout(r, 200 * attempt));
+            }
+        }
+    }
+    // ── Layer 2: LLM fallback (the common recovery path — WARN, not Slack) ────
+    logger_1.logger.warn("translation: primary failed, falling back to LLM", {
+        sourceLang: from,
+        targetLang: to,
+        primaryAttempts: PRIMARY_MAX_ATTEMPTS,
+        fallbackModel: FALLBACK_MODEL,
+        err: errMsg(primaryErr),
+    });
+    try {
+        return await callLlmTranslate(text, from, to);
+    }
+    catch (fallbackErr) {
+        // Both layers down — this is the only case worth a Slack alert.
+        logger_1.logger.error("translation failed on BOTH primary and LLM fallback", {
+            sourceLang: from,
+            targetLang: to,
+            primaryErr: errMsg(primaryErr),
+            fallbackErr: errMsg(fallbackErr),
+        });
+        const e = new Error(exports.TRANSLATION_FAILED);
+        e.cause = fallbackErr;
+        throw e;
+    }
+}
+/**
+ * Detect the language of `text`. Primary CF; on failure fails OPEN to English
+ * (matches prior behavior — language detection must never block generation).
+ */
+async function detectLanguage(text) {
+    try {
+        const res = await axios_1.default.post(`${PRIMARY_BASE}/detectLang`, { text }, {
+            headers: { "internal-key": process.env.TRANSLATION_SERVICE_KEY || "" },
+            timeout: PRIMARY_TIMEOUT_MS,
+        });
+        return res.data;
+    }
+    catch (err) {
+        logger_1.logger.warn("translation: detectLang failed, defaulting to en", {
+            err: errMsg(err),
+        });
+        return {
+            reliable: false,
+            textBytes: 0,
+            languages: [
+                { name: "English", code: types_1.ELANGUAGE_CODE.en, percent: 100, score: 0 },
+            ],
+            chunks: [],
+        };
+    }
+}
+function errMsg(err) {
+    if (err instanceof Error)
+        return err.stack ?? err.message;
+    return String(err);
+}
+exports.translationService = {
+    translate,
+    detectLanguage,
+};
+// ── Legacy aliases (kept so existing callsites need no change) ──────────────
+/** @deprecated use `translationService.translate` */
+exports.getTranslationWrapper = translate;
+/** @deprecated use `translationService.detectLanguage` */
+exports.detectLang = detectLanguage;

package/lib/utils/helpers.d.ts

@@ -1,4 +1,4 @@
-import { ELANGUAGE_CODE, ERENEWAL_FREQUENCY, ESUBSCRIPTION_PLANS, EVideoDurationType, IDetectLang } from "../globals/types";
+import { ERENEWAL_FREQUENCY, ESUBSCRIPTION_PLANS, EVideoDurationType } from "../globals/types";
 import z from "zod";
 import { ETextGenModels } from "../globals";
 export declare const getPlanTypeById: (priceId: string) => ESUBSCRIPTION_PLANS | null;
@@ -32,9 +32,7 @@ export declare const assertCostFound: (modelKey: string, cost: number | undefine
  */
 export declare const MULTI_CLIP_DISCOUNT_FACTORS: Partial<Record<EVideoDurationType, number>>;
 export declare function getMultiClipDiscountFactor(durationType: EVideoDurationType): number;
-export declare const TRANSLATION_FAILED = "TRANSLATION_FAILED";
-export declare const getTranslationWrapper: (text: string, from: ELANGUAGE_CODE, to?: ELANGUAGE_CODE, version?: "v1" | "v2") => Promise<string>;
-export declare const detectLang: (text: string) => Promise<IDetectLang>;
+export { TRANSLATION_FAILED, getTranslationWrapper, detectLang, } from "../services/translation/translation.service";
 export declare function waitForFile(path: string, timeout?: number, interval?: number): Promise<boolean>;
 export declare function generateAndValidate<T extends z.ZodSchema<any>>(args: {
     userPrompt: string;

package/lib/utils/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAElB,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,KACd,mBAAmB,GAAG,IASxB,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,KAAG,kBAAkB,GAAG,IASlE,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,MAAM,mBAAmB,EACzB,OAAM,kBAA+C,WAgBtD,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,EAAE,oBAAiB,KAAG,MAQpE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,EAChB,MAAM,MAAM,GAAG,SAAS,EACxB,UAAU,MAAM,KACf,MASF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAInF,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,kBAAkB,GAAG,MAAM,CAEnF;AAED,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,MAAM,cAAc,EACpB,KAAI,cAAkC,EACtC,UAAS,IAAI,GAAG,IAAW,KAC1B,OAAO,CAAC,MAAM,CAwChB,CAAC;AAEF,eAAO,MAAM,UAAU,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,WAAW,CAuBlE,CAAC;AAEF,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,SAAQ,EACf,QAAQ,SAAM,oBAQf;AAGD,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,SAAS,EAAE,CAAC,CAAC;IACb,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAGxB,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AA0DrB,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAatE"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAEnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,CAAC,MAAM,KAAK,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,KACd,mBAAmB,GAAG,IASxB,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,KAAG,kBAAkB,GAAG,IASlE,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,MAAM,mBAAmB,EACzB,OAAM,kBAA+C,WAgBtD,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,EAAE,oBAAiB,KAAG,MAQpE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,EAChB,MAAM,MAAM,GAAG,SAAS,EACxB,UAAU,MAAM,KACf,MASF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAInF,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,kBAAkB,GAAG,MAAM,CAEnF;AAOD,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,UAAU,GACX,MAAM,6CAA6C,CAAC;AAErD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,SAAQ,EACf,QAAQ,SAAM,oBAQf;AAGD,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,SAAS,EAAE,CAAC,CAAC;IACb,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAGxB,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AA0DrB,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAatE"}