API

TaleShop provides a public API for other plugins to integrate with.

Getting the API

TaleShopProvider api = TaleShopAPI.get();
if (api == null) {
    // TaleShop is not loaded
    return;
}

Sub-APIs

The main TaleShopProvider gives access to four sub-APIs:

API	Description
ShopCatalog	Query and manage categories and items
ShopTransaction	Execute buy/sell operations
AuctionHouse	Create, buy, cancel listings and query mailbox
EconomyAccess	Read-only balance and currency formatting

Shop Catalog

Query and modify the shop programmatically.

ShopCatalog catalog = api.getShopCatalog();

// Get all categories
List<ShopCategory> categories = catalog.getCategories();

// Get items in a category
List<ShopItem> items = catalog.getItems("tools");

// Get a specific item
ShopItem item = catalog.getItem("tools", "Tool_Pickaxe_Iron");

Shop Transactions

Execute buy/sell operations on behalf of players.

ShopTransaction tx = api.getShopTransaction();

// Buy an item for a player
tx.buyItem(player, shopItem, amount);

// Sell an item for a player
tx.sellItem(player, shopItem, amount);

Auction House

Auction operations are async and return CompletableFuture.

AuctionHouse auction = api.getAuctionHouse();

// Get active listings
CompletableFuture<List<AuctionListing>> listings = auction.getActiveListings();

// Create a listing
auction.createListing(player, itemStack, price);

// Buy a listing
auction.buyListing(player, listingId);

// Cancel a listing
auction.cancelListing(player, listingId);

Economy Access

Read-only access to the active economy provider.

EconomyAccess economy = api.getEconomyAccess();

// Get player balance
double balance = economy.getBalance(player);

// Check if player can afford something
boolean canAfford = economy.has(player, 100.0);

// Format currency for display
String formatted = economy.format(100.0); // "$ 100"

// Get economy provider name
String name = economy.getEconomyName();

Events

TaleShop fires events that other plugins can listen to. Cancellable events can be cancelled to prevent the action.

ShopBuyEvent (Cancellable)

Fired before a player buys an item from the shop.

@EventHandler
public void onShopBuy(ShopBuyEvent event) {
    Player player = event.getPlayer();
    ShopItem item = event.getItem();
    int amount = event.getAmount();
    BigDecimal totalCost = event.getTotalCost();

    // Cancel to prevent the purchase
    event.setCancelled(true);
}

ShopSellEvent (Cancellable)

Fired before a player sells an item to the shop.

@EventHandler
public void onShopSell(ShopSellEvent event) {
    Player player = event.getPlayer();
    ShopItem item = event.getItem();
    int amount = event.getAmount();
    BigDecimal totalRevenue = event.getTotalRevenue();
}

AuctionCreateEvent (Cancellable)

Fired before a player creates an auction listing.

@EventHandler
public void onAuctionCreate(AuctionCreateEvent event) {
    Player seller = event.getSeller();
    ItemStack item = event.getItem();
    BigDecimal price = event.getPrice();
}

AuctionBuyEvent (Cancellable)

Fired before a player buys an auction listing.

@EventHandler
public void onAuctionBuy(AuctionBuyEvent event) {
    Player buyer = event.getBuyer();
    AuctionListing listing = event.getListing();
}

AuctionCancelEvent (Cancellable)

Fired before a player cancels their auction listing.

@EventHandler
public void onAuctionCancel(AuctionCancelEvent event) {
    Player player = event.getPlayer();
    AuctionListing listing = event.getListing();
}

AuctionExpireEvent

Fired when an auction listing expires. Not cancellable.

@EventHandler
public void onAuctionExpire(AuctionExpireEvent event) {
    AuctionListing listing = event.getListing();
}

GitHub

API source and documentation: github.com/catzalli/TaleShop