vidspotai-shared 1.0.82 → 1.0.83

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);

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

@@ -0,0 +1,131 @@
+import { ESocialProvider } from "../../globals/types";
+/**
+ * X8 Social Suite — Phase 6 C5 (growth insights / recommendations) + E5
+ * (content ideas). Two halves, deliberately split:
+ *
+ *   1. `deriveInsightSignals()` — PURE, deterministic stats over the user's OWN
+ *      posts + snapshots. Every number the user sees is computed here, never by
+ *      the model. This is the anti-hallucination guarantee: the LLM is handed
+ *      finished facts ("Instagram averages 2.1× your YouTube views over 6
+ *      posts") and only phrases them — it can't invent a stat.
+ *   2. `generateRecommendationsCore(llm, …)` — turns those grounded facts into a
+ *      short weekly-digest summary, concrete recommendations (C5), and next-post
+ *      content ideas (E5). Defensive parse; degrades to the deterministic facts
+ *      when the model misbehaves, so the panel always renders something true.
+ *
+ * Same `*Core(llm,…)` convention as captionGen/hookScore — unit-/eval-testable.
+ */
+/** A published post reduced to the fields insights need (no Firestore types). */
+export interface IInsightPost {
+    postId: string;
+    /** The primary provider this post went to (first target's provider). */
+    provider: ESocialProvider;
+    /** Publish time in unix ms (or createdAt fallback). */
+    publishedAtMs: number;
+    /** Caption (used only for the top-post snippet — never invented). */
+    caption?: string;
+    /** Source video length in seconds, when cheaply known (drives the length cut). */
+    durationSec?: number;
+}
+/** A latest-per-surface metric row reduced to what insights need. */
+export interface IInsightMetricRow {
+    socialPostId: string;
+    provider: ESocialProvider;
+    views: number;
+    /** likes + comments + shares + saves (precomputed engagement count). */
+    engagement: number;
+    saves: number;
+    shares: number;
+    comments: number;
+    likes: number;
+}
+export interface IInsightSignalsInput {
+    posts: IInsightPost[];
+    metrics: IInsightMetricRow[];
+    /** IANA zone for the timing signal; defaults to UTC. */
+    timeZone?: string;
+    /** "now" in unix ms — injected so the cadence math is testable/deterministic. */
+    nowMs: number;
+}
+export interface IProviderPerformance {
+    provider: ESocialProvider;
+    posts: number;
+    avgViews: number;
+    /** Engagement rate 0..1 (engagement / views), 0 when no views. */
+    engagementRate: number;
+}
+/** The structured, fully-derived signal set (every value computed, not guessed). */
+export interface IInsightSignals {
+    /** Posts that have at least one metric snapshot. */
+    measuredPosts: number;
+    overallAvgViews: number;
+    overallEngagementRate: number;
+    /** Per-provider performance, sorted by avgViews desc. */
+    providers: IProviderPerformance[];
+    /** Provider with the highest avgViews (min 2 posts), if any. */
+    topProvider: IProviderPerformance | null;
+    /** Best (weekday,hour) by avgViews in `timeZone` (min 2 posts), if any. */
+    bestTime: {
+        weekday: number;
+        hour: number;
+        avgViews: number;
+    } | null;
+    /** Dominant interaction type across all engagement, if any stands out. */
+    dominantInteraction: "saves" | "shares" | "comments" | "likes" | null;
+    /** Posts published in the trailing 7 / 30 days. */
+    postsLast7: number;
+    postsLast30: number;
+    /** Top post by views (id + caption snippet + views), if any. */
+    topPost: {
+        postId: string;
+        snippet: string;
+        views: number;
+    } | null;
+    /** Length cut: avg views for short(<30s)/mid(30-60s)/long(>60s), each ≥2 posts. */
+    lengthBuckets: {
+        bucket: "short" | "mid" | "long";
+        posts: number;
+        avgViews: number;
+    }[];
+    /** Human-readable grounded facts fed to the LLM (and a deterministic fallback). */
+    facts: string[];
+}
+/**
+ * Derive the deterministic signal set. Pure — no I/O, no `Date.now()` (the
+ * caller injects `nowMs`). Cold-start safe: returns zeros/nulls + empty facts
+ * when there's nothing measured yet.
+ */
+export declare function deriveInsightSignals(input: IInsightSignalsInput): IInsightSignals;
+/** The LLM-phrased digest. */
+export interface IGrowthRecommendations {
+    /** 1-2 sentence weekly-digest summary. */
+    summary: string;
+    /** Concrete, grounded recommendations (C5). */
+    recommendations: string[];
+    /** Next-post content ideas grounded in what's working (E5). */
+    contentIdeas: string[];
+}
+export type RecommendationsLlm = (messages: Array<{
+    role: "system" | "user";
+    content: string;
+}>) => Promise<string>;
+/** Build the chat prompt from the GROUNDED facts. Pure — no I/O. */
+export declare function buildRecommendationsPrompt(signals: IInsightSignals, language?: string): Array<{
+    role: "system" | "user";
+    content: string;
+}>;
+/**
+ * Parse the model's JSON into recommendations. Defensive: on malformed JSON it
+ * falls back to the deterministic facts as recommendations, so the panel always
+ * shows something TRUE (the facts can't be wrong — we computed them).
+ */
+export declare function parseRecommendations(raw: string, signals: IInsightSignals): IGrowthRecommendations;
+/**
+ * Generate growth recommendations with the LLM injected (testable). Phrases the
+ * pre-computed grounded signals; never throws on a bad response.
+ */
+export declare function generateRecommendationsCore(llm: RecommendationsLlm, args: {
+    signals: IInsightSignals;
+    language?: string;
+}): Promise<IGrowthRecommendations>;
+//# sourceMappingURL=recommendations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recommendations.d.ts","sourceRoot":"","sources":["../../../src/services/socialInsights/recommendations.ts"],"names":[],"mappings":"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"}

