initial commit

2026-04-09 20:36:10 -07:00
commit 4681b1a3c8
248 changed files with 97032 additions and 0 deletions
--- a/EXAMPLE_CSVs.md
+++ b/EXAMPLE_CSVs.md
@@ -0,0 +1,300 @@
+# Example Bank CSV Files
+
+## Format 1: Date, Description, Amount
+
+This is the most common format from bank exports.
+
+### Example: `bank_export_standard.csv`
+```csv
+Date,Description,Amount
+2024-01-02,ACH WITHDRAWAL - RENT PAYMENT,5000.00
+2024-01-03,DEPOSIT - ACME CORP PAYMENT,15000.50
+2024-01-04,ELECTRONIC PAYMENT - UTILITIES,850.25
+2024-01-05,"CHECK #1001 - OFFICE SUPPLIES, INC",1250.00
+2024-01-08,BANK FEE,25.00
+2024-01-10,DEPOSIT - CUSTOMER ABC LLC,3500.00
+2024-01-12,ACH WITHDRAWAL - PAYROLL,12500.00
+2024-01-15,WIRE TRANSFER OUT - SUPPLIER PAYMENT,8900.00
+2024-01-16,DEPOSIT - RETURNED CHECK,500.00
+2024-01-18,ONLINE PAYMENT - LOAN PAYMENT,2000.00
+2024-01-20,ACH WITHDRAWAL - TAXES QUARTERLY,5000.00
+2024-01-22,DEPOSIT - CONSULTING SERVICES,4500.00
+2024-01-25,CHECK #1002 - EQUIPMENT LEASE,1800.00
+2024-01-28,BANK INTEREST CREDIT,150.00
+2024-01-30,ACH WITHDRAWAL - INSURANCE,750.00
+```
+
+**How it's parsed:**
+- Debit: Single amount (interpreted as DEBIT/withdrawal)
+- Credit: Single amount (if negative, interpreted as CREDIT/deposit)
+- All amounts are assumed DEBIT by default
+- Date format: YYYY-MM-DD
+
+---
+
+## Format 2: Date, Description, Debit, Credit
+
+This format explicitly shows debits and credits, common in business bank statements.
+
+### Example: `bank_export_debit_credit.csv`
+```csv
+Date,Description,Debit,Credit
+2024-01-02,ACH WITHDRAWAL - RENT PAYMENT,5000.00,
+2024-01-03,DEPOSIT - ACME CORP PAYMENT,,15000.50
+2024-01-04,ELECTRONIC PAYMENT - UTILITIES,850.25,
+2024-01-05,"CHECK #1001 - OFFICE SUPPLIES, INC",1250.00,
+2024-01-08,BANK FEE,25.00,
+2024-01-10,DEPOSIT - CUSTOMER ABC LLC,,3500.00
+2024-01-12,ACH WITHDRAWAL - PAYROLL,12500.00,
+2024-01-15,WIRE TRANSFER OUT - SUPPLIER PAYMENT,8900.00,
+2024-01-16,DEPOSIT - RETURNED CHECK,,500.00
+2024-01-18,ONLINE PAYMENT - LOAN PAYMENT,2000.00,
+2024-01-20,ACH WITHDRAWAL - TAXES QUARTERLY,5000.00,
+2024-01-22,DEPOSIT - CONSULTING SERVICES,,4500.00
+2024-01-25,CHECK #1002 - EQUIPMENT LEASE,1800.00,
+2024-01-28,BANK INTEREST CREDIT,,150.00
+2024-01-30,ACH WITHDRAWAL - INSURANCE,750.00,
+```
+
+**How it's parsed:**
+- If Debit column has value: transaction type is DEBIT, amount is Debit value
+- If Credit column has value: transaction type is CREDIT, amount is Credit value
+- Both columns cannot have values in same row
+- Empty string or 0 in column means no transaction
+
+---
+
+## Format 3: With Quoted Descriptions (Commas in Description)
+
+Handles bank statements where description contains commas.
+
+### Example: `bank_export_quoted.csv`
+```csv
+Date,Description,Amount
+2024-01-05,"CHECK #1001 - OFFICE SUPPLIES, INC, Springfield, IL",1250.00
+2024-01-10,"DEPOSIT - CUSTOMER ABC LLC, Invoice #INV-2024-001, Reference: PO-5555",3500.00
+2024-02-01,"WIRE TRANSFER - VENDOR XYZ, Invoice #INV-12345, Amount $8900, Reference Code ABC123",8900.00
+2024-02-15,"ACH PAYMENT - MULTIPLE INVOICES, Details: INV-001 $500, INV-002 $750, INV-003 $1000",2250.00
+```
+
+**Key Features:**
+- Descriptions with commas are wrapped in quotes: `"Description, with, commas"`
+- Quotes are properly handled by the CSV parser
+- Real-world bank statements often include detailed transaction info
+
+---
+
+## Format 4: Mixed with Escaped Quotes
+
+Handles descriptions that contain both commas AND quotes.
+
+### Example: `bank_export_escaped_quotes.csv`
+```csv
+Date,Description,Amount
+2024-01-20,"VENDOR INVOICE - Widget Corp, Item: ""Ultra Premium Widgets"", Qty: 500",2500.00
+2024-02-10,"CUSTOMER DEPOSIT - ABC Corp, Receipt: ""2024-Feb-Invoice"", Amount: USD 5000",5000.00
+```
+
+**Key Features:**
+- Quotes inside quoted strings are escaped with double-quotes: `"The ""thing"" is..."`
+- Parser handles these correctly
+- Uncommon but can appear in detailed bank statements
+
+---
+
+## API Request Examples
+
+### Parse CSV (Form Data)
+
+```bash
+curl -X POST http://localhost:3000/api/bank-transactions/parse-csv \
+  -F "file=@bank_export_standard.csv"
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "count": 15,
+  "transactions": [
+    {
+      "transactionDate": "2024-01-02",
+      "description": "ACH WITHDRAWAL - RENT PAYMENT",
+      "transactionType": "DEBIT",
+      "amount": 5000.00
+    },
+    {
+      "transactionDate": "2024-01-03",
+      "description": "DEPOSIT - ACME CORP PAYMENT",
+      "transactionType": "DEBIT",
+      "amount": 15000.50
+    },
+    ...
+  ],
+  "message": "Parsed 15 transaction(s) from CSV"
+}
+```
+
+### Import Transactions (JSON)
+
+```bash
+curl -X POST http://localhost:3000/api/bank-transactions/import \
+  -H "Content-Type: application/json" \
+  -d '{
+    "bankAccountId": "550e8400-e29b-41d4-a716-446655440000",
+    "transactions": [
+      {
+        "transactionDate": "2024-01-02",
+        "description": "ACH WITHDRAWAL - RENT PAYMENT",
+        "transactionType": "DEBIT",
+        "amount": 5000.00,
+        "referenceNumber": "ACH-123456",
+        "oppositeParty": "Landlord LLC"
+      },
+      {
+        "transactionDate": "2024-01-03",
+        "description": "DEPOSIT - ACME CORP PAYMENT",
+        "transactionType": "DEBIT",
+        "amount": 15000.50,
+        "referenceNumber": "INV-2024-001",
+        "oppositeParty": "Acme Corp"
+      }
+    ]
+  }'
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "imported": 2,
+  "message": "Successfully imported 2 transaction(s)"
+}
+```
+
+---
+
+## Common Bank CSV Exports
+
+### Chase Business Banking
+Typically uses: `Date, Description, Amount`
+- Date format: MM/DD/YYYY
+- Description includes transaction type and details
+- Single amount column (positive = debit)
+
+### Bank of America
+Typically uses: `Date, Description, Debit, Credit`
+- Date format: MM/DD/YYYY
+- Description is brief
+- Explicit debit/credit columns
+
+### Wells Fargo Business
+Typically uses: `Date, Description, Amount`
+- Date format: M/D/YYYY
+- Description is detailed
+- Amount is always positive
+
+### Quickbooks Export
+Typically uses: `Date, Reference, Amount, Description`
+- Can be remapped to standard format
+- Date format: M/D/YYYY
+- Amount includes sign (negative = credit)
+
+---
+
+## Data Quality Notes
+
+### Best Practices for CSV Uploads
+
+1. **Remove headers:** API expects headers in first row
+2. **Check date format:** Should be YYYY-MM-DD or MM/DD/YYYY
+3. **Consistent amounts:** All positive numbers (debit/credit indicated by column)
+4. **No special formatting:** Avoid currency symbols ($), commas in amounts (500.00, not 500,00)
+5. **Quoted descriptions:** Use quotes if description contains commas
+6. **No summary rows:** Remove total/balance rows at end of file
+
+### Invalid Examples (Will Fail)
+
+```csv
+Date,Description,$Amount
+1/2/24,Rent Payment,"$5,000.00"
+1/3/24,Deposit,15000.50
+```
+**Problems:**
+- Currency symbol in header ($Amount)
+- Non-standard date format (1/2/24)
+- Currency formatting in amount ($5,000.00)
+
+### Valid Examples (Will Succeed)
+
+```csv
+Date,Description,Amount
+2024-01-02,Rent Payment,5000.00
+2024-01-03,Deposit,15000.50
+```
+
+---
+
+## Testing Workflow
+
+### Step 1: Prepare CSV
+Use one of the example files above or export from your bank.
+
+### Step 2: Parse for Preview
+```bash
+curl -X POST http://localhost:3000/api/bank-transactions/parse-csv \
+  -F "file=@bank_export.csv"
+```
+Review the parsed transactions in the response.
+
+### Step 3: Adjust if Needed
+If parsing fails, check:
+- CSV has required columns (Date, Description, Amount or Debit/Credit)
+- Date format is standard (YYYY-MM-DD or MM/DD/YYYY)
+- Descriptions with commas are quoted
+- No extra rows (headers, totals, etc.)
+
+### Step 4: Import
+Once happy with preview, send parsed transactions to import endpoint.
+
+```bash
+curl -X POST http://localhost:3000/api/bank-transactions/import \
+  -H "Content-Type: application/json" \
+  -d '{
+    "bankAccountId": "your-account-uuid",
+    "transactions": [... from parse response ...]
+  }'
+```
+
+### Step 5: Verify in UI
+Log in and check that transactions appear in:
+- Bank Transactions list view
+- Bank Account details
+- Cash position report
+
+---
+
+## Troubleshooting
+
+### "CSV must have 'Date' and 'Description' columns"
+- Check header row for exact column names
+- Use: `Date` and `Description` (case-sensitive)
+- Or: `date`, `description` (lowercase works too)
+
+### "CSV must have 'Amount' or 'Debit'/'Credit' columns"
+- Format 1: Include `Amount` column
+- Format 2: Include both `Debit` AND `Credit` columns
+- Cannot mix formats in same file
+
+### "CSV file is empty"
+- Check that file was uploaded successfully
+- File must have at least header + 1 data row
+
+### "Cannot read property 'toLowerCase' of null"
+- Likely missing required columns
+- Verify CSV header row has Date and Description
+
+### Transactions show with wrong type (DEBIT vs CREDIT)
+- In Format 1 (single Amount column), all treated as DEBIT
+- Use Format 2 (Debit/Credit columns) for mixed transaction types
+- Or ensure negative amounts are handled correctly