vidspotai-shared 1.0.82 → 1.0.83

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"hookScore.d.ts","sourceRoot":"","sources":["../../../src/services/socialAI/hookScore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtD;;;;;;;;;;;;;;;GAeG;AAEH,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,oEAAoE;AACpE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErD,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,OAAO,EAAE,WAAW,CAAC;IACrB,6BAA6B;IAC7B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,sCAAsC;IACtC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,CACzB,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,KAC1D,OAAO,CAAC,MAAM,CAAC,CAAC;AAkBrB,qDAAqD;AACrD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAI1D;AA+BD,qEAAqE;AACrE,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,iBAAiB,GACrB,KAAK,CAAC;IAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA2CrD;AAYD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CA8CtD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,UAAU,CAAC,CAIrB"}

package/lib/services/socialAI/hookScore.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verdictForScore = verdictForScore;
+exports.buildHookScorePrompt = buildHookScorePrompt;
+exports.parseHookScore = parseHookScore;
+exports.scoreHookCore = scoreHookCore;
+const types_1 = require("../../globals/types");
+const captionGen_1 = require("./captionGen");
+const DRIVER_KEYS = [
+    "attention",
+    "clarity",
+    "curiosity",
+    "relevance",
+    "platformFit",
+];
+const MAX_HOOK_INPUT = 600;
+const MAX_BULLET = 160;
+const MAX_BULLETS = 4;
+const MAX_REWRITE = 280;
+const MAX_REWRITES = 3;
+const VALID_PROVIDERS = new Set(Object.values(types_1.ESocialProvider));
+/** Verdict bands: <40 weak, <70 okay, ≥70 strong. */
+function verdictForScore(score) {
+    if (score < 40)
+        return "weak";
+    if (score < 70)
+        return "okay";
+    return "strong";
+}
+function clampScore(raw) {
+    const n = typeof raw === "number" ? raw : Number(raw);
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(100, Math.round(n)));
+}
+/** Clamp + trim a free-text bullet to one tidy line. */
+function clampBullet(text, max) {
+    if (typeof text !== "string")
+        return "";
+    return text.replace(/\s+/g, " ").trim().slice(0, max);
+}
+/** Normalize a string list: trim, drop empties, dedupe, cap length + count. */
+function normalizeList(raw, maxLen, maxCount) {
+    if (!Array.isArray(raw))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const item of raw) {
+        const s = clampBullet(item, maxLen);
+        if (!s)
+            continue;
+        const key = s.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(s);
+        if (out.length >= maxCount)
+            break;
+    }
+    return out;
+}
+/** Build the chat prompt for a hook-score request. Pure — no I/O. */
+function buildHookScorePrompt(ctx) {
+    const lang = (ctx.language || "en").trim();
+    const provider = ctx.provider && VALID_PROVIDERS.has(ctx.provider) ? ctx.provider : undefined;
+    const platformNote = provider
+        ? `Target platform: ${provider}. ${captionGen_1.PLATFORM_COPY_HINTS[provider].note}`
+        : "No specific platform — judge against general short-form video norms.";
+    const about = ctx.videoSummary
+        ? `What the video is actually about (judge RELEVANCE against this — penalize bait that the video can't pay off):\n${ctx.videoSummary.slice(0, 1200)}`
+        : "The video's content is unknown — judge relevance only on internal coherence of the hook.";
+    const system = "You are a short-form video growth expert who predicts how well a hook " +
+        "will perform. You grade hooks against proven engagement drivers: " +
+        "scroll-stopping ATTENTION, instant CLARITY, a CURIOSITY gap, RELEVANCE to " +
+        "the actual content (no clickbait the video can't deliver), and native " +
+        "PLATFORM FIT. You are calibrated and honest — most hooks are mediocre; " +
+        "reserve 80+ for genuinely scroll-stopping copy. You always respond in the " +
+        `requested language (${lang}) for the prose fields and rewrites. You reply ` +
+        "with ONLY a single JSON object — no prose, no code fences.";
+    const user = `Grade this hook and propose stronger rewrites. Write prose + rewrites in language "${lang}".\n\n` +
+        `HOOK:\n"""${ctx.hook.slice(0, MAX_HOOK_INPUT)}"""\n\n` +
+        `${platformNote}\n\n${about}\n\n` +
+        "Score the hook 0-100 overall and 0-100 on each driver. Give 1-3 short " +
+        "strengths, 1-3 short actionable issues, and 2-3 rewrites that keep the " +
+        "topic but hit harder (each a complete, ready-to-use hook). Do not invent " +
+        "facts the video can't support.\n\n" +
+        "Reply with ONLY this JSON shape:\n" +
+        "{\n" +
+        '  "score": 0,\n' +
+        '  "breakdown": { "attention": 0, "clarity": 0, "curiosity": 0, "relevance": 0, "platformFit": 0 },\n' +
+        '  "strengths": ["..."],\n' +
+        '  "issues": ["..."],\n' +
+        '  "rewrites": ["...", "..."]\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 `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.
+ */
+function parseHookScore(raw) {
+    let obj = null;
+    try {
+        const parsed = JSON.parse(stripCodeFence(raw));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            obj = parsed;
+        }
+    }
+    catch {
+        obj = null;
+    }
+    if (!obj) {
+        return {
+            score: 50,
+            verdict: verdictForScore(50),
+            breakdown: {
+                attention: 50,
+                clarity: 50,
+                curiosity: 50,
+                relevance: 50,
+                platformFit: 50,
+            },
+            strengths: [],
+            issues: [],
+            rewrites: [],
+        };
+    }
+    const score = clampScore(obj.score);
+    const rawBreakdown = obj.breakdown && typeof obj.breakdown === "object"
+        ? obj.breakdown
+        : {};
+    const breakdown = DRIVER_KEYS.reduce((acc, k) => {
+        acc[k] = clampScore(rawBreakdown[k]);
+        return acc;
+    }, {});
+    return {
+        score,
+        verdict: verdictForScore(score),
+        breakdown,
+        strengths: normalizeList(obj.strengths, MAX_BULLET, MAX_BULLETS),
+        issues: normalizeList(obj.issues, MAX_BULLET, MAX_BULLETS),
+        rewrites: normalizeList(obj.rewrites, MAX_REWRITE, MAX_REWRITES),
+    };
+}
+/**
+ * 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`).
+ */
+async function scoreHookCore(llm, ctx) {
+    const messages = buildHookScorePrompt(ctx);
+    const raw = await llm(messages);
+    return parseHookScore(raw);
+}

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

