TypeScript SDK - Avala Documentation

Instalación

npm install @avala-ai/sdk

yarn add @avala-ai/sdk

pnpm add @avala-ai/sdk

Inicio rápido

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);
}

Crear una cuenta

La función signup crea una nueva cuenta de Avala y devuelve una API key. No requiere autenticación.

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}`);

Use la API key devuelta para inicializar el cliente:

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

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

Autenticación

El SDK se autentica usando su API key de Avala, que se envía a través del encabezado X-Avala-Api-Key en cada solicitud. Puede proporcionar la clave directamente o dejar que el SDK la lea del entorno. Opción 1: Pasar la clave directamente

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

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

Opción 2: Usar una variable de entorno

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();

Trabajar con datasets

El TypeScript SDK es actualmente solo lectura para datasets — puede listar y obtener datasets pero no crear, actualizar ni eliminarlos. Use la REST API para subidas y mutaciones.

Listar datasets

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}`);
}

Obtener un dataset

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

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

Trabajar con proyectos

Listar proyectos

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}`);
}

Obtener un proyecto

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

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

Trabajar con tareas

Listar tareas

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})`);
}

Obtener una tarea

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

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

Trabajar con exportaciones

Crear una exportación

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

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

Consultar hasta completar

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}`);

Tipos TypeScript

El SDK exporta interfaces TypeScript completas para todos los objetos de la API. Úselos para tipar sus funciones y 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
}

Manejo de errores

El SDK lanza errores tipados para que pueda manejar diferentes modos de fallo con precisión.

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;
  }
}

Excepción	Descripción
`AvalaError`	Clase de error base para todos los errores de la API de Avala.
`AuthenticationError`	API key inválida o faltante (HTTP 401).
`NotFoundError`	El recurso solicitado no existe (HTTP 404).
`RateLimitError`	Ha excedido el límite de tasa de la API (HTTP 429). Incluye una propiedad `retryAfter`.
`ValidationError`	La carga de la solicitud falló en la validación (HTTP 400/422).
`ServerError`	El servidor devolvió un error interno (HTTP 5xx).

Paginación

Los métodos de listado devuelven un objeto CursorPage<T> con paginación basada en cursor.

// 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!,
  });
}

Trabajar con agentes

Crear un agente

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

Listar ejecuciones de agentes

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

Trabajar con webhooks

Crear un webhook

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

Inspeccionar entregas

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

Trabajar con calidad y consenso

Crear un objetivo de calidad

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

Verificar consenso

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

Gestión de flotas

La gestión de flotas está en vista previa. Las APIs descritas aquí pueden cambiar.

El namespace fleet proporciona acceso al registro de dispositivos, grabaciones, eventos, reglas y alertas.

// 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" }],
});

Consulte la guía del Panel de flota para ejemplos completos.

Configuración

Puede personalizar el comportamiento del cliente en el momento de la inicialización.

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)
});

Parámetro	Tipo	Valor por defecto	Descripción
`apiKey`	`string`	Variable de entorno `AVALA_API_KEY`	Su API key de Avala.
`baseUrl`	`string`	`https://api.avala.ai/api/v1`	La URL base de la API.
`timeout`	`number`	`30000`	Tiempo de espera de solicitud en milisegundos.

Cero dependencias

El paquete @avala-ai/sdk tiene cero dependencias en tiempo de ejecución. Usa la API nativa fetch disponible en Node.js 18+, Deno y Bun.

Ejemplos con frameworks

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");
});

​Instalación

​Inicio rápido

​Crear una cuenta

​Autenticación

​Trabajar con datasets

​Listar datasets

​Obtener un dataset

​Trabajar con proyectos

​Listar proyectos

​Obtener un proyecto

​Trabajar con tareas

​Listar tareas

​Obtener una tarea

​Trabajar con exportaciones

​Crear una exportación

​Consultar hasta completar

​Tipos TypeScript

​Manejo de errores

​Paginación

​Trabajar con agentes

​Crear un agente

​Listar ejecuciones de agentes

​Trabajar con webhooks

​Crear un webhook

​Inspeccionar entregas

​Trabajar con calidad y consenso

​Crear un objetivo de calidad

​Verificar consenso

​Gestión de flotas

​Configuración

​Cero dependencias

​Ejemplos con frameworks

​Next.js (App Router)

​Express

Instalación

Inicio rápido

Crear una cuenta

Autenticación

Trabajar con datasets

Listar datasets

Obtener un dataset

Trabajar con proyectos

Listar proyectos

Obtener un proyecto

Trabajar con tareas

Listar tareas

Obtener una tarea

Trabajar con exportaciones

Crear una exportación

Consultar hasta completar

Tipos TypeScript

Manejo de errores

Paginación

Trabajar con agentes

Crear un agente

Listar ejecuciones de agentes

Trabajar con webhooks

Crear un webhook

Inspeccionar entregas

Trabajar con calidad y consenso

Crear un objetivo de calidad

Verificar consenso

Gestión de flotas

Configuración

Cero dependencias

Ejemplos con frameworks

Next.js (App Router)

Express