kapp.rewards (récompenses)

Marquer des viewers comme gagnants/perdants au fil de la partie ; les récompenses sont envoyées au serveur au finish(). Scope d'appli : rewards:distrib.

Ce que l'appli décide, et ce qu'elle ne décide pas

• L'appli décide qui a gagné ou perdu. Elle ne fixe pas les gains : le serveur transmet la liste aux services de récompense configurés sur le channel (monnaie, items, points), qui appliquent leurs propres réglages.
• Une distribution accepte au plus 100 viewers distincts, gagnants et perdants compris. Au-delà, la requête est refusée et finish() rejette. Borne la participation ou ne marque que les viewers utiles.
• Les viewers ayant interdit l'appli sont retirés de la distribution par le serveur.
• Un succès signifie que la demande a été acceptée. Si un service de récompense du channel est indisponible, le serveur passe aux suivants sans le signaler : un finish() réussi ne prouve pas que chaque gain a été crédité.

Méthodes

• kapp.rewards.winner(user: User): void : marque un viewer gagnant (accumulé localement).
• kapp.rewards.loser(user: User): void : marque un viewer perdant (accumulé localement).
• await kapp.rewards.sendRewards(): Promise<void> : envoie winners (valeur 1) et losers (valeur 0). Appelé automatiquement par kapp.finish() avant la clôture. Réinitialise les listes locales immédiatement (même si la requête échoue).

Pattern

(async function () {
    // ... déroulé du jeu ...
    kapp.rewards.winner(gagnant);
    perdants.forEach(u => kapp.rewards.loser(u));

    await kapp.finish();   // sendRewards() est déclenché ici
})();

Pièges

• Rien n'est envoyé tant que finish() (donc sendRewards()) n'a pas tourné. Un abort() abandonne les rewards accumulées.
• Si un viewer est marqué winner et loser, loser l'emporte quel que soit l'ordre des appels : l'envoi construit les gagnants, puis applique les perdants.
• Une erreur de distribution rejette finish() avant les hooks de sortie. Les listes sont déjà vidées et le résultat distant peut être incertain : ne les reconstruis pas pour un renvoi automatique. Voir fermeture et gestion des erreurs.
• winner / loser prennent un objet User (récupéré via kapp.users.get(...) ou kapp.triggerRequest.setter selon le contexte).
• Pour créditer un montant précis décidé par l'appli, ce n'est pas rewards : voir les actions monnaie de users (currency:manage).