حزمة Node.js

‏@videohati/node هي حزمة الخادم الرسمية. وهي بصيغة ESM، بلا تبعيات وقت التشغيل، ومكتوبة بأنواع مطابقة لمواصفة OpenAPI 3.1 المنشورة على ‏https://api.videohati.com/openapi.json. الإصدار 1.0.0-rc.0.

التثبيت

‏Node.js الإصدار 18 فأحدث. الحزمة بصيغة ESM فقط — استخدم import لا require.

npm install @videohati/node

إنشاء عميل

أنشئ عميلًا واحدًا وأعد استخدامه. يتبع الوضع (live أو test) بادئة المفتاح دائمًا — فمفتاح vh_test_ يعمل مقابل بيانات الاختبار.

import { Videohati } from "@videohati/node";

const videohati = new Videohati({
  apiKey: process.env.VIDEOHATI_API_KEY, // vh_live_... أو vh_test_...
});

خيارات VideohatiOptions:

المصادقة

يصادق العميل بمفتاح API للمشروع يُرسَل رمزًا حاملًا (bearer). استخدم مفتاح ‏vh_live_ في الإنتاج ومفتاح vh_test_ مقابل بيانات الاختبار — تستنتج الحزمة الوضع من البادئة. تنشئ المفاتيح وتديرها من لوحة التحكّم.

الفيديوهات

يغطّي المورد videos دورة الحياة كاملة: الإنشاء والرفع والقراءة وإدارة الصور المصغّرة.

الرفع في استدعاء واحد

‏videos.upload(file, options) يُنفّذ تدفّق الرفع المُجزّأ كاملًا في استدعاء واحد. وfile مسار ملف أو Buffer/Uint8Array أو Blob/File.

const uploaded = await videohati.videos.upload("./lecture-01.mp4", {
  onProgress: (p) => console.log(`${p.uploadedBytes}/${p.totalBytes} bytes`),
});

// استقصِ الحالة حتى يصبح الفيديو قابلًا للتشغيل من طرف إلى طرف:
const video = await videohati.videos.waitForState(uploaded.videoId);
console.log(video.state); // "ready"

خيارات UploadOptions:

يفترض waitForState القيم targetStates: ["ready", "failed"] وintervalMs: 3000 وtimeoutMs: 900000 (15 دقيقة)؛ ويُطلق VideohatiError عند انتهاء المهلة.

ما تفعله إعادة المحاولة وما لا تفعله

مرّر idempotencyKey فتصبح الكتابتان اللتان تُنشئان حالة على الخادم — الفيديو وجلسة الرفع — آمنتين للتكرار. استدعِ upload مرة أخرى بعد إخفاق فتحصل على معرّف الفيديو نفسه وجلسة الرفع نفسها، حتى لو ضاعت استجابة المحاولة الأولى في الطريق بعد أن أثبتها الخادم فعلًا. وبغير مفتاح تصبح تلك الاستجابة الضائعة لا تُميَّز عن طلب لم يصل قطّ، فتُنشئ إعادة المحاولة فيديو ثانيًا.

ثلاثة قيود تستحقّ القراءة قبل الاعتماد عليها:

• يجب أن يبقى المفتاح حيًّا بعد ما تحاول التعافي منه. أمان إعادة المحاولة بعد إعادة تشغيل العملية لا يصحّ إلا إذا عادت القيمة نفسها بعد إعادة التشغيل، فاشتقّها من حالة دائمة — معرّف عنصر في طابور، معرّف سجلّ في قاعدة بيانات. أمّا قيمة من Math.random() أو Date.now() أو عدّاد في الذاكرة فلا تمنحك حماية إطلاقًا، لأن إعادة المحاولة تُرسل مفتاحًا مختلفًا.
• لا شيء من نقل البايتات يُستأنف. إعادة المحاولة يُعيد إرسال كل الأجزاء من البداية. الضمان يخصّ عدم تكرار الفيديو، لا توفير حجم النقل.
• المفتاح الواحد لملف واحد. تربط الحزمة المفتاح باسم الملف وحجمه (وبـ checksumSha256 إن مرّرته)، فإعادة استخدام مفتاح لملف مختلف تبدأ رفعًا جديدًا فعليًا بدل إعادة فيديو الملف الأول. ومع ذلك، فضّل مفتاحًا جديدًا لكل ملف.

