مرجع API

أنشئ مفتاح API من الإعدادات ← مفاتيح API. يتطلب ذلك اشتراك Pro أو Team أو Business. احتفظ بالمفتاح على خادمك أو في مخزن أسرار CI، ولا تضعه أبدًا في كود المتصفح. تستقبل حزمة javascript-obfuscator المفتاح عبر apiToken (و--pro-api-token في CLI)، أما طلب REST المباشر فيرسله في الترويسة Authorization: Bearer. وفي خطة Team أو Business، يمكن لمالك الفريق تحديد مفتاح خدمة الفريق في مربع الحوار إنشاء مفتاح API؛ وهذا المفتاح يخص الفريق لا شخصًا بعينه، لذا يظل صالحًا عند مغادرة الأعضاء.

مفاتيح API · استخدام حزمة NPM

الطلب

POST https://obfuscator.io/api/v1/obfuscate

أرسل JSON يحتوي على code وoptions. فعّل ميزة Pro واحدة على الأقل: vmObfuscation: true أو parseHtml: true، مباشرةً أو عبر إعداد مسبق. ثبّت معامل الاستعلام version للحصول على بناءات قابلة للتكرار؛ فإغفاله يعني استخدام أحدث إصدار. يقبل المعامل إصدارًا محددًا مثل 8.0.0، أو نطاقًا: ^8.0.0 يتبع الإصدارات الثانوية وإصدارات التصحيح الجديدة من 8.x، و~8.0.0 يتبع إصدارات التصحيح من 8.0.x، ويُحَل النطاق إلى أعلى إصدار مطابق. تتطلب النطاقات خطة Team أو Business.

يمكن أن تسمّي options إعدادًا مسبقًا بدلًا من سرد كل الخيارات: اضبط optionsPreset على إعداد مسبق مدمج مثل vm-default (انظر اختيار الإعدادات المسبقة) أو على الاسم المستعار لواجهة API لإعداد مسبق مخصص. يُطبَّق الإعداد المسبق المدمج كما يعرّفه إصدار المشوِّش المطلوب، ويُحَل الاسم المستعار بالرؤية نفسها التي تتبعها نقطة نهاية الإعدادات المسبقة. يكون الإعداد المسبق هو الأساس، ويتجاوز كل خيار آخر في الطلب قيمته. أما الاسم الذي لا يكون أيًّا منهما فيُفشل الطلب مع رسالة خطأ.

إذا فرض مالك الفريق إصدارًا أو إعدادًا مسبقًا، فإنه يتجاوز version أو options في الطلب بالنسبة لأعضاء الفريق ومفاتيح خدمة الفريق. راجع فرض إصدار على فريقك والإعدادات المسبقة المشتركة.

الترويسة	القيمة
Content-Type	application/json
Authorization	Bearer YOUR_API_KEY

الاستجابة

اقرأ جسم الاستجابة بصيغة JSON مفصولة بأسطر جديدة (NDJSON). قد تقسم عملية قراءة واحدة من الشبكة سطر JSON أو حرف UTF-8. التقدم لا يعني الاكتمال: اشترط وصول رسالة result أو chunk_end، واحتفظ بالحقل warnings.

يصل الناتج الصغير في رسالة result واحدة. أما الناتج الكبير فيصل على شكل رسائل chunk تليها chunk_end. تحمل كلتا الرسالتين الختاميتين الحقل version، وهو إصدار المشوِّش الفعلي الذي أنتج الناتج (مفيد عندما تطلب نطاقًا أو عندما يفرض الفريق إصدارًا). يسرد warnings تحذيرات التشويش غير القاتلة بالشكل { type, message, functionName? }، ويُحذف عند عدم وجود أي تحذير، لذا تعامل مع غياب الحقل على أنه قائمة فارغة. لا تُنتَج خرائط المصدر لبناءات VM ولا لمدخلات HTML. أما بناء parseHtml لكود JavaScript عادي مع sourceMap: true فيعيد خريطة مصدر في الحقل sourceMap من الرسالة الختامية، أو على شكل أجزاء sourceMap عندما تكون كبيرة.

