Kappapps SDK

Appearance

Channel, teams, stream, statuts et items ​

Données du channel qui exécute l'appli ou le widget. Services partagés appli + widget ; les scopes indiqués ne concernent que les applis (permissions).

kapp.channel : identité et réglages globaux ​

Lecture locale, sans appel réseau, resynchronisée automatiquement.

  • id : identifiant Kappapps du channel ; twitchUser : compte Twitch du streamer (login, display_name…).
  • bot : { login, display_name, profile_image_url } | null, voir chat.
  • preferences : réglages globaux du channel, dont language, command_symbol, currency_name, currency_symbol, stream_delay (secondes) et default_announce_tracks. getPreference(clé) lit une de ces valeurs.
  • events.on(kapp.channel.EVENTS.PREFERENCES_UPDATED, cb) reçoit le nouvel objet preferences ; EVENTS.LANGUAGE_UPDATED reçoit la nouvelle langue.

Ces réglages appartiennent au streamer et sont distincts des préférences d'une appli (kapp.preferences).

local_files_url est l’adresse HTTP du dossier local HUB, ou null si aucun n’est configuré (absente sur un ancien backend). Utiliser kapp.localFiles pour parcourir son index et lire ses fichiers depuis le PC de l’overlay.

kapp.teams : teams Kappapps du channel ​

await kapp.teams.get() renvoie les teams auxquelles le channel courant appartient, triées par nom puis ID. Chaque Team porte id, name et getChannels(). La liste est vide sans adhésion ; les invitations en attente ne sont pas incluses. Il s'agit des teams Kappapps, pas des teams Twitch.

await team.getChannels() renvoie les membres, channel courant inclus, triés par login puis ID de channel. Chaque TeamChannelData contient à plat :

  • les champs publics Twitch de /channels (broadcaster_id, broadcaster_login, broadcaster_name, title, game_id, game_name, etc.) ;
  • stream : objet public /streams, ou null hors live. Sa présence indique le live, même avec viewer_count: 0 ; voir les champs Twitch ;
  • channel_id : ID Kappapps du channel, distinct de l'ID Twitch broadcaster_id ;
  • role : 'owner', 'admin' ou 'member' dans cette team.

Les deux méthodes demandent le scope teams:read pour toutes les applis, même avec un ancien manifeste ; les widgets ne déclarent pas de scope. L'appartenance est contrôlée à chaque requête : une team supprimée ou inaccessible répond 404. Les adhésions et rôles sont relus à chaque appel, sans cache. Les données Twitch partagent le cache serveur de 30 secondes fixes par ID Twitch avec kapp.twitch.channel() et kapp.twitch.channels() ; une lecture ne prolonge pas ce délai. Aucun cache supplémentaire côté SDK.

Les comptes introuvables chez Twitch sont omis, ce qui peut produire une liste vide. Une erreur Twitch rejette la requête ; elle ne devient jamais un résultat hors live. Les teams dépassant 100 membres sont prises en charge sans pagination côté SDK.

js
const teams = await kapp.teams.get();
for (const team of teams) {
    const channels = await team.getChannels();
    const liveChannels = channels.filter(channel => channel.stream !== null);
    for (const channel of liveChannels) {
        console.log(team.name, channel.broadcaster_login, channel.role, channel.stream.viewer_count);
    }
}

kapp.stream : état du live ​

  • stream_id : identifiant du live en cours, null hors ligne. stream_started_at : début du live en secondes Unix, null hors ligne.
  • events.on(kapp.stream.EVENTS.STREAM_ONLINE, cb), STREAM_OFFLINE, STREAM_RESTARTED : cb({ id, started_at }) au démarrage ou au redémarrage, sans argument à l'arrêt. Les deux propriétés sont déjà à jour quand le callback est appelé.
  • await kapp.stream.getData() : événements mémorisés pendant le live courant. Appli : scope stream-data:read.

Renvoie les événements du live courant. Une appli doit déclarer le scope stream-data:read.

  • Les catégories twitch-follow, twitch-raid, twitch-subscribe, twitch-subscription-gift, twitch-subscription-message et twitch-infos contiennent des listes d'événements, vides lorsqu'aucun événement n'a été enregistré.
  • twitch-chatters est un objet indexé par pseudo affiché, avec {count, first, last} : nombre de messages et dates du premier/dernier message en millisecondes Unix.
  • twitch_stream.started_at est le dernier début de live connu en millisecondes Unix, ou null lorsqu'il est indisponible. Après un redémarrage du Core, cette date peut encore désigner le dernier live terminé : sa présence ne prouve pas que la chaîne est en direct.
  • Un événement du Core actuel porte type, ts (millisecondes Unix) et channel. Le Core historique utilise created_at (date ISO) et _created_at (millisecondes) ; ces métadonnées sont donc optionnelles dans les types communs.
  • Certains champs d'abonnement peuvent être null : streak_months, duration_months, cumulative_total. Vérifier ces valeurs avant un calcul.
js
const data = await kapp.stream.getData();
const raids = Array.isArray(data['twitch-raid']) ? data['twitch-raid'] : [];
const chatters = Object.entries(data['twitch-chatters'] ?? {})
    .sort(([, a], [, b]) => b.count - a.count)
    .slice(0, 3)
    .map(([name, stats]) => `${name} (${stats.count})`);
await kapp.chat.say(`${raids.length} raid(s) ; plus bavards : ${chatters.join(', ') || 'personne'}`);

Conditions de triggers liées au live ​

Le streamer peut ajouter une condition État du stream : En stream / Hors stream à un trigger ou à son groupe. Sans cette condition, les deux états sont autorisés. Elle se cumule avec les conditions de statut et de catégorie. Elle est ignorée pour ONLIVE, MANUAL_LAUNCH et CHDASHB, y compris lorsqu’elle vient d’un groupe. Les variantes de préférences et les règles de choix d’overlay ne proposent pas cette condition.

Un changement d’état live réévalue les exécutions : celles dont les conditions ne sont plus remplies sont fermées. Un PROCESSUS démarre dès que ses conditions sont remplies et que son overlay est disponible ; les autres triggers attendent leur événement habituel. Ces réglages se font dans la fiche du trigger ou du groupe.

kapp.statuses : statuts de stream du channel ​

Le streamer définit des statuts (par exemple « Pause », « Partie en cours ») et change le statut actif depuis Kappapps. Lecture locale :

  • status : statut actif { id, name, keyword }, ou null ; statuses : tous les statuts définis.
  • events.on(kapp.statuses.EVENTS.STATUS, cb) reçoit le nouveau statut actif ; EVENTS.STATUSES reçoit la nouvelle liste.

Une appli ne change pas le statut actif. Pour laisser le streamer en choisir un dans les réglages, utiliser le type de préférence status (types de préférences).

kapp.items : catalogue d'items du channel ​

  • await kapp.items.all() : items du catalogue ; await kapp.items.get(id) : un item. Prévoir un rejet si son identifiant est invalide.
  • Chaque item contient id, name, description, cost, exchangeable, identifier, icon_url, icon, quality, trigger et on_sale_quantity.
  • cost, identifier, icon_url, icon, quality et trigger peuvent être null. La qualité porte quality_string, quality_level, border_color et background_color. Un stock on_sale_quantity de -1 signifie illimité.
  • Prérequis : feature Items du channel, sinon 403 ; un item d'un autre channel répond aussi 403. Appli : scope channel-items:read.

Donner, retirer ou utiliser un item d'un viewer passe par users (items:manage).

Les entrées de user.addItem() et user.removeItem() continuent à accepter un objet contenant seulement id.