# 03 — Function TODOs

What each interactor method does, inputs, outputs, and edge cases.

---

## expense / GetExpenses

### `subscribeAll(): Flow<List<ExpenseWithCategory>>`
JOIN expenses with categories, ordered by `date DESC`, `createdAt DESC`. Emits on any change to either table.

### `subscribeByDateRange(range: DateRange): Flow<List<ExpenseWithCategory>>`
Same join, filtered: `expense.date >= range.start AND expense.date <= range.end`. Ordered date DESC.

### `awaitOne(id: Long): ExpenseWithCategory?`
Single JOIN lookup by expense id. Returns null if not found.

### `awaitAll(query: String, range: DateRange?): List<ExpenseWithCategory>`
One-shot search. If `query` is blank and `range` is null, returns all expenses (ordered date DESC). If `query` is non-blank, filters: `note LIKE '%query%'` OR `CAST(amount AS TEXT) LIKE '%query%'` OR `category.name LIKE '%query%'`. If `range` is non-null, also filters by date range. Results ordered date DESC.

---

## expense / UpsertExpense

### `await(expense: Expense): Long`
If `expense.id == 0L`: insert and return generated id. Otherwise: update by id and return the existing id. Uses Room `@Upsert`.

---

## expense / InsertExpenses

### `awaitAll(expenses: List<Expense>)`
Bulk insert in a single Room transaction. Used after the user confirms PDF import. `expense.id` must be 0 for all items.

---

## expense / DeleteExpense

### `await(id: Long)`
Deletes expense by primary key. Does not touch any `RecurringExpense` template that generated it — those continue running independently.

---

## expense / ReassignExpenseCategory

### `await(fromCategoryId: Long, toCategoryId: Long)`
Single SQL `UPDATE expenses SET categoryId = :toCategoryId WHERE categoryId = :fromCategoryId`. Used by `DeleteCategory` before removing a category.

---

## expense / GetExpenseSummary

### `await(range: DateRange): ExpenseSummary`
1. Fetch all expenses with category in range (one-shot, uses DAO directly).
2. Sum all amounts → `totalAmount`.
3. Group by category, sum per group, sort by amount DESC → `byCategory`.
4. Return `ExpenseSummary(totalAmount, byCategory, range)`.

---

## category / GetCategories

### `subscribeAll(): Flow<List<Category>>`
All categories ordered by name ASC, emits on change.

### `awaitOne(id: Long): Category?`
Nullable lookup by primary key.

### `awaitAll(): List<Category>`
One-shot list, ordered by name ASC.

### `awaitDefault(): Category`
Returns the single category where `isDefault = true`. Throws `IllegalStateException` if not found (seeding hasn't run — should not happen in practice).

---

## category / UpsertCategory

### `await(category: Category): Long`
Insert if `id == 0`, update otherwise. Returns the id. Does not allow changing `isDefault` — if the incoming category has `isDefault = true` but the existing DB record has `isDefault = false`, the DB value wins (impl reads existing `isDefault` before update). In practice, only the seeder sets `isDefault = true`.

---

## category / DeleteCategory

### `await(id: Long)`
1. Guard: fetch category by id. If `isDefault = true`, throw `IllegalArgumentException("Cannot delete a default category")`.
2. Find the fallback: call `getCategories.awaitDefault()` to get the "Other" category id.
3. Call `reassignExpenseCategory.await(id, fallbackId)` to move orphaned expenses.
4. Delete the category from the DB.

Steps 3 and 4 run sequentially in the interactor (not a DB transaction). If step 4 fails, expenses are already reassigned to Other — acceptable, retry is safe.

---

## category / SeedDefaultCategories

### `await()`
Checks count of categories in DB. If count > 0, no-op. Otherwise inserts the 8 default categories (see `01-data-model.md`). Called from `MainApplication.onCreate` after `startKoin` completes, using a `CoroutineScope(Dispatchers.IO)`.

---

## recurring / GetRecurringExpenses

### `subscribeAll(): Flow<List<RecurringExpenseWithCategory>>`
All recurring expenses (active and inactive) joined with category, ordered by `nextDueDate ASC`. Emits on change.

### `awaitOne(id: Long): RecurringExpense?`
Nullable lookup by primary key.

---

## recurring / UpsertRecurringExpense

### `await(recurring: RecurringExpense): Long`
Insert if `id == 0`, update otherwise. Caller must set `nextDueDate = startDate` on initial insert.

---

## recurring / DeleteRecurringExpense

### `await(id: Long)`
Deletes the recurring template by id. Expense instances previously created from this template retain their `recurringExpenseId` value — they become historical records and are not deleted.

---

## recurring / ProcessDueRecurringExpenses

### `await(today: LocalDate): List<Expense>`
1. Query recurring expenses where `isActive = true AND nextDueDate <= today`.
2. For each due item:
   a. Create `Expense(amount, categoryId, note from template, date = nextDueDate, recurringExpenseId = template.id)`.
   b. Insert the expense.
   c. Advance: `newNextDueDate = interval.advance(current nextDueDate)`.
   d. Update the recurring template with `nextDueDate = newNextDueDate`.
3. Return the list of created expenses so the caller can show a banner.

Edge case — app not opened for multiple intervals: advances `nextDueDate` by one interval per call. The next app open will process it again if still overdue. This avoids flooding the expense list with back-filled entries.

---

## bankstatement / BankStatementImporter

### `val bankName: String`
Display name shown in the bank picker (e.g. `"BRI"`, `"Jago"`, `"BNI"`).

### `await(pdfUri: Uri): Result<List<PendingImportExpense>>`
Contract for all implementations:
1. Open PDF via `ContentResolver.openInputStream(pdfUri)`.
2. Extract text with PDFBox-Android (`PDDocument` + `PDFTextStripper`), page by page.
3. Parse bank-specific format into raw entry models (e.g. `BRIStatementEntry`).
4. Filter to debit-only rows (skip credits/income).
5. Map raw entries to `PendingImportExpense` — parse Indonesian number format (`1.500.000,00`), parse date strings to `LocalDate`.
6. Return `Result.success(list)` or `Result.failure(exception)`.

**`ImportBRIBankStatement.await`** — stub: `Result.failure(NotImplementedError("BRI import not yet implemented"))`.

**`ImportJagoBankStatement.await`** — stub: same.

**`ImportBNIBankStatement.await`** — stub: same.

---

## export / ExportExpensesToCsv

### `await(range: DateRange, outputUri: Uri): Result<Unit>`
1. Fetch all `ExpenseWithCategory` in range from DAO (one-shot).
2. Open `OutputStream` via `context.contentResolver.openOutputStream(outputUri)`.
3. Wrap with Okio `BufferedSink`.
4. Write UTF-8 BOM (`0xEF, 0xBB, 0xBF`) for Excel compatibility.
5. Write header: `Date,Category,Amount,Note`.
6. For each expense: `date` in ISO 8601 (`yyyy-MM-dd`), then `category.name`, `amount`, `"note"` (double-quote the note to handle embedded commas).
7. Close sink.
8. Return `Result.success(Unit)` or `Result.failure(exception)`.