تصل أخطاء التطبيق على شكل رسائل error داخل البث، وعادةً مع حالة HTTP 200. تحقّق من حالة HTTP ومن الأخطاء المبثوثة معًا. أما نقاط نهاية البنية التحتية والرفع فقد تعيد استجابات HTTP خارج نطاق 2xx.

Node.js (.mjs)

الإعدادات المسبقة

GET https://obfuscator.io/api/v1/presets/{name}

يعيد خيارات إعداد مسبق جاهزةً للإرسال بوصفها options في طلب التشويش. أرسل ترويسة Authorization: Bearer نفسها. تجري مطابقة الاسم دون تمييز بين الأحرف الكبيرة والصغيرة، والاستجابة كائن JSON واحد وليست بثًا. الأمثلة أدناه مختصرة.

• الإعدادات المسبقة المدمجة: يكون {name} إعدادًا مسبقًا مدمجًا مثل vm-default (انظر اختيار الإعدادات المسبقة). يحدد معامل الاستعلام version إصدار المشوِّش الذي يُعاد إعداده المسبق؛ ويقبل القيم نفسها التي تقبلها نقطة نهاية التشويش، وقيمته الافتراضية أحدث إصدار. تكون قيمة كل من description وupdatedAt هي null.
• الإعدادات المسبقة المخصصة: يكون {name} الاسمَ المستعار لواجهة API المضبوط في نافذة حفظ الإعداد المسبق المخصص في لوحة التحكم، وoptions هي الإعدادات المحفوظة (جميع الخيارات، لا تلك التي غُيّرت عن إعداد مسبق فقط). تتبع الرؤية ما هو معمول به في لوحة التحكم: يصل مفتاح API إلى الإعدادات المسبقة الخاصة بمستخدمه إضافةً إلى تلك التي شاركها مالك فريق هذا المستخدم، ويصل مفتاح خدمة الفريق إلى الإعدادات المسبقة الخاصة بالمالك.

GET https://obfuscator.io/api/v1/presets/vm-default

GET https://obfuscator.io/api/v1/presets/production

الحالة	المعنى
200	الإعداد المسبق.
400	الاسم غير صالح (من 1 إلى 20 حرفًا، من الأحرف a-z أو الأرقام أو الشرطات أو الشرطات السفلية، ويبدأ بحرف أو رقم)، أو أن قيمة version غير مدعومة.
401	مفتاح API مفقود أو غير صالح أو منتهي الصلاحية.
403	الحساب موقوف، أو لا يوجد اشتراك نشط، أو الخطة لا تتضمن الوصول إلى API.
404	لا يوجد إعداد مسبق مدمج بهذا الاسم في الإصدار المطلوب، ولا إعداد مسبق مخصص بهذا الاسم المستعار مرئي لهذا المفتاح.
429	تجاوز حد المعدل؛ يتشارك الطلب الحصص لكل مستخدم ولكل عنوان IP الموضحة في الحدود والإخفاقات.
500	فشل البحث عن الإعداد المسبق على الخادم. أعد المحاولة لاحقًا.

تكون الأخطاء بالشكل {"error": "..."}. توجد أمثلة الاستخدام لحزمة javascript-obfuscator وواجهة CLI الخاصة بها في استخدام حزمة NPM.

الحصة

GET https://obfuscator.io/api/v1/quota

يعيد مقدار الاستخدام المتبقي في خطتك، كي يتحقق البناء قبل أن يبدأ من أن مجموعة الملفات تتسع ضمن المتبقي، بدلًا من أن يفشل في منتصف الطريق. أرسل ترويسة Authorization: Bearer نفسها. الاستجابة كائن JSON واحد وليست بثًا، والطلب نفسه لا يُحتسب ضمن الاستخدام.

