> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Vollständiger Guide für das Avala TypeScript SDK

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @avala-ai/sdk
  ```

  ```bash yarn theme={null}
  yarn add @avala-ai/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @avala-ai/sdk
  ```
</CodeGroup>

## Schnellstart

```typescript theme={null}
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.

```typescript theme={null}
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:

```typescript theme={null}
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**

```typescript theme={null}
import Avala from "@avala-ai/sdk";

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

**Option 2: Umgebungsvariable verwenden**

```bash theme={null}
export AVALA_API_KEY="your-api-key"
```

```typescript theme={null}
import Avala from "@avala-ai/sdk";

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

## Arbeiten mit Datensätzen

<Note>
  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](/docs/sdks/rest-api#file-uploads) für Uploads und Mutationen.
</Note>

### Datensätze auflisten

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
const project = await avala.projects.get("770a9600-a40d-63f6-c938-668877660000");

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

## Arbeiten mit Aufgaben

### Aufgaben auflisten

```typescript theme={null}
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

```typescript theme={null}
const task = await avala.tasks.get("990c1800-b62f-85a8-e150-880099880000");

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

## Arbeiten mit Exporten

### Export erstellen

```typescript theme={null}
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

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
// 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

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

### Agent-Ausführungen auflisten

```typescript theme={null}
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

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

### Zustellungen inspizieren

```typescript theme={null}
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

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

### Konsens prüfen

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

## Flottenmanagement

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

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

```typescript theme={null}
// 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](/docs/visualization/fleet/fleet-dashboard) Guide für vollständige Beispiele.

## Konfiguration

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

```typescript theme={null}
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)

```typescript theme={null}
// 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

```typescript theme={null}
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");
});
```