feat(econify): Add FX date transparency for SNP database integration (v0.2.7)

- Enhanced FXTable interface with optional dates field for rate timestamps
- explain.fx.asOf field shows when each exchange rate was last updated
- Perfect for SNP database integration - pass through FX update dates
- Fully backward compatible - dates are optional
- Added comprehensive tests and documentation
- All 241 tests passing

Author: algoflows

packages/econify/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to the econify package will be documented in this file.
 
+## [0.2.7] - 2025-01-16
+
+### Enhanced
+
+- **FX Date Transparency**: Added support for FX rate dates in explain metadata
+  - **Date Tracking**: `FXTable.dates` field to specify when each rate was last
+    updated
+  - **Explain Integration**: `explain.fx.asOf` field shows rate timestamp in
+    metadata
+  - **SNP Database Ready**: Perfect for passing through dates from external FX
+    sources
+  - **Full Transparency**: Users can see exactly when each exchange rate was
+    current
+
+### Technical Improvements
+
+- **Enhanced FXTable Interface**: Added optional `dates` field for rate
+  timestamps
+- **Backward Compatible**: Existing code works unchanged - dates are optional
+- **Documentation Enhanced**: Complete examples showing FX date usage patterns
+
 ## [0.2.6] - 2025-01-16
 
 ### Enhanced

packages/econify/README.md

@@ -134,10 +134,11 @@ const result = await processEconomicData(economicData, {
   targetMagnitude: "billions",
   targetTimeScale: "month", // 🆕 Standardize time periods to monthly
 
-  // Provide exchange rates
+  // Provide exchange rates with dates
   fxFallback: {
     base: "USD",
     rates: { EUR: 0.92 },
+    dates: { EUR: "2024-01-15T10:30:00Z" }, // When each rate was last updated
   },
 });
 
@@ -225,7 +226,9 @@ result.data.forEach((item) => {
   // Enhanced FX information
   if (item.explain?.fx) {
     console.log(
-      `  💱 FX: ${item.explain.fx.currency} → ${item.explain.fx.base} (rate: ${item.explain.fx.rate})`,
+      `  💱 FX: ${item.explain.fx.currency} → ${item.explain.fx.base} (rate: ${item.explain.fx.rate})${
+        item.explain.fx.asOf ? ` as of ${item.explain.fx.asOf}` : ""
+      }`,
     );
   }
 });
@@ -897,6 +900,7 @@ interface PipelineOptions {
   fxFallback?: {
     base: string;
     rates: Record<string, number>;
+    dates?: Record<string, string>; // When each rate was last updated
   };
 
   // Exemptions - skip normalization for specific indicators
@@ -1064,6 +1068,45 @@ const value = normalizeValue(100, "EUR Million", {
 });
 ```
 
+### FX Rate Dates & Transparency
+
+Include when each exchange rate was last updated for full transparency:
+
+```ts
+// From your SNP database - include dates for each rate
+const fxFallback = {
+  base: "USD",
+  rates: {
+    XOF: 558.16,
+    EUR: 0.92,
+    GBP: 0.79,
+  },
+  dates: {
+    XOF: "2024-01-15T10:30:00Z", // When XOF rate was last updated
+    EUR: "2024-01-15T09:45:00Z", // When EUR rate was last updated
+    GBP: "2024-01-15T11:15:00Z", // When GBP rate was last updated
+  },
+};
+
+const result = await processEconomicData(data, {
+  targetCurrency: "USD",
+  fxFallback,
+  explain: true,
+});
+
+// The explain metadata will include the date for each FX conversion:
+// {
+//   "fx": {
+//     "currency": "XOF",
+//     "base": "USD",
+//     "rate": 558.16,
+//     "asOf": "2024-01-15T10:30:00Z",  // ← Date included!
+//     "source": "fallback",
+//     "sourceId": "SNP"
+//   }
+// }
+```
+
 ### Data Quality Assessment
 
 Assess and improve data quality:

packages/econify/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@tellimer/econify",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "tasks": {
     "dev": "deno run --watch src/helpers/sample_usage.ts",
     "test": "deno test",

packages/econify/src/normalization/explain.ts

@@ -44,6 +44,8 @@ export function buildExplainMetadata(
         currency: effectiveCurrency,
         base: "USD",
         rate: rate,
+        // Include the date if available from FX table
+        asOf: options.fx.dates?.[effectiveCurrency],
         source: "fallback", // We'll enhance this when we have live FX info
         sourceId: "SNP", // Default for fallback
       };

packages/econify/src/normalization/explain_test.ts

@@ -551,3 +551,45 @@ Deno.test("buildExplainMetadata - component fields with no original time scale",
   assertEquals(explain.timeScale.original, undefined);
   assertEquals(explain.timeScale.normalized, "month");
 });
+
+Deno.test("buildExplainMetadata - FX with date information", () => {
+  const fx: FXTable = {
+    base: "USD",
+    rates: { XOF: 558.16, EUR: 0.85 },
+    dates: {
+      XOF: "2024-01-15T10:30:00Z",
+      EUR: "2024-01-15T10:30:00Z",
+    },
+  };
+
+  const explain = buildExplainMetadata(1000, "XOF billions", 1791.4, {
+    toCurrency: "USD",
+    toMagnitude: "millions",
+    fx,
+  });
+
+  // Should include FX date information
+  assertEquals(explain.fx?.currency, "XOF");
+  assertEquals(explain.fx?.rate, 558.16);
+  assertEquals(explain.fx?.asOf, "2024-01-15T10:30:00Z");
+  assertEquals(explain.fx?.source, "fallback");
+  assertEquals(explain.fx?.sourceId, "SNP");
+});
+
+Deno.test("buildExplainMetadata - FX without date information", () => {
+  const fx: FXTable = {
+    base: "USD",
+    rates: { EUR: 0.85 },
+    // No dates field
+  };
+
+  const explain = buildExplainMetadata(100, "EUR millions", 85, {
+    toCurrency: "USD",
+    fx,
+  });
+
+  // Should not include asOf field when no date available
+  assertEquals(explain.fx?.currency, "EUR");
+  assertEquals(explain.fx?.rate, 0.85);
+  assertEquals(explain.fx?.asOf, undefined);
+});

packages/econify/src/types.ts

@@ -18,6 +18,8 @@ export interface Classification {
 export interface FXTable {
   base: string;
   rates: Record<string, number>;
+  /** Optional dates for each rate - when each rate was last updated */
+  dates?: Record<string, string>;
 }
 
 export type Scale =