@xuda.io/account_module 1.2.2302 → 1.2.2304

package/index.mjs

@@ -139,6 +139,15 @@ export const _sync_account_project_name = async function (account_obj, ref_info)
   }
 };
 
+// The profile PICTURE is open to everyone, including accounts that have not
+// confirmed their email; the generated AVATAR is what waits for verification.
+// stat 1 is the unverified state (stat 2 is the password-reset temp state,
+// stat 3 verified), matching the write-gate in http_module — which now lets
+// update_account_info and upload_drive_file_user through at stat 1 precisely so
+// the picture can be saved. verify_account starts any deferred generation the
+// moment the account flips to verified, so nothing is lost by waiting here.
+const can_generate_avatar = (account_obj) => account_obj?.stat !== 1;
+
 export const update_account_info = async function (req, job_id, headers) {
   const { uid } = req;
   const data = req;
@@ -278,7 +287,7 @@ export const update_account_info = async function (req, job_id, headers) {
     return { code: -1310, data: error };
   }
   if (!change) {
-    if (account_obj.account_info?.profile_picture && !account_obj.account_info?.profile_avatar && account_obj.account_info.profile_avatar_stat !== 2) {
+    if (can_generate_avatar(account_obj) && account_obj.account_info?.profile_picture && !account_obj.account_info?.profile_avatar && account_obj.account_info.profile_avatar_stat !== 2) {
       set_account_profile_picture(uid, uid, account_obj.account_info, job_id, headers, account_profile_info);
     }
     return { code: 1300, data: 'no change' };
@@ -317,7 +326,7 @@ export const update_account_info = async function (req, job_id, headers) {
     await _sync_account_project_name(account_obj, _old_name_info);
   }
 
-  if (account_obj.account_info?.profile_picture) {
+  if (can_generate_avatar(account_obj) && account_obj.account_info?.profile_picture) {
     if (!account_obj.account_info?.profile_avatar && account_obj.account_info.profile_avatar_stat !== 2) {
       set_account_profile_picture(uid, uid, account_obj.account_info, job_id, headers, account_profile_info);
     }
@@ -556,6 +565,159 @@ export const get_effective_entitlements = function (account_doc) {
   return { ai_credits, drive_gb };
 };
 
+// ===================================================================
+// Module subscriptions. Membership, support and AI workspace are the three
+// core tiers the billing screen already renders off the account doc; every
+// other suite is sold as its own PLAN_OBJ category billed as a line item on
+// the consolidated subscription. This registry is what the billing screen
+// lists under "Modules", so the customer can see which suites need a
+// subscription and switch one on.
+//
+// scope 'account'  → one plan for the whole account, held in `field`, changed
+//                    with the module's own *_set_plan method.
+// scope 'resource' → priced on the thing itself (a website, a phone number),
+//                    so there is no account-wide plan to show, only a pointer
+//                    to where it is set.
+// scope 'metered'  → no plan ladder at all, usage is metered per call. Listed
+//                    so the customer can see it costs no subscription.
+const _MODULE_SUBSCRIPTIONS = [
+  { key: 'commerce', scope: 'account', field: 'commerce_plan', default_plan: 'commerce_free' },
+  { key: 'shipping', scope: 'account', field: 'shipping_plan', default_plan: 'shipping_free' },
+  { key: 'finance', scope: 'account', field: 'finance_plan', default_plan: 'finance_free' },
+  // The desk screen has its own copy of this ladder (UI-82), because Tickets is
+  // switched on there as well as here. Both call tickets_set_plan, so the plan
+  // is one line item on the consolidated subscription either way.
+  { key: 'tickets', scope: 'account', field: 'tickets_plan', default_plan: 'tickets_free' },
+  // No free tier and no account field: the entitlement IS the subscription item
+  // (or a paid membership, which includes the standard tier at no charge).
+  { key: 'bot_protection', scope: 'account' },
+  { key: 'static_website', scope: 'resource' },
+  { key: 'profile_phone', scope: 'resource' },
+  // Xuda Verify (verify_module) has no PLAN_OBJ category: every check is metered
+  // per call into verify_meter and nothing is charged to the account today.
+  { key: 'trust_center', scope: 'metered' },
+];
+
+// The individual paid things inside a per-resource module, so the billing
+// screen can be the ONE place that shows everything the account pays for.
+// A site or a number on a free tier is not a subscription and is left out.
+const _module_resource_items = async (uid) => {
+  const items = { static_website: [], profile_phone: [] };
+
+  try {
+    const ret = await db_module.find_couch_query(
+      'xuda_master',
+      { selector: { docType: 'app', app_type: 'static_website', app_uId: uid }, limit: 1000 },
+      true,
+    );
+    for (const app of ret?.docs || []) {
+      const tier = app.static_website?.plan_tier || app.deploy_data?.static_website_hosting_plan || 'free';
+      const plan = _conf.PLAN_OBJ?.[`static_website_${tier}`];
+      const price = Number(plan?.price) || 0;
+      if (!price) continue;
+      items.static_website.push({
+        id: app._id,
+        label: app.app_name || app.name || app.deploy_data?.domain || app._id,
+        plan_id: plan.id || `static_website_${tier}`,
+        plan_name: plan.name || tier,
+        price,
+      });
+    }
+  } catch (e) {
+    console.error('[get_module_subscriptions static_website]', e.message);
+  }
+
+  try {
+    const ret = await db_module.find_couch_query(
+      'xuda_master',
+      { selector: { docType: 'voice_number', owner_uid: uid, status: { $ne: 'released' } }, limit: 500 },
+      true,
+    );
+    const profiles = new Map();
+    for (const number of ret?.docs || []) {
+      let profile = profiles.get(number.profile_id);
+      if (profile === undefined) {
+        const pr = await db_module.get_couch_doc('xuda_master', number.profile_id);
+        profile = pr.code > -1 ? pr.data : null;
+        profiles.set(number.profile_id, profile);
+      }
+      const tier = profile?.voice_plan?.tier || 'free';
+      const plan = _conf.PLAN_OBJ?.[`profile_phone_${tier}`];
+      // billing.monthly_total is the number's FULL monthly (rental plus the
+      // tier's service fee), so it wins when set. A number on the free tier
+      // still costs its rental, which is exactly what this row must show.
+      const rental = Number(number.billing?.monthly_total) || 0;
+      const price = rental > 0 ? rental : Number(plan?.price) || 0;
+      if (!price) continue;
+      items.profile_phone.push({
+        id: number._id,
+        label: number.friendly_name || number.phone_number || number._id,
+        plan_id: plan?.id || `profile_phone_${tier}`,
+        plan_name: plan?.name || 'Number',
+        price,
+      });
+    }
+  } catch (e) {
+    console.error('[get_module_subscriptions profile_phone]', e.message);
+  }
+
+  return items;
+};
+
+// Per-module subscription state for the billing screen: what the account is on
+// now, and whether the module is switched on at all.
+export const get_module_subscriptions = async function (req = {}) {
+  try {
+    const uid = req?.uid;
+    if (!uid) return { code: -401, data: 'not authenticated' };
+    const ar = await db_module.get_couch_doc('xuda_accounts', uid);
+    if (ar.code < 0 || !ar.data) return { code: -404, data: 'account not found' };
+    const account = ar.data;
+    const plans = _conf.PLAN_OBJ || {};
+    const is_member = !!(account.membership_plan && account.membership_plan !== 'free');
+    // A category is only offerable once its paid tiers carry a real Stripe
+    // price, otherwise "activate" would set a plan nobody is billed for.
+    const billable = (key) =>
+      Object.values(plans).some((p) => p.category === key && Number(p.price) > 0 && p.price_id && !/TODO/.test(p.price_id));
+
+    const resource_items = await _module_resource_items(uid);
+
+    const modules = _MODULE_SUBSCRIPTIONS.map((m) => {
+      const base = { key: m.key, scope: m.scope, billable: billable(m.key), items: resource_items[m.key] || [] };
+      if (m.key === 'bot_protection') {
+        const has_item = !!account.stripe_subscription_items?.bot_protection;
+        return { ...base, active: has_item || is_member, included: is_member && !has_item, plan_id: '', plan_name: '', price: 0 };
+      }
+      if (m.scope === 'resource' || m.scope === 'metered') {
+        const price = base.items.reduce((sum, i) => sum + Number(i.price || 0), 0);
+        return {
+          ...base,
+          active: m.scope === 'metered' || base.items.length > 0,
+          included: m.scope === 'metered',
+          plan_id: '',
+          plan_name: '',
+          price,
+        };
+      }
+      const plan_id = account[m.field] || m.default_plan;
+      const plan = plans[plan_id] || {};
+      const price = Number(plan.price) || 0;
+      return {
+        ...base,
+        plan_id,
+        plan_name: plan.name || plan_id,
+        price,
+        active: price > 0,
+        included: false,
+        changed_ts: account[`${m.field}_changed`] || null,
+      };
+    });
+    return { code: 1, data: { modules, membership_plan: account.membership_plan || 'free' } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
 // Which website-builder image modes an account may use. SVG and stock are always
 // available; the two gpt-image modes (gen_low = img-1, gen_high = img-2) require a
 // paid membership AND a non-free workspace credit plan. Single source of truth for
@@ -1036,6 +1198,21 @@ export const recompute_abuse_signals = async function (req) {
   }
 };
 
+// xuda.network personas (ambassadors + mentors) are seed accounts on
+// @ambassadors.xuda.network / @mentors.xuda.network, not customers, so every
+// ops list and search hides them. Three independent markers, any one is
+// enough: the signup flag, the `xuda_network_*` source stamped at creation,
+// and the seed mail domains. They agree on all of them today, and belt-and-
+// braces means a persona created through a future surface still stays out.
+const _NETWORK_PERSONA_DOMAINS = ['ambassadors.xuda.network', 'mentors.xuda.network'];
+const _is_network_persona = (a = {}) => {
+  const info = a.account_info || {};
+  if (info.is_xuda_network_ambassador === true) return true;
+  if (String(a.source || '').startsWith('xuda_network_')) return true;
+  const email = String(info.email || a.email || '').toLowerCase();
+  return _NETWORK_PERSONA_DOMAINS.some((d) => email.endsWith(`@${d}`));
+};
+
 // Admin-only: list every account currently flagged. The dashboard's
 // /admin/abuse page reads from here.
 export const get_flagged_accounts = async function (req) {
@@ -1054,7 +1231,7 @@ export const get_flagged_accounts = async function (req) {
       limit: 500,
     });
 
-    const rows = (find_ret?.docs || []).map((a) => ({
+    const rows = (find_ret?.docs || []).filter((a) => !_is_network_persona(a)).map((a) => ({
       uid: a._id,
       email: a.email,
       first_name: a.first_name,
@@ -1501,6 +1678,10 @@ export const get_account_data = async function (req) {
     // one-shot notice at suspension time can be missed or predate this). Best-
     // effort + fire-and-forget; only touches the DB for the rare suspended account.
     if (acc_obj.account_email_bounce_suspended) _ensure_bounce_suspension_banner(acc_obj);
+    // UI-82: same treatment for the billing hold. Called on every load, not
+    // only when the hold is on, because this is also what retires the banner
+    // once the hold is lifted.
+    _ensure_billing_hold_banner(acc_obj);
 
     return ret;
   } catch (err) {
@@ -1973,7 +2154,10 @@ export const ops_list_terminations = async function (req = {}) {
       db_module.find_couch_query('xuda_accounts', { selector: { docType: 'account', account_termination_status: 1 }, limit: 9999 }, true),
     ]);
     const by_id = new Map();
-    for (const a of [...(susp_ret?.docs || []), ...(term_ret?.docs || [])]) by_id.set(a._id, a);
+    for (const a of [...(susp_ret?.docs || []), ...(term_ret?.docs || [])]) {
+      if (_is_network_persona(a)) continue;
+      by_id.set(a._id, a);
+    }
     const rows = [...by_id.values()].map((a) => ({
       account_uid: a._id,
       email: a.account_info?.email,
@@ -2015,6 +2199,8 @@ const _ops_account_summary = (a) => ({
 });
 
 // Find accounts by email / name / uid (substring, case-insensitive).
+// xuda.network personas are dropped AFTER the query, so the fetch limit is
+// raised to keep a full page of real customers when personas match the term.
 export const ops_find_account = async function (req = {}) {
   try {
     if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
@@ -2030,9 +2216,39 @@ export const ops_find_account = async function (req = {}) {
           { _id: { $regex: rx } },
         ],
       },
-      limit: 25,
+      limit: 200,
     }, true);
-    return { code: 1, data: { rows: (ret.docs || []).map(_ops_account_summary) } };
+    const rows = (ret.docs || []).filter((a) => !_is_network_persona(a)).slice(0, 25).map(_ops_account_summary);
+    return { code: 1, data: { rows } };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
+// Every customer account, newest first, paged. Backs the "All customers" tab.
+// Deleted accounts (stat 5) and xuda.network personas are left out, so the
+// total is the real customer base rather than a raw doc count. A few hundred
+// docs, so the page is cut in memory (Mango has no stable sort here without a
+// dedicated index, and skip/limit paging over an unsorted view is not stable).
+export const ops_list_accounts = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const limit = Math.min(Math.max(parseInt(req.limit, 10) || 50, 1), 200);
+    const skip = Math.max(parseInt(req.skip, 10) || 0, 0);
+    const ret = await db_module.find_couch_query('xuda_accounts', {
+      selector: { docType: 'account' },
+      limit: 100000,
+    }, true);
+    const all = (ret.docs || [])
+      .filter((a) => a.stat !== 5 && !_is_network_persona(a))
+      .sort((a, b) => (b.ts || 0) - (a.ts || 0));
+    return {
+      code: 1,
+      data: {
+        rows: all.slice(skip, skip + limit).map(_ops_account_summary),
+        total: all.length,
+        skip,
+        limit,
+      },
+    };
   } catch (err) { return { code: -1, data: err.message }; }
 };
 
@@ -2143,7 +2359,9 @@ export const ops_add_ai_credits = async function (req = {}) {
     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);
+    // An ops grant is a deliberate gift on top of the plan, so it must survive
+    // the period roll rather than evaporating at the next renewal.
+    const cr = await record_ai_credit(req.uid, credits, 'admin_grant', details, account_uid, { kind: CREDIT_KIND.TOPUP });
     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' });
@@ -3182,6 +3400,19 @@ export const verify_account = async function (req) {
     console.warn('[verify_account] confirm_email banner cleanup failed:', e.message);
   }
 
+  // A picture uploaded before verification deliberately did NOT generate an
+  // avatar (see can_generate_avatar). The account is verified as of the save
+  // above, so start the generation that was deferred. Fire-and-forget:
+  // generation is heavy (vision + image ops) and must not hold up the verify
+  // response, and ensure_profile_avatar re-reads the doc and does its own
+  // guarding — picture present, no avatar yet, not already generating — so a
+  // user who never uploaded one is a no-op.
+  try {
+    ensure_profile_avatar({ uid: account_id }).catch((e) => console.warn('[verify_account] deferred avatar start failed:', e.message));
+  } catch (e) {
+    console.warn('[verify_account] deferred avatar start threw:', e.message);
+  }
+
   // is_boarded rides along so the verify route can tell the client whether
   // onboarding is still pending (it is, for a fresh email signup).
   return { code: 1, data: { ...ret_acc.data, is_boarded: !!obj.isBoarded } };
@@ -4660,6 +4891,61 @@ const _notify_bounce_suspended = async (account) => {
 // can be missed or predate this; get_account_data calls this on every load.
 // Idempotent + banner-only: bails if a persistent (app_id '') banner already
 // exists, so it never duplicates the doc or re-sends the SMS.
+// The billing-hold band, as a notification instead of a hardcoded strip in the
+// dashboard shell (UI-82). Driven by account state on every load rather than
+// hooked onto the four places that flip the flag (ops apply, ops release, and
+// both Stripe webhook paths), because a state check cannot drift out of sync
+// with the flag the way four call sites can. Raises the banner while the hold
+// is on, retires it when the hold lifts.
+const _ensure_billing_hold_banner = async (account) => {
+  try {
+    const uid = account._id;
+    const on = account.account_billing_hold_status === 1;
+    const ret = await db_module.find_couch_query('xuda_notification', {
+      selector: { docType: 'notification', uid, topic: 'account_billing_hold', delivery_method: 'banner', read: false },
+    });
+    const docs = ret?.docs || [];
+
+    if (!on) {
+      // Hold lifted: retire whatever is on screen. Same read + stat 4 the
+      // bounce banner uses for its duplicates, so the notification centre
+      // treats it as handled rather than leaving a stale warning up.
+      for (const doc of docs) {
+        doc.read = true;
+        doc.stat = 4;
+        doc.stat_ts = Date.now();
+        await db_module.save_couch_doc('xuda_notification', doc).catch(() => {});
+      }
+      return;
+    }
+
+    // Same de-duplication as the bounce banner: find-then-create is not atomic
+    // and the index lags a fresh doc, so concurrent loads can both create one.
+    if (docs.length) {
+      docs.sort((a, b) => (b.date_created_ts || 0) - (a.date_created_ts || 0));
+      for (let i = 1; i < docs.length; i++) {
+        docs[i].read = true;
+        docs[i].stat = 4;
+        docs[i].stat_ts = Date.now();
+        await db_module.save_couch_doc('xuda_notification', docs[i]).catch(() => {});
+      }
+      return;
+    }
+
+    const host = _conf.is_debug ? process.env.XUDA_HOSTNAME || _conf.domain : _conf.domain;
+    await notification_msa.submit_notification({
+      type: 'account',
+      app_id: null,
+      to_app_id: '',
+      uid_arr: [uid],
+      topic: 'account_billing_hold',
+      params: { action_label: 'Review billing', action_href: `https://${host}/dashboard/settings/billing` },
+    });
+  } catch (e) {
+    console.error('ensure billing hold banner failed:', e.message);
+  }
+};
+
 const _ensure_bounce_suspension_banner = async (account) => {
   try {
     const uid = account._id;
@@ -6587,24 +6873,38 @@ export const save_cache_hit = async function (_id) {
 ///////////////////////////////
 
 export const get_account_ai_usage = async function (req, job_id, headers) {
-  // Default to the LIFETIME window (all-time spend) — the credit model is a
-  // remaining-pool ledger (see _LIFETIME_WINDOW + the Credit Management page).
-  // Callers that want a specific range (the usage chart in WorkspaceUsage.vue)
-  // pass explicit year/month/day. The nav meter + ring call with no window, so
-  // this makes them read lifetime "used" and match the Credit Management page
-  // instead of a current-month slice against a lifetime pool.
+  // Called with NO window at all (the nav meter, the avatar ring, account boot,
+  // the low-credit alert), this reports the CURRENT BILLING PERIOD: usage.total
+  // is the period's spend and credits.total is the period allowance plus the
+  // topup still available. That keeps `credits.total - usage.total` equal to the
+  // real remaining balance, which matters because the dashboard reads those two
+  // numbers directly and computes the difference itself — so the meter stays
+  // correct with no frontend change.
+  //
+  // Callers that pass an explicit range (the WorkspaceUsage chart) still get raw
+  // windowed spend and the full ledger total, unchanged.
   const { uid, year_from = 2000, month_from = 1, day_from = 1, year_to = 2999, month_to = 12, day_to = 31 } = req;
   try {
     const app_id = await get_account_default_project_id(uid);
 
+    // ts_from / ts_to override the Y/M/D window. Billing periods start at an
+    // arbitrary time of day (Isaac's renews 04:00 on the 2nd), and the Y/M/D
+    // form can only express midnight boundaries, so a day-granular window would
+    // count a few hours of the neighbouring period's spend against this one.
+    const has_ts = Number(req?.ts_from) > 0 || Number(req?.ts_to) > 0;
+    const has_ymd = req?.year_from != null || req?.year_to != null || req?.month_from != null || req?.month_to != null || req?.day_from != null || req?.day_to != null;
+    // No window requested at all -> scope to the account's current credit period.
+    const acct_doc = !has_ts && !has_ymd ? await db_module.get_couch_doc_native('xuda_accounts', uid) : null;
+    const period = acct_doc ? _current_credit_period(acct_doc) : null;
+
     // const timestamp_from = new Date(Number(year_from) || year, (Number(month_from) || month) - 1, Number(day_from) || day).getTime();
     // const timestamp_to = new Date(Number(year_to) || year, (Number(month_to) || month) - 1, Number(day_to) || day).getTime();
 
     // BEGINNING OF DAY (00:00:00.000)
-    const timestamp_from = new Date(Number(year_from), Number(month_from) - 1, Number(day_from)).setHours(0, 0, 0, 0);
+    const timestamp_from = period ? period.start : has_ts ? Number(req.ts_from) || 0 : new Date(Number(year_from), Number(month_from) - 1, Number(day_from)).setHours(0, 0, 0, 0);
 
     // END OF DAY (23:59:59.999)
-    const timestamp_to = new Date(Number(year_to), Number(month_to) - 1, Number(day_to)).setHours(23, 59, 59, 999);
+    const timestamp_to = period ? Date.now() : has_ts ? Number(req.ts_to) || Date.now() : new Date(Number(year_to), Number(month_to) - 1, Number(day_to)).setHours(23, 59, 59, 999);
 
     const query = {
       // include_docs: true,
@@ -6648,7 +6948,24 @@ export const get_account_ai_usage = async function (req, job_id, headers) {
       credits_obj[source] += credits;
     }
 
-    let data = { credits: { ...credits_obj, total: total_credits }, usage: { profile, projects: [], total: total_usage }, packs: _conf.ai_credit_packs || [] };
+    // Period-scoped read: the ledger total above counts every active grant, but
+    // topup already spent in EARLIER periods is invisible to this period's usage
+    // figure, so it has to be deducted here. Without that, rolling the period
+    // would hand the customer back topup credits they had already spent.
+    let period_meta = null;
+    if (period) {
+      let period_grant = 0;
+      let topup_total = 0;
+      for (const [src, amount] of Object.entries(credits_obj)) {
+        if (_credit_kind({ source: src }) === CREDIT_KIND.TOPUP) topup_total += amount;
+        else period_grant += amount;
+      }
+      const topup_available = Math.max(0, topup_total - Math.max(0, Number(acct_doc?.credits_topup_consumed) || 0));
+      total_credits = period_grant + topup_available;
+      period_meta = { start_ts: period.start, end_ts: period.end, source: period.source, period_grant, topup_total, topup_available };
+    }
+
+    let data = { credits: { ...credits_obj, total: total_credits }, usage: { profile, projects: [], total: total_usage }, packs: _conf.ai_credit_packs || [], period: period_meta };
 
     if (job_id) {
       data.profile_info = {};
@@ -6750,9 +7067,143 @@ const _usage_total = function (usage_data) {
   return Object.values(by_profile).reduce((a, b) => a + (Number(b) || 0), 0);
 };
 
-// Wide window so "used" reads as all-time spend (the lifetime / remaining-pool model).
+// Wide window so "used" reads as all-time spend. Kept for the few places that
+// genuinely want all-time (ops snapshots, reporting). It is NOT the basis of the
+// balance any more: see get_credit_balance below for why that was broken.
 const _LIFETIME_WINDOW = { year_from: 2000, month_from: 1, day_from: 1, year_to: 2999, month_to: 12, day_to: 31 };
 
+/////////////////////////////////////////////////////////////////////////
+// CREDIT BALANCE
+//
+// The balance used to be computed two different ways, and they disagreed:
+// evaluate_credit_gate did (ledger grants - LIFETIME usage) while the Credit
+// Management page did (plan entitlement - LIFETIME usage). Both were unstable,
+// because grants expire after 30 days while usage was counted forever, so the
+// balance could only ever drift negative. A paying Pro customer was hard-blocked
+// from AI while his own dashboard told him he had 539 credits left.
+//
+// The model now matches how the plans are actually sold:
+//
+//   period pool — the plan's allowance for the CURRENT billing period. Granted
+//                 when the invoice is paid, and it does not roll over. The next
+//                 period starts from the plan's number again.
+//   topup pool  — separately acquired credits (bought packs, ops grants,
+//                 bonuses). Never reset; they persist until spent.
+//
+// Spend comes out of the period pool first and only overflows into topup once
+// the period allowance is exhausted. Overflow consumed in PAST periods is
+// remembered on the account as credits_topup_consumed, because usage is only
+// ever queried for the current period — without that counter, rolling the
+// period would silently hand back topup credits the customer already spent.
+/////////////////////////////////////////////////////////////////////////
+
+// The window the current period pool is measured over. A paid account gets its
+// real Stripe period (stamped by the invoice.paid webhook). Anything else falls
+// back to the calendar month, so a free account's daily drip still resets on a
+// predictable boundary instead of being compared against all-time spend. A
+// stored period that has already elapsed is treated as absent, so a missed or
+// late renewal webhook degrades to the fallback instead of freezing the window.
+const _current_credit_period = function (account_doc) {
+  const now = Date.now();
+  const start = Number(account_doc?.credits_period_start_ts) || 0;
+  const end = Number(account_doc?.credits_period_end_ts) || 0;
+  if (start && end && now >= start && now < end) return { start, end, source: 'invoice' };
+  const d = new Date(now);
+  return { start: Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1), end: Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1), source: 'calendar' };
+};
+
+// Single source of truth for "how many credits does this account have left".
+// Everything that gates, meters or displays credits must go through here.
+export const get_credit_balance = async function (uid, account_doc) {
+  const doc = account_doc || (await db_module.get_couch_doc_native('xuda_accounts', uid));
+  const period = _current_credit_period(doc);
+
+  // Active (stat 3) grants, summed by source, then split into the two pools.
+  // Expired period grants drop out of this view on their own, which is what
+  // makes the period pool reset. Legacy docs carry no credit_kind, so the
+  // classification falls back to the source name (see _credit_kind).
+  const view = await db_module.get_couch_view('xuda_billing', 'ai_credits', { startkey: [uid, ''], endkey: [uid, 'zzz'], reduce: true, group_level: 999 });
+  const by_source = {};
+  let period_grant = 0;
+  let topup_total = 0;
+  for (const row of view?.data?.rows || []) {
+    const source = row.key[1];
+    const credits = Number(row.value) || 0;
+    by_source[source] = (by_source[source] || 0) + credits;
+    if (_credit_kind({ source }) === CREDIT_KIND.TOPUP) topup_total += credits;
+    else period_grant += credits;
+  }
+
+  const usage_ret = await get_account_ai_usage({ uid, ts_from: period.start, ts_to: Date.now() });
+  const used = _usage_total(usage_ret?.data?.usage);
+
+  const topup_consumed = Math.max(0, Number(doc?.credits_topup_consumed) || 0);
+  const topup_available = Math.max(0, topup_total - topup_consumed);
+
+  // An "unlimited" tier (Enterprise T3) resolves to Infinity and must never gate.
+  const unlimited = !Number.isFinite(get_effective_entitlements(doc).ai_credits);
+  const granted = period_grant + topup_available;
+
+  return {
+    period_start_ts: period.start,
+    period_end_ts: period.end,
+    period_source: period.source,
+    period_grant,
+    topup_total,
+    topup_consumed,
+    topup_available,
+    granted,
+    used,
+    remaining: unlimited ? Infinity : Math.round((granted - used) * 100) / 100,
+    unlimited,
+    by_source,
+    usage_profile: usage_ret?.data?.usage?.profile,
+  };
+};
+
+// Close out the period that just ended and open the next one. Called from the
+// invoice.paid webhook right before the new grant lands.
+//
+// The overflow bookkeeping is the important half: any spend beyond the old
+// period's allowance came out of topup, and because the next balance read only
+// looks at the NEW period's usage, that spend would otherwise be forgotten and
+// the customer would get those topup credits back every month.
+export const roll_credit_period = async function (uid, next_start_ts, next_end_ts) {
+  try {
+    const doc = await db_module.get_couch_doc_native('xuda_accounts', uid);
+    if (!doc) return { code: -1, data: 'account not found' };
+
+    const prev_start = Number(doc.credits_period_start_ts) || 0;
+    const prev_end = Number(doc.credits_period_end_ts) || 0;
+    if (prev_start && prev_end && Number(next_start_ts) > prev_start) {
+      const prev = await get_credit_balance(uid, doc);
+      const prev_overflow = Math.max(0, prev.used - prev.period_grant);
+      if (prev_overflow > 0) doc.credits_topup_consumed = (Number(doc.credits_topup_consumed) || 0) + prev_overflow;
+
+      // Retire the old period's grants so they cannot be spent in the new one.
+      // Scoped to period grants whose window has closed; topup is never touched.
+      const stale = await db_module.find_couch_query('xuda_billing', { selector: { docType: 'ai_credit', credited_uid: uid, stat: 3 }, limit: 9999 });
+      for (const c of stale?.docs || []) {
+        if (_credit_kind(c) !== CREDIT_KIND.PERIOD) continue;
+        const ended = Number(c.period_end_ts) || Number(c.date_created_ts) || 0;
+        if (ended && ended > Number(next_start_ts)) continue; // belongs to the period we are opening
+        c.stat = 5;
+        c.stat_ts = Date.now();
+        c.stat_reason = 'period closed';
+        await db_module.save_couch_doc('xuda_billing', c);
+      }
+    }
+
+    doc.credits_period_start_ts = Number(next_start_ts) || Date.now();
+    doc.credits_period_end_ts = Number(next_end_ts) || 0;
+    const save = await db_module.save_couch_doc('xuda_accounts', doc);
+    return { code: save.code > 0 ? 1 : -1, data: { period_start_ts: doc.credits_period_start_ts, period_end_ts: doc.credits_period_end_ts, topup_consumed: doc.credits_topup_consumed || 0 } };
+  } catch (err) {
+    console.error('[roll_credit_period]', err?.message || err);
+    return { code: -1, data: err?.message };
+  }
+};
+
 // Per-model / per-source spend is not emitted by the usage view, so re-derive it
 // from the raw ai_usage docs and CALIBRATE to the view's authoritative total, so the
 // numbers stay in the same credit unit (factor = view_total / raw_token_cost_total).
@@ -6764,7 +7215,9 @@ const _get_scoped_usage = async function (owner_uid, need_raw) {
   const cached = _scoped_usage_cache[owner_uid];
   if (cached && now - cached.ts < _SCOPED_USAGE_TTL && (!need_raw || cached.has_raw)) return cached.data;
 
-  const usage_ret = await get_account_ai_usage({ uid: owner_uid, ..._LIFETIME_WINDOW });
+  // No window: per-profile and per-member caps are an allocation of the CURRENT
+  // period's pool, so they have to be measured over the same period the pool is.
+  const usage_ret = await get_account_ai_usage({ uid: owner_uid });
   const { by_profile, by_user } = _fold_usage(usage_ret?.data?.usage?.profile);
   const total = _usage_total(usage_ret?.data?.usage);
 
@@ -6895,10 +7348,15 @@ export const evaluate_credit_gate = async function (req) {
     const account_doc = await db_module.get_couch_doc_native('xuda_accounts', owner);
     const rules = account_doc?.credit_rules;
 
-    // Back-compat: no rules or disabled => legacy single ledger cap, byte-for-byte.
+    // No rules or disabled => the single account-wide pool cap, which is the
+    // default for almost every account. This is what hard-blocks AI, so it MUST
+    // read the same balance the dashboard shows the customer. It used to compute
+    // its own (ledger grants - lifetime usage) while the Credit Management page
+    // computed (plan entitlement - lifetime usage); the two drifted apart and a
+    // paying Pro customer was blocked while his page reported 539 credits left.
     if (!rules || rules.enabled === false) {
-      const usage = await get_account_ai_usage({ uid: owner, ..._LIFETIME_WINDOW });
-      const over = (Number(usage?.data?.credits?.total) || 0) - _usage_total(usage?.data?.usage) < -0.5;
+      const bal = await get_credit_balance(owner, account_doc);
+      const over = bal.remaining < -0.5;
       return { block: over, scope: over ? 'pool' : null, reason: over ? _SCOPE_REASON.ledger : '', hard_breached: over ? [{ scope: 'pool', key: 'ledger' }] : [], soft_breached: [], account_id: owner };
     }
 
@@ -7009,15 +7467,17 @@ export const get_credit_management = async function (req) {
     const plan = account_doc?.membership_plan || 'free';
     const can_edit = _is_team_tier(plan);
     const rules = account_doc?.credit_rules || _default_credit_rules();
-    const ent = get_effective_entitlements(account_doc);
-    const unlimited = !Number.isFinite(ent.ai_credits);
-    const entitlements = { ai_credits: unlimited ? null : ent.ai_credits, unlimited };
+    // Report exactly what the gate enforces. These were two different formulas
+    // and the page cheerfully showed credits to a customer the gate was blocking.
+    const bal = await get_credit_balance(uid, account_doc);
+    const unlimited = bal.unlimited;
+    const entitlements = { ai_credits: unlimited ? null : bal.granted, unlimited };
 
     const su = await _get_scoped_usage(uid, true);
-    const remaining = unlimited ? null : Math.round((ent.ai_credits - su.total) * 100) / 100;
+    const remaining = unlimited ? null : bal.remaining;
     const usage_breakdown = {
-      window: { mode: rules.window || 'lifetime' },
-      pool: { used: Math.round(su.total * 100) / 100, remaining },
+      window: { mode: 'period', period_start_ts: bal.period_start_ts, period_end_ts: bal.period_end_ts, period_grant: bal.period_grant, topup_available: bal.topup_available },
+      pool: { used: Math.round(bal.used * 100) / 100, remaining },
       by_profile: su.by_profile,
       by_user: su.by_user,
       by_model: su.by_model,
@@ -7307,7 +7767,26 @@ export const record_ai_usage = async function (uid, input_tokens, output_tokens,
   }
 };
 
-export const record_ai_credit = async function (uid, credits = 0, source, details, credited_uid) {
+// A credit belongs to exactly one of two pools, and they behave differently:
+//
+//   'period' — the allowance that comes WITH a plan (the monthly membership
+//              grant, and the free tier's daily drip). It is spent inside one
+//              billing period and does NOT roll over: the next period starts
+//              from the plan's number again.
+//   'topup'  — credits the customer separately acquired (bought packs, ops
+//              grants, the boarding bonus, referral bonuses). These never
+//              reset; they sit there until they are used.
+//
+// Legacy docs predate the field, so _credit_kind() infers it from `source`
+// rather than requiring a backfill.
+const CREDIT_KIND = { PERIOD: 'period', TOPUP: 'topup' };
+const _TOPUP_SOURCES = new Set(['purchase', 'admin_grant', 'boarding', 'contact connection']);
+const _credit_kind = function (doc) {
+  if (doc?.credit_kind === CREDIT_KIND.TOPUP || doc?.credit_kind === CREDIT_KIND.PERIOD) return doc.credit_kind;
+  return _TOPUP_SOURCES.has(doc?.source) ? CREDIT_KIND.TOPUP : CREDIT_KIND.PERIOD;
+};
+
+export const record_ai_credit = async function (uid, credits = 0, source, details, credited_uid, opts = {}) {
   try {
     var dup = await db_module.find_couch_query('xuda_billing', {
       selector: {
@@ -7334,7 +7813,11 @@ export const record_ai_credit = async function (uid, credits = 0, source, detail
       stat: 3,
       credited_uid,
       details,
+      credit_kind: opts.kind === CREDIT_KIND.TOPUP ? CREDIT_KIND.TOPUP : CREDIT_KIND.PERIOD,
     };
+    if (opts.period_start_ts) credit_doc.period_start_ts = opts.period_start_ts;
+    if (opts.period_end_ts) credit_doc.period_end_ts = opts.period_end_ts;
+    if (opts.stripe_invoice_id) credit_doc.stripe_invoice_id = opts.stripe_invoice_id;
     const save_ret = await db_module.save_couch_doc('xuda_billing', credit_doc);
     // console.log(save_ret);
     broadcast_credits(credited_uid); // live meter: this account just gained credits
@@ -7359,7 +7842,9 @@ export const add_ai_credits_to_active_accounts = async function () {
   const _24_hr_ms = 1000 * 60 * 60 * 24;
   const active_accounts = await db_module.find_couch_query('xuda_accounts', { selector: { stat: 3, docType: 'account', last_free_daily_ai_credit_ts: { $lt: Date.now() - _24_hr_ms }, ai_workspace_plan: 'free_ai_workspace' }, limit: 99999 });
   for await (let account_doc of active_accounts.docs) {
-    const ret = await record_ai_credit('system', 1, 'daily credit', 'free daily credit ' + date_str, account_doc._id);
+    // The free tier's drip IS its plan allowance, so it is a period credit: it
+    // resets with the period instead of accumulating forever.
+    const ret = await record_ai_credit('system', 1, 'daily credit', 'free daily credit ' + date_str, account_doc._id, { kind: CREDIT_KIND.PERIOD });
     if (ret.code > -1) {
       account_doc.last_free_daily_ai_credit_ts = Date.now();
       account_doc.last_free_daily_ai_credit_id = ret.data.id;
@@ -7371,11 +7856,23 @@ export const add_ai_credits_to_active_accounts = async function () {
 export const archive_expire_ai_credits = async function () {
   const _24_hr_ms = 1000 * 60 * 60 * 24;
   const _mo_ms = _24_hr_ms * 30;
+  const now = Date.now();
 
-  const active_ai_credits = await db_module.find_couch_query('xuda_billing', { selector: { stat: 3, docType: 'ai_credit', date_created_ts: { $lt: Date.now() - _mo_ms } }, limit: 99999 });
+  const active_ai_credits = await db_module.find_couch_query('xuda_billing', { selector: { stat: 3, docType: 'ai_credit', date_created_ts: { $lt: now - _mo_ms } }, limit: 99999 });
   for await (let ai_credit_doc of active_ai_credits.docs) {
+    // TOPUP credits are the customer's property until they spend them: bought
+    // packs, ops grants, the welcome bonus. This cron used to expire those too,
+    // silently deleting credits people had paid real money for.
+    if (_credit_kind(ai_credit_doc) === CREDIT_KIND.TOPUP) continue;
+
+    // A period grant expires when its PERIOD ends, not 30 days after it was
+    // written. Those differ whenever a month is 31 days long, and the old rule
+    // would have retired the current allowance a day early.
+    const period_end = Number(ai_credit_doc.period_end_ts) || 0;
+    if (period_end && period_end > now) continue;
+
     ai_credit_doc.stat = 5;
-    ai_credit_doc.stat_ts = Date.now();
+    ai_credit_doc.stat_ts = now;
     ai_credit_doc.stat_reason = 'expired';
     const save_ret = await db_module.save_couch_doc('xuda_billing', ai_credit_doc);
   }

package/index_ms.mjs

@@ -57,6 +57,10 @@ export const get_effective_entitlements = async function (...args) {
   return await broker.send_to_queue("get_effective_entitlements", ...args);
 };
 
+export const get_module_subscriptions = async function (...args) {
+  return await broker.send_to_queue("get_module_subscriptions", ...args);
+};
+
 export const _site_build_image_modes = async function (...args) {
   return await broker.send_to_queue("_site_build_image_modes", ...args);
 };
@@ -181,6 +185,10 @@ export const ops_find_account = async function (...args) {
   return await broker.send_to_queue("ops_find_account", ...args);
 };
 
+export const ops_list_accounts = async function (...args) {
+  return await broker.send_to_queue("ops_list_accounts", ...args);
+};
+
 export const ops_account_snapshot = async function (...args) {
   return await broker.send_to_queue("ops_account_snapshot", ...args);
 };
@@ -509,6 +517,14 @@ export const get_account_ai_usage = async function (...args) {
   return await broker.send_to_queue("get_account_ai_usage", ...args);
 };
 
+export const get_credit_balance = async function (...args) {
+  return await broker.send_to_queue("get_credit_balance", ...args);
+};
+
+export const roll_credit_period = async function (...args) {
+  return await broker.send_to_queue("roll_credit_period", ...args);
+};
+
 export const emit_credit_soft_limit = async function (...args) {
   return await broker.send_to_queue("emit_credit_soft_limit", ...args);
 };

package/index_msa.mjs

@@ -57,6 +57,10 @@ export const get_effective_entitlements =  function (...args) {
    broker.send_to_queue_async("get_effective_entitlements", ...args);
 };
 
+export const get_module_subscriptions =  function (...args) {
+   broker.send_to_queue_async("get_module_subscriptions", ...args);
+};
+
 export const _site_build_image_modes =  function (...args) {
    broker.send_to_queue_async("_site_build_image_modes", ...args);
 };
@@ -181,6 +185,10 @@ export const ops_find_account =  function (...args) {
    broker.send_to_queue_async("ops_find_account", ...args);
 };
 
+export const ops_list_accounts =  function (...args) {
+   broker.send_to_queue_async("ops_list_accounts", ...args);
+};
+
 export const ops_account_snapshot =  function (...args) {
    broker.send_to_queue_async("ops_account_snapshot", ...args);
 };
@@ -509,6 +517,14 @@ export const get_account_ai_usage =  function (...args) {
    broker.send_to_queue_async("get_account_ai_usage", ...args);
 };
 
+export const get_credit_balance =  function (...args) {
+   broker.send_to_queue_async("get_credit_balance", ...args);
+};
+
+export const roll_credit_period =  function (...args) {
+   broker.send_to_queue_async("roll_credit_period", ...args);
+};
+
 export const emit_credit_soft_limit =  function (...args) {
    broker.send_to_queue_async("emit_credit_soft_limit", ...args);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xuda.io/account_module",
-  "version": "1.2.2302",
+  "version": "1.2.2304",
   "description": "Xuda Account Server Module",
   "main": "index.mjs",
   "dependencies": {