# Project Context Log

## [2025-08-19 10:00] - Initial Setup & Context Discussion

- Initial project directory structure reviewed.
- Agreed to use this file (`PROJECT_CONTEXT.md`) as a log/journal for our collaboration.
- Decided on a format for entries: `## [YYYY-MM-DD HH:MM] - Brief Description of Key Info/Topic`.
- This file will be updated after each significant discussion or task completion to capture context, decisions, or important notes.
- Next steps: Begin working on specific tasks within the project. New entries will be added here as needed.

## [2025-08-19 10:15] - Firefly III Transaction Submission API Research

- Researched Firefly III API documentation for submitting transactions.
- Found the correct endpoint: `POST /api/v1/transactions`.
- Identified required and optional JSON fields for a transaction.
- Obtained an example `curl` command for submitting a transaction.

**Key Information:**
- **Endpoint:** `POST /api/v1/transactions`
- **Required Headers:**
  - `Authorization: Bearer YOUR_ACCESS_TOKEN`
  - `Content-Type: application/json`
- **Example JSON Payload:**
  ```json
  {
    "transactions": [
      {
        "type": "withdrawal",
        "date": "2023-10-01",
        "amount": "100.00",
        "description": "Groceries",
        "source_id": 1,
        "destination_id": 2,
        "category_id": 3,
        "budget_id": 4
      }
    ]
  }
  ```
- **Example `curl` Command:**
  ```bash
  curl -X POST "https://your-firefly-iii-instance.com/api/v1/transactions" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "transactions": [
      {
        "type": "withdrawal",
        "date": "2023-10-01",
        "amount": "100.00",
        "description": "Groceries",
        "source_id": 1,
        "destination_id": 2,
        "category_id": 3,
        "budget_id": 4
      }
    ]
  }'
  ```
  *(Note: Replace `YOUR_ACCESS_TOKEN` and the instance URL with actual values)*

## [2025-08-19 10:30] - Firefly III Accounts Retrieval API Research

- Researched Firefly III API documentation for retrieving accounts.
- Found the correct endpoint: `GET /api/v1/accounts`.
- Learned how to filter accounts by type (e.g., `asset`, `expense`, `revenue`).
- Obtained example `curl` commands for fetching accounts.

**Key Information:**
- **Endpoint:** `GET /api/v1/accounts`
- **Required Headers:**
  - `Authorization: Bearer YOUR_ACCESS_TOKEN`
  - `Accept: application/json`
- **Query Parameters:**
  - `type`: Filter accounts by type (`asset`, `expense`, `revenue`, `liability`, `loan`, `debt`, `mortgage`).
  - `page`: For pagination.
- **Example `curl` Commands:**
  ```bash
  # Get all accounts
  curl -X GET "https://your-firefly-iii-instance.com/api/v1/accounts" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Accept: application/json"

  # Get only 'asset' accounts (commonly used as source accounts)
  curl -X GET "https://your-firefly-iii-instance.com/api/v1/accounts?type=asset" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Accept: application/json"

  # Get 'expense' accounts (commonly used as destination for withdrawals)
  curl -X GET "https://your-firefly-iii-instance.com/api/v1/accounts?type=expense" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Accept: application/json"
  ```
- **Response Structure:**
  The response includes a `data` array where each account object has an `id` and `attributes` containing details like `name` and `type`.

## [2025-08-19 10:45] - Create `curl_scripts` Directory and Scripts

- Created a new directory `curl_scripts` to store our API interaction scripts.
- Created `get_accounts.sh`:
  - Script to fetch accounts from Firefly III using `GET /api/v1/accounts`.
  - Includes examples for fetching all accounts, 'asset' accounts (source), and 'expense' accounts (destination).
  - Uses environment variables for URL and token for security.
- Created `submit_dummy_transaction.sh`:
  - Script to submit a dummy transaction to Firefly III using `POST /api/v1/transactions`.
  - Uses environment variables for URL, token, source ID, and destination ID.
  - Includes basic error handling and response code checking.
- Made both scripts executable with `chmod +x`.

## [2025-08-19 11:00] - Update `get_accounts.sh` Script for Filtering

- Updated `curl_scripts/get_accounts.sh` to accept an optional `ACCOUNT_TYPE` environment variable.
- This allows fetching specific types of accounts (e.g., `asset`, `expense`) to reduce output clutter.
- Example usage:
  ```bash
  YOUR_FIREFLY_III_URL="..." YOUR_ACCESS_TOKEN="..." ACCOUNT_TYPE="asset" ./curl_scripts/get_accounts.sh
  ```
- Added debug output to show the final URL being used by the script.
- Re-applied executable permissions to the updated script.

## [2025-08-19 11:15] - Clarify Account Types for 'Receipt' Context

