thumbgate 0.9.10

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

@@ -0,0 +1,209 @@
+'use strict';
+
+/**
+ * zernio.js
+ * Unified publisher via Zernio API.
+ *
+ * Required env vars:
+ *   ZERNIO_API_KEY — Bearer token for https://zernio.com/api/v1
+ */
+
+const { tagUrlsInText } = require('../utm');
+
+const ZERNIO_UTM = { source: 'zernio', medium: 'social', campaign: 'organic' };
+
+const ZERNIO_BASE = 'https://zernio.com/api/v1';
+
+function requireApiKey() {
+  const key = process.env.ZERNIO_API_KEY;
+  if (!key) {
+    throw new Error('ZERNIO_API_KEY environment variable is required');
+  }
+  return key;
+}
+
+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();
+}
+
+/**
+ * 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) {
+  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');
+  }
+
+  // Tag trackable URLs with Zernio UTM parameters before publishing
+  content = tagUrlsInText(content, 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 ${platforms.length} platform(s): ${platforms.map((p) => p.platform).join(', ')}`);
+
+  const json = await zernioFetch('POST', '/posts', {
+    content,
+    publishNow: true,
+    platforms,
+  });
+
+  const data = json.data ?? 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) {
+  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');
+
+  console.log(`[zernio:publisher] Scheduling post for ${scheduledFor} (${timezone}) to ${platforms.length} platform(s)`);
+
+  const json = await zernioFetch('POST', '/posts', {
+    content,
+    publishNow: false,
+    platforms,
+    scheduledFor,
+    timezone,
+  });
+
+  const data = json.data ?? 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 ?? []);
+
+  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) {
+  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 platforms = accounts.map((acc) => ({
+    platform: acc.platform,
+    accountId: acc.accountId,
+  }));
+
+  const published = [];
+  const errors = [];
+
+  try {
+    const result = await publishPost(content, platforms);
+    published.push(result);
+  } catch (err) {
+    console.error(`[zernio:publisher] Bulk publish failed: ${err.message}`);
+    errors.push({ error: err.message, platforms: platforms.map((p) => p.platform) });
+  }
+
+  console.log(`[zernio:publisher] Bulk publish complete. published=${published.length} errors=${errors.length}`);
+  return { published, errors };
+}
+
+module.exports = {
+  publishPost,
+  schedulePost,
+  publishToAllPlatforms,
+  getConnectedAccounts,
+};
+
+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,
+};

package/scripts/social-analytics/utm.js

@@ -0,0 +1,143 @@
+'use strict';
+
+/**
+ * UTM link builder utility for social posts.
+ *
+ * Provides helpers for constructing tracked URLs to use in social content,
+ * with pre-built platform link sets and a placeholder for dub.co shortening.
+ */
+
+/**
+ * Appends UTM parameters to a base URL.
+ * Handles existing query strings gracefully.
+ *
+ * @param {string} baseUrl - The destination URL to annotate.
+ * @param {{ source: string, medium?: string, campaign: string, content?: string }} options
+ * @returns {string} URL with UTM query parameters appended.
+ */
+function buildUTMLink(baseUrl, { source, medium = 'social', campaign, content } = {}) {
+  if (!baseUrl) throw new Error('buildUTMLink: baseUrl is required');
+  if (!source) throw new Error('buildUTMLink: source is required');
+  if (!campaign) throw new Error('buildUTMLink: campaign is required');
+
+  const url = new URL(baseUrl);
+  url.searchParams.set('utm_source', source);
+  url.searchParams.set('utm_medium', medium);
+  url.searchParams.set('utm_campaign', campaign);
+  if (content) {
+    url.searchParams.set('utm_content', content);
+  }
+  return url.toString();
+}
+
+/**
+ * Returns a pre-built set of tracked links for each social platform.
+ *
+ * @param {string} baseUrl - The destination URL.
+ * @param {string} campaign - The campaign name (e.g. 'launch-v2', 'spring-promo').
+ * @returns {{
+ *   instagram: string,
+ *   tiktok: string,
+ *   x: string,
+ *   github: string,
+ *   reddit: string,
+ *   zernio: string,
+ * }}
+ */
+function buildSocialLinks(baseUrl, campaign) {
+  if (!baseUrl) throw new Error('buildSocialLinks: baseUrl is required');
+  if (!campaign) throw new Error('buildSocialLinks: campaign is required');
+
+  return {
+    instagram: buildUTMLink(baseUrl, { source: 'instagram', medium: 'social', campaign }),
+    tiktok: buildUTMLink(baseUrl, { source: 'tiktok', medium: 'social', campaign }),
+    x: buildUTMLink(baseUrl, { source: 'x', medium: 'social', campaign }),
+    github: buildUTMLink(baseUrl, { source: 'github', medium: 'social', campaign }),
+    reddit: buildUTMLink(baseUrl, { source: 'reddit', medium: 'social', campaign }),
+    zernio: buildUTMLink(baseUrl, { source: 'zernio', medium: 'social', campaign }),
+  };
+}
+
+/**
+ * Known trackable domains — URLs matching these will have UTM params injected.
+ */
+const TRACKABLE_DOMAINS = [
+  'thumbgate-production.up.railway.app',
+  'github.com/IgorGanapolsky/ThumbGate',
+  'github.com/IgorGanapolsky/thumbgate',
+];
+
+/**
+ * Replace raw trackable URLs in text with UTM-tagged versions.
+ *
+ * Scans the input for URLs containing any of the known trackable domains
+ * and appends UTM parameters to them.
+ *
+ * @param {string} text - The content to scan for URLs.
+ * @param {{ source: string, medium?: string, campaign: string }} utmOptions
+ * @returns {string} Text with trackable URLs replaced by UTM-tagged versions.
+ */
+function tagUrlsInText(text, { source, medium = 'social', campaign }) {
+  if (!text) return text;
+
+  // Match http(s) URLs
+  const urlPattern = /https?:\/\/[^\s)"\]]+/g;
+
+  return text.replace(urlPattern, (match) => {
+    const isTrackable = TRACKABLE_DOMAINS.some((domain) => match.includes(domain));
+    if (!isTrackable) return match;
+
+    try {
+      return buildUTMLink(match, { source, medium, campaign });
+    } catch {
+      // If URL parsing fails, return the original
+      return match;
+    }
+  });
+}
+
+/**
+ * Placeholder for dub.co link shortening.
+ * Returns the original long URL as-is until a shortening provider is enabled.
+ *
+ * To activate: set DUB_API_KEY in the environment and call
+ * POST https://api.dub.co/links with { url: longUrl, domain: 'dub.sh' }.
+ *
+ * @param {string} longUrl - The full URL to shorten.
+ * @returns {Promise<string>} The longUrl unchanged (no-op placeholder).
+ */
+async function shortenWithDub(longUrl) {
+  // Deliberate no-op until a shortening provider is enabled for this pipeline.
+  // Example future implementation: POST https://api.dub.co/links with Bearer DUB_API_KEY.
+  return longUrl;
+}
+
+module.exports = {
+  buildUTMLink,
+  buildSocialLinks,
+  shortenWithDub,
+  tagUrlsInText,
+  TRACKABLE_DOMAINS,
+};
+
+// Allow running directly:
+//   node scripts/social-analytics/utm.js --url https://example.com --campaign spring-promo
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const get = (flag) => {
+    const idx = args.indexOf(flag);
+    return idx !== -1 ? args[idx + 1] : null;
+  };
+
+  const url = get('--url');
+  const campaign = get('--campaign');
+
+  if (!url || !campaign) {
+    console.error('Usage: node utm.js --url <baseUrl> --campaign <campaign>');
+    process.exit(1);
+  }
+
+  const links = buildSocialLinks(url, campaign);
+  console.log('Social UTM links for campaign:', campaign);
+  console.log(JSON.stringify(links, null, 2));
+}