vidspotai-shared 1.0.82-dev.0 → 1.0.83

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

package/lib/services/socialInsights/timeBuckets.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidTimeZone = isValidTimeZone;
+exports.bucketLocal = bucketLocal;
+exports.resolveTimeZone = resolveTimeZone;
+/** Sun-first weekday index, matching `Date.prototype.getUTCDay()`. */
+const WEEKDAY_INDEX = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+};
+/**
+ * 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.
+ */
+function isValidTimeZone(tz) {
+    if (typeof tz !== "string" || tz.trim() === "")
+        return false;
+    try {
+        // Throws RangeError for an unknown zone; succeeds (and is a no-op) for a
+        // valid one. "UTC" and offset-less IANA names both pass.
+        new Intl.DateTimeFormat("en-US", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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
+ */
+function bucketLocal(epochMs, timeZone) {
+    const tz = isValidTimeZone(timeZone) ? timeZone : "UTC";
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone: tz,
+        weekday: "short",
+        hour: "2-digit",
+        hour12: false,
+    }).formatToParts(new Date(epochMs));
+    let weekday = 0;
+    let hour = 0;
+    for (const p of parts) {
+        if (p.type === "weekday")
+            weekday = WEEKDAY_INDEX[p.value] ?? 0;
+        // `hour12:false` can emit "24" for midnight in some ICU builds — fold to 0.
+        else if (p.type === "hour")
+            hour = parseInt(p.value, 10) % 24;
+    }
+    return { weekday, hour };
+}
+/** The zone actually used after validation (echoed back to the client). */
+function resolveTimeZone(timeZone) {
+    return isValidTimeZone(timeZone) ? timeZone : "UTC";
+}

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

@@ -0,0 +1,5 @@
+import { ESocialProvider } from "../../globals/types";
+import { ISocialMetricsClient } from "./types";
+export declare function getSocialMetricsClient(provider: ESocialProvider): ISocialMetricsClient;
+export declare function isSocialMetricsSupported(provider: ESocialProvider): boolean;
+//# sourceMappingURL=factory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/services/socialMetrics/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAU/C,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,eAAe,GACxB,oBAAoB,CAMtB;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAE3E"}

package/lib/services/socialMetrics/factory.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSocialMetricsClient = getSocialMetricsClient;
+exports.isSocialMetricsSupported = isSocialMetricsSupported;
+const types_1 = require("../../globals/types");
+const meta_metrics_1 = require("./meta.metrics");
+const tiktok_metrics_1 = require("./tiktok.metrics");
+const youtube_metrics_1 = require("./youtube.metrics");
+const registry = {
+    [types_1.ESocialProvider.YOUTUBE]: () => new youtube_metrics_1.YouTubeMetricsClient(),
+    [types_1.ESocialProvider.INSTAGRAM]: () => new meta_metrics_1.InstagramMetricsClient(),
+    [types_1.ESocialProvider.FACEBOOK]: () => new meta_metrics_1.FacebookMetricsClient(),
+    [types_1.ESocialProvider.TIKTOK]: () => new tiktok_metrics_1.TikTokMetricsClient(),
+};
+function getSocialMetricsClient(provider) {
+    const make = registry[provider];
+    if (!make) {
+        throw new Error(`Social metrics not implemented for '${provider}'`);
+    }
+    return make();
+}
+function isSocialMetricsSupported(provider) {
+    return Boolean(registry[provider]);
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/socialMetrics/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC"}

package/lib/services/socialMetrics/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.metrics"), exports);
+__exportStar(require("./meta.metrics"), exports);
+__exportStar(require("./tiktok.metrics"), exports);
+__exportStar(require("./factory"), exports);

package/lib/services/socialMetrics/meta.metrics.d.ts

@@ -0,0 +1,22 @@
+import { ESocialProvider } from "../../globals/types";
+import { ISocialMetricSnapshot } from "../../models/social.model";
+import { AudienceInput, ISocialAudience, ISocialMetricsClient, MetricsInput } from "./types";
+/** Instagram media insights for a published Reel/media. */
+export declare class InstagramMetricsClient implements ISocialMetricsClient {
+    readonly provider = ESocialProvider.INSTAGRAM;
+    fetchPostMetrics({ accessToken, providerPostId, }: MetricsInput): Promise<ISocialMetricSnapshot>;
+    /**
+     * IG audience demographics via the account-level insights edge. Needs a
+     * business/creator account with ≥100 followers; otherwise Graph errors and we
+     * let the caller degrade to "not supported". `follower_demographics` returns
+     * a breakdown keyed by the requested dimension; `follower_count` (lifetime
+     * total) comes from the user node.
+     */
+    fetchAudience({ accessToken, providerAccountId, }: AudienceInput): Promise<ISocialAudience>;
+}
+/** Facebook Page video metrics via the video object summaries. */
+export declare class FacebookMetricsClient implements ISocialMetricsClient {
+    readonly provider = ESocialProvider.FACEBOOK;
+    fetchPostMetrics({ accessToken, providerPostId, }: MetricsInput): Promise<ISocialMetricSnapshot>;
+}
+//# sourceMappingURL=meta.metrics.d.ts.map

package/lib/services/socialMetrics/meta.metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.metrics.d.ts","sourceRoot":"","sources":["../../../src/services/socialMetrics/meta.metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EACL,aAAa,EAEb,eAAe,EACf,oBAAoB,EACpB,YAAY,EACb,MAAM,SAAS,CAAC;AAgCjB,2DAA2D;AAC3D,qBAAa,sBAAuB,YAAW,oBAAoB;IACjE,QAAQ,CAAC,QAAQ,6BAA6B;IAExC,gBAAgB,CAAC,EACrB,WAAW,EACX,cAAc,GACf,EAAE,YAAY,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAiDhD;;;;;;OAMG;IACG,aAAa,CAAC,EAClB,WAAW,EACX,iBAAiB,GAClB,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC;CAmD5C;AAoBD,kEAAkE;AAClE,qBAAa,qBAAsB,YAAW,oBAAoB;IAChE,QAAQ,CAAC,QAAQ,4BAA4B;IAEvC,gBAAgB,CAAC,EACrB,WAAW,EACX,cAAc,GACf,EAAE,YAAY,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAkBjD"}