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

# Attività

> Ispeziona le attività e attendi il completamento delle operazioni asincrone

Ogni operazione asincrona in Youka alla fine viene eseguita come un’attività, ma la superficie principale dell’SDK ora restituisce handle di operazione invece di ID attività grezzi. La maggior parte dei chiamanti dovrebbe usare `client.projects.wait(...)` o `client.exports.wait(...)` e ricorrere a `client.tasks.*` solo quando serve un’ispezione di basso livello delle attività.

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

Recupera lo stato corrente di un’attività tramite ID.

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

### Stati dell’attività

| Stato         | Terminale? | Significato                                                 |
| ------------- | ---------- | ----------------------------------------------------------- |
| `created`     | No         | L’attività è stata creata ma non è ancora in coda.          |
| `queued`      | No         | L’attività è in attesa di essere eseguita.                  |
| `in-progress` | No         | L’attività è attualmente in esecuzione.                     |
| `completed`   | Sì         | L’attività è terminata con successo.                        |
| `finalized`   | Sì         | L’attività è terminata e la post-elaborazione è completata. |
| `failed`      | Sì         | L’attività è fallita con un errore.                         |
| `cancelled`   | Sì         | L’attività è stata annullata.                               |
| `timed-out`   | Sì         | L’attività ha raggiunto il suo limite di tempo.             |

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

Esegue il polling di un’attività finché non raggiunge uno stato terminale. Restituisce l’attività finale in caso di successo, genera `YoukaTaskError` in caso di errore.

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

### Opzioni

<ParamField path="pollIntervalMs" type="number">
  Millisecondi tra un polling e l’altro. Il valore predefinito è `2000`.
</ParamField>

<ParamField path="signal" type="AbortSignal">
  Annulla l’attesa. La richiesta in corso e qualsiasi ritardo in sospeso vengono annullati
  immediatamente.
</ParamField>

### Errori

`client.tasks.wait(...)` genera `YoukaTaskError` quando l’attività termina in `failed`, `cancelled` o `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); // Payload completo RestTask
  }
  throw error;
}
```

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

Attende il completamento di un’operazione con ambito progetto, quindi recupera nuovamente il progetto. Restituisce l’handle dell’operazione, l’attività terminale e il progetto aggiornato.

```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>
  Di solito il risultato di `client.projects.create(...)`,
  `client.projects.separateStems(...)` o `client.projects.syncLyrics(...)`.
</ParamField>

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

Attende che un’esportazione cloud raggiunga uno stato terminale. Passa l’`ExportOperation` restituito da `client.exports.create(...)` oppure una stringa `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);
```

## Annullamento

Passa un `AbortSignal` per annullare un’attesa di lunga durata:

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

Lo stesso segnale annulla anche la richiesta di polling sottostante dell’attività o dell’esportazione.

## Cosa fare dopo

* [Errors](/it/sdk/errors) — gestire `YoukaTaskError` ed errori ritentabili
* [Exports](/it/sdk/exports) — attendere il completamento di un’esportazione
* [API async jobs](/it/api/async-jobs) — lo stesso pattern in HTTP grezzo