package/lib/services/socialInsights/recommendations.js

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveInsightSignals = deriveInsightSignals;
+exports.buildRecommendationsPrompt = buildRecommendationsPrompt;
+exports.parseRecommendations = parseRecommendations;
+exports.generateRecommendationsCore = generateRecommendationsCore;
+const timeBuckets_1 = require("./timeBuckets");
+const MIN_PROVIDER_SAMPLE = 2;
+const MIN_TIME_SAMPLE = 2;
+const MIN_LENGTH_SAMPLE = 2;
+function avg(nums) {
+    if (nums.length === 0)
+        return 0;
+    return nums.reduce((a, b) => a + b, 0) / nums.length;
+}
+function round1(n) {
+    return Math.round(n * 10) / 10;
+}
+/** First ~80 chars of a caption on one line — only the user's own words. */
+function snippet(caption) {
+    if (!caption)
+        return "";
+    const one = caption.replace(/\s+/g, " ").trim();
+    return one.length > 80 ? `${one.slice(0, 80)}…` : one;
+}
+/**
+ * Derive the deterministic signal set. Pure — no I/O, no `Date.now()` (the
+ * caller injects `nowMs`). Cold-start safe: returns zeros/nulls + empty facts
+ * when there's nothing measured yet.
+ */
+function deriveInsightSignals(input) {
+    const { posts, metrics, timeZone, nowMs } = input;
+    const viewsByPost = new Map();
+    const engByPost = new Map();
+    for (const m of metrics) {
+        viewsByPost.set(m.socialPostId, (viewsByPost.get(m.socialPostId) ?? 0) + m.views);
+        engByPost.set(m.socialPostId, (engByPost.get(m.socialPostId) ?? 0) + m.engagement);
+    }
+    // Only posts we actually have metrics for count toward averages.
+    const measured = posts.filter((p) => viewsByPost.has(p.postId));
+    const overallAvgViews = round1(avg(measured.map((p) => viewsByPost.get(p.postId) ?? 0)));
+    const totalViews = measured.reduce((a, p) => a + (viewsByPost.get(p.postId) ?? 0), 0);
+    const totalEng = measured.reduce((a, p) => a + (engByPost.get(p.postId) ?? 0), 0);
+    const overallEngagementRate = totalViews > 0 ? round1((totalEng / totalViews) * 1000) / 1000 : 0;
+    // Per-provider performance.
+    const byProvider = new Map();
+    for (const p of measured) {
+        const bucket = byProvider.get(p.provider) ?? { views: [], eng: 0, vws: 0 };
+        const v = viewsByPost.get(p.postId) ?? 0;
+        bucket.views.push(v);
+        bucket.vws += v;
+        bucket.eng += engByPost.get(p.postId) ?? 0;
+        byProvider.set(p.provider, bucket);
+    }
+    const providers = [...byProvider.entries()]
+        .map(([provider, b]) => ({
+        provider,
+        posts: b.views.length,
+        avgViews: round1(avg(b.views)),
+        engagementRate: b.vws > 0 ? round1((b.eng / b.vws) * 1000) / 1000 : 0,
+    }))
+        .sort((a, b) => b.avgViews - a.avgViews);
+    const topProvider = providers.find((p) => p.posts >= MIN_PROVIDER_SAMPLE) ?? null;
+    // Timing: best (weekday,hour) by avg views in the user's zone.
+    const timeGrid = new Map();
+    for (const p of measured) {
+        const { weekday, hour } = (0, timeBuckets_1.bucketLocal)(p.publishedAtMs, timeZone);
+        const key = `${weekday}:${hour}`;
+        const cell = timeGrid.get(key) ?? { views: 0, count: 0 };
+        cell.views += viewsByPost.get(p.postId) ?? 0;
+        cell.count += 1;
+        timeGrid.set(key, cell);
+    }
+    let bestTime = null;
+    for (const [key, cell] of timeGrid) {
+        if (cell.count < MIN_TIME_SAMPLE)
+            continue;
+        const a = cell.views / cell.count;
+        if (!bestTime || a > bestTime.avgViews) {
+            const [wd, hr] = key.split(":").map(Number);
+            bestTime = { weekday: wd, hour: hr, avgViews: round1(a) };
+        }
+    }
+    // Engagement composition — which interaction the audience favours.
+    const comp = { saves: 0, shares: 0, comments: 0, likes: 0 };
+    for (const m of metrics) {
+        comp.saves += m.saves;
+        comp.shares += m.shares;
+        comp.comments += m.comments;
+        comp.likes += m.likes;
+    }
+    const compTotal = comp.saves + comp.shares + comp.comments + comp.likes;
+    let dominantInteraction = null;
+    if (compTotal > 0) {
+        const entries = Object.entries(comp);
+        entries.sort((a, b) => b[1] - a[1]);
+        // Only call it "dominant" if it's a real lead (≥40% of all engagement and
+        // not a tie with the runner-up) — otherwise it's noise.
+        const [topKind, topVal] = entries[0];
+        if (topVal / compTotal >= 0.4 && topVal > (entries[1]?.[1] ?? 0)) {
+            dominantInteraction = topKind;
+        }
+    }
+    // Cadence.
+    const DAY = 24 * 60 * 60 * 1000;
+    const postsLast7 = posts.filter((p) => nowMs - p.publishedAtMs <= 7 * DAY).length;
+    const postsLast30 = posts.filter((p) => nowMs - p.publishedAtMs <= 30 * DAY).length;
+    // Top post by views.
+    let topPost = null;
+    for (const p of measured) {
+        const v = viewsByPost.get(p.postId) ?? 0;
+        if (!topPost || v > topPost.views) {
+            topPost = { postId: p.postId, snippet: snippet(p.caption), views: v };
+        }
+    }
+    // Length cut — only when durations are known for enough posts.
+    const lenBuckets = { short: [], mid: [], long: [] };
+    for (const p of measured) {
+        if (typeof p.durationSec !== "number" || p.durationSec <= 0)
+            continue;
+        const v = viewsByPost.get(p.postId) ?? 0;
+        if (p.durationSec < 30)
+            lenBuckets.short.push(v);
+        else if (p.durationSec <= 60)
+            lenBuckets.mid.push(v);
+        else
+            lenBuckets.long.push(v);
+    }
+    const lengthBuckets = [
+        ["short", lenBuckets.short],
+        ["mid", lenBuckets.mid],
+        ["long", lenBuckets.long],
+    ]
+        .filter(([, arr]) => arr.length >= MIN_LENGTH_SAMPLE)
+        .map(([bucket, arr]) => ({ bucket, posts: arr.length, avgViews: round1(avg(arr)) }));
+    // ── Grounded fact strings (this is what the LLM phrases) ────────────────
+    const facts = [];
+    if (measured.length > 0) {
+        facts.push(`Across ${measured.length} measured posts, average views = ${overallAvgViews}, average engagement rate = ${(overallEngagementRate * 100).toFixed(1)}%.`);
+    }
+    if (topProvider) {
+        const others = providers.filter((p) => p.provider !== topProvider.provider && p.posts >= 1);
+        const ratio = others.length > 0 && avg(others.map((o) => o.avgViews)) > 0
+            ? round1(topProvider.avgViews / avg(others.map((o) => o.avgViews)))
+            : null;
+        facts.push(`${topProvider.provider} is your strongest platform (${topProvider.avgViews} avg views over ${topProvider.posts} posts${ratio && ratio > 1 ? `, ~${ratio}× your other platforms` : ""}).`);
+    }
+    if (bestTime) {
+        facts.push(`Posts published on weekday ${bestTime.weekday} around ${bestTime.hour}:00 (local) average ${bestTime.avgViews} views — your best slot.`);
+    }
+    if (dominantInteraction) {
+        facts.push(`Your audience ${dominantInteraction} more than anything else — ${dominantInteraction} dominate your engagement mix.`);
+    }
+    for (const lb of lengthBuckets) {
+        facts.push(`${lb.bucket}-length videos (${lb.bucket === "short" ? "<30s" : lb.bucket === "mid" ? "30–60s" : ">60s"}) average ${lb.avgViews} views over ${lb.posts} posts.`);
+    }
+    facts.push(`Posting cadence: ${postsLast7} post(s) in the last 7 days, ${postsLast30} in the last 30.`);
+    if (topPost && topPost.snippet) {
+        facts.push(`Top post (${topPost.views} views): "${topPost.snippet}".`);
+    }
+    return {
+        measuredPosts: measured.length,
+        overallAvgViews,
+        overallEngagementRate,
+        providers,
+        topProvider,
+        bestTime,
+        dominantInteraction,
+        postsLast7,
+        postsLast30,
+        topPost,
+        lengthBuckets,
+        facts,
+    };
+}
+const MAX_REC = 5;
+const MAX_IDEA = 5;
+const MAX_LINE = 240;
+/** Build the chat prompt from the GROUNDED facts. Pure — no I/O. */
+function buildRecommendationsPrompt(signals, language = "en") {
+    const lang = (language || "en").trim();
+    const system = "You are a social-media growth strategist writing a creator's weekly " +
+        "digest. You are given GROUND-TRUTH stats already computed from the " +
+        "creator's own posts — treat them as facts and NEVER invent numbers or " +
+        "claims beyond them. Turn them into a crisp summary, specific " +
+        "recommendations, and concrete next-post content ideas grounded in what's " +
+        `already working for THIS creator. Write in language "${lang}". Reply with ` +
+        "ONLY a single JSON object — no prose, no code fences.";
+    const factBlock = signals.facts.length
+        ? signals.facts.map((f) => `- ${f}`).join("\n")
+        : "- (Not enough published history yet to compute trends.)";
+    const user = `Here are the creator's ground-truth stats:\n${factBlock}\n\n` +
+        "Write a 1-2 sentence summary, up to 5 specific recommendations (each tied " +
+        "to a stat above — what to do more/less of, when to post, which platform to " +
+        "lean into), and up to 5 next-post content ideas that build on what's " +
+        "working. If history is thin, say so plainly and give starter advice. Do " +
+        "not fabricate metrics.\n\n" +
+        "Reply with ONLY this JSON shape:\n" +
+        "{\n" +
+        '  "summary": "string",\n' +
+        '  "recommendations": ["..."],\n' +
+        '  "contentIdeas": ["..."]\n' +
+        "}";
+    return [
+        { role: "system", content: system },
+        { role: "user", content: user },
+    ];
+}
+function stripCodeFence(raw) {
+    const t = raw.trim();
+    if (!t.startsWith("```"))
+        return t;
+    return t.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
+}
+function normalizeList(raw, max) {
+    if (!Array.isArray(raw))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== "string")
+            continue;
+        const s = item.replace(/\s+/g, " ").trim().slice(0, MAX_LINE);
+        if (!s)
+            continue;
+        const key = s.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(s);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+/**
+ * Parse the model's JSON into recommendations. Defensive: on malformed JSON it
+ * falls back to the deterministic facts as recommendations, so the panel always
+ * shows something TRUE (the facts can't be wrong — we computed them).
+ */
+function parseRecommendations(raw, signals) {
+    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 {
+            summary: signals.measuredPosts > 0
+                ? "Here's what your own numbers say so far."
+                : "Publish a few posts to unlock growth insights.",
+            recommendations: signals.facts.slice(0, MAX_REC),
+            contentIdeas: [],
+        };
+    }
+    return {
+        summary: typeof obj.summary === "string"
+            ? obj.summary.replace(/\s+/g, " ").trim().slice(0, 400)
+            : "",
+        recommendations: normalizeList(obj.recommendations, MAX_REC),
+        contentIdeas: normalizeList(obj.contentIdeas, MAX_IDEA),
+    };
+}
+/**
+ * Generate growth recommendations with the LLM injected (testable). Phrases the
+ * pre-computed grounded signals; never throws on a bad response.
+ */
+async function generateRecommendationsCore(llm, args) {
+    const messages = buildRecommendationsPrompt(args.signals, args.language);
+    const raw = await llm(messages);
+    return parseRecommendations(raw, args.signals);
+}

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

