Watch-IP

استخدام Watch-IP مع JavaScript وTypeScript

تُغلِّف @digitload/watch-ip-sdk (على npm، الإصدار v0.1.1) استدعاء GET /v1/geo ضمن عميل صغير يوفر أنواع TypeScript لكل حقل في الاستجابة، دون أي تبعيات وقت تشغيل.

التثبيت

يتطلب Node.js 18 أو أحدث، أو أي متصفح حديث — فكلاهما يوفر الدالة العامة fetch التي تُبنى عليها هذه الحزمة.

npm

npm install @digitload/watch-ip-sdk

البدء السريع

أنشئ عميلاً بمفتاحك القابل للنشر واستدعِ getGeo(). كائن GeoResponse المُعاد مُحدَّد الأنواع بالكامل؛ كل حقل باستثناء ip وisEUCountry قابل لأن يكون فارغًا (null)، لذا تحقق من الحقل قبل عرضه.

TypeScript

import { WatchIP } from "@digitload/watch-ip-sdk";

const client = new WatchIP("wip_pub_xxxxxxxx");
const geo = await client.getGeo();

console.log(geo.country, geo.city, geo.timezone);

معالجة الأخطاء والمُهل الزمنية

كل فشل — سواء طلب مرفوض (مفتاح غير صالح، نطاق غير مسموح به، تجاوز حد المعدل) أو خطأ في الشبكة — يُطلِق WatchIPError يحمل status ورمزًا ثابتًا. لا توجد مهلة زمنية مدمجة؛ مرِّر signal الخاص بـ AbortController لإلغاء طلب بطيء بنفسك.

TypeScript

import { WatchIP, WatchIPError } from "@digitload/watch-ip-sdk";

const client = new WatchIP("wip_pub_xxxxxxxx");
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

try {
  const geo = await client.getGeo({ signal: controller.signal });
} catch (err) {
  if (err instanceof WatchIPError) {
    console.error(err.code, err.status, err.message);
  }
}

الحقول الاختيارية

مرِّر include: ["hostname"] لإضافة بحث DNS عكسي لعنوان IP المتصل. وهو اختياري (opt-in) لأنه يضيف قفزة شبكية إضافية، لذا اطلبه فقط إذا كنت ستستخدم هذا الحقل.

TypeScript

const geo = await client.getGeo({ include: ["hostname"] });

ما لا تُغطيه هذه الحزمة (SDK)

لا تستدعي هذه الحزمة سوى GET /v1/geo. وليس لديها أي دوال للبحث عن عنوان IP، أو التحقق من البريد الإلكتروني، أو فحوصات المخاطر — فتلك نقاط نهاية من خادم إلى خادم تُوثَّق بمفتاح سري، لا بالمفتاح القابل للنشر الذي بُنيت حوله هذه الحزمة. استدعِها مباشرة عبر HTTP؛ راجع مرجع البحث عن عنوان IP ودليل المصادقة.

صفحات ذات صلة