henergyqueai-sdk

La bibliothèque officielle de l’API HenergyqueAI pour JavaScript et TypeScript : Velys, Oryne et Aelyr en quelques lignes.

• Aucune dépendance, 5 Ko compressée.
• Node 18+, Deno et Bun : partout où fetch existe.
• Types TypeScript inclus.
• Streaming, outils, images, sorties JSON.
• Nouvelles tentatives automatiques sur les erreurs passagères.

npm install henergyqueai-sdk

Créez une clé sur henergyqueai.fr/plateforme/cles, puis :

export HENERGYQUEAI_API_KEY="hak_…"

Premier appel

import HenergyqueAI from "henergyqueai-sdk";

const client = new HenergyqueAI(); // lit HENERGYQUEAI_API_KEY

console.log(await client.ask("Donne-moi trois idées de prénom pour un chat."));

ask utilise Velys par défaut. Pour choisir le modèle ou ajouter une consigne :

await client.ask("Relis cette fonction.", { model: "oryne", system: "Réponds en une phrase." });

Conversation complète

const reponse = await client.chat.create({
  model: "oryne",
  messages: [
    { role: "system", content: "Tu es un relecteur de code exigeant." },
    { role: "user", content: "Que penses-tu de `for (i in tableau)` ?" },
  ],
  temperature: 0.3,
});

console.log(reponse.text); // le texte, déjà extrait
console.log(reponse.usage); // { prompt_tokens, completion_tokens, total_tokens }

Streaming

const flux = client.chat.stream({
  model: "velys",
  messages: [{ role: "user", content: "Raconte une histoire courte." }],
});

for await (const texte of flux.textStream()) process.stdout.write(texte);

const finale = await flux.finalCompletion(); // la réponse entière, une fois terminée

flux.abort() arrête la génération en cours.

Outils

const reponse = await client.chat.create({
  model: "oryne",
  messages: [{ role: "user", content: "Quel temps fait-il à Nantes ?" }],
  tools: [
    {
      type: "function",
      function: {
        name: "meteo",
        description: "La météo actuelle d’une ville",
        parameters: { type: "object", properties: { ville: { type: "string" } }, required: ["ville"] },
      },
    },
  ],
});

for (const appel of reponse.choices[0].message.tool_calls ?? []) {
  const { ville } = JSON.parse(appel.function.arguments);
  // … exécutez l’outil, puis renvoyez son résultat dans un message { role: "tool", tool_call_id: appel.id, content }
}

Format messages

L’API accepte aussi le format messages, avec des blocs de contenu. max_tokens vaut 1024 par défaut dans la bibliothèque.

const message = await client.messages.create({
  model: "aelyr",
  system: "Tu es précis et concis.",
  messages: [{ role: "user", content: "Explique la différence entre TCP et UDP." }],
});
console.log(message.text);

const flux = client.messages.stream({ model: "aelyr", messages: [{ role: "user", content: "Un haïku." }] });
for await (const texte of flux.textStream()) process.stdout.write(texte);

const { input_tokens } = await client.messages.countTokens({ model: "velys", messages: [{ role: "user", content: "Bonjour" }] });

Modèles et consommation

const modeles = await client.models.list(); // [{ id: "velys", … }, …]
const oryne = await client.models.retrieve("oryne");
const conso = await client.usage(); // { plan, requests: { used, limit, remaining, resets_at }, key }

Erreurs

Chaque erreur de l’API devient une exception typée, avec status, type, code, param, requestId et, si l’API le précise, retryAfter.

import { RateLimitError, AuthenticationError } from "henergyqueai-sdk";

try {
  await client.ask("Bonjour");
} catch (erreur) {
  if (erreur instanceof RateLimitError) console.log(`Réessayez dans ${erreur.retryAfter} s.`);
  else if (erreur instanceof AuthenticationError) console.log("Clé invalide.");
  else throw erreur;
}

Les autres classes sont InvalidRequestError, PermissionDeniedError, NotFoundError, ServerError, ConnectionError et TimeoutError, toutes filles de HenergyqueAIError.

Les erreurs passagères (429, 5xx, coupure réseau) sont retentées deux fois, en respectant retry-after. La limite quotidienne de votre offre n’est jamais retentée.

Options

const client = new HenergyqueAI({
  apiKey: "hak_…",   // sinon HENERGYQUEAI_API_KEY
  timeout: 60_000,   // attente maximale d’une réponse, en ms (10 minutes par défaut)
  maxRetries: 3,     // 2 par défaut
});

// Pour un seul appel :
await client.chat.create(params, { signal: controleur.signal, timeout: 30_000, maxRetries: 0 });

Sécurité

Gardez la clé côté serveur. Ne l’incluez jamais dans le code d’une page web, d’une application mobile ou d’un dépôt Git.

Licence

MIT