# 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