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

# 작업

> 작업을 확인하고 비동기 작업이 완료될 때까지 대기

Youka의 모든 비동기 작업은 결국 task로 실행되지만, 기본 SDK 표면은 이제 원시 task ID 대신 operation handle을 반환합니다. 대부분의 호출자는 `client.projects.wait(...)` 또는 `client.exports.wait(...)`를 사용해야 하며, 저수준 task 검사(인스펙션)가 필요할 때만 `client.tasks.*`를 사용하는 것이 좋습니다.

## `client.tasks.get(taskId, options?)`

ID로 task의 현재 상태를 가져옵니다.

```ts theme={null}
const task = await client.tasks.get("tsk_abc123");
console.log(task.status, task.type);
```

### Task statuses

| 상태            | 종료 상태? | 의미                             |
| ------------- | ------ | ------------------------------ |
| `created`     | No     | Task가 생성되었지만 아직 큐에 들어가지 않았습니다. |
| `queued`      | No     | Task가 실행을 기다리는 중입니다.           |
| `in-progress` | No     | Task가 현재 실행 중입니다.              |
| `completed`   | Yes    | Task가 성공적으로 완료되었습니다.           |
| `finalized`   | Yes    | Task가 완료되었고 후처리까지 끝났습니다.       |
| `failed`      | Yes    | Task가 오류로 실패했습니다.              |
| `cancelled`   | Yes    | Task가 취소되었습니다.                 |
| `timed-out`   | Yes    | Task가 시간 제한에 도달했습니다.           |

## `client.tasks.wait(taskId, options?)`

task가 종료 상태에 도달할 때까지 폴링합니다. 성공 시 최종 task를 반환하고, 실패 시 `YoukaTaskError`를 throw합니다.

```ts theme={null}
const task = await client.tasks.wait("tsk_abc123", {
  pollIntervalMs: 3_000,
  signal: abortController.signal,
});
```

### Options

<ParamField path="pollIntervalMs" type="number">
  폴링 사이의 밀리초 간격입니다. 기본값은 `2000`입니다.
</ParamField>

<ParamField path="signal" type="AbortSignal">
  대기를 중단합니다. 진행 중인 요청과 대기 중인 지연은 즉시 취소됩니다.
</ParamField>

### Errors

`client.tasks.wait(...)`는 task가 `failed`, `cancelled`, 또는 `timed-out`으로 끝나면 `YoukaTaskError`를 throw합니다:

```ts theme={null}
import { YoukaTaskError } from "@youka/sdk";

try {
  await client.tasks.wait("tsk_abc123");
} catch (error) {
  if (error instanceof YoukaTaskError) {
    console.error(error.code); // TASK_FAILED | TASK_CANCELLED | TASK_TIMED_OUT
    console.error(error.task); // Full RestTask payload
  }
  throw error;
}
```

## `client.projects.wait(operation, options?)`

프로젝트 범위의 operation이 완료될 때까지 기다린 뒤, 프로젝트를 다시 가져옵니다. operation handle, 종료 상태의 task, 업데이트된 project를 반환합니다.

```ts theme={null}
const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
});

const { project, task } = await client.projects.wait(operation, {
  pollIntervalMs: 2_500,
});

console.log("Project ready:", project.id);
console.log("Task finished in state:", task.status);
```

<ParamField path="operation" type="ProjectOperation" required>
  보통 `client.projects.create(...)`,
  `client.projects.separateStems(...)`, 또는 `client.projects.syncLyrics(...)`의 결과입니다.
</ParamField>

## `client.exports.wait(operationOrId, options?)`

클라우드 export가 종료 상태에 도달할 때까지 기다립니다. `client.exports.create(...)`가 반환한 `ExportOperation` 또는 `exportId` 문자열을 전달하세요.

```ts theme={null}
const operation = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  quality: "high",
});

const finalized = await client.exports.wait(operation, {
  pollIntervalMs: 3_000,
});

console.log(finalized.status, finalized.url);
```

## Cancellation

오래 걸리는 대기를 취소하려면 `AbortSignal`을 전달하세요:

```ts theme={null}
const controller = new AbortController();

setTimeout(() => controller.abort(), 60_000);

try {
  await client.projects.wait(operation, { signal: controller.signal });
} catch (error) {
  if (error instanceof Error && error.name === "AbortError") {
    console.log("Wait cancelled after 60s");
  } else {
    throw error;
  }
}
```

같은 signal은 내부적으로 수행되는 task 또는 export 폴링 요청도 취소합니다.

## What's next

* [Errors](/ko/sdk/errors) — `YoukaTaskError` 및 재시도 가능한 오류 처리
* [Exports](/ko/sdk/exports) — export가 완료될 때까지 대기
* [API async jobs](/ko/api/async-jobs) — 원시 HTTP에서의 동일한 패턴