Être lancée par kapp.apps ou laisser le streamer choisir une cible

Le contrat partagé des lanceurs fait autorité pour run, runApp, runWidget, les listes, les résultats, les raisons d'échec et les délais ; arguments détaille les conversions. Cette fiche ne couvre que ce qui est propre à une appli : la préférence runTarget, le rôle de cible, run-output et kind. Un widget n'a pas ce manifeste.

À ne pas confondre avec kapp.services.call() : call appelle une fonction d'une appli déjà lancée ; kapp.apps lance une cible dédiée et résout avec la donnée passée à son finish(result). Pour le premier cas, voir services.

Laisser le streamer choisir la cible : préférence runTarget

Déclare un item runTarget dans preferences.config.js : le dashboard affiche un sélecteur des applis installées compatibles avec l’overlay et des widgets du channel. La valeur lue est directement une cible pour kapp.apps.run.

// preferences.config.js
cible: {
    type: 'runTarget',
    label: { en: 'Target to run', fr: 'Cible à lancer' },
},
cibleApp: {                              // restreint aux applis
    type: 'runTarget',
    label: { en: 'App to run', fr: 'Appli à lancer' },
    wuOptions: { targets: 'app' },
},
ciblesBonus: {                           // plusieurs cibles → collection
    type: 'collection',
    label: { en: 'Bonus targets', fr: 'Cibles bonus' },
    collectionItems: { type: 'runTarget' },
},

// script.js : la cible vient des préférences, pas du code
const cible = kapp.preferences.get('cible');   // { type: 'app', slug } | { type: 'widget', id } | null
if (cible) {
    const r = await kapp.apps.run(cible, { mise: 100 });
    if (r.resolved) console.log(r.data);
}

• Valeur hydratée : { type: 'app', slug }, { type: 'widget', id } ou null si rien n'est choisi : gère toujours ce cas.
• wuOptions.targets: 'app' | 'widget' restreint le sélecteur à un type.
• default est interdit (un ID de widget n'est pas portable) et l'item n'est jamais required.
• En collection, la valeur est un tableau de cibles : for (const t of cibles) await kapp.apps.run(t, args).
• Un widget désactivé reste sélectionnable ; run répond alors { resolved: false, reason: 'disabled' }.
• kapp.preferences.set() accepte le même objet cible pour un chemin runTarget.

Être la cible : déclarer ses arguments et renvoyer un résultat

Toute appli compatible avec l’overlay peut être lancée par runApp, y compris une ancienne backtask. Pour recevoir des args, elle les déclare dans config/trigger_arguments.config.json (même schéma qu'un trigger ; dans un projet compilé, depuis une entrée de configCompiler, voir l'exemple compilé). Les clés non déclarées sont ignorées. Les valeurs arrivent typées dans kapp.arguments.

[
  { "name": "Question", "key": "question", "type": "string", "required": true }
]

(async function () {
    const question = kapp.arguments.question;
    kapp.display();
    const color = await askViewer(question);      // ta logique (UI, vote, interaction…)
    await kapp.finish({ color });                 // remonte comme { resolved: true, data: { color } }
})();

• finish(result) : toute valeur JSON. finish() sans valeur donne no_result ; abort('raison') donne reason: 'raison'.
• result n'a d'effet que si l'appli a été lancée par kapp.apps.
• Une seule instance de l'appli à la fois : un second lancement reçoit busy.
• Sans finish() ni abort(), l’appelant attend jusqu’à son délai. L’expiration de ce délai ne ferme pas l’appli lancée.

Listes de valeurs. Le type d'argument string_list (string[]) reçoit un vrai tableau quand l'appelant est une appli ou un widget. Depuis le chat ou une récompense, la saisie est découpée par separator (défaut ,) : !pick a, b, c donne ['a', 'b', 'c'].

[
  { "name": "Options", "key": "options", "type": "string_list", "separator": ",", "required": true }
]

Déclarer le format de sortie : run-output

Dans infos.json, une appli peut déclarer le type de son result, validé au finish (sinon invalid_output). Types : string, string_list, int, bool, object (JSON libre), void.

{ "run-output": { "type": "string", "description": "La valeur choisie" } }

Contrats standards : kind

Une appli peut adopter un kind, contrat d'entrée et de sortie prédéfini, via "kind" dans infos.json. Le kind prime sur les déclarations de fichiers.

kind	Entrée	Sortie
pick-string	options (string_list, requis)	string

// infos.json de la cible
{ "kind": "pick-string" }

// script.js de la cible
(async function () {
    const opts = kapp.arguments.options;            // string[] fourni par le kind
    await kapp.finish(opts[Math.floor(Math.random() * opts.length)]);
})();

Un appelant trouve ces applis avec listApps() et le champ kind : voir l'exemple de découverte.

Pièges

• L'appli appelante déclare apps:run pour toutes les listes et tous les lancements.
• Ne code pas en dur un ID de widget : listWidgets() ou préférence runTarget.
• Un timeout côté appelant ne prouve pas que la cible n'a rien fait : ne relance pas automatiquement une action à effet de bord.