@@ -0,0 +1,35 @@
+/**
+ * X8 Social Suite — Phase 6 best-time-to-post: per-user timezone bucketing.
+ *
+ * The best-time grid (C4) buckets each published post by (weekday, hour) and
+ * averages its views. v1 bucketed in UTC, which is wrong for the human question
+ * the feature answers — "what hour of *my* day should I post?". A creator in
+ * America/Los_Angeles posting at 6pm local was being filed under hour 02 (next
+ * day UTC), so the heatmap pointed at the wrong row AND the wrong column.
+ *
+ * This module is the pure, dependency-free core: given an epoch-ms timestamp and
+ * an IANA time-zone name, return the local weekday (0=Sun … 6=Sat) and hour
+ * (0–23). It uses `Intl.DateTimeFormat` (built into the runtime — no tz library)
+ * so it's deterministic and unit-testable away from any I/O. Invalid / absent
+ * zones fall back to UTC, preserving the old behaviour rather than throwing.
+ */
+/**
+ * Is `tz` a time zone the runtime's Intl can resolve? Empty / non-string / made
+ * up names return false (so the caller can fall back to UTC). Cheap enough to
+ * call per request — Intl caches its internal data.
+ */
+export declare function isValidTimeZone(tz: unknown): tz is string;
+/**
+ * Bucket an epoch-ms timestamp into a LOCAL (weekday, hour) pair for the given
+ * IANA time zone. Falls back to UTC when `timeZone` is missing or invalid.
+ *
+ * @param epochMs unix milliseconds (the post's publish time)
+ * @param timeZone IANA name (e.g. "America/New_York"); undefined → UTC
+ */
+export declare function bucketLocal(epochMs: number, timeZone?: string): {
+    weekday: number;
+    hour: number;
+};
+/** The zone actually used after validation (echoed back to the client). */
+export declare function resolveTimeZone(timeZone?: string): string;
+//# sourceMappingURL=timeBuckets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeBuckets.d.ts","sourceRoot":"","sources":["../../../src/services/socialInsights/timeBuckets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAUzD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAiBnC;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzD"}