social-autoposter 1.6.0 → 1.6.1

package/bin/server.js

@@ -42,7 +42,7 @@ function agentPath(job) {
 
 // Matrix: rows = job types, columns = platforms
 // Each cell is a job (or null if that combo doesn't exist)
-const PLATFORMS = ['Reddit', 'Twitter', 'LinkedIn', 'MoltBook', 'GitHub'];
+const PLATFORMS = ['Reddit', 'Twitter', 'LinkedIn', 'MoltBook', 'GitHub', 'Instagram'];
 const JOB_TYPES = ['Post Threads', 'Post Comments', 'Engage', 'DM Outreach', 'DM Replies', 'Link Edit', 'Stats', 'Post Audit', 'Octolens'];
 
 const JOBS = [
@@ -86,6 +86,7 @@ const JOBS = [
   { label: 'com.m13v.social-stats-twitter', name: 'Stats Twitter', type: 'Stats', platform: 'Twitter', script: 'stats-twitter.sh', logPrefix: 'stats-twitter-', plist: 'com.m13v.social-stats-twitter.plist' },
   { label: 'com.m13v.social-stats-linkedin', name: 'Stats LinkedIn', type: 'Stats', platform: 'LinkedIn', script: 'stats-linkedin.sh', logPrefix: 'stats-linkedin-', plist: 'com.m13v.social-stats-linkedin.plist' },
   { label: 'com.m13v.social-stats-moltbook', name: 'Stats MoltBook', type: 'Stats', platform: 'MoltBook', script: 'stats-moltbook.sh', logPrefix: 'stats-moltbook-', plist: 'com.m13v.social-stats-moltbook.plist' },
+  { label: 'com.m13v.social-stats-instagram', name: 'Stats Instagram', type: 'Stats', platform: 'Instagram', script: 'stats-instagram.sh', logPrefix: 'stats-instagram-', plist: 'com.m13v.social-stats-instagram.plist' },
   // Post Audit row (verify posts still exist / API health)
   { label: 'com.m13v.social-audit-reddit', name: 'Post Audit Reddit', type: 'Post Audit', platform: 'Reddit', script: 'audit-reddit.sh', logPrefix: 'audit-reddit-', plist: 'com.m13v.social-audit-reddit.plist' },
   { label: 'com.m13v.social-audit-twitter', name: 'Post Audit Twitter', type: 'Post Audit', platform: 'Twitter', script: 'audit-twitter.sh', logPrefix: 'audit-twitter-', plist: 'com.m13v.social-audit-twitter.plist' },
@@ -128,6 +129,7 @@ const REQUIRED_LOCKS = {
   'link-edit-moltbook.sh':          ['link-edit-moltbook'],
   'link-edit-github.sh':            ['link-edit-github'],
   'stats-reddit.sh':                ['reddit-browser'],
+  'stats-instagram.sh':             ['instagram-poster'],
   'audit-reddit.sh':                ['reddit-browser', 'audit-reddit'],
   'audit-twitter.sh':               ['twitter-browser', 'audit-twitter'],
   'audit-linkedin.sh':              ['linkedin-browser', 'audit-linkedin'],
@@ -154,6 +156,38 @@ function json(res, obj, status = 200) {
   res.end(JSON.stringify(obj));
 }
 
+// Short-link code alphabet matches scripts/dm_short_links.py CODE_ALPHABET
+// so codes minted by either path are visually consistent. 32 chars (no 0/1/l/o
+// to avoid ambiguity in handwritten/printed contexts).
+const SHORT_LINK_ALPHABET = 'abcdefghijkmnpqrstuvwxyz23456789';
+
+function mintShortLinkCode(n = 8) {
+  let s = '';
+  const bytes = crypto.randomBytes(n);
+  for (let i = 0; i < n; i++) {
+    s += SHORT_LINK_ALPHABET[bytes[i] % SHORT_LINK_ALPHABET.length];
+  }
+  return s;
+}
+
+// Look up a project's wrapper host (where /r/<code> is served) by name from
+// config.json. Mirrors _project_short_links_host in scripts/dm_short_links.py.
+// Falls back to project.website. Returns null if the project is not configured.
+function getProjectWrapperHost(projectName) {
+  if (!projectName) return null;
+  try {
+    const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    const projects = Array.isArray(config.projects) ? config.projects : [];
+    const p = projects.find(x => x && x.name === projectName);
+    if (!p) return null;
+    const host = (p.short_links_host || p.website || '').trim().replace(/\/+$/, '');
+    return host || null;
+  } catch (e) {
+    console.error('[wrapper-host] config read failed:', e.message);
+    return null;
+  }
+}
+
 function isJobLoaded(label) {
   return driver.isLoaded(label);
 }
@@ -3246,32 +3280,79 @@ async function handleApi(req, res) {
             RETURNING post_id, reply_id, platform, project_name,
                       target_url, kind`;
       const postRes = await pool.query(postSql, [code]);
-      if (!postRes.rows.length) {
+      if (postRes.rows.length) {
+        const prow = postRes.rows[0];
+        if (!prow.target_url) {
+          return json(res, { error: 'no_target_url', post_id: prow.post_id, reply_id: prow.reply_id }, 404);
+        }
+        // Per-click log for post rail (humans + bots).
+        try {
+          await pool.query(
+            `INSERT INTO post_link_clicks (code, ip_hash, user_agent, is_bot, referrer)
+             VALUES ($1, $2, $3, $4, $5)`,
+            [code, ipHash, fwdUa, isBot, fwdRef]
+          );
+        } catch (e) {
+          console.error('[short-links] post_link_clicks insert failed (non-fatal):', e.message);
+        }
+        let pPlatform = (prow.platform || 'reddit').toLowerCase();
+        if (pPlatform === 'x') pPlatform = 'twitter';
+        return json(res, {
+          post_id: prow.post_id,
+          reply_id: prow.reply_id,
+          platform: pPlatform,
+          project: prow.project_name || null,
+          kind: prow.kind || null,
+          target_url: prow.target_url,
+        });
+      }
+
+      // Final fallback: newsletter_links rail. Outbound broadcast emails
+      // sent by ~/analytics (dash.m13v.com) mint per-recipient codes via
+      // POST /api/newsletter/mint; the resolver here closes the loop on
+      // click attribution. broadcast_product + broadcast_id let the
+      // analytics dashboard cross-reference back into the originating
+      // studyly_broadcast_log / fazm_broadcasts / etc. row. The customer
+      // /r/[code] handler (see ~/seo-components/src/lib/dm-short-link-redirect.ts)
+      // fires `newsletter_short_link_clicked` in PostHog when broadcast_id
+      // is set in the response, so signup attribution stitches via the
+      // same anonymous distinct_id session that landed on the page.
+      const newsSql = isBot
+        ? `SELECT broadcast_product, broadcast_id, recipient_email_hash,
+                  recipient_email, target_url, kind, project_name
+           FROM newsletter_links WHERE code = $1`
+        : `UPDATE newsletter_links SET
+              clicks = clicks + 1,
+              first_click_at = COALESCE(first_click_at, NOW()),
+              last_click_at = NOW()
+            WHERE code = $1
+            RETURNING broadcast_product, broadcast_id, recipient_email_hash,
+                      recipient_email, target_url, kind, project_name`;
+      const newsRes = await pool.query(newsSql, [code]);
+      if (!newsRes.rows.length) {
         return json(res, { error: 'not_found', code }, 404);
       }
-      const prow = postRes.rows[0];
-      if (!prow.target_url) {
-        return json(res, { error: 'no_target_url', post_id: prow.post_id, reply_id: prow.reply_id }, 404);
+      const nrow = newsRes.rows[0];
+      if (!nrow.target_url) {
+        return json(res, { error: 'no_target_url', broadcast_id: nrow.broadcast_id }, 404);
       }
-      // Per-click log for post rail (humans + bots).
+      // Per-click log for newsletter rail (humans + bots).
       try {
         await pool.query(
-          `INSERT INTO post_link_clicks (code, ip_hash, user_agent, is_bot, referrer)
+          `INSERT INTO newsletter_link_clicks (code, ip_hash, user_agent, is_bot, referrer)
            VALUES ($1, $2, $3, $4, $5)`,
           [code, ipHash, fwdUa, isBot, fwdRef]
         );
       } catch (e) {
-        console.error('[short-links] post_link_clicks insert failed (non-fatal):', e.message);
+        console.error('[short-links] newsletter_link_clicks insert failed (non-fatal):', e.message);
       }
-      let pPlatform = (prow.platform || 'reddit').toLowerCase();
-      if (pPlatform === 'x') pPlatform = 'twitter';
       return json(res, {
-        post_id: prow.post_id,
-        reply_id: prow.reply_id,
-        platform: pPlatform,
-        project: prow.project_name || null,
-        kind: prow.kind || null,
-        target_url: prow.target_url,
+        broadcast_id: Number(nrow.broadcast_id),
+        broadcast_product: nrow.broadcast_product,
+        recipient_email_hash: nrow.recipient_email_hash,
+        project: nrow.project_name || nrow.broadcast_product || null,
+        kind: nrow.kind || null,
+        target_url: nrow.target_url,
       });
     } catch (e) {
       console.error('[short-links] resolver db error:', e.message);
@@ -3279,6 +3360,218 @@ async function handleApi(req, res) {
     }
   }
 
+  // PUBLIC (shared-secret): newsletter rail mint endpoint.
+  //
+  // Called server-to-server by ~/analytics (dash.m13v.com) at broadcast
+  // send time. For every recipient x URL, mints a code and INSERTs a row
+  // in newsletter_links so /api/short-links/<code> can resolve it later.
+  // The caller passes raw target URLs (already UTM-stamped on its side
+  // per the canonical s4l UTM scheme), this endpoint just wraps them.
+  //
+  // Auth is a NEWSLETTER_API_SECRET shared between analytics + this server.
+  // Without it the endpoint 401s. We deliberately do NOT use the Firebase
+  // auth path because the caller is a Vercel serverless function with no
+  // Firebase ID token of its own.
+  //
+  // Request:  { product: "studyly", broadcast_id: 5,
+  //             recipient_email: "a@b.com",
+  //             urls: [{ target_url: "https://studyly.io/...", kind: "web" }, ...] }
+  // Response: { links: [{ target_url, code, short_url } | { target_url, error }, ...] }
+  if (p === '/api/newsletter/mint' && req.method === 'POST') {
+    const authz = (req.headers['authorization'] || '').toString();
+    const wantSecret = (process.env.NEWSLETTER_API_SECRET || '').trim();
+    if (!wantSecret || authz !== `Bearer ${wantSecret}`) {
+      return json(res, { error: 'unauthorized' }, 401);
+    }
+    let body;
+    try {
+      const raw = await readBody(req);
+      body = JSON.parse(raw || '{}');
+    } catch {
+      return json(res, { error: 'bad_json' }, 400);
+    }
+    const { product, broadcast_id, recipient_email, urls, wrapper_host: wrapperHostInput } = body || {};
+    if (typeof product !== 'string' || !product.trim()) {
+      return json(res, { error: 'product required' }, 400);
+    }
+    const broadcastId = Number(broadcast_id);
+    if (!Number.isFinite(broadcastId)) {
+      return json(res, { error: 'broadcast_id (numeric) required' }, 400);
+    }
+    if (typeof recipient_email !== 'string' || !recipient_email.includes('@')) {
+      return json(res, { error: 'recipient_email required' }, 400);
+    }
+    if (!Array.isArray(urls) || urls.length === 0) {
+      return json(res, { error: 'urls (non-empty array) required' }, 400);
+    }
+    if (urls.length > 50) {
+      return json(res, { error: 'too many urls (max 50 per request)' }, 400);
+    }
+    // Wrapper host (where /r/<code> is served): caller can pass it directly,
+    // otherwise fall back to config.json lookup. The Cloud Run image does NOT
+    // bundle config.json (the local-operator dashboard does), so analytics
+    // always passes it explicitly. Local operator usage just works.
+    let wrapperHost = null;
+    if (typeof wrapperHostInput === 'string' && /^https?:\/\//i.test(wrapperHostInput)) {
+      wrapperHost = wrapperHostInput.trim().replace(/\/+$/, '');
+    } else {
+      wrapperHost = getProjectWrapperHost(product);
+    }
+    if (!wrapperHost) {
+      return json(res, { error: `no wrapper host for project '${product}' (pass wrapper_host in request body or set in config.json)` }, 400);
+    }
+    const pool = getPool();
+    if (!pool) return json(res, { error: 'no_db' }, 500);
+
+    const emailLower = recipient_email.trim().toLowerCase();
+    const emailHash = crypto.createHash('sha256').update(emailLower).digest('hex').slice(0, 16);
+
+    const out = [];
+    for (const u of urls) {
+      if (!u || typeof u !== 'object') {
+        out.push({ target_url: null, error: 'not_an_object' });
+        continue;
+      }
+      const targetUrl = String(u.target_url || '').trim();
+      const kind = String(u.kind || 'web').slice(0, 32);
+      if (!/^https?:\/\//i.test(targetUrl)) {
+        out.push({ target_url: targetUrl, error: 'invalid_url' });
+        continue;
+      }
+      // Mint with PK collision retry (8 chars x 32 alphabet = ~10^12 keyspace,
+      // collisions are astronomically rare but cheap to retry).
+      let code = null;
+      let lastErr = null;
+      for (let attempt = 0; attempt < 5; attempt++) {
+        const candidate = mintShortLinkCode(8);
+        try {
+          await pool.query(
+            `INSERT INTO newsletter_links
+               (code, broadcast_product, broadcast_id, recipient_email_hash,
+                recipient_email, target_url, kind, project_name)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+            [candidate, product, broadcastId, emailHash, recipient_email,
+             targetUrl, kind, product]
+          );
+          code = candidate;
+          break;
+        } catch (e) {
+          lastErr = e;
+          if (!/duplicate key/i.test(e.message || '')) {
+            console.error('[newsletter/mint] insert failed:', e.message);
+            break;
+          }
+        }
+      }
+      if (!code) {
+        out.push({ target_url: targetUrl, error: lastErr ? lastErr.message.slice(0, 200) : 'mint_failed' });
+        continue;
+      }
+      out.push({
+        target_url: targetUrl,
+        code,
+        short_url: `${wrapperHost}/r/${code}`,
+      });
+    }
+    return json(res, {
+      product,
+      broadcast_id: broadcastId,
+      recipient_email,
+      recipient_email_hash: emailHash,
+      links: out,
+    });
+  }
+
+  // PUBLIC (shared-secret): newsletter rail aggregate stats.
+  //
+  // Returns click + recipient breakdown for a broadcast so the analytics
+  // dashboard and the social-autoposter dashboard can render the same
+  // numbers without either holding state about the other. Click counts
+  // live here (the canonical clicks store); signup attribution lives
+  // in PostHog and is computed analytics-side via HogQL against the
+  // utm_content this endpoint reports.
+  //
+  // Request:  GET /api/newsletter/stats?product=studyly&broadcast_id=5
+  // Response: { product, broadcast_id, total_links, total_recipients,
+  //             total_human_clicks, recipients_clicked, human_hits,
+  //             bot_hits, per_recipient: [...] }
+  if (p === '/api/newsletter/stats' && req.method === 'GET') {
+    const authz = (req.headers['authorization'] || '').toString();
+    const wantSecret = (process.env.NEWSLETTER_API_SECRET || '').trim();
+    if (!wantSecret || authz !== `Bearer ${wantSecret}`) {
+      return json(res, { error: 'unauthorized' }, 401);
+    }
+    const product = (url.searchParams.get('product') || '').trim();
+    const broadcastIdRaw = (url.searchParams.get('broadcast_id') || '').trim();
+    if (!product || !broadcastIdRaw) {
+      return json(res, { error: 'product and broadcast_id required' }, 400);
+    }
+    const broadcastId = Number(broadcastIdRaw);
+    if (!Number.isFinite(broadcastId)) {
+      return json(res, { error: 'broadcast_id must be numeric' }, 400);
+    }
+    const pool = getPool();
+    if (!pool) return json(res, { error: 'no_db' }, 500);
+
+    try {
+      const agg = await pool.query(
+        `SELECT
+           COUNT(*) AS total_links,
+           COUNT(DISTINCT recipient_email_hash) AS total_recipients,
+           COALESCE(SUM(clicks), 0) AS total_human_clicks,
+           COUNT(DISTINCT recipient_email_hash) FILTER (WHERE clicks > 0) AS recipients_clicked
+         FROM newsletter_links
+         WHERE broadcast_product = $1 AND broadcast_id = $2`,
+        [product, broadcastId]
+      );
+      const hitsRes = await pool.query(
+        `SELECT
+           COUNT(*) FILTER (WHERE is_bot = false) AS human_hits,
+           COUNT(*) FILTER (WHERE is_bot = true)  AS bot_hits
+         FROM newsletter_link_clicks nlc
+         JOIN newsletter_links nl ON nl.code = nlc.code
+         WHERE nl.broadcast_product = $1 AND nl.broadcast_id = $2`,
+        [product, broadcastId]
+      );
+      const perRecipient = await pool.query(
+        `SELECT
+           recipient_email,
+           recipient_email_hash,
+           COUNT(*) AS link_count,
+           COALESCE(SUM(clicks), 0) AS clicks,
+           MAX(last_click_at) AS last_click_at
+         FROM newsletter_links
+         WHERE broadcast_product = $1 AND broadcast_id = $2
+         GROUP BY recipient_email, recipient_email_hash
+         ORDER BY clicks DESC, link_count DESC
+         LIMIT 1000`,
+        [product, broadcastId]
+      );
+      const row = agg.rows[0] || {};
+      const hitRow = hitsRes.rows[0] || {};
+      return json(res, {
+        product,
+        broadcast_id: broadcastId,
+        total_links: Number(row.total_links || 0),
+        total_recipients: Number(row.total_recipients || 0),
+        total_human_clicks: Number(row.total_human_clicks || 0),
+        recipients_clicked: Number(row.recipients_clicked || 0),
+        human_hits: Number(hitRow.human_hits || 0),
+        bot_hits: Number(hitRow.bot_hits || 0),
+        per_recipient: perRecipient.rows.map(r => ({
+          email: r.recipient_email,
+          email_hash: r.recipient_email_hash,
+          link_count: Number(r.link_count || 0),
+          clicks: Number(r.clicks || 0),
+          last_click_at: r.last_click_at,
+        })),
+      });
+    } catch (e) {
+      console.error('[newsletter/stats] db error:', e.message);
+      return json(res, { error: 'stats_failed', detail: String(e.message).slice(0, 500) }, 500);
+    }
+  }
+
   // Auth: no-op when CLIENT_MODE is unset (local operator use).
   // When CLIENT_MODE=1, require a Firebase Bearer token and enforce admin/project claims.
   const av = await auth.verifyAuth(req, p);
@@ -4416,8 +4709,12 @@ async function handleApi(req, res) {
     // and scripts/engagement_styles.py picker). clicks weighted ×10 because a
     // real human click outvalues 10 likes of vibes. Clicks come from a
     // bot-filtered subquery against post_link_clicks (matching the picker).
+    // NOTE: reference pl.total_clicks directly here, NOT the `clicks` alias.
+    // Postgres does not let one expression in a SELECT list reference another
+    // expression's alias from the same SELECT; doing so previously caused
+    // `column "clicks" does not exist` and silently returned 0 rows.
     const scoreExpr =
-      "(COALESCE(clicks, 0) * 10 + " +
+      "(COALESCE(pl.total_clicks, 0) * 10 + " +
         "COALESCE(comments_count,0) * 3 + " +
         "CASE WHEN LOWER(platform) IN ('reddit', 'moltbook') " +
           "THEN GREATEST(0, COALESCE(upvotes,0) - 1) " +
@@ -5647,7 +5944,7 @@ async function handleApi(req, res) {
     const windowKey = Object.prototype.hasOwnProperty.call(WINDOW_HOURS, rawWindow) ? rawWindow : '7d';
     const windowHours = WINDOW_HOURS[windowKey];
     const rawPlatform = String(url.searchParams.get('platform') || '').toLowerCase().trim();
-    const ALLOWED_PLATFORMS = new Set(['reddit', 'twitter', 'x', 'linkedin', 'moltbook']);
+    const ALLOWED_PLATFORMS = new Set(['reddit', 'twitter', 'x', 'linkedin', 'moltbook', 'instagram']);
     const platformFilter = ALLOWED_PLATFORMS.has(rawPlatform) ? rawPlatform : '';
     const rawKind = String(url.searchParams.get('kind') || 'all').toLowerCase().trim();
     const kindFilter = (rawKind === 'threads' || rawKind === 'comments') ? rawKind : 'all';
@@ -8446,7 +8743,7 @@ function fmtInterval(secs) {
 }
 
 let _initialized = false;
-const PLATFORMS = ['Reddit', 'Twitter', 'LinkedIn', 'MoltBook', 'GitHub'];
+const PLATFORMS = ['Reddit', 'Twitter', 'LinkedIn', 'MoltBook', 'GitHub', 'Instagram'];
 const JOB_TYPES = ['Post Threads', 'Post Comments', 'Engage', 'DM Outreach', 'DM Replies', 'Link Edit', 'Stats', 'Post Audit', 'Octolens'];
 
 function renderToggle(label, loaded) {
@@ -14378,6 +14675,20 @@ function renderTopPosts(payload) {
         filterMode: 'none' },
     ],
   });
+  // Reconcile the top-level "Link sent" pill with the column filter that
+  // mountSortableTable just hydrated from localStorage. See
+  // syncTopLinkPillFromColumn for the full reasoning.
+  syncTopLinkPillFromColumn();
+  // Also live-sync the pill when the user changes the inline column dropdown
+  // directly. Without this, the pill would stay stale until the next render
+  // (project switch, window flip, etc.) and the user would see the same
+  // mismatch they just reported. mountSortableTable is generic and shouldn't
+  // know about specific columns, so wire this here at the call site.
+  const linkColDd = document.querySelector('select.activity-col-filter[data-filter-key="link_clicks"]');
+  if (linkColDd && !linkColDd._linkPillSyncWired) {
+    linkColDd.addEventListener('change', () => { syncTopLinkPillFromColumn(); });
+    linkColDd._linkPillSyncWired = true;
+  }
 }
 
 async function loadTopPosts(force) {
@@ -14410,6 +14721,39 @@ async function loadTopPosts(force) {
   }
 }
 
+// Two layers can set the "link sent" filter on the Top > Posts table:
+//   1. The top-level pill row (#top-dm-link-pills, persisted at sa.top.dmLink.v1)
+//   2. The inline column dropdown for the link_clicks column (persisted inside
+//      sa.topTable.v2.filters.link_clicks via mountSortableTable).
+// They hydrate from different localStorage keys, independently, on every page
+// load. Without reconciliation the table can be rendering with link_clicks=
+// 'has_link' (only link-sent rows visible) while the pill row reads "All",
+// leaving the user with no top-level indication that a filter is active.
+//
+// Source of truth = the column filter (it's what actually drives the visible
+// rows). After mountSortableTable hydrates, mirror its value into the pill so
+// the top-level UI never lies. has_clicks has no pill equivalent: surface it
+// as "All" on the pill but leave the column filter intact so the inline
+// dropdown still works for that advanced case.
+function syncTopLinkPillFromColumn() {
+  const linkRow = document.getElementById('top-dm-link-pills');
+  if (!linkRow) return;
+  const colVal = (_topTableState && _topTableState.filters && _topTableState.filters.link_clicks) || '';
+  const colToPill = { has_link: 'yes', no_link: 'no' };
+  const desired = colToPill[colVal] || 'all';
+  if (_topDmLink === desired) {
+    // Defensive: even if our in-memory _topDmLink is consistent, the visible
+    // active-class on the pill might still be stale from a prior render path
+    // (e.g. inline column dropdown change that bypassed the pill). Force the
+    // DOM to match.
+    setTopPillActive(linkRow, desired);
+    return;
+  }
+  _topDmLink = desired;
+  try { saSave('sa.top.dmLink.v1', _topDmLink); } catch {}
+  setTopPillActive(linkRow, desired);
+}
+
 function setTopPillActive(row, value) {
   if (!row) return;
   row.dataset.selected = value || 'all';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "social-autoposter",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Automated social posting pipeline for Reddit, X/Twitter, LinkedIn, and Moltbook. Install as a Claude Code agent skill.",
   "bin": {
     "social-autoposter": "bin/cli.js"

package/scripts/account_resolver.py

@@ -0,0 +1,141 @@
+"""Single source of truth for the posting account on every platform.
+
+Resolution order for each platform (first non-empty wins):
+
+  1. Env var `AUTOPOSTER_<PLATFORM>_HANDLE` (used by the VM / per-account
+     systemd or launchd units to override config.json without rewriting the
+     checked-in file). Twitter retains the legacy `AUTOPOSTER_TWITTER_HANDLE`
+     name as an alias.
+  2. The matching field in `config.json` -> `accounts.<platform>.<field>`.
+
+The handle is normalized:
+  - leading `@` is stripped (twitter)
+  - leading `u/` is stripped (reddit)
+  - surrounding whitespace is stripped
+So both `@matt_diak` and `matt_diak` resolve to `matt_diak`, both
+`u/Deep_Ad1959` and `Deep_Ad1959` resolve to `Deep_Ad1959`, matching the
+canonical shape stored in `posts.our_account` after the 2026-05-20 migration.
+
+Returns None if neither source has a value. Callers should treat None as
+"unknown account" and decline to scope per-account work that needs a handle
+(e.g. dedupe filters).
+
+Platform key map:
+    twitter   -> accounts.twitter.handle           (env: AUTOPOSTER_TWITTER_HANDLE)
+    reddit    -> accounts.reddit.username          (env: AUTOPOSTER_REDDIT_USERNAME)
+    linkedin  -> accounts.linkedin.name            (env: AUTOPOSTER_LINKEDIN_NAME)
+    github    -> accounts.github.username          (env: AUTOPOSTER_GITHUB_USERNAME)
+    moltbook  -> accounts.moltbook.username        (env: AUTOPOSTER_MOLTBOOK_USERNAME)
+"""
+from __future__ import annotations
+
+import json
+import os
+from functools import lru_cache
+from typing import Optional
+
+_PLATFORM_CONFIG_FIELD = {
+    "twitter":  ("twitter",  "handle"),
+    "x":        ("twitter",  "handle"),   # alias for the canonical post-platform
+    "reddit":   ("reddit",   "username"),
+    "linkedin": ("linkedin", "name"),
+    "github":   ("github",   "username"),
+    "moltbook": ("moltbook", "username"),
+}
+
+_PLATFORM_ENV_NAME = {
+    "twitter":  "AUTOPOSTER_TWITTER_HANDLE",
+    "x":        "AUTOPOSTER_TWITTER_HANDLE",
+    "reddit":   "AUTOPOSTER_REDDIT_USERNAME",
+    "linkedin": "AUTOPOSTER_LINKEDIN_NAME",
+    "github":   "AUTOPOSTER_GITHUB_USERNAME",
+    "moltbook": "AUTOPOSTER_MOLTBOOK_USERNAME",
+}
+
+
+def normalize(handle: Optional[str]) -> Optional[str]:
+    """Canonicalize a raw account handle.
+
+    Drops leading `@` (twitter) and `u/` (reddit) plus surrounding
+    whitespace. Returns None for empty input.
+    """
+    if not handle:
+        return None
+    h = handle.strip()
+    if h.startswith("@"):
+        h = h[1:]
+    elif h.lower().startswith("u/"):
+        h = h[2:]
+    h = h.strip()
+    return h or None
+
+
+@lru_cache(maxsize=1)
+def _load_config() -> dict:
+    repo_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    cfg_path = os.path.join(repo_root, "config.json")
+    try:
+        with open(cfg_path, "r", encoding="utf-8") as f:
+            return json.load(f) or {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def resolve(platform: str) -> Optional[str]:
+    """Return the normalized posting handle for `platform`, or None."""
+    key = (platform or "").strip().lower()
+    if key not in _PLATFORM_CONFIG_FIELD:
+        return None
+
+    env_name = _PLATFORM_ENV_NAME[key]
+    env_value = normalize(os.environ.get(env_name))
+    if env_value:
+        return env_value
+
+    section, field = _PLATFORM_CONFIG_FIELD[key]
+    cfg = _load_config()
+    accounts = cfg.get("accounts") or {}
+    block = accounts.get(section) or {}
+    return normalize(block.get(field))
+
+
+def require(platform: str) -> str:
+    """Like resolve() but raises if no handle is configured."""
+    h = resolve(platform)
+    if not h:
+        section, field = _PLATFORM_CONFIG_FIELD.get(
+            (platform or "").lower(), ("?", "?")
+        )
+        env_name = _PLATFORM_ENV_NAME.get(
+            (platform or "").lower(), f"AUTOPOSTER_{platform.upper()}_HANDLE"
+        )
+        raise RuntimeError(
+            f"No account configured for platform={platform!r}. "
+            f"Set env {env_name} or accounts.{section}.{field} in config.json."
+        )
+    return h
+
+
+# Backwards-compatible shim so the existing twitter-only call site keeps
+# working without churn. `from twitter_account import resolve_handle` will
+# continue to work; new code should call `account_resolver.resolve('twitter')`.
+def resolve_handle() -> Optional[str]:
+    return resolve("twitter")
+
+
+def require_handle() -> str:
+    return require("twitter")
+
+
+if __name__ == "__main__":
+    import sys
+    if len(sys.argv) > 1:
+        plat = sys.argv[1]
+    else:
+        plat = "twitter"
+    h = resolve(plat)
+    if h:
+        sys.stdout.write(h + "\n")
+        sys.exit(0)
+    sys.stderr.write(f"no handle configured for platform={plat}\n")
+    sys.exit(1)