Documentation

Les SDK officiels

Six SDK écrits sur le même contrat : clés, sessions visiteur, réponses en flux, erreurs typées et nouvelles tentatives.

Six SDK officiels, écrits sur le même contrat : mêmes méthodes, mêmes erreurs, mêmes règles de nouvelles tentatives, dans les idiomes de chaque langage. Choisissez le vôtre.

Votre projet	SDK	Installation
Node.js, Next.js, Nuxt, navigateur, Deno, Bun	`@valais-connect/gaspard`	`npm install @valais-connect/gaspard`
Laravel, Symfony, PHP 8.2+	`valais-connect/gaspard`	`composer require valais-connect/gaspard`
Site WordPress	Extension « Gaspard Assistant »	Téléverser le zip de l’extension
ASP.NET Core, .NET 8+	`ValaisConnect.Gaspard`	`dotnet add package ValaisConnect.Gaspard`
Flutter (Android, iOS, web, desktop), Dart	`valais_connect_gaspard`	`flutter pub add valais_connect_gaspard`
Android natif, Kotlin, Spring, Ktor	`ch.valais-connect:gaspard`	`implementation("ch.valais-connect:gaspard:1.0.0")`
N’importe quel site HTML	Le widget, sans SDK	Deux lignes de HTML

Ce que chaque SDK fait pour vous #

Les clés : apiKey (serveur, Authorization: Bearer) ou publishableKey (widget, X-Gaspard-Key), exactement l’une des deux ; une clé secrète utilisée là où elle serait visible est refusée.
Les sessions visiteur : privacyNotice(), puis openSession({consent: true}) garde le jeton vst_… et l’envoie ensuite ; setVisitorToken() le restaure au prochain lancement.
Vos utilisateurs : forEndUser(id) envoie X-End-User (clé serveur).
Le flux : askStream() renvoie les morceaux delta puis la réponse complète, sous la forme idiomatique (itérable asynchrone, Generator, IAsyncEnumerable, Flow, Stream).
Les erreurs : une seule exception (GaspardError / GaspardException) avec status, code, message, requestId et retryAfter.
Les nouvelles tentatives : jusqu’à 2 par défaut, sur 503 assistant_busy, 429 rate_limited et, pour GET et DELETE, les erreurs réseau ; en respectant Retry-After (au-delà de 30 s, l’erreur est levée).

Les méthodes communes #

Méthode	Route
`privacyNotice(locale)`	`GET /privacy-notice`
`openSession(consent, locale, allowTraining)`	`POST /sessions` (clé widget)
`startConversation(locale, page?)`	`POST /gaspard/conversations`
`ask(conversationId, text, firstName?)`	`POST /gaspard/conversations/{id}/messages`
`askStream(conversationId, text, firstName?)`	idem, en flux
`conversation(conversationId)`	`GET /gaspard/conversations/{id}`
`feedback(messageId, rating, comment?)`	`POST /gaspard/messages/{id}/feedback`
`searchKnowledge(query, limit, topics?)`	`POST /knowledge/search`
`consent()` · `giveConsent()` · `withdrawConsent()`	`/visitors/me/consent`
`exportData()` · `eraseData()`	`GET /visitors/me/data` · `DELETE /visitors/me`

Les noms suivent les conventions de chaque langage (StartConversationAsync en C#…). Les champs inconnus renvoyés par le serveur sont ignorés : une évolution additive de l’API ne casse pas votre application.

Configuration commune #

Option	Défaut	Rôle
`baseUrl`	`https://hubmix.dealmood-solutions.com`	Hôte du service ; le SDK ajoute `/v1/public`
`apiKey` / `publishableKey`	—	L’une des deux, obligatoire
`origin`	—	Clé widget hors navigateur : une origine déclarée
`endUser`	—	Clé serveur : l’identifiant de votre utilisateur
`timeout`	60 s	Par requête ; un flux n’a pas de délai total
`maxRetries`	2	`0` désactive les nouvelles tentatives
`userAgent`	`gaspard-<langage>/1.0.0`	Hors navigateur