vidspotai-shared 1.0.82-dev.0 → 1.0.83

package/lib/services/socialEngage/metaWebhook.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyMetaSignature = verifyMetaSignature;
+exports.verifyMetaSubscription = verifyMetaSubscription;
+exports.parseMetaWebhook = parseMetaWebhook;
+const crypto_1 = require("crypto");
+const types_1 = require("../../globals/types");
+/**
+ * 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).
+ */
+function verifyMetaSignature(rawBody, signatureHeader) {
+    const secret = process.env.META_APP_SECRET;
+    if (!secret || !signatureHeader)
+        return false;
+    const expected = "sha256=" +
+        (0, crypto_1.createHmac)("sha256", secret)
+            .update(typeof rawBody === "string" ? Buffer.from(rawBody) : rawBody)
+            .digest("hex");
+    const a = Buffer.from(expected);
+    const b = Buffer.from(signatureHeader);
+    if (a.length !== b.length)
+        return false;
+    return (0, crypto_1.timingSafeEqual)(a, b);
+}
+/**
+ * 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).
+ */
+function verifyMetaSubscription(query) {
+    const token = process.env.META_WEBHOOK_VERIFY_TOKEN;
+    if (query["hub.mode"] === "subscribe" &&
+        token &&
+        query["hub.verify_token"] === token) {
+        return query["hub.challenge"] ?? "";
+    }
+    return 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.
+ */
+function parseMetaWebhook(body) {
+    const parsed = body;
+    const provider = parsed.object === "instagram"
+        ? types_1.ESocialProvider.INSTAGRAM
+        : parsed.object === "page"
+            ? types_1.ESocialProvider.FACEBOOK
+            : null;
+    if (!provider)
+        return [];
+    const events = [];
+    for (const entry of parsed.entry ?? []) {
+        const providerAccountId = entry.id;
+        if (!providerAccountId)
+            continue;
+        for (const change of entry.changes ?? []) {
+            const isComment = change.field === "comments" || change.field === "mentions";
+            if (!isComment)
+                continue;
+            const v = change.value ?? {};
+            const externalId = v.comment_id ?? v.id;
+            if (!externalId)
+                continue;
+            const createdMs = typeof v.created_time === "number"
+                ? v.created_time * 1000 // Meta sends unix seconds
+                : typeof entry.time === "number"
+                    ? entry.time * 1000
+                    : 0;
+            events.push({
+                provider,
+                providerAccountId,
+                comment: {
+                    externalId,
+                    parentProviderPostId: v.media?.id ?? v.post_id,
+                    authorHandle: v.from?.username ?? v.from?.id,
+                    authorName: v.from?.name ?? v.from?.username,
+                    text: v.text ?? v.message ?? "",
+                    createdAt: createdMs,
+                    type: change.field === "mentions"
+                        ? types_1.ESocialInboxType.MENTION
+                        : types_1.ESocialInboxType.COMMENT,
+                },
+            });
+        }
+    }
+    return events;
+}

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

@@ -0,0 +1,72 @@
+import { ESocialInboxType, ESocialProvider } from "../../globals/types";
+/**
+ * X8 Social Suite — Phase 5 engagement (inbox) client abstraction. Mirrors the
+ * socialMetrics/socialPublish adapter shape: one thin implementation per
+ * platform behind a single interface, registered in a factory. Comments arrive
+ * two ways — Meta PUSHES them via webhooks (~1–5s), while YouTube has no comment
+ * webhook so the metrics-style poll sweep PULLS them. Either way the provider
+ * payload is normalized into `IRemoteComment`, which the controller/sweep maps
+ * onto the `socialInbox` model. See notes/SOCIAL_SUITE_PLAN.md §D.
+ *
+ * TikTok comment read/reply is Business-API-only, so it is intentionally absent
+ * here (plan §6 — TikTok engage deferred).
+ */
+/** A comment/mention/DM as returned by a provider, before we persist it. */
+export interface IRemoteComment {
+    /** Provider's stable id for this comment (used for reply + dedupe). */
+    externalId: string;
+    /** The post this relates to (provider post id), when known. */
+    parentProviderPostId?: string;
+    authorHandle?: string;
+    authorName?: string;
+    text: string;
+    /** Unix ms the comment was created. */
+    createdAt: number;
+    type: ESocialInboxType;
+}
+export interface FetchCommentsInput {
+    /** Cleartext access token for the owning account (already refreshed). */
+    accessToken: string;
+    /** Provider's post/video id whose comments we want. */
+    providerPostId: string;
+    /** Only return comments newer than this unix-ms (incremental poll). */
+    since?: number;
+    /** Soft cap on how many to return per poll. */
+    limit?: number;
+}
+export interface ReplyInput {
+    /** Cleartext access token for the owning account (already refreshed). */
+    accessToken: string;
+    /** Provider id of the comment/thread we're replying to. */
+    externalId: string;
+    message: string;
+    /** Provider post id — some platforms need it alongside the comment id. */
+    providerPostId?: string;
+}
+export interface ReplyResult {
+    /** Provider id of the reply we just created. */
+    externalId: string;
+}
+export interface ModerateInput {
+    /** Cleartext access token for the owning account (already refreshed). */
+    accessToken: string;
+    /** Provider id of the comment to hide/unhide. */
+    externalId: string;
+    /** true → hide, false → unhide. */
+    hidden: boolean;
+}
+export interface ISocialEngageClient {
+    readonly provider: ESocialProvider;
+    /** Pull recent comments for a published post (used by the poll sweep). */
+    fetchComments(input: FetchCommentsInput): Promise<IRemoteComment[]>;
+    /** Post a reply to a comment. */
+    replyToComment(input: ReplyInput): Promise<ReplyResult>;
+    /**
+     * Hide/unhide a comment (moderation). Optional — providers without a
+     * moderation API simply omit it and the caller degrades to "reply only".
+     */
+    moderateComment?(input: ModerateInput): Promise<void>;
+}
+/** Parse an ISO-8601 timestamp into unix ms, defaulting to 0 on garbage. */
+export declare function isoToMillis(iso: string | undefined): number;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/socialEngage/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAExE;;;;;;;;;;;GAWG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,0EAA0E;IAC1E,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACpE,iCAAiC;IACjC,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACxD;;;OAGG;IACH,eAAe,CAAC,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI3D"}

package/lib/services/socialEngage/types.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isoToMillis = isoToMillis;
+/** Parse an ISO-8601 timestamp into unix ms, defaulting to 0 on garbage. */
+function isoToMillis(iso) {
+    if (!iso)
+        return 0;
+    const ms = Date.parse(iso);
+    return Number.isFinite(ms) ? ms : 0;
+}

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

@@ -0,0 +1,9 @@
+import { ESocialProvider } from "../../globals/types";
+import { FetchCommentsInput, IRemoteComment, ISocialEngageClient, ModerateInput, ReplyInput, ReplyResult } from "./types";
+export declare class YouTubeEngageClient implements ISocialEngageClient {
+    readonly provider = ESocialProvider.YOUTUBE;
+    fetchComments({ accessToken, providerPostId, since, limit, }: FetchCommentsInput): Promise<IRemoteComment[]>;
+    replyToComment({ accessToken, externalId, message, }: ReplyInput): Promise<ReplyResult>;
+    moderateComment({ accessToken, externalId, hidden, }: ModerateInput): Promise<void>;
+}
+//# sourceMappingURL=youtube.engage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"youtube.engage.d.ts","sourceRoot":"","sources":["../../../src/services/socialEngage/youtube.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;AAiCjB,qBAAa,mBAAoB,YAAW,mBAAmB;IAC7D,QAAQ,CAAC,QAAQ,2BAA2B;IAEtC,aAAa,CAAC,EAClB,WAAW,EACX,cAAc,EACd,KAAK,EACL,KAAU,GACX,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAkC3C,cAAc,CAAC,EACnB,WAAW,EACX,UAAU,EACV,OAAO,GACR,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAoB9B,eAAe,CAAC,EACpB,WAAW,EACX,UAAU,EACV,MAAM,GACP,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBjC"}

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

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YouTubeEngageClient = void 0;
+const types_1 = require("../../globals/types");
+const types_2 = require("./types");
+/**
+ * YouTube engagement client. YouTube has NO comment webhook, so the poll sweep
+ * pulls `commentThreads` for each published video on a schedule. Replies use
+ * `comments.insert` (needs the `youtube.force-ssl` scope, which our publish
+ * scope already includes). Moderation maps "hide" → setModerationStatus
+ * `rejected` (channel-owner only). See notes/SOCIAL_SUITE_PLAN.md §D.
+ */
+const API = "https://www.googleapis.com/youtube/v3";
+class YouTubeEngageClient {
+    constructor() {
+        this.provider = types_1.ESocialProvider.YOUTUBE;
+    }
+    async fetchComments({ accessToken, providerPostId, since, limit = 50, }) {
+        const max = Math.min(100, Math.max(1, limit));
+        const url = `${API}/commentThreads?part=snippet&order=time&textFormat=plainText` +
+            `&maxResults=${max}&videoId=${encodeURIComponent(providerPostId)}`;
+        const resp = await fetch(url, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!resp.ok) {
+            // Comments disabled / video private surfaces as 403 — treat as "none".
+            if (resp.status === 403 || resp.status === 404)
+                return [];
+            throw new Error(`YouTubeEngage: commentThreads ${resp.status}`);
+        }
+        const json = (await resp.json());
+        const out = [];
+        for (const item of json.items ?? []) {
+            const top = item.snippet?.topLevelComment;
+            const s = top?.snippet;
+            if (!top?.id || !s)
+                continue;
+            const createdAt = (0, types_2.isoToMillis)(s.publishedAt);
+            if (since && createdAt <= since)
+                continue;
+            out.push({
+                externalId: top.id,
+                parentProviderPostId: providerPostId,
+                authorHandle: s.authorChannelId?.value,
+                authorName: s.authorDisplayName,
+                text: s.textDisplay ?? "",
+                createdAt,
+                type: types_1.ESocialInboxType.COMMENT,
+            });
+        }
+        return out;
+    }
+    async replyToComment({ accessToken, externalId, message, }) {
+        const resp = await fetch(`${API}/comments?part=snippet`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                snippet: { parentId: externalId, textOriginal: message },
+            }),
+        });
+        const json = (await resp.json());
+        if (!resp.ok || !json.id) {
+            throw new Error(`YouTubeEngage: comments.insert ${resp.status} ${json.error?.message ?? ""}`.trim());
+        }
+        return { externalId: json.id };
+    }
+    async moderateComment({ accessToken, externalId, hidden, }) {
+        // YouTube has no "unhide"; rejecting removes from public view. Unhide would
+        // require the comment to be re-published, which the API doesn't expose for
+        // arbitrary comments — so unhide is a no-op (status stays as the user left it).
+        if (!hidden)
+            return;
+        const url = `${API}/comments/setModerationStatus` +
+            `?id=${encodeURIComponent(externalId)}&moderationStatus=rejected`;
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!resp.ok) {
+            throw new Error(`YouTubeEngage: setModerationStatus ${resp.status}`);
+        }
+    }
+}
+exports.YouTubeEngageClient = YouTubeEngageClient;

