# API Reference

# API Reference

Technical reference for plugin developers. Provides programmatic access to the Shop system through the unified CoreAPI facade.

:::info Module
The CoreAPI is provided by the Core mod (`KyuubiSoftCore-2.9.9.jar`). Ensure the Core mod is loaded before calling any API methods.
:::

## Getting the API Instance

```java
import com.kyuubisoft.core.api.CoreAPI;

// Availability check (recommended)
if (CoreAPI.isAvailable()) {
    CoreAPI api = CoreAPI.getInstance();
    // ...
}

// Or direct (returns null if Core is not loaded)
CoreAPI api = CoreAPI.getInstance();
if (api == null) {
    // Core plugin not loaded
    return;
}
```

## Shop Methods

| Method | Return Type | Description |
|--------|-------------|-------------|
| `openShop(Player, PlayerRef, Ref, Store, String shopId)` | `void` | Open a shop UI for the player |
| `getShop(String id)` | `ShopConfig` | Get the ShopConfig by ID, or `null` if not found |
| `registerShop(ShopConfig)` | `void` | Register a custom shop configuration at runtime |
| `registerCurrency(CurrencyProvider)` | `void` | Register a custom currency provider |
| `getCurrency(String id)` | `CurrencyProvider` | Get a currency provider by ID, or `null` if not found |

## Interfaces

### CurrencyProvider

Implement this interface to define a custom currency for the shop system. Each currency must have a unique ID.

```java
import com.kyuubisoft.core.shop.CurrencyProvider;

public interface CurrencyProvider {
    /** Unique currency ID (e.g., "quest_tokens", "achievement_points", "item:Ingredient_Bar_Gold") */
    String getCurrencyId();

    /** Display name (i18n key or plain text) */
    String getDisplayName();

    /** Icon item ID for display in the shop header */
    String getIconItemId();

    /** Get the player's current balance */
    int getBalance(Player player);

    /** Whether the player can pay now (since 2.9.2). Default: getBalance(player) >= amount.
     *  Providers whose balance lives in a database may answer from a cache; spend() still decides. */
    default boolean canAfford(Player player, int amount) { ... }

    /** Deduct currency. Returns true on success, false if insufficient balance. */
    boolean spend(Player player, int amount);

    /** Credit currency back (for refunds). */
    void refund(Player player, int amount);

    /** Credit currency and report whether the full amount arrived (since 2.7.4).
     *  Default: calls refund() and returns true. Override it if a payout can fail. */
    default boolean tryRefund(Player player, int amount) { ... }
}
```

Existing providers keep working: both new methods have defaults. Override `tryRefund` if your payout can fail (for example a full inventory), so Core can log a failed refund instead of losing it silently.

## Usage Examples

### Open a Shop Programmatically

```java
CoreAPI api = CoreAPI.getInstance();

// Open a shop for the player
// (typically called from within a command or event handler that has access to PlayerRef/Ref/Store)
api.openShop(player, playerRef, ref, store, "blacksmith_shop");
```

### Register a Custom Currency

```java
CoreAPI api = CoreAPI.getInstance();

api.registerCurrency(new CurrencyProvider() {
    @Override
    public String getCurrencyId() { return "quest_tokens"; }

    @Override
    public String getDisplayName() { return "Quest Tokens"; }

    @Override
    public String getIconItemId() { return "Ingredient_Bar_Gold"; }

    @Override
    public int getBalance(Player player) {
        return questData.getTokens(player);
    }

    @Override
    public boolean spend(Player player, int amount) {
        if (questData.getTokens(player) < amount) return false;
        questData.removeTokens(player, amount);
        return true;
    }

    @Override
    public void refund(Player player, int amount) {
        questData.addTokens(player, amount);
    }
});
```

### Check Shop Existence

```java
CoreAPI api = CoreAPI.getInstance();

ShopConfig shop = api.getShop("blacksmith_shop");
if (shop != null) {
    LOGGER.info("Shop found: " + shop.id);
} else {
    LOGGER.warning("Shop 'blacksmith_shop' does not exist");
}
```

### Register a Custom Shop at Runtime

```java
CoreAPI api = CoreAPI.getInstance();

ShopConfig customShop = new ShopConfig();
// ... configure shop items, currency, etc. ...
api.registerShop(customShop);
```

Shops that another mod registers this way are shown **read-only** in Core's shop editor, with that mod's name. Admins can copy them as a Core shop, but changes belong in your mod's own files.

### Check Currency Balance

```java
CoreAPI api = CoreAPI.getInstance();

CurrencyProvider currency = api.getCurrency("quest_tokens");
if (currency != null) {
    int balance = currency.getBalance(player);
    player.sendMessage("You have " + balance + " " + currency.getDisplayName());
}
```

## Thread Safety

- Shops and currencies are kept in concurrent maps, so registration is thread-safe
- `getShop` and `getCurrency` are read-only lookups and can be called from any thread
- `openShop` involves UI operations and should be called from the main thread or within `world.execute()`
- `registerShop` and `registerCurrency` can be called during plugin initialization or at runtime