API para desenvolvedores

A API vem ativada por padrão em integrations.developer-api. Ela é registrada no ServicesManager do Bukkit, não tem requisito de dependência obrigatória e é removida de forma limpa quando o ReferralTrack é desativado. Uma recarga da configuração a registra ou remove imediatamente.

java

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

Adicione o ReferralTrack como softdepend ou depend no plugin que o consome. Não empacote com shade nem realoque as classes da API do ReferralTrack. Verifique api.isReady() antes de fazer consultas. findReferral, countValidatedInvites e topReferrers são somente leitura e retornam CompletableFuture; seus callbacks não são executados na thread principal/de entidade do Bukkit. Os registros DTO são imutáveis e não expõem IDs internos de linhas do banco de dados nem objetos de configuração mutáveis.

Eventos #

ReferralPreClaimEvent é síncrono e cancelável. Ele é disparado depois das proteções próprias do ReferralTrack de comando, permissão, tempo de espera, ignorar e janela de resgate, mas antes de qualquer consulta assíncrona ou gravação no banco de dados. O cancelamento impede o resgate e mostra uma mensagem localizada genérica de bloqueio por integração. As strings enviadas são somente leitura para que os listeners não possam contornar a validação do ReferralTrack.

ReferralClaimResultEvent é assíncrono e não cancelável. Ele informa cada resultado concluído do gerenciador, incluindo os resultados de rejeição/erro, a identidade da origem/campanha, o UUID do convidador e o estado pendente. O listener dele não deve acessar diretamente as APIs de jogador/mundo/inventário do Bukkit; agende esse trabalho pelo agendador compatível com Paper/Folia do plugin que o consome. Não conceda dinheiro a partir desta notificação: o livro-razão durável de recompensas do ReferralTrack continua sendo a fonte da verdade.

Os dois eventos têm chaves de configuração independentes. Desativar a API para desenvolvedores desativa ambos.