@dhyasama/totem-models 12.31.0 → 12.35.0

package/lib/Financials.js

@@ -128,6 +128,12 @@ module.exports = function(mongoose, config) {
           group: { type: String, trim: true },
           position: {
             _id: false,
+            text: {
+              _id: false,
+              quote: { type: String, maxlength: 4096 },
+              prefix: { type: String, maxlength: 256 },
+              suffix: { type: String, maxlength: 256 }
+            },
             page: { type: Number },
             bbox: {
               _id: false,
@@ -173,6 +179,12 @@ module.exports = function(mongoose, config) {
             group: { type: String, trim: true },
             position: {
               _id: false,
+              text: {
+                _id: false,
+                quote: { type: String, maxlength: 4096 },
+                prefix: { type: String, maxlength: 256 },
+                suffix: { type: String, maxlength: 256 }
+              },
               page: { type: Number },
               bbox: {
                 _id: false,
@@ -876,10 +888,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({
@@ -889,6 +902,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,
@@ -901,15 +916,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;
             });
 
@@ -942,10 +962,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({
@@ -955,6 +976,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,
@@ -967,7 +990,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;
@@ -1012,10 +1040,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({
@@ -1025,6 +1054,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,
@@ -1037,7 +1068,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;
@@ -1255,7 +1291,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() }
           }
         }
@@ -1339,27 +1377,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.31.0",
+  "version": "12.35.0",
   "author": "Jason Reynolds",
   "license": "UNLICENSED",
   "description": "Models for Totem platform",

package/test/Financials.js

@@ -40,6 +40,29 @@ describe('Financials', function() {
     snapshot.metrics[0].scale.should.equal(1000);
   });
 
+  it('preserves narrative text evidence on current and previous metric sources', function() {
+    var position = { text: {
+      quote: 'Revenue was $1.2m in July.', prefix: 'Intro\n', suffix: '\nThanks'
+    } };
+    var source = { model: 'Message', ref: new mongoose.Types.ObjectId(), position: position };
+    var f = new Financials({
+      organization: orgA,
+      customer: customerA,
+      snapshots: [{
+        uuid: 'narrative-source-evidence', year: 2026, period: 'FY',
+        metrics: [{
+          name: 'Revenue', scenario: 'actual', value: 1200000,
+          sources: [source],
+          previous: { value: 1000000, sources: [source] }
+        }]
+      }]
+    });
+
+    var metric = f.snapshots[0].metrics[0].toObject();
+    metric.sources[0].position.should.deepEqual(position);
+    metric.previous.sources[0].position.should.deepEqual(position);
+  });
+
   before(function(done) {
     databaseHelpers.connect(mongoose, done);
   });
@@ -163,6 +186,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;
+    }
+  });
+});