- Discussed the specific account types needed for submitting a 'receipt' (struk) transaction.
- **For a 'receipt' representing incoming funds/purchase:**
  - **`source_id`**: Should be an account of type **`revenue`** (e.g., Salary, Gift). This is where the money is considered to come from.
  - **`destination_id`**: Should be an account of type **`asset`** (e.g., Checking Account, Cash Wallet). This is where the money ends up.
- Updated understanding for using `get_accounts.sh`:
  - Run once with `ACCOUNT_TYPE="revenue"` to find a suitable `source_id`.
  - Run once with `ACCOUNT_TYPE="asset"` to find a suitable `destination_id`.
- These IDs will then be used with `submit_dummy_transaction.sh` to create the transaction record in Firefly III.

## [2025-08-19 11:30] - Fix Bug in `submit_dummy_transaction.sh`

- Identified and fixed a bug in `curl_scripts/submit_dummy_transaction.sh` that caused error `line 25: Dummy: command not found`.
- The issue was due to an incorrect use of a multiline string variable assignment (`read -r -d '' ... << EOM`).
- The script was updated to build the JSON payload directly within the `curl` command using `-d` with proper escaping. This is a more robust and portable method.
- Re-applied executable permissions to the corrected script.

## [2025-08-19 11:45] - Fix Account Type Mismatch & Add Transaction Type Flexibility

- Diagnosed the `HTTP Code: 000` and subsequent Firefly III error `[a] Could not find a valid source account...`.
- Root cause: The transaction `type` in `submit_dummy_transaction.sh` was hardcoded to `withdrawal`, which is incompatible with using a `revenue` account as `source_id`.
- **Solution Implemented:**
  - Updated `curl_scripts/submit_dummy_transaction.sh` to accept an optional `TRANSACTION_TYPE` environment variable.
  - Default value for `TRANSACTION_TYPE` is now set to `deposit`, which is the correct type when `source_id` is `revenue` and `destination_id` is `asset`.
  - Example usage for 'receipt' context:
    ```bash
    YOUR_FIREFLY_III_URL="..." YOUR_ACCESS_TOKEN="..." SOURCE_ACCOUNT_ID=92 DESTINATION_ACCOUNT_ID=1 TRANSACTION_TYPE="deposit" ./curl_scripts/submit_dummy_transaction.sh
    ```
- This change provides more flexibility for testing different transaction types and ensures compatibility with the intended account types for a 'receipt'.
- Re-applied executable permissions to the updated script.

## [2025-08-19 12:00] - Successfully Submit Dummy Transaction via `curl`

- After correcting the account types and transaction type, successfully submitted a dummy transaction using `submit_dummy_transaction.sh`.
- Confirmed that `source_id` from a `revenue` account and `destination_id` from an `asset` account, with `TRANSACTION_TYPE="deposit"`, works correctly.

## [2025-08-19 12:15] - Start Integrating with Flutter App

- Goal: Create a Flutter screen to select source and destination accounts from Firefly III and submit a transaction.
- Checked `pubspec.yaml` and confirmed `http: ^1.5.0` is already included.
- Created `lib/models/firefly_account.dart`:
  - Defined a `FireflyAccount` model to represent account data from the API.
  - Includes `id`, `name`, and `type` properties.
  - Has a `fromJson` factory constructor for easy parsing.
- Created `lib/services/firefly_api_service.dart`:
  - Defined `FireflyApiService` class to encapsulate API calls.
  - Includes `fetchAccounts({String? type})` to get accounts, filtering by type if provided.
  - Includes `submitDummyTransaction` to send a transaction to the API.
  - Uses `Bearer` token authentication.
- Created `lib/screens/transaction_screen.dart`:
  - Defined `TransactionScreen` widget.
  - Fetches `revenue` and `asset` accounts on initialization.
  - Displays two dropdowns for selecting source (`revenue`) and destination (`asset`) accounts.
  - Includes buttons to reload accounts and submit a dummy transaction.
  - Shows loading indicators and status messages.

## [2025-08-19 12:30] - Improve Security & User Experience

- Recognized that hardcoding URL/token is insecure. Implemented a better approach.
- Created `lib/screens/config_screen.dart`:
  - New screen for users to input Firefly III URL and Personal Access Token.
  - Uses `TextField` for input with basic validation.
  - Stores credentials securely using `shared_preferences`.
- Modified `lib/services/firefly_api_service.dart`:
  - Removed hardcoded URL and token.
  - Updated `fetchAccounts` and `submitDummyTransaction` methods to accept `baseUrl` and `accessToken` as required parameters.
- Modified `lib/screens/transaction_screen.dart`:
  - Updated to load URL and token from `shared_preferences`.
  - Passes loaded credentials to `FireflyApiService` methods.
  - Adds a settings icon in the app bar to navigate to `ConfigScreen`.
  - Handles cases where credentials are missing or invalid.

