@xuda.io/account_module 1.2.2279 → 1.2.2281

package/index.mjs

@@ -1,5 +1,6 @@
 import path from 'path';
 import fs from 'fs';
+import crypto from 'node:crypto';
 import _ from 'lodash';
 // import { exec } from 'child_process';
 // import util from 'util';
@@ -36,6 +37,7 @@ const account_info_properties = [
   'network_country_code',
   'network_city_slug',
   'public_profile_disabled',
+  'login_screen_obj',
 ];
 
 global._conf = (await import(path.join(process.env.XUDA_HOME, "common", "load_conf.mjs"))).loadConf();
@@ -213,6 +215,19 @@ export const update_account_info = async function (req, job_id, headers) {
   delete account_obj.account_info.job_id;
   delete account_obj.account_info.app_id;
 
+  // Changing the email away from a hard-bounced address lifts an email-bounce
+  // suspension immediately (the daily sweep_email_bounces covers email changes
+  // made through any other path).
+  if (account_info_changes_arr.includes('email')) {
+    const eb = account_obj.account_email_bounce;
+    if (eb && (eb.status === 'suspended' || eb.status === 'flagged')
+      && (account_obj.account_info.email || '').toLowerCase().trim() !== (eb.recipient || '').toLowerCase().trim()) {
+      eb.status = 'cleared';
+      eb.cleared_ts = Date.now();
+      account_obj.account_email_bounce_suspended = 0;
+    }
+  }
+
   const save_ret = await db_module.save_couch_doc('xuda_accounts', account_obj);
 
   if (account_obj.account_info?.profile_picture) {
@@ -281,12 +296,21 @@ export const update_account_info = async function (req, job_id, headers) {
   return save_ret;
 };
 export const update_account_preferences = async function (req) {
-  const { uid, hide_create_button, default_dashboard, sidebar_style, enable_thumbnail_avatar_generation } = req;
+  const { uid, hide_create_button, default_dashboard, sidebar_style, enable_thumbnail_avatar_generation, sidenav_mode, newsletter_opt_in } = req;
   try {
     let account_doc = await db_module.get_couch_doc_native('xuda_accounts', uid);
     account_doc.ts = Date.now();
 
-    account_doc.preferences = { hide_create_button, default_dashboard, sidebar_style, enable_thumbnail_avatar_generation };
+    // Merge over the existing prefs so a save from a screen that doesn't
+    // know about newer keys (e.g. sidenav_mode) can't silently wipe them.
+    account_doc.preferences = { ...(account_doc.preferences || {}), hide_create_button, default_dashboard, sidebar_style, enable_thumbnail_avatar_generation };
+    // 'static' (curated groups, today's behavior) | 'recent' (auto-reorder
+    // by last activity). Only touched when the caller sends it.
+    if (sidenav_mode !== undefined) account_doc.preferences.sidenav_mode = sidenav_mode;
+    // Weekly newsletter opt-in (default true at signup). Backs the profile toggle
+    // + the onboarding checkbox; the email-footer unsubscribe link flips this same
+    // flag via router /newsletter/unsubscribe. Only touched when the caller sends it.
+    if (newsletter_opt_in !== undefined) account_doc.preferences.newsletter_opt_in = !!newsletter_opt_in;
 
     const save_ret = await db_module.save_couch_doc('xuda_accounts', account_doc);
     if (save_ret.code < 0) {
@@ -298,6 +322,80 @@ export const update_account_preferences = async function (req) {
   }
 };
 
+// ── Left-menu dash state ─────────────────────────────────────────────────
+// Per-user doc holding the sidenav's per-ITEM state: pinned items + last-
+// activity timestamps (powers the "recent" auto-reorder mode and the items
+// grid). Kept OUT of the account doc on purpose: activity is touched on
+// every app open, and the account doc has too many other writers to absorb
+// that churn. The mode itself lives in preferences.sidenav_mode.
+const DASH_STATE_ID = (uid) => `dash_state_${uid}`;
+// Newest-N cap: the sidenav/grid never needs more, and it bounds doc growth
+// for accounts that open lots of apps over years.
+const DASH_ACTIVITY_CAP = 300;
+
+const _get_dash_state_doc = async function (uid) {
+  // no_cache — this doc is read-modify-write; a stale memcached copy would
+  // silently drop pins/touches made from another node.
+  const ret = await db_module.get_couch_doc('xuda_accounts', DASH_STATE_ID(uid), true);
+  if (ret.code > 0 && ret.data) return ret.data;
+  return { _id: DASH_STATE_ID(uid), docType: 'dash_state', uid, activity: {}, pins: {} };
+};
+
+export const get_dash_state = async function (req) {
+  try {
+    if (!req.uid) return { code: -1, data: 'uid missing' };
+    const doc = await _get_dash_state_doc(req.uid);
+    return { code: 1, data: { activity: doc.activity || {}, pins: doc.pins || {} } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
+export const touch_item_activity = async function (req) {
+  const { uid, app_id } = req;
+  if (!uid || !app_id) return { code: -1, data: 'uid/app_id missing' };
+  try {
+    const doc = await _get_dash_state_doc(uid);
+    doc.activity = doc.activity || {};
+    doc.activity[app_id] = Date.now();
+
+    const keys = Object.keys(doc.activity);
+    if (keys.length > DASH_ACTIVITY_CAP) {
+      keys
+        .sort((a, b) => doc.activity[a] - doc.activity[b])
+        .slice(0, keys.length - DASH_ACTIVITY_CAP)
+        .forEach((k) => delete doc.activity[k]);
+    }
+
+    doc.ts = Date.now();
+    const save_ret = await db_module.save_couch_doc('xuda_accounts', doc);
+    if (save_ret.code < 0) throw new Error(save_ret.data);
+    return { code: 1, data: { app_id, ts: doc.activity[app_id] } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
+export const set_item_pin = async function (req) {
+  const { uid, app_id, pinned } = req;
+  if (!uid || !app_id) return { code: -1, data: 'uid/app_id missing' };
+  try {
+    const doc = await _get_dash_state_doc(uid);
+    doc.pins = doc.pins || {};
+    if (pinned) {
+      doc.pins[app_id] = Date.now();
+    } else {
+      delete doc.pins[app_id];
+    }
+    doc.ts = Date.now();
+    const save_ret = await db_module.save_couch_doc('xuda_accounts', doc);
+    if (save_ret.code < 0) throw new Error(save_ret.data);
+    return { code: 1, data: { pins: doc.pins } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
 export const save_admin_presets = async function (req) {
   const ret = await db_module.get_couch_doc('xuda_master', req.app_id);
   if (ret.code < 0) {
@@ -322,6 +420,30 @@ export const save_admin_presets = async function (req) {
   return obj;
 };
 
+// Effective entitlements = the membership plan's base quota PLUS the AI-workspace
+// add-on's credits + storage stacked on top. The Free membership tier does NOT
+// stack (it keeps its base only); every paid tier adds whatever ai_workspace plan
+// the account carries. String quotas ("unlimited", e.g. Enterprise T3) short-circuit
+// to Infinity so downstream numeric comparisons never cap. Single source of truth —
+// use for quota checks and any effective-quota display/API.
+export const get_effective_entitlements = function (account_doc) {
+  const membership = _conf.PLAN_OBJ?.[account_doc?.membership_plan];
+  const mf = membership?.features || {};
+
+  const numOrInf = (v) => (typeof v === 'string' ? Infinity : Number(v) || 0);
+  let ai_credits = numOrInf(mf.ai_credits);
+  let drive_gb = numOrInf(mf.drive);
+
+  if (account_doc?.membership_plan && account_doc.membership_plan !== 'free') {
+    const ws = _conf.PLAN_OBJ?.[account_doc?.ai_workspace_plan];
+    if (ws && ws.category === 'ai_workspace') {
+      if (Number.isFinite(ai_credits)) ai_credits += Number(ws.ai_credits) || 0;
+      if (Number.isFinite(drive_gb)) drive_gb += (Number(ws.size) || 0) / 1073741824;
+    }
+  }
+  return { ai_credits, drive_gb };
+};
+
 export const increment_account_usage = async function (req) {
   const { uid } = req;
 
@@ -367,9 +489,17 @@ export const increment_account_usage = async function (req) {
 
       if (Date.now() - doc.ts >= interval) {
         const plan = _conf.PLAN_OBJ[account_data.membership_plan];
-        if (!plan) throw new Error(`${account_data.account_info.first_name + ' ' + account_data.account_info.last_name} has no plan in file`);
+        if (!plan) {
+          // Only report missing plans for stat 3 (verified) accounts. Stat 1/2
+          // (unverified stubs, temp-pass invites, widget signups) have no plan
+          // until their first real login by design — skip silently.
+          if (account_data.stat === 3) throw new Error(`${account_data.account_info.first_name + ' ' + account_data.account_info.last_name} has no plan in file`);
+          return;
+        }
         const drive_size_total = account_data.user_drive_size + account_data.studio_drive_size + account_data.workspace_drive_size + account_data.builds_drive_size + account_data.plugins_drive_size;
-        if (bytesToGB(drive_size_total) > plan.features.drive) {
+        // Effective drive quota = membership base + stacked AI-workspace storage (paid tiers only).
+        const { drive_gb: effective_drive_gb } = get_effective_entitlements(account_data);
+        if (bytesToGB(drive_size_total) > effective_drive_gb) {
           var price_per_hour = (bytesToGB(drive_size_total) * _conf.PRICE_OBJ.price_per_gb_drive) / _conf.PRICE_OBJ.avg_hours_in_month;
 
           doc.hours++;
@@ -597,6 +727,17 @@ const is_admin_email = (email) => {
   return ADMIN_EMAILS.has(String(email).toLowerCase());
 };
 
+// Abuse-triage access = the ADMIN_EMAILS allowlist above (defense-in-depth,
+// can't be granted by editing config) OR a platform superuser (the same gate
+// the rest of the admin console — ops_*, firewall — uses). The comment above
+// says "keep this in sync with the dashboard's admin-route gate", which is now
+// the superuser check; the hardcoded email had drifted stale, locking real
+// superusers (e.g. info@xuda.ai) out of /admin/abuse.
+const is_abuse_admin = (uid, email) => {
+  if (is_admin_email(email)) return true;
+  return !!(uid && Array.isArray(_conf.superuser_account_ids) && _conf.superuser_account_ids.includes(uid));
+};
+
 // Get the active billing cycle bounds for an account, on demand from
 // Stripe. Used by recompute_abuse_signals to scope its "this cycle"
 // counters correctly. Returns { cycle_start_ts, cycle_end_ts } in ms
@@ -755,7 +896,7 @@ export const get_flagged_accounts = async function (req) {
   if (!caller_uid) return { code: -1, data: 'unauthorized' };
   try {
     const caller_ret = await db_module.get_couch_doc('xuda_accounts', caller_uid);
-    if (caller_ret.code < 0 || !is_admin_email(caller_ret.data.email)) {
+    if (caller_ret.code < 0 || !is_abuse_admin(caller_uid, caller_ret.data.email)) {
       return { code: -1, data: 'unauthorized' };
     }
 
@@ -801,7 +942,7 @@ export const sweep_abuse_signals = async function (req) {
   if (!caller_uid) return { code: -1, data: 'unauthorized' };
   try {
     const caller_ret = await db_module.get_couch_doc('xuda_accounts', caller_uid);
-    if (caller_ret.code < 0 || !is_admin_email(caller_ret.data.email)) {
+    if (caller_ret.code < 0 || !is_abuse_admin(caller_uid, caller_ret.data.email)) {
       return { code: -1, data: 'unauthorized' };
     }
 
@@ -840,7 +981,7 @@ export const mark_account_reviewed = async function (req) {
   if (!caller_uid || !target_uid) return { code: -1, data: 'uid + target_uid required' };
   try {
     const caller_ret = await db_module.get_couch_doc('xuda_accounts', caller_uid);
-    if (caller_ret.code < 0 || !is_admin_email(caller_ret.data.email)) {
+    if (caller_ret.code < 0 || !is_abuse_admin(caller_uid, caller_ret.data.email)) {
       return { code: -1, data: 'unauthorized' };
     }
 
@@ -966,6 +1107,57 @@ export const backfill_app_costs = async function (opts = {}) {
   return summary;
 };
 
+// True when a plan is team-tier or higher (team/agency/enterprise_*). Sponsoring a
+// login screen requires this tier both at invite time and while the sponsorship is served.
+export const is_login_sponsor_tier = function (membership_plan) {
+  const rank = _conf.PLAN_OBJ?.[membership_plan]?.rank;
+  const team_rank = _conf.PLAN_OBJ?.['team']?.rank;
+  return typeof rank === 'number' && typeof team_rank === 'number' && rank >= team_rank;
+};
+
+// Resolve the effective login screen for an account, pre-auth-safe.
+// Precedence: an active sponsorship (sponsor still has an image AND is still team+)
+// > the account's own personal image (only while paid) > Xuda's default video.
+// Defensive: if the sponsorship views aren't present yet, it silently falls through
+// to personal/default, so it is safe to ship before the CouchDB views are deployed.
+export const resolve_effective_login_screen = async function (account_doc) {
+  const DEFAULT = { source: 'default', media_type: 'video', file_url: null };
+  try {
+    if (!account_doc?._id) return DEFAULT;
+
+    // 1) Active sponsorship where this account is the invitee.
+    try {
+      const body = await db_module.get_couch_view_raw('xuda_team', 'login_sponsorship_by_invitee', {
+        key: account_doc._id,
+        include_docs: true,
+      });
+      const rows = body?.rows || [];
+      // newest active sponsorship wins if there are (transient) duplicates
+      const row = rows.map((r) => r.doc).filter(Boolean).sort((a, b) => (b?.team_req_status_date || 0) - (a?.team_req_status_date || 0))[0];
+      if (row?.team_req_from_uid) {
+        const { data: sponsor } = await db_module.get_couch_doc('xuda_accounts', row.team_req_from_uid);
+        const sponsor_img = sponsor?.account_info?.login_screen_obj?.file_url;
+        if (sponsor_img && is_login_sponsor_tier(sponsor?.membership_plan)) {
+          return { source: 'sponsored', media_type: 'image', file_url: sponsor_img, sponsor_uid: row.team_req_from_uid, team_req_id: row._id };
+        }
+        // sponsor deleted their image or downgraded -> fall through to personal/default
+      }
+    } catch (e) {
+      // views not deployed yet, or lookup failed -> treat as "not sponsored"
+    }
+
+    // 2) The account's own image, but only while on a paid plan.
+    const own = account_doc.account_info?.login_screen_obj;
+    if (own?.file_url && (account_doc.membership_plan || 'free') !== 'free') {
+      return { source: 'personal', media_type: 'image', file_url: own.file_url, w: own.w, h: own.h, bytes: own.bytes, uploaded_ts: own.uploaded_ts };
+    }
+
+    return DEFAULT;
+  } catch (err) {
+    return DEFAULT;
+  }
+};
+
 export const get_account_data = async function (req) {
   var { uid, enforce_usage } = req;
 
@@ -1012,6 +1204,11 @@ export const get_account_data = async function (req) {
         account_billing_hold_data: acc_obj.account_billing_hold_date,
         account_termination_status: acc_obj.account_termination_status,
         account_termination_data: acc_obj.account_termination_data,
+        // Email-bounce suspension: the user can still log in; the dashboard
+        // shows a suspension message (update email / open a ticket) and hides
+        // everything else. Cleared automatically on email change.
+        account_email_bounce_suspended: acc_obj.account_email_bounce_suspended || 0,
+        account_email_bounce_recipient: acc_obj.account_email_bounce_suspended ? acc_obj.account_email_bounce?.recipient || '' : '',
       },
       drive_usage: {
         user_drive_size: acc_obj.user_drive_size || 0,
@@ -1025,6 +1222,9 @@ export const get_account_data = async function (req) {
 
       stripe_connect_account_id: acc_obj?.stripe_connect_account_obj?.id,
       stripe_connect_account_status: acc_obj?.stripe_connect_account_status,
+      // Effective login screen (sponsored > personal > default) for the client to
+      // render + cache in a cookie for pre-auth render on the next visit.
+      login_screen: await resolve_effective_login_screen(acc_obj),
     };
 
     return ret;
@@ -1037,6 +1237,86 @@ export const get_account_data = async function (req) {
   // return get_info();
 };
 
+// reset_login_screen: restore the Xuda default. Allowed for any plan (incl. free).
+// If the caller is currently sponsored, this is a PERMANENT opt-out — it revokes the
+// sponsorship (stopping the sponsor's billing via team_module) — and it also clears
+// any personal image the caller uploaded/generated.
+export const reset_login_screen = async function (req, job_id, headers) {
+  const uid = req.uid || req.token_ret?.data?.uid;
+  if (!uid) return { code: -401, data: 'not authorized (no uid)' };
+  try {
+    const { data: account_obj } = await db_module.get_couch_doc('xuda_accounts', uid);
+    if (!account_obj) return { code: -404, data: 'account not found' };
+
+    // Sponsored -> permanent opt-out (revoke + final flush + notify sponsor).
+    let opted_out = false;
+    try {
+      const body = await db_module.get_couch_view_raw('xuda_team', 'login_sponsorship_by_invitee', { key: uid, include_docs: true });
+      const row = (body?.rows || []).map((r) => r.doc).filter(Boolean)[0];
+      const team_req_id = row?._id;
+      if (team_req_id) {
+        await team_ms.remove_login_sponsor({ uid, team_req_id });
+        opted_out = true;
+      }
+    } catch (e) {
+      // views not deployed / no sponsorship -> nothing to opt out of
+    }
+
+    // Always drop the caller's own image too (free the R2 bytes).
+    let cleared = false;
+    const prev = account_obj.account_info?.login_screen_obj;
+    if (prev) {
+      if (prev.bucket) {
+        try {
+          await drive_ms.delete_file_from_bucket(prev.bucket);
+        } catch (e) {}
+      }
+      delete account_obj.account_info.login_screen_obj;
+      account_obj.ts = Date.now();
+      await db_module.save_couch_doc('xuda_accounts', account_obj);
+      cleared = true;
+    }
+
+    return { code: 1, data: { login_screen: { source: 'default', media_type: 'video', file_url: null }, opted_out, cleared } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// get_login_screen: PUBLIC pre-auth resolver for a first visit on a new device
+// (the primary pre-auth path is the cookie the client sets after login). Returns
+// ONLY { source, media_type, file_url } — never account internals — and returns the
+// default for any unknown/plain-screen account so it can't be used to enumerate emails.
+// Prefer keying by the opaque team_req_id (from a sponsorship invite link) or uid.
+export const get_login_screen = async function (req) {
+  const DEFAULT = { code: 1, data: { source: 'default', media_type: 'video', file_url: null } };
+  try {
+    const { email, uid, team_req_id } = req;
+    let account_obj = null;
+
+    if (uid) {
+      const r = await db_module.get_couch_doc('xuda_accounts', uid);
+      account_obj = r?.data || null;
+    } else if (team_req_id) {
+      const r = await db_module.get_couch_doc('xuda_team', team_req_id);
+      const row = r?.data;
+      if (row?.access_type === 'login_sponsorship' && row?.team_req_to_uid) {
+        const a = await db_module.get_couch_doc('xuda_accounts', row.team_req_to_uid);
+        account_obj = a?.data || null;
+      }
+    } else if (email) {
+      const ret = await db_module.find_couch_query('xuda_accounts', { selector: { 'account_info.email': email }, limit: 1 });
+      account_obj = ret?.docs?.[0] || null;
+    }
+
+    if (!account_obj) return DEFAULT;
+    const eff = await resolve_effective_login_screen(account_obj);
+    return { code: 1, data: { source: eff.source, media_type: eff.media_type, file_url: eff.file_url } };
+  } catch (err) {
+    return DEFAULT;
+  }
+};
+
 export const get_account_projects = async function (req) {
   const { uid } = req;
   var opt = {
@@ -1114,6 +1394,25 @@ export const get_account_static_websites = async function (req) {
   }
 };
 
+// External apps are apps (app_type:'external_app') not emitted by any user_*
+// view — same Mango-query approach as get_account_static_websites → so the
+// sidenav bucket (DATA.external_app) picks up a newly connected app right after
+// create, without a full account reload.
+export const get_account_external_apps = async function (req) {
+  try {
+    const isSuper = _conf.superuser_account_ids?.includes(req.uid);
+    const selector = isSuper ? { app_type: 'external_app', docType: 'app' } : { app_uId: req.uid, app_type: 'external_app', docType: 'app' };
+    const ret = await db_module.find_couch_query('xuda_master', {
+      selector,
+      limit: 1000,
+    });
+    const rows = (ret?.docs || []).map((d) => ({ id: d._id, value: d }));
+    return { code: 1, data: { rows } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
 export const get_account_info = async function (req) {
   return await get_account_data({
     uid: req.uid,
@@ -1307,6 +1606,172 @@ export const ops_list_terminations = async function (req = {}) {
   } catch (err) { return { code: -1, data: err.message }; }
 };
 
+// ===================================================================
+// Ops customer-admin helpers (superuser only): lookup + billing hold +
+// AI-credit grant + direct notification. Same auth model as the
+// suspend/terminate ladder above — `req.uid` is the authenticated ops
+// caller (the HTTP layer sets it from the session), and the TARGET is
+// always passed as `account_uid`.
+// ===================================================================
+
+// Lean, safe account summary for the ops dashboard (never leaks secrets/tokens).
+const _ops_account_summary = (a) => ({
+  account_uid: a._id,
+  email: a.account_info?.email || '',
+  name: `${a.account_info?.first_name || ''} ${a.account_info?.last_name || ''}`.trim() || a.account_info?.full_name || '',
+  membership_plan: a.membership_plan || 'free',
+  ai_workspace_plan: a.ai_workspace_plan || '',
+  suspended: a.account_suspension_status === 1,
+  terminated: a.account_termination_status === 1,
+  billing_hold: a.account_billing_hold_status === 1,
+  appeal_status: a.appeal_status || 'none',
+  finalized: !!a.termination_finalized_ts,
+});
+
+// Find accounts by email / name / uid (substring, case-insensitive).
+export const ops_find_account = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const q = String(req.query || '').trim();
+    if (!q) return { code: -1, data: 'query is required' };
+    const rx = `(?i)${q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`;
+    const ret = await db_module.find_couch_query('xuda_accounts', {
+      selector: {
+        docType: 'account',
+        $or: [
+          { 'account_info.email': { $regex: rx } },
+          { 'account_info.full_name': { $regex: rx } },
+          { _id: { $regex: rx } },
+        ],
+      },
+      limit: 25,
+    }, true);
+    return { code: 1, data: { rows: (ret.docs || []).map(_ops_account_summary) } };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
+// Full status snapshot for one account incl. live AI-credit balance.
+export const ops_account_snapshot = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const account_uid = req.account_uid;
+    if (!account_uid) return { code: -1, data: 'account_uid is required' };
+    const ar = await db_module.get_couch_doc('xuda_accounts', account_uid);
+    if (ar.code < 0 || !ar.data) return { code: -1, data: 'account not found' };
+    const a = ar.data;
+    let credits = { max: 0, used: 0, remaining: 0 };
+    try {
+      const cr = await get_account_ai_usage({ uid: account_uid });
+      if (cr && cr.code === 55) {
+        const max = Math.round((cr.data?.credits?.total || 0) * 100) / 100;
+        const used = Math.round((cr.data?.usage?.total || 0) * 100) / 100;
+        credits = { max, used, remaining: Math.round((max - used) * 100) / 100, by_source: cr.data?.credits || {} };
+      }
+    } catch (e) { console.error('[ops snapshot credits]', e.message); }
+    return {
+      code: 1,
+      data: {
+        ..._ops_account_summary(a),
+        suspension_date: a.account_suspension_date || null,
+        suspension_reason: a.suspension_reason || '',
+        termination_date: a.account_termination_date || null,
+        termination_reason: a.termination_reason || '',
+        appeal_deadline: a.termination_appeal_deadline || null,
+        billing_hold_date: a.account_billing_hold_date || null,
+        billing_hold_reason: a.billing_hold_reason || '',
+        reinstated_ts: a.reinstated_ts || null,
+        entitlements: get_effective_entitlements(a),
+        credits,
+      },
+    };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
+// Put an account's billing on hold (manual; mirrors the Stripe-webhook hold).
+export const ops_set_billing_hold = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const account_uid = req.account_uid;
+    if (!account_uid) return { code: -1, data: 'account_uid is required' };
+    const ar = await db_module.get_couch_doc('xuda_accounts', account_uid);
+    if (ar.code < 0 || !ar.data) return { code: -1, data: 'account not found' };
+    const account = ar.data;
+    account.account_billing_hold_status = 1;
+    account.account_billing_hold_date = Date.now();
+    account.billing_hold_reason = req.reason || '';
+    account.billing_hold_by_uid = req.uid;
+    const sr = await db_module.save_couch_doc('xuda_accounts', account);
+    if (sr.code < 0) return { code: -1, data: sr.data };
+    ws_dashboard_msa.emit_message_to_dashboard({ service: 'account_billing_hold_applied', to: [account_uid], data: { account_billing_hold_status: 1, account_billing_hold_date: account.account_billing_hold_date } });
+    _ops_notify_ops(`Billing hold applied: ${account.account_info?.email || account_uid}`, [['Account', account_uid], ['Email', account.account_info?.email], ['By', req.uid], ['Reason', req.reason || '']], 'OPS-BHOLD');
+    logs_msa.add_account_log({ uid: account_uid, method: 'ops_set_billing_hold', source: 'ops dashboard', response_status_code: 200, response_data: `billing hold by ${req.uid}` });
+    return { code: 1, data: { billing_hold: account_uid } };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
+// Release a billing hold (mirrors release_account_billing_hold_if_current).
+export const ops_release_billing_hold = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const account_uid = req.account_uid;
+    if (!account_uid) return { code: -1, data: 'account_uid is required' };
+    const ar = await db_module.get_couch_doc('xuda_accounts', account_uid);
+    if (ar.code < 0 || !ar.data) return { code: -1, data: 'account not found' };
+    const account = ar.data;
+    account.account_billing_hold_status = 0;
+    account.account_billing_hold_date = Date.now();
+    account.billing_hold_by_uid = req.uid;
+    const sr = await db_module.save_couch_doc('xuda_accounts', account);
+    if (sr.code < 0) return { code: -1, data: sr.data };
+    ws_dashboard_msa.emit_message_to_dashboard({ service: 'account_billing_hold_released', to: [account_uid], data: { account_billing_hold_status: 0, account_billing_hold_date: account.account_billing_hold_date } });
+    _ops_notify_ops(`Billing hold released: ${account.account_info?.email || account_uid}`, [['Account', account_uid], ['Email', account.account_info?.email], ['By', req.uid]], 'OPS-BHOLD');
+    logs_msa.add_account_log({ uid: account_uid, method: 'ops_release_billing_hold', source: 'ops dashboard', response_status_code: 200, response_data: `billing hold released by ${req.uid}` });
+    return { code: 1, data: { released: account_uid } };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
+// Grant AI credits to an account (idempotent per unique details string).
+export const ops_add_ai_credits = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const account_uid = req.account_uid;
+    const credits = Number(req.credits);
+    if (!account_uid) return { code: -1, data: 'account_uid is required' };
+    if (!Number.isFinite(credits) || credits <= 0) return { code: -1, data: 'credits must be a positive number' };
+    if (credits > 100000) return { code: -1, data: 'credits exceeds max single grant (100000)' };
+    const ar = await db_module.get_couch_doc('xuda_accounts', account_uid);
+    if (ar.code < 0 || !ar.data) return { code: -1, data: 'account not found' };
+    const account = ar.data;
+    const details = `admin grant ${credits} by ${req.uid} @ ${Date.now()}`;
+    const cr = await record_ai_credit(req.uid, credits, 'admin_grant', details, account_uid);
+    if (cr.code < 0) return { code: -1, data: cr.data };
+    if (req.notify) {
+      notification_msa.submit_notification({ type: 'account', uid_arr: [account_uid], subject: `${credits} AI credits added to your account`, body: `<h2>${credits} AI credits added</h2><p>Our team has added ${credits} AI credits to your account. Enjoy!</p>`, delivery_method: ['banner', 'email'], display_type: 'success' });
+    }
+    _ops_notify_ops(`AI credits granted: ${account.account_info?.email || account_uid}`, [['Account', account_uid], ['Email', account.account_info?.email], ['By', req.uid], ['Credits', credits], ['Reason', req.reason || '']], 'OPS-CREDIT');
+    logs_msa.add_account_log({ uid: account_uid, method: 'ops_add_ai_credits', source: 'ops dashboard', response_status_code: 200, response_data: `granted ${credits} credits by ${req.uid}` });
+    return { code: 1, data: { credited: account_uid, credits } };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
+// Send a direct notification to a single customer (banner + email by default).
+export const ops_send_notification = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const account_uid = req.account_uid;
+    const subject = String(req.subject || '').trim();
+    const body_in = String(req.body || '').trim();
+    if (!account_uid) return { code: -1, data: 'account_uid is required' };
+    if (!subject || !body_in) return { code: -1, data: 'subject and body are required' };
+    const body = /<[a-z][\s\S]*>/i.test(body_in) ? body_in : `<p>${body_in.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\n/g, '<br>')}</p>`;
+    const delivery_method = Array.isArray(req.delivery_method) && req.delivery_method.length ? req.delivery_method : ['banner', 'email'];
+    const display_type = req.display_type || 'info';
+    const nr = await notification_msa.submit_notification({ type: 'account', uid_arr: [account_uid], subject, body, delivery_method, display_type, sender_uid: req.uid });
+    logs_msa.add_account_log({ uid: account_uid, method: 'ops_send_notification', source: 'ops dashboard', response_status_code: 200, response_data: `notification "${subject}" sent by ${req.uid} via ${delivery_method.join('+')}` });
+    return { code: 1, data: { sent: account_uid, notification: nr?.data || {} } };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
 const TIPS_FILE_PATH = path.join(process.env.XUDA_HOME, 'dist', 'tips', 'tips.json');
 let _did_you_know_tips_cache = null;
 let _did_you_know_tips_cache_mtime = 0;
@@ -1686,10 +2151,10 @@ export const validate_user_plan = async function (req) {
     // group_level: 2,
   });
 
-  if (app_obj.app_type === 'master' && user_active_app_requests_count_ret.data?.rows?.[0]?.value >= plan.features.team) {
+  if (app_obj.app_type === 'master' && user_active_app_requests_count_ret.data?.rows?.[0]?.value >= plan.features.team_members) {
     return {
       code: -9,
-      data: `Number of team shares (${user_active_app_requests_count_ret.data.rows[0].value}) exceeds to the ${plan.features.team} plan limits`,
+      data: `Number of team shares (${user_active_app_requests_count_ret.data.rows[0].value}) exceeds to the ${plan.features.team_members} plan limits`,
     };
   }
 
@@ -1765,6 +2230,83 @@ export const add_account_log_util = async function (body, status, service, sourc
   logs_msa.add_account_log(get_account_log_object(body, status, service, source, response_data, ip, headers, security));
 };
 
+// Prefixes for read-style methods — reads are not "actions on the entity", so
+// they're excluded from the app action log (mirrors the account-log read skip).
+const _APP_LOG_READ_PREFIXES = ['get_', 'list_', 'find_', 'search_', 'count_', 'check_', 'read_', 'fetch_', 'preview_', 'validate_'];
+// Keys never copied into the slim arg_summary (defence-in-depth vs. secret bloat).
+const _APP_LOG_ARG_SENSITIVE = /pass|token|secret|key|cred|card|cvv|ssh|auth|otp|code/i;
+
+const _app_log_resolve_app_id = (body, response_data) => {
+  const d = (body && body.data) || {};
+  const r = response_data || {};
+  return (
+    d.app_id ||
+    body?.app_id ||
+    r.app_id ||
+    r.data?.app_id ||
+    r.app_obj?._id ||
+    r.data?.app_obj?._id ||
+    null
+  );
+};
+
+// Build a tiny, sanitized summary of the action's arguments for the log row —
+// short scalars only, sensitive keys dropped, capped in count + length.
+const _app_log_arg_summary = (body) => {
+  try {
+    const d = (body && body.data) || {};
+    const out = {};
+    let n = 0;
+    for (const [k, v] of Object.entries(d)) {
+      if (n >= 12) break;
+      if (_APP_LOG_ARG_SENSITIVE.test(k)) continue;
+      if (v === null) continue;
+      const t = typeof v;
+      if (t === 'string') out[k] = v.length > 120 ? v.slice(0, 120) + '…' : v;
+      else if (t === 'number' || t === 'boolean') out[k] = v;
+      else continue;
+      n++;
+    }
+    return Object.keys(out).length ? out : null;
+  } catch (e) {
+    return null;
+  }
+};
+
+// Entity ACTION log. Sibling of add_account_log_util, but purpose-built for the
+// per-entity Logs tab: records any action taken ON an app/server/vps/external
+// app (keyed by app_id), INCLUDING private methods (external_app's are private),
+// and EXCLUDING pure reads. Stored centrally via logs_module.add_app_log so it
+// works for standalone/server apps that have no project DB.
+export const add_app_log_util = async function (body, status, service, source, response_data, ip, headers) {
+  try {
+    if (!service || !_conf.cpi_methods?.[service]) return;
+    const app_id = _app_log_resolve_app_id(body, response_data);
+    if (!app_id) return; // not an entity action
+
+    // Skip read-style calls made without a developer key — they aren't actions.
+    const is_key = !!(body?.api_key || body?.api_pk || body?.api_sk);
+    if (!is_key && _APP_LOG_READ_PREFIXES.some((p) => service.startsWith(p))) return;
+    // Don't log the log-reader itself, or the utils, to avoid recursion/noise.
+    if (service === 'get_logs' || service === 'get_logs_counts' || service === 'add_account_log_util' || service === 'add_app_log_util') return;
+
+    const channel = headers?.['xu-channel'] === 'mcp' ? 'mcp' : is_key ? 'api' : 'dashboard';
+    logs_msa.add_app_log({
+      app_id,
+      uid: body?.uid,
+      method: service,
+      method_label: _conf.cpi_methods?.[service]?.name || service,
+      source,
+      channel,
+      response_status_code: status,
+      ip,
+      arg_summary: _app_log_arg_summary(body),
+    });
+  } catch (e) {
+    console.error('add_app_log_util', e.message);
+  }
+};
+
 export const save_ssh_key = async function (req) {
   const { uid, _id, ssh_key_name, ssh_key_content } = req;
 
@@ -2860,30 +3402,57 @@ const _bounce_settings_url = () => {
   return `https://${host}/dashboard/settings`;
 };
 
-// Alert the user to update their email (banner + SMS per the topic's delivery
-// methods). SMS is gated/log-only in notification_module until sms_enabled.
-const _send_bounce_alert = async (account, attempt, max) => {
+// Suspension notices: in-dashboard banner + SMS to the user (email would just
+// bounce again; SMS is gated/log-only in notification_module until sms_enabled)
+// and an ops email to the superusers.
+const _notify_bounce_suspended = async (account) => {
   const eb = account.account_email_bounce || {};
-  return await notification_msa.submit_notification({
-    type: 'account',
-    app_id: null,
-    uid_arr: [account._id],
-    topic: 'email_bounce_update_required',
-    params: {
-      recipient_email: eb.recipient || account.account_info?.email || '',
-      settings_url: _bounce_settings_url(),
-      attempt,
-      max,
-    },
-  });
+  const host = _conf.is_debug ? process.env.XUDA_HOSTNAME || _conf.domain : _conf.domain;
+  try {
+    await notification_msa.submit_notification({
+      type: 'account',
+      app_id: null,
+      uid_arr: [account._id],
+      topic: 'email_bounce_update_required',
+      params: {
+        recipient_email: eb.recipient || account.account_info?.email || '',
+        settings_url: _bounce_settings_url(),
+        support_url: `https://${host}/dashboard/support`,
+      },
+    });
+  } catch (e) { console.error('bounce user notice failed:', e.message); }
+  const supers = _conf.superuser_account_ids || [];
+  if (supers.length) {
+    try {
+      await notification_msa.submit_notification({
+        type: 'account',
+        app_id: null,
+        uid_arr: supers,
+        topic: 'email_bounce_suspended',
+        system: true,
+        params: {
+          uid: account._id,
+          account_email: account.account_info?.email || eb.recipient || '',
+          recipient: eb.recipient || '',
+          reason: eb.reason || '',
+          status_code: eb.status_code || '',
+          attempts: eb.bounce_count || 1,
+          domain: host,
+        },
+      });
+    } catch (e) { console.error('ops bounce-suspend alert failed:', e.message); }
+  }
 };
 
-// Hard-email-bounce flag. Called (via account_ms RPC) by email_module's
+// Hard-email-bounce handler. Called (via account_ms RPC) by email_module's
 // scan_platform_bounces when a platform email to this account's address bounces
-// permanently (5.x.x). Records the flag and, on the FIRST transition into
-// flagged, fires alert #1 immediately (attempts 2..max + suspend are driven by
-// the daily sweep_email_bounces cron). Idempotent: repeated bounces for an
-// already-flagged/suspended account only refresh last_bounce_ts (no re-alert).
+// permanently (5.x.x). Policy: suspend IMMEDIATELY (account_email_bounce_suspended,
+// enforced at router_module.validate_app_active_status; outbound platform email
+// to the bounced address is suppressed in notification_module). The user can
+// still log in: the dashboard shows the suspension message and they can open a
+// support ticket or update their email, which lifts the suspension instantly
+// (update_account_info) or via the daily sweep.
+// TODO(long-term): notify by SMS/voice first, wait a grace window, then suspend.
 export const flag_email_bounce = async function (req) {
   const { uid, recipient, reason, status_code, message_id, source } = req || {};
   if (!uid) return { code: -1, data: 'uid required' };
@@ -2893,8 +3462,7 @@ export const flag_email_bounce = async function (req) {
     const account = acct_ret.data;
     const now = Date.now();
     const eb = account.account_email_bounce || {};
-    const was_active = eb.status === 'flagged' || eb.status === 'suspended';
-    const max = Number(_conf.bounce_monitor?.suspend_after_alerts || 3);
+    const was_suspended = eb.status === 'suspended';
 
     eb.recipient = recipient || eb.recipient;
     eb.reason = reason || eb.reason;
@@ -2903,49 +3471,38 @@ export const flag_email_bounce = async function (req) {
     eb.source = source || eb.source || 'dsn';
     eb.last_bounce_ts = now;
     eb.bounce_count = (eb.bounce_count || 0) + 1;
-    if (eb.status !== 'suspended') {
-      eb.status = 'flagged';
-      eb.first_bounce_ts = eb.first_bounce_ts || now;
-      if (!was_active) {
-        // Fresh flag -> immediate first alert.
-        eb.attempt_count = 1;
-        eb.first_alert_ts = now;
-        eb.last_attempt_ts = now;
-      } else if (eb.attempt_count == null) {
-        eb.attempt_count = 0;
-      }
+    eb.first_bounce_ts = eb.first_bounce_ts || now;
+    if (!was_suspended) {
+      eb.status = 'suspended';
+      eb.suspended_ts = now;
+      account.account_email_bounce_suspended = 1;
     }
 
     account.account_email_bounce = eb;
     const save_ret = await db_module.save_couch_doc('xuda_accounts', account);
     if (save_ret.code < 0) return save_ret;
 
-    if (!was_active) {
-      try { await _send_bounce_alert(account, 1, max); } catch (e) { console.error('flag_email_bounce alert #1 failed:', e.message); }
-    }
-    console.log(`flag_email_bounce: ${uid} <${recipient}> ${status_code || ''} -> status=${eb.status} attempt=${eb.attempt_count} bounce_count=${eb.bounce_count}${!was_active ? ' (alert #1 sent)' : ''}`);
-    return { code: 1, data: { uid, status: eb.status, attempt_count: eb.attempt_count, bounce_count: eb.bounce_count } };
+    if (!was_suspended) await _notify_bounce_suspended(account);
+    console.log(`flag_email_bounce: ${uid} <${recipient}> ${status_code || ''} -> status=${eb.status} bounce_count=${eb.bounce_count}${!was_suspended ? ' (suspended now)' : ''}`);
+    return { code: 1, data: { uid, status: eb.status, bounce_count: eb.bounce_count } };
   } catch (err) {
     console.error('flag_email_bounce error:', err);
     return { code: -10, data: err.message };
   }
 };
 
-// Daily retry/escalation sweep for flagged accounts (controller cron). For each
-// account with account_email_bounce.status === 'flagged':
-//   - if the user changed their email away from the bounced address -> CLEAR;
-//   - else if under the alert cap and >= alert_interval since last -> next alert;
-//   - else (cap reached) -> SUSPEND (account_email_bounce_suspended) + ops alert.
-// `req` overrides: { interval_ms, max, limit, uids }.
+// Daily reconciliation sweep (controller cron) over bounce-affected accounts:
+//   - email changed away from the bounced address -> CLEAR the suspension
+//     (update_account_info already clears synchronously on the dashboard path;
+//     this catches email changes made any other way);
+//   - status still 'flagged' (legacy state from the pre-immediate-suspend alert
+//     ladder) -> SUSPEND now.
+// `req` overrides: { limit, uids }.
 export const sweep_email_bounces = async function (req = {}) {
-  const bm = _conf.bounce_monitor || {};
-  const DAY_MS = 24 * 60 * 60 * 1000;
-  const interval = Number(req.interval_ms ?? bm.alert_interval_ms ?? DAY_MS);
-  const max = Number(req.max ?? bm.suspend_after_alerts ?? 3);
   const now = Date.now();
-  const summary = { flagged: 0, cleared: 0, alerted: 0, suspended: 0, skipped: 0 };
+  const summary = { matched: 0, cleared: 0, suspended: 0, skipped: 0 };
   try {
-    const selector = { 'account_email_bounce.status': 'flagged' };
+    const selector = { 'account_email_bounce.status': { $in: ['flagged', 'suspended'] } };
     if (Array.isArray(req.uids) && req.uids.length) selector._id = { $in: req.uids };
     const find_ret = await db_module.find_couch_query('xuda_accounts', {
       selector,
@@ -2953,14 +3510,14 @@ export const sweep_email_bounces = async function (req = {}) {
       limit: req.limit ?? 99999,
     });
     const rows = find_ret?.data?.docs || find_ret?.docs || [];
-    summary.flagged = rows.length;
+    summary.matched = rows.length;
 
     for (const row of rows) {
       const acct_ret = await db_module.get_couch_doc('xuda_accounts', row._id);
       if (acct_ret.code < 0) continue;
       const account = acct_ret.data;
       const eb = account.account_email_bounce;
-      if (!eb || eb.status !== 'flagged') { summary.skipped++; continue; }
+      if (!eb || (eb.status !== 'flagged' && eb.status !== 'suspended')) { summary.skipped++; continue; }
 
       // CLEAR: the user updated their email away from the bounced address.
       const cur_email = (account.account_info?.email || '').toLowerCase().trim();
@@ -2968,55 +3525,22 @@ export const sweep_email_bounces = async function (req = {}) {
         eb.status = 'cleared';
         eb.cleared_ts = now;
         account.account_email_bounce = eb;
+        account.account_email_bounce_suspended = 0;
         await db_module.save_couch_doc('xuda_accounts', account);
         summary.cleared++;
         continue;
       }
 
-      // Cadence gate.
-      if (eb.last_attempt_ts && now - eb.last_attempt_ts < interval) { summary.skipped++; continue; }
-
-      if ((eb.attempt_count || 0) < max) {
-        const next = (eb.attempt_count || 0) + 1;
-        eb.attempt_count = next;
-        eb.last_attempt_ts = now;
-        account.account_email_bounce = eb;
-        await db_module.save_couch_doc('xuda_accounts', account);
-        try { await _send_bounce_alert(account, next, max); } catch (e) { console.error('bounce alert failed:', e.message); }
-        summary.alerted++;
-      } else {
-        // SUSPEND after the alert cap. Dedicated flag (enforced at
-        // router_module.validate_app_active_status alongside billing
-        // suspension) so we never clobber account_suspension_status.
+      if (eb.status === 'flagged') {
         eb.status = 'suspended';
         eb.suspended_ts = now;
         account.account_email_bounce = eb;
         account.account_email_bounce_suspended = 1;
         await db_module.save_couch_doc('xuda_accounts', account);
-
-        const host = _conf.is_debug ? process.env.XUDA_HOSTNAME || _conf.domain : _conf.domain;
-        const supers = _conf.superuser_account_ids || [];
-        if (supers.length) {
-          try {
-            await notification_msa.submit_notification({
-              type: 'account',
-              app_id: null,
-              uid_arr: supers,
-              topic: 'email_bounce_suspended',
-              system: true,
-              params: {
-                uid: account._id,
-                account_email: account.account_info?.email || eb.recipient || '',
-                recipient: eb.recipient || '',
-                reason: eb.reason || '',
-                status_code: eb.status_code || '',
-                attempts: eb.attempt_count || max,
-                domain: host,
-              },
-            });
-          } catch (e) { console.error('ops bounce-suspend alert failed:', e.message); }
-        }
+        await _notify_bounce_suspended(account);
         summary.suspended++;
+      } else {
+        summary.skipped++;
       }
     }
     console.log('sweep_email_bounces:', JSON.stringify(summary));
@@ -5231,3 +5755,557 @@ setTimeout(async () => {
   const uid = 'd39126e0e2c51ffbd1aad10709fc8335';
   // onboarding_completed({ uid });
 }, 2000);
+
+// ============================================================================
+// WEEKLY NEWSLETTER ENGINE
+// ----------------------------------------------------------------------------
+// The controller_module weekly cron (master only) calls newsletter_generate,
+// which assembles one item from each content source (did_you_know / dev_articles
+// / news_articles CouchDB + a fashion promo + a feature highlight), mints a fresh
+// 10% monthly Stripe coupon, saves a NUMBERED draft issue to xuda_newsletter, and
+// emails a sample to ops (info@xuda.ai) + a superuser notification for review.
+// Nothing goes to subscribers until a superuser hits Publish in the dashboard
+// (newsletter_publish), which blasts to every preferences.newsletter_opt_in
+// account with a per-recipient unsubscribe link + List-Unsubscribe header.
+// Opt-out flips the same flag the router /newsletter/unsubscribe route reads.
+// ============================================================================
+const NEWSLETTER_DB = 'xuda_newsletter';
+
+// Curated pool for the weekly coupon + "explore a feature" highlight. Ads are
+// deliberately absent — they're never discounted (and are one-off charges, so a
+// subscription coupon can't apply to them anyway).
+// gif = basename under https://xuda.ai/dist/images/email/<gif>.gif (the same
+// animated demos the onboarding email uses). Only vps/studio/contacts/ai_chats
+// exist, so features reuse the closest match.
+const NEWSLETTER_FEATURES = [
+  { key: 'vps', label: 'VPS', blurb: 'Spin up a full Linux VPS on the Xuda farm in seconds.', gif: 'vps' },
+  { key: 'static_website', label: 'Static Website', blurb: 'Host a blazing-fast static site with a free subdomain or your own domain.', gif: 'studio' },
+  { key: 'full_stack_vps', label: 'Full Stack VPS', blurb: 'An AI-managed box that reads, writes and fixes its own files and databases.', gif: 'vps' },
+  { key: 'auto_backup', label: 'Automatic Backups', blurb: 'Scheduled, restorable backups for your apps and data.', gif: 'vps' },
+  { key: 'custom_domain', label: 'Custom Domains', blurb: 'Connect your own domain with automatic TLS.', gif: 'studio' },
+  { key: 'drive', label: 'Xuda Drive', blurb: 'Store, share and OCR your files right inside your workspace.', gif: 'contacts' },
+  { key: 'ai_workspace', label: 'AI Workspace', blurb: 'Build apps by chatting with AI agents that ship real code.', gif: 'ai_chats' },
+];
+const _nl_gif_url = (g) => (g ? `https://xuda.ai/dist/images/email/${g}.gif` : '');
+
+const _nl_esc = (v) =>
+  String(v == null ? '' : v).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+// Next issue number = max(existing) + 1. Read-only projection (never PUT these).
+const _nl_next_number = async () => {
+  try {
+    const ret = await db_module.find_couch_query(NEWSLETTER_DB, { selector: { docType: 'newsletter_issue' }, fields: ['issue_number'], limit: 100000 }, true);
+    return (ret.docs || []).reduce((m, d) => Math.max(m, d.issue_number || 0), 0) + 1;
+  } catch (e) {
+    return 1;
+  }
+};
+
+// One random published doc of a docType from a content DB.
+const _nl_one = async (db, docType) => {
+  try {
+    const ret = await db_module.find_couch_query(db, { selector: { docType }, limit: 300 }, true);
+    const docs = (ret.docs || []).filter((d) => d.published !== false);
+    return docs.length ? docs[Math.floor(Math.random() * docs.length)] : null;
+  } catch (e) {
+    return null;
+  }
+};
+
+const _nl_fashion_url = (p) => {
+  const rel = p.custom_url || (p.slug ? '/' + p.slug : '');
+  return `https://xuda.fashion${rel}`;
+};
+const _nl_fashion_img = (p) => {
+  const first = p.images && (p.images.front || Object.values(p.images)[0]);
+  return first ? `https://xuda.fashion${first}` : '';
+};
+// A fashion product prioritized to the recipient's CITY, then COUNTRY, then a
+// featured active tee, then the classic tee (mirrors the city-merch placeholder
+// rule). Matches the city/country name inside the product title or tags.
+// `rotate` (the issue number) rotates through the matching tees so each weekly
+// issue features a different shirt for the same city/country.
+const _nl_fashion_for = (pool, country, city, rotate = 0) => {
+  const CLASSIC = { title: 'XUDA.AI Classic Tee', url: 'https://xuda.fashion', img: '' };
+  if (!Array.isArray(pool) || !pool.length) return CLASSIC;
+  const mk = (p) => ({ title: p.title, url: _nl_fashion_url(p), img: _nl_fashion_img(p) });
+  const hay = (p) => `${p.title || ''} ${(p.tags || []).join(' ')}`.toLowerCase();
+  const rot = (arr) => arr[(((rotate | 0) % arr.length) + arr.length) % arr.length];
+  const cty = String(city || '').trim().toLowerCase();
+  const ctry = String(country || '').trim().toLowerCase();
+  if (cty) {
+    const hits = pool.filter((p) => hay(p).includes(cty));
+    if (hits.length) return mk(rot(hits));
+  }
+  if (ctry && ctry.length > 2) {
+    const hits = pool.filter((p) => hay(p).includes(ctry));
+    if (hits.length) return mk(rot(hits));
+  }
+  const actives = pool.filter((p) => p.active !== false);
+  const list = actives.length ? actives : pool;
+  return list.length ? mk(rot(list)) : CLASSIC;
+};
+
+const _nl_fashion_pool = async () => {
+  try {
+    const fr = await db_module.find_couch_query('xuda_website', { selector: { docType: 'xuda_fashion' }, limit: 200 }, true);
+    return fr.docs || [];
+  } catch (e) {
+    return [];
+  }
+};
+
+// xuda.network partners (ambassadors + mentors) are xuda_accounts flagged
+// is_xuda_network_ambassador; the role is encoded in network_profile_url
+// (.../ambassadors/... vs .../mentors/...), keyed by network_country_code + city.
+const _nl_partner_pool = async () => {
+  try {
+    const r = await db_module.find_couch_query('xuda_accounts', { selector: { docType: 'account', 'account_info.is_xuda_network_ambassador': true }, limit: 500 }, true);
+    return (r.docs || []).map((d) => {
+      const a = d.account_info || {};
+      const url = a.network_profile_url || '';
+      return {
+        name: [a.first_name, a.last_name].filter(Boolean).join(' ') || a.username || 'Xuda partner',
+        role: /\/mentors\//i.test(url) ? 'mentor' : /\/ambassadors\//i.test(url) ? 'ambassador' : '',
+        cc: (a.network_country_code || '').toLowerCase(),
+        country: (a.country || '').toLowerCase(),
+        city: (a.city || '').toLowerCase(),
+        pic: a.profile_picture || a.profile_avatar || '',
+        url,
+      };
+    });
+  } catch (e) {
+    return [];
+  }
+};
+
+// One ambassador + one mentor for the recipient, prioritized city → cc → country.
+const _nl_partners_for = (pool, cc, country, city) => {
+  if (!Array.isArray(pool) || !pool.length) return { ambassador: null, mentor: null };
+  const wcc = String(cc || '').toLowerCase();
+  const wcity = String(city || '').trim().toLowerCase();
+  const wctry = String(country || '').trim().toLowerCase();
+  const pick = (role) => {
+    const list = pool.filter((p) => p.role === role && p.url);
+    if (!list.length) return null;
+    return (
+      (wcity && list.find((p) => p.city && p.city === wcity)) ||
+      (wcc && list.find((p) => p.cc && p.cc === wcc)) ||
+      (wctry && wctry.length > 1 && list.find((p) => p.country && p.country === wctry)) ||
+      null
+    );
+  };
+  return { ambassador: pick('ambassador'), mentor: pick('mentor') };
+};
+
+// Ensure the account carries an opaque unsubscribe token; mint + save if missing.
+const _nl_ensure_unsub_token = async (account) => {
+  if (account.newsletter_unsub_token) return account.newsletter_unsub_token;
+  account.newsletter_unsub_token = crypto.randomBytes(16).toString('hex');
+  try {
+    await db_module.save_couch_doc('xuda_accounts', account);
+  } catch (e) {}
+  return account.newsletter_unsub_token;
+};
+
+// Render the issue to rich HTML for one recipient (fashion + unsubscribe +
+// greeting are per-recipient; the rest is shared issue content). Design language
+// mirrors the onboarding email: image cards, a dark gradient feature card, a
+// bright coupon hero, emoji section labels, #0091FF buttons. Sits inside the
+// platform email_template.html wrapper (which adds the XUDA logo + ~500px card).
+const _nl_titlecase = (s) => String(s || '').replace(/\b\w/g, (m) => m.toUpperCase());
+const _nl_avatar_url = (host, pic) => {
+  const p = String(pic || '');
+  if (/^https?:\/\//i.test(p)) return p;
+  if (p.startsWith('/')) return `https://xuda.ai${p}`;
+  return '';
+};
+
+const _nl_render_email = (issue, { host, first_name, fashion, partners, unsub_url }) => {
+  const c = issue.content || {};
+  const esc = _nl_esc;
+  const btn = (href, txt, bg = '#0091FF', fg = '#fff') =>
+    `<a href="${esc(href)}" style="display:inline-block;background:${bg};color:${fg};text-decoration:none;padding:11px 24px;border-radius:9px;font-weight:700;font-size:14px">${esc(txt)} &rarr;</a>`;
+
+  // A white content card with an optional top image. imgFit 'cover' crops to a
+  // banner; 'contain' shows the WHOLE image (used for the t-shirt) on imgBg.
+  const card = ({ img, imgAlt, emoji, label, title, href, text, btnText, btnHref, imgFit = 'cover', imgBg = '#f4f6fa', imgMaxH = '210px' }) => {
+    let image = '';
+    if (img) {
+      const inner = imgFit === 'contain'
+        ? `<div style="background:${imgBg};text-align:center;padding:16px"><img src="${esc(img)}" alt="${esc(imgAlt || '')}" style="display:inline-block;max-width:100%;max-height:${imgMaxH};height:auto"></div>`
+        : `<img src="${esc(img)}" alt="${esc(imgAlt || '')}" width="100%" style="display:block;width:100%;max-height:${imgMaxH};object-fit:cover">`;
+      image = `<a href="${esc(href || btnHref || '#')}" style="text-decoration:none">${inner}</a>`;
+    }
+    const titleHtml = href ? `<a href="${esc(href)}" style="color:#0b1220;text-decoration:none">${esc(title)}</a>` : esc(title);
+    return `
+<table cellpadding="0" cellspacing="0" width="100%" style="border-collapse:separate;margin:0 0 16px">
+  <tr><td style="background:#ffffff;border:1px solid #e9edf3;border-radius:14px;overflow:hidden">
+    ${image}
+    <div style="padding:18px 20px">
+      <div style="font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#0091FF;font-weight:700;margin-bottom:7px">${emoji} ${esc(label)}</div>
+      <div style="font-size:18px;font-weight:700;line-height:1.28;color:#0b1220;margin-bottom:7px">${titleHtml}</div>
+      <p style="color:#475569;font-size:14px;line-height:1.55;margin:0 0 15px">${esc(text)}</p>
+      ${btn(btnHref, btnText)}
+    </div>
+  </td></tr>
+</table>`;
+  };
+
+  const parts = [];
+
+  // Coupon — bright hero offer, leads the issue.
+  if (c.coupon) {
+    parts.push(`
+<table cellpadding="0" cellspacing="0" width="100%" style="border-collapse:separate;margin:0 0 20px">
+  <tr><td style="background:linear-gradient(135deg,#0091FF,#0b57c9);border-radius:16px;padding:24px 22px;text-align:center">
+    <div style="display:inline-block;background:rgba(255,255,255,.20);color:#fff;font-size:11px;font-weight:700;letter-spacing:.5px;text-transform:uppercase;padding:5px 13px;border-radius:20px;margin-bottom:12px">🎁 This week only</div>
+    <div style="font-size:24px;font-weight:800;color:#fff;line-height:1.15;margin:0 0 4px">${esc(c.coupon.percent_off)}% off ${esc(c.coupon.feature)}</div>
+    <p style="color:#dcefff;font-size:14px;margin:0 0 16px">for ${esc(c.coupon.duration_in_months)} month${c.coupon.duration_in_months > 1 ? 's' : ''}. Use this code at checkout</p>
+    <div style="display:inline-block;background:#ffffff;color:#0b1220;font-family:'SF Mono',Menlo,Consolas,monospace;font-size:20px;font-weight:800;letter-spacing:2px;padding:12px 24px;border-radius:10px;margin-bottom:18px">${esc(c.coupon.promo_code)}</div>
+    <div><a href="https://${esc(host)}/dashboard" style="display:inline-block;background:#0b1220;color:#fff;text-decoration:none;padding:12px 28px;border-radius:9px;font-weight:700;font-size:14px">Claim offer &rarr;</a></div>
+  </td></tr>
+</table>`);
+  }
+
+  // Did you know — tip image hosted on prod (always loads in mail).
+  if (c.tip) {
+    parts.push(card({
+      img: c.tip.image ? `https://xuda.ai${c.tip.image}` : '',
+      imgAlt: c.tip.title, emoji: '💡', label: 'Did you know?',
+      title: c.tip.title, href: c.tip.url, text: c.tip.text,
+      btnText: 'Try it', btnHref: c.tip.url || `https://${host}/dashboard`,
+    }));
+  }
+
+  // Tip of the week — a compact accent callout (a second, distinct tip).
+  if (c.tip2) {
+    parts.push(`
+<table cellpadding="0" cellspacing="0" width="100%" style="border-collapse:separate;margin:0 0 16px">
+  <tr><td style="background:#eff6ff;border-left:4px solid #0091FF;border-radius:10px;padding:16px 18px">
+    <div style="font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#0b66c2;font-weight:700;margin-bottom:5px">⭐ Tip of the week</div>
+    <div style="font-size:16px;font-weight:700;color:#0b1220;margin:0 0 5px">${esc(c.tip2.title)}</div>
+    <p style="color:#334155;font-size:14px;line-height:1.55;margin:0 0 ${c.tip2.url ? '12px' : '0'}">${esc(c.tip2.text)}</p>
+    ${c.tip2.url ? btn(c.tip2.url, 'See how') : ''}
+  </td></tr>
+</table>`);
+  }
+
+  // News — DARK box; big hero image (SSR /news/<slug>/hero.png) full width on top.
+  if (c.news) {
+    const nurl = `https://${host}/news/${c.news.slug}`;
+    parts.push(`
+<table cellpadding="0" cellspacing="0" width="100%" style="border-collapse:separate;margin:0 0 16px">
+  <tr><td style="background:linear-gradient(160deg,#0b1220,#10213b);border-radius:14px;overflow:hidden">
+    <a href="${esc(nurl)}" style="text-decoration:none"><img src="https://${esc(host)}/news/${encodeURIComponent(c.news.slug)}/hero.png" alt="${esc(c.news.headline)}" width="100%" style="display:block;width:100%;max-height:230px;object-fit:cover"></a>
+    <div style="padding:18px 20px">
+      <div style="font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#66BDFF;font-weight:700;margin-bottom:7px">📰 News</div>
+      <div style="font-size:18px;font-weight:700;line-height:1.28;margin-bottom:7px"><a href="${esc(nurl)}" style="color:#ffffff;text-decoration:none">${esc(c.news.headline)}</a></div>
+      <p style="color:#cbd5e1;font-size:14px;line-height:1.55;margin:0 0 15px">${esc(c.news.deck || c.news.description)}</p>
+      <a href="${esc(nurl)}" style="display:inline-block;background:#0091FF;color:#fff;text-decoration:none;padding:11px 24px;border-radius:9px;font-weight:700;font-size:14px">Read the story &rarr;</a>
+    </div>
+  </td></tr>
+</table>`);
+  }
+
+  // From the blog — no image; clean card.
+  if (c.dev) {
+    parts.push(card({
+      emoji: '📖', label: 'From the blog',
+      title: c.dev.title, href: `https://${host}/blog/${c.dev.slug}`,
+      text: c.dev.description,
+      btnText: 'Read the guide', btnHref: `https://${host}/blog/${c.dev.slug}`,
+    }));
+  }
+
+  // Explore a feature — dark gradient card with an animated GIF demo.
+  if (c.feature) {
+    const gif = c.feature.gif ? _nl_gif_url(c.feature.gif) : '';
+    parts.push(`
+<table cellpadding="0" cellspacing="0" width="100%" style="border-collapse:separate;margin:0 0 16px">
+  <tr><td style="background:linear-gradient(160deg,#0b1220,#10213b);border-radius:14px;padding:22px">
+    <div style="display:inline-block;background:#0091FF;color:#fff;font-size:11px;font-weight:700;letter-spacing:.5px;text-transform:uppercase;padding:4px 11px;border-radius:20px;margin-bottom:14px">⚡ Explore a feature</div>
+    ${gif ? `<a href="https://${esc(host)}/dashboard" style="text-decoration:none"><img src="${esc(gif)}" alt="${esc(c.feature.label)}" width="100%" style="display:block;width:100%;border-radius:10px;border:1px solid #22344f;margin:0 0 14px"></a>` : ''}
+    <div style="font-size:20px;font-weight:700;color:#ffffff;margin:0 0 6px">${esc(c.feature.label)}</div>
+    <p style="color:#cbd5e1;font-size:14px;line-height:1.55;margin:0 0 16px">${esc(c.feature.blurb)}</p>
+    <a href="https://${esc(host)}/dashboard" style="display:inline-block;background:#0091FF;color:#fff;text-decoration:none;padding:11px 24px;border-radius:9px;font-weight:700;font-size:14px">Explore &rarr;</a>
+  </td></tr>
+</table>`);
+  }
+
+  // Wear the brand — DARK box so the dark-background tee blends edge to edge; the
+  // full-bleed image shows the WHOLE tee. City/country-first, rotates per issue.
+  if (fashion) {
+    const teeImg = fashion.img
+      ? `<a href="${esc(fashion.url)}" style="text-decoration:none"><img src="${esc(fashion.img)}" alt="${esc(fashion.title)}" width="100%" style="display:block;width:100%;height:auto"></a>`
+      : '';
+    parts.push(`
+<table cellpadding="0" cellspacing="0" width="100%" style="border-collapse:separate;margin:0 0 16px">
+  <tr><td style="background:linear-gradient(160deg,#160f2b,#0b1220);border-radius:14px;overflow:hidden">
+    ${teeImg}
+    <div style="padding:16px 20px 20px">
+      <div style="font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#66BDFF;font-weight:700;margin-bottom:7px">👕 Wear the brand</div>
+      <div style="font-size:18px;font-weight:700;line-height:1.28;margin-bottom:7px"><a href="${esc(fashion.url)}" style="color:#ffffff;text-decoration:none">${esc(fashion.title)}</a></div>
+      <p style="color:#cbd5e1;font-size:14px;line-height:1.55;margin:0 0 15px">Rep Xuda in your city. Premium tees, shipped worldwide.</p>
+      <a href="${esc(fashion.url)}" style="display:inline-block;background:#0091FF;color:#fff;text-decoration:none;padding:11px 24px;border-radius:9px;font-weight:700;font-size:14px">Shop xuda.fashion &rarr;</a>
+    </div>
+  </td></tr>
+</table>`);
+  }
+
+  // Your local Xuda team — moved to the bottom, each partner on its own bigger
+  // card (avatar left, details + profile link right).
+  const amb = partners && partners.ambassador;
+  const men = partners && partners.mentor;
+  if (amb || men) {
+    const person_card = (p) => {
+      if (!p) return '';
+      const av = _nl_avatar_url(host, p.pic);
+      const avatar = av
+        ? `<img src="${esc(av)}" alt="${esc(p.name)}" width="76" height="76" style="border-radius:50%;object-fit:cover;border:2px solid #e9edf3;display:block">`
+        : `<div style="width:76px;height:76px;border-radius:50%;background:#0091FF;color:#fff;font-size:30px;font-weight:800;line-height:76px;text-align:center">${esc((p.name || '?').slice(0, 1))}</div>`;
+      const role = _nl_titlecase(p.role || 'Partner');
+      const emoji = p.role === 'mentor' ? '🧭' : '📣';
+      const where = p.city ? `${role} in ${esc(_nl_titlecase(p.city))}` : role;
+      return `
+<table cellpadding="0" cellspacing="0" width="100%" style="border-collapse:separate;margin:0 0 12px">
+  <tr><td style="background:#ffffff;border:1px solid #e9edf3;border-radius:14px;padding:18px 20px">
+    <table cellpadding="0" cellspacing="0" width="100%"><tr>
+      <td width="88" style="vertical-align:middle">${avatar}</td>
+      <td style="vertical-align:middle;padding-left:16px">
+        <div style="font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#0091FF;font-weight:700;margin-bottom:3px">${emoji} ${esc(where)}</div>
+        <div style="font-size:19px;font-weight:800;color:#0b1220;margin:0 0 10px">${esc(p.name)}</div>
+        <a href="${esc(p.url)}" style="display:inline-block;background:#eff6ff;color:#0b66c2;text-decoration:none;padding:8px 16px;border-radius:8px;font-weight:700;font-size:13px">View profile &rarr;</a>
+      </td>
+    </tr></table>
+  </td></tr>
+</table>`;
+    };
+    parts.push(`<p style="text-align:center;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#0091FF;font-weight:700;margin:6px 0 4px">🤝 Your local Xuda team</p>
+<p style="text-align:center;color:#94a3b8;font-size:13px;margin:0 0 14px">Your regional ambassador and mentor are here to help you build.</p>`);
+    if (amb) parts.push(person_card(amb));
+    if (men) parts.push(person_card(men));
+  }
+
+  const greet = first_name ? `Hi ${esc(first_name)},` : 'Hi there,';
+  let dateStr = '';
+  try { dateStr = new Date(issue.created_ts || Date.now()).toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric' }); } catch (e) {}
+
+  return `
+<div style="font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif">
+  <div style="text-align:center;margin:0 0 8px">
+    <span style="display:inline-block;background:#eff6ff;color:#0b66c2;font-size:11px;font-weight:700;letter-spacing:.5px;text-transform:uppercase;padding:5px 13px;border-radius:20px">Issue #${esc(issue.issue_number)}${dateStr ? ' &middot; ' + esc(dateStr) : ''}</span>
+  </div>
+  <h1 style="text-align:center;font-size:28px;font-weight:800;color:#0b1220;margin:0 0 8px">Xuda Weekly</h1>
+  <p style="text-align:center;color:#475569;font-size:15px;line-height:1.55;margin:0 auto 24px;max-width:400px"><strong style="color:#0b1220">${greet}</strong> here's what's new at Xuda this week: a quick tip, fresh reads, a feature to try, and this week's deal.</p>
+  ${parts.join('')}
+  <p style="text-align:center;color:#94a3b8;font-size:12px;line-height:1.7;margin:26px 0 0;border-top:1px solid #e9edf3;padding-top:18px">You're receiving this because you opted in to Xuda updates.<br><a href="${esc(unsub_url)}" style="color:#94a3b8;text-decoration:underline">Unsubscribe</a> &nbsp;&middot;&nbsp; <a href="https://${esc(host)}/dashboard" style="color:#94a3b8;text-decoration:underline">Your account</a></p>
+</div>`;
+};
+
+// Demo recipient for previews/samples. Uses a real region (Berlin/DE) so the
+// city/country-targeted sections — fashion + the local ambassador/mentor — render
+// instead of falling back, and a demo first name so personalization is visible.
+const _nl_sample_recipient = (host) => ({
+  host,
+  first_name: 'Alex',
+  cc: 'de',
+  country: 'Germany',
+  city: 'Berlin',
+  fashion: { title: 'XUDA.AI Classic Tee', url: 'https://xuda.fashion', img: '' },
+  partners: { ambassador: null, mentor: null },
+  unsub_url: `https://${host}/newsletter/unsubscribe?u=SAMPLE&t=SAMPLE`,
+});
+
+const _newsletter_send_sample_internal = async (issue, to_email) => {
+  const host = _ops_host();
+  const [fpool, ppool] = await Promise.all([_nl_fashion_pool(), _nl_partner_pool()]);
+  const rcpt = _nl_sample_recipient(host);
+  rcpt.fashion = _nl_fashion_for(fpool, rcpt.country, rcpt.city, issue.issue_number);
+  rcpt.partners = _nl_partners_for(ppool, rcpt.cc, rcpt.country, rcpt.city);
+  const html = _nl_render_email(issue, rcpt);
+  // email_ms (request/response) so we get a real {code} back — email_msa is
+  // fire-and-forget and would report undefined.
+  return email_ms.send_email({ email: to_email, subject: `[SAMPLE] ${issue.subject}`, body: html, display_type: 'info' });
+};
+
+// Build the weekly draft: content + coupon + numbered issue, then sample to ops.
+// req.system=true when called by the cron (skips the superuser gate).
+export const newsletter_generate = async function (req = {}) {
+  try {
+    if (!req.system && !_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+
+    // Two DISTINCT tips: one for "Did you know?", one for "Tip of the week".
+    const _two_tips = async () => {
+      try {
+        const ret = await db_module.find_couch_query('xuda_did_you_know', { selector: { docType: 'did_you_know' }, limit: 300 }, true);
+        const docs = (ret.docs || []).filter((d) => d.published !== false);
+        if (!docs.length) return [null, null];
+        const i = Math.floor(Math.random() * docs.length);
+        let j = i;
+        if (docs.length > 1) { while (j === i) j = Math.floor(Math.random() * docs.length); }
+        return [docs[i], docs.length > 1 ? docs[j] : null];
+      } catch (e) { return [null, null]; }
+    };
+    const [[tip, tip2], dev, news] = await Promise.all([
+      _two_tips(),
+      _nl_one('xuda_dev_articles', 'dev_article'),
+      _nl_one('xuda_news_articles', 'news_article'),
+    ]);
+    const feature = NEWSLETTER_FEATURES[Math.floor(Math.random() * NEWSLETTER_FEATURES.length)];
+
+    let coupon = null;
+    try {
+      const cret = await stripe_ms.newsletter_create_coupon({ percent_off: 10, duration_in_months: 1, feature: feature.label });
+      if (cret && cret.code > 0) coupon = cret.data;
+      else console.error('[newsletter] coupon create failed:', cret && cret.data);
+    } catch (e) {
+      console.error('[newsletter] coupon error:', e.message);
+    }
+
+    const issue_number = await _nl_next_number();
+    const subject = `Xuda Weekly #${issue_number}${coupon ? `: ${coupon.percent_off}% off ${coupon.feature}` : ''}`;
+    const issue = {
+      _id: `nl_issue_${issue_number}`,
+      docType: 'newsletter_issue',
+      issue_number,
+      status: 'draft',
+      subject,
+      created_ts: Date.now(),
+      content: {
+        tip: tip ? { title: tip.title, text: tip.text, url: tip.url, slug: tip.slug, image: tip.image } : null,
+        tip2: tip2 ? { title: tip2.title, text: tip2.text, url: tip2.url, slug: tip2.slug } : null,
+        dev: dev ? { title: dev.title, description: dev.description, slug: dev.slug } : null,
+        news: news ? { headline: news.headline, deck: news.deck, description: news.description, slug: news.slug } : null,
+        feature: { key: feature.key, label: feature.label, blurb: feature.blurb, gif: feature.gif },
+        coupon,
+      },
+      sent: { count: 0, failed: 0 },
+    };
+    const save = await db_module.save_couch_doc(NEWSLETTER_DB, issue);
+    if (save.code < 0) return { code: -1, data: save.data };
+
+    // Sample to ops for review — before anything reaches subscribers.
+    try { await _newsletter_send_sample_internal(issue, 'info@xuda.ai'); } catch (e) { console.error('[newsletter] sample failed:', e.message); }
+    _ops_notify_ops(
+      `Newsletter draft #${issue_number} ready to review`,
+      [['Issue', '#' + issue_number], ['Subject', subject], ['Coupon', coupon ? `${coupon.promo_code} (${coupon.percent_off}% ${coupon.feature})` : '(none)'], ['Review', 'a [SAMPLE] copy was emailed to info@xuda.ai'], ['Publish', 'Admin → Newsletter Manager']],
+      'NL-' + issue_number,
+    );
+    try { logs_msa.add_account_log({ uid: req.uid || 'system', method: 'newsletter_generate', source: 'newsletter', response_status_code: 200, response_data: `draft #${issue_number}` }); } catch (e) {}
+    return { code: 1, data: { issue_number, id: issue._id, subject, coupon } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
+export const newsletter_list_issues = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const ret = await db_module.find_couch_query(NEWSLETTER_DB, { selector: { docType: 'newsletter_issue' }, limit: 500 }, true);
+    const rows = (ret.docs || [])
+      .sort((a, b) => (b.issue_number || 0) - (a.issue_number || 0))
+      .map((d) => ({ id: d._id, issue_number: d.issue_number, status: d.status, subject: d.subject, created_ts: d.created_ts, published_ts: d.published_ts || null, coupon: d.content && d.content.coupon ? d.content.coupon.promo_code : null, sent: d.sent || { count: 0, failed: 0 } }));
+    return { code: 1, data: { rows } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
+export const newsletter_preview = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const id = req.id || `nl_issue_${req.issue_number}`;
+    const ret = await db_module.get_couch_doc(NEWSLETTER_DB, id);
+    if (ret.code < 0 || !ret.data) return { code: -1, data: 'issue not found' };
+    const host = _ops_host();
+    const [fpool, ppool] = await Promise.all([_nl_fashion_pool(), _nl_partner_pool()]);
+    const rcpt = _nl_sample_recipient(host);
+    rcpt.fashion = _nl_fashion_for(fpool, rcpt.country, rcpt.city, ret.data.issue_number);
+    rcpt.partners = _nl_partners_for(ppool, rcpt.cc, rcpt.country, rcpt.city);
+    const html = _nl_render_email(ret.data, rcpt);
+    return { code: 1, data: { issue_number: ret.data.issue_number, subject: ret.data.subject, status: ret.data.status, html } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
+export const newsletter_send_sample = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const id = req.id || `nl_issue_${req.issue_number}`;
+    const ret = await db_module.get_couch_doc(NEWSLETTER_DB, id);
+    if (ret.code < 0 || !ret.data) return { code: -1, data: 'issue not found' };
+    const to = req.email || 'info@xuda.ai';
+    const sr = await _newsletter_send_sample_internal(ret.data, to);
+    return { code: 1, data: { sent_to: to, email_code: sr && sr.code } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
+// The blast runs in the account_module worker AFTER newsletter_publish returns,
+// so the admin HTTP call doesn't block on the whole send.
+const _newsletter_blast = async (issue, by_uid) => {
+  const host = _ops_host();
+  const [pool, ppool] = await Promise.all([_nl_fashion_pool(), _nl_partner_pool()]);
+  let sent = 0, failed = 0, total = 0;
+  try {
+    const rret = await db_module.find_couch_query('xuda_accounts', { selector: { docType: 'account', stat: 3, 'preferences.newsletter_opt_in': true }, limit: 100000 }, true);
+    const recipients = rret.docs || [];
+    total = recipients.length;
+    for (const acct of recipients) {
+      const email = acct.account_info && acct.account_info.email;
+      if (!email) continue;
+      try {
+        const token = await _nl_ensure_unsub_token(acct);
+        const unsub_url = `https://${host}/newsletter/unsubscribe?u=${encodeURIComponent(acct._id)}&t=${encodeURIComponent(token)}`;
+        const ai = acct.account_info || {};
+        const fashion = _nl_fashion_for(pool, ai.country, ai.city, issue.issue_number);
+        const partners = _nl_partners_for(ppool, ai.network_country_code, ai.country, ai.city);
+        const html = _nl_render_email(issue, { host, first_name: ai.first_name, fashion, partners, unsub_url });
+        // email_ms (request/response) returns a real {code} for accurate counts.
+        const er = await email_ms.send_email({ email, subject: issue.subject, body: html, display_type: 'info', headers: { 'List-Unsubscribe': `<${unsub_url}>`, 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click' } });
+        if (er && er.code > 0) sent++; else failed++;
+      } catch (e) {
+        failed++;
+      }
+    }
+  } catch (e) {
+    console.error('[newsletter] blast query failed:', e.message);
+  }
+  try {
+    const fresh = await db_module.get_couch_doc_native(NEWSLETTER_DB, issue._id);
+    fresh.status = 'published';
+    fresh.published_ts = Date.now();
+    fresh.published_by = by_uid;
+    fresh.sent = { count: sent, failed };
+    await db_module.save_couch_doc(NEWSLETTER_DB, fresh);
+  } catch (e) {
+    console.error('[newsletter] finalize failed:', e.message);
+  }
+  _ops_notify_ops(`Newsletter #${issue.issue_number} published`, [['Issue', '#' + issue.issue_number], ['Sent', sent], ['Failed', failed], ['Recipients', total]], 'NL-DONE-' + issue.issue_number);
+};
+
+export const newsletter_publish = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const id = req.id || `nl_issue_${req.issue_number}`;
+    const gret = await db_module.get_couch_doc(NEWSLETTER_DB, id);
+    if (gret.code < 0 || !gret.data) return { code: -1, data: 'issue not found' };
+    const issue = gret.data;
+    if (issue.status === 'published' && !req.force) return { code: -1, data: 'already published (pass force to resend)' };
+    if (issue.status === 'publishing' && !req.force) return { code: -1, data: 'already publishing' };
+
+    // Ops alert BEFORE the blast, then mark publishing and kick the send
+    // detached so this HTTP call returns immediately.
+    _ops_notify_ops(`Publishing newsletter #${issue.issue_number}`, [['Issue', '#' + issue.issue_number], ['Subject', issue.subject], ['By', req.uid]], 'NL-PUB-' + issue.issue_number);
+    issue.status = 'publishing';
+    issue.publish_started_ts = Date.now();
+    await db_module.save_couch_doc(NEWSLETTER_DB, issue);
+    _newsletter_blast(issue, req.uid).catch((e) => console.error('[newsletter] blast crashed:', e.message));
+    return { code: 1, data: { issue_number: issue.issue_number, status: 'publishing' } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};