معالجة نتائج مهام CAPTCHA بأمان في TypeScript

استخدم TaskRequest الذي تصدّره حزمة SDK للمدخلات وTaskResult للاستجابات. يتيح تضييق النوع حسب الحالة لـ TypeScript التمييز بين العمل غير المكتمل والفشل والجاهزية دون any أو تحويل نوع لا يفعل سوى مطالبة المترجم بالوثوق بك.

import { Solvethree, type TaskRequest, type TaskResult } from '@solvethree/sdk';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY! });
const input: TaskRequest = { site: 'accounts.example.com', action: 'login', proxy: process.env.SOLVETHREE_PROXY! };
function inspect(result: TaskResult): void {
  switch (result.status) {
    case 'pending':
    case 'solving':
      console.log('Retrieve this task again:', result.id);
      return;
    case 'failed':
      console.error('Failed task:', result.id, result.errorCode);
      return;
    case 'ready':
      // Solution fields depend on the requested product; check optional fields.
      if (!result.solution.token || !result.solution.userAgent || !result.solution.secChUa) {
        throw new Error('Expected a complete reCAPTCHA solution');
      }
      console.log('Ready task:', result.id);
      // Submit token privately with its browser identity and original proxy.
      return;
  }
}
inspect(await client.createTask(input, { waitMs: 0 }));
// Save the returned ID and call getTask while pending/solving with a deadline.

ينشئ المثال مهمة واحدة ويفحص الاستجابة الفورية. تعني الحالتان pending وsolving ضرورة استرجاعها مجددًا؛ وتوقف failed المعالجة؛ أما ready فتنتقل إلى فحوص الحل. إذا فصلت فرع الحالة الجاهزة في دالة مساعدة، فاستخدم النوع المُصدَّر ReadyTask لمعاملها. يضيّق ذلك نطاق الحالة، لكنه لا يجعل جميع حقول الحل الخاصة بكل منتج إلزامية.

تتحقق شروط الحماية من وجود رمز وكلا حقلي هوية المتصفح لأن هذه المدخلات تطلب reCAPTCHA. لكنها لا تثبت أن الجهة المستهدفة ستقبل الرمز. يتعمد المثال عدم طباعة الرمز.

• استخدم Node.js 22+ وثبّت حزمة SDK الرسمية من أرشيف tarball كما هو موثق في وثائق API؛ ولا تفترض وجود إصدار في سجل npm.
• اضبط SOLVETHREE_API_KEY وSOLVETHREE_PROXY في بيئة الخادم. لا تتحقق تأكيدات ! من غياب متغيرات البيئة وقت التشغيل.
• استبدل accounts.example.com وlogin باسم المضيف والإجراء المقصودين. يجب أن يكون للموقع ملف تعريف نشط في مساحة العمل مسبقًا؛ راجع إعداد ملف تعريف الموقع.

يترك المثال الاستطلاع للجهة المستدعية. أبقِ الإنشاء خارج تلك الحلقة: استدعاء createTask مجددًا ليس طريقة للتحقق مما إذا كانت المهمة الأولى قد انتهت.

1. 1.

   احفظ المعرّف من نتيجة الإنشاء

   تحقق من أن المعرّف المُعاد سلسلة نصية غير فارغة قبل استخدامه للاسترجاع. أبقِه مرتبطًا بالطلب الأصلي، الذي ستحتاج إليه أيضًا عند اختيار الوكيل الناجح.

2. 2.

   استرجع المهمة نفسها

   استدعِ getTask بالمعرّف المحفوظ ما دامت الحالة pending أو solving، مع تحديد مهلة نهائية محلية. قبل معالجة كل استجابة، تحقق من تطابق معرّفها مع المعرّف المحفوظ. يحدد تطابق المعرّف المهمة التي تتعامل معها، لا ما إذا كانت قد نجحت.

3. 3.

   توقف عند نتيجة نهائية

   عند ready، تحقق من الحقول التي يتطلبها المنتج المطلوب. وعند failed، افحص كلًا من errorCode وerror، ثم توقف عن استطلاع حالة تلك المهمة. تعامل مع أخطاء الطلبات على حدة: فشل طلب الاسترجاع لا يُعد بحد ذاته فشلًا نهائيًا للمهمة.

إذا انتهت مهلة الإنشاء قبل تلقي معرّف، فلا تفترض أنه لم تُنشأ أي مهمة. إذا كنت قد أرسلت requestId، فإن إعادة إرسال الطلب المطابق بالقيمة نفسها تستعيد المهمة الموجودة. تؤدي إعادة استخدامه مع مدخلات معدّلة إلى تعارض؛ ولا يؤدي إنشاء قيمة جديدة إلى استعادة المهمة الأصلية.

اختر المعالج بناءً على الطلب الأصلي، ثم تحقق من حقول الحل المتوقعة. لا يكفي وجود رمز وحده للتمييز بين استجابة reCAPTCHA وقيمة ملف تعريف ارتباط TMPT.

يدعم Kasada المستقل حاليًا وجهات HTTPS على www.ticketmaster.com، وليس أي موقع آخر. معالج ترويساته ليس تكاملًا عامًا مع Kasada.

لكل منتج، أرسل الطلب باستخدام userAgent وsecChUa المُعادين والوكيل الناجح. عند استخدام وكلاء مرشحين، استخدم successfulProxy(originalTask, readyResult) بدلًا من افتراض نجاح المرشح الأول. لا تطبّق حزمة SDK الحل على الجهة المستهدفة نيابةً عنك، ولا تضمن ready قبول ذلك الطلب اللاحق.