TypeScript SDK - Avala Documentation

Installation

npm install @avala-ai/sdk

yarn add @avala-ai/sdk

pnpm add @avala-ai/sdk

Démarrage rapide

import Avala from "@avala-ai/sdk";

const avala = new Avala({ apiKey: "your-api-key" });

const datasets = await avala.datasets.list();
for (const dataset of datasets.items) {
  console.log(dataset.name, dataset.uid);
}

Créer un compte

La fonction signup crée un nouveau compte Avala et retourne une clé API. Elle ne nécessite pas d’authentification.

import { signup } from "@avala-ai/sdk";

const result = await signup({
  email: "dev@acme.com",
  password: "SecurePass123!",
  firstName: "Jane",       // optional
  lastName: "Doe",         // optional
});

console.log(`User: ${result.user.email}`);
console.log(`API Key: ${result.apiKey}`);

Utilisez la clé API retournée pour initialiser le client :

import Avala, { signup } from "@avala-ai/sdk";

const { apiKey } = await signup({ email: "dev@acme.com", password: "SecurePass123!" });
const avala = new Avala({ apiKey });

Authentification

Le SDK s’authentifie en utilisant votre clé API Avala, qui est envoyée via l’en-tête X-Avala-Api-Key à chaque requête. Vous pouvez fournir la clé directement ou laisser le SDK la lire depuis l’environnement. Option 1 : Passer la clé directement

import Avala from "@avala-ai/sdk";

const avala = new Avala({ apiKey: "your-api-key" });

Option 2 : Utiliser une variable d’environnement

export AVALA_API_KEY="your-api-key"

import Avala from "@avala-ai/sdk";

// Automatically reads AVALA_API_KEY from the environment
const avala = new Avala();

Travailler avec les jeux de données

Le TypeScript SDK est actuellement en lecture seule pour les jeux de données — vous pouvez lister et récupérer les jeux de données mais pas les créer, les mettre à jour ou les supprimer. Utilisez la REST API pour les téléchargements et les mutations.

Lister les jeux de données

const datasets = await avala.datasets.list();

for (const dataset of datasets.items) {
  console.log(`${dataset.name} (${dataset.uid})`);
  console.log(`  Items: ${dataset.itemCount}`);
  console.log(`  Created: ${dataset.createdAt}`);
}

Obtenir un jeu de données

const dataset = await avala.datasets.get("550e8400-e29b-41d4-a716-446655440000");

console.log(dataset.name);
console.log(dataset.slug);
console.log(dataset.itemCount);

Travailler avec les projets

Lister les projets

const projects = await avala.projects.list();

for (const project of projects.items) {
  console.log(`${project.name} (${project.uid})`);
  console.log(`  Status: ${project.status}`);
  console.log(`  Created: ${project.createdAt}`);
}

Obtenir un projet

const project = await avala.projects.get("770a9600-a40d-63f6-c938-668877660000");

console.log(project.name);
console.log(project.status);

Travailler avec les tâches

Lister les tâches

const tasks = await avala.tasks.list({
  project: "770a9600-a40d-63f6-c938-668877660000",
  status: "pending",
});

for (const task of tasks.items) {
  console.log(`${task.uid} — ${task.name} (${task.status})`);
}

Obtenir une tâche

const task = await avala.tasks.get("990c1800-b62f-85a8-e150-880099880000");

console.log(task.name);
console.log(task.status);

Travailler avec les exports

Créer un export

const exportJob = await avala.exports.create({
  project: "770a9600-a40d-63f6-c938-668877660000",
});

console.log(`Export started: ${exportJob.uid}`);
console.log(`Status: ${exportJob.status}`);

Attendre la fin

let exportJob = await avala.exports.create({
  project: "770a9600-a40d-63f6-c938-668877660000",
});

while (exportJob.status !== "completed") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  exportJob = await avala.exports.get(exportJob.uid);
  console.log(`Status: ${exportJob.status}`);
}

