@dhyasama/totem-models 12.23.0 → 12.25.0

package/lib/Financials.js

@@ -76,6 +76,9 @@ module.exports = function(mongoose, config) {
 
       uuid: { type: String },
 
+      // DEPRECATED: currency/scale now live per-metric (see metrics[].currency / metrics[].scale).
+      // Retained during the dual-write transition as the fallback default for un-migrated metrics;
+      // remove once all read paths resolve currency/scale per metric.
       currency: { type: String, default: 'USD' },
       scale: { type: Number, enum: [1, 1000, 1000000, 1000000000, 1000000000000], default: 1 },
 
@@ -145,6 +148,11 @@ module.exports = function(mongoose, config) {
           }
         }],
         verified: { type: Boolean, default: false },
+        // Per-metric currency/scale. Intentionally NO defaults: an undefined value means
+        // "not yet migrated" and read paths fall back to the (deprecated) snapshot-level
+        // currency/scale. See scripts/migrate-financials-schema.js for the backfill.
+        currency: { type: String, trim: true },
+        scale: { type: Number, enum: [1, 1000, 1000000, 1000000000, 1000000000000] },
         history: [{
           _id: false,
           timestamp: { type: Date, required: true, default: Date.now },
@@ -156,6 +164,8 @@ module.exports = function(mongoose, config) {
           value: { type: Number },
           breakdown: { type: Schema.Types.Mixed },
           calculation: { type: String, trim: true },
+          currency: { type: String, trim: true },
+          scale: { type: Number, enum: [1, 1000, 1000000, 1000000000, 1000000000000] },
           sources: [{
             _id: false,
             model: { type: String, enum: ['Document', 'Meeting', 'Message', 'Note'] },
@@ -443,6 +453,8 @@ module.exports = function(mongoose, config) {
             value: currentMetric.value != null ? currentMetric.value : null,
             breakdown: currentMetric.breakdown != null ? currentMetric.breakdown : null,
             calculation: currentMetric.calculation || null,
+            currency: currentMetric.currency != null ? currentMetric.currency : null,
+            scale: currentMetric.scale != null ? currentMetric.scale : null,
             sources: currentMetric.sources || [],
             verified: currentMetric.verified != null ? currentMetric.verified : null,
             history: currentMetric.history || []
@@ -459,6 +471,11 @@ module.exports = function(mongoose, config) {
             'snapshots.$.metrics.$[metric].verified': metric.verified
           };
 
+          // Persist per-metric currency/scale only when the caller actually supplies a value, so a
+          // caller that omits them (or passes null) never clobbers an already-migrated metric.
+          if (metric.currency != null) { $set['snapshots.$.metrics.$[metric].currency'] = metric.currency; }
+          if (metric.scale != null) { $set['snapshots.$.metrics.$[metric].scale'] = metric.scale; }
+
           // Save previous state if the metric already exists
           if (previousState) {
             $set['snapshots.$.metrics.$[metric].previous'] = previousState;
@@ -564,7 +581,7 @@ module.exports = function(mongoose, config) {
           const $set = {};
           const $unset = { [prefix + '.previous']: 1 };
 
-          const fields = ['value', 'breakdown', 'calculation', 'sources', 'verified'];
+          const fields = ['value', 'breakdown', 'calculation', 'currency', 'scale', 'sources', 'verified'];
           fields.forEach(field => {
             if (prev[field] != null) {
               $set[prefix + '.' + field] = prev[field];

package/package.json

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

package/scripts/migrate-financials-schema.js

@@ -21,6 +21,10 @@
  * 10. Link metrics to their source financial statement documents (Income Statement,
  *     Balance Sheet, Cash Flow Statement) when available
  * 11. Remove projections array from root level
+ * 12. Backfill per-metric currency/scale from the (now-deprecated) snapshot-level
+ *     currency/scale. Idempotent: metrics that already carry their own are left untouched.
+ *     Defaults to 'USD' / 1 when the snapshot has neither. Part of the snapshot→metric
+ *     currency migration (dual-write transition; snapshot fields retained as fallback).
  *
  * Usage:
  *   node scripts/migrate-financials-schema.js <customerId> [--config <configPath>] [--dry-run]
@@ -81,6 +85,14 @@ if (configPath) {
   dbUri = config.db.uri;
 }
 
+// Valid metric scales (must match the enum in lib/Financials.js). The backfill sanitizes the
+// snapshot's stored scale against this set so a corrupt legacy value can't propagate into a
+// metric and fail a future validated write. Unknown/absent values fall back to 1.
+const VALID_METRIC_SCALES = [1, 1000, 1000000, 1000000000, 1000000000000];
+function sanitizeScale(scale) {
+  return VALID_METRIC_SCALES.includes(scale) ? scale : 1;
+}
+
 console.log('Migration Configuration:');
 console.log('  Customer ID:', CUSTOMER_ID);
 console.log('  Database URI:', dbUri.replace(/\/\/[^:]+:[^@]+@/, '//*****:*****@')); // Mask credentials
@@ -312,12 +324,18 @@ async function migrateFinancials() {
               const source = getSourceForMetric(metric.name);
 
               // Create separate metric entries for each scenario that has a value
+              // Backfill per-metric currency/scale from the (now-deprecated) snapshot-level values
+              const metricCurrency = snapshot.currency || 'USD';
+              const metricScale = sanitizeScale(snapshot.scale);
+
               if ('actual' in metric && metric.actual !== undefined && metric.actual !== null) {
                 const newMetric = {
                   name: metric.name,
                   scenario: 'actual',
                   value: metric.actual,
                   breakdown: metric.breakdown || {},
+                  currency: metricCurrency,
+                  scale: metricScale,
                   verified: true,
                   history: historyArrayForMetrics
                 };
@@ -331,6 +349,8 @@ async function migrateFinancials() {
                   scenario: 'budget',
                   value: metric.budget,
                   breakdown: {},
+                  currency: metricCurrency,
+                  scale: metricScale,
                   verified: true,
                   history: historyArrayForMetrics
                 };
@@ -344,6 +364,8 @@ async function migrateFinancials() {
                   scenario: 'forecast',
                   value: metric.forecast,
                   breakdown: {},
+                  currency: metricCurrency,
+                  scale: metricScale,
                   verified: true,
                   history: historyArrayForMetrics
                 };
@@ -356,7 +378,7 @@ async function migrateFinancials() {
             updates[`snapshots.${index}.metrics`] = newMetrics;
             changes.push(`  - Snapshot ${index}: Converted ${oldMetrics.length} metric(s) to new structure (${newMetrics.length} entries, ${metricsWithSources} with sources)`);
           } else {
-            // Already in new structure, just add verified, history, and source if missing
+            // Already in new structure, just add verified, history, source, and currency/scale if missing
             oldMetrics.forEach((metric, mIndex) => {
               if (!('verified' in metric)) {
                 updates[`snapshots.${index}.metrics.${mIndex}.verified`] = true;
@@ -373,6 +395,17 @@ async function migrateFinancials() {
                   changes.push(`  - Snapshot ${index}: Added sources to metric ${mIndex} (${metric.name})`);
                 }
               }
+              // Backfill per-metric currency/scale from the (now-deprecated) snapshot-level values.
+              // Idempotent: only set when the metric doesn't already carry its own.
+              if (!('currency' in metric)) {
+                updates[`snapshots.${index}.metrics.${mIndex}.currency`] = snapshot.currency || 'USD';
+                changes.push(`  - Snapshot ${index}: Backfilled currency (${snapshot.currency || 'USD'}) to metric ${mIndex} (${metric.name})`);
+              }
+              if (!('scale' in metric)) {
+                const backfillScale = sanitizeScale(snapshot.scale);
+                updates[`snapshots.${index}.metrics.${mIndex}.scale`] = backfillScale;
+                changes.push(`  - Snapshot ${index}: Backfilled scale (${backfillScale}) to metric ${mIndex} (${metric.name})`);
+              }
             });
           }
         }