Add earliest import date setting

Author: NikxDa

README.md

@@ -84,6 +84,17 @@ purposePatterns = []
 
 The above configuration would ignore all transactions that have a comment containing the string `[actual-ignore]`.
 
+### Earliest import date
+
+Each budget can specify an earliest import date. This can be useful when starting to use the importer with an already existing budget in order to prevent duplicates from being imported. The importer will ignore any transactions from before the specified date.
+
+```
+[[actualServers.budgets]]
+earliestImportDate = "2024-01-01" # Format is YYYY-MM-DD
+```
+
+Note that the date is a string, not a TOML date.
+
 ## Bugs
 
 If you notice any bugs or issues, please file an issue.

src/utils/Importer.ts

@@ -137,11 +137,38 @@ class Importer {
         isDryRun?: boolean;
     }) {
         const fromDate = from ?? subMonths(new Date(), 1);
+        const earliestImportDate = this.budgetConfig.earliestImportDate
+            ? new Date(this.budgetConfig.earliestImportDate)
+            : null;
+
+        const importDate =
+            earliestImportDate && earliestImportDate > fromDate
+                ? earliestImportDate
+                : fromDate;
+
+        if (earliestImportDate && earliestImportDate > fromDate) {
+            this.logger.warn(
+                `Earliest import date is set to ${format(
+                    earliestImportDate,
+                    DATE_FORMAT
+                )}. Using this date instead of ${format(fromDate, DATE_FORMAT)}.`
+            );
+        }
 
         let monMonTransactions = await getTransactions({
-            from: fromDate,
+            from: importDate,
         });
 
+        if (monMonTransactions.length === 0) {
+            this.logger.info(
+                `No transactions found in MoneyMoney since ${format(
+                    importDate,
+                    DATE_FORMAT
+                )}.`
+            );
+            return;
+        }
+
         if (!this.config.import.importUncheckedTransactions) {
             monMonTransactions = monMonTransactions.filter((t) => t.booked);
         }
@@ -176,7 +203,7 @@ class Importer {
             `Found ${
                 monMonTransactions.length
             } total transactions in MoneyMoney since ${format(
-                fromDate,
+                importDate,
                 DATE_FORMAT
             )}`
         );

src/utils/config.ts

@@ -8,6 +8,7 @@ import { ZodIssueCode, z } from 'zod';
 const budgetSchema = z
     .object({
         syncId: z.string(),
+        earliestImportDate: z.string().optional(),
         e2eEncryption: z.object({
             enabled: z.boolean(),
             password: z.string().optional(),
@@ -23,6 +24,17 @@ const budgetSchema = z
             });
         }
 
+        if (val.earliestImportDate) {
+            const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
+            if (!dateRegex.test(val.earliestImportDate)) {
+                ctx.addIssue({
+                    code: ZodIssueCode.custom,
+                    message:
+                        'Invalid earliest import date format (required format is YYYY-MM-DD)',
+                });
+            }
+        }
+
         return val;
     });
 
@@ -92,11 +104,20 @@ export const getConfig = async (argv: ArgumentsCamelCase) => {
     }
 
     const configContent = await fs.readFile(configFile, 'utf-8');
-    const configData = toml.parse(configContent);
 
     try {
+        const configData = toml.parse(configContent);
         return configSchema.parse(configData);
     } catch (e) {
+        if (e instanceof Error && e.name === 'SyntaxError') {
+            const line = 'line' in e ? e.line : -1;
+            const column = 'column' in e ? e.column : -1;
+
+            throw new Error(
+                `Failed to parse configuration file: ${e.message} (line ${line}, column ${column})`
+            );
+        }
+
         throw new Error(
             `Invalid configuration file format. Run 'validate' to see errors.`
         );

src/utils/shared.ts

@@ -33,6 +33,7 @@ serverPassword = "<password>"
 # Budgets for the server, you can add multiple budgets
 [[actualServers.budgets]]
 syncId = "<syncId>" # Get this value from the Actual advanced settings
+# earliestImportDate = "2021-01-01" # Optional, only import transactions from this date
 
 # E2E encryption for the budget, if enabled
 [actualServers.budgets.e2eEncryption]