Mint

https://mint.mintychochip.dev
Admin
Mint is a Java library that provides economy account management and transaction handling with audit...
Tokens:19,612
Snippets:122
Trust Score:4.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Get All Services by Priority (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/ServiceHolder

Returns a list of all registered service instances, ordered by their priority in descending order (highest priority first). If no services are registered, an empty list is returned.

```java
List<T> getAll();
```

--------------------------------

### Get Top Balances Asynchronously (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/Service

Asynchronously retrieves a map of holder IDs to their balances, sorted in descending order by balance. This is useful for leaderboards. The `limit` parameter restricts the number of entries returned. The operation is non-blocking and returns a CompletableFuture.

```Java
CompletableFuture<Map<UUID,BigDecimal>> getTopBalances(int limit)
```

--------------------------------

### Get Transaction State (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/Transaction

Retrieves the current lifecycle state of the transaction. Returns the current state object.

```java
Transaction.State getState()

```

--------------------------------

### Get Highest Priority Service (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/ServiceHolder

Retrieves the service instance with the highest priority currently registered in the holder. If multiple services share the same highest priority, the one that was registered first will be returned. Returns null if no services are registered.

```java
T get();
```

--------------------------------

### Transaction Result Details

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/TransactionResult

Retrieve detailed information about a specific transaction result. This includes its ID, commit time, start time, state, operation count, total amount, and a list of all operations or operations for a specific account.

```APIDOC
## Transaction Result API

### Description
Provides methods to access details of a committed transaction.

### Methods

#### `getId()`

*   **Description**: Returns the unique identifier for this transaction.
*   **Returns**: `UUID` - The transaction UUID.

#### `getCommitTime()`

*   **Description**: Returns the instant when the transaction was committed.
*   **Returns**: `Instant` - The transaction commit timestamp.

#### `getStartTime()`

*   **Description**: Returns the instant when the transaction was created.
*   **Returns**: `Instant` - The transaction start timestamp.

#### `getState()`

*   **Description**: Returns the final state of the transaction. Always `Transaction.State.COMMITTED` for results returned from successful commits.
*   **Returns**: `Transaction.State` - The transaction state.

#### `getOperationCount()`

*   **Description**: Returns the number of operations executed in this transaction.
*   **Returns**: `int` - The operation count.

#### `getTotalAmount()`

*   **Description**: Returns the sum of all operation amounts. This aggregates amounts from all operations regardless of type or direction.
*   **Returns**: `BigDecimal` - The total transaction amount.

#### `getOperations()`

*   **Description**: Returns all operations executed in this transaction in execution order. The returned list is unmodifiable.
*   **Returns**: `List<TransactionOperation>` - An immutable list of operations.

#### `getOperationsFor(UUID accountId)`

*   **Description**: Returns all operations that affected the specified account. Filters operations where `TransactionOperation.accountId()` matches the parameter.
*   **Parameters**:
    *   `accountId` (UUID) - Required - The account identifier to filter by.
*   **Returns**: `List<TransactionOperation>` - A list of operations for the account (may be empty).

### Factory Method (Internal Use)

#### `of(UUID id, List<TransactionOperation> operations, Transaction.State state, Instant startTime, Instant commitTime)`

*   **Description**: Factory method to create a transaction result. Typically used by implementors, not by API consumers.
*   **Parameters**:
    *   `id` (UUID) - Required - Transaction identifier.
    *   `operations` (List<TransactionOperation>) - Required - List of operations (will be copied to unmodifiable list).
    *   `state` (Transaction.State) - Required - Final transaction state.
    *   `startTime` (Instant) - Required - Transaction creation timestamp.
    *   `commitTime` (Instant) - Required - Transaction commit timestamp.
*   **Returns**: `TransactionResult` - A new transaction result instance.
```

--------------------------------

### Mint Class and Constants

Source: https://mint.mintychochip.dev/index-all

Main class and static variables for the Mint service.

```APIDOC
## CLASS Mint

### Description
Main entry point for the Mint economy system.

### Static Variables
- **SERVICE** (Static variable) - Represents the primary Mint service.
```

--------------------------------

### Create Account Asynchronously (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/Service

Asynchronously creates a new account for a given holder. It requires the holder's ID and a display name for the account. The operation returns a CompletableFuture that will complete with the newly created account object.

```Java
CompletableFuture<Account> createAccount(UUID holderId, String name)
```

--------------------------------

### PluginActor Constructor

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/TransactionContext.PluginActor

Provides details on how to create an instance of the PluginActor record.

```APIDOC
## POST /TransactionContext/PluginActor

### Description
Creates an instance of a `PluginActor` record class, representing a Bukkit plugin that initiated a transaction.

### Method
POST

### Endpoint
`/TransactionContext/PluginActor`

### Parameters
#### Request Body
- **plugin** (org.bukkit.plugin.Plugin) - Required - The Bukkit plugin that initiated the transaction.

### Request Example
```json
{
  "plugin": "your_plugin_instance"
}
```

### Response
#### Success Response (201)
- **actor** (TransactionContext.PluginActor) - The created PluginActor instance.

#### Response Example
```json
{
  "actor": {
    "plugin": "your_plugin_instance"
  }
}
```
```

--------------------------------

### Deposit Funds Asynchronously (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/Service

Asynchronously deposits funds into a specified holder's account. This operation takes the holder's ID and the deposit amount. The returned CompletableFuture completes with the amount that was successfully deposited, providing a non-blocking mechanism for fund additions.

```Java
CompletableFuture<BigDecimal> deposit(UUID holderId, BigDecimal amount)
```

--------------------------------

### Service Interface Documentation

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/Service

Documentation for the primary service interface for managing economy accounts and transactions.

```APIDOC
## Service Interface

Primary service interface for managing economy accounts and transactions. All account operations are asynchronous and return `CompletableFuture`. Transactions are synchronously created but execute asynchronously on commit.

### Available Since

1.1

### Methods

#### `getName()`

- **Description**: Returns the name of this service implementation.
- **Method**: GET (Implicit)
- **Endpoint**: N/A
- **Response**: String - the service name

#### `getMaxFractionalDigits()`

- **Description**: Returns the maximum number of fractional digits allowed for currency amounts.
- **Method**: GET (Implicit)
- **Endpoint**: N/A
- **Response**: int - maximum decimal places for monetary values

#### `beginTransaction(UUID accountId)`

- **Description**: Begins a new transaction against the specified account with empty context. Equivalent to `beginTransaction(accountId, TransactionContext.empty())`.
- **Method**: POST (Implicit for transaction start)
- **Endpoint**: N/A
- **Parameters**:
  - **Path Parameters**:
    - `accountId` (UUID) - Required - The account to transact against
- **Response**: Transaction - a new active transaction

#### `beginTransaction(UUID accountId, TransactionContext ctx)`

- **Description**: Begins a new transaction against the specified account with provided context. The transaction is created in `Transaction.State.ACTIVE` state. Operations can be chained before calling `Transaction.commit()`.
- **Method**: POST (Implicit for transaction start)
- **Endpoint**: N/A
- **Parameters**:
  - **Path Parameters**:
    - `accountId` (UUID) - Required - The account to transact against
  - **Request Body**:
    - `ctx` (TransactionContext) - Required - Context containing actor and optional reason
- **Response**: Transaction - a new active transaction

#### `getAccount(UUID accountId)`

- **Description**: Asynchronously retrieves an account by its identifier.
- **Method**: GET
- **Endpoint**: `/accounts/{accountId}`
- **Parameters**:
  - **Path Parameters**:
    - `accountId` (UUID) - Required - The account identifier
- **Response**:
  - **Success Response (200)**:
    - `Account` (Account) - The account details or empty if not found

#### `createAccount(UUID holderId, String name)`

- **Description**: Asynchronously creates a new account for the specified holder.
- **Method**: POST
- **Endpoint**: `/accounts`
- **Parameters**:
  - **Request Body**:
    - `holderId` (UUID) - Required - The unique identifier of the account holder
    - `name` (String) - Required - The name of the account
- **Response**:
  - **Success Response (200)**:
    - `Account` (Account) - The newly created account details

#### `deleteAccount(UUID accountId)`

- **Description**: Asynchronously deletes the specified account.
- **Method**: DELETE
- **Endpoint**: `/accounts/{accountId}`
- **Parameters**:
  - **Path Parameters**:
    - `accountId` (UUID) - Required - The identifier of the account to delete
- **Response**:
  - **Success Response (200)**:
    - `Boolean` - `true` if the account was successfully deleted, `false` otherwise

#### `updateAccountName(UUID accountId, String name)`

- **Description**: Asynchronously updates the display name of the specified account.
- **Method**: PUT
- **Endpoint**: `/accounts/{accountId}`
- **Parameters**:
  - **Path Parameters**:
    - `accountId` (UUID) - Required - The identifier of the account to update
  - **Request Body**:
    - `name` (String) - Required - The new name for the account
- **Response**:
  - **Success Response (200)**:
    - `Boolean` - `true` if the account name was successfully updated, `false` otherwise

#### `getBalanceByAccount(UUID accountId)`

- **Description**: Asynchronously retrieves the balance of the specified account.
- **Method**: GET
- **Endpoint**: `/accounts/{accountId}/balance`
- **Parameters**:
  - **Path Parameters**:
    - `accountId` (UUID) - Required - The account identifier
- **Response**:
  - **Success Response (200)**:
    - `BigDecimal` - The account balance

#### `getBalanceByHolder(UUID holderId)`

- **Description**: Asynchronously retrieves the balance of the account for the specified holder.
- **Method**: GET
- **Endpoint**: `/holders/{holderId}/balance`
- **Parameters**:
  - **Path Parameters**:
    - `holderId` (UUID) - Required - The holder's unique identifier
- **Response**:
  - **Success Response (200)**:
    - `BigDecimal` - The account balance for the holder

#### `getBalances(List<UUID> accountIds)`

- **Description**: Asynchronously retrieves balances for multiple accounts in a single batch operation.
- **Method**: POST
- **Endpoint**: `/accounts/balances`
- **Parameters**:
  - **Request Body**:
    - `accountIds` (List<UUID>) - Required - List of account identifiers
- **Response**:
  - **Success Response (200)**:
    - `List<BigDecimal>` - A list of balances in the same order as the input `accountIds`

#### `hasAccount(UUID holderId)`

- **Description**: Asynchronously checks if an account exists for the specified holder.
- **Method**: GET
- **Endpoint**: `/holders/{holderId}/account/exists`
- **Parameters**:
  - **Path Parameters**:
    - `holderId` (UUID) - Required - The holder's unique identifier
- **Response**:
  - **Success Response (200)**:
    - `Boolean` - `true` if an account exists for the holder, `false` otherwise

#### `deposit(UUID holderId, BigDecimal amount)`

- **Description**: Asynchronously deposits funds into the specified holder's account.
- **Method**: POST
- **Endpoint**: `/holders/{holderId}/deposit`
- **Parameters**:
  - **Path Parameters**:
    - `holderId` (UUID) - Required - The holder's unique identifier
  - **Request Body**:
    - `amount` (BigDecimal) - Required - The amount to deposit
- **Response**:
  - **Success Response (200)**:
    - `BigDecimal` - The new balance after the deposit

#### `withdraw(UUID holderId, BigDecimal amount)`

- **Description**: Asynchronously withdraws funds from the specified holder's account.
- **Method**: POST
- **Endpoint**: `/holders/{holderId}/withdraw`
- **Parameters**:
  - **Path Parameters**:
    - `holderId` (UUID) - Required - The holder's unique identifier
  - **Request Body**:
    - `amount` (BigDecimal) - Required - The amount to withdraw
- **Response**:
  - **Success Response (200)**:
    - `BigDecimal` - The new balance after the withdrawal

#### `transfer(UUID fromHolderId, UUID toHolderId, BigDecimal amount)`

- **Description**: Asynchronously transfers funds from one holder's account to another holder's account.
- **Method**: POST
- **Endpoint**: `/transfer`
- **Parameters**:
  - **Request Body**:
    - `fromHolderId` (UUID) - Required - The identifier of the holder to transfer funds from
    - `toHolderId` (UUID) - Required - The identifier of the holder to transfer funds to
    - `amount` (BigDecimal) - Required - The amount to transfer
- **Response**:
  - **Success Response (200)**:
    - `Boolean` - `true` if the transfer was successful, `false` otherwise

#### `getTopBalances(int limit)`

- **Description**: Asynchronously retrieves all holder balances sorted by balance in descending order, limited by the specified count.
- **Method**: GET
- **Endpoint**: `/holders/top-balances`
- **Parameters**:
  - **Query Parameters**:
    - `limit` (int) - Required - The maximum number of top balances to retrieve
- **Response**:
  - **Success Response (200)**:
    - `Map<UUID, BigDecimal>` - A map where keys are holder IDs and values are their balances, sorted by balance in descending order
```

--------------------------------

### Service and Account Operations

Source: https://mint.mintychochip.dev/index-all

Details on interacting with the Mint service, including account withdrawals.

```APIDOC
## Interface `dev.mintychochip.mint.Transaction`

### Methods
#### `withdraw(BigDecimal amount)`
- **Description**: Stages a withdrawal operation to remove funds from the account.
- **Method**: INSTANCE
- **Parameters**:
  - `amount` (BigDecimal) - The amount of funds to withdraw.

## Interface `dev.mintychochip.mint.Service`

### Methods
#### `withdraw(UUID accountId, BigDecimal amount)`
- **Description**: Asynchronously withdraws funds from the specified holder's account.
- **Method**: INSTANCE
- **Parameters**:
  - `accountId` (UUID) - The unique identifier of the account from which to withdraw funds.
  - `amount` (BigDecimal) - The amount of funds to withdraw.
```

--------------------------------

### PluginActor Methods

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/TransactionContext.PluginActor

Details on the methods available for the PluginActor record, including getType, getName, toString, hashCode, equals, and plugin.

```APIDOC
## GET /TransactionContext/PluginActor/{actorId}

### Description
Retrieves information about a specific PluginActor.

### Method
GET

### Endpoint
`/TransactionContext/PluginActor/{actorId}`

### Parameters
#### Path Parameters
- **actorId** (String) - Required - The unique identifier of the PluginActor.

### Response
#### Success Response (200)
- **actor** (TransactionContext.PluginActor) - The requested PluginActor details.

#### Response Example
```json
{
  "actor": {
    "plugin": "your_plugin_instance"
  }
}
```

## GET /TransactionContext/PluginActor/{actorId}/type

### Description
Retrieves the type of the PluginActor.

### Method
GET

### Endpoint
`/TransactionContext/PluginActor/{actorId}/type`

### Parameters
#### Path Parameters
- **actorId** (String) - Required - The unique identifier of the PluginActor.

### Response
#### Success Response (200)
- **type** (TransactionContext.Actor.Type) - The type of the actor.

#### Response Example
```json
{
  "type": "PLUGIN"
}
```

## GET /TransactionContext/PluginActor/{actorId}/name

### Description
Retrieves the display name of the PluginActor.

### Method
GET

### Endpoint
`/TransactionContext/PluginActor/{actorId}/name`

### Parameters
#### Path Parameters
- **actorId** (String) - Required - The unique identifier of the PluginActor.

### Response
#### Success Response (200)
- **name** (String) - The display name of the actor.

#### Response Example
```json
{
  "name": "YourPluginName"
}
```

## GET /TransactionContext/PluginActor/{actorId}/details

### Description
Retrieves the string representation of the PluginActor, including its components.

### Method
GET

### Endpoint
`/TransactionContext/PluginActor/{actorId}/details`

### Parameters
#### Path Parameters
- **actorId** (String) - Required - The unique identifier of the PluginActor.

### Response
#### Success Response (200)
- **details** (String) - The string representation of the PluginActor.

#### Response Example
```json
{
  "details": "TransactionContext.PluginActor[plugin=your_plugin_instance]"
}
```

## GET /TransactionContext/PluginActor/{actorId}/hashCode

### Description
Retrieves the hash code value for the PluginActor.

### Method
GET

### Endpoint
`/TransactionContext/PluginActor/{actorId}/hashCode`

### Parameters
#### Path Parameters
- **actorId** (String) - Required - The unique identifier of the PluginActor.

### Response
#### Success Response (200)
- **hashCode** (Integer) - The hash code value of the actor.

#### Response Example
```json
{
  "hashCode": 123456789
}
```

## POST /TransactionContext/PluginActor/{actorId}/equals

### Description
Checks if the specified PluginActor is equal to another object.

### Method
POST

### Endpoint
`/TransactionContext/PluginActor/{actorId}/equals`

### Parameters
#### Path Parameters
- **actorId** (String) - Required - The unique identifier of the PluginActor.
#### Request Body
- **otherObject** (Object) - Required - The object to compare with.

### Response
#### Success Response (200)
- **isEqual** (Boolean) - True if the objects are equal, false otherwise.

#### Response Example
```json
{
  "isEqual": true
}
```

## GET /TransactionContext/PluginActor/{actorId}/plugin

### Description
Retrieves the Bukkit plugin associated with the PluginActor.

### Method
GET

### Endpoint
`/TransactionContext/PluginActor/{actorId}/plugin`

### Parameters
#### Path Parameters
- **actorId** (String) - Required - The unique identifier of the PluginActor.

### Response
#### Success Response (200)
- **plugin** (org.bukkit.plugin.Plugin) - The Bukkit plugin instance.

#### Response Example
```json
{
  "plugin": "your_plugin_instance"
}
```
```

--------------------------------

### Account Management API

Source: https://mint.mintychochip.dev/index-all

Endpoints for creating, retrieving, and deleting accounts within the Mint Economy system.

```APIDOC
## POST /api/accounts

### Description
Asynchronously creates a new account for a specified holder.

### Method
POST

### Endpoint
/api/accounts

### Parameters
#### Query Parameters
- **holderId** (UUID) - Required - The unique identifier for the account holder.
- **holderName** (String) - Required - The name of the account holder.

### Request Example
```json
{
  "holderId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "holderName": "John Doe"
}
```

### Response
#### Success Response (200)
- **accountId** (UUID) - The unique identifier of the newly created account.
- **createdAt** (Timestamp) - The timestamp when the account was created.

#### Response Example
```json
{
  "accountId": "f0e9d8c7-b6a5-4321-9876-fedcba098765",
  "createdAt": "2023-10-27T10:30:00Z"
}
```

## GET /api/accounts/{accountId}

### Description
Retrieves a read-only view of a specific account.

### Method
GET

### Endpoint
/api/accounts/{accountId}

### Parameters
#### Path Parameters
- **accountId** (UUID) - Required - The unique identifier of the account to retrieve.

### Response
#### Success Response (200)
- **accountId** (UUID) - The unique identifier of the account.
- **amount** (BigDecimal) - The current balance of the account.
- **createdAt** (Timestamp) - The timestamp when the account was created.

#### Response Example
```json
{
  "accountId": "f0e9d8c7-b6a5-4321-9876-fedcba098765",
  "amount": "1500.75",
  "createdAt": "2023-10-27T10:30:00Z"
}
```

## DELETE /api/accounts/{accountId}

### Description
Asynchronously deletes the specified account.

### Method
DELETE

### Endpoint
/api/accounts/{accountId}

### Parameters
#### Path Parameters
- **accountId** (UUID) - Required - The unique identifier of the account to delete.

### Response
#### Success Response (200)
- **message** (String) - Confirmation message of account deletion.

#### Response Example
```json
{
  "message": "Account with ID f0e9d8c7-b6a5-4321-9876-fedcba098765 deleted successfully."
}
```
```

--------------------------------

### Account Interface Methods

Source: https://mint.mintychochip.dev/index-all

Methods related to account information.

```APIDOC
## INTERFACE Account

### Description
Represents a financial account.

### Methods
- **name()** - Returns the display name of this account.
```

--------------------------------

### ServiceHolder Interface Methods

Source: https://mint.mintychochip.dev/index-all

Methods for managing services within the ServiceHolder.

```APIDOC
## INTERFACE ServiceHolder<T>

### Description
A generic priority-based service registry that supports multiple implementations.

### Methods
- **isLoaded()** - Checks if any service is currently registered.
- **register(T service, int priority)** - Registers a service with the specified integer priority.
- **register(T service, ServiceHolder.Priority priority)** - Registers a service with the specified enum priority.
```

--------------------------------

### Utility Enum Operations

Source: https://mint.mintychochip.dev/index-all

Utility methods for various enum classes within the Mint project.

```APIDOC
## Enum `dev.mintychochip.mint.ServiceHolder.Priority`

### Description
Represents the priority for service holders.

### Methods
#### `valueOf(String name)`
- **Description**: Returns the enum constant of this class with the specified name.
- **Method**: STATIC
- **Parameters**:
  - `name` (String) - The name of the enum constant to retrieve.

#### `values()`
- **Description**: Returns an array containing the constants of this enum class, in the order they are declared.
- **Method**: STATIC

## Enum `dev.mintychochip.mint.TransactionContext.Actor.Type`

### Description
Represents the types of actors in a transaction context.

### Methods
#### `valueOf(String name)`
- **Description**: Returns the enum constant of this class with the specified name.
- **Method**: STATIC
- **Parameters**:
  - `name` (String) - The name of the enum constant to retrieve.

#### `values()`
- **Description**: Returns an array containing the constants of this enum class, in the order they are declared.
- **Method**: STATIC

## Enum `dev.mintychochip.mint.TransactionException.ErrorType`

### Description
Represents the types of errors that can occur during a transaction.

### Methods
#### `valueOf(String name)`
- **Description**: Returns the enum constant of this class with the specified name.
- **Method**: STATIC
- **Parameters**:
  - `name` (String) - The name of the enum constant to retrieve.

#### `values()`
- **Description**: Returns an array containing the constants of this enum class, in the order they are declared.
- **Method**: STATIC
```

--------------------------------

### Update Account Name Asynchronously (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/Service

Asynchronously updates the display name of an existing account. It takes the account ID and the new name as parameters. The returned CompletableFuture will yield true if the update was successful, or false if the account was not found, preventing blocking operations.

```Java
CompletableFuture<Boolean> updateAccountName(UUID accountId, String name)
```

--------------------------------

### TransactionContext.Actor API

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/TransactionContext.Actor

This section details the methods available for the TransactionContext.Actor interface, including creating actors and retrieving their properties.

```APIDOC
## TransactionContext.Actor Interface

### Description
Represents the initiator of a transaction.

### Nested Classes
#### `static enum TransactionContext.Actor.Type`
Actor type classifications.

### Methods
#### `static TransactionContext.Actor simple(String name)`
Creates a simple custom actor with the specified name.

##### Parameters
- **name** (String) - Required - The actor's display name.

##### Returns
- custom actor instance

#### `default String getName()`
Returns the display name of this actor.

##### Returns
- actor name (String)

#### `default TransactionContext.Actor.Type getType()`
Returns the classification of this actor.

##### Returns
- actor type (TransactionContext.Actor.Type)
```

--------------------------------

### TransactionException Builder

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/TransactionException

Details on how to use the builder pattern to construct TransactionException instances.

```APIDOC
## TransactionException Builder

### Description
Use the `builder()` method to create a fluent interface for constructing `TransactionException` instances.

### Method
- **`builder()`**

### Endpoint
N/A (Class method)

### Parameters
None

### Request Example
```java
TransactionException exception = TransactionException.builder()
    .withErrorType(TransactionException.ErrorType.VALIDATION_FAILED)
    .withMessage("Invalid transaction data")
    .build();
```

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A
```

--------------------------------

### Transaction Interface Methods

Source: https://mint.mintychochip.dev/index-all

Methods for managing and staging transaction operations.

```APIDOC
## INTERFACE Transaction

### Description
Represents an ongoing financial transaction that allows staging operations.

### Methods
- **set(BigDecimal amount)** - Stages an operation to set the account balance to an exact value.
- **rollback()** - Discards all staged operations without applying changes.
```

--------------------------------

### PlayerActor Record Implementation in Java

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/TransactionContext.PlayerActor

Defines the PlayerActor record, a Java implementation for player-initiated transactions. It extends the Record class and implements the TransactionContext.Actor interface, holding a Bukkit Player object. Key methods include retrieving the player, actor type, and display name.

```java
public static record TransactionContext.PlayerActor(org.bukkit.entity.Player player) extends Record implements TransactionContext.Actor
Actor implementation for player-initiated transactions.

Record Components:
    `player` - the Bukkit player who initiated the transaction 

All Implemented Interfaces:
    `TransactionContext.Actor` 

Enclosing interface:
    `TransactionContext`

Constructor Summary
Constructors
Constructor
Description
`PlayerActor(org.bukkit.entity.Player player)`
Creates an instance of a `PlayerActor` record class.

Method Summary
All MethodsInstance MethodsConcrete Methods
Modifier and Type
Method
Description
`final boolean`
`equals(Object o)`
Indicates whether some other object is "equal to" this one.
`String`
`getName()`
Returns the display name of this actor.
`TransactionContext.Actor.Type`
`getType()`
Returns the classification of this actor.
`final int`
`hashCode()`
Returns a hash code value for this object.
`org.bukkit.entity.Player`
`player()`
Returns the value of the `player` record component.
`final String`
`toString()`
Returns a string representation of this record class.

Constructor Details
PlayerActor
public PlayerActor(org.bukkit.entity.Player player)
Creates an instance of a `PlayerActor` record class. 

Parameters:
    `player` - the value for the `player` record component

Method Details
getType
public TransactionContext.Actor.Type getType()
Returns the classification of this actor.

Specified by:
    `getType` in interface `TransactionContext.Actor` 

Returns:
    actor type
getName
public String getName()
Returns the display name of this actor.

Specified by:
    `getName` in interface `TransactionContext.Actor` 

Returns:
    actor name
tostring
public final String toString()
Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components. 

Specified by:
    `toString` in class `Record` 

Returns:
    a string representation of this object
hashcode
public final int hashCode()
Returns a hash code value for this object. The value is derived from the hash code of each of the record components. 

Specified by:
    `hashCode` in class `Record` 

Returns:
    a hash code value for this object
equals
public final boolean equals(Object o)
Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with `Objects::equals(Object,Object)`. 

Specified by:
    `equals` in class `Record` 

Parameters:
    `o` - the object with which to compare 

Returns:
    `true` if this object is the same as the `o` argument; `false` otherwise.
player
public org.bukkit.entity.Player player()
Returns the value of the `player` record component. 

Returns:
    the value of the `player` record component
```

--------------------------------

### Register Service with Integer Priority (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/ServiceHolder

Registers a service instance with a custom integer priority. Higher integer values indicate higher priority. If multiple services share the same highest priority, the one registered first will be selected. This method takes the service object and its integer priority as parameters.

```java
void register(T service, int priority);
```

--------------------------------

### TransactionOperation Constructor in Java

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/TransactionOperation

Defines the constructor for the TransactionOperation record class. It takes accountId, relatedAccountId, type, amount, balanceBefore, and balanceAfter as parameters to create a new transaction operation instance. This is a core method for initializing transaction objects.

```java
public TransactionOperation(UUID accountId, Optional<UUID> relatedAccountId, TransactionOperation.Type type, BigDecimal amount, BigDecimal balanceBefore, BigDecimal balanceAfter)
```

--------------------------------

### Retrieve Account Asynchronously (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/Service

Asynchronously retrieves an account using its unique identifier. The result is wrapped in an Optional within a CompletableFuture, indicating whether the account was found or not. This is useful for safely accessing account data without blocking.

```Java
CompletableFuture<Optional<Account>> getAccount(UUID accountId)
```

--------------------------------

### Balance Management API

Source: https://mint.mintychochip.dev/index-all

Endpoints for retrieving account balances, including single, multiple, and top balances.

```APIDOC
## GET /api/balances/account/{accountId}

### Description
Asynchronously retrieves the balance of the specified account.

### Method
GET

### Endpoint
/api/balances/account/{accountId}

### Parameters
#### Path Parameters
- **accountId** (UUID) - Required - The unique identifier of the account.

### Response
#### Success Response (200)
- **balance** (number) - The balance of the account.

#### Response Example
{
  "balance": 100.50
}

## GET /api/balances/holder/{holderId}

### Description
Asynchronously retrieves the balance of the account for the specified holder.

### Method
GET

### Endpoint
/api/balances/holder/{holderId}

### Parameters
#### Path Parameters
- **holderId** (UUID) - Required - The unique identifier of the holder.

### Response
#### Success Response (200)
- **balance** (number) - The balance of the account associated with the holder.

#### Response Example
{
  "balance": 100.50
}

## POST /api/balances/batch

### Description
Asynchronously retrieves balances for multiple accounts in a single batch operation.

### Method
POST

### Endpoint
/api/balances/batch

### Parameters
#### Request Body
- **accountIds** (array) - Required - A list of account identifiers.

### Request Example
{
  "accountIds": [
    "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "f1e2d3c4-b5a6-0987-6543-210fedcba987"
  ]
}

### Response
#### Success Response (200)
- **balances** (object) - A map of account IDs to their respective balances.

#### Response Example
{
  "balances": {
    "a1b2c3d4-e5f6-7890-1234-567890abcdef": 100.50,
    "f1e2d3c4-b5a6-0987-6543-210fedcba987": 25.75
  }
}

## GET /api/balances/top/{limit}

### Description
Asynchronously retrieves all holder balances sorted by balance in descending order, up to a specified limit.

### Method
GET

### Endpoint
/api/balances/top/{limit}

### Parameters
#### Path Parameters
- **limit** (integer) - Required - The maximum number of balances to retrieve.

### Response
#### Success Response (200)
- **topBalances** (array) - A list of objects, each containing holder ID and balance, sorted by balance.

#### Response Example
[
  {
    "holderId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "balance": 500.00
  },
  {
    "holderId": "f1e2d3c4-b5a6-0987-6543-210fedcba987",
    "balance": 450.25
  }
]
```

--------------------------------

### Build TransactionException with Builder - Java

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/TransactionException.TransactionExceptionBuilder

Demonstrates how to use the TransactionException.TransactionExceptionBuilder to construct a TransactionException. The builder allows setting the cause, error type, and a detail message. It is a common pattern for creating exception objects with additional context.

```java
TransactionException transactionException = new TransactionException.TransactionExceptionBuilder()
    .errorType(TransactionException.ErrorType.INVALID_INPUT)
    .message("Invalid transaction data provided.")
    .cause(new IllegalArgumentException("Missing required field."))
    .build();
```

--------------------------------

### TransactionException.TransactionExceptionBuilder Methods

Source: https://mint.mintychochip.dev/index-all

Methods for building transaction exceptions.

```APIDOC
## CLASS dev.mintychochip.mint.TransactionException.TransactionExceptionBuilder

### Methods
- **message(String message)** - Sets the detail message for the exception.
```

--------------------------------

### TransactionException Builder Methods - Java

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/TransactionException.TransactionExceptionBuilder

Illustrates the core methods of the TransactionException.TransactionExceptionBuilder for setting exception details. The `errorType`, `message`, and `cause` methods are used to configure the exception, followed by the `build` method to create the final exception object.

```java
public class TransactionExceptionBuilder extends Object {
    public TransactionExceptionBuilder errorType(TransactionException.ErrorType errorType) {
        // ... set error type
        return this;
    }

    public TransactionExceptionBuilder message(String message) {
        // ... set message
        return this;
    }

    public TransactionExceptionBuilder cause(Throwable cause) {
        // ... set cause
        return this;
    }

    public TransactionException build() {
        // ... build and return TransactionException
        return new TransactionException();
    }
}
```

--------------------------------

### TransactionOperation balanceBefore Getter in Java

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/TransactionOperation

Provides a getter method for the balanceBefore record component of the TransactionOperation class. This method returns the BigDecimal value of the account balance before the transaction.

```java
public BigDecimal balanceBefore()
```

--------------------------------

### TransactionContext Interface Methods

Source: https://mint.mintychochip.dev/index-all

Methods for accessing transaction context information.

```APIDOC
## INTERFACE TransactionContext

### Description
Provides context for a financial transaction.

### Methods
- **reason()** - Returns the optional human-readable justification for this transaction.
```

--------------------------------

### Account Management API

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/Service

Endpoints for managing financial accounts.

```APIDOC
## POST /accounts

### Description
Asynchronously creates a new account for the specified holder.

### Method
POST

### Endpoint
/accounts

### Parameters
#### Query Parameters
- **holderId** (UUID) - Required - the holder's unique identifier
- **name** (String) - Required - the display name for the account

### Response
#### Success Response (200)
- **account** (Account) - The newly created account details

#### Response Example
```json
{
  "account": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "holderId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "name": "My Account",
    "balance": 0.00
  }
}
```
```

