vidspotai-shared 1.0.82-dev.0 → 1.0.83

package/lib/services/rateLimiter/distributedRateLimiter.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"distributedRateLimiter.service.d.ts","sourceRoot":"","sources":["../../../src/services/rateLimiter/distributedRateLimiter.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAU5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,UAAU,4BAA4B;IACpC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAuDD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,SAAS,CAAyB;gBAE9B,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,4BAA4B;IAOlE;;;;;OAKG;IACG,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAUzC;;;;;OAKG;IACG,4BAA4B,IAAI,OAAO,CAAC,IAAI,CAAC;IAInD,gEAAgE;IAChE,WAAW,IAAI,IAAI;IAInB,IAAI,qBAAqB,IAAI,MAAM,CAElC;IAEK,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC;YAoC5B,iBAAiB;IAc/B,OAAO,CAAC,iBAAiB;YAQX,iBAAiB;CA6DhC;AAwBD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,WAAW,GACpB,sBAAsB,CAaxB;AAED,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,WAAW,GACpB,sBAAsB,CAexB;AAED;4DAC4D;AAC5D,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAM1E"}
+{"version":3,"file":"distributedRateLimiter.service.d.ts","sourceRoot":"","sources":["../../../src/services/rateLimiter/distributedRateLimiter.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAM5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,SAAU,CAAC;AAC9C,eAAO,MAAM,mBAAmB,SAAU,CAAC;AAQ3C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,UAAU,4BAA4B;IACpC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,eAAe,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;IACnB,yDAAyD;IACzD,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AA4DD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,SAAS,CAAyB;gBAE9B,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,4BAA4B;IAOlE;;;;;;;;;;;;OAYG;IACG,kBAAkB,CAAC,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtE;;;;;;;;OAQG;IACG,4BAA4B,IAAI,OAAO,CAAC,IAAI,CAAC;IAInD;;;;;OAKG;IACG,eAAe,CACnB,mBAAmB,GAAE,MAA+B,GACnD,OAAO,CAAC,eAAe,CAAC;IAgF3B,gEAAgE;IAChE,WAAW,IAAI,IAAI;IAInB,IAAI,qBAAqB,IAAI,MAAM,CAElC;IAEK,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC;YAoC5B,iBAAiB;IAc/B,OAAO,CAAC,iBAAiB;YAQX,iBAAiB;CAoHhC;AAwBD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,WAAW,GACpB,sBAAsB,CA0BxB;AAED,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,WAAW,GACpB,sBAAsB,CAexB;AAED;4DAC4D;AAC5D,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAM1E"}

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/socialAI/captionGen.d.ts

@@ -0,0 +1,81 @@
+import { ESocialProvider } from "../../globals/types";
+/**
+ * X8 Social Suite — E1: AI caption / hashtag / title generation (Phase 6 AI
+ * growth layer). Pure, dependency-free core: builds the LLM prompt, parses +
+ * clamps the model's JSON, and exposes `generateSocialSuggestionsCore(llm, ctx)`
+ * with the LLM injected so it's unit-/eval-testable away from the OpenAI client
+ * (planner-style `*Core(llm,…)` convention — see L-3/L-5).
+ *
+ * One round-trip produces a platform-agnostic BASE (caption + hashtags + title)
+ * that fills the composer's main fields, PLUS per-platform VARIANTS tailored to
+ * each requested provider's norms (char limits, hashtag conventions, title use)
+ * that pre-seed the composer's per-platform overrides. The composer applies the
+ * base by default and reveals the variants progressively (pro depth, beginner
+ * surface — plan §B1/§E1).
+ */
+/** Input context for a suggestion request (no secrets — safe to log). */
+export interface ISocialSuggestionContext {
+    /** Providers to tailor per-platform variants for (the composer's targets). */
+    providers: ESocialProvider[];
+    /** Title of the source video, if any. */
+    videoTitle?: string;
+    /** What the video is about — prompt / script summary that grounds the copy. */
+    videoSummary?: string;
+    /** ISO-639-1 / locale to WRITE the copy in (defaults to English). */
+    language?: string;
+    /** Optional brand-voice / tone steer (e.g. "playful, no emojis"). */
+    tone?: string;
+}
+/** A per-platform tailored caption + hashtag set. */
+export interface ISocialSuggestionVariant {
+    provider: ESocialProvider;
+    caption: string;
+    hashtags: string[];
+}
+/** The full suggestion the composer renders. */
+export interface ISocialSuggestion {
+    /** Platform-agnostic caption the composer fills into the main field. */
+    caption: string;
+    /** Platform-agnostic hashtag set (no leading '#', deduped). */
+    hashtags: string[];
+    /** Title (used by YouTube; harmless to ignore on caption-only platforms). */
+    title: string;
+    /** Per-platform variants for the requested providers (best-effort). */
+    variants: ISocialSuggestionVariant[];
+}
+/** A minimal LLM call: take chat messages, return the raw text completion. */
+export type SuggestionLlm = (messages: Array<{
+    role: "system" | "user";
+    content: string;
+}>) => Promise<string>;
+/**
+ * Per-platform copy norms. `maxChars` clamps the caption; `maxHashtags` caps the
+ * tag list; `note` is fed to the model so each variant reads native to the
+ * platform. Hard limits (X = 280) are real product constraints, not style.
+ */
+interface PlatformCopyHint {
+    maxChars: number;
+    maxHashtags: number;
+    note: string;
+}
+export declare const PLATFORM_COPY_HINTS: Record<ESocialProvider, PlatformCopyHint>;
+/** Build the chat prompt for a suggestion request. Pure — no I/O. */
+export declare function buildSuggestionPrompt(ctx: ISocialSuggestionContext): Array<{
+    role: "system" | "user";
+    content: string;
+}>;
+/**
+ * Parse + validate + clamp the model's JSON into an `ISocialSuggestion`.
+ * Defensive: malformed JSON degrades to a plain caption (the raw text) with no
+ * hashtags/variants rather than throwing, so the composer always gets something
+ * usable. Variants are kept only for providers the caller actually requested.
+ */
+export declare function parseSocialSuggestion(raw: string, ctx: ISocialSuggestionContext): ISocialSuggestion;
+/**
+ * Generate social suggestions with the LLM injected (testable). Builds the
+ * prompt, calls the model, parses + clamps the result. Never throws on a bad
+ * model response — it degrades to a usable caption (see `parseSocialSuggestion`).
+ */
+export declare function generateSocialSuggestionsCore(llm: SuggestionLlm, ctx: ISocialSuggestionContext): Promise<ISocialSuggestion>;
+export {};
+//# sourceMappingURL=captionGen.d.ts.map

package/lib/services/socialAI/captionGen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captionGen.d.ts","sourceRoot":"","sources":["../../../src/services/socialAI/captionGen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AAEH,yEAAyE;AACzE,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,QAAQ,EAAE,wBAAwB,EAAE,CAAC;CACtC;AAED,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,CAC1B,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,KAC1D,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB;;;;GAIG;AACH,UAAU,gBAAgB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAyCzE,CAAC;AAqCF,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,wBAAwB,GAC5B,KAAK,CAAC;IAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAkDrD;AAYD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,wBAAwB,GAC5B,iBAAiB,CA2DnB;AAED;;;;GAIG;AACH,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,wBAAwB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAI5B"}

package/lib/services/socialAI/captionGen.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLATFORM_COPY_HINTS = void 0;
+exports.buildSuggestionPrompt = buildSuggestionPrompt;
+exports.parseSocialSuggestion = parseSocialSuggestion;
+exports.generateSocialSuggestionsCore = generateSocialSuggestionsCore;
+const types_1 = require("../../globals/types");
+exports.PLATFORM_COPY_HINTS = {
+    [types_1.ESocialProvider.YOUTUBE]: {
+        maxChars: 4900,
+        maxHashtags: 5,
+        note: "YouTube: a strong, searchable title carries the post; description can be longer and front-load the hook; 3–5 relevant hashtags.",
+    },
+    [types_1.ESocialProvider.INSTAGRAM]: {
+        maxChars: 2100,
+        maxHashtags: 12,
+        note: "Instagram Reels: hook in the first line (it's the only part shown collapsed); conversational; 8–12 niche, non-spammy hashtags.",
+    },
+    [types_1.ESocialProvider.TIKTOK]: {
+        maxChars: 2100,
+        maxHashtags: 6,
+        note: "TikTok: punchy, native, trend-aware; only ~150 chars show before the fold; 3–6 hashtags mixing broad + niche.",
+    },
+    [types_1.ESocialProvider.FACEBOOK]: {
+        maxChars: 4900,
+        maxHashtags: 3,
+        note: "Facebook: friendly and shareable; hashtags are sparse here — at most 1–3.",
+    },
+    [types_1.ESocialProvider.LINKEDIN]: {
+        maxChars: 2900,
+        maxHashtags: 5,
+        note: "LinkedIn: professional, value-first, minimal emojis; 3–5 industry hashtags.",
+    },
+    [types_1.ESocialProvider.X]: {
+        maxChars: 270,
+        maxHashtags: 2,
+        note: "X (Twitter): HARD 280-char limit including hashtags — keep it tight; at most 1–2 hashtags.",
+    },
+    [types_1.ESocialProvider.PINTEREST]: {
+        maxChars: 480,
+        maxHashtags: 5,
+        note: "Pinterest: keyword-rich and descriptive for search; 2–5 descriptive hashtags.",
+    },
+    [types_1.ESocialProvider.THREADS]: {
+        maxChars: 480,
+        maxHashtags: 3,
+        note: "Threads: casual and conversational; very few hashtags (Threads supports one primary topic tag).",
+    },
+};
+const VALID_PROVIDERS = new Set(Object.values(types_1.ESocialProvider));
+/** Normalize a raw hashtag list: strip '#', spaces, dedupe (case-insensitive). */
+function normalizeHashtags(raw, cap) {
+    if (!Array.isArray(raw))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== "string")
+            continue;
+        // Strip leading '#'s and all whitespace; a model sometimes returns "#a b".
+        const tag = item.replace(/^#+/, "").replace(/\s+/g, "").trim();
+        if (!tag)
+            continue;
+        const key = tag.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(tag);
+        if (out.length >= cap)
+            break;
+    }
+    return out;
+}
+/** Clamp to a max char length on a word boundary where possible. */
+function clampText(text, maxChars) {
+    const t = (text ?? "").trim();
+    if (t.length <= maxChars)
+        return t;
+    const cut = t.slice(0, maxChars);
+    const lastSpace = cut.lastIndexOf(" ");
+    return (lastSpace > maxChars * 0.6 ? cut.slice(0, lastSpace) : cut).trim();
+}
+/** The loosest base limits (used for the platform-agnostic base caption). */
+const BASE_CAPTION_MAX = 2200;
+const BASE_HASHTAG_MAX = 15;
+const TITLE_MAX = 100;
+/** Build the chat prompt for a suggestion request. Pure — no I/O. */
+function buildSuggestionPrompt(ctx) {
+    const providers = ctx.providers.filter((p) => VALID_PROVIDERS.has(p));
+    const lang = (ctx.language || "en").trim();
+    const toneLine = ctx.tone
+        ? `Brand voice / tone: ${ctx.tone}.`
+        : "Brand voice: authentic, energetic, and human — never corporate or spammy.";
+    const platformNotes = providers
+        .map((p) => `- ${p}: ${exports.PLATFORM_COPY_HINTS[p].note}`)
+        .join("\n");
+    const system = "You are an expert social media copywriter for short-form video creators. " +
+        "You write scroll-stopping captions, relevant non-spammy hashtags, and " +
+        "compelling titles that maximize reach and engagement. You always write in " +
+        `the requested language (${lang}) and respect each platform's norms and ` +
+        "character limits. You reply with ONLY a single JSON object, no prose, no " +
+        "code fences.";
+    const aboutLines = [
+        ctx.videoTitle ? `Working title: ${ctx.videoTitle}` : null,
+        ctx.videoSummary ? `What the video is about: ${ctx.videoSummary}` : null,
+    ].filter(Boolean);
+    const about = aboutLines.length
+        ? aboutLines.join("\n")
+        : "A short-form video (no further details provided — infer a generic but appealing angle).";
+    const user = `Write social copy in language "${lang}" for this video.\n\n${about}\n\n` +
+        `${toneLine}\n\n` +
+        `Target platforms:\n${platformNotes || "- (generic)"}\n\n` +
+        "Produce a platform-agnostic BASE (a strong caption, a hashtag set, and a " +
+        "title) AND one tailored VARIANT per target platform that respects that " +
+        "platform's note above (length, hashtag count, style). Hashtags must NOT " +
+        "include the '#' symbol and must be single words (no spaces). Do not invent " +
+        "facts about the video.\n\n" +
+        "Reply with ONLY this JSON shape:\n" +
+        "{\n" +
+        '  "title": "string (<= 100 chars, YouTube-style)",\n' +
+        '  "caption": "string (the base caption)",\n' +
+        '  "hashtags": ["tag1", "tag2"],\n' +
+        '  "variants": [\n' +
+        '    { "provider": "<one of the target platforms>", "caption": "string", "hashtags": ["tag1"] }\n' +
+        "  ]\n" +
+        "}";
+    return [
+        { role: "system", content: system },
+        { role: "user", content: user },
+    ];
+}
+/** Strip a ```json … ``` fence the model may wrap the object in. */
+function stripCodeFence(raw) {
+    const t = raw.trim();
+    if (!t.startsWith("```"))
+        return t;
+    return t
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```$/, "")
+        .trim();
+}
+/**
+ * Parse + validate + clamp the model's JSON into an `ISocialSuggestion`.
+ * Defensive: malformed JSON degrades to a plain caption (the raw text) with no
+ * hashtags/variants rather than throwing, so the composer always gets something
+ * usable. Variants are kept only for providers the caller actually requested.
+ */
+function parseSocialSuggestion(raw, ctx) {
+    const requested = new Set(ctx.providers.filter((p) => VALID_PROVIDERS.has(p)));
+    let obj = null;
+    try {
+        const parsed = JSON.parse(stripCodeFence(raw));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            obj = parsed;
+        }
+    }
+    catch {
+        obj = null;
+    }
+    // Fallback: treat the whole response as the caption.
+    if (!obj) {
+        return {
+            caption: clampText(raw, BASE_CAPTION_MAX),
+            hashtags: [],
+            title: "",
+            variants: [],
+        };
+    }
+    const title = clampText(typeof obj.title === "string" ? obj.title : "", TITLE_MAX);
+    const caption = clampText(typeof obj.caption === "string" ? obj.caption : "", BASE_CAPTION_MAX);
+    const hashtags = normalizeHashtags(obj.hashtags, BASE_HASHTAG_MAX);
+    const variants = [];
+    const seenProviders = new Set();
+    if (Array.isArray(obj.variants)) {
+        for (const v of obj.variants) {
+            if (!v || typeof v !== "object")
+                continue;
+            const rec = v;
+            const provider = rec.provider;
+            if (typeof provider !== "string" || !requested.has(provider)) {
+                continue;
+            }
+            const p = provider;
+            if (seenProviders.has(p))
+                continue;
+            seenProviders.add(p);
+            const hint = exports.PLATFORM_COPY_HINTS[p];
+            variants.push({
+                provider: p,
+                caption: clampText(typeof rec.caption === "string" ? rec.caption : caption, hint.maxChars),
+                hashtags: normalizeHashtags(rec.hashtags, hint.maxHashtags),
+            });
+        }
+    }
+    return { caption, hashtags, title, variants };
+}
+/**
+ * Generate social suggestions with the LLM injected (testable). Builds the
+ * prompt, calls the model, parses + clamps the result. Never throws on a bad
+ * model response — it degrades to a usable caption (see `parseSocialSuggestion`).
+ */
+async function generateSocialSuggestionsCore(llm, ctx) {
+    const messages = buildSuggestionPrompt(ctx);
+    const raw = await llm(messages);
+    return parseSocialSuggestion(raw, ctx);
+}

package/lib/services/socialAI/hookScore.d.ts

@@ -0,0 +1,85 @@
+import { ESocialProvider } from "../../globals/types";
+/**
+ * X8 Social Suite — Phase 6 E4: hook / caption score predictor.
+ *
+ * Score a hook (the caption's first line / the on-screen opener) for predicted
+ * engagement BEFORE posting, and hand back concrete rewrites. This is the same
+ * `*Core(llm,…)` convention as captionGen (E1) — pure prompt-build + defensive
+ * parse/clamp with the LLM injected, so it's unit-/eval-testable away from the
+ * OpenAI client. It is a *predictor / coach*, not a guarantee: the score is the
+ * model's judgement against well-known short-form hook heuristics (scroll-stop,
+ * clarity, curiosity gap, relevance, platform fit), surfaced so the user can
+ * iterate the copy. Review-before-publish — nothing posts here.
+ *
+ * Why a separate brain from E1: E1 *writes* copy from a video; E4 *grades*
+ * arbitrary copy the user already has (typed or AI-written) and proposes
+ * stronger variants. Different prompt, different output shape, shared norms.
+ */
+/** Input for a hook score request (no secrets — safe to log). */
+export interface IHookScoreContext {
+    /** The hook / caption opener to grade (required). */
+    hook: string;
+    /** Platform the copy targets — tunes the rubric to that surface's norms. */
+    provider?: ESocialProvider;
+    /** What the video is about — lets the model judge relevance, not just craft. */
+    videoSummary?: string;
+    /** Language the copy is written in (defaults to English). */
+    language?: string;
+}
+/** The five engagement drivers we grade a hook on (each 0–100). */
+export interface IHookScoreBreakdown {
+    /** Scroll-stopping power — does it arrest the thumb in the first beat? */
+    attention: number;
+    /** Is the promise/topic instantly legible (no decoding)? */
+    clarity: number;
+    /** Curiosity gap — does it open a loop the viewer must close? */
+    curiosity: number;
+    /** Does it match what the video actually delivers (no bait)? */
+    relevance: number;
+    /** Native fit for the target platform's length + tone conventions. */
+    platformFit: number;
+}
+/** Coarse band derived deterministically from the overall score. */
+export type HookVerdict = "weak" | "okay" | "strong";
+/** The full graded result the composer renders. */
+export interface IHookScore {
+    /** Overall 0–100 predicted-engagement score. */
+    score: number;
+    /** Band derived from `score` (not trusted from the model). */
+    verdict: HookVerdict;
+    /** Per-driver sub-scores. */
+    breakdown: IHookScoreBreakdown;
+    /** What's working (short bullets). */
+    strengths: string[];
+    /** What's holding it back (short, actionable bullets). */
+    issues: string[];
+    /** 2–3 stronger rewrites the user can adopt with one tap. */
+    rewrites: string[];
+}
+/** A minimal LLM call: take chat messages, return the raw text completion. */
+export type HookScoreLlm = (messages: Array<{
+    role: "system" | "user";
+    content: string;
+}>) => Promise<string>;
+/** Verdict bands: <40 weak, <70 okay, ≥70 strong. */
+export declare function verdictForScore(score: number): HookVerdict;
+/** Build the chat prompt for a hook-score request. Pure — no I/O. */
+export declare function buildHookScorePrompt(ctx: IHookScoreContext): Array<{
+    role: "system" | "user";
+    content: string;
+}>;
+/**
+ * Parse + validate + clamp the model's JSON into an `IHookScore`. Defensive:
+ * malformed JSON degrades to a neutral 50 with empty coaching rather than
+ * throwing, so the composer always renders something. The verdict is ALWAYS
+ * recomputed from the clamped score (never trusted from the model) so the band
+ * and number can't disagree.
+ */
+export declare function parseHookScore(raw: string): IHookScore;
+/**
+ * Score a hook with the LLM injected (testable). Builds the prompt, calls the
+ * model, parses + clamps. Never throws on a bad model response — degrades to a
+ * neutral score (see `parseHookScore`).
+ */
+export declare function scoreHookCore(llm: HookScoreLlm, ctx: IHookScoreContext): Promise<IHookScore>;
+//# sourceMappingURL=hookScore.d.ts.map