Kappapps SDK

Appearance

Développer une appli Kappapps — guide agent IA ​

Tu écris une appli Kappapps (jeu ou outil installable par un streamer sur son channel). Ce dossier contient ton appli ; le sous-dossier ai-knowledge/ est le corpus de référence du SDK, téléchargé depuis Kappapps. Lis-le avant de coder une API dont tu n'es pas sûr.

Par où commencer ​

  1. ai-knowledge/CHEATSHEET.md — mémo 1 page : contrat d'exécution, globaux, services, cycle de vie. À lire en premier.
  2. ai-knowledge/reference/ — doc détaillée par service / concept :
    • Concepts appli : lifecycle, preferences, data-storage, rewards, dynamic-triggers, persistent-triggers, launch-modes, app-to-app, i18n, plugins, prefs-panels, image-atlases.
    • Services SDK partagés : chat, emotes, medias, announces, textToSpeech, users, twitch, polls, ai, dom, events, overlay, services.
  3. ai-knowledge/examples/ — applis gold complètes (html + js + config commentés).
  4. ai-knowledge/PITFALLS.md + ai-knowledge/common-PITFALLS.md — pièges appli + pièges transverses.
  5. ai-knowledge/reference/vertical.md — adapter une app au vertical : déclaration, dimensions, placements, liberté de présentation et recette des deux formats.

Types & autocomplétion ​

  • Les types TypeScript du SDK sont dans app-sdk.d.ts (à la racine de l'app). Utilise-les pour l'autocomplétion / la vérification de signatures.
  • Doc en ligne : https://kappapps.app/docs/sdk/index.html ; typedefs V2 en ligne : https://kappapps.app/overlay/app.d.ts.

Règle d'or ​

N'invente jamais une signature. Avant d'utiliser une API incertaine, lis le fichier reference/ correspondant ou vérifie dans app-sdk.d.ts. Une signature inventée = une appli cassée.

Structure de fichiers d'une appli ​

index.html               point d'entrée : charge le SDK puis style.css + script.js (sur l'event AppliLoaded)
script.js                ta logique (IIFE async ; kapp/k déjà dispo)
style.css                styles de l'appli
infos.json               manifeste : launch-mode, scopes, services, overlay-formats, plugins, textset, viewers-optout
textset.js               i18n (window.textset → global text())
preferences.config.js    arbre des préférences streamer (compilé en config/preferences.config.json)
cli-config.json          config de build/upload (entries, exclusions et éventuelle racine runtime)
modules/                 modules sources éventuels (à regrouper dans l'artifact si l'app est compilée)
assets/                  ressources statiques
config/                  fichiers compilés en mode classique — NE PAS éditer à la main

Workspace source et artifact publié ​

  • Sans bloc runtime, ou avec "runtime": { "root": "." }, l'app reste en mode classique : le workspace entier est servi, comparé, sauvegardé et publié.
  • Une app avec build peut opter pour un artifact séparé, par exemple "runtime": { "root": "dist" }. La racine doit être un chemin relatif interne au workspace : jamais de chemin absolu ni de segment ...
  • Pour une app compilée, ce mode artifact avec dist/ est la pratique recommandée : publie un runtime autonome plutôt que les sources et fichiers de build (voir ai-knowledge/PITFALLS.md).
  • Dans ce mode, les sources (src/, package.json, configs Vite, .git, etc.) restent dans le workspace, tandis que seul dist/ est servi, comparé, sauvegardé, restauré et publié. Le ZIP contient donc directement index.html, jamais dist/index.html.
  • Ne modifie pas dist/ à la main. Modifie les sources puis lance explicitement le build du projet, par exemple npm run build ; le DEV HUB ne lance ni npm ni les commandes de cli-config.json automatiquement.
  • Les entrées de configCompiler restent relatives au workspace, mais leurs JSON sont écrits dans <runtime>/config. Le infos.json source reste à la racine du workspace et le HUB en copie la version courante dans le runtime avant diff, sync ou push.
  • En mode artifact, pull et restauration remplacent seulement le runtime et préservent les sources ainsi que .git. En mode classique, ils continuent à remplacer le dossier complet.

Workflow dev (via le Kappapps DEV HUB) ​

  • Les outils sont exposés par l'app de bureau Kappapps DEV HUB via son endpoint MCP local : http://localhost:7581/mcp.
  • pull récupère l'artifact publié depuis Kappapps ; push envoie le runtime effectif (. en classique, dist ou autre racine configurée en mode artifact).
  • transpile compile par exemple preferences.config.js → <runtime>/config/preferences.config.json. watch le fait à chaque changement des sources configurées.
  • serve sert le runtime effectif en local + enregistre l'URL localhost auprès de Kappapps pour tester en direct.
  • Pour toute validation visuelle, appelle prepare_preview avec une surface explicite : overlay, external, viewers_plugin ou streamer_plugin. Ouvre immédiatement la preview_url dans ton propre navigateur/Playwright, au viewport indiqué, puis cible frame.selector / frame.origin. C'est le chemin normal.
  • Les previews plugins chargent un shell Kappapps dédié avec le bridge, les JWT et les sockets réels du channel DEV. Ne remplace jamais cette URL par l'iframe localhost brute et ne cherche pas à ouvrir le Dashboard.
  • Le ticket d'amorçage est one-shot et expire en deux minutes ; après redirection, l'URL propre est rechargeable pendant une session DEV courte et révocable. Ne logge, ne publie et ne versionne jamais la preview_url.
  • Si le navigateur ne peut réellement pas atteindre la page ou son iframe localhost, utilise seulement alors open_managed_preview avec le context_id, puis les outils snapshot_app, capture_app_screenshot, interact_app, evaluate_app, wait_for_app, resize_app et read_app_console du DEV HUB.
  • download_sdk_typedefs met à jour app-sdk.d.ts ; download_app_knowledge met à jour ce corpus ai-knowledge/.
  • create_image_atlas analyse ou crée un atlas multi-planches pour réduire les requêtes ; compact_image_assets reste un alias historique (voir reference/image-atlases.md).
  • ⚠️ Migration : ces outils vivaient avant dans le HUB streamer (http://localhost:7580/mcp). Si ta config MCP pointe encore sur le port 7580, mets-la à jour : claude mcp add --transport http kappapps-hub http://localhost:7581/mcp (le DEV HUB se télécharge depuis le portail développeur).

Sources de vérité (pour qui maintient ce corpus) ​

  • Surface réelle : assets/overlay/src/appli.ts, src/kapp/Appli.ts + src/kapp/App.ts, src/services/*, src/models/*.
  • Applis réelles de référence : apps/_bootstrap (squelette), apps/sdk-smoke-test (couverture SDK), apps/aiquizz, apps/currency-manager.