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

# Tarefas

> Inspecione tarefas e aguarde a conclusão de operações assíncronas

Toda operação assíncrona no Youka eventualmente é executada como uma tarefa, mas a superfície principal do SDK agora retorna handles de operação em vez de IDs de tarefa brutos. A maioria dos utilizadores deve usar `client.projects.wait(...)` ou `client.exports.wait(...)` e recorrer a `client.tasks.*` apenas quando precisar de inspeção de tarefas de baixo nível.

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

Obtém o estado atual de uma tarefa pelo ID.

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

### Status de tarefa

| Status        | Terminal? | Significado                                                  |
| ------------- | --------- | ------------------------------------------------------------ |
| `created`     | Não       | A tarefa foi criada, mas ainda não foi enfileirada.          |
| `queued`      | Não       | A tarefa está aguardando para executar.                      |
| `in-progress` | Não       | A tarefa está em execução no momento.                        |
| `completed`   | Sim       | A tarefa foi concluída com sucesso.                          |
| `finalized`   | Sim       | A tarefa foi concluída e o pós-processamento foi finalizado. |
| `failed`      | Sim       | A tarefa falhou com um erro.                                 |
| `cancelled`   | Sim       | A tarefa foi cancelada.                                      |
| `timed-out`   | Sim       | A tarefa atingiu o limite de tempo.                          |

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

Faz polling de uma tarefa até que ela atinja um estado terminal. Retorna a tarefa final em caso de sucesso e lança `YoukaTaskError` em caso de falha.

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

### Opções

<ParamField path="pollIntervalMs" type="number">
  Milissegundos entre polls. O padrão é `2000`.
</ParamField>

<ParamField path="signal" type="AbortSignal">
  Cancela a espera. A requisição em andamento e qualquer atraso pendente são cancelados
  imediatamente.
</ParamField>

### Erros

`client.tasks.wait(...)` lança `YoukaTaskError` quando a tarefa termina em `failed`, `cancelled` ou `timed-out`:

```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?)`

Aguarde a conclusão de uma operação no escopo do projeto e, em seguida, busque novamente o projeto. Retorna o handle da operação, a tarefa terminal e o projeto atualizado.

```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>
  Normalmente, o resultado de `client.projects.create(...)`,
  `client.projects.separateStems(...)` ou `client.projects.syncLyrics(...)`.
</ParamField>

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

Aguarde até que uma exportação na nuvem atinja um estado terminal. Passe o `ExportOperation` retornado por `client.exports.create(...)` ou uma string `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);
```

## Cancelamento

Passe um `AbortSignal` para cancelar uma espera demorada:

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

O mesmo signal também cancela a requisição subjacente de polling de tarefas ou exportações.

## O que vem a seguir

* [Errors](/pt/sdk/errors) — trate `YoukaTaskError` e erros passíveis de retry
* [Exports](/pt/sdk/exports) — aguarde a conclusão de uma exportação
* [API async jobs](/pt/api/async-jobs) — o mesmo padrão em HTTP bruto