vidspotai-shared 1.0.82-dev.0 → 1.0.83

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"}

package/lib/services/socialEngage/factory.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENGAGE_POLL_PROVIDERS = void 0;
+exports.getSocialEngageClient = getSocialEngageClient;
+exports.isSocialEngageSupported = isSocialEngageSupported;
+const types_1 = require("../../globals/types");
+const meta_engage_1 = require("./meta.engage");
+const youtube_engage_1 = require("./youtube.engage");
+const registry = {
+    [types_1.ESocialProvider.YOUTUBE]: () => new youtube_engage_1.YouTubeEngageClient(),
+    [types_1.ESocialProvider.INSTAGRAM]: () => new meta_engage_1.InstagramEngageClient(),
+    [types_1.ESocialProvider.FACEBOOK]: () => new meta_engage_1.FacebookEngageClient(),
+};
+function getSocialEngageClient(provider) {
+    const make = registry[provider];
+    if (!make) {
+        throw new Error(`Social engage not implemented for '${provider}'`);
+    }
+    return make();
+}
+function isSocialEngageSupported(provider) {
+    return Boolean(registry[provider]);
+}
+/** Providers whose comments must be PULLED (no webhook) by the poll sweep. */
+exports.ENGAGE_POLL_PROVIDERS = [types_1.ESocialProvider.YOUTUBE];

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

@@ -0,0 +1,6 @@
+export * from "./types";
+export * from "./youtube.engage";
+export * from "./meta.engage";
+export * from "./factory";
+export * from "./metaWebhook";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/socialEngage/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}

package/lib/services/socialEngage/index.js

@@ -0,0 +1,21 @@
+"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("./types"), exports);
+__exportStar(require("./youtube.engage"), exports);
+__exportStar(require("./meta.engage"), exports);
+__exportStar(require("./factory"), exports);
+__exportStar(require("./metaWebhook"), exports);

package/lib/services/socialEngage/meta.engage.d.ts

@@ -0,0 +1,17 @@
+import { ESocialProvider } from "../../globals/types";
+import { FetchCommentsInput, IRemoteComment, ISocialEngageClient, ModerateInput, ReplyInput, ReplyResult } from "./types";
+/** Instagram comment engagement on a published media/Reel. */
+export declare class InstagramEngageClient implements ISocialEngageClient {
+    readonly provider = ESocialProvider.INSTAGRAM;
+    fetchComments({ accessToken, providerPostId, since, limit, }: FetchCommentsInput): Promise<IRemoteComment[]>;
+    replyToComment({ accessToken, externalId, message, }: ReplyInput): Promise<ReplyResult>;
+    moderateComment({ accessToken, externalId, hidden, }: ModerateInput): Promise<void>;
+}
+/** Facebook Page post/video comment engagement. */
+export declare class FacebookEngageClient implements ISocialEngageClient {
+    readonly provider = ESocialProvider.FACEBOOK;
+    fetchComments({ accessToken, providerPostId, since, limit, }: FetchCommentsInput): Promise<IRemoteComment[]>;
+    replyToComment({ accessToken, externalId, message, }: ReplyInput): Promise<ReplyResult>;
+    moderateComment({ accessToken, externalId, hidden, }: ModerateInput): Promise<void>;
+}
+//# sourceMappingURL=meta.engage.d.ts.map

package/lib/services/socialEngage/meta.engage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.engage.d.ts","sourceRoot":"","sources":["../../../src/services/socialEngage/meta.engage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,UAAU,EACV,WAAW,EAEZ,MAAM,SAAS,CAAC;AA+BjB,8DAA8D;AAC9D,qBAAa,qBAAsB,YAAW,mBAAmB;IAC/D,QAAQ,CAAC,QAAQ,6BAA6B;IAExC,aAAa,CAAC,EAClB,WAAW,EACX,cAAc,EACd,KAAK,EACL,KAAU,GACX,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA+B3C,cAAc,CAAC,EACnB,WAAW,EACX,UAAU,EACV,OAAO,GACR,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAe9B,eAAe,CAAC,EACpB,WAAW,EACX,UAAU,EACV,MAAM,GACP,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAajC;AAWD,mDAAmD;AACnD,qBAAa,oBAAqB,YAAW,mBAAmB;IAC9D,QAAQ,CAAC,QAAQ,4BAA4B;IAEvC,aAAa,CAAC,EAClB,WAAW,EACX,cAAc,EACd,KAAK,EACL,KAAU,GACX,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA+B3C,cAAc,CAAC,EACnB,WAAW,EACX,UAAU,EACV,OAAO,GACR,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAe9B,eAAe,CAAC,EACpB,WAAW,EACX,UAAU,EACV,MAAM,GACP,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAajC"}

