vidspotai-shared 1.0.82-dev.0 → 1.0.83

package/lib/services/socialPublish/tiktok.publish.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TikTokPublisher = void 0;
+const types_1 = require("../../globals/types");
+const logger_1 = require("../../utils/logger");
+/**
+ * TikTok publisher — Content Posting API, PULL_FROM_URL direct post. Phase 6.
+ *
+ * Flow (plan §G, TikTok Content Posting API):
+ *   1. POST /v2/post/publish/video/init/  with source=PULL_FROM_URL + video_url
+ *      → { publish_id }
+ *   2. Poll /v2/post/publish/status/fetch/ until PUBLISH_COMPLETE / FAILED.
+ *
+ * Gates:
+ * - PULL_FROM_URL requires the media domain (our CDN) verified in the dev portal.
+ * - Until the Content Posting audit passes, `privacy_level` is forced to
+ *   SELF_ONLY (private) and the app can only post for test users. We map the
+ *   generic `privacy` to TikTok's enum and default to SELF_ONLY (safe pre-audit).
+ * - TikTok has NO native scheduling — the worker schedules via BullMQ delay.
+ */
+const INIT_ENDPOINT = "https://open.tiktokapis.com/v2/post/publish/video/init/";
+const STATUS_ENDPOINT = "https://open.tiktokapis.com/v2/post/publish/status/fetch/";
+const PRIVACY_VALUES = new Set([
+    "PUBLIC_TO_EVERYONE",
+    "MUTUAL_FOLLOW_FRIENDS",
+    "FOLLOWER_OF_CREATOR",
+    "SELF_ONLY",
+]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+class TikTokPublisher {
+    constructor() {
+        this.provider = types_1.ESocialProvider.TIKTOK;
+        this.maxPolls = 30;
+        this.pollDelayMs = 5000;
+    }
+    async publish(input) {
+        const title = this.buildTitle(input);
+        const privacyLevel = this.resolvePrivacy(input);
+        // 1. Init the direct post with PULL_FROM_URL.
+        const initResp = await fetch(INIT_ENDPOINT, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${input.accessToken}`,
+                "Content-Type": "application/json; charset=UTF-8",
+            },
+            body: JSON.stringify({
+                post_info: {
+                    title,
+                    privacy_level: privacyLevel,
+                    disable_duet: false,
+                    disable_comment: false,
+                    disable_stitch: false,
+                },
+                source_info: {
+                    source: "PULL_FROM_URL",
+                    video_url: input.mediaUrl,
+                },
+            }),
+        });
+        const init = (await initResp.json());
+        const publishId = init.data?.publish_id;
+        if (!initResp.ok || init.error?.code === "access_token_invalid" || !publishId) {
+            throw new Error(`TikTokPublisher: init ${initResp.status} ${init.error?.message ?? "no publish_id"}`);
+        }
+        // 2. Poll for completion.
+        const postId = await this.pollStatus(input.accessToken, publishId);
+        logger_1.logger.info("TikTokPublisher: published", { publishId, postId });
+        return {
+            providerPostId: postId ?? publishId,
+            // TikTok doesn't return a canonical web URL pre-audit; the worker can fill
+            // it once the post id resolves (profile-relative).
+            publishedUrl: undefined,
+        };
+    }
+    async pollStatus(accessToken, publishId) {
+        for (let i = 0; i < this.maxPolls; i++) {
+            await sleep(this.pollDelayMs);
+            const resp = await fetch(STATUS_ENDPOINT, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    "Content-Type": "application/json; charset=UTF-8",
+                },
+                body: JSON.stringify({ publish_id: publishId }),
+            });
+            const json = (await resp.json());
+            const status = json.data?.status;
+            if (status === "PUBLISH_COMPLETE") {
+                return json.data?.publicaly_available_post_id?.[0];
+            }
+            if (status === "FAILED") {
+                throw new Error(`TikTokPublisher: publish failed — ${json.data?.fail_reason ?? "unknown"}`);
+            }
+            // PROCESSING_* / SEND_TO_USER_INBOX → keep polling.
+        }
+        throw new Error("TikTokPublisher: timed out waiting for publish completion");
+    }
+    /** TikTok caption ("title") max ~2200 chars; merge hashtags inline. */
+    buildTitle(input) {
+        const tags = input.hashtags && input.hashtags.length
+            ? " " +
+                input.hashtags.map((h) => (h.startsWith("#") ? h : `#${h}`)).join(" ")
+            : "";
+        return `${input.caption ?? ""}${tags}`.trim().slice(0, 2200);
+    }
+    resolvePrivacy(input) {
+        const p = (input.privacy ?? "").toUpperCase();
+        if (PRIVACY_VALUES.has(p))
+            return p;
+        // Map common generic values; default SELF_ONLY (audit-safe).
+        if (p === "PUBLIC")
+            return "PUBLIC_TO_EVERYONE";
+        if (p === "PRIVATE")
+            return "SELF_ONLY";
+        return "SELF_ONLY";
+    }
+}
+exports.TikTokPublisher = TikTokPublisher;

package/lib/services/socialPublish/types.d.ts

@@ -0,0 +1,47 @@
+import { ESocialProvider } from "../../globals/types";
+/**
+ * X8 Social Suite — publisher abstraction. One implementation per platform turns
+ * a (mediaUrl, caption, options, accessToken) into a live post. The publish
+ * worker resolves a valid access token (refreshing if needed) and calls this.
+ * See notes/SOCIAL_SUITE_PLAN.md §4.
+ */
+export interface PublishInput {
+    /** Cleartext access token for the target account (already refreshed). */
+    accessToken: string;
+    /**
+     * The provider's account id (IG Business user id / FB Page id). Required by
+     * Meta publishers, which POST to `/{ig-user-id}/media` or `/{page-id}/videos`.
+     * YouTube ignores it (the access token already scopes to the channel).
+     */
+    providerAccountId?: string;
+    /** Public URL of the media to publish (rendered/cropped for the platform). */
+    mediaUrl: string;
+    /**
+     * Public URL of a poster/cover frame for the video. Optional and ignored by
+     * most publishers; Pinterest REQUIRES a cover image for video pins, so the
+     * worker should populate it (e.g. the videoJob's poster) when targeting
+     * Pinterest. When absent, the Pinterest publisher falls back to a key-frame.
+     */
+    thumbnailUrl?: string;
+    /** Caption / description text. */
+    caption: string;
+    /** Title (YouTube uses this; others ignore). */
+    title?: string;
+    /** Provider visibility value (e.g. "public" | "unlisted" | "private"). */
+    privacy?: string;
+    /** Unix ms for native scheduled publish where the platform supports it (YT). */
+    scheduledAt?: number;
+    /** Hashtags to merge into the caption per-platform convention. */
+    hashtags?: string[];
+}
+export interface PublishResult {
+    /** Provider's id for the new post. */
+    providerPostId: string;
+    /** Public URL of the live (or scheduled) post, when derivable. */
+    publishedUrl?: string;
+}
+export interface ISocialPublisher {
+    readonly provider: ESocialProvider;
+    publish(input: PublishInput): Promise<PublishResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/services/socialPublish/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/socialPublish/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACtD"}

package/lib/services/socialPublish/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/services/socialPublish/x.publish.d.ts

@@ -0,0 +1,12 @@
+import { ESocialProvider } from "../../globals/types";
+import { ISocialPublisher, PublishInput, PublishResult } from "./types";
+export declare class XPublisher implements ISocialPublisher {
+    readonly provider = ESocialProvider.X;
+    private readonly maxPolls;
+    publish(input: PublishInput): Promise<PublishResult>;
+    private uploadForm;
+    private pollMediaStatus;
+    /** X has a hard 280-char limit; trim caption + as many hashtags as fit. */
+    private buildText;
+}
+//# sourceMappingURL=x.publish.d.ts.map

package/lib/services/socialPublish/x.publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x.publish.d.ts","sourceRoot":"","sources":["../../../src/services/socialPublish/x.publish.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAkCxE,qBAAa,UAAW,YAAW,gBAAgB;IACjD,QAAQ,CAAC,QAAQ,qBAAqB;IAEtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAM;IAEzB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;YAoF5C,UAAU;YAoBV,eAAe;IAuB7B,2EAA2E;IAC3E,OAAO,CAAC,SAAS;CAalB"}

package/lib/services/socialPublish/x.publish.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XPublisher = void 0;
+const types_1 = require("../../globals/types");
+const logger_1 = require("../../utils/logger");
+/**
+ * X (Twitter) publisher — Phase 6. Chunked video upload (v1.1 media/upload,
+ * which accepts an OAuth 2.0 user-context bearer) then a v2 Tweet referencing
+ * the media id:
+ *   1. INIT     → media_id_string
+ *   2. APPEND   → upload each ≤5MB chunk (multipart)
+ *   3. FINALIZE → may return async processing_info
+ *   4. STATUS   → poll until state=succeeded
+ *   5. POST /2/tweets { text, media: { media_ids: [id] } }
+ *
+ * No native scheduling — the worker schedules via BullMQ delay. Caption is hard-
+ * capped at 280 chars (X's real limit), hashtags merged inline within that cap.
+ */
+const UPLOAD_ENDPOINT = "https://upload.twitter.com/1.1/media/upload.json";
+const TWEETS_ENDPOINT = "https://api.twitter.com/2/tweets";
+const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB, X's per-APPEND limit
+const TWEET_MAX = 280;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+class XPublisher {
+    constructor() {
+        this.provider = types_1.ESocialProvider.X;
+        this.maxPolls = 30;
+    }
+    async publish(input) {
+        const token = input.accessToken;
+        // 0. Fetch the media bytes.
+        const mediaResp = await fetch(input.mediaUrl);
+        if (!mediaResp.ok) {
+            throw new Error(`XPublisher: media fetch ${mediaResp.status}`);
+        }
+        const bytes = Buffer.from(await mediaResp.arrayBuffer());
+        // 1. INIT.
+        const init = (await this.uploadForm(token, {
+            command: "INIT",
+            total_bytes: String(bytes.length),
+            media_type: "video/mp4",
+            media_category: "tweet_video",
+        }));
+        const mediaId = init.media_id_string;
+        if (!mediaId) {
+            throw new Error(`XPublisher: INIT failed ${init.errors?.[0]?.message ?? ""}`);
+        }
+        // 2. APPEND each chunk.
+        let segment = 0;
+        for (let offset = 0; offset < bytes.length; offset += CHUNK_SIZE) {
+            const chunk = bytes.subarray(offset, offset + CHUNK_SIZE);
+            const form = new FormData();
+            form.append("command", "APPEND");
+            form.append("media_id", mediaId);
+            form.append("segment_index", String(segment));
+            form.append("media", new Blob([chunk]));
+            const resp = await fetch(UPLOAD_ENDPOINT, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${token}` },
+                body: form,
+            });
+            if (!resp.ok) {
+                throw new Error(`XPublisher: APPEND segment ${segment} ${resp.status}`);
+            }
+            segment++;
+        }
+        // 3. FINALIZE.
+        const finalize = (await this.uploadForm(token, {
+            command: "FINALIZE",
+            media_id: mediaId,
+        }));
+        // 4. Poll async processing if needed.
+        if (finalize.processing_info && finalize.processing_info.state !== "succeeded") {
+            await this.pollMediaStatus(token, mediaId, finalize.processing_info.check_after_secs);
+        }
+        // 5. Create the Tweet.
+        const tweetResp = await fetch(TWEETS_ENDPOINT, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                text: this.buildText(input),
+                media: { media_ids: [mediaId] },
+            }),
+        });
+        const tweet = (await tweetResp.json());
+        const tweetId = tweet.data?.id;
+        if (!tweetResp.ok || !tweetId) {
+            throw new Error(`XPublisher: create tweet ${tweetResp.status} ${tweet.errors?.[0]?.message ?? tweet.detail ?? ""}`.trim());
+        }
+        logger_1.logger.info("XPublisher: published", { tweetId });
+        return {
+            providerPostId: tweetId,
+            publishedUrl: `https://x.com/i/web/status/${tweetId}`,
+        };
+    }
+    async uploadForm(token, fields) {
+        const form = new FormData();
+        for (const [k, v] of Object.entries(fields))
+            form.append(k, v);
+        const resp = await fetch(UPLOAD_ENDPOINT, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}` },
+            body: form,
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`XPublisher: upload ${fields.command} ${resp.status} ${text}`);
+        }
+        return resp.json();
+    }
+    async pollMediaStatus(token, mediaId, firstDelaySecs) {
+        let delayMs = (firstDelaySecs ?? 3) * 1000;
+        for (let i = 0; i < this.maxPolls; i++) {
+            await sleep(delayMs);
+            const url = `${UPLOAD_ENDPOINT}?command=STATUS&media_id=${mediaId}`;
+            const resp = await fetch(url, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            const json = (await resp.json());
+            const state = json.processing_info?.state;
+            if (state === "succeeded")
+                return;
+            if (state === "failed") {
+                throw new Error("XPublisher: media processing failed");
+            }
+            delayMs = (json.processing_info?.check_after_secs ?? 3) * 1000;
+        }
+        throw new Error("XPublisher: timed out waiting for media processing");
+    }
+    /** X has a hard 280-char limit; trim caption + as many hashtags as fit. */
+    buildText(input) {
+        const caption = (input.caption ?? "").trim();
+        const tags = (input.hashtags ?? []).map((h) => h.startsWith("#") ? h : `#${h}`);
+        let text = caption;
+        for (const tag of tags) {
+            const candidate = text ? `${text} ${tag}` : tag;
+            if (candidate.length > TWEET_MAX)
+                break;
+            text = candidate;
+        }
+        return text.slice(0, TWEET_MAX);
+    }
+}
+exports.XPublisher = XPublisher;

package/lib/services/socialPublish/youtube.publish.d.ts

@@ -0,0 +1,9 @@
+import { ESocialProvider } from "../../globals/types";
+import { ISocialPublisher, PublishInput, PublishResult } from "./types";
+export declare class YouTubePublisher implements ISocialPublisher {
+    readonly provider = ESocialProvider.YOUTUBE;
+    publish(input: PublishInput): Promise<PublishResult>;
+    private resolvePrivacy;
+    private buildDescription;
+}
+//# sourceMappingURL=youtube.publish.d.ts.map

package/lib/services/socialPublish/youtube.publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"youtube.publish.d.ts","sourceRoot":"","sources":["../../../src/services/socialPublish/youtube.publish.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AA0BxE,qBAAa,gBAAiB,YAAW,gBAAgB;IACvD,QAAQ,CAAC,QAAQ,2BAA2B;IAEtC,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IA+E1D,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,gBAAgB;CAUzB"}

package/lib/services/socialPublish/youtube.publish.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YouTubePublisher = void 0;
+const types_1 = require("../../globals/types");
+const logger_1 = require("../../utils/logger");
+/**
+ * YouTube publisher — uploads a video via the Data API `videos.insert` resumable
+ * endpoint and sets visibility / native scheduling. Phase 1. See SOCIAL_SUITE_PLAN.md.
+ *
+ * Flow:
+ *   1. POST metadata to the resumable endpoint → get the upload session URL.
+ *   2. PUT the media bytes to that URL → get the video resource (with id).
+ *
+ * Scheduling: when `scheduledAt` is set, YouTube requires `privacyStatus=private`
+ * + `status.publishAt` (RFC3339); it auto-flips to public at that time.
+ *
+ * Quota: `videos.insert` is the expensive call against the shared 10k/day project
+ * quota — the worker should track burn (plan §3). Single-PUT upload is fine for
+ * short-form; switch to chunked upload if we publish very large long-form files.
+ */
+const RESUMABLE_INIT = "https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status";
+class YouTubePublisher {
+    constructor() {
+        this.provider = types_1.ESocialProvider.YOUTUBE;
+    }
+    async publish(input) {
+        const description = this.buildDescription(input);
+        const privacyStatus = this.resolvePrivacy(input);
+        const metadata = {
+            snippet: {
+                title: (input.title ?? input.caption ?? "VidSpot video").slice(0, 100),
+                description: description.slice(0, 5000),
+            },
+            status: {
+                privacyStatus,
+                selfDeclaredMadeForKids: false,
+                ...(input.scheduledAt
+                    ? { publishAt: new Date(input.scheduledAt).toISOString() }
+                    : {}),
+            },
+        };
+        // 1. Fetch the media bytes (the worker passes a public/rendered URL).
+        const mediaResp = await fetch(input.mediaUrl);
+        if (!mediaResp.ok) {
+            throw new Error(`YouTubePublisher: media fetch ${mediaResp.status} for ${input.mediaUrl}`);
+        }
+        const contentType = mediaResp.headers.get("content-type") ?? "video/mp4";
+        const bytes = Buffer.from(await mediaResp.arrayBuffer());
+        // 2. Init the resumable session.
+        const initResp = await fetch(RESUMABLE_INIT, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${input.accessToken}`,
+                "Content-Type": "application/json; charset=UTF-8",
+                "X-Upload-Content-Type": contentType,
+                "X-Upload-Content-Length": String(bytes.length),
+            },
+            body: JSON.stringify(metadata),
+        });
+        if (!initResp.ok) {
+            const text = await initResp.text();
+            throw new Error(`YouTubePublisher: resumable init ${initResp.status} ${text}`);
+        }
+        const uploadUrl = initResp.headers.get("location");
+        if (!uploadUrl) {
+            throw new Error("YouTubePublisher: no upload session URL returned");
+        }
+        // 3. Upload the bytes.
+        const uploadResp = await fetch(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "Content-Type": contentType,
+                "Content-Length": String(bytes.length),
+            },
+            body: bytes,
+        });
+        const result = (await uploadResp.json());
+        if (!uploadResp.ok || !result.id) {
+            throw new Error(`YouTubePublisher: upload failed ${uploadResp.status} ${result.error?.message ?? ""}`);
+        }
+        logger_1.logger.info("YouTubePublisher: published", {
+            videoId: result.id,
+            scheduled: Boolean(input.scheduledAt),
+        });
+        return {
+            providerPostId: result.id,
+            publishedUrl: `https://www.youtube.com/watch?v=${result.id}`,
+        };
+    }
+    resolvePrivacy(input) {
+        // Native scheduling requires private until publishAt fires.
+        if (input.scheduledAt)
+            return "private";
+        const p = (input.privacy ?? "public").toLowerCase();
+        return ["public", "unlisted", "private"].includes(p) ? p : "public";
+    }
+    buildDescription(input) {
+        const tags = input.hashtags && input.hashtags.length
+            ? "\n\n" +
+                input.hashtags
+                    .map((h) => (h.startsWith("#") ? h : `#${h}`))
+                    .join(" ")
+            : "";
+        return `${input.caption ?? ""}${tags}`;
+    }
+}
+exports.YouTubePublisher = YouTubePublisher;

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

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

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

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

package/lib/services/stock/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("./realPersonSafety"), exports);

package/lib/services/stock/realPersonSafety.d.ts

@@ -0,0 +1,99 @@
+/**
+ * S-1 — real-person safety screening for the internal stock library.
+ *
+ * The stock catalog (S-1/S-2/S-3) may surface free-tier user output as public
+ * "made on VidSpot" / inspiration content. Per ToS we must NEVER surface a
+ * video whose prompt or input imagery involves a *real, identifiable person*
+ * (privacy / likeness exposure). This module is the safety gate the candidate
+ * scanner (and later the S-2 tagger) runs before a video is even eligible for
+ * human review.
+ *
+ * Two independent signals, both via Gemini Flash (cheap, ~$0.00002/image):
+ *   1. `detectRealPersonNamesInText` — LLM scan of all prompt/title/VO text for
+ *      proper names of real people (celebrities, politicians, public figures,
+ *      or a specific named private individual). Generic descriptors
+ *      ("a woman", "the CEO", "a doctor"), brand names, and clearly-fictional
+ *      character names are NOT flagged.
+ *   2. `detectRealPersonInImage` — vision pass over an input/reference/poster
+ *      image asking whether it shows a real *photographic* human person (an
+ *      actual individual's likeness) vs. an illustration / 3D-render / clearly
+ *      AI-generated synthetic face.
+ *
+ * Fail-safe posture: any check that errors is reported with `error` set and
+ * `incomplete: true` on the combined result — the caller treats "could not
+ * confirm safe" as NOT cleared (never silently passes a video through).
+ *
+ * Pure + side-effect-free apart from the network call to Gemini. No Firestore,
+ * no writes — see `scripts/scanStockCandidates.ts` for orchestration.
+ */
+export interface RealPersonSafetyConfig {
+    /** Gemini / Google AI Studio API key. */
+    apiKey: string;
+    /** Override the model. Defaults to gemini-2.5-flash. */
+    model?: string;
+    /** Per-call timeout. Defaults to 30s. */
+    timeoutMs?: number;
+}
+export interface NameScanResult {
+    /** True when at least one real, identifiable person's name appears. */
+    flagged: boolean;
+    /** The specific real-person names found (best-effort, may be empty). */
+    names: string[];
+    /** Short rationale from the model. */
+    reason: string;
+    /** Set when the scan could not run; caller treats this as not-cleared. */
+    error?: string;
+}
+export interface ImagePersonResult {
+    imageUrl: string;
+    /** True when the image shows a real photographic human (a real likeness). */
+    containsRealPerson: boolean;
+    /** Model confidence 0..1. */
+    confidence: number;
+    reason: string;
+    /** Set when the check could not run; caller treats this as not-cleared. */
+    error?: string;
+}
+export interface VideoSafetyInput {
+    /** All free-text associated with the video: prompt, originalPrompt, title, ttsText, per-scene prompts. */
+    texts: string[];
+    /** Candidate likeness images: input/reference images + poster still. */
+    imageUrls: string[];
+}
+export interface VideoSafetyResult {
+    /** True once at least one screening signal actually ran. */
+    checked: boolean;
+    nameScan?: NameScanResult;
+    imageScans: ImagePersonResult[];
+    /** Final verdict: a real, identifiable person is involved → must be dropped. */
+    involvesRealPerson: boolean;
+    /** True when some signal errored, so "safe" could not be fully confirmed. */
+    incomplete: boolean;
+    /** Human-readable reasons backing the verdict / incompleteness. */
+    reasons: string[];
+}
+/**
+ * Scan all of a video's free text for references to real, identifiable people.
+ * Returns `flagged:false` for empty input. On error returns `flagged:false`
+ * with `error` set — the caller must treat a set `error` as not-cleared.
+ */
+export declare function detectRealPersonNamesInText(texts: string[], config: RealPersonSafetyConfig): Promise<NameScanResult>;
+/**
+ * Vision pass: does this single image show a real, identifiable photographic
+ * person? On any fetch/model error returns `containsRealPerson:false` with
+ * `error` set — caller treats a set `error` as not-cleared.
+ */
+export declare function detectRealPersonInImage(imageUrl: string, config: RealPersonSafetyConfig): Promise<ImagePersonResult>;
+export interface ScreenOptions {
+    /** Cap how many images get a (paid) vision call. Defaults to 4. */
+    maxImages?: number;
+}
+/**
+ * Run the full real-person screen for one video: name scan + per-image vision.
+ *
+ * `involvesRealPerson` is the OR of every positive signal. `incomplete` is true
+ * when any signal errored — callers must require `checked && !involvesRealPerson
+ * && !incomplete` before treating a video as a cleared stock candidate.
+ */
+export declare function screenForRealPerson(input: VideoSafetyInput, config: RealPersonSafetyConfig, opts?: ScreenOptions): Promise<VideoSafetyResult>;
+//# sourceMappingURL=realPersonSafety.d.ts.map

package/lib/services/stock/realPersonSafety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realPersonSafety.d.ts","sourceRoot":"","sources":["../../../src/services/stock/realPersonSafety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAQH,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,kBAAkB,EAAE,OAAO,CAAC;IAC5B,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,0GAA0G;IAC1G,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wEAAwE;IACxE,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,gFAAgF;IAChF,kBAAkB,EAAE,OAAO,CAAC;IAC5B,6EAA6E;IAC7E,UAAU,EAAE,OAAO,CAAC;IACpB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAuCD;;;;GAIG;AACH,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,cAAc,CAAC,CA6CzB;AA4BD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAyD5B;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,sBAAsB,EAC9B,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CA8C5B"}