عن المشروع

sightings هي مكتبة تحاليل صفحات خفيفة الوزن ومعدّلة بـTypeScript. تتتبع الزيارات دون كتابة أي شيء على جهاز المستخدم—بدون كوكيز أو localStorage أو بصمات—وتُخزن جميع السجلات مباشرة في قاعدة بياناتك. يعتمد التصميم على اعتبار كل زيارة "رؤية": مجرد ملاحظة حدوث زيارة، دون ارتباط بهوية. يستخدم التعرف على الزائر hash SHA-256 مملح مشتقًا من IP وعنوان المستعرض ومفتاح سري ويوم UTC، مختزل إلى 128 بت ومُدار يوميًا. تفرض المكتبة حدود بيانات صارمة: تتم رفض معاملات الاستعلام غير المدرجة في القائمة المسموح بها، ويقتصر مخزن الإحالة على أسماء النطاقات، ولا توجد حمولات أحداث مخصصة—فإضافة أي حقل إلى جسم الإشارات يعيد خطأ 400 بدلاً من تسجيل مقياس جديد. يميّز المكتبة بين جزأين من حركة المرور يخلط معظم الأدوات بينهما. يرسل الزوار البشريون طلب sendBeacon واحدًا لكل تصفّح، ويُحتسب على الخادم. أما عناكب البحث والوكلاء الذكيون (مثل gptbot وclaudebot وperplexitybot وtelegram-preview) فلا ينفذون JavaScript من جانب العميل أبدًا، لذا يتم اكتشافهم واحتسابهم في middleware باستخدام تصنيف العائلات بدلاً من سلاسل عنوان المستعرض الخام. هذا يجعل قياس ما إذا كانت نماذج الذكاء الاصطناعي قد قامت بعملية زحف فعلية لمحتواك أمرًا عمليًا. يعمل الحزمة الأساسية في أي بيئة تدعم Request/Response وقائمة Web Crypto—Node وDeno وBun وVercel Edge وCloudflare Workers. تشمل التكاملات الرسمية @sightings/next (معالج Next.js App Router وmiddleware) و@sightings/prisma (مدخل Prisma مع نموذج schema). يمكن تنفيذ محولات تخزين مخصصة بتوفير طريقة record() فقط وأسلوب summary() اختياريًا. تحكم خيارات التكوين الرئيسية في مسار API الأساسي، وإخفاء المسارات (مثل استبعاد شجرتي /admin و/invite)، وقائمة معاملات الاستعلام المسموح بها (افتراضيًا utm_* وref)، واكتشاف عائلات العناكب، ونافذة hash الزائر (يومياً افتراضياً أو ساعةً)، وأولوية رؤوس IP والدولة، والتعامل مع الأخطاء. توفر واجهة api.summary() مضمنة لوحات عرض مجمعة عبر نطاقات زمنية مع إمكانية تصفية الروبوتات عن البشر. كما يمكن الوصول إلى طرق التسجيل المباشر لسياقات SSR أو الأطر غير HTTP أو عمليات الإعادة الملء. يستخدم المستودع changesets لل_versions المشترك_ عبر حزمه الثلاث وينشر tarballs مرتبطة بالأصل عبر CI. الفئة: data | الفئة الفرعية: analytics-bi