@@ -0,0 +1,3 @@
+export * from "./captionGen";
+export * from "./hookScore";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/socialAI/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/lib/services/socialAI/index.js

@@ -0,0 +1,18 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./captionGen"), exports);
+__exportStar(require("./hookScore"), exports);

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

@@ -0,0 +1,2 @@
+export * from "./socialAccountService";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/socialAccounts/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/lib/services/socialAccounts/index.js

@@ -0,0 +1,17 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./socialAccountService"), exports);

package/lib/services/socialAccounts/socialAccountService.d.ts

@@ -0,0 +1,25 @@
+import { ESocialAccountStatus, ESocialProvider } from "../../globals/types";
+import { ISocialTokenBundle } from "../../models/social.model";
+import { OAuthTokens } from "../socialOAuth/types";
+/** Encrypt cleartext OAuth tokens into the persisted bundle shape. */
+export declare function toEncryptedTokenBundle(tokens: OAuthTokens): ISocialTokenBundle;
+/**
+ * Return a valid CLEARTEXT access token for an account, refreshing + persisting
+ * it first if it's expired or near expiry. Throws (and flags the account as
+ * NEEDS_RECONNECT) if refresh fails — callers should surface a reconnect nudge.
+ */
+export declare function getValidAccessToken(accountId: string): Promise<string>;
+/** Persist a freshly-refreshed token bundle + mark the account healthy. */
+export declare function persistRefreshedTokens(accountId: string, refreshed: OAuthTokens): Promise<void>;
+/** Update only the health sub-document (status + optional error). */
+export declare function markAccountHealth(accountId: string, status: ESocialAccountStatus, lastError?: string): Promise<void>;
+/**
+ * Find accounts whose access token expires within `withinMs` so the refresh
+ * daemon can proactively refresh them (Meta 60-day / YT short-lived). Scoped to
+ * ACTIVE accounts that actually have a refresh token.
+ */
+export declare function findAccountsNeedingRefresh(withinMs: number, limit?: number): Promise<Array<{
+    id: string;
+    provider: ESocialProvider;
+}>>;
+//# sourceMappingURL=socialAccountService.d.ts.map

package/lib/services/socialAccounts/socialAccountService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socialAccountService.d.ts","sourceRoot":"","sources":["../../../src/services/socialAccounts/socialAccountService.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAInC,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAanD,sEAAsE;AACtE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,kBAAkB,CAS9E;AAWD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkC5E;AAED,2EAA2E;AAC3E,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,WAAW,GACrB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,qEAAqE;AACrE,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,oBAAoB,EAC5B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,KAAK,SAAM,GACV,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,CAAC,CAAC,CAQ3D"}