```APIDOC
## GET /accounts/{accountId}

### Description
Asynchronously retrieves an account by its identifier.

### Method
GET

### Endpoint
/accounts/{accountId}

### Parameters
#### Path Parameters
- **accountId** (UUID) - Required - the account identifier

### Response
#### Success Response (200)
- **account** (Optional<Account>) - The account if found, otherwise empty

#### Response Example
```json
{
  "account": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "holderId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "name": "My Account",
    "balance": 100.50
  }
}
```
```

```APIDOC
## DELETE /accounts/{accountId}

### Description
Asynchronously deletes the specified account.

### Method
DELETE

### Endpoint
/accounts/{accountId}

### Parameters
#### Path Parameters
- **accountId** (UUID) - Required - the account identifier

### Response
#### Success Response (200)
- **deleted** (Boolean) - `true` if the account was deleted, `false` if not found

#### Response Example
```json
{
  "deleted": true
}
```
```

```APIDOC
## PUT /accounts/{accountId}/name

### Description
Asynchronously updates the display name of the specified account.

### Method
PUT

### Endpoint
/accounts/{accountId}/name

### Parameters
#### Path Parameters
- **accountId** (UUID) - Required - the account identifier
#### Request Body
- **name** (String) - Required - the new display name for the account

### Response
#### Success Response (200)
- **updated** (Boolean) - `true` if the account name was updated, `false` if the account was not found

#### Response Example
```json
{
  "updated": true
}
```
```

