Triggers persistants de préférences

Une préférence type: 'trigger' matérialise un trigger durable de l'installation. Le streamer choisit sa configuration et garde la main sur son activation. Le trigger survit à la fermeture de l'app, mais ne la lance jamais : une activation appelle son callback uniquement si une exécution de cette app est déjà ouverte. À l'arrêt, l'activation est refusée et les paiements remboursables sont annulés.

// preferences.config.js
module.exports = {
    viewerAction: {
        type: 'trigger',
        label: 'Action des viewers',
        required: false,
        wuOptions: {
            types: ['CHATCMD', 'PLDASHB', 'CHANAPI'],
            arguments: [
                {name: 'Montant', key: 'amount', type: 'int', required: true},
            ],
        },
        default: {type: 'CHATCMD', title: 'Action', keyword: 'action'},
    },
};

// script.js, après AppliLoaded. Scope infos.json : triggers:manage.
const unsubscribe = k.triggers.onTrigger(
    k.preferences.get('viewerAction'),
    async (trigger, request, resolve, reject) => {
        if (request.args.amount < 1) {
            await reject('Le montant doit être positif.');
            return;
        }
        // Traiter l'action, puis confirmer sa demande.
        await resolve();
    },
);
// unsubscribe() retire seulement ce callback local.

wuOptions.types est une liste optionnelle non vide, sans doublon. Sans restriction, les types disponibles sont CHATCMD, KEYWORD, REGEX, BITSCMD, BITS, CHDASHB, PLDASHB, INTERVAL, TWREW et CHANAPI. Les neuf premiers réutilisent les champs décrits dans preferences.md. CHANAPI possède type et title ; son lien stable est copiable dans l'interface streamer et n'expose jamais la clé API à l'app. Il nécessite la fonctionnalité API Channel ; TWREW nécessite Twitch Rewards et suit le quota des récompenses durables.

La valeur hydratée est un TriggerPreference : id stable, _ref de préférence, config normalisée ou null, enabled (choix du streamer), active (configuration effective) et arguments. Même non configurée, une préférence existante conserve sa référence et accepte un callback anticipé. Un aperçu non synchronisé peut avoir id: null ; l'enregistrement est alors sans effet.

Les variantes modifient la configuration effective en conservant l'identité et le choix d'activation. Les collections utilisent l'UUID de chaque entrée : un tri ne change pas les callbacks. Enregistrer les nouvelles entrées sur l'événement k.preferences.EVENTS.UPDATED. Réenregistrer le même id remplace son callback ; un ancien désabonnement ne retire pas le nouveau callback.

Chaque préférence définit ses propres arguments dans wuOptions.arguments, avec les types usuels (Player, int, bool, string, long_string, tts_input, string_list). Ils arrivent dans request.args, avec _raw et _config ; les Player deviennent des User. Ils sont indépendants des arguments de lancement. Pour typer précisément le callback, annoter la préférence avec TriggerPreference<typeof schema>.

Une demande se confirme par resolve() ou s'annule par reject(reason?). Un callback absent ou qui lève une exception entraîne un rejet. La fermeture de l'exécution annule ses demandes encore ouvertes. Une livraison dupliquée ne réexécute pas le callback ; la finalisation est idempotente côté serveur.

L'app ne crée, n'édite, n'active et ne supprime aucun de ces triggers, y compris via preferences.set sur un parent ou une collection. Le streamer les configure depuis les préférences ; leur première configuration est active par défaut. Une suppression définitive, une migration supprimant la préférence ou une désinstallation nettoie les ressources associées.

Les dynamic triggers gardent leur contrat : création par le SDK, durée de vie limitée à l'exécution, schéma d'arguments fourni par le code.