> ## 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 تعمل في النهاية كمهمة، لكن واجهة الـ SDK الأساسية تُرجع الآن مقابض عمليات بدلًا من معرّفات مهام خام. ينبغي لمعظم المستخدمين استعمال `client.projects.wait(...)` أو `client.exports.wait(...)` وعدم اللجوء إلى `client.tasks.*` إلا عند الحاجة إلى فحص منخفض المستوى للمهمة.

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

اجلب الحالة الحالية لمهمة عبر المعرّف.

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

### حالات المهام

| الحالة        | نهائية؟ | المعنى                                 |
| ------------- | ------- | -------------------------------------- |
| `created`     | لا      | تم إنشاء المهمة لكن لم تُصفّ بعد.      |
| `queued`      | لا      | المهمة بانتظار التشغيل.                |
| `in-progress` | لا      | المهمة قيد التنفيذ حاليًا.             |
| `completed`   | نعم     | انتهت المهمة بنجاح.                    |
| `finalized`   | نعم     | انتهت المهمة واكتملت المعالجة اللاحقة. |
| `failed`      | نعم     | فشلت المهمة مع حدوث خطأ.               |
| `cancelled`   | نعم     | تم إلغاء المهمة.                       |
| `timed-out`   | نعم     | وصلت المهمة إلى حدها الزمني.           |

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

استطلع حالة المهمة حتى تصل إلى حالة نهائية. يُرجع المهمة النهائية عند النجاح، ويطلق `YoukaTaskError` عند الفشل.

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

### الخيارات

<ParamField path="pollIntervalMs" type="number">
  عدد الملّي ثواني بين عمليات الاستطلاع. القيمة الافتراضية `2000`.
</ParamField>

<ParamField path="signal" type="AbortSignal">
  إلغاء الانتظار. يتم إلغاء الطلب الجاري وأي تأخير مُعلّق
  فورًا.
</ParamField>

### الأخطاء

تُطلق `client.tasks.wait(...)` خطأ `YoukaTaskError` عندما تنتهي المهمة بحالة `failed` أو `cancelled` أو `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?)`

انتظر حتى تنتهي عملية ضمن نطاق المشروع، ثم أعد جلب المشروع. يُرجع مقبض العملية، والمهمة النهائية، والمشروع المحدّث.

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

انتظر حتى يصل تصدير سحابي إلى حالة نهائية. مرّر إمّا `ExportOperation` المُرجَع من `client.exports.create(...)` أو سلسلة `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);
```

## الإلغاء

مرّر `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;
  }
}
```

تُلغِي الإشارة نفسها أيضًا طلب الاستطلاع الأساسي للمهمة أو التصدير.

## ما التالي

* [الأخطاء](/ar/sdk/errors) — التعامل مع `YoukaTaskError` والأخطاء القابلة لإعادة المحاولة
* [التصديرات](/ar/sdk/exports) — انتظار اكتمال التصدير
* [وظائف API غير المتزامنة](/ar/api/async-jobs) — النمط نفسه عبر HTTP الخام