Exposer des services (avancé)

Une appli ou un widget peut exposer une capacité nommée. La déclaration décrit cette capacité ; le contrat commun d’implémentation et d’appel explique comment la rendre disponible, découvrir son nom et obtenir une réponse. Une alerte autonome n’a pas besoin de service.

kapp.services (alias k.services) est l'API publique commune aux applis et widgets. Ses méthodes implements, create, get, call et remove sont décrites dans les types distribués du SDK.

Forme d'un service

Champ	Rôle
name	nom du service (identifiant lisible)
description	description fonctionnelle (obligatoire, lisible par le streamer)
description_for_ai	description orientée IA : comment/quand l'appeler (optionnel mais recommandé)
granted_role	rôle Kappapps minimum de la personne pour laquelle l'IA appelle le service
domains	contextes où le service est exposé (ex. app, widget)

granted_role — la permission

granted_role contrôle le rôle de la personne pour laquelle le bot ou l'assistant IA appelle le service. L'identité est établie par la plateforme ; un argument userId fourni au callback ne prouve pas cette identité.

Valeur	Personnes autorisées via l'IA
absent, null ou viewer	tout le monde
animator	animateurs, administrateurs et propriétaire du channel
admin	administrateurs et propriétaire du channel
superadmin	propriétaire du channel uniquement

viewer est un alias de null propre aux services. mod et streamer ne sont pas des valeurs acceptées ; ces rôles sont ceux de Kappapps, pas ceux de Twitch.

Les appels directs appli/widget → service utilisent les scopes et domains, sans contrôler un rôle utilisateur. Une annonce configurée par le streamer suit également son parcours backend. Pour réserver une action à l'IA, choisir domains: ["aibot"] ; granted_role ne suffit pas à restreindre les autres domaines. Proposer le rôle minimum adapté à la sensibilité de l'action.

Quand proposer un service (vs ne pas le faire)

• ✅ « ce code doit pouvoir être piloté par mon autre appli / par l'IA » → expose un service nommé.
• ✅ « expose une action réutilisable (ex. "ajouter des points") » → service + description_for_ai.
• ❌ une simple alerte ou un outil autonome → aucun service.

Côté widget (blueprint)

Renseigne services: [{ name, description, description_for_ai, granted_role, domains }] dans set_blueprint uniquement si pertinent. Après soumission acceptée dans le dashboard, la liste est synchronisée automatiquement : les services absents sont retirés. Seul un nouveau déclencheur attend l'activation explicite du streamer. L'outil widget read_sdk_doc {service: "services"} fournit le contrat de configuration et de disponibilité propre à ce parcours.

Côté appli

Les services exposés sont déclarés dans infos.json ("services": [...]) et matérialisés à l'installation de l'appli sur un channel.

Extrait de manifeste du fournisseur d’exemple, à fusionner avec le manifeste courant :

{
  "scopes": ["app-service:create"],
  "services": [{
    "name": "status",
    "description": "Lire la disponibilité de cette exécution",
    "description_for_ai": null,
    "domains": ["app", "widget"],
    "granted_role": null,
    "args": []
  }]
}

La déclaration persistée n’est pas un callback enregistré. Dans le script métier chargé par le bootstrap, exécuter le fournisseur de service-calls, puis tester son appel et son retrait. Laisser cette appli ouverte pour que son service reste disponible.

Pour proposer le démarrage automatique de ce fournisseur à l'installation, déclarer un default PROCESSUS selon le contrat des déclencheurs d'appli.

Le consommateur est une autre appli du même channel. Il n’a pas à recopier la déclaration du fournisseur dans ses propres services. Pour l’exemple de découverte puis d’appel, fusionner ces scopes avec ses besoins existants :

{
  "scopes": ["app-service:read", "app-service:call"]
}

Les deux applis doivent être lancées et le fournisseur doit avoir terminé son implements. En développement, compiler les configurations et vérifier le serveur local de chaque appli ; démarrer une seule session ne prépare pas l’autre projet. Suivre la recette à deux applis.

Chaque argument de service porte name, type, description, required et éventuellement description_for_ai. Le callback contrôle les valeurs reçues. Un type de service standard reconnu peut imposer son schéma ; ne pas le mélanger avec un contrat libre. Ce schéma est distinct de trigger_arguments.