feat: add Amex translator, docs updates

Make sample config json valid

Author: joshcanhelp

docs/configuration.md

@@ -40,44 +40,45 @@ This tool can be configured using a `.budget-cli.json` file in the root of this
   },
   "moveFilesAfterImport": {
     "AccountTranslatorName1": "/path/to/destination/directory/for/TranslatorName1",
-    "AccountTranslatorName2": "/path/to/destination/directory/for/TranslatorName2",
+    "AccountTranslatorName2": "/path/to/destination/directory/for/TranslatorName2"
   },
   "defaultImportDir": "/path/to/default/import/directory",
   "autoCategorization": [
-	{
-		"descriptions": [
-			"Description 1",
-			"Description 2"
-		],
-		"amount": {
-			"lt": 150, 
-			"lte": 125, 
-			"gte": 75, 
-			"gt": 50, 
-		},
-		"categorization": {
-			"category": "expense",
-			"subCategory": "family",
-			"expenseType": "need",
-			"notes": "Notes here"
-		}
-	}
+    {
+      "descriptions": [
+        "Description 1",
+        "Description 2"
+      ],
+      "amount": {
+        "lt": 150,
+        "lte": 125,
+        "gte": 75,
+        "gt": 50
+      },
+      "categorization": {
+        "category": "expense",
+        "subCategory": "family",
+        "expenseType": "need",
+        "notes": "Notes here"
+      }
+    }
+  ]
 }
 ```
 
-All keys are optional and will provide defaults. 
+All keys are optional and will provide defaults.
 
-- `outputFile`: This can be set to a string to use a single file for all transactions or an object with years as keys and paths as values to set a different file for different years. 
+- `outputFile`: This can be set to a string to use a single file for all transactions or an object with years as keys and paths as values to set a different file for different years.
 - `subCategories`: This can be set to an object with `income` and `expense` as keys. Each of those keys must be set to an array of strings indicating the sub-categories to use for each. When importing transactions, the tool will prompt you to select one.
 - `expenseTypeMapping`: The keys in the object are expense categories and the values are an expense type of "need" or "want" to automatically map expense categories to types.
 - `expenseAllowance`: This can be set to an object with keys indicating a specific year. Each year should be set to an object with expense sub-categories as keys. Each sub-category should be set to an object with the keys `allowance`, indicating how much is allowed per month, and `carryover`, indicating any rollover from the previous year (or `0` if none).
 - `moveFilesAfterImport`: This can be set to an object with keys indicating an account name and values indicating an absolute path to a local directory. If a destination path is set for a specific account, the CSV file will be moved there after successful import.
 - `defaultImportDir`: This can be set to a directory where the import command will look for CSV files. If this is not present then the command will require a directory path in the `input` flag.
 - `autoCategorization`: This can be set to a specifically-shaped object that will be used to auto-categorize transactions.
-    - `descriptions` is an array of one or more strings that are used to match the incoming transaction description in an "or" strategy. 
-    - `amount` is an object that should have at least one of the following keys: 
-      - `gt` (greater than)
-      - `gte` (greater than or equals)
-      - `lt` (less than)
-      - `lte` (less than or equals)
-    - `categorization` is the object that is merged with the transaction data if the conditions are met.
+  - `descriptions` is an array of one or more strings that are used to match the incoming transaction description in an "or" strategy.
+  - `amount` is an object that should have at least one of the following keys:
+    - `gt` (greater than)
+    - `gte` (greater than or equals)
+    - `lt` (less than)
+    - `lte` (less than or equals)
+  - `categorization` is the object that is merged with the transaction data if the conditions are met.

docs/usage.md

@@ -2,20 +2,20 @@
 
 ### Importing Transactions
 
-The first thing you will need for this to do anything for you are some transactions in the database. Transactions are imported from CSV files and translated from their original format to the CSV database. The translators currently available are the [translators](src/translators) folder. See the [Contributing](#Contributing) section for how to add or request new translators. 
+The first thing you will need for this to do anything for you are some transactions in the database. Transactions are imported from CSV files and translated from their original format to the CSV database. The translators currently available are the [translators](../src/translators) folder. See the [Contributing](#Contributing) section for how to add or request new translators. 
 
 Assuming we have a CSV from one of the supported banks, we can run the importer, indicating a specific file or a directory containing one or more CSV files. 
 
 ```bash
-$ ./bin/run.js import --input='/path/to/directory'
+$ ./bin/run.js import "/path/to/directory"
 # ... or
-$ ./bin/run.js import --input='/path/to/directory/transactions.csv'
+$ ./bin/run.js import "/path/to/directory/transactions.csv"
 ```
 
 By default, the script will only import transactions for the current year. To import from a year in the past (or, I guess, the future), add a `year` argument to the command.
 
 ```bash
-$ ./bin/run.js import --input='/path/to/directory' --year='2022'
+$ ./bin/run.js import "/path/to/directory" --year=2022
 ```
 
 If the command checks out, you will be prompted to confirm the import file. This will help you determine if the configuration file is working. Next, it will prompt you for the first CSV it finds from your import path. Answering `n` will move on to the next CSV found, if there is one. 

package-lock.json

@@ -43,4 +43,4 @@
     "dirname": "money",
     "topicSeparator": ":"
   }
-}
+}

package.json

@@ -0,0 +1,42 @@
+import { getFormattedDate } from "../utils/date.js";
+import { generateHash } from "../utils/index.js";
+import { convertStringCurrencyToNumber } from "../utils/money.js";
+import { TransactionImported } from "../utils/transaction.js";
+import { Translator } from "./index.js";
+
+/*
+ * American Express credit card statement parser
+ * https://global.americanexpress.com/activity/statement
+ */
+export const amexTranslator: Translator = {
+  name: "American Express",
+
+  translate: (record: string[]): TransactionImported | null => {
+    // Skip header row
+    // TODO validate that all columns are in the expected places
+    if (record[4] === "Amount") {
+      return null;
+    }
+
+    // TODO allow customizing input format
+    const datePosted = new Date(record[0]);
+
+    // Don't hash Card Member as it's implied by Account #
+    const hashValues = [
+      datePosted.toISOString(),
+      record[1], // Description
+      record[4], // Amount
+      record[3], // Account #
+    ];
+    const transactionId = generateHash(hashValues.join("\n"));
+
+    return {
+      account: "amex",
+      id: transactionId,
+      datePosted: getFormattedDate(datePosted),
+      description: record[1],
+      amount: convertStringCurrencyToNumber(record[4]),
+      comments: `Card member: ${record[2]} (${record[3]})`,
+    };
+  },
+};

src/translators/amex.ts

@@ -3,8 +3,8 @@ import { Translator } from "./index.js";
 import { convertStringCurrencyToNumber } from "../utils/money.js";
 import { getFormattedDate } from "../utils/date.js";
 
-// TODO: Change the const name here and import ir in ../index.ts
-export const boaTranslator: Translator = {
+// TODO: Change the const name here and import it in ../index.ts
+export const exampleTranslator: Translator = {
   // TODO: Change this to something useful
   name: "Name that appears during import",
 

src/translators/example.ts

@@ -1,4 +1,5 @@
 import { TransactionComplete, TransactionImported } from "../utils/transaction.js";
+import { amexTranslator } from "./amex.js";
 import { boaTranslator } from "./boa.js";
 import { chaseTranslator } from "./chase.js";
 import { nordstromsTranslator } from "./nordstroms.js";
@@ -13,6 +14,7 @@ export interface Translator {
 }
 
 const availableTranslators: Translator[] = [
+  amexTranslator,
   boaTranslator,
   chaseTranslator,
   nordstromsTranslator,