console.log(`Download: ${exportJob.downloadUrl}`);

Types TypeScript

Le SDK exporte des interfaces TypeScript complètes pour tous les objets API. Utilisez-les pour typer vos fonctions et variables.

import Avala from "@avala-ai/sdk";
import type { Dataset, Project, Export, Task, CursorPage } from "@avala-ai/sdk";

function processDataset(dataset: Dataset): void {
  console.log(dataset.name);       // string
  console.log(dataset.uid);        // string
  console.log(dataset.itemCount);  // number
  console.log(dataset.createdAt);  // string | null
}

function processTask(task: Task): void {
  console.log(task.uid);           // string
  console.log(task.name);          // string | null
  console.log(task.status);        // string | null
  console.log(task.project);       // string | null
}

Gestion des erreurs

Le SDK lève des erreurs typées pour que vous puissiez gérer précisément les différents modes de défaillance.

import Avala, { AvalaError, NotFoundError, RateLimitError } from "@avala-ai/sdk";

const avala = new Avala();

try {
  const dataset = await avala.datasets.get("nonexistent");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(`Dataset not found: ${error.message}`);
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds.`);
  } else if (error instanceof AvalaError) {
    console.log(`API error (${error.statusCode}): ${error.message}`);
  } else {
    throw error;
  }
}

Exception	Description
`AvalaError`	Classe d’erreur de base pour toutes les erreurs de l’API Avala.
`AuthenticationError`	Clé API invalide ou manquante (HTTP 401).
`NotFoundError`	La ressource demandée n’existe pas (HTTP 404).
`RateLimitError`	Vous avez dépassé la limite de débit de l’API (HTTP 429). Inclut une propriété `retryAfter`.
`ValidationError`	La charge utile de la requête a échoué la validation (HTTP 400/422).
`ServerError`	Le serveur a retourné une erreur interne (HTTP 5xx).

Pagination

Les méthodes de liste retournent un objet CursorPage<T> avec une pagination basée sur les curseurs.

// Access items on the current page
const page = await avala.datasets.list({ limit: 10 });
for (const dataset of page.items) {
  console.log(dataset.name);
}

// Fetch the next page
if (page.hasMore) {
  const nextPage = await avala.datasets.list({
    limit: 10,
    cursor: page.nextCursor!,
  });
}

Travailler avec les agents

Créer un agent

const agent = await avala.agents.create({
  name: "QA Bot",
  events: ["task.completed"],
  callbackUrl: "https://example.com/webhook",
  taskTypes: ["annotation"],
});

Lister les exécutions d’un agent

const executions = await avala.agents.listExecutions(agent.uid);
for (const exec of executions.items) {
  console.log(`${exec.eventType} — ${exec.status}`);
}

Travailler avec les webhooks

Créer un webhook

const webhook = await avala.webhooks.create({
  targetUrl: "https://example.com/webhook",
  events: ["task.completed", "export.ready"],
});

Inspecter les livraisons

const deliveries = await avala.webhookDeliveries.list();
for (const d of deliveries.items) {
  console.log(`${d.eventType} — ${d.status} (attempts: ${d.attempts})`);
}

Travailler avec la qualité et le consensus

Créer un objectif de qualité

const target = await avala.qualityTargets.create("proj_uid", {
  name: "Accuracy",
  metric: "accuracy",
  operator: "gte",
  threshold: 0.95,
  notifyEmails: ["alerts@example.com"],
});

Vérifier le consensus

const summary = await avala.consensus.getSummary("proj_uid");
console.log(`Mean score: ${summary.meanScore}`);
console.log(`Coverage: ${summary.itemsWithConsensus}/${summary.totalItems}`);

Gestion de flotte

La gestion de flotte est en aperçu. Les APIs décrites ici peuvent changer.

L’espace de noms fleet fournit l’accès au registre d’appareils, aux enregistrements, événements, règles et alertes.

// List online devices
const devices = await avala.fleet.devices.list({ status: "online" });

// Create a timeline event on a recording
const event = await avala.fleet.events.create({
  recordingId: "rec_abc123",
  timestamp: "2026-01-15T10:30:00Z",
  type: "anomaly",
  label: "Gripper force spike",
  metadata: { force_n: 45.2 },
});

// Create a recording rule
const rule = await avala.fleet.rules.create({
  name: "High Latency Alert",
  condition: { type: "threshold", topic: "/diagnostics/latency", field: "data.value", operator: "gt", value: 100 },
  actions: [{ type: "tag", value: "high-latency" }, { type: "notify", channelId: "ch_your_channel_id" }],
});

Consultez le guide Tableau de bord de flotte pour des exemples complets.

Configuration

Vous pouvez personnaliser le comportement du client lors de l’initialisation.

import Avala from "@avala-ai/sdk";

const avala = new Avala({
  apiKey: "your-api-key",
  baseUrl: "https://api.avala.ai/api/v1", // Default
  timeout: 60_000,    // Request timeout in ms (default: 30000)
});

Paramètre	Type	Défaut	Description
`apiKey`	`string`	Variable d’env `AVALA_API_KEY`	Votre clé API Avala.
`baseUrl`	`string`	`https://api.avala.ai/api/v1`	L’URL de base de l’API.
`timeout`	`number`	`30000`	Délai d’attente de requête en millisecondes.

Zéro dépendance

Le package @avala-ai/sdk a zéro dépendance runtime. Il utilise l’API fetch native disponible dans Node.js 18+, Deno et Bun.

Exemples de framework

Next.js (App Router)

// app/api/datasets/route.ts
import Avala from "@avala-ai/sdk";
import { NextResponse } from "next/server";

const avala = new Avala({ apiKey: process.env.AVALA_API_KEY! });

export async function GET() {
  const datasets = await avala.datasets.list();
  return NextResponse.json(datasets);
}

Express

import express from "express";
import Avala from "@avala-ai/sdk";

const app = express();
const avala = new Avala(); // Reads AVALA_API_KEY from env

app.get("/datasets", async (req, res) => {
  try {
    const datasets = await avala.datasets.list();
    res.json(datasets);
  } catch (error) {
    res.status(500).json({ error: "Failed to fetch datasets" });
  }
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

​Installation

​Démarrage rapide

​Créer un compte

​Authentification

​Travailler avec les jeux de données

​Lister les jeux de données

​Obtenir un jeu de données

​Travailler avec les projets

​Lister les projets

​Obtenir un projet

​Travailler avec les tâches

​Lister les tâches

​Obtenir une tâche

​Travailler avec les exports

​Créer un export

​Attendre la fin

​Types TypeScript

​Gestion des erreurs

​Pagination

​Travailler avec les agents

​Créer un agent

​Lister les exécutions d’un agent

​Travailler avec les webhooks

​Créer un webhook

​Inspecter les livraisons

​Travailler avec la qualité et le consensus

​Créer un objectif de qualité

​Vérifier le consensus

​Gestion de flotte

​Configuration

​Zéro dépendance

​Exemples de framework

​Next.js (App Router)

​Express

Installation

Démarrage rapide

Créer un compte

Authentification

Travailler avec les jeux de données

Lister les jeux de données

Obtenir un jeu de données

Travailler avec les projets

Lister les projets

Obtenir un projet

Travailler avec les tâches

Lister les tâches

Obtenir une tâche

Travailler avec les exports

Créer un export

Attendre la fin

Types TypeScript

Gestion des erreurs

Pagination

Travailler avec les agents

Créer un agent

Lister les exécutions d’un agent

Travailler avec les webhooks

Créer un webhook

Inspecter les livraisons

Travailler avec la qualité et le consensus

Créer un objectif de qualité

Vérifier le consensus

Gestion de flotte

Configuration

Zéro dépendance

Exemples de framework

Next.js (App Router)

Express