// يأتي المفتاح من سجلّ المهمة، فيُعاد استخدامه بعد أي انهيار وإعادة تشغيل.
const uploaded = await videohati.videos.upload(job.path, {
  idempotencyKey: job.id,
  checksumSha256: job.sha256,
});

إعادة محاولة الإنشاء وحده

تقبل videos.create المفتاح idempotencyKey نفسه، إن كنت تُدير خطوات الرفع الثلاث بنفسك. والمطابقة على (project, idempotencyKey) بقاعدة الأسبق يفوز، والمفتاح هو الهوية كاملة — فـ originalFilename ليس جزءًا منها أبدًا. وتكرار استدعاء أُثبت يُعيد فيديو الاستدعاء الأول، بأي حالة بلغها بعد ذلك.

const { videoId } = await videohati.videos.create({
  originalFilename: "lecture-01.mp4",
  idempotencyKey: crypto.randomUUID(), // مُخزَّن مع مهمتك، لا يُولَّد من جديد
});

البحث والتصفية

‏q مطابقة سلسلة فرعية حرفية دون حساسية لحالة الأحرف على title و originalFilename — وهي ليست بحثًا تقريبيًا ولا بحثًا في النصّ الكامل، ولا تُطابق description ولا الوسوم. وtag يُعيد الفيديوهات التي تحمل ذلك الوسم بالضبط. وتُدمَج أيّ منهما مع state، ويُصفَّح الناتج بـ cursor.

const { data, nextCursor } = await videohati.videos.list({
  q: "lecture 01",
  tag: "arabic-101",
  state: "ready",
  limit: 50,
});

تحديث البيانات الوصفية

‏videos.update تحديث جزئي: أرسل أي مجموعة فرعية من title وdescription و tags وvisibility، وواحدًا منها على الأقل.

const video = await videohati.videos.update(videoId, {
  title: "المحاضرة 01 — مقدّمة",
  tags: ["arabic-101", "semester-1"],
  visibility: "unlisted",
  description: null, // يمحوه
});

الإجراءات المجمّعة

تُطبّق videos.bulk إجراءً واحدًا على 1–100 معرّف فيديو: { action: "delete" } أو { action: "set_visibility", visibility }. ويتصرّف delete تمامًا مثل videos.delete لكل معرّف.

يُستجاب للنداء بـ 200 حتى حين تفشل بعض المعرّفات، فافحص راية ok في كل عنصر — تحمل results عنصرًا واحدًا لكل معرّف مطلوب فريد، بترتيب الطلب، ويحمل العنصر الفاشل error.code وerror.message.

const { results } = await videohati.videos.bulk({
  action: "set_visibility",
  visibility: "private",
  videoIds: [videoId, otherVideoId],
});
for (const result of results) {
  if (!result.ok) console.error(result.videoId, result.error.code);
}

القراءة والحذف

const { data } = await videohati.videos.list({ state: "ready" });

const detail = await videohati.videos.get(videoId);
console.log(detail.state); // uploading | uploaded | encoding | ready | failed

await videohati.videos.delete(videoId); // حذف ناعم؛ يُلغي أي رفع نشط

التشغيل

أنشئ الجلسة في خادمك وسلّم sessionToken فقط إلى الصفحة (ضمّنها مع ‏@videohati/player أو @videohati/react).

يستدعي تطبيقك createSession فقط؛ أمّا بقية نداءات التشغيل فيتولّاها المشغّل بنفسه عبر رمز الجلسة.

معاملات createSession:

const session = await videohati.playback.createSession({
  videoId,
  watermarkText: "أحمد ك.",
});
console.log(session.sessionToken);

حدّ التزامن لكل مشاهد بلا علامة مائية