```APIDOC
## POST /transfers

### Description
Asynchronously transfers funds from one holder's account to another holder's account.

### Method
POST

### Endpoint
/transfers

### Parameters
#### Request Body
- **fromHolderId** (UUID) - Required - the holder transferring funds
- **toHolderId** (UUID) - Required - the holder receiving funds
- **amount** (BigDecimal) - Required - the amount to transfer

### Response
#### Success Response (200)
- **transferredAmount** (BigDecimal) - the amount actually transferred

#### Response Example
```json
{
  "transferredAmount": 50.00
}
```
```

```APIDOC
## POST /deposits

### Description
Asynchronously deposits funds into the specified holder's account.

### Method
POST

### Endpoint
/deposits

### Parameters
#### Request Body
- **holderId** (UUID) - Required - the holder's unique identifier
- **amount** (BigDecimal) - Required - the amount to deposit

### Response
#### Success Response (200)
- **depositedAmount** (BigDecimal) - the amount actually deposited

#### Response Example
```json
{
  "depositedAmount": 200.00
}
```
```

```APIDOC
## POST /withdrawals

### Description
Asynchronously withdraws funds from the specified holder's account.

### Method
POST

### Endpoint
/withdrawals

### Parameters
#### Request Body
- **holderId** (UUID) - Required - the holder's unique identifier
- **amount** (BigDecimal) - Required - the amount to withdraw

### Response
#### Success Response (200)
- **withdrawnAmount** (BigDecimal) - the amount actually withdrawn

#### Response Example
```json
{
  "withdrawnAmount": 75.00
}
```
```