package/lib/services/socialEngage/meta.engage.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FacebookEngageClient = exports.InstagramEngageClient = void 0;
+const types_1 = require("../../globals/types");
+const types_2 = require("./types");
+/**
+ * Meta engagement clients (Instagram + Facebook). Comments PUSH in via webhooks
+ * (handled in the Functions webhook receiver), but we still expose fetchComments
+ * for backfill / reconciliation. Replies and hide/unhide go through the Graph
+ * API. Env: META_GRAPH_VERSION (optional, default v21.0). See plan §D.
+ */
+const DEFAULT_GRAPH_VERSION = "v21.0";
+function graph(path) {
+    const v = process.env.META_GRAPH_VERSION || DEFAULT_GRAPH_VERSION;
+    return `https://graph.facebook.com/${v}${path}`;
+}
+/** Instagram comment engagement on a published media/Reel. */
+class InstagramEngageClient {
+    constructor() {
+        this.provider = types_1.ESocialProvider.INSTAGRAM;
+    }
+    async fetchComments({ accessToken, providerPostId, since, limit = 50, }) {
+        const tokenQs = `access_token=${encodeURIComponent(accessToken)}`;
+        const resp = await fetch(graph(`/${providerPostId}/comments?fields=id,text,username,timestamp&limit=${Math.min(100, Math.max(1, limit))}&${tokenQs}`));
+        const json = (await resp.json());
+        if (!resp.ok || json.error) {
+            throw new Error(`InstagramEngage: comments ${resp.status} ${json.error?.message ?? ""}`.trim());
+        }
+        const out = [];
+        for (const c of json.data ?? []) {
+            if (!c.id)
+                continue;
+            const createdAt = (0, types_2.isoToMillis)(c.timestamp);
+            if (since && createdAt <= since)
+                continue;
+            out.push({
+                externalId: c.id,
+                parentProviderPostId: providerPostId,
+                authorHandle: c.username,
+                authorName: c.username,
+                text: c.text ?? "",
+                createdAt,
+                type: types_1.ESocialInboxType.COMMENT,
+            });
+        }
+        return out;
+    }
+    async replyToComment({ accessToken, externalId, message, }) {
+        const resp = await fetch(graph(`/${externalId}/replies`), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ message, access_token: accessToken }),
+        });
+        const json = (await resp.json());
+        if (!resp.ok || !json.id) {
+            throw new Error(`InstagramEngage: reply ${resp.status} ${json.error?.message ?? ""}`.trim());
+        }
+        return { externalId: json.id };
+    }
+    async moderateComment({ accessToken, externalId, hidden, }) {
+        const resp = await fetch(graph(`/${externalId}`), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ hide: hidden, access_token: accessToken }),
+        });
+        if (!resp.ok) {
+            const json = (await resp.json().catch(() => ({})));
+            throw new Error(`InstagramEngage: hide ${resp.status} ${json.error?.message ?? ""}`.trim());
+        }
+    }
+}
+exports.InstagramEngageClient = InstagramEngageClient;
+/** Facebook Page post/video comment engagement. */
+class FacebookEngageClient {
+    constructor() {
+        this.provider = types_1.ESocialProvider.FACEBOOK;
+    }
+    async fetchComments({ accessToken, providerPostId, since, limit = 50, }) {
+        const tokenQs = `access_token=${encodeURIComponent(accessToken)}`;
+        const resp = await fetch(graph(`/${providerPostId}/comments?fields=id,message,from,created_time&limit=${Math.min(100, Math.max(1, limit))}&${tokenQs}`));
+        const json = (await resp.json());
+        if (!resp.ok || json.error) {
+            throw new Error(`FacebookEngage: comments ${resp.status} ${json.error?.message ?? ""}`.trim());
+        }
+        const out = [];
+        for (const c of json.data ?? []) {
+            if (!c.id)
+                continue;
+            const createdAt = (0, types_2.isoToMillis)(c.created_time);
+            if (since && createdAt <= since)
+                continue;
+            out.push({
+                externalId: c.id,
+                parentProviderPostId: providerPostId,
+                authorHandle: c.from?.id,
+                authorName: c.from?.name,
+                text: c.message ?? "",
+                createdAt,
+                type: types_1.ESocialInboxType.COMMENT,
+            });
+        }
+        return out;
+    }
+    async replyToComment({ accessToken, externalId, message, }) {
+        const resp = await fetch(graph(`/${externalId}/comments`), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ message, access_token: accessToken }),
+        });
+        const json = (await resp.json());
+        if (!resp.ok || !json.id) {
+            throw new Error(`FacebookEngage: reply ${resp.status} ${json.error?.message ?? ""}`.trim());
+        }
+        return { externalId: json.id };
+    }
+    async moderateComment({ accessToken, externalId, hidden, }) {
+        const resp = await fetch(graph(`/${externalId}`), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ is_hidden: hidden, access_token: accessToken }),
+        });
+        if (!resp.ok) {
+            const json = (await resp.json().catch(() => ({})));
+            throw new Error(`FacebookEngage: hide ${resp.status} ${json.error?.message ?? ""}`.trim());
+        }
+    }
+}
+exports.FacebookEngageClient = FacebookEngageClient;

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

