Skip to main content
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. 
const task = await client.tasks.get("tsk_abc123");
console.log(task.status, task.type);

​
Stati dell’attività

StatoTerminale?Significato
createdNoL’attività è stata creata ma non è ancora in coda.
queuedNoL’attività è in attesa di essere eseguita.
in-progressNoL’attività è attualmente in esecuzione.
completedSìL’attività è terminata con successo.
finalizedSìL’attività è terminata e la post-elaborazione è completata.
failedSìL’attività è fallita con un errore.
cancelledSìL’attività è stata annullata.
timed-outSì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. 
const task = await client.tasks.wait("tsk_abc123", {
  pollIntervalMs: 3_000,
  signal: abortController.signal,
});

​
Opzioni

​
pollIntervalMs
number
Millisecondi tra un polling e l’altro. Il valore predefinito è 2000.
​
signal
AbortSignal
Annulla l’attesa. La richiesta in corso e qualsiasi ritardo in sospeso vengono annullati immediatamente.

​
Errori

client.tasks.wait(...) genera YoukaTaskError quando l’attività termina in failed, cancelled o timed-out: 
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. 
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
Di solito il risultato di client.projects.create(...), client.projects.separateStems(...) o client.projects.syncLyrics(...).

​
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. 
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: 
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 — gestire YoukaTaskError ed errori ritentabili
  • Exports — attendere il completamento di un’esportazione
  • API async jobs — lo stesso pattern in HTTP grezzo