Developer API

The API is enabled by default under integrations.developer-api. It is registered with Bukkit's ServicesManager, has no hard dependency requirement and is removed cleanly when ReferralTrack is disabled. A config reload immediately registers or unregisters it.

java

RegisteredServiceProvider<ReferralTrackApi> registration =
        Bukkit.getServicesManager().getRegistration(ReferralTrackApi.class);
ReferralTrackApi api = registration == null ? null : registration.getProvider();

Add ReferralTrack as softdepend or depend in the consuming plugin. Do not shade or relocate ReferralTrack API classes. Check api.isReady() before queries. findReferral, countValidatedInvites and topReferrers are read-only and return CompletableFuture; their callbacks do not run on the Bukkit main/entity thread. The DTO records are immutable and do not expose internal database row IDs or mutable configuration objects.

Events #

ReferralPreClaimEvent is synchronous and cancellable. It fires after ReferralTrack's own command, permission, cooldown, ignore and claim-window guards, but before any asynchronous lookup or database write. Cancellation prevents the claim and shows a localized generic integration-blocked message. The submitted strings are read-only so listeners cannot bypass ReferralTrack validation.

ReferralClaimResultEvent is asynchronous and non-cancellable. It reports every completed manager result, including rejection/error outcomes, source/campaign identity, inviter UUID and pending state. Its listener must not access Bukkit player/world/inventory APIs directly; schedule such work through the consuming plugin's Paper/Folia-compatible scheduler. Do not award money from this notification: ReferralTrack's durable reward ledger remains the source of truth.

Both events have independent config switches. Disabling the developer API disables both events.