@@ -0,0 +1,50 @@
+import { ESocialProvider } from "../../globals/types";
+import { IRemoteComment } from "./types";
+/**
+ * Meta webhook helpers — Phase 5. Instagram + Facebook push comment/mention/DM
+ * events to our public `/v1/social/webhooks/meta` endpoint. Two concerns live
+ * here so the controller stays thin:
+ *
+ *  1. `verifyMetaSignature` — Meta signs every POST with HMAC-SHA256 of the raw
+ *     body using the app secret, in the `X-Hub-Signature-256` header. We MUST
+ *     verify it (the endpoint is public) before trusting anything.
+ *  2. `parseMetaWebhook` — flattens the nested `entry[].changes[]` envelope into
+ *     normalized `MetaWebhookEvent`s keyed by the providerAccountId (page/IG id)
+ *     so the controller can resolve the owning socialAccount and write inbox
+ *     items. Unknown change types are skipped (we only ingest comments today).
+ *
+ * Env: META_APP_SECRET (signature key), META_WEBHOOK_VERIFY_TOKEN (GET verify).
+ * See notes/SOCIAL_SUITE_PLAN.md §D / §6 Phase 5.
+ */
+/** A normalized webhook event tied to the account that owns it. */
+export interface MetaWebhookEvent {
+    provider: ESocialProvider;
+    /** The page id (FB) or IG user id the event belongs to — matches our account. */
+    providerAccountId: string;
+    comment: IRemoteComment;
+}
+/**
+ * Verify the `X-Hub-Signature-256` header against the raw request body. Returns
+ * false on any mismatch/missing-secret rather than throwing, so the caller can
+ * respond 403 uniformly. `rawBody` MUST be the exact bytes Meta sent (mount a
+ * raw-body capture on the webhook route — JSON.stringify of a parsed body will
+ * not match).
+ */
+export declare function verifyMetaSignature(rawBody: Buffer | string, signatureHeader: string | undefined): boolean;
+/**
+ * Handle the GET verification handshake Meta performs when you register a
+ * webhook. Returns the challenge string to echo (200) when the verify token
+ * matches, else null (caller responds 403).
+ */
+export declare function verifyMetaSubscription(query: {
+    "hub.mode"?: string;
+    "hub.verify_token"?: string;
+    "hub.challenge"?: string;
+}): string | null;
+/**
+ * Flatten a verified Meta webhook body into normalized comment events. `object`
+ * tells us the platform: "instagram" → IG, "page" → Facebook. Only `comments`
+ * (and IG `mentions`) changes are ingested today; everything else is ignored.
+ */
+export declare function parseMetaWebhook(body: unknown): MetaWebhookEvent[];
+//# sourceMappingURL=metaWebhook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metaWebhook.d.ts","sourceRoot":"","sources":["../../../src/services/socialEngage/metaWebhook.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;;;;;;;;;GAeG;AAEH,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,eAAe,CAAC;IAC1B,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,OAAO,CAYT;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,MAAM,GAAG,IAAI,CAUhB;AAyBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,EAAE,CA8ClE"}