kapp.emotes

Accéder aux emotes et badges Twitch disponibles sur le channel (globaux + spécifiques au channel, BetterTTV), et résoudre les badges portés par un viewer en images affichables à l'écran.

Service partagé appli + widget : l'API est identique. Seul le wrapper d'exécution diffère (côté widget : window.executeWidgetFunction ; côté appli : script.js après l'event AppliLoaded).

Quand l'utiliser (vs alternative)

• kapp.emotes.getBadges(ev) : afficher les badges d'un viewer (abonné tier 1/2/3 avec palier 1 mois, 2 mois…, modo, VIP, founder…) à partir d'un message chat.
• kapp.emotes.get() : accéder au set complet (emotes Twitch / BTTV, jeux de badges) pour un rendu custom.
• Les emotes d'un message se rendent déjà via ev.getMessageAsHtml() (voir chat.md) — pas besoin de ce service pour ça.

Méthodes

• get(): Promise<EmotesSet> — set complet { emotes_global, emotes_channel, badges_global, badges_channel, emotes_bttv_global, emotes_bttv_channel }. async. Chaque appel fetch une donnée fraîche (endpoint rate-limité) : ne l'appelle PAS à chaque message — pour les badges, utilise getBadge/getBadges qui cachent en interne.
• getBadge(set_id, version): Promise<ResolvedBadge|null> — résout un badge (ex. 'subscriber', '3012') en { set_id, id, title, description, image_url_1x, image_url_2x, image_url_4x, … }. Les badges du channel (paliers d'abo custom, bits) sont prioritaires sur les globaux, comme sur Twitch. null si inconnu. async. Sets cachés en interne pour toute l'exécution → utilisable à chaque message sans coût réseau.
• getBadges(source): Promise<ResolvedBadge[]> — résout d'un coup les badges d'un message : source = le ChatEvent directement, ou une liste {set_id, version} (= ev.getBadges()). Ordre d'affichage Twitch préservé, badges inconnus ignorés. async. Même cache interne que getBadge.

Côté ChatEvent (sync, voir chat.md) : ev.getBadges() (badges portés, bruts), ev.isSubscriber(), ev.getSubscriberMonths() (mois d'abo exacts, via badge-info), ev.getSubscriberTier() (1|2|3, ou null si indéterminable).

Exemple (V2, exécutable)

// Affiche badges + infos d'abo de chaque abonné qui parle
kapp.chat.onMessage(async (user, ev) => {
    if (!ev.isSubscriber()) return;
    const months = ev.getSubscriberMonths();          // mois exacts (badge-info)
    const tier   = ev.getSubscriberTier();            // 1|2|3, ou null (ex. founder)
    const badges = await kapp.emotes.getBadges(ev);   // badges → images

    const row = document.createElement('div');
    row.innerHTML = badges.map(b => `<img src="${b.image_url_2x}" alt="${b.title}" width="24" height="24">`).join('')
        + ` <b>${user.display_name}</b> — sub T${tier ?? '?'} depuis ${months} mois`;
    document.body.prepend(row);
});

Pièges

• Les badges sont une donnée par message (tags IRC Twitch) : ils ne sont PAS sur l'objet User. Pas de message reçu = pas de badges connus pour ce viewer. Pour vérifier uniquement l'abonnement actuel d'un User, même sans message, utilise await user.getSubscriptionStatus() (appel Twitch live, voir users.md).
• getSubscriberTier() peut être null alors que isSubscriber() est true : un founder qui affiche son badge founder ne porte pas de badge subscriber.
• Le badge d'abo affiché est un palier (1, 2, 3, 6, 9 mois…), pas la durée réelle : la durée exacte est ev.getSubscriberMonths().
• get() fetch à chaque appel et l'endpoint est rate-limité : dans un onMessage, passe par getBadge/getBadges (cache interne), jamais par get() en boucle.
• badges_channel ne contient que les badges custom du streamer ; getBadge/getBadges gèrent déjà le fallback vers les badges globaux — ne réimplémente pas la résolution à la main.