• remainingBytes: ما يمكنك استخدامه الآن، أي الأصغر بين المتبقي اليوم والمتبقي هذا الشهر. تكون قيمته null عندما لا يكون لخطتك حد.
• minBytesPerBuild: أدنى قدر يُحتسب لعملية بناء واحدة.
• daily وmonthly: البايتات المستخدمة والحد لكل نافذة زمنية، أو null عندما لا يكون لخطتك حد من هذا النوع. يشير resetsAt إلى موعد بدء النافذة من جديد، بتنسيق ISO 8601 وبتوقيت UTC: النافذة اليومية عند الساعة 00:00 UTC، والنافذة الشهرية في تاريخ الفوترة الخاص بك من كل شهر.
• في الفريق، يُبلغ مفتاح العضو عن الاستخدام الشهري المشترك للفريق وعن الاستخدام اليومي الخاص بالعضو. أما مفتاح خدمة الفريق فيُبلغ عن استخدام مالك الفريق.

تُحتسب عملية البناء بحجم مصدرها بالبايت (UTF-8)، مرة واحدة، أيًّا كانت الخيارات التي تستخدمها، وبحد أدنى قدره minBytesPerBuild. لا يُحتسب حجم الناتج. وفي ملف HTML يُبنى باستخدام parseHtml، لا تُحتسب إلا السكربتات المختارة للتشويش. اجمع عمليات البناء التي توشك على تشغيلها وقارن المجموع بقيمة remainingBytes.

عندما يُرفض بناء لأن أحد الحدود قد استُنفد، تحمل رسالة error في البث الحقل errorCode:

errorCode	المعنى
dailyLimit	استُنفد الحد اليومي. أعد المحاولة بعد daily.resetsAt.
monthlyLimit	استُنفد الحد الشهري. أعد المحاولة بعد monthly.resetsAt، أو رقِّ خطتك.
usageCheckFailed	تعذّر التحقق من الاستخدام. أعد المحاولة بعد قليل.

هذه الرموز الثلاثة ثابتة. قد تحمل أخطاء أخرى أيضًا الحقل errorCode؛ فلا تعتمد عليه.

الحالة	المعنى
200	الحصة.
401	مفتاح API مفقود أو غير صالح أو منتهي الصلاحية.
403	الحساب موقوف، أو لا يوجد اشتراك نشط، أو الخطة لا تتضمن الوصول إلى API.
429	تجاوز حد المعدل؛ يتشارك الطلب الحصص لكل مستخدم ولكل عنوان IP الموضحة في الحدود والإخفاقات.
500	تعذّرت قراءة الاستخدام. أعد المحاولة لاحقًا.

الحدود والإخفاقات

تنطبق حدود الخطة على حجم المصدر وعلى الاستخدام. أبقِ جسم JSON المتسلسل كاملًا، بما في ذلك محارف الهروب والخيارات، دون 4.4 ميغابايت. وتحتاج المصادر الأكبر إلى الرفع المؤقت، المتاح في خطتي Team وBusiness عبر حزمة javascript-obfuscator فقط. تحقّق من حدودك واستخدامك الحاليين في لوحة التحكم أو عبر نقطة نهاية الحصة. لا تُحتسب ضمن الاستخدام إلا عمليات البناء التي تُعيد كودًا مشوَّشًا؛ أما الطلب الذي ينتهي بخطأ فلا يُحتسب.

تقبل واجهة API حتى 30 طلبًا في الدقيقة لكل مستخدم، مشتركةً بين مفاتيحه، و100 طلب في الدقيقة لكل عنوان IP. تُحتسب الطلبات إلى نقطتَي نهاية الإعدادات المسبقة والحصة ضمن الحدود نفسها التي تُحتسب فيها طلبات التشويش.

يجب أن يؤدي تجاوز حد المعدل وإخفاقات الحصة وانقطاع البث إلى إيقاف البناء. أعد المحاولة عن قصد؛ فالطلب المكرر قد يستهلك استخدامًا إضافيًا. لا تنشر ناتجًا جزئيًا.

الاختبار وCI