Developer API - SnAuction Docs

SnAuction exposes a public developer API for other plugins: custom Bukkit events and a read-only query service. The API lives in the com.sn.auction.api package inside the plugin jar. There is no separate artifact.

Only com.sn.auction.api is a stable, kept contract. Everything else in the jar is obfuscated and internal. Do not call it.

Getting the jar

Download the latest release jar.

Install it into your local Maven repository:

mvn install:install-file -Dfile=SnAuction-<version>.jar -DgroupId=com.sn \
  -DartifactId=SnAuction -Dversion=<version> -Dpackaging=jar

Depend on it with provided scope. Never shade it.

Quick start

Declare the dependency in your plugin.yml:

depend: [SnAuction]      # or softdepend if optional

Resolve the API when you need it:

SnAuctionAPI api = SnAuctionProvider.get();
if (api != null) {
    // use the api
}

Resolve the reference when you need it. Do not cache it across a SnAuction reload. SnAuction registers the API once its market has loaded, a moment after it enables.

Money amounts

Every amount is an exact whole number in the currency's minor units. For a currency with 2 decimals, 1050 means 10.50. Use formatAmount to display one the way SnAuction does.

Master switch

API events can be disabled by the server owner with api-events.enabled: false in config.yml. The query service stays available either way.

Events

Cancellable events fire before the action, after SnAuction's own checks passed. Cancelling aborts it before any item or money moves. SnAuction sends no message then, so tell the player why yourself.

Event	Fired when	Cancel effect
`ListingCreateEvent`	A player is about to list items (held stack or sell menu)	Nothing is taken, no fee is charged
`ListingPurchaseEvent`	A player is about to buy a listing or buy an auction out	No money moves, the listing stays on the market
`BidPlaceEvent`	A player is about to place an accepted bid	No money moves, the auction is unchanged
`ListingCancelEvent`	A seller is about to take their own listing off the market	The listing stays on the market

A bid that reaches the buyout price fires ListingPurchaseEvent, not BidPlaceEvent. Staff removals fire no cancellable event.

Notification events fire after the change is saved. They cannot be cancelled.

Event	Fired when	Thread
`ListingPostedEvent`	A new listing went on the market	Main
`ListingSoldEvent`	A listing was sold; `getReason()` is `PURCHASE`, `BUYOUT` or `AUCTION_WON`	Main
`ListingEndedEvent`	A listing left the market unsold; `getReason()` is `EXPIRED`, `NO_BIDS`, `CANCELLED` or `REMOVED`	Main
`PayoutDeliveredEvent`	Money was credited to a player (sale proceeds or a refund)	Main

Listen like any Bukkit event:

@EventHandler
public void on(ListingPurchaseEvent event) {
    if (event.getTotal() > 1_000_000L) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("That purchase is too large today.");
    }
}

Event payloads are read-only. Listings arrive as ListingView, an immutable snapshot whose items are copies.

Query service

These methods read in-memory state. Call them on the main thread.

Method	Returns	Notes
`getListing(long id)`	`Optional<ListingView>`	Empty when no active listing has this id
`getActiveListings()`	`List<ListingView>`	Every active listing, newest first
`getListingsBySeller(UUID)`	`List<ListingView>`	One seller's active listings, newest first
`getWinningBids(UUID)`	`List<ListingView>`	Auctions the player leads, ending soonest first
`getActiveListingCount()`	`int`	Number of active listings
`getPendingPayout(UUID, String)`	`long`	What a claim would pay an online player in one currency; 0 when offline
`formatAmount(String, long)`	`String`	SnAuction's display of an amount; may contain `&` color codes
`getApiVersion()`	`String`	The API contract version

ListingView carries the id, type (FIXED or AUCTION), state, seller, currency, price, buyout, current bid, top bidder, bid count, creation and end times, and the items.

Versioning

Call getApiVersion() for the API contract version. It is independent of the plugin version. Additions bump the minor component. Existing members are never removed or changed; deprecated members keep working.