thumbgate 0.9.9

package/scripts/social-analytics/publishers/zernio.js

@@ -0,0 +1,378 @@
+'use strict';
+
+/**
+ * zernio.js
+ * Unified publisher via Zernio API.
+ *
+ * Required env vars:
+ *   ZERNIO_API_KEY — Bearer token for https://zernio.com/api/v1
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { tagUrlsInText } = require('../utm');
+const { loadLocalEnv } = require('../load-env');
+
+const ZERNIO_UTM = { source: 'zernio', medium: 'social', campaign: 'organic' };
+
+const ZERNIO_BASE = 'https://zernio.com/api/v1';
+
+loadLocalEnv();
+
+function requireApiKey() {
+  const key = process.env.ZERNIO_API_KEY;
+  if (!key) {
+    throw new Error('ZERNIO_API_KEY environment variable is required');
+  }
+  return key;
+}
+
+function resolveAccountId(account) {
+  if (!account || typeof account !== 'object') {
+    return '';
+  }
+  return String(account.accountId || account._id || account.id || '').trim();
+}
+
+function normalizeAccount(account) {
+  if (!account || typeof account !== 'object') {
+    return null;
+  }
+  const platform = String(account.platform || '').trim();
+  const accountId = resolveAccountId(account);
+  return {
+    ...account,
+    platform,
+    accountId,
+  };
+}
+
+function normalizePlatforms(platforms) {
+  return platforms
+    .map(normalizeAccount)
+    .filter(Boolean)
+    .map((platform) => ({
+      platform: platform.platform,
+      accountId: platform.accountId,
+    }));
+}
+
+function groupAccountsByPlatform(accounts) {
+  const groups = new Map();
+  for (const account of accounts) {
+    if (!account || !account.platform || !account.accountId) {
+      continue;
+    }
+    const existing = groups.get(account.platform) || [];
+    existing.push({
+      platform: account.platform,
+      accountId: account.accountId,
+    });
+    groups.set(account.platform, existing);
+  }
+  return groups;
+}
+
+function inferContentType(filePath) {
+  const ext = path.extname(String(filePath || '')).toLowerCase();
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+  if (ext === '.png') return 'image/png';
+  if (ext === '.webp') return 'image/webp';
+  if (ext === '.gif') return 'image/gif';
+  if (ext === '.mp4') return 'video/mp4';
+  if (ext === '.mov') return 'video/quicktime';
+  if (ext === '.webm') return 'video/webm';
+  return 'application/octet-stream';
+}
+
+function inferMediaType(contentType) {
+  if (String(contentType || '').startsWith('video/')) {
+    return 'video';
+  }
+  return 'image';
+}
+
+function normalizePostResult(payload) {
+  const data = payload && typeof payload === 'object' ? (payload.data ?? payload) : {};
+  const post = data.post && typeof data.post === 'object' ? data.post : null;
+  const id = data.id || data._id || post?._id || post?.id || null;
+  return {
+    ...data,
+    id,
+    post: post || data.post,
+  };
+}
+
+async function zernioFetch(method, endpoint, body = null) {
+  const apiKey = requireApiKey();
+  const url = `${ZERNIO_BASE}${endpoint}`;
+
+  const options = {
+    method,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+  };
+
+  if (body !== null) {
+    options.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(url, options);
+
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => '');
+    throw new Error(`Zernio API ${res.status} for ${method} ${endpoint}: ${errorText}`);
+  }
+
+  return res.json();
+}
+
+async function requestMediaPresign(filename, contentType, size) {
+  if (!filename) throw new Error('requestMediaPresign: filename is required');
+  if (!contentType) throw new Error('requestMediaPresign: contentType is required');
+
+  const json = await zernioFetch('POST', '/media/presign', {
+    filename,
+    contentType,
+    size,
+  });
+
+  return json.data ?? json;
+}
+
+async function uploadLocalMedia(filePath, options = {}) {
+  const resolvedPath = path.resolve(String(filePath || ''));
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`uploadLocalMedia: file not found at ${resolvedPath}`);
+  }
+
+  const stats = fs.statSync(resolvedPath);
+  const filename = options.filename || path.basename(resolvedPath);
+  const contentType = options.contentType || inferContentType(resolvedPath);
+  const presign = await requestMediaPresign(filename, contentType, stats.size);
+
+  if (!presign.uploadUrl || !presign.publicUrl) {
+    throw new Error('uploadLocalMedia: presign response missing uploadUrl or publicUrl');
+  }
+
+  const uploadResponse = await fetch(presign.uploadUrl, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': contentType,
+    },
+    body: fs.readFileSync(resolvedPath),
+  });
+
+  if (!uploadResponse.ok) {
+    const errorText = await uploadResponse.text().catch(() => '');
+    throw new Error(`uploadLocalMedia: upload failed with ${uploadResponse.status}: ${errorText}`);
+  }
+
+  return {
+    contentType,
+    key: presign.key || '',
+    size: stats.size,
+    type: presign.type || inferMediaType(contentType),
+    url: presign.publicUrl,
+  };
+}
+
+/**
+ * Publishes a post immediately to one or more platforms.
+ * @param {string} content
+ * @param {Array<{platform: string, accountId: string}>} platforms
+ * @returns {Promise<object>}
+ */
+async function publishPost(content, platforms, options = {}) {
+  if (!content) throw new Error('publishPost: content is required');
+  if (!Array.isArray(platforms) || platforms.length === 0) {
+    throw new Error('publishPost: platforms must be a non-empty array');
+  }
+
+  const normalizedPlatforms = normalizePlatforms(platforms);
+  if (normalizedPlatforms.length === 0 || normalizedPlatforms.some((entry) => !entry.platform || !entry.accountId)) {
+    throw new Error('publishPost: each platform entry requires platform and accountId');
+  }
+
+  // Tag trackable URLs with Zernio UTM parameters before publishing
+  content = tagUrlsInText(content, options.utm || ZERNIO_UTM);
+
+  const qualityGate = require('../../social-quality-gate');
+  const gateResult = qualityGate.gatePost(content);
+  if (!gateResult.allowed) {
+    const reasons = gateResult.findings.map(f => f.reason).join(', ');
+    console.error(`[zernio:publisher] BLOCKED by quality gate: ${reasons}`);
+    return { blocked: true, reasons: gateResult.findings };
+  }
+
+  console.log(`[zernio:publisher] Publishing to ${normalizedPlatforms.length} platform(s): ${normalizedPlatforms.map((p) => p.platform).join(', ')}`);
+
+  const json = await zernioFetch('POST', '/posts', {
+    content,
+    firstComment: options.firstComment,
+    mediaItems: options.mediaItems,
+    publishNow: true,
+    platforms: normalizedPlatforms,
+  });
+
+  const data = normalizePostResult(json);
+  console.log(`[zernio:publisher] Post published. id=${data.id ?? 'unknown'}`);
+  return data;
+}
+
+/**
+ * Schedules a post for future publication.
+ * @param {string} content
+ * @param {Array<{platform: string, accountId: string}>} platforms
+ * @param {string} scheduledFor  ISO 8601 datetime
+ * @param {string} timezone      IANA timezone string
+ * @returns {Promise<object>}
+ */
+async function schedulePost(content, platforms, scheduledFor, timezone, options = {}) {
+  if (!content) throw new Error('schedulePost: content is required');
+  if (!Array.isArray(platforms) || platforms.length === 0) {
+    throw new Error('schedulePost: platforms must be a non-empty array');
+  }
+  if (!scheduledFor) throw new Error('schedulePost: scheduledFor is required');
+  if (!timezone) throw new Error('schedulePost: timezone is required');
+
+  const normalizedPlatforms = normalizePlatforms(platforms);
+  if (normalizedPlatforms.length === 0 || normalizedPlatforms.some((entry) => !entry.platform || !entry.accountId)) {
+    throw new Error('schedulePost: each platform entry requires platform and accountId');
+  }
+
+  content = tagUrlsInText(content, options.utm || ZERNIO_UTM);
+
+  console.log(`[zernio:publisher] Scheduling post for ${scheduledFor} (${timezone}) to ${normalizedPlatforms.length} platform(s)`);
+
+  const json = await zernioFetch('POST', '/posts', {
+    content,
+    firstComment: options.firstComment,
+    mediaItems: options.mediaItems,
+    publishNow: false,
+    platforms: normalizedPlatforms,
+    scheduledFor,
+    timezone,
+  });
+
+  const data = normalizePostResult(json);
+  console.log(`[zernio:publisher] Post scheduled. id=${data.id ?? 'unknown'}`);
+  return data;
+}
+
+/**
+ * Fetches all connected platform accounts from Zernio.
+ * @returns {Promise<Array<{platform: string, accountId: string, name: string}>>}
+ */
+async function getConnectedAccounts() {
+  console.log('[zernio:publisher] Fetching connected accounts');
+
+  const json = await zernioFetch('GET', '/accounts');
+  const accounts = (Array.isArray(json) ? json : (json.data ?? json.accounts ?? []))
+    .map(normalizeAccount)
+    .filter((account) => account && account.platform && account.accountId);
+
+  console.log(`[zernio:publisher] ${accounts.length} connected account(s) found`);
+  return accounts;
+}
+
+/**
+ * Publishes a post to all connected Zernio accounts in one call.
+ * @param {string} content
+ * @returns {Promise<{ published: object[], errors: object[] }>}
+ */
+async function publishToAllPlatforms(content, options = {}) {
+  if (!content) throw new Error('publishToAllPlatforms: content is required');
+
+  console.log('[zernio:publisher] Fetching all connected accounts for bulk publish');
+  const accounts = await getConnectedAccounts();
+
+  if (accounts.length === 0) {
+    console.warn('[zernio:publisher] No connected accounts found — nothing to publish');
+    return { published: [], errors: [] };
+  }
+
+  const published = [];
+  const errors = [];
+  const requestedPlatforms = Array.isArray(options.platforms) && options.platforms.length > 0
+    ? new Set(options.platforms.map((platform) => String(platform || '').trim()).filter(Boolean))
+    : null;
+  const groupedAccounts = groupAccountsByPlatform(accounts);
+
+  for (const [platform, platformAccounts] of groupedAccounts.entries()) {
+    if (requestedPlatforms && !requestedPlatforms.has(platform)) {
+      continue;
+    }
+
+    try {
+      const result = await publishPost(content, platformAccounts, {
+        utm: {
+          source: platform,
+          medium: options.medium || ZERNIO_UTM.medium,
+          campaign: options.campaign || ZERNIO_UTM.campaign,
+        },
+      });
+      published.push({ platform, result });
+    } catch (err) {
+      console.error(`[zernio:publisher] Bulk publish failed for ${platform}: ${err.message}`);
+      errors.push({ error: err.message, platform });
+    }
+  }
+
+  console.log(`[zernio:publisher] Bulk publish complete. published=${published.length} errors=${errors.length}`);
+  return { published, errors };
+}
+
+module.exports = {
+  publishPost,
+  schedulePost,
+  publishToAllPlatforms,
+  getConnectedAccounts,
+  groupAccountsByPlatform,
+  inferContentType,
+  inferMediaType,
+  normalizeAccount,
+  normalizePlatforms,
+  normalizePostResult,
+  requestMediaPresign,
+  resolveAccountId,
+  uploadLocalMedia,
+};
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  function getArg(flag) {
+    const prefix = `${flag}=`;
+    const entry = args.find((a) => a.startsWith(prefix));
+    return entry ? entry.slice(prefix.length) : null;
+  }
+
+  const text = getArg('--text');
+  const schedule = getArg('--schedule');
+  const timezone = getArg('--timezone') || 'UTC';
+
+  if (!text) {
+    console.error('Usage: node zernio.js --text="..." [--schedule="2026-04-01T10:00:00Z" --timezone="America/New_York"]');
+    process.exit(1);
+  }
+
+  (async () => {
+    try {
+      if (schedule) {
+        const accounts = await getConnectedAccounts();
+        const platforms = accounts.map((a) => ({ platform: a.platform, accountId: a.accountId }));
+        const result = await schedulePost(text, platforms, schedule, timezone);
+        console.log(`[zernio:publisher] Scheduled. id=${result.id ?? 'unknown'}`);
+      } else {
+        const result = await publishToAllPlatforms(text);
+        console.log(`[zernio:publisher] Done. published=${result.published.length} errors=${result.errors.length}`);
+      }
+    } catch (err) {
+      console.error('[zernio:publisher] Failed:', err.message);
+      process.exit(1);
+    }
+  })();
+}

