bank_accounts/API.md

# Bank Accounts - API Documentation

This document describes the public API for the `bank_accounts` mod, allowing other mods to safely interact with player account data.

## Introduction

The entire API is accessible through the global table `bank_accounts`. It is highly recommended to check for its existence before using it to ensure the mod is enabled:

```lua
if not bank_accounts then
    -- bank_accounts mod is not enabled or not loaded yet
    return
end
```

All functions that modify a player's balance or credit will automatically create a corresponding entry in the player's transaction history (account statement).

## Data Types

* **player_name:** A string representing the player's name (e.g., `"Rage87"`).
* **amount:** A number. The API supports floating-point numbers for digital transactions. Note that the ATM and Teller Computer nodes enforce integer-only values for physical cash withdrawals and deposits.
* **trans_type:** A short, non-translatable string used as a key to identify the transaction method (e.g., `"API Purchase"`, `"Quest Reward"`). This string should be added to a `.tr` file for localization.
* **purpose:** A short, user-facing string that describes the transaction. This will be displayed directly in the account statement.
* **other_party:** A string representing the name of the other player or entity involved in the transaction.

---

## API Functions

### Data Retrieval

---

#### `bank_accounts.get_account_data(player_name)`
Returns a table containing all key data for a single player. This is the most efficient way to get multiple pieces of information at once.

* **`player_name`** `(string)`: The name of the player.
* **Returns:** A table with the following structure:
    ```lua
    {
      balance = 1234.56, -- (number) The player's current balance.
      credit = 500.00,   -- (number) The player's current credit debt.
      pin = "1234",      -- (string) The player's PIN.
      history = { ... }  -- (table) A list of transaction tables for the player.
    }
    ```

**Example:**
```lua
local data = bank_accounts.get_account_data("Rage87")
if data then
    print("Balance for Rage87: " .. data.balance)
end
```

---

#### `bank_accounts.get_balance(player_name)`
Returns only the balance of a player.

* **`player_name`** `(string)`: The name of the player.
* **Returns:** A `number` representing the player's balance, or `0` if the player has no account.

---

#### `bank_accounts.get_credit(player_name)`
Returns only the credit debt of a player.

* **`player_name`** `(string)`: The name of the player.
* **Returns:** A `number` representing the player's credit debt, or `0`.

---

#### `bank_accounts.player_has_account(player_name)`
Checks if a player has an account in the database.

* **`player_name`** `(string)`: The name of the player.
* **Returns:** `true` if the account exists, `false` otherwise.

---
### Data Modification

All modification functions will create an entry in the transaction history.

---

#### `bank_accounts.add_balance(player_name, amount, trans_type, purpose, other_party)`
Adds a value to a player's balance. Use a negative amount to subtract.

* **`player_name`** `(string)`: The name of the player whose balance will be changed.
* **`amount`** `(number)`: The amount to add (can be negative).
* **`trans_type`** `(string)`: The internal type for this transaction (e.g., `"Quest Reward"`).
* **`purpose`** `(string)`: *(optional)* A user-facing description (e.g., `"For completing the 'Dragon Slayer' quest."`).
* **`other_party`** `(string)`: *(optional)* The name of the entity giving the money (e.g., `"King's Treasury"`).
* **Returns:** `true` on success.

**Example:**
```lua
-- Give player 'Rage87' a quest reward of 150.75 MG.
bank_accounts.add_balance("Rage87", 150.75, "Quest Reward", "Dragon Slaying", "King Arthur")
```

---

#### `bank_accounts.set_balance(player_name, amount, trans_type, purpose, other_party)`
Sets a player's balance to an absolute value. The transaction log will record the *difference* between the old and new balance.

* **`player_name`** `(string)`: The name of the player.
* **`amount`** `(number)`: The new absolute balance.
* **`trans_type`**, **`purpose`**, **`other_party`**: Same as above.
* **Returns:** `true` on success.

---

#### `bank_accounts.add_credit(player_name, amount, trans_type, purpose, other_party)`
Adds a value to a player's credit debt. Use a negative amount to pay off debt.

* **Parameters:** Same as `add_balance`.
* **Returns:** `true` on success.

**Example:**
```lua
-- A shop mod charges an item to the player's credit card.
bank_accounts.add_credit("Rage87", 99.95, "Credit Purchase", "Diamond Pickaxe", "Tool Shop")
```

---

#### `bank_accounts.set_credit(player_name, amount, trans_type, purpose, other_party)`
Sets a player's credit debt to an absolute value.

* **Parameters:** Same as `set_balance`.
* **Returns:** `true` on success.

---

#### `bank_accounts.set_pin(player_name, pin)`
Sets a player's PIN. This should rarely be used by external mods.

* **`player_name`** `(string)`: The name of the player.
* **`pin`** `(string)`: The new 4-digit PIN.
* **Returns:** `true` on success.

---
### Background Scripting Functions

These functions are intended for scripts that need to process all accounts at once, like the `interest.lua` script. Use with caution.

---

#### `bank_accounts.get_all_data()`
Reads and returns the entire accounts database.

* **Returns:** The complete data `table`.

---

#### `bank_accounts.save_all(data)`
Saves the entire provided data table, overwriting the existing file. Includes a lock to wait for the interest calculation to finish.

* **`data`** `(table)`: The complete and modified data table to be saved.
* **Returns:** `true` on success.