يُحسَب حدّ الجلسات المتزامنة لكل مشاهد، وتُحدَّد هوية المشاهد بهذا الترتيب: viewerId، ثم watermarkText، ثم تجزئة عنوان IP للعميل. وبغير أي من الحقلين يرتدّ كل مستخدم نهائي خلف مفتاح API واحد إلى تجزئة IP — فتنطوي شبكة مشتركة بأكملها في حدٍّ واحد مشترك.

مرّر viewerId لإصلاح ذلك مع الحفاظ على تشغيل نظيف: فهو يُعرّف المشاهد لأجل الحدّ فقط. ولا يُخزَّن أبدًا — إذ لا تصل الجلسة إلا تجزئته — ولا يرسم شيئًا. وتظهر العلامة المائية إن ضبطت watermarkText وفقط إن ضبطته، فـ viewerId وحده لا يُشعل علامة مائية أبدًا.

// حدود مستقلّة لكل مستخدم نهائي، بلا أي طبقة على الفيديو.
const session = await videohati.playback.createSession({
  videoId,
  viewerId: user.id,
});

// الاثنان معًا، حين تريد مشاهدًا معرَّفًا وعلامة مائية ظاهرة.
const identified = await videohati.playback.createSession({
  videoId,
  viewerId: user.id,
  watermarkText: user.name,
});

Webhooks

سجّل نقاط النهاية، وافحص التسليمات، وتحقّق من التواقيع. التدفّق الكامل في دليل Webhooks.

التحقّق من توقيع

يُصدَّر verifyWebhookSignature أيضًا مستقلًّا. مرّر جسم الطلب الخام — لا JSON مُعاد تسلسله.

import { verifyWebhookSignature, SIGNATURE_HEADER } from "@videohati/node";

app.post("/webhooks/videohati", (req, res) => {
  const { valid, event } = verifyWebhookSignature({
    payload: req.rawBody, // نص أو Uint8Array، كما وصل تمامًا
    header: req.headers[SIGNATURE_HEADER], // "videohati-signature"
    secret: process.env.VIDEOHATI_WEBHOOK_SECRET,
  });
  if (!valid) return res.status(400).end();
  if (event?.type === "video.encoding.ready") {
    // الفيديو جاهز — أنشئ جلسة تشغيل، أبلغ المستخدم، إلخ.
  }
  res.status(200).end();
});

الترويسة هي Videohati-Signature: t=<unix_ts>,v1=<hex_sha256> (HMAC-SHA256 على ‏<unix_ts>.<raw_body>)؛ والتحقّق ثابت الزمن ويرفض الطوابع الزمنية الأقدم من 300 ثانية (اضبطها بـ toleranceSeconds).

المشاريع ومفاتيح API

تنشئ المشاريع ومفاتيح API وتديرها من لوحة التحكّم، لا عبر الحزمة. انظر المفاهيم لمعرفة العلاقة بين الحسابات والمشاريع والمفاتيح.

الأخطاء

كل استجابة غير 2xx تُطلق فئة فرعية مكتوبة من VideohatiError، تحمل status وcode (رمز الآلة من واجهة API، مثل video_not_found). لا تحتوي الأخطاء على مفتاح API أبدًا.

import {
  VideohatiError,
  VideohatiNotFoundError,
  VideohatiRateLimitError,
} from "@videohati/node";

try {
  await videohati.videos.get(videoId);
} catch (error) {
  if (error instanceof VideohatiNotFoundError) {
    // 404 — error.code === "video_not_found"
  } else if (error instanceof VideohatiRateLimitError) {
    await sleep((error.retryAfterSeconds ?? 1) * 1000);
  } else if (error instanceof VideohatiError) {
    console.error(error.status, error.code, error.message);
  }
}

تُعاد محاولة طلبات GET وDELETE وردود 429 و5xx بتراجع أُسّي محدود بـ 8 ثوانٍ — محاولتان افتراضيًا. ويحترم ردّ 429 ترويسة Retry-After. اضبط السلوك بـ ‏maxRetries وtimeoutMs.