@dhyasama/totem-models 12.30.0 → 12.33.0

package/lib/Financials.js

@@ -155,7 +155,9 @@ module.exports = function(mongoose, config) {
           _id: false,
           timestamp: { type: Date, required: true, default: Date.now },
           user: { type: String, trim: true, required: true },
-          action: { type: String, enum: ['updated', 'deleted', 'verified'], required: true },
+          // 'confirmed' = a re-extraction found the identical value: freshness signal only,
+          // never a change — it does not touch value or verified state.
+          action: { type: String, enum: ['updated', 'deleted', 'verified', 'confirmed'], required: true },
         }],
         previous: {
           _id: false,
@@ -195,7 +197,7 @@ module.exports = function(mongoose, config) {
             _id: false,
             timestamp: { type: Date },
             user: { type: String, trim: true },
-            action: { type: String, enum: ['updated', 'deleted', 'verified'] },
+            action: { type: String, enum: ['updated', 'deleted', 'verified', 'confirmed'] },
           }]
         }
       }],
@@ -874,10 +876,11 @@ module.exports = function(mongoose, config) {
       var query = this.find({
         'snapshots': {
           $elemMatch: {
+            'form.0': { $exists: true },
             'notifications.company.initial.sendTo': { $gt: [] },
             'notifications.company.initial.sendOn': { $lte: now },
             'notifications.company.initial.sentOn': null,
-            'status': { $nin: ['Pending', 'Completed', 'Archived'] }
+            'status': { $nin: ['Pending', 'Completed', 'Archived', 'Skipped'] }
           }
         }
       }).select({
@@ -887,6 +890,8 @@ module.exports = function(mongoose, config) {
         'snapshots.uuid': 1,
         'snapshots.year': 1,
         'snapshots.period': 1,
+        'snapshots.form._id': 1,
+        'snapshots.status': 1,
         'snapshots.notifications.company.initial.sendTo': 1,
         'snapshots.notifications.company.initial.sendOn': 1,
         'snapshots.notifications.company.initial.sentOn': 1,
@@ -899,15 +904,20 @@ module.exports = function(mongoose, config) {
 
         _.each(financial.snapshots, function(snapshot) {
 
-          var hasSendTo = snapshot.notifications.company.initial.sendTo && snapshot.notifications.company.initial.sendTo.length > 0;
-          var hasSendOnLessThanNow = snapshot.notifications.company.initial.sendOn && snapshot.notifications.company.initial.sendOn < now;
-          var hasSentOn = snapshot.notifications.company.initial.sentOn;
+          if (!snapshot.form || snapshot.form.length === 0) return;
+          if (_.contains(['Pending', 'Completed', 'Archived', 'Skipped'], snapshot.status)) return;
+          var initial = snapshot.notifications && snapshot.notifications.company && snapshot.notifications.company.initial;
+          if (!initial) return;
+
+          var hasSendTo = initial.sendTo && initial.sendTo.length > 0;
+          var hasSendOnLessThanNow = initial.sendOn && initial.sendOn < now;
+          var hasSentOn = initial.sentOn;
 
           var conditions = hasSendTo && hasSendOnLessThanNow && !hasSentOn;
 
           if(conditions) {
 
-            var recipients = snapshot.notifications.company.initial.sendTo.map(function(sendTo) {
+            var recipients = initial.sendTo.map(function(sendTo) {
               return sendTo.email;
             });
 
@@ -940,10 +950,11 @@ module.exports = function(mongoose, config) {
       var query = this.find({
         'snapshots': {
           $elemMatch: {
+            'form.0': { $exists: true },
             'notifications.company.reminders.sendTo': { $gt: [] },
             'notifications.company.reminders.sendOn': { $lte: now },
             'notifications.company.reminders.sentOn': null,
-            'status': { $nin: ['Pending', 'Completed', 'Archived'] }
+            'status': { $nin: ['Pending', 'Completed', 'Archived', 'Skipped'] }
           }
         }
       }).select({
@@ -953,6 +964,8 @@ module.exports = function(mongoose, config) {
         'snapshots.uuid': 1,
         'snapshots.year': 1,
         'snapshots.period': 1,
+        'snapshots.form._id': 1,
+        'snapshots.status': 1,
         'snapshots.notifications.company.reminders.sendTo': 1,
         'snapshots.notifications.company.reminders.sendOn': 1,
         'snapshots.notifications.company.reminders.sentOn': 1,
@@ -965,7 +978,12 @@ module.exports = function(mongoose, config) {
 
         _.each(financial.snapshots, function(snapshot) {
 
-          _.each(snapshot.notifications.company.reminders, function(reminder) {
+          if (!snapshot.form || snapshot.form.length === 0) return;
+          if (_.contains(['Pending', 'Completed', 'Archived', 'Skipped'], snapshot.status)) return;
+          var reminders = snapshot.notifications && snapshot.notifications.company && snapshot.notifications.company.reminders;
+          if (!Array.isArray(reminders)) return;
+
+          _.each(reminders, function(reminder) {
 
             var hasSendTo = reminder.sendTo && reminder.sendTo.length > 0;
             var hasSendOnLessThanNow = reminder.sendOn && reminder.sendOn < now;
@@ -1010,10 +1028,11 @@ module.exports = function(mongoose, config) {
       var query = this.find({
         'snapshots': {
           $elemMatch: {
+            'form.0': { $exists: true },
             'notifications.company.rejections.sendTo': { $gt: [] },
             'notifications.company.rejections.sendOn': { $lte: now },
             'notifications.company.rejections.sentOn': null,
-            'status': { $nin: ['Pending', 'Completed', 'Archived'] }
+            'status': { $nin: ['Pending', 'Completed', 'Archived', 'Skipped'] }
           }
         }
       }).select({
@@ -1023,6 +1042,8 @@ module.exports = function(mongoose, config) {
         'snapshots.uuid': 1,
         'snapshots.year': 1,
         'snapshots.period': 1,
+        'snapshots.form._id': 1,
+        'snapshots.status': 1,
         'snapshots.notifications.company.rejections.sendTo': 1,
         'snapshots.notifications.company.rejections.sendOn': 1,
         'snapshots.notifications.company.rejections.sentOn': 1,
@@ -1035,7 +1056,12 @@ module.exports = function(mongoose, config) {
 
         _.each(financial.snapshots, function(snapshot) {
 
-          _.each(snapshot.notifications.company.rejections, function(rejection) {
+          if (!snapshot.form || snapshot.form.length === 0) return;
+          if (_.contains(['Pending', 'Completed', 'Archived', 'Skipped'], snapshot.status)) return;
+          var rejections = snapshot.notifications && snapshot.notifications.company && snapshot.notifications.company.rejections;
+          if (!Array.isArray(rejections)) return;
+
+          _.each(rejections, function(rejection) {
 
             var hasSendTo = rejection.sendTo && rejection.sendTo.length > 0;
             var hasSendOnLessThanNow = rejection.sendOn && rejection.sendOn < now;
@@ -1253,7 +1279,9 @@ module.exports = function(mongoose, config) {
       const query = this.find({
         'snapshots': {
           $elemMatch: {
-            'status': { $nin: ['Completed', 'Archived', 'Overdue'] },
+            'form.0': { $exists: true },
+            'submittedOn': null,
+            'status': { $nin: ['Pending', 'Completed', 'Archived', 'Overdue', 'Skipped'] },
             'dueOn': { $lte: new Date() }
           }
         }
@@ -1337,27 +1365,40 @@ module.exports = function(mongoose, config) {
       var isApproved = snapshot.approvedOn;
       var isRejected = snapshot.rejectedOn && snapshot.rejection;
       var isArchived = snapshot.archivedOn;
-      var isOverdue = snapshot.dueOn ? moment(new Date()).isAfter(moment(snapshot.dueOn)) : false;
+      var hasForm = snapshot.form && snapshot.form.length > 0;
+      var isOverdue = hasForm && !isSubmitted && snapshot.dueOn
+        ? moment(new Date()).isSameOrAfter(moment(snapshot.dueOn))
+        : false;
 
       var isOpened = false;
       var isDelivered = false;
       var isScheduled = false;
+      var hasDeliveryAttempt = false;
       if(snapshot.notifications && snapshot.notifications.company && snapshot.notifications.company.initial) {
-        isOpened = snapshot.notifications.company.initial.status && snapshot.notifications.company.initial.status === 'Opened' || snapshot.notifications.company.initial.status === 'Clicked';
-        isDelivered = snapshot.notifications.company.initial.sentOn;
-        isScheduled = snapshot.notifications.company.initial.sendOn;
+        var initial = snapshot.notifications.company.initial;
+        isOpened = hasForm && (initial.status === 'Opened' || initial.status === 'Clicked');
+        isDelivered = hasForm && initial.sentOn;
+        isScheduled = hasForm && initial.sendOn;
+        hasDeliveryAttempt = initial.sentOn || initial.postmarkMessageId || initial.status;
       }
-
-      if(snapshot.submittedBy === 'Totem Sheet') snapshot.status = 'Completed'; // sheet snapshots should always be completed
+      var isSkipped = snapshot.status === 'Skipped' && hasForm && isScheduled &&
+        !hasDeliveryAttempt && !isSubmitted;
+
+      // Skipped represents a scheduled request that was unnecessary before
+      // delivery. If someone later explicitly submits that visible form, the
+      // normal submission/approval lifecycle must take precedence.
+      if(isArchived) snapshot.status = 'Archived';
+      else if(isSkipped) snapshot.status = 'Skipped';
+      else if(snapshot.submittedBy === 'Totem Sheet') snapshot.status = 'Completed'; // sheet snapshots should always be completed
       else if(needsApproval && isApproved) snapshot.status = 'Completed';
       else if(!needsApproval && isSubmitted) snapshot.status = 'Completed';
-      else if(isArchived) snapshot.status = 'Archived';
       else if(needsApproval && isSubmitted && !isRejected) snapshot.status = 'Pending';
       else if(needsApproval && isSubmitted && isRejected) snapshot.status = 'Opened';
       else if(isOverdue) snapshot.status = 'Overdue';
       else if(isDelivered && isOpened) snapshot.status = 'Opened';
       else if(isDelivered) snapshot.status = 'Delivered';
       else if(isScheduled) snapshot.status = 'Scheduled'; // when a snapshot is scheduled, but not yet sent (checks every 5 minutes)
+      else snapshot.status = undefined;
 
     });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhyasama/totem-models",
-  "version": "12.30.0",
+  "version": "12.33.0",
   "author": "Jason Reynolds",
   "license": "UNLICENSED",
   "description": "Models for Totem platform",

package/test/Financials.js

@@ -163,6 +163,43 @@ describe('Financials', function() {
 
   });
 
+  it('preserves Skipped and excludes skipped snapshots from sends and overdue work', async function() {
+    var uuid = 'complete-request-skipped';
+    var f = await Financials.create({
+      organization: new mongoose.Types.ObjectId(),
+      customer: new mongoose.Types.ObjectId(),
+      snapshots: [{
+        uuid: uuid,
+        year: 2026,
+        period: 'Q1',
+        status: 'Skipped',
+        dueOn: new Date(Date.now() - 86400000),
+        notifications: {
+          company: {
+            initial: {
+              sendOn: new Date(Date.now() - 3600000),
+              sendTo: [{ email: 'company@example.com' }]
+            },
+            reminders: [{
+              sendOn: new Date(Date.now() - 1800000),
+              sendTo: [{ email: 'company@example.com' }]
+            }]
+          }
+        }
+      }]
+    });
+
+    var reloaded = await Financials.findById(f._id);
+    reloaded.snapshots[0].status.should.equal('Skipped');
+
+    var initial = await Financials.getCompanyInitialToSend();
+    initial.some(function(item) { return item.uuid === uuid; }).should.equal(false);
+    var reminders = await Financials.getCompanyReminderToSend();
+    reminders.some(function(item) { return item.uuid === uuid; }).should.equal(false);
+    var overdue = await Financials.getOverdue();
+    overdue.some(function(item) { return item._id.toString() === f._id.toString(); }).should.equal(false);
+  });
+
   describe.skip('old so skip for now', function() {
 
     it('gets financials for an org', function(done) {

package/test/FinancialsSkippedUnit.js

@@ -0,0 +1,234 @@
+"use strict";
+
+var should = require('should');
+var mongoose = require('mongoose');
+var config = require('./config')['test'];
+
+if (!mongoose.models.Financials) { require('../index')(mongoose, config); }
+var Financials = mongoose.model('Financials');
+
+describe('Financials snapshot status policy (no database)', function() {
+  it('derives every snapshot status from one consistent precedence matrix', function() {
+    var now = Date.now();
+    var snapshots = [
+      {
+        uuid: 'scheduled', year: 2026, period: 'January',
+        notifications: { company: { initial: { sendOn: new Date(now + 60000) } } }
+      },
+      {
+        uuid: 'delivered', year: 2026, period: 'February',
+        notifications: { company: { initial: { sendOn: new Date(now - 60000), sentOn: new Date(now - 60000), status: 'Sent' } } }
+      },
+      {
+        uuid: 'opened', year: 2026, period: 'March',
+        notifications: { company: { initial: { sendOn: new Date(now - 60000), sentOn: new Date(now - 60000), status: 'Opened' } } }
+      },
+      {
+        uuid: 'overdue', year: 2026, period: 'April', dueOn: new Date(now - 60000),
+        notifications: { company: { initial: { sendOn: new Date(now - 120000), sentOn: new Date(now - 120000) } } }
+      },
+      {
+        uuid: 'skipped', year: 2026, period: 'May', status: 'Skipped',
+        form: [{ name: 'Revenue', type: 'metric' }],
+        notifications: { company: { initial: { sendOn: new Date(now + 60000) } } }
+      },
+      {
+        uuid: 'pending', year: 2026, period: 'June', approval: true,
+        submittedOn: new Date(now - 60000), submittedBy: 'company@example.com'
+      },
+      {
+        uuid: 'completed', year: 2026, period: 'July', approval: false,
+        submittedOn: new Date(now - 60000), submittedBy: 'investor@example.com'
+      },
+      {
+        uuid: 'approved', year: 2026, period: 'August', approval: true,
+        submittedOn: new Date(now - 120000), approvedOn: new Date(now - 60000)
+      },
+      {
+        uuid: 'rejected', year: 2026, period: 'September', approval: true,
+        submittedOn: new Date(now - 120000), rejectedOn: new Date(now - 60000), rejection: 'Please revise'
+      },
+      {
+        uuid: 'archived', year: 2026, period: 'October', status: 'Completed',
+        submittedOn: new Date(now - 120000), archivedOn: new Date(now - 60000)
+      },
+      {
+        uuid: 'sheet', year: 2026, period: 'November', submittedBy: 'Totem Sheet'
+      }
+    ];
+    snapshots.forEach(function(snapshot) {
+      if (snapshot.uuid !== 'sheet') snapshot.form = [{ name: 'Revenue', type: 'metric' }];
+    });
+    var financials = Financials.hydrate({
+      _id: new mongoose.Types.ObjectId(),
+      customer: new mongoose.Types.ObjectId(),
+      organization: new mongoose.Types.ObjectId(),
+      snapshots: snapshots
+    });
+    var expected = {
+      scheduled: 'Scheduled',
+      delivered: 'Delivered',
+      opened: 'Opened',
+      overdue: 'Overdue',
+      skipped: 'Skipped',
+      pending: 'Pending',
+      completed: 'Completed',
+      approved: 'Completed',
+      rejected: 'Opened',
+      archived: 'Archived',
+      sheet: 'Completed'
+    };
+    financials.snapshots.forEach(function(snapshot) {
+      snapshot.status.should.equal(expected[snapshot.uuid]);
+    });
+  });
+
+  it('preserves Skipped when a scheduled snapshot is hydrated', function() {
+    var financials = Financials.hydrate({
+      _id: new mongoose.Types.ObjectId(),
+      customer: new mongoose.Types.ObjectId(),
+      organization: new mongoose.Types.ObjectId(),
+      snapshots: [{
+        uuid: 'skipped-hydration',
+        year: 2026,
+        period: 'Q1',
+        status: 'Skipped',
+        form: [{ name: 'Revenue', type: 'metric' }],
+        notifications: { company: { initial: { sendOn: new Date() } } }
+      }]
+    });
+    financials.snapshots[0].status.should.equal('Skipped');
+  });
+
+  it('lets an explicit submission supersede Skipped', function() {
+    var financials = Financials.hydrate({
+      _id: new mongoose.Types.ObjectId(),
+      customer: new mongoose.Types.ObjectId(),
+      organization: new mongoose.Types.ObjectId(),
+      snapshots: [{
+        uuid: 'submitted-after-skip',
+        year: 2026,
+        period: 'Q1',
+        status: 'Skipped',
+        form: [{ name: 'Revenue', type: 'metric' }],
+        submittedOn: new Date(),
+        submittedBy: 'investor@example.com',
+        approval: false,
+        notifications: { company: { initial: { sendOn: new Date() } } }
+      }]
+    });
+    financials.snapshots[0].status.should.equal('Completed');
+  });
+
+  it('gives Archived precedence over completed and skipped states', function() {
+    var financials = Financials.hydrate({
+      _id: new mongoose.Types.ObjectId(),
+      customer: new mongoose.Types.ObjectId(),
+      organization: new mongoose.Types.ObjectId(),
+      snapshots: [{
+        uuid: 'archived-complete',
+        year: 2026,
+        period: 'Q1',
+        status: 'Completed',
+        submittedOn: new Date(),
+        archivedOn: new Date()
+      }, {
+        uuid: 'archived-skipped',
+        year: 2026,
+        period: 'Q2',
+        status: 'Skipped',
+        form: [{ name: 'Revenue', type: 'metric' }],
+        archivedOn: new Date(),
+        notifications: { company: { initial: { sendOn: new Date() } } }
+      }]
+    });
+    financials.snapshots[0].status.should.equal('Archived');
+    financials.snapshots[1].status.should.equal('Archived');
+  });
+
+  it('does not preserve Skipped outside an unsent scheduled form', function() {
+    var financials = Financials.hydrate({
+      _id: new mongoose.Types.ObjectId(),
+      customer: new mongoose.Types.ObjectId(),
+      organization: new mongoose.Types.ObjectId(),
+      snapshots: [{
+        uuid: 'data-only-skipped', year: 2026, period: 'Q1', status: 'Skipped', form: []
+      }, {
+        uuid: 'data-only-scheduled', year: 2026, period: 'Q2', status: 'Scheduled', form: [],
+        notifications: { company: { initial: { sendOn: new Date() } } }
+      }, {
+        uuid: 'sent-skipped', year: 2026, period: 'Q3', status: 'Skipped',
+        form: [{ name: 'Revenue', type: 'metric' }],
+        notifications: { company: { initial: {
+          sendOn: new Date(), sentOn: new Date(), status: 'Opened'
+        } } }
+      }]
+    });
+    should(financials.snapshots[0].status).equal(undefined);
+    should(financials.snapshots[1].status).equal(undefined);
+    financials.snapshots[2].status.should.equal('Opened');
+  });
+
+  it('only considers form-bearing, unsubmitted requests eligible for Overdue', async function() {
+    var capturedFilter;
+    var originalFind = Financials.find;
+    Financials.find = function(filter) {
+      capturedFilter = filter;
+      return Promise.resolve([]);
+    };
+    try {
+      await Financials.getOverdue();
+      var eligibility = capturedFilter.snapshots.$elemMatch;
+      eligibility['form.0'].should.deepEqual({ $exists: true });
+      should(eligibility.submittedOn).eql(null);
+      eligibility.status.$nin.should.containEql('Pending');
+    } finally {
+      Financials.find = originalFind;
+    }
+  });
+
+  it('excludes Skipped from the company initial-send query', async function() {
+    var capturedFilter;
+    var originalFind = Financials.find;
+    Financials.find = function(filter) {
+      capturedFilter = filter;
+      return {
+        select: function() {
+          return { lean: async function() { return []; } };
+        }
+      };
+    };
+    try {
+      var results = await Financials.getCompanyInitialToSend();
+      results.should.deepEqual([]);
+      capturedFilter.snapshots.$elemMatch.status.$nin.should.containEql('Skipped');
+      capturedFilter.snapshots.$elemMatch['form.0'].should.deepEqual({ $exists: true });
+    } finally {
+      Financials.find = originalFind;
+    }
+  });
+
+  it('requires a form in every company notification query', async function() {
+    var capturedFilters = [];
+    var originalFind = Financials.find;
+    Financials.find = function(filter) {
+      capturedFilters.push(filter);
+      return {
+        select: function() {
+          return { lean: async function() { return []; } };
+        }
+      };
+    };
+    try {
+      await Financials.getCompanyInitialToSend();
+      await Financials.getCompanyReminderToSend();
+      await Financials.getCompanyRejectionToSend();
+      capturedFilters.length.should.equal(3);
+      capturedFilters.forEach(function(filter) {
+        filter.snapshots.$elemMatch['form.0'].should.deepEqual({ $exists: true });
+      });
+    } finally {
+      Financials.find = originalFind;
+    }
+  });
+});