package/scripts/social-analytics/run-digest.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const path = require('node:path');
+const { initDb } = require('./store');
+const { generateDigest, writeDigest } = require('./digest');
+const { sendSlackDigest, formatDigestForConsole } = require('./notify');
+
+async function main(argv = process.argv.slice(2)) {
+  const days = parseInt(argv.find((a) => a.startsWith('--days='))?.split('=')[1] || '7', 10) || 7;
+  const outputDir = path.resolve(__dirname, '..', '..', '.artifacts', 'social', 'digests');
+
+  console.log(`Generating ${days}-day social analytics digest...`);
+
+  const db = initDb();
+  const digest = generateDigest(db, { days });
+  db.close();
+
+  writeDigest(digest, outputDir);
+  console.log(`Digest written to ${outputDir}`);
+
+  console.log('');
+  console.log(formatDigestForConsole(digest));
+
+  await sendSlackDigest(digest);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+module.exports = { main };

package/scripts/social-analytics/store.js

@@ -0,0 +1,257 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const Database = require('better-sqlite3');
+
+const DEFAULT_DB_PATH = path.join(__dirname, 'db', 'social-analytics.db');
+const SCHEMA_PATH = path.join(__dirname, 'db', 'schema.sql');
+
+/**
+ * Opens the SQLite database, applies the schema, and returns the db instance.
+ * Idempotent — safe to call multiple times; schema uses IF NOT EXISTS guards.
+ *
+ * @param {string} [dbPath] - Absolute path to the .db file. Defaults to DEFAULT_DB_PATH.
+ * @returns {import('better-sqlite3').Database}
+ */
+function initDb(dbPath = DEFAULT_DB_PATH) {
+  const isInMemoryDatabase = dbPath === ':memory:';
+  const resolvedPath = isInMemoryDatabase ? dbPath : path.resolve(dbPath);
+  const dir = isInMemoryDatabase ? null : path.dirname(resolvedPath);
+
+  if (dir && !fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const db = new Database(resolvedPath);
+  db.pragma('busy_timeout = 3000');
+
+  // Enable WAL mode for better concurrent read performance.
+  if (!isInMemoryDatabase) {
+    db.pragma('journal_mode = WAL');
+  }
+  db.pragma('foreign_keys = ON');
+
+  const schema = fs.readFileSync(SCHEMA_PATH, 'utf8');
+  db.exec(schema);
+
+  return db;
+}
+
+/**
+ * Upserts a single engagement metric record.
+ * Uses INSERT OR REPLACE to handle the UNIQUE(platform, post_id, metric_date) constraint.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {object} record - Fields matching the engagement_metrics schema.
+ * @param {string} record.platform
+ * @param {string} record.content_type
+ * @param {string} record.post_id
+ * @param {string} [record.post_url]
+ * @param {string} [record.published_at]
+ * @param {string} record.metric_date
+ * @param {number} [record.impressions]
+ * @param {number} [record.reach]
+ * @param {number} [record.likes]
+ * @param {number} [record.comments]
+ * @param {number} [record.shares]
+ * @param {number} [record.saves]
+ * @param {number} [record.clicks]
+ * @param {number} [record.video_views]
+ * @param {number} [record.followers_delta]
+ * @param {string|object} [record.extra_json]
+ * @param {string} record.fetched_at
+ * @returns {import('better-sqlite3').RunResult}
+ */
+function upsertMetric(db, record) {
+  if (!record.platform) throw new Error('upsertMetric: record.platform is required');
+  if (!record.content_type) throw new Error('upsertMetric: record.content_type is required');
+  if (!record.post_id) throw new Error('upsertMetric: record.post_id is required');
+  if (!record.metric_date) throw new Error('upsertMetric: record.metric_date is required');
+  if (!record.fetched_at) throw new Error('upsertMetric: record.fetched_at is required');
+
+  const extraJson =
+    record.extra_json && typeof record.extra_json === 'object'
+      ? JSON.stringify(record.extra_json)
+      : record.extra_json ?? null;
+
+  const stmt = db.prepare(`
+    INSERT OR REPLACE INTO engagement_metrics (
+      platform, content_type, post_id, post_url, published_at, metric_date,
+      impressions, reach, likes, comments, shares, saves, clicks,
+      video_views, followers_delta, extra_json, fetched_at
+    ) VALUES (
+      @platform, @content_type, @post_id, @post_url, @published_at, @metric_date,
+      @impressions, @reach, @likes, @comments, @shares, @saves, @clicks,
+      @video_views, @followers_delta, @extra_json, @fetched_at
+    )
+  `);
+
+  return stmt.run({
+    platform: record.platform,
+    content_type: record.content_type,
+    post_id: record.post_id,
+    post_url: record.post_url ?? null,
+    published_at: record.published_at ?? null,
+    metric_date: record.metric_date,
+    impressions: record.impressions ?? 0,
+    reach: record.reach ?? 0,
+    likes: record.likes ?? 0,
+    comments: record.comments ?? 0,
+    shares: record.shares ?? 0,
+    saves: record.saves ?? 0,
+    clicks: record.clicks ?? 0,
+    video_views: record.video_views ?? 0,
+    followers_delta: record.followers_delta ?? 0,
+    extra_json: extraJson,
+    fetched_at: record.fetched_at,
+  });
+}
+
+/**
+ * Upserts a follower snapshot.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {{ platform: string, follower_count: number, snapshot_date: string }} snapshot
+ * @returns {import('better-sqlite3').RunResult}
+ */
+function upsertFollowerSnapshot(db, { platform, follower_count, snapshot_date }) {
+  if (!platform) throw new Error('upsertFollowerSnapshot: platform is required');
+  if (follower_count == null) throw new Error('upsertFollowerSnapshot: follower_count is required');
+  if (!snapshot_date) throw new Error('upsertFollowerSnapshot: snapshot_date is required');
+
+  const stmt = db.prepare(`
+    INSERT OR REPLACE INTO follower_snapshots (platform, follower_count, snapshot_date)
+    VALUES (@platform, @follower_count, @snapshot_date)
+  `);
+
+  return stmt.run({ platform, follower_count, snapshot_date });
+}
+
+/**
+ * Returns aggregated engagement metrics grouped by platform for the last N days.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {{ platform?: string, days?: number }} options
+ * @returns {object[]}
+ */
+function queryMetrics(db, { platform, days = 30 } = {}) {
+  if (days <= 0) throw new Error('queryMetrics: days must be a positive integer');
+
+  const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
+    .toISOString()
+    .slice(0, 10);
+
+  const params = { cutoff };
+  let platformClause = '';
+
+  if (platform) {
+    platformClause = 'AND platform = @platform';
+    params.platform = platform;
+  }
+
+  return db
+    .prepare(
+      `
+      SELECT
+        platform,
+        COUNT(DISTINCT post_id)    AS post_count,
+        SUM(impressions)           AS total_impressions,
+        SUM(reach)                 AS total_reach,
+        SUM(likes)                 AS total_likes,
+        SUM(comments)              AS total_comments,
+        SUM(shares)                AS total_shares,
+        SUM(saves)                 AS total_saves,
+        SUM(clicks)                AS total_clicks,
+        SUM(video_views)           AS total_video_views,
+        ROUND(AVG(impressions), 2) AS avg_impressions,
+        ROUND(AVG(likes), 2)       AS avg_likes
+      FROM engagement_metrics
+      WHERE metric_date >= @cutoff
+        ${platformClause}
+      GROUP BY platform
+      ORDER BY total_impressions DESC
+    `
+    )
+    .all(params);
+}
+
+/**
+ * Returns top content by total engagement (likes + comments + shares + saves)
+ * for the last N days.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {{ days?: number, limit?: number }} options
+ * @returns {object[]}
+ */
+function topContent(db, { days = 30, limit = 10 } = {}) {
+  if (days <= 0) throw new Error('topContent: days must be a positive integer');
+  if (limit <= 0) throw new Error('topContent: limit must be a positive integer');
+
+  const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
+    .toISOString()
+    .slice(0, 10);
+
+  return db
+    .prepare(
+      `
+      SELECT
+        platform,
+        content_type,
+        post_id,
+        post_url,
+        published_at,
+        SUM(likes + comments + shares + saves) AS total_engagement,
+        SUM(impressions)                        AS total_impressions,
+        SUM(likes)                              AS total_likes,
+        SUM(comments)                           AS total_comments,
+        SUM(shares)                             AS total_shares,
+        SUM(saves)                              AS total_saves,
+        SUM(video_views)                        AS total_video_views
+      FROM engagement_metrics
+      WHERE metric_date >= @cutoff
+      GROUP BY platform, post_id
+      ORDER BY total_engagement DESC
+      LIMIT @limit
+    `
+    )
+    .all({ cutoff, limit });
+}
+
+/**
+ * Returns follower snapshots for a platform for the last N days.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {{ platform: string, days?: number }} options
+ * @returns {object[]}
+ */
+function getFollowerHistory(db, { platform, days = 30 } = {}) {
+  if (!platform) throw new Error('getFollowerHistory: platform is required');
+  if (days <= 0) throw new Error('getFollowerHistory: days must be a positive integer');
+
+  const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
+    .toISOString()
+    .slice(0, 10);
+
+  return db
+    .prepare(
+      `
+      SELECT platform, follower_count, snapshot_date
+      FROM follower_snapshots
+      WHERE platform = @platform
+        AND snapshot_date >= @cutoff
+      ORDER BY snapshot_date ASC
+    `
+    )
+    .all({ platform, cutoff });
+}
+
+module.exports = {
+  DEFAULT_DB_PATH,
+  initDb,
+  upsertMetric,
+  upsertFollowerSnapshot,
+  queryMetrics,
+  topContent,
+  getFollowerHistory,
+};