# API Functionality

## API Functionality

This section provides detailed documentation for each function available in the **BlanketEconomy API**. These functions are designed to help developers manage in-game currencies effectively, both virtual and item-based.

### 1. `getBalance`

**Signature**: `getBalance(playerId: UUID, currencyType: String): BigDecimal`

* **Description**: Retrieves the balance of a specific player for a given currency type.
* **Parameters**:
  * `playerId` (UUID): The UUID of the player.
  * `currencyType` (String): The type of currency.
* **Returns**: `BigDecimal` - The balance of the player in the specified currency.
* **Example**:

  ```kotlin
  val balance = api.getBalance(playerUUID, "gold_coin")
  println("Player balance: $balance")
  ```

### 2. `setBalance`

**Signature**: `setBalance(playerId: UUID, balance: BigDecimal, currencyType: String)`

* **Description**: Sets the balance of a specific player for a given currency type.
* **Parameters**:
  * `playerId` (UUID): The UUID of the player.
  * `balance` (BigDecimal): The new balance to set.
  * `currencyType` (String): The type of currency.
* **Example**:

  ```kotlin
  api.setBalance(playerUUID, BigDecimal(1000), "gold_coin")
  ```

### 3. `addBalance`

**Signature**: `addBalance(playerId: UUID, amount: BigDecimal, currencyType: String)`

* **Description**: Adds a specific amount to the balance of a player for a given currency type.
* **Parameters**:
  * `playerId` (UUID): The UUID of the player.
  * `amount` (BigDecimal): The amount to add.
  * `currencyType` (String): The type of currency.
* **Example**:

  ```kotlin
  api.addBalance(playerUUID, BigDecimal(500), "cobble_coin")
  ```

### 4. `subtractBalance`

**Signature**: `subtractBalance(playerId: UUID, amount: BigDecimal, currencyType: String): Boolean`

* **Description**: Subtracts a specific amount from the balance of a player for a given currency type. Returns `true` if successful, `false` otherwise.
* **Parameters**:
  * `playerId` (UUID): The UUID of the player.
  * `amount` (BigDecimal): The amount to subtract.
  * `currencyType` (String): The type of currency.
* **Returns**: `Boolean` - `true` if the balance was successfully subtracted; `false` otherwise.
* **Example**:

  ```kotlin
  val success = api.subtractBalance(playerUUID, BigDecimal(100), "gold_coin")
  if (success) {
      println("Balance subtracted successfully.")
  } else {
      println("Insufficient funds.")
  }
  ```

### 5. `transfer`

**Signature**: `transfer(fromPlayerId: UUID, toPlayerId: UUID, amount: BigDecimal, currencyType: String): Boolean`

* **Description**: Transfers a specific amount of currency from one player to another. Returns `true` if successful, `false` if the sender has insufficient funds.
* **Parameters**:
  * `fromPlayerId` (UUID): The UUID of the player sending the currency.
  * `toPlayerId` (UUID): The UUID of the player receiving the currency.
  * `amount` (BigDecimal): The amount to transfer.
  * `currencyType` (String): The type of currency.
* **Returns**: `Boolean` - `true` if the transfer was successful; `false` otherwise.
* **Example**:

  ```kotlin
  val transferSuccess = api.transfer(fromPlayerUUID, toPlayerUUID, BigDecimal(150), "gold_coin")
  if (transferSuccess) {
      println("Transfer completed successfully.")
  } else {
      println("Transfer failed: insufficient funds.")
  }
  ```

### 6. `addEventListener`

**Signature**: `addEventListener(listener: EconomyEventListener)`

* **Description**: Adds an event listener to the economy system. The listener will be notified of specific events, such as when a player's balance changes.
* **Parameters**:
  * `listener` (EconomyEventListener): The listener to handle events.
* **Example**:

  ```kotlin
  val myListener = object : EconomyEventListener {
      override fun onBalanceChanged(playerId: UUID, currencyType: String, newBalance: BigDecimal) {
          println("Player $playerId has a new balance of $newBalance $currencyType.")
      }
  }
  api.addEventListener(myListener)
  ```

### 7. `removeEventListener`

**Signature**: `removeEventListener(listener: EconomyEventListener)`

* **Description**: Removes a previously added event listener from the economy system.
* **Parameters**:
  * `listener` (EconomyEventListener): The listener to remove.
* **Example**:

  ```kotlin
  api.removeEventListener(myListener)
  ```

### 8. `conditionalTransaction`

**Signature**: `conditionalTransaction(playerId: UUID, amount: BigDecimal, currencyType: String, condition: (BigDecimal) -> Boolean): Boolean`

