Client d'interface

createInterfaceClient est le client de navigateur utilisé par les pages hébergées et par le lanceur. Il n'exige aucune clé d'API : il adresse une interface par son identifiant et conserve la session du visiteur dans un cookie (credentials: "include"). L'origine de votre site doit figurer dans les Origines autorisées de l'interface.

import { createInterfaceClient, ScrydonInterfaceError } from "@scrydon/sdk/interfaces";

const chat = createInterfaceClient({
  baseUrl: "https://scrydon.example.com/agentic",
  identifier: "<identifier>",
});

const page = await chat.getPage();          // the experience and auth mode
await chat.authenticate("password");        // only for a password-protected interface
const transcript = await chat.getSession(); // the visitor's earlier messages

const controller = new AbortController();
try {
  for await (const event of chat.sendMessage("When are you open?", { signal: controller.signal })) {
    if (event.type === "message.delta") render(event.text);
  }
} catch (error) {
  if (error instanceof ScrydonInterfaceError) showNotice(error.code, error.retryAfterSeconds);
}

// A Form interface has its own identifier and its own client.
const form = createInterfaceClient({
  baseUrl: "https://scrydon.example.com/agentic",
  identifier: "<form identifier>",
});
const result = await form.submitForm({ email: "ada@example.com" });

getPage() répond ready (avec l'expérience et l'indication qu'un mot de passe est requis), locked tant que authenticate n'a pas réussi, ou unavailable. getSession() renvoie les messages du visiteur et turnsRemaining ; il ne crée aucune conversation. submitForm(values) renvoie { status: "replied", message } lorsqu'un Form Reply a répondu dans le délai de réponse du formulaire, sinon { status: "submitted" }.

Événements

Quitter la boucle plus tôt annule le flux. Le serveur envoie un signal de présence (heartbeat) toutes les INTERFACE_HEARTBEAT_INTERVAL_MS (5 secondes). Une réponse qui reste silencieuse pendant trois intervalles (15 secondes), se termine ou s'interrompt sans événement final est remise sous la forme d'un error avec code: "FAILED", afin que votre interface n'attende jamais une réponse qui ne viendra pas.

Rien ne borne la requête elle-même avant le début de la réponse. Passez signal à sendMessage pour la borner ; interrompre le signal rejette avec la raison de l'interruption.

Erreurs

Un refus avant l'ouverture du flux lève ScrydonInterfaceError avec un code stable (RATE_LIMITED, TURN_LIMIT, BUDGET_EXHAUSTED, UNAVAILABLE, UNAUTHORIZED) et retryAfterSeconds, renseigné chaque fois que la réponse porte un en-tête Retry-After : RATE_LIMITED, BUDGET_EXHAUSTED, et un UNAVAILABLE provenant de l'indisponibilité du limiteur de débit ou du budget quotidien. Il vaut null sinon. L'erreur porte aussi le status HTTP (0 lorsqu'aucune réponse n'a pu être lue). Voir le déclencheur Chat.

Le client ajoute ses propres codes, listés dans INTERFACE_CLIENT_ERROR_CODES : NOT_FOUND, INVALID_INPUT (un envoi de formulaire dont les champs ne conviennent pas ; details les liste), BAD_REQUEST, PAYLOAD_TOO_LARGE, ORIGIN_NOT_ALLOWED, NETWORK_ERROR et UNEXPECTED_RESPONSE.

• NETWORK_ERROR depuis une autre origine. Une page dont l'origine ne figure pas dans les Origines autorisées de l'interface voit NETWORK_ERROR, et non ORIGIN_NOT_ALLOWED : le refus ne comporte aucune autorisation inter-origines, donc le navigateur le masque. Vérifiez d'abord les origines autorisées. Le même code couvre aussi une vraie panne réseau et un identifiant inconnu : réessayez donc un nombre borné de fois, avec un délai croissant.
• Ne renvoyez pas un formulaire automatiquement. Après un 502 ou un 504, ou un NETWORK_ERROR, submitForm a peut-être déjà démarré une exécution. Demandez au visiteur avant de renvoyer les valeurs.

Un exemple exécutable se trouve dans examples/interface-chat dans le dépôt Scrydon.