## [2025-08-19 13:00] - Add Debug Logging for Account Loading

- Added extensive debug `print` statements to `FireflyApiService` and `TransactionScreen`.
- Purpose: To trace the flow of data loading, identify where the process might be failing, and verify if accounts are successfully fetched and parsed from the Firefly III API.
- This will help diagnose why the dropdowns for source and destination accounts might appear empty even after configuration is set.

## [2025-08-20 14:00] - Refactor main.dart and Correct Transaction Payload

- Corrected the payload in `lib/services/firefly_api_service.dart`'s `submitDummyTransaction` method. Ensured that `source_id` and `destination_id` are passed as strings to align with Firefly III API expectations.
- Refactored `lib/main.dart` to improve the initial application flow.
- Set `TransactionScreen` as the initial route (`/`).
- Added named routes for `TransactionScreen` (`/`), `ConfigScreen` (`/config`), and `ReceiptScreen` (`/receipt`) to create a clear and maintainable navigation structure.
- This change directs the user to the primary transaction interface on startup, facilitating immediate testing of the core functionality being developed.

## [2025-08-20 14:30] - Fix Compilation and Runtime Errors

- Resolved build errors caused by incorrect import paths and class names in `lib/screens/receipt_screen.dart` and `lib/screens/settings_screen.dart`.
- Corrected the import from `firefly_service.dart` to `firefly_api_service.dart`.
- Renamed all instances of `FireflyService` to the correct class name, `FireflyApiService`.
- Implemented the missing `testConnection` and `testAuthentication` methods in `lib/services/firefly_api_service.dart` to enable configuration testing.
- Updated `lib/screens/settings_screen.dart` to pass the required `baseUrl` and `accessToken` parameters to the new API service methods.
- The application is now in a runnable state, allowing for further testing of the Firefly III integration.

## [2025-08-20 15:00] - Redesign Receipt UI to Match Sample Image

- Redesigned the `ReceiptScreen` UI to match a more traditional receipt format similar to `sample-struk.jpg`.
- Updated the layout to have a receipt paper style with proper borders and styling.
- Improved the item list display with better alignment and formatting.
- Moved transaction settings to a separate section with better organization.
- Updated the PDF export service to match the new UI design.
- Fixed several syntax errors and code quality issues identified by the analyzer.
- The UI now has a more professional receipt appearance with proper spacing, dividers, and formatting.

## [2025-08-20 16:00] - Update Receipt UI with Courier Font and Fix Layout Issues

- Added `google_fonts` dependency to `pubspec.yaml` to use Courier Prime font for a more authentic receipt appearance.
- Updated `ReceiptScreen` to use a fixed-width layout that resembles a physical receipt.
- Added transaction details like cashier ID and transaction ID.
- Improved the overall styling with better spacing, dividers, and a thank you message.
- Fixed syntax errors in the `receipt_screen.dart` file that were preventing the app from building correctly.
- Successfully ran the app on a physical device and verified that the new UI is displayed correctly.
- Confirmed that the app can be navigated to the ReceiptScreen, though it currently defaults to TransactionScreen as the home route.

## [2025-08-20 17:00] - Fix PDF Export Path and Add PDF Opening Functionality

- Updated `PdfExportService` to use the application documents directory instead of temporary directory for saving PDF files.
- Added a function to open the generated PDF file using the `open_file` package.
- Modified `_printReceipt` function in `ReceiptScreen` to automatically open the generated PDF after creation.
- This ensures that users can easily access and view the generated receipt PDFs on their devices.

## [2025-08-20 18:00] - Implement Bluetooth Thermal Printer Functionality

- Integrated the `bluetooth_print` plugin to enable printing receipts on thermal printers.
- Added Bluetooth device scanning and connection functionality in `ReceiptScreen`.
- Implemented a function to format and print receipts to thermal printers using the ESC/POS protocol.
- Added UI elements to connect to Bluetooth printers and print receipts.
- The thermal printer functionality allows users to print receipts directly from the app to compatible Bluetooth thermal printers.

## [2025-08-20 19:00] - Fix UI Overflow and setState() After Dispose Errors

- Fixed UI overflow error in `ReceiptScreen` by properly sizing the action buttons using `Expanded` widgets.
- Resolved `setState() called after dispose` errors in `SettingsScreen` by adding `mounted` checks before calling `setState()`.
- These fixes improve the stability and user experience of the application.

## [2025-08-20 20:00] - Final Testing and Bug Fixes

- Successfully built and ran the application on a physical device.
- Verified that all core functionalities work as expected:
  - Connection to Firefly III API
  - Account fetching and selection
  - Transaction submission
  - PDF generation and opening
  - Bluetooth printer connection and printing
- Fixed remaining syntax errors in the codebase.
- The application is now fully functional and ready for use.