GreenStash Documentation

Use GoalToCSVConverter.convertFromCSV() to parse a CSV string back into a BackupCSVModel. This model contains the schema version, the backup timestamp, and the reconstructed list of GoalWithTransactions.

The converter includes a compatibility layer for version == 1 backups, which handles legacy deadline formats (string-based dd/MM/yyyy or yyyy/MM/dd) by converting them to epoch milliseconds using parseOldDeadlineToMillis.

val converter = GoalToCSVConverter()
val backupModel = converter.convertFromCSV(csvString)

// Access the data
val goals = backupModel.data
val version = backupModel.version

The WidgetConfigViewModel is used to manage the configuration of home screen widgets, specifically mapping a widget to a specific saving goal.

It provides access to all available goals via allGoals and allows you to persist the relationship between a widget and a goal using setWidgetData.

// Accessing all available goals for selection
val goals = viewModel.allGoals.value

// Mapping a specific widget to a selected goal
viewModel.setWidgetData(
    widgetId = currentWidgetId,
    goalId = selectedGoalId
) { goalItem -> 
    // Callback triggered on the Main thread after successful database insertion
    // goalItem is the GoalWithTransactions associated with the selected goalId
    println("Widget configured for goal: ${goalItem.goal.name}")
}

If a user performs a deposit via a notification action, you can update the existing notification to confirm the transaction using updateWithDepositNotification. This replaces the current reminder with a success message showing the amount deposited, formatted with the user's default currency.

Requires the goalId and the amount deposited.

// Updates the notification for a specific goal with the deposited amount
reminderSender.updateWithDepositNotification(goalId = 123L, amount = 50.0)

Call refreshReminders() to trigger a background synchronization of reminders. This method fetches all goals from the GoalDao and passes them to the ReminderManager to check and schedule upcoming reminders.

mainViewModel.refreshReminders()

Restores goals and transactions from a backup string (JSON or CSV) back into the database. This method handles the parsing and database insertion logic.

Parameters:

• backupString: The raw string content of the backup file.
• backupType: The format of the string (BackupType.JSON or BackupType.CSV). Defaults to JSON.
• onFailure: A callback executed on the Main thread if parsing fails or the data is invalid.
• onSuccess: A callback executed on the Main thread if the restoration completes successfully.

Note: This is a suspend function and should be called from a coroutine scope.

backupManager.restoreDatabaseBackup(
    backupString = myBackupString,
    backupType = BackupType.JSON,
    onFailure = { 
        // Handle error on Main thread
    },
    onSuccess = { 
        // Handle success on Main thread
    }
)

Use scheduleReminder(goalId: Long) to schedule a daily reminder for a specific goal. The reminder is automatically set for 09:30 AM. If the scheduled time for the current day has already passed, the reminder is set for the same time on the following day.

This method uses Android's AlarmManager with RTC_WAKEUP to ensure the reminder triggers even if the device is in sleep mode.

val reminderManager = ReminderManager(context)
reminderManager.scheduleReminder(goalId = 123L)

The PreferenceUtil class provides a simplified interface for interacting with Android's SharedPreferences to persist application settings. It is initialized with an Android Context and manages a private preferences file named greenstash_settings.

To use it, instantiate the class with a context and use the provided put and get methods with the predefined constant keys found in the PreferenceUtil.Companion object.

// Initialize the utility
val preferenceUtil = PreferenceUtil(context)

// Storing a value
preferenceUtil.putString(PreferenceUtil.DEFAULT_CURRENCY_STR, "EUR")
preferenceUtil.putBoolean(PreferenceUtil.APP_LOCK_BOOL, true)

// Retrieving a value
val currency = preferenceUtil.getString(PreferenceUtil.DEFAULT_CURRENCY_STR, "USD")
val isLocked = preferenceUtil.getBoolean(PreferenceUtil.APP_LOCK_BOOL, false)

Generates a database backup by converting goals and transaction data into either JSON or CSV format. The method saves the file to the application's cache directory and returns a chooser Intent that allows the user to share the backup file (e.g., via email, cloud storage, or file manager).

// backupType can be BackupType.JSON or BackupType.CSV
val chooserIntent = backupManager.createDatabaseBackup(BackupType.JSON)
// Use the returned intent to start an activity (e.g., via startActivity(chooserIntent))

Use checkAndScheduleReminders(allGoals: List<GoalWithTransactions>) to iterate through a list of goals and schedule reminders for any goal that has its reminder property enabled but does not currently have an active scheduled reminder.

// Assuming allGoals is a List<GoalWithTransactions> retrieved from the database
reminderManager.checkAndScheduleReminders(allGoals)

The GoalToJSONConverter class provides utilities to serialize and deserialize savings goal data for backup and export purposes. It handles the conversion between the application's internal GoalWithTransactions data models and a JSON string format.

It includes a built-in compatibility layer that automatically detects and migrates legacy backup files (Version 1) where goal deadlines were stored as strings (e.g., "dd/MM/yyyy") to the current format where deadlines are stored as Long (epoch milliseconds).

val converter = GoalToJSONConverter()

// Exporting data to JSON
val goals: List<GoalWithTransactions> = // ... get data from database
val jsonString = converter.convertToJson(goals)

// Importing data from JSON
val restoredModel = converter.convertFromJson(jsonString)
val restoredGoals = restoredModel.data