API para desarrolladores

La API está activada por defecto en integrations.developer-api. Se registra en el ServicesManager de Bukkit, no exige ninguna dependencia obligatoria y se elimina limpiamente cuando ReferralTrack se desactiva. Una recarga de la configuración la registra o la elimina de inmediato.

java

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

Añade ReferralTrack como softdepend o depend en el plugin que lo consume. No empaquetes con shade ni reubiques las clases de la API de ReferralTrack. Comprueba api.isReady() antes de hacer consultas. findReferral, countValidatedInvites y topReferrers son de solo lectura y devuelven CompletableFuture; sus callbacks no se ejecutan en el hilo principal/de entidad de Bukkit. Los registros DTO son inmutables y no exponen los ID internos de filas de la base de datos ni objetos de configuración mutables.

Eventos #

ReferralPreClaimEvent es síncrono y cancelable. Se lanza después de las protecciones propias de ReferralTrack de comando, permiso, tiempo de espera, ignorar y ventana de reclamación, pero antes de cualquier consulta asíncrona o escritura en la base de datos. La cancelación impide la reclamación y muestra un mensaje localizado genérico de bloqueo por integración. Las cadenas enviadas son de solo lectura para que los listeners no puedan eludir la validación de ReferralTrack.

ReferralClaimResultEvent es asíncrono y no cancelable. Informa de cada resultado completado del gestor, incluidos los resultados de rechazo/error, la identidad del origen/campaña, el UUID del invitador y el estado pendiente. Su listener no debe acceder directamente a las API de jugador/mundo/inventario de Bukkit; programa ese trabajo mediante el planificador compatible con Paper/Folia del plugin que lo consume. No concedas dinero a partir de esta notificación: el libro de recompensas duradero de ReferralTrack sigue siendo la fuente de verdad.

Ambos eventos tienen interruptores de configuración independientes. Desactivar la API para desarrolladores desactiva los dos eventos.