```APIDOC
## GET /balances/top

### Description
Asynchronously retrieves all holder balances sorted by balance in descending order. This is useful for leaderboards and statistics.

### Method
GET

### Endpoint
/balances/top

### Parameters
#### Query Parameters
- **limit** (int) - Required - the maximum number of entries to return

### Response
#### Success Response (200)
- **holderBalances** (Map<UUID, BigDecimal>) - A map containing holder UUIDs as keys and their corresponding balances as values, sorted by balance (highest first).

#### Response Example
```json
{
  "holderBalances": {
    "a1b2c3d4-e5f6-7890-1234-567890abcdef": 1500.75,
    "f0e1d2c3-b4a5-6789-0123-456789abcdef": 1200.50,
    "1a2b3c4d-5e6f-7890-1234-567890abcd": 950.25
  }
}
```
```

--------------------------------

### TransactionContext Actor Static Method

Source: https://mint.mintychochip.dev/index-all

Static method for creating custom actors.

```APIDOC
## INTERFACE TransactionContext.Actor

### Description
Represents an actor involved in a transaction.

### Static Methods
- **simple(String name)** - Creates a simple custom actor with the specified name.
```

--------------------------------

### Account Management API

Source: https://mint.mintychochip.dev/index-all

Endpoints for retrieving and checking the existence of accounts.

