> ## 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

> Avala TypeScript SDK 전체 가이드

## 설치

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

## 빠른 시작

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

## 계정 생성

`signup` 함수는 새 Avala 계정을 생성하고 API 키를 반환합니다. 인증이 필요 없습니다.

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

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

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

## 인증

**방법 1: 키 직접 전달**

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

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

**방법 2: 환경 변수 사용**

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

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

// 환경에서 AVALA_API_KEY를 자동으로 읽음
const avala = new Avala();
```

## 데이터셋 작업

```typescript theme={null}
const datasets = await avala.datasets.list();
for (const dataset of datasets.items) {
  console.log(`${dataset.name} (${dataset.uid})`);
}

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

## 프로젝트 작업

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

## 내보내기 작업

```typescript theme={null}
const exportJob = await avala.exports.create({
  project: "770a9600-a40d-63f6-c938-668877660000",
});
console.log(`Export started: ${exportJob.uid}`);

// 완료까지 폴링
let job = exportJob;
while (job.status !== "completed") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  job = await avala.exports.get(job.uid);
}
console.log(`Download: ${job.downloadUrl}`);
```

## 오류 처리

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

| 예외                    | 설명                                           |
| --------------------- | -------------------------------------------- |
| `AvalaError`          | 모든 Avala API 오류의 기본 에러 클래스.                  |
| `AuthenticationError` | 유효하지 않거나 누락된 API 키 (HTTP 401).               |
| `NotFoundError`       | 요청된 리소스가 존재하지 않음 (HTTP 404).                 |
| `RateLimitError`      | API 속도 제한 초과 (HTTP 429). `retryAfter` 속성 포함. |
| `ValidationError`     | 요청 페이로드 검증 실패 (HTTP 400/422).                |
| `ServerError`         | 서버 내부 오류 (HTTP 5xx).                         |

## 페이지네이션

```typescript theme={null}
const page = await avala.datasets.list({ limit: 10 });
for (const dataset of page.items) {
  console.log(dataset.name);
}

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

## 구성

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

const avala = new Avala({
  apiKey: "your-api-key",
  baseUrl: "https://api.avala.ai/api/v1", // 기본값
  timeout: 60_000,    // 요청 타임아웃(ms) (기본값: 30000)
});
```

## 의존성 없음

`@avala-ai/sdk` 패키지는 런타임 의존성이 없습니다. Node.js 18+, Deno, Bun에서 사용 가능한 네이티브 `fetch` API를 사용합니다.