package/lib/services/socialAccounts/socialAccountService.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEncryptedTokenBundle = toEncryptedTokenBundle;
+exports.getValidAccessToken = getValidAccessToken;
+exports.persistRefreshedTokens = persistRefreshedTokens;
+exports.markAccountHealth = markAccountHealth;
+exports.findAccountsNeedingRefresh = findAccountsNeedingRefresh;
+const firebase_1 = require("../../libs/firebase");
+const types_1 = require("../../globals/types");
+const logger_1 = require("../../utils/logger");
+const firestore_service_1 = require("../firestore.service");
+const factory_1 = require("../socialOAuth/factory");
+const tokenVault_1 = require("../crypto/tokenVault");
+/**
+ * X8 Social Suite — connected-account token lifecycle. Centralizes the
+ * encrypt-on-write / decrypt-on-read + refresh-if-expiring logic so the publish
+ * worker, metrics poller, and refresh daemon never touch raw ciphertext or the
+ * refresh wire directly. See notes/SOCIAL_SUITE_PLAN.md §4.
+ */
+/** Refresh the access token when it's within this window of expiry. */
+const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+/** Encrypt cleartext OAuth tokens into the persisted bundle shape. */
+function toEncryptedTokenBundle(tokens) {
+    return {
+        accessToken: (0, tokenVault_1.encryptToken)(tokens.accessToken),
+        refreshToken: tokens.refreshToken
+            ? (0, tokenVault_1.encryptToken)(tokens.refreshToken)
+            : undefined,
+        expiresAt: tokens.expiresAt,
+        refreshExpiresAt: tokens.refreshExpiresAt,
+    };
+}
+async function loadAccount(accountId) {
+    const snap = await firestore_service_1.FirestoreService.socialAccountsCol.doc(accountId).get();
+    const data = snap.data();
+    if (!data)
+        throw new Error(`socialAccount ${accountId} not found`);
+    return { id: accountId, data };
+}
+/**
+ * Return a valid CLEARTEXT access token for an account, refreshing + persisting
+ * it first if it's expired or near expiry. Throws (and flags the account as
+ * NEEDS_RECONNECT) if refresh fails — callers should surface a reconnect nudge.
+ */
+async function getValidAccessToken(accountId) {
+    const { data } = await loadAccount(accountId);
+    const { tokens } = data;
+    const fresh = tokens.expiresAt - Date.now() > REFRESH_BUFFER_MS;
+    if (fresh) {
+        return (0, tokenVault_1.decryptToken)(tokens.accessToken);
+    }
+    if (!tokens.refreshToken) {
+        await markAccountHealth(accountId, types_1.ESocialAccountStatus.NEEDS_RECONNECT, "access token expired and no refresh token on file");
+        throw new Error(`socialAccount ${accountId}: expired, no refresh token`);
+    }
+    try {
+        const provider = (0, factory_1.getSocialOAuthProvider)(data.provider);
+        const refreshToken = (0, tokenVault_1.decryptToken)(tokens.refreshToken);
+        const refreshed = await provider.refresh(refreshToken);
+        await persistRefreshedTokens(accountId, refreshed);
+        return refreshed.accessToken;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger_1.logger.warn("socialAccount: token refresh failed", { accountId, message });
+        await markAccountHealth(accountId, types_1.ESocialAccountStatus.NEEDS_RECONNECT, message);
+        throw new Error(`socialAccount ${accountId}: refresh failed — ${message}`);
+    }
+}
+/** Persist a freshly-refreshed token bundle + mark the account healthy. */
+async function persistRefreshedTokens(accountId, refreshed) {
+    await firestore_service_1.FirestoreService.socialAccountsCol.doc(accountId).update({
+        tokens: toEncryptedTokenBundle(refreshed),
+        health: {
+            status: types_1.ESocialAccountStatus.ACTIVE,
+            lastRefreshAt: Date.now(),
+        },
+        updatedAt: firebase_1.FieldValue.serverTimestamp(),
+    });
+}
+/** Update only the health sub-document (status + optional error). */
+async function markAccountHealth(accountId, status, lastError) {
+    await firestore_service_1.FirestoreService.socialAccountsCol.doc(accountId).update({
+        health: {
+            status,
+            ...(lastError ? { lastError } : {}),
+            lastRefreshAt: Date.now(),
+        },
+        updatedAt: firebase_1.FieldValue.serverTimestamp(),
+    });
+}
+/**
+ * Find accounts whose access token expires within `withinMs` so the refresh
+ * daemon can proactively refresh them (Meta 60-day / YT short-lived). Scoped to
+ * ACTIVE accounts that actually have a refresh token.
+ */
+async function findAccountsNeedingRefresh(withinMs, limit = 100) {
+    const cutoff = Date.now() + withinMs;
+    const snap = await firestore_service_1.FirestoreService.socialAccountsCol
+        .where("health.status", "==", types_1.ESocialAccountStatus.ACTIVE)
+        .where("tokens.expiresAt", "<=", cutoff)
+        .limit(limit)
+        .get();
+    return snap.docs.map((d) => ({ id: d.id, provider: d.data().provider }));
+}

package/lib/services/socialEngage/factory.d.ts

@@ -0,0 +1,7 @@
+import { ESocialProvider } from "../../globals/types";
+import { ISocialEngageClient } from "./types";
+export declare function getSocialEngageClient(provider: ESocialProvider): ISocialEngageClient;
+export declare function isSocialEngageSupported(provider: ESocialProvider): boolean;
+/** Providers whose comments must be PULLED (no webhook) by the poll sweep. */
+export declare const ENGAGE_POLL_PROVIDERS: ESocialProvider[];
+//# sourceMappingURL=factory.d.ts.map

package/lib/services/socialEngage/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/services/socialEngage/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAS9C,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,eAAe,GACxB,mBAAmB,CAMrB;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAE1E;AAED,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,EAAE,eAAe,EAA8B,CAAC"}