package/lib/services/socialFormat/aspectGeometry.d.ts

@@ -0,0 +1,74 @@
+/**
+ * X8 Social Suite — B2 auto-format geometry.
+ *
+ * Pure, dependency-free math for re-framing an already-rendered video into a
+ * platform's recommended aspect. Lives in `shared` (not the node app) so it is
+ * unit-testable and reused by both the publish worker and any future preview UI.
+ *
+ * The plan's intent (SOCIAL_SUITE_PLAN.md §4 B2): *don't re-encode blindly* — but
+ * for plain generated videos we only have the stitched MP4 (no Project JSON), so
+ * the reframe is an ffmpeg scale+crop/pad transform here rather than a Remotion
+ * re-render. Agent projects that DO carry Project JSON can later route through
+ * the Remotion path; this module only computes target dimensions + the ffmpeg
+ * filter, so both callers share the same geometry.
+ *
+ * Two modes:
+ *   - "cover"  (default) — scale to fill the target frame, then center-crop the
+ *                overflow. No bars; loses edge content. This is what Reels/Shorts
+ *                auto-format expects. (Smart/face-aware crop is deferred — v1 is
+ *                a center crop.)
+ *   - "contain" — scale to fit inside the target frame, then pad (letterbox /
+ *                pillarbox) with a solid colour. Preserves all content; adds bars.
+ */
+export type EReframeMode = "cover" | "contain";
+/** Aspects the composer can request (mirrors AspectSchema + a few publish-only ratios). */
+export declare const SUPPORTED_ASPECTS: readonly ["9:16", "1:1", "4:5", "16:9", "4:3", "3:4"];
+export type SupportedAspect = (typeof SUPPORTED_ASPECTS)[number];
+/** Parse "9:16" → { w: 9, h: 16 }. Throws on malformed input (validated upstream by zod). */
+export declare function parseAspect(aspect: string): {
+    w: number;
+    h: number;
+};
+/** Numeric width/height ratio of an aspect string (e.g. "16:9" → 1.777…). */
+export declare function aspectRatio(aspect: string): number;
+/**
+ * Target output dimensions for an aspect. Uses the canonical table when known;
+ * otherwise derives a ~1080-class box from the parsed ratio so any zod-valid
+ * "W:H" still produces sane even dimensions.
+ */
+export declare function targetSizeFor(aspect: string): {
+    width: number;
+    height: number;
+};
+/**
+ * Whether a source of (srcW × srcH) needs re-framing to hit `targetAspect`.
+ * Returns false when the source ratio already matches within `tolerance`
+ * (default 1%) — the publish worker then skips the render and publishes the
+ * source as-is (no wasted transcode, no quality loss).
+ */
+export declare function needsReframe(srcWidth: number, srcHeight: number, targetAspect: string, tolerance?: number): boolean;
+/**
+ * Build the ffmpeg `-vf` filter string that reframes a source of (srcW × srcH)
+ * into (dstW × dstH) using the chosen mode. SAR is reset to 1 so non-square
+ * source pixels don't skew the output.
+ *
+ * cover:  scale to the smallest size that fully covers the target (increase),
+ *         then center-crop to exact target dimensions.
+ * contain: scale to the largest size that fits inside (decrease), then pad the
+ *         remainder centred with `padColor`.
+ */
+export declare function buildReframeFilter(dstWidth: number, dstHeight: number, mode?: EReframeMode, padColor?: string): string;
+/**
+ * One-shot geometry resolution for a reframe job: given the probed source
+ * dimensions and a requested aspect, return the target dimensions, whether a
+ * reframe is actually required, and the ready-to-use ffmpeg filter. The worker
+ * calls this and either skips (when `reframe` is false) or runs ffmpeg with
+ * `filter`.
+ */
+export declare function resolveReframe(srcWidth: number, srcHeight: number, targetAspect: string, mode?: EReframeMode): {
+    width: number;
+    height: number;
+    reframe: boolean;
+    filter: string;
+};
+//# sourceMappingURL=aspectGeometry.d.ts.map