* **Description**: Performs a transaction that subtracts an amount from a player's balance only if a condition is met.
* **Parameters**:
  * `playerId` (UUID): The UUID of the player.
  * `amount` (BigDecimal): The amount to subtract.
  * `currencyType` (String): The type of currency.
  * `condition` ((BigDecimal) -> Boolean): The condition for the transaction.
* **Returns**: `Boolean` - `true` if the condition was met and the transaction succeeded.
* **Example**:

  ```kotlin
  val condition: (BigDecimal) -> Boolean = { balance -> balance > BigDecimal(500) }
  val result = api.conditionalTransaction(playerUUID, BigDecimal(100), "gold_coin", condition)

  if (result) {
      println("Transaction successful!")
  } else {
      println("Transaction failed: Condition not met or insufficient funds.")
  }
  ```

### 9. `logTransaction`

**Signature**: `logTransaction(playerId: UUID, currencyType: String, amount: BigDecimal, type: String)`

* **Description**: Logs a transaction for a player.
* **Parameters**:
  * `playerId` (UUID): The UUID of the player.
  * `currencyType` (String): The type of currency.
  * `amount` (BigDecimal): The amount of the transaction.
  * `type` (String): The type of transaction (e.g., "credit", "debit").
* **Example**:

  ```kotlin
  api.logTransaction(playerUUID, "gold_coin", BigDecimal(150), "credit")
  println("Transaction logged for player $playerUUID.")
  ```

### 10. `getTransactionHistory`

**Signature**: `getTransactionHistory(playerId: UUID): List<Transaction>`

* **Description**: Retrieves the transaction history for a specific player.
* **Parameters**:
  * `playerId` (UUID): The UUID of the player.
* **Returns**: `List<Transaction>` - A list of transaction details.
* **Example**:

  ```kotlin
  val history = api.getTransactionHistory(playerUUID)
  history.forEach { transaction ->
      println("Transaction Type: ${transaction.type}, Amount: ${transaction.amount}, Currency: ${transaction.currencyType}")
  }
  ```

***

### Additional API Functions

