SDK JavaScript

npm install @pacerelle/sdk

Nécessite Node.js 20+. Le paquet est un module ES et fournit ses propres types TypeScript.

createNodeAgentGatewayClient

Crée un client configuré pour Node.js (implémentation WebSocket et module de chiffrement inclus).

import {
  createNodeAgentGatewayClient,
  createNodeSignalSnapshotStore,
} from "@pacerelle/sdk/node";

const state = createNodeSignalSnapshotStore(process.env.PACERELLE_AGENT_ID);

const client = createNodeAgentGatewayClient({
  agentId: process.env.PACERELLE_AGENT_ID,
  token: process.env.PACERELLE_AGENT_TOKEN,
  e2ee: true,
  signalSnapshot: state.signalSnapshot,
  onSignalSnapshot: state.onSignalSnapshot,
});

createNodeSignalSnapshotStore

createNodeSignalSnapshotStore(agentId: string, options?: { file?: string; dir?: string })

Renvoie { file, signalSnapshot, onSignalSnapshot }, adossé à un fichier écrit de façon atomique avec les permissions 0600. Le chemin par défaut est ~/.pacerelle/agents/<agentId>.signal.b64, modifiable avec options.file ou les variables d'environnement PACERELLE_AGENT_SIGNAL_STATE_FILE / PACERELLE_AGENT_SIGNAL_STATE_DIR.

Connexion

connect()

connect(): Promise<void>

Publie les clés publiques de l'agent (avec e2ee), ouvre le WebSocket et se résout une fois la connexion ouverte. Rejette si la connexion échoue avant l'ouverture. Le client ne se reconnecte pas de lui-même.

close()

close(): void

Ferme la connexion et libère le module de chiffrement.

getVerificationCode()

getVerificationCode(): Promise<string>

Renvoie l'empreinte de la clé d'identité publiée par l'agent, à comparer avec Vérifier dans l'application. Voir Vérifier votre agent.

Réception

onMessage(handler)

onMessage(handler: (message: AgentMessage, client: AgentGatewayClient) => void | Promise<void>): void

Enregistre la fonction de traitement. Les messages sont traités un par un, dans l'ordre. Quand la fonction se résout, le message est marqué traité et acquitté ; si elle lève une erreur, le message peut être relivré.

listConversationMessages(options)

listConversationMessages(options: {
  conversationId: string;
  limit?: number;          // 1–100, 50 par défaut
  before?: string | Date;
  beforeId?: string;
  skipUndecodable?: boolean;
}): Promise<AgentMessage[]>

Récupère et déchiffre les messages récents reçus par l'agent dans une conversation, y compris les votes collectifs des agents membres d'un groupe.

Envoi

reply(message, options)

reply(message: AgentMessage, options: { text: string; attachments?: AgentAttachment[] }): Promise<void>

Répond à un message dans sa conversation — ou son groupe — sur l'appareil qui l'a envoyé, en le liant au message d'origine. La façon recommandée de répondre.

sendMessage(options)

sendMessage(options: {
  conversationId: string;
  to: string;               // message.from, ou `group:<conversationId>`
  text: string;
  replyToMessageId?: string;
  toDeviceId?: string;
  attachments?: AgentAttachment[];
}): Promise<void>

Envoie un message. Se résout quand il est remis à la connexion ; lève une erreur si la connexion n'est pas ouverte.

sendTyping(options)

sendTyping(options: { conversationId: string; to: string }): void

Affiche un indicateur « en train d'écrire » dans l'application.

sendFile(options) · sendMedia(options)

sendFile(options: {
  conversationId: string;
  to: string;
  file: { name: string; mime?: string; data: Uint8Array | ArrayBuffer | Blob };
  text?: string;
  replyToMessageId?: string;
}): Promise<AgentAttachment>

Chiffre et envoie un fichier. sendMedia accepte les mêmes options plus width, height et durationMs. Voir Fichiers et médias.

uploadFile(file)

uploadFile(file: { name: string; mime?: string; data: Uint8Array | ArrayBuffer | Blob }): Promise<AgentAttachment>

Chiffre et téléverse un fichier sans envoyer de message — pour joindre plusieurs fichiers à un même sendMessage.

downloadAttachment(attachment)

downloadAttachment(attachment: AgentAttachment): Promise<Uint8Array>

Télécharge un fichier reçu dans un message et le déchiffre localement avec la clé transportée par le message chiffré de bout en bout. Fonctionne pour les conversations dont l'agent est membre. Voir Fichiers et médias.

Widgets

Chaque méthode de widget prend conversationId, to, title, et en option id, body et expiresAt. Chacune renvoie l'identifiant du widget. Voir Widgets interactifs.

responseMode vaut "individual" ou "collective" — voir votes collectifs.

Types

AgentMessage

AgentWidgetResponse

AgentAttachment

Agent Connect

Fonctions serveur pour Agent Connect. Toutes acceptent un baseUrl facultatif (par défaut https://api.pacerelle.com).