```APIDOC
## GET /api/accounts/{accountId}

### Description
Asynchronously retrieves an account by its identifier.

### Method
GET

### Endpoint
/api/accounts/{accountId}

### Parameters
#### Path Parameters
- **accountId** (UUID) - Required - The unique identifier of the account.

### Response
#### Success Response (200)
- **accountDetails** (object) - Details of the account.

#### Response Example
{
  "accountDetails": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "holderId": "f1e2d3c4-b5a6-0987-6543-210fedcba987",
    "balance": 100.50
  }
}

## GET /api/accounts/exists/{holderId}

### Description
Asynchronously checks if an account exists for the specified holder.

### Method
GET

### Endpoint
/api/accounts/exists/{holderId}

### Parameters
#### Path Parameters
- **holderId** (UUID) - Required - The unique identifier of the holder.

### Response
#### Success Response (200)
- **exists** (boolean) - True if an account exists, false otherwise.

#### Response Example
{
  "exists": true
}
```

--------------------------------

### Check if Service Holder is Loaded (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/ServiceHolder

Determines whether any services have been registered in the ServiceHolder. This is a default method that returns true if at least one service is present, and false otherwise.

```java
default boolean isLoaded() {
    return !getAll().isEmpty();
}
```

--------------------------------

### Service Information API

