TypeScript SDK - Avala Documentation

Installation

npm install @avala-ai/sdk

Schnellstart

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

Konto erstellen

Die Funktion signup erstellt ein neues Avala-Konto und gibt einen API Key zurück. Sie erfordert keine Authentifizierung.

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

Verwenden Sie den zurückgegebenen API Key, um den Client zu initialisieren:

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

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

Authentifizierung

Das SDK authentifiziert sich mit Ihrem Avala API Key, der über den X-Avala-Api-Key Header bei jeder Anfrage gesendet wird. Sie können den Key direkt übergeben oder das SDK ihn aus der Umgebung lesen lassen. Option 1: Key direkt übergeben

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

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

Option 2: Umgebungsvariable verwenden

export AVALA_API_KEY="your-api-key"

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

// Liest automatisch AVALA_API_KEY aus der Umgebung
const avala = new Avala();

Arbeiten mit Datensätzen

Das TypeScript SDK ist derzeit schreibgeschützt für Datensätze — Sie können Datensätze auflisten und abrufen, aber nicht erstellen, aktualisieren oder löschen. Verwenden Sie die REST API für Uploads und Mutationen.

Datensätze auflisten

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

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

Datensatz abrufen

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

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

Arbeiten mit Projekten

Projekte auflisten

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(`  Erstellt: ${project.createdAt}`);
}

Projekt abrufen

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

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

Arbeiten mit Aufgaben

Aufgaben auflisten

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

Aufgabe abrufen

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

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

Arbeiten mit Exporten

Export erstellen

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

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

Auf Fertigstellung warten

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

TypeScript-Typen

Das SDK exportiert vollständige TypeScript-Interfaces für alle API-Objekte. Verwenden Sie sie, um Ihre Funktionen und Variablen zu typisieren.

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
}

Fehlerbehandlung

Das SDK wirft typisierte Fehler, sodass Sie verschiedene Fehlermodi präzise behandeln können.

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(`Datensatz nicht gefunden: ${error.message}`);
  } else if (error instanceof RateLimitError) {
    console.log(`Rate-Limit erreicht. Erneut versuchen nach ${error.retryAfter} Sekunden.`);
  } else if (error instanceof AvalaError) {
    console.log(`API-Fehler (${error.statusCode}): ${error.message}`);
  } else {
    throw error;
  }
}

Exception	Beschreibung
`AvalaError`	Basis-Fehlerklasse für alle Avala API-Fehler.
`AuthenticationError`	Ungültiger oder fehlender API Key (HTTP 401).
`NotFoundError`	Die angeforderte Ressource existiert nicht (HTTP 404).
`RateLimitError`	Das API-Rate-Limit wurde überschritten (HTTP 429). Enthält eine `retryAfter`-Eigenschaft.
`ValidationError`	Die Anfrage hat die Validierung nicht bestanden (HTTP 400/422).
`ServerError`	Der Server hat einen internen Fehler zurückgegeben (HTTP 5xx).

Paginierung

Listen-Methoden geben ein CursorPage<T>-Objekt mit cursorbasierter Paginierung zurück.

// Auf Elemente der aktuellen Seite zugreifen
const page = await avala.datasets.list({ limit: 10 });
for (const dataset of page.items) {
  console.log(dataset.name);
}

// Nächste Seite abrufen
if (page.hasMore) {
  const nextPage = await avala.datasets.list({
    limit: 10,
    cursor: page.nextCursor!,
  });
}

Arbeiten mit Agents

Agent erstellen

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

Agent-Ausführungen auflisten

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

Arbeiten mit Webhooks

Webhook erstellen

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

Zustellungen inspizieren

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

Arbeiten mit Qualität & Konsens

Qualitätsziel erstellen

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

Konsens prüfen

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

Flottenmanagement

Flottenmanagement ist in der Vorschau. Die hier beschriebenen APIs können sich ändern.

Der fleet-Namespace bietet Zugriff auf Geräteregister, Aufnahmen, Events, Regeln und Warnungen.

// Online-Geräte auflisten
const devices = await avala.fleet.devices.list({ status: "online" });

// Ein Zeitleisten-Event auf einer Aufnahme erstellen
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 },
});

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

Siehe den Fleet Dashboard Guide für vollständige Beispiele.

Konfiguration

Sie können das Client-Verhalten bei der Initialisierung anpassen.

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

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

Parameter	Typ	Standard	Beschreibung
`apiKey`	`string`	`AVALA_API_KEY` Umgebungsvariable	Ihr Avala API Key.
`baseUrl`	`string`	`https://api.avala.ai/api/v1`	Die API-Basis-URL.
`timeout`	`number`	`30000`	Request-Timeout in Millisekunden.

Keine Abhängigkeiten

Das Paket @avala-ai/sdk hat keine Laufzeitabhängigkeiten. Es verwendet die native fetch API, die in Node.js 18+, Deno und Bun verfügbar ist.

Framework-Beispiele

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(); // Liest AVALA_API_KEY aus der Umgebung

app.get("/datasets", async (req, res) => {
  try {
    const datasets = await avala.datasets.list();
    res.json(datasets);
  } catch (error) {
    res.status(500).json({ error: "Fehler beim Abrufen der Datensätze" });
  }
});

app.listen(3000, () => {
  console.log("Server läuft auf Port 3000");
});

SDKs

​Installation

​Schnellstart

​Konto erstellen

​Authentifizierung

​Arbeiten mit Datensätzen

​Datensätze auflisten

​Datensatz abrufen

​Arbeiten mit Projekten

​Projekte auflisten

​Projekt abrufen

​Arbeiten mit Aufgaben

​Aufgaben auflisten

​Aufgabe abrufen

​Arbeiten mit Exporten

​Export erstellen

​Auf Fertigstellung warten

​TypeScript-Typen

​Fehlerbehandlung

​Paginierung

​Arbeiten mit Agents

​Agent erstellen

​Agent-Ausführungen auflisten

​Arbeiten mit Webhooks

​Webhook erstellen

​Zustellungen inspizieren

​Arbeiten mit Qualität & Konsens

​Qualitätsziel erstellen

​Konsens prüfen

​Flottenmanagement

​Konfiguration

​Keine Abhängigkeiten

​Framework-Beispiele

​Next.js (App Router)

​Express

Installation

Schnellstart

Konto erstellen

Authentifizierung

Arbeiten mit Datensätzen

Datensätze auflisten

Datensatz abrufen

Arbeiten mit Projekten

Projekte auflisten

Projekt abrufen

Arbeiten mit Aufgaben

Aufgaben auflisten

Aufgabe abrufen

Arbeiten mit Exporten

Export erstellen

Auf Fertigstellung warten

TypeScript-Typen

Fehlerbehandlung

Paginierung

Arbeiten mit Agents

Agent erstellen

Agent-Ausführungen auflisten

Arbeiten mit Webhooks

Webhook erstellen

Zustellungen inspizieren

Arbeiten mit Qualität & Konsens

Qualitätsziel erstellen

Konsens prüfen

Flottenmanagement

Konfiguration

Keine Abhängigkeiten

Framework-Beispiele

Next.js (App Router)

Express