```kotlin
/**
 * The instance of the Minecraft server this API is operating on.
 */
val server: MinecraftServer

/**
 * Retrieves the balance of a player for a specific currency type.
 * @param playerId The UUID of the player.
 * @param currencyType The type of currency to check.
 * @return The balance as a BigDecimal.
 */
fun getBalance(playerId: UUID, currencyType: String): BigDecimal

/**
 * Sets the balance of a player for a specific currency type.
 * @param playerId The UUID of the player.
 * @param balance The new balance to set.
 * @param currencyType The type of currency to set the balance for.
 */
fun setBalance(playerId: UUID, balance: BigDecimal, currencyType: String)

/**
 * Adds an amount to a player's balance for a specific currency type.
 * @param playerId The UUID of the player.
 * @param amount The amount to add.
 * @param currencyType The type of currency to add to.
 */
fun addBalance(playerId: UUID, amount: BigDecimal, currencyType: String)

/**
 * Subtracts an amount from a player's balance for a specific currency type.
 * @param playerId The UUID of the player.
 * @param amount The amount to subtract.
 * @param currencyType The type of currency to subtract from.
 * @return True if the operation was successful, false if the player has insufficient funds.
 */
fun subtractBalance(playerId: UUID, amount: BigDecimal, currencyType: String): Boolean

/**
 * Transfers an amount of currency from one player to another.
 * @param fromPlayerId The UUID of the player sending the currency.
 * @param toPlayerId The UUID of the player receiving the currency.
 * @param amount The amount to transfer.
 * @param currencyType The type of currency to transfer.
 * @return True if the transfer was successful, false otherwise.
 */
fun transfer(fromPlayerId: UUID, toPlayerId: UUID, amount: BigDecimal, currencyType: String): Boolean

/**
 * Registers an event listener for economy-related events.
 * @param listener The event listener to add.
 */
fun addEventListener(listener: EconomyEventListener)

/**
 * Unregisters an event listener for economy-related events.
 * @param listener The event listener to remove.
 */
fun removeEventListener(listener: EconomyEventListener)

/**
 * Performs a transaction only if a specified condition is met.
 * @param playerId The UUID of the player.
 * @param amount The amount for the transaction.
 * @param currencyType The type of currency to transact.
 * @param condition A lambda function that defines the condition.
 * @return True if the transaction is completed, false otherwise.
 */
fun conditionalTransaction(playerId: UUID, amount: BigDecimal, currencyType: String, condition: (BigDecimal) -> Boolean): Boolean

/**
 * Logs a transaction for a player in a specific currency type.
 * @param playerId The UUID of the player.
 * @param currencyType The type of currency.
 * @param amount The amount involved in the transaction.
 * @param type The type of transaction (e.g., "credit", "debit").
 */
fun logTransaction(playerId: UUID, currencyType: String, amount: BigDecimal, type: String)

/**
 * Retrieves the transaction history for a player.
 * @param playerId The UUID of the player.
 * @return A list of transactions made by the player.
 */
fun getTransactionHistory(playerId: UUID): List<Transaction>

/**
 * Creates a new currency with specific properties.
 * @param name The name of the currency.
 * @param lore The lore (description) of the currency.
 * @param material The material type of the currency item.
 * @param customModelData The custom model data ID for the item.
 * @param balanceStart The starting balance for this currency.
 * @return True if the currency was created successfully, false otherwise.
 */
fun createCurrency(name: String, lore: String, material: String, customModelData: Int, balanceStart: BigDecimal, symbol: String, isPrimary: Boolean): Boolean

/**
 * Checks if a player has enough funds for a transaction.
 * @param playerId The UUID of the player.
 * @param amount The amount to check.
 * @param currencyType The type of currency.
 * @return True if the player has enough funds, false otherwise.
 */
fun hasEnoughFunds(playerId: UUID, amount: BigDecimal, currencyType: String): Boolean

/**
 * Manages a player's inventory by adding or removing a specified item.
 * @param playerId The UUID of the player.
 * @param itemStack The item stack to add or remove.
 * @param action The action to perform (ADD or REMOVE).
 * @return True if the action was successful, false otherwise.
 */
fun manageInventory(playerId: UUID, itemStack: ItemStack, action: InventoryAction): Boolean

/**
 * Processes a batch of transactions.
 * @param transactions A list of transactions to process.
 * @return True if all transactions were processed successfully, false otherwise.
 */
fun processBatchTransactions(transactions: List<Transaction>): Boolean

/**
 * Adds a specified amount of currency items to a player's inventory.
 * @param playerId The UUID of the player.
 * @param itemStack The currency item stack.
 * @param amount The amount to add.
 * @return True if the currency items were added successfully, false otherwise.
 */
fun addCurrencyItem(playerId: UUID, itemStack: ItemStack, amount: Int): Boolean

/**
 * Removes a specified amount of currency items from a player's inventory.
 * @param playerId The UUID of the player.
 * @param itemStack The currency item stack.
 * @param amount The amount to remove.
 * @return True if the currency items were removed successfully, false otherwise.
 */
fun removeCurrencyItem(playerId: UUID, itemStack: ItemStack, amount: Int): Boolean

/**
 * Transfers a specified amount of currency items from one player to another.
 * @param fromPlayerId The UUID of the player sending the currency items.
 * @param toPlayerId The UUID of the player receiving the currency items.
 * @param itemStack The currency item stack.
 * @param amount The amount to transfer.
 * @return True if the transfer was successful, false otherwise.
 */
fun transferCurrencyItem(fromPlayerId: UUID, toPlayerId: UUID, itemStack: ItemStack, amount: Int): Boolean

/**
 * Gets the balance of a specific currency item in a player's inventory.
 * @param playerId The UUID of the player.
 * @param itemStack The currency item stack to check.
 * @return The total amount of the currency item in the player's inventory.
 */
fun getCurrencyItemBalance(playerId: UUID, itemStack: ItemStack): Int

/**
 * Checks if a player has enough of a specific currency item.
 * @param playerId The UUID of the player.
 * @param itemStack The currency item stack to check.
 * @param amount The amount required.
 * @return True if the player has enough currency items, false otherwise.
 */
fun hasEnoughCurrencyItems(playerId: UUID, itemStack: ItemStack, amount: Int): Boolean

/**
 * Gets the type of a currency item based on its properties.
 * @param itemStack The currency item stack.
 * @return The currency type as a string, or null if it is not a currency item.
 */
fun getCurrencyItemType(itemStack: ItemStack): String?

/**
 * Retrieves the primary currency from the configuration.
 * @return The primary currency as EconomyConfig.
 */
fun getPrimaryCurrency(): Blanketconfig.EconomyConfig?

/**
 * Returns the valid currency type or falls back to the primary currency if the type is incorrect.
 * @param currencyType The requested currency type.
 * @return The valid currency type or the primary one.
 */
fun getCurrencyTypeOrFallback(currencyType: String): String

/**
 * Retrieves the symbol for a specific currency type.
 * @param currencyType The type of currency.
 * @return The symbol of the currency as a string, or empty string if not found.
 */
fun getCurrencySymbol(currencyType: String): String

/**
 * Retrieves the list of all configured currencies.
 *
 * @return A list of `EconomyConfig` representing all available currencies.
 */
fun getCurrencyList(): List<Blanketconfig.EconomyConfig>

/**
 * Checks if a currency with the specified type exists.
 *
 * @param currencyType The type of currency to check.
 * @return True if the currency exists, false otherwise.
 */
fun currencyExists(currencyType: String): Boolean
```