package/lib/services/socialFormat/aspectGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aspectGeometry.d.ts","sourceRoot":"","sources":["../../../src/services/socialFormat/aspectGeometry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/C,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,uDAAwD,CAAC;AACvF,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAgBjE,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAOpE;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGlD;AAOD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAS/E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,SAAO,GACf,OAAO,CAKT;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,YAAsB,EAC5B,QAAQ,SAAU,GACjB,MAAM,CAaR;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,IAAI,GAAE,YAAsB,GAC3B;IACD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAQA"}

package/lib/services/socialFormat/aspectGeometry.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * X8 Social Suite — B2 auto-format geometry.
+ *
+ * Pure, dependency-free math for re-framing an already-rendered video into a
+ * platform's recommended aspect. Lives in `shared` (not the node app) so it is
+ * unit-testable and reused by both the publish worker and any future preview UI.
+ *
+ * The plan's intent (SOCIAL_SUITE_PLAN.md §4 B2): *don't re-encode blindly* — but
+ * for plain generated videos we only have the stitched MP4 (no Project JSON), so
+ * the reframe is an ffmpeg scale+crop/pad transform here rather than a Remotion
+ * re-render. Agent projects that DO carry Project JSON can later route through
+ * the Remotion path; this module only computes target dimensions + the ffmpeg
+ * filter, so both callers share the same geometry.
+ *
+ * Two modes:
+ *   - "cover"  (default) — scale to fill the target frame, then center-crop the
+ *                overflow. No bars; loses edge content. This is what Reels/Shorts
+ *                auto-format expects. (Smart/face-aware crop is deferred — v1 is
+ *                a center crop.)
+ *   - "contain" — scale to fit inside the target frame, then pad (letterbox /
+ *                pillarbox) with a solid colour. Preserves all content; adds bars.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_ASPECTS = void 0;
+exports.parseAspect = parseAspect;
+exports.aspectRatio = aspectRatio;
+exports.targetSizeFor = targetSizeFor;
+exports.needsReframe = needsReframe;
+exports.buildReframeFilter = buildReframeFilter;
+exports.resolveReframe = resolveReframe;
+/** Aspects the composer can request (mirrors AspectSchema + a few publish-only ratios). */
+exports.SUPPORTED_ASPECTS = ["9:16", "1:1", "4:5", "16:9", "4:3", "3:4"];
+/**
+ * Canonical upload dimensions per aspect — the resolution each platform
+ * recommends. Even-numbered (h264 requires even width/height). Portrait/Reels
+ * caps the long edge at 1920 (1080×1920); square/landscape use 1080-class.
+ */
+const CANONICAL_SIZE = {
+    "9:16": { width: 1080, height: 1920 },
+    "16:9": { width: 1920, height: 1080 },
+    "1:1": { width: 1080, height: 1080 },
+    "4:5": { width: 1080, height: 1350 },
+    "4:3": { width: 1440, height: 1080 },
+    "3:4": { width: 1080, height: 1440 },
+};
+/** Parse "9:16" → { w: 9, h: 16 }. Throws on malformed input (validated upstream by zod). */
+function parseAspect(aspect) {
+    const m = /^(\d{1,2}):(\d{1,2})$/.exec(aspect.trim());
+    if (!m)
+        throw new Error(`invalid aspect "${aspect}"`);
+    const w = Number(m[1]);
+    const h = Number(m[2]);
+    if (!w || !h)
+        throw new Error(`invalid aspect "${aspect}"`);
+    return { w, h };
+}
+/** Numeric width/height ratio of an aspect string (e.g. "16:9" → 1.777…). */
+function aspectRatio(aspect) {
+    const { w, h } = parseAspect(aspect);
+    return w / h;
+}
+/** Round to the nearest even integer (h264 demands even pixel dimensions). */
+function even(n) {
+    return Math.max(2, 2 * Math.round(n / 2));
+}
+/**
+ * Target output dimensions for an aspect. Uses the canonical table when known;
+ * otherwise derives a ~1080-class box from the parsed ratio so any zod-valid
+ * "W:H" still produces sane even dimensions.
+ */
+function targetSizeFor(aspect) {
+    const known = CANONICAL_SIZE[aspect];
+    if (known)
+        return known;
+    const { w, h } = parseAspect(aspect);
+    // Base the shorter side on 1080 and scale the longer side off the ratio.
+    if (w >= h) {
+        return { width: even((1080 * w) / h), height: 1080 };
+    }
+    return { width: 1080, height: even((1080 * h) / w) };
+}
+/**
+ * Whether a source of (srcW × srcH) needs re-framing to hit `targetAspect`.
+ * Returns false when the source ratio already matches within `tolerance`
+ * (default 1%) — the publish worker then skips the render and publishes the
+ * source as-is (no wasted transcode, no quality loss).
+ */
+function needsReframe(srcWidth, srcHeight, targetAspect, tolerance = 0.01) {
+    if (!srcWidth || !srcHeight)
+        return true;
+    const src = srcWidth / srcHeight;
+    const target = aspectRatio(targetAspect);
+    return Math.abs(src - target) / target > tolerance;
+}
+/**
+ * Build the ffmpeg `-vf` filter string that reframes a source of (srcW × srcH)
+ * into (dstW × dstH) using the chosen mode. SAR is reset to 1 so non-square
+ * source pixels don't skew the output.
+ *
+ * cover:  scale to the smallest size that fully covers the target (increase),
+ *         then center-crop to exact target dimensions.
+ * contain: scale to the largest size that fits inside (decrease), then pad the
+ *         remainder centred with `padColor`.
+ */
+function buildReframeFilter(dstWidth, dstHeight, mode = "cover", padColor = "black") {
+    if (mode === "contain") {
+        return [
+            `scale=${dstWidth}:${dstHeight}:force_original_aspect_ratio=decrease`,
+            `pad=${dstWidth}:${dstHeight}:(ow-iw)/2:(oh-ih)/2:color=${padColor}`,
+            `setsar=1`,
+        ].join(",");
+    }
+    return [
+        `scale=${dstWidth}:${dstHeight}:force_original_aspect_ratio=increase`,
+        `crop=${dstWidth}:${dstHeight}`,
+        `setsar=1`,
+    ].join(",");
+}
+/**
+ * One-shot geometry resolution for a reframe job: given the probed source
+ * dimensions and a requested aspect, return the target dimensions, whether a
+ * reframe is actually required, and the ready-to-use ffmpeg filter. The worker
+ * calls this and either skips (when `reframe` is false) or runs ffmpeg with
+ * `filter`.
+ */
+function resolveReframe(srcWidth, srcHeight, targetAspect, mode = "cover") {
+    const { width, height } = targetSizeFor(targetAspect);
+    return {
+        width,
+        height,
+        reframe: needsReframe(srcWidth, srcHeight, targetAspect),
+        filter: buildReframeFilter(width, height, mode),
+    };
+}

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

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

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

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

package/lib/services/socialFormat/index.js

@@ -0,0 +1,19 @@
+"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 });
+// X8 Social Suite — B2 auto-format. Pure geometry shared by the publish worker
+// (ffmpeg reframe) and any future per-platform preview. See aspectGeometry.ts.
+__exportStar(require("./aspectGeometry"), exports);

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

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

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

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

package/lib/services/socialInsights/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("./timeBuckets"), exports);
+__exportStar(require("./recommendations"), exports);