Source: https://mint.mintychochip.dev/index-all

Endpoints for retrieving information about the available services and their properties.

```APIDOC
## GET /api/services

### Description
Returns all registered services ordered by priority (highest first).

### Method
GET

### Endpoint
/api/services

### Response
#### Success Response (200)
- **services** (array) - A list of registered services with their details.

#### Response Example
[
  {
    "name": "PrimaryAccountService",
    "priority": "HIGHEST",
    "maxFractionalDigits": 2
  },
  {
    "name": "SecondaryAccountService",
    "priority": "HIGH",
    "maxFractionalDigits": 4
  }
]

## GET /api/services/highest-priority

### Description
Returns the highest-priority registered service.

### Method
GET

### Endpoint
/api/services/highest-priority

### Response
#### Success Response (200)
- **service** (object) - Details of the highest-priority service.

#### Response Example
{
  "name": "PrimaryAccountService",
  "priority": "HIGHEST",
  "maxFractionalDigits": 2
}
```

--------------------------------

### TransactionContext Record Classes

Source: https://mint.mintychochip.dev/index-all

Record classes for transaction context details.

```APIDOC
## RECORD TransactionContext.PlayerActor

### Description
Represents a transaction initiated by a player.

### Components
- **player** (Player) - The player initiating the transaction.

### Constructors
- **PlayerActor(Player player)** - Creates an instance of a `PlayerActor` record class.

## RECORD TransactionContext.PluginActor

### Description
Represents a transaction initiated by a plugin or system.

### Components
- **plugin** (Plugin) - The plugin initiating the transaction.

### Constructors
- **PluginActor(Plugin plugin)** - Creates an instance of a `PluginActor` record class.
```

--------------------------------

### Transfer Funds Asynchronously (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/Service

Asynchronously facilitates fund transfers between two accounts identified by their holder IDs. It requires the source holder ID, destination holder ID, and the amount to transfer. The operation returns a CompletableFuture with the actual amount transferred, ensuring non-blocking execution.

```Java
CompletableFuture<BigDecimal> transfer(UUID fromHolderId, UUID toHolderId, BigDecimal amount)
```

--------------------------------

### Register Service with Enum Priority (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/ServiceHolder

Registers a service instance with a predefined priority level using the ServiceHolder.Priority enum. This method delegates to the integer-based registration by using the enum's ordinal value. It takes the service object and its priority as parameters.

```java
default void register(T service, ServiceHolder.Priority priority) {
    register(service, priority.ordinal());
}
```

--------------------------------

### Withdraw Funds Asynchronously (Java)

Source: https://mint.mintychochip.dev/dev/mintychochip/mint/Service

Asynchronously withdraws funds from a specified holder's account. It requires the holder's ID and the withdrawal amount. The method returns a CompletableFuture that resolves with the amount actually withdrawn, allowing for non-blocking financial transactions.

```Java
CompletableFuture<BigDecimal> withdraw(UUID holderId, BigDecimal amount)
```

--------------------------------

### TransactionResult Factory Method

Source: https://mint.mintychochip.dev/index-all

Factory method for creating transaction results.

```APIDOC
## INTERFACE TransactionResult

### Description
Represents the result of a financial transaction.

### Static Methods
- **of(UUID relatedAccountId, List<TransactionOperation> operations, Transaction.State state, Instant timestamp, Instant processingTimestamp)** - Factory method to create a transaction result.
```
Tokens:
Raw