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

​
client.tasks.get(taskId, options?)

ID로 task의 현재 상태를 가져옵니다. 
const task = await client.tasks.get("tsk_abc123");
console.log(task.status, task.type);

​
Task statuses

상태종료 상태?의미
createdNoTask가 생성되었지만 아직 큐에 들어가지 않았습니다.
queuedNoTask가 실행을 기다리는 중입니다.
in-progressNoTask가 현재 실행 중입니다.
completedYesTask가 성공적으로 완료되었습니다.
finalizedYesTask가 완료되었고 후처리까지 끝났습니다.
failedYesTask가 오류로 실패했습니다.
cancelledYesTask가 취소되었습니다.
timed-outYesTask가 시간 제한에 도달했습니다.

​
client.tasks.wait(taskId, options?)

task가 종료 상태에 도달할 때까지 폴링합니다. 성공 시 최종 task를 반환하고, 실패 시 YoukaTaskError를 throw합니다. 
const task = await client.tasks.wait("tsk_abc123", {
  pollIntervalMs: 3_000,
  signal: abortController.signal,
});

​
Options

​
pollIntervalMs
number
폴링 사이의 밀리초 간격입니다. 기본값은 2000입니다.
​
signal
AbortSignal
대기를 중단합니다. 진행 중인 요청과 대기 중인 지연은 즉시 취소됩니다.

​
Errors

client.tasks.wait(...)는 task가 failed, cancelled, 또는 timed-out으로 끝나면 YoukaTaskError를 throw합니다: 
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를 반환합니다. 
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);
​
operation
ProjectOperation
required
보통 client.projects.create(...), client.projects.separateStems(...), 또는 client.projects.syncLyrics(...)의 결과입니다.

​
client.exports.wait(operationOrId, options?)

클라우드 export가 종료 상태에 도달할 때까지 기다립니다. client.exports.create(...)가 반환한 ExportOperation 또는 exportId 문자열을 전달하세요. 
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을 전달하세요: 
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 — YoukaTaskError 및 재시도 가능한 오류 처리
  • Exports — export가 완료될 때까지 대기
  • API async jobs — 원시 HTTP에서의 동일한 패턴