@xuda.io/account_module 1.2.2308 → 1.2.2310

package/index.mjs

@@ -542,11 +542,18 @@ export const save_admin_presets = async function (req) {
 };
 
 // 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.
+// add-on's credits + storage stacked on top, PLUS the Drive plan's own storage.
+// The Free membership tier does NOT stack the workspace add-on (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 it for
+// quota checks and any effective-quota display or API.
+//
+// UI-113: the Drive plan (drive_* category) is a storage add-on the customer buys
+// on its own, so unlike the workspace it stacks on EVERY membership tier including
+// free. Withholding space that has its own line on the invoice would be selling
+// nothing. The breakdown comes back with it, because a customer looking at a full
+// bar needs to see which of the three plans to move to get more room.
 export const get_effective_entitlements = function (account_doc) {
   const membership = _conf.PLAN_OBJ?.[account_doc?.membership_plan];
   const mf = membership?.features || {};
@@ -554,15 +561,34 @@ export const get_effective_entitlements = function (account_doc) {
   const numOrInf = (v) => (typeof v === 'string' ? Infinity : Number(v) || 0);
   let ai_credits = numOrInf(mf.ai_credits);
   let drive_gb = numOrInf(mf.drive);
+  const membership_drive_gb = drive_gb;
+  let workspace_drive_gb = 0;
+  let plan_drive_gb = 0;
 
   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;
+      workspace_drive_gb = (Number(ws.size) || 0) / 1073741824;
+      if (Number.isFinite(drive_gb)) drive_gb += workspace_drive_gb;
     }
   }
-  return { ai_credits, drive_gb };
+
+  const drive_plan = _conf.PLAN_OBJ?.[account_doc?.drive_plan];
+  if (drive_plan && drive_plan.category === 'drive') {
+    plan_drive_gb = Number(drive_plan.flags?.extra_gb) || 0;
+    if (Number.isFinite(drive_gb)) drive_gb += plan_drive_gb;
+  }
+
+  return {
+    ai_credits,
+    drive_gb,
+    drive_breakdown: {
+      membership_gb: membership_drive_gb,
+      workspace_gb: workspace_drive_gb,
+      drive_plan_gb: plan_drive_gb,
+    },
+  };
 };
 
 // ===================================================================
@@ -588,19 +614,58 @@ const _MODULE_SUBSCRIPTIONS = [
   // 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' },
+  // UI-104: email is its own product, billed per mailbox tier. Its plan lives on the
+  // account as an OBJECT (`email_plan.tier`), which is why it resolves rather than
+  // reading a field, and `set_email_plan` is what moves it.
+  {
+    key: 'email',
+    scope: 'account',
+    field: 'email_plan',
+    default_plan: 'email_free',
+    resolve: (a) => (a && a.email_plan && a.email_plan.tier ? `email_${a.email_plan.tier}` : ''),
+  },
   // Auto response is the single gate for whether the AI answers, on every channel
   // (chat, the public chat widget, email and the phone). It is account scoped and
   // billed once however many scenarios are written, so it is a plain line item
   // here rather than a per-resource charge like phone or email.
-  { key: 'auto_response', scope: 'account', field: 'auto_response_plan', default_plan: 'auto_response_free' },
+  //
+  // UI-110: "nothing auto-responds before a plan is picked" is the module's own rule
+  // (auto_response_module assert_active), so PICKED is what active means here, Free
+  // included. Judging it on price alone would report an account that deliberately runs
+  // the free tier as switched off, and the menu gate would then hide the screen it uses.
+  {
+    key: 'auto_response',
+    scope: 'account',
+    field: 'auto_response_plan',
+    default_plan: 'auto_response_free',
+    is_active: (a) => !!a.auto_response_plan,
+  },
   // Four-tier ladder since 2026-08-06 (free / external / api / custom rules),
   // chosen on the Bot Protection Manager's Plans tab, which calls
   // bot_protection_set_plan. Free holds no line item at all.
   // No default_plan on purpose: Free is a tier the customer activates, so an
   // account that never chose one reads as not active rather than as Free.
-  { key: 'bot_protection', scope: 'account', field: 'bot_protection_plan', default_plan: '' },
+  { key: 'bot_protection', scope: 'account', field: 'bot_protection_plan', default_plan: '', is_active: (a) => !!a.bot_protection_plan },
   { key: 'static_website', scope: 'resource' },
-  { key: 'profile_phone', scope: 'resource' },
+  // Phone is the one module that is BOTH: an account-wide tier (set_voice_plan, held in
+  // communications.voice_plan) and a per-number charge, because the plan fee rides the
+  // oldest live number's own Stripe subscription rather than the consolidated one. So the
+  // row carries the tier for the switch AND one item per number for the billing card.
+  //
+  // billable is forced true for the same reason: the generic test looks for a Stripe
+  // price_id on a paid tier, and the phone ladder has none by design, its money is on the
+  // number. Left to the generic test the module would read "coming soon" while customers
+  // are being billed for numbers.
+  {
+    key: 'profile_phone',
+    scope: 'resource',
+    billable: true,
+    plan_of: (a) => `profile_phone_${a?.communications?.voice_plan?.tier || 'free'}`,
+    // get_voice_plans' own definition, kept identical on purpose: a number bought before
+    // UI-84 counts as active, so an existing customer is not asked to activate a plan
+    // they already pay for.
+    is_active: (a, items) => !!a?.communications?.voice_plan?.activated_ts || items.length > 0,
+  },
   // UI-96: the hosted resources. Not PLAN_OBJ categories, they are billed per resource
   // from `app_cost` on the app doc, but they are money on the same invoice, so the card
   // that answers "what am I paying for" has to show them.
@@ -614,9 +679,26 @@ const _MODULE_SUBSCRIPTIONS = [
   // so both carry their own `cycle` on each item rather than being assumed monthly.
   { key: 'domain', scope: 'resource' },
   { key: 'ipv4', 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' },
+  // Trust Center (verify_module) is sold on the trust_center_* ladder: the tier
+  // buys a capability ceiling and an included volume of live verifications for
+  // the customer's OWN users, and traffic past the allowance still meters per
+  // check into verify_meter. Account scoped since 2026-08-06; it was 'metered'
+  // while the service had no ladder behind it. Xuda's own verification is never
+  // priced by this plan, deliberately: see the note in verify_module.
+  { key: 'trust_center', scope: 'account', field: 'trust_center_plan', default_plan: 'trust_center_free' },
+  // The Marketplace seller ladder: the tier buys live listings, the listing types the
+  // account may sell, and above all the cut Xuda keeps on each sale (20% down to 5%).
+  // is_active on the FIELD rather than on price, like auto response: Free is a tier a
+  // seller picks, and it is the tier that decides their commission, so an account that
+  // deliberately runs Free is switched on and must not read as off.
+  { key: 'marketplace', scope: 'account', field: 'marketplace_plan', default_plan: 'marketplace_free', is_active: (a) => !!a.marketplace_plan },
+  // UI-113: Drive is sold on its own drive_* ladder, storage only. The tier buys space
+  // STACKED on top of what the membership and the AI workspace plan already include
+  // (get_effective_entitlements), which is why the free tier is 0 extra GB rather than
+  // a number: an account that never touched this ladder keeps exactly the space it has
+  // today and owes nothing new. Judged on price, so Free reads as not active, because
+  // here that is the truth: Free adds nothing and holds no line on the invoice.
+  { key: 'drive', scope: 'account', field: 'drive_plan', default_plan: 'drive_free' },
 ];
 
 // app_type -> the row it belongs under. An app type that is not here is not a
@@ -785,30 +867,42 @@ export const get_module_subscriptions = async function (req = {}) {
     const account = ar.data;
     const plans = _conf.PLAN_OBJ || {};
     // 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));
+    // price, otherwise "activate" would set a plan nobody is billed for. A module
+    // whose money is NOT a plan line item says so itself (phone), because for those
+    // an absent price_id is the design, not a gap.
+    const billable = (m) =>
+      m.billable === true ||
+      Object.values(plans).some((p) => p.category === m.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] || [] };
+      const base = { key: m.key, scope: m.scope, billable: billable(m), items: resource_items[m.key] || [] };
       if (m.scope === 'resource' || m.scope === 'metered') {
         const price = base.items.reduce((sum, i) => sum + Number(i.price || 0), 0);
         // UI-97: a row is only yearly when everything in it is (domains). Anything
         // else stays monthly, so a total is never a sum of two different cycles.
         const cycle = base.items.length && base.items.every((i) => i.cycle === 'yr') ? 'yr' : 'mo';
+        // UI-110: a resource row may still sit under an account-wide tier (phone), and
+        // the switch needs that tier, not the sum of the numbers. Everything without a
+        // `plan_of` keeps reporting no plan, exactly as before.
+        const plan_id = m.plan_of ? m.plan_of(account) : '';
+        const plan = plans[plan_id] || {};
         return {
           ...base,
-          active: m.scope === 'metered' || base.items.length > 0,
+          active: m.is_active ? !!m.is_active(account, base.items) : m.scope === 'metered' || base.items.length > 0,
           included: m.scope === 'metered',
-          plan_id: '',
-          plan_name: '',
+          plan_id,
+          plan_name: plan.name || '',
+          plan_price: Number(plan.price) || 0,
           price,
           cycle,
         };
       }
-      const plan_id = account[m.field] || m.default_plan;
+      // UI-104: most modules keep their plan id directly on the account, but email
+      // keeps `{ tier, activated_ts }`, so a module may bring its own resolver rather
+      // than forcing every field into the same shape.
+      const plan_id = (m.resolve ? m.resolve(account) : account[m.field]) || m.default_plan;
       const plan = plans[plan_id] || {};
       // UI-103: a switch-off is a DOWNGRADE, so Stripe schedules it for the end of the
       // period the customer already paid for and the plan field does not move until the
@@ -824,7 +918,10 @@ export const get_module_subscriptions = async function (req = {}) {
         plan_id,
         plan_name: plan.name || plan_id,
         price,
-        active: price > 0,
+        // UI-110: paying is the default proof that a module is on, but a module that
+        // records the customer CHOOSING a tier says so itself, because a deliberate
+        // free tier is switched on and a price of zero cannot tell the two apart.
+        active: m.is_active ? !!m.is_active(account, base.items) : price > 0,
         included: false,
         pending,
         changed_ts: account[`${m.field}_changed`] || null,
@@ -1783,7 +1880,31 @@ export const get_account_data = async function (req) {
         builds_drive_size: acc_obj.builds_drive_size || 0,
         project_data_size: acc_obj.project_data_size || 0,
         total_drive_size: acc_obj.total_drive_size || 0,
+        // UI-113: the QUOTA travels with the usage now. Every surface that drew a
+        // storage bar (the sidenav popover, UsageBar, the Drive plans screen) was
+        // deriving the ceiling from the ai_workspace plan's `size` alone, which
+        // ignored the membership base and would have ignored the Drive plan too, so
+        // a bar could read full while the account had room. This is the same
+        // get_effective_entitlements the overage metering charges on, in bytes.
+        ...(() => {
+          const ent = get_effective_entitlements(acc_obj);
+          const gb = 1073741824;
+          const b = ent.drive_breakdown || {};
+          return {
+            quota_bytes: Number.isFinite(ent.drive_gb) ? Math.round(ent.drive_gb * gb) : 0,
+            quota_unlimited: !Number.isFinite(ent.drive_gb),
+            quota_from: {
+              membership_bytes: Math.round((b.membership_gb === Infinity ? 0 : b.membership_gb || 0) * gb),
+              workspace_bytes: Math.round((b.workspace_gb || 0) * gb),
+              drive_plan_bytes: Math.round((b.drive_plan_gb || 0) * gb),
+            },
+          };
+        })(),
       },
+      // UI-113: the Drive storage ladder the account sits on, for the plans screen
+      // and the Modules card. Absent on an account that never picked one, which the
+      // registry reads as drive_free.
+      drive_plan: acc_obj.drive_plan || 'drive_free',
 
       stripe_connect_account_id: acc_obj?.stripe_connect_account_obj?.id,
       stripe_connect_account_status: acc_obj?.stripe_connect_account_status,
@@ -4126,6 +4247,7 @@ export const merge_contact = async function (req) {
   }
 
   const primary_contact_save_ret = await save_contact(uid, primary_contact_doc);
+  log_contact_activity(uid, contact_to_merge, 'merged_in', { count: contact_to_delete.length, emails: primary_contact_doc.email, note: 'kept as the primary of a duplicate set' });
 
   for (let contact_id of contact_to_delete) {
     try {
@@ -4134,6 +4256,7 @@ export const merge_contact = async function (req) {
       contact_doc.stat_ts = Date.now();
       contact_doc.stat_reason = 'merge';
       await save_contact(uid, contact_doc);
+      log_contact_activity(uid, contact_id, 'merged_away', { into: contact_to_merge, note: 'folded into the primary duplicate and closed' });
     } catch (error) {}
   }
 
@@ -4632,7 +4755,9 @@ export const update_contact = async function (req) {
       doc.profile_avatar = account_obj.account_info.profile_avatar;
     }
 
-    return await save_contact(uid, doc);
+    const save_ret = await save_contact(uid, doc);
+    log_contact_activity(uid, doc._id, 'updated', { stat, team_req_id, linked_account: contact_uid, note: contact_uid ? 'picture and avatar taken from the linked Xuda account' : undefined });
+    return save_ret;
   }
   return { code: -1, data: 'contact not found' };
 };
@@ -5542,6 +5667,16 @@ export const add_contact = async function (req, job_id, headers) {
 
     /////////////////
 
+    // Minted up front rather than at save time, so every classification step
+    // below can file its verdict under the contact it is deciding about. The
+    // steps run BEFORE the doc exists, which is exactly why their reasoning
+    // used to be unrecoverable.
+    const contact_id = await _common.xuda_get_uuid('contact');
+    const app_id = account_profile_info.app_id;
+    const activity = (event, detail) => log_contact_activity(uid, contact_id, event, detail, app_id);
+
+    await activity('created', { source: source || 'unknown', email: email.toLowerCase(), name: name || '', from_account: !!contact_uid, subject: metadata.subject, profile_id: account_profile_obj?._id });
+
     let is_spam = false;
     // let email_type_info;
     // let account_type_info;
@@ -5558,27 +5693,42 @@ export const add_contact = async function (req, job_id, headers) {
       }
 
       set_account_profile_picture(uid, contact_uid, metadata, job_id, headers, account_profile_info);
+      await activity('linked_account', { contact_uid });
     } else {
       is_spam = await isLikelySpamEmail(email);
+      if (is_spam) await activity('spam_check', { by: 'pattern', is_spam: true, note: 'address matched the local spam pattern list, no AI step ran' });
 
       // contact without use account
       cached_contact = await get_xuda_cache(uid, 'contact', email, 'metadata');
+      if (!_.isEmpty(cached_contact)) {
+        // Every classification below is SKIPPED on a cache hit, which is the single
+        // most confusing thing about the result: the contact inherits a verdict that
+        // was reached for an earlier contact on the same address or domain.
+        await activity('classification_reused', { from_cache: true, key: email.toLowerCase(), account_type: cached_contact.account_type, business_name: cached_contact?.business_info?.business_name, is_spam: cached_contact.is_spam });
+      }
 
       if (_.isEmpty(cached_contact)) {
         if (!is_spam && metadata.subject && !metadata.is_sent && !metadata.is_answered && !metadata.not_junk) {
           // deep search for spam
           is_spam = await ai_ms.is_spam_email(uid, email, metadata.subject, account_profile_info);
+          await activity('spam_check', { by: 'ai', is_spam: !!is_spam, subject: metadata.subject });
         }
         if (!is_spam) {
           const is_business = await ai_ms.is_business_contact(uid, email, name, metadata.subject, metadata.summarized_body, account_profile_info);
           account_type = is_business ? 'business' : 'personal';
+          await activity('classified', { by: 'ai', account_type, inputs: { email: email.toLowerCase(), name: name || '', subject: metadata.subject || '' } });
           if (is_business) {
             business_info = await ai_ms.get_business_info(uid, '', email, account_profile_info, { light: true });
             if (business_info.business_name !== 'Not available') {
+              await activity('business_info', { by: 'ai', depth: 'light', business_name: business_info.business_name, business_domain: business_info.business_domain, business_category: business_info.business_category });
               business_has_person = await ai_ms.is_business_contact_has_person(uid, email, name, metadata.subject, metadata.summarized_body, account_profile_info);
+              await activity('business_has_person', { by: 'ai', has_person: !!business_has_person });
             } else {
               account_type = 'personal';
               business_info = undefined;
+              // The reversal matters more than the original verdict: the card says
+              // personal even though the business call answered yes.
+              await activity('classified', { by: 'ai', account_type, reverted_from: 'business', reason: 'no business could be identified behind the address' });
             }
           }
           if (_.isEmpty(cached_contact) && account_type === 'business' && !business_has_person) {
@@ -5587,6 +5737,9 @@ export const add_contact = async function (req, job_id, headers) {
             } else {
               cached_contact = await get_xuda_cache(uid, 'contact', business_info.business_name, 'metadata');
             }
+            if (!_.isEmpty(cached_contact)) {
+              await activity('classification_reused', { from_cache: true, key: business_info.business_domain || business_info.business_name, account_type: cached_contact.account_type, business_name: cached_contact?.business_info?.business_name });
+            }
           }
         }
       }
@@ -5594,7 +5747,7 @@ export const add_contact = async function (req, job_id, headers) {
 
     const d = Date.now();
     const contact_obj = {
-      _id: await _common.xuda_get_uuid('contact'),
+      _id: contact_id,
       email: email.toLowerCase(),
       name: cached_contact?.name || name,
       stat: stat || 3,
@@ -5621,13 +5774,16 @@ export const add_contact = async function (req, job_id, headers) {
     if (!is_spam) {
       if (account_type === 'personal' || contact_obj?.business_has_person) {
         contact_obj.person_info = await ai_ms.get_person_info(uid, contact_obj.name, contact_obj.email, account_profile_info, metadata?.summarized_body, { light: true });
+        await activity('person_info', { by: 'ai', depth: 'light', full_name: contact_obj.person_info?.full_name, job_title: contact_obj.person_info?.job_title, company: contact_obj.person_info?.company_name });
         if (!contact_obj.name) {
           contact_obj.name = await ai_ms.get_name_from_email_addr(uid, contact_obj.email, account_profile_info);
+          await activity('name_resolved', { by: 'ai', from: 'email address', name: contact_obj.name });
         }
       }
 
       const conversation_obj = await ai_ms.create_openai_conversation();
       contact_obj.contact_reference_conversation_id = conversation_obj.id;
+      await activity('ai_thread_opened', { conversation_id: conversation_obj.id });
     } else {
       if (!contact_obj.name) {
         contact_obj.name = '';
@@ -5637,6 +5793,10 @@ export const add_contact = async function (req, job_id, headers) {
     const save_ret = await save_contact(uid, contact_obj);
     save_xuda_cache(uid, 'contact', contact_obj.email, null, contact_obj);
 
+    // The saved verdict, in one row, so the trail ends on the answer the card
+    // actually shows rather than making the reader replay the steps above.
+    await activity('saved', { account_type: contact_obj.account_type || 'unset', is_spam: !!contact_obj.is_spam, business_name: contact_obj?.business_info?.business_name, name: contact_obj.name || '' });
+
     if (!contact_obj.is_spam && contact_obj.name) {
       set_contact_profile_picture(uid, contact_obj._id, metadata, job_id, headers, account_profile_info, false);
     }
@@ -5700,6 +5860,7 @@ const set_contact_profile_picture = async function (uid, contact_id, metadata, j
         contact_obj.profile_picture_source = file_ret.profile_picture_source;
 
         const contact_save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, contact_obj);
+        log_contact_activity(uid, contact_id, 'picture_found', { by: cache ? 'cache' : 'ai', source: file_ret.profile_picture_source, account_type: contact_obj.account_type || 'unset' });
         // profile_picture = contact_obj.profile_picture;
       }
     }
@@ -5784,10 +5945,14 @@ const set_contact_profile_picture = async function (uid, contact_id, metadata, j
       contact_obj.profile_avatar = contact_obj?.profile_avatar_obj?.file_url;
       contact_obj.avatar_source = file_ret?.data?.avatar_source;
       const contact_save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, contact_obj);
+      log_contact_activity(uid, contact_id, 'avatar_ready', { by: cache ? 'cache' : 'ai', source: contact_obj.avatar_source, account_type: contact_obj.account_type || 'unset' });
     }
     await update_contact_profile_picture_status(uid, contact_id, 3);
   } catch (err) {
     await update_contact_profile_picture_status(uid, contact_id, 1, err.message);
+    // Worth a row of its own: a contact stuck on the shop / silhouette placeholder
+    // looks like a classification result, and this is the line that says otherwise.
+    log_contact_activity(uid, contact_id, 'picture_failed', { error: err?.message });
     delete_xuda_cache(contact_obj);
   }
 };
@@ -6020,6 +6185,7 @@ export const archive_contact = async function (req) {
     contact_doc.stat_reason = 'archived by the user';
 
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'archived', { by: 'user', reason: contact_doc.stat_reason });
 
     return contact_save_ret;
   } catch (err) {
@@ -6042,6 +6208,7 @@ export const delete_contact = async function (req, job_id, headers) {
     contact_doc.stat_reason = 'deleted by the user';
 
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'deleted', { by: 'user', reason: contact_doc.stat_reason, note: 'conversations attached to this contact were deleted with it' });
 
     ai_msa.delete_depended_chats(uid, contact_id);
     return contact_save_ret;
@@ -6067,6 +6234,7 @@ export const unarchive_contact = async function (req, job_id, headers) {
     contact_doc.stat_reason = 'unarchive by the user';
 
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'unarchived', { by: 'user', reason: contact_doc.stat_reason });
 
     if (!contact_doc.is_spam) {
       not_spam_contact(req, job_id, headers);
@@ -6096,6 +6264,7 @@ export const unfriend_contact = async function (req) {
 
     contact_doc.team_req_id = null;
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'unfriended', { by: 'user' });
 
     const req_save_ret = await db_module.save_couch_doc('xuda_team', req_doc);
 
@@ -6115,6 +6284,7 @@ export const pin_contact = async function (req) {
     contact_doc.pinned = true;
 
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'pinned', { by: 'user' });
 
     ws_dashboard_msa.emit_message_to_dashboard({
       service: 'contact_pinned',
@@ -6159,6 +6329,7 @@ export const unpin_contact = async function (req) {
     contact_doc.pinned = false;
 
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'unpinned', { by: 'user' });
 
     ws_dashboard_msa.emit_message_to_dashboard({
       service: 'contact_unpinned',
@@ -6190,22 +6361,30 @@ export const not_spam_contact = async function (req, job_id, headers) {
         stat: 3,
       });
     }
+    const was_spam = !!contact_doc.is_spam;
     contact_doc.is_spam = false;
+    log_contact_activity(uid, contact_id, 'marked_not_spam', { by: 'user', was_spam, note: was_spam ? 'address added to the spam whitelist, classification is being redone' : 'classification is being redone' });
 
     if (!contact_doc.contact_reference_conversation_id) {
       const conversation_obj = await ai_ms.create_openai_conversation();
       contact_doc.contact_reference_conversation_id = conversation_obj.id;
+      await log_contact_activity(uid, contact_id, 'ai_thread_opened', { conversation_id: conversation_obj.id });
     }
 
+    const previous_account_type = contact_doc.account_type;
     const is_business = await ai_ms.is_business_contact(uid, contact_doc.email, contact_doc.name, contact_doc?.metadata?.subject, contact_doc?.metadata?.summarized_body, account_profile_info);
     contact_doc.account_type = is_business ? 'business' : 'personal';
+    await log_contact_activity(uid, contact_id, 'classified', { by: 'ai', trigger: 'not spam', account_type: contact_doc.account_type, previous_account_type: previous_account_type || 'unset' });
     if (is_business) {
       contact_doc.business_info = await ai_ms.get_business_info(uid, '', contact_doc.email, account_profile_info, { light: true });
       if (contact_doc.business_info.business_name !== 'Not available') {
+        await log_contact_activity(uid, contact_id, 'business_info', { by: 'ai', depth: 'light', business_name: contact_doc.business_info.business_name, business_domain: contact_doc.business_info.business_domain, business_category: contact_doc.business_info.business_category });
         contact_doc.business_has_person = await ai_ms.is_business_contact_has_person(uid, contact_doc.email, contact_doc.name, contact_doc?.metadata?.subject, contact_doc?.metadata?.summarized_body, account_profile_info);
+        await log_contact_activity(uid, contact_id, 'business_has_person', { by: 'ai', has_person: !!contact_doc.business_has_person });
       } else {
         contact_doc.account_type = 'personal';
         contact_doc.business_info = undefined;
+        await log_contact_activity(uid, contact_id, 'classified', { by: 'ai', account_type: 'personal', reverted_from: 'business', reason: 'no business could be identified behind the address' });
       }
     }
 
@@ -6241,6 +6420,7 @@ export const not_spam_contact = async function (req, job_id, headers) {
       req.email_id = email._id;
       await email_ms.process_pending_email(req, job_id, headers);
     }
+    if (emails.docs.length) log_contact_activity(uid, contact_id, 'emails_reprocessed', { count: emails.docs.length, trigger: 'not spam', note: 'partially processed emails were re-read in full' });
 
     return contact_save_ret;
   } catch (err) {
@@ -6269,6 +6449,7 @@ export const generate_contact_avatar = async function (req, job_id, headers) {
 
     const contact_save_ret = await save_contact(uid, contact_doc);
     await delete_xuda_cache(contact_doc);
+    log_contact_activity(uid, contact_id, 'avatar_regenerate_requested', { by: 'user', note: 'existing picture and avatar cleared, a new avatar is being generated' });
     set_contact_profile_picture(uid, contact_doc._id, {}, job_id, headers, account_profile_info, true);
 
     return contact_save_ret;
@@ -6286,21 +6467,27 @@ export const set_deep_research_contact = async function (req, job_id, headers) {
   try {
     var contact_doc = await get_contact(uid, contact_id);
     contact_doc.deep_research = true;
+    await log_contact_activity(uid, contact_id, 'deep_research_started', { by: 'user', account_type: contact_doc.account_type || 'unset' });
 
     if (contact_doc.account_type === 'business') {
       contact_doc.business_info = await ai_ms.get_business_info(uid, '', contact_doc.email, account_profile_info);
       if (contact_doc.business_info.business_name !== 'Not available') {
+        await log_contact_activity(uid, contact_id, 'business_info', { by: 'ai', depth: 'deep', business_name: contact_doc.business_info.business_name, business_domain: contact_doc.business_info.business_domain, business_category: contact_doc.business_info.business_category });
         contact_doc.business_has_person = await ai_ms.is_business_contact_has_person(uid, contact_doc.email, contact_doc.name, contact_doc?.metadata?.subject, contact_doc?.metadata?.summarized_body, account_profile_info);
+        await log_contact_activity(uid, contact_id, 'business_has_person', { by: 'ai', has_person: !!contact_doc.business_has_person });
       } else {
         contact_doc.account_type = 'personal';
         contact_doc.business_info = undefined;
+        await log_contact_activity(uid, contact_id, 'classified', { by: 'ai', account_type: 'personal', reverted_from: 'business', reason: 'deep research found no business behind the address' });
       }
     }
 
     if (contact_doc.account_type === 'personal' || contact_doc?.business_has_person) {
       contact_doc.person_info = await ai_ms.get_person_info(uid, contact_doc.name, contact_doc.email, account_profile_info, contact_doc?.metadata?.summarized_body);
+      await log_contact_activity(uid, contact_id, 'person_info', { by: 'ai', depth: 'deep', full_name: contact_doc.person_info?.full_name, job_title: contact_doc.person_info?.job_title, company: contact_doc.person_info?.company_name });
       if (!contact_doc.name) {
         contact_doc.name = await ai_ms.get_name_from_email_addr(uid, contact_doc.email, account_profile_info);
+        await log_contact_activity(uid, contact_id, 'name_resolved', { by: 'ai', from: 'email address', name: contact_doc.name });
       }
     }
 
@@ -6335,6 +6522,8 @@ export const set_deep_research_contact = async function (req, job_id, headers) {
         throw err;
       }
     }
+    if (conversation_items.docs.length) log_contact_activity(uid, contact_id, 'attachments_transcribed', { count: conversation_items.docs.length, trigger: 'deep research' });
+    log_contact_activity(uid, contact_id, 'deep_research_finished', { account_type: contact_doc.account_type || 'unset', business_name: contact_doc?.business_info?.business_name });
 
     return contact_save_ret;
   } catch (err) {
@@ -6354,6 +6543,7 @@ export const unset_deep_research_contact = async function (req, job_id, headers)
 
     const contact_save_ret = await save_contact(uid, contact_doc);
     await delete_xuda_cache(contact_doc);
+    log_contact_activity(uid, contact_id, 'deep_research_turned_off', { by: 'user' });
 
     return contact_save_ret;
   } catch (err) {
@@ -6363,6 +6553,80 @@ export const unset_deep_research_contact = async function (req, job_id, headers)
     };
   }
 };
+
+// The trail for one contact, newest first.
+//
+// Recorded rows are only half the answer: every contact that existed before the
+// trail did has none, and those are most of them. So the contact doc is read back
+// into the same shape first (derived: true). The doc keeps one timestamp per
+// FIELD, not per step, so a derived row is stamped with the closest timestamp it
+// honestly has (date_created for the creation and the classification that ran
+// inside it, profile_avatar_stat_ts for the picture, stat_ts for the archive) and
+// says derived so the UI can mark it as reconstructed rather than observed.
+export const get_contact_activity = async function (req) {
+  const { uid, contact_id } = req;
+  try {
+    if (!contact_id) throw new Error('contact_id is missing');
+    const account_profile_info = await get_active_account_profile_info(uid);
+    const contact_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, contact_id);
+    if (!contact_doc || contact_doc.docType !== 'contact') throw new Error(`contact ${contact_id} not found`);
+    if (contact_doc.uid !== uid && contact_doc?.uid_created !== uid) throw new Error('Operation not allowed');
+
+    const recorded_ret = await db_module.find_app_couch_query(account_profile_info.app_id, {
+      selector: { docType: 'contact_activity', contact_id },
+      limit: 500,
+    });
+    const recorded = (recorded_ret?.docs || []).map((d) => ({ event: d.event, detail: d.detail || {}, ts: d.ts, derived: false }));
+
+    const derived = [];
+    const add = (event, ts, detail) => {
+      if (!ts) return;
+      // A recorded row always wins: it has the real timestamp and the real inputs.
+      if (recorded.some((r) => r.event === event)) return;
+      derived.push({ event, detail, ts, derived: true });
+    };
+
+    const created_ts = contact_doc.date_created || contact_doc.ts;
+    add('created', created_ts, { source: contact_doc.source || 'unknown', email: contact_doc.email, name: contact_doc.name || '', from_account: !!contact_doc.contact_uid, subject: contact_doc?.metadata?.subject });
+    if (contact_doc.is_spam) add('spam_check', created_ts, { is_spam: true });
+    if (contact_doc.account_type) add('classified', created_ts, { account_type: contact_doc.account_type });
+    if (contact_doc?.business_info?.business_name) add('business_info', created_ts, { business_name: contact_doc.business_info.business_name, business_domain: contact_doc.business_info.business_domain, business_category: contact_doc.business_info.business_category });
+    if (contact_doc.business_has_person !== undefined && contact_doc.business_has_person !== null) add('business_has_person', created_ts, { has_person: !!contact_doc.business_has_person });
+    if (contact_doc?.person_info) add('person_info', created_ts, { full_name: contact_doc.person_info.full_name || contact_doc.person_info.person_full_name, job_title: contact_doc.person_info.job_title, company: contact_doc.person_info.company_name });
+    if (contact_doc.contact_reference_conversation_id) add('ai_thread_opened', created_ts, { conversation_id: contact_doc.contact_reference_conversation_id });
+    if (contact_doc.profile_picture) add('picture_found', contact_doc.profile_avatar_stat_ts || created_ts, { source: contact_doc.profile_picture_source });
+    if (contact_doc.profile_avatar) add('avatar_ready', contact_doc.profile_avatar_stat_ts || created_ts, { source: contact_doc.avatar_source });
+    if (contact_doc.profile_avatar_stat === 1 && contact_doc.profile_avatar_error) add('picture_failed', contact_doc.profile_avatar_stat_ts, { error: contact_doc.profile_avatar_error });
+    if (contact_doc.deep_research) add('deep_research_started', contact_doc.stat_ts || created_ts, {});
+    if (contact_doc.pinned) add('pinned', contact_doc.stat_ts || created_ts, {});
+    // stat carries only the LAST transition, which is why an archive/unarchive
+    // history is exactly what the recorded trail adds from here on.
+    if (contact_doc.stat === 5) add('archived', contact_doc.stat_ts, { reason: contact_doc.stat_reason });
+    if (contact_doc.stat === 4) add('deleted', contact_doc.stat_ts, { reason: contact_doc.stat_reason });
+
+    const rows = [...recorded, ...derived].sort((a, b) => (b.ts || 0) - (a.ts || 0));
+
+    return {
+      code: 1,
+      data: {
+        contact_id,
+        // What the card shows today, so the UI can head the trail with the outcome.
+        current: {
+          account_type: contact_doc.account_type || null,
+          is_spam: !!contact_doc.is_spam,
+          stat: contact_doc.stat,
+          source: contact_doc.source || null,
+          deep_research: !!contact_doc.deep_research,
+          business_name: contact_doc?.business_info?.business_name || null,
+          profile_avatar_stat: contact_doc.profile_avatar_stat,
+        },
+        rows,
+      },
+    };
+  } catch (err) {
+    return { code: -25, data: err.message };
+  }
+};
 //////// PROFILES  //////////////
 
 export const get_pending_share_profile_in = async function (uid, _id) {
@@ -6909,6 +7173,48 @@ export const get_contact = async function (uid, contact_id) {
   return contact_ret;
 };
 
+// ---------------------------------------------------------------------------
+// Contact activity trail
+//
+// A contact accumulates a lot of history that was previously only visible as
+// the END STATE on its own doc: it was created from somewhere, several AI steps
+// ran on it and each decided something (spam, business or personal, the business
+// profile, the person profile, the name, the avatar), and it may since have been
+// archived, unarchived, pinned, re-classified or sent to deep research. The doc
+// keeps the last answer of each and nothing about when, in what order, or what
+// the previous answer was, so "why is this contact a business" had no trace to
+// read back.
+//
+// One `contact_activity` doc per event, in the same app db as the contact.
+// Deliberately append-only and deliberately silent: a failure to WRITE the trail
+// must never fail the action being recorded, so every call is wrapped and logged
+// to the console instead of thrown. Callers do not await it for that reason
+// either, except where the next line already awaits something else anyway.
+// ---------------------------------------------------------------------------
+const log_contact_activity = async function (uid, contact_id, event, detail = {}, app_id) {
+  try {
+    if (!uid || !contact_id || !event) return null;
+    const app = app_id || (await get_active_account_profile_info(uid))?.app_id;
+    if (!app) return null;
+
+    return await db_module.save_app_couch_doc_native(app, {
+      _id: await _common.xuda_get_uuid('contact_activity'),
+      docType: 'contact_activity',
+      contact_id,
+      uid,
+      event,
+      // Values the UI prints back verbatim, so keep them short and human. Never
+      // put a full AI response or an email body here: the trail is a summary.
+      detail,
+      ts: Date.now(),
+      stat: 3,
+    });
+  } catch (err) {
+    console.error('[account_module] contact activity not recorded:', event, contact_id, err?.message);
+    return null;
+  }
+};
+
 export const save_contact = async function (uid, contact_doc) {
   const account_profile_info = await get_active_account_profile_info(uid);
   const contact_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, contact_doc);

package/index_ms.mjs

@@ -449,6 +449,10 @@ export const unset_deep_research_contact = async function (...args) {
   return await broker.send_to_queue("unset_deep_research_contact", ...args);
 };
 
+export const get_contact_activity = async function (...args) {
+  return await broker.send_to_queue("get_contact_activity", ...args);
+};
+
 export const get_pending_share_profile_in = async function (...args) {
   return await broker.send_to_queue("get_pending_share_profile_in", ...args);
 };

package/index_msa.mjs

@@ -449,6 +449,10 @@ export const unset_deep_research_contact =  function (...args) {
    broker.send_to_queue_async("unset_deep_research_contact", ...args);
 };
 
+export const get_contact_activity =  function (...args) {
+   broker.send_to_queue_async("get_contact_activity", ...args);
+};
+
 export const get_pending_share_profile_in =  function (...args) {
    broker.send_to_queue_async("get_pending_share_profile_in", ...args);
 };

package/package.json

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