وثائق المطورين

حزمة رسمية للـ TypeScript وأخرى لـ PHP. نفس العقد، نفس المسارات، نفس الصلاحيات التي يفحصها تطبيق قُرب نفسه.

TypeScript1.9.0PHP1.9

أحداث الشريك

أحداث موقّعة من خادمك تخبر قُرب خلال ثوانٍ من يحق له البقاء في مجتمعك، وما اسمه وبريده وصورته.

لماذا أحداث وليس سؤالاً عند كل زيارة

قُرب لا يتصل بموقعك أبداً. أنت ترسل كل تغيير لحظة حفظه، ولقطة ليلية تصلح أي شيء فات. هكذا يبقى موقعك المرجع الوحيد دون أن يتوقف المجتمع على عمل موقعك.

الطلب

عنوان واحد لكل مجتمع. المحتوى ⁦JSON⁩، والترويسات الثلاث ⁦webhook-⁩* وفق مواصفة ⁦Standard Webhooks⁩.

http
POST https://community.example.com/api/webhooks/inbound/{communityId}/host
content-type: application/json
webhook-id: evt_6f1c2a…              # = the body's "id", the same on every retry
webhook-timestamp: 1791808447        # unix seconds, fresh on every try
webhook-signature: v1,K3x0…=         # one "v1,…" per secret, space-separated

{
  "id": "evt_6f1c2a…",
  "type": "access.changed",
  "created_at": "2026-10-12T09:15:02.418Z",
  "community": "{communityId}",
  "data": { "sub": "yourorg_9b1e…", "state_version": 1791808447123, "access": "blocked" }
}

التوقيع

وقّع النص ⁦id.timestamp.body⁩ بخوارزمية ⁦HMAC-SHA256⁩ باستخدام سر الأحداث بعد فك ترميز ⁦base64⁩ لما يلي البادئة ⁦whsec_⁩، وأرسله بترميز ⁦base64⁩ مسبوقاً بـ ⁦v1,⁩. أي مكتبة ⁦Standard Webhooks⁩ تفعل ذلك تماماً.

ts
import { createHmac } from 'node:crypto'

// secret = "whsec_<base64>": sign with the DECODED bytes after the prefix
const key = Buffer.from(secret.slice('whsec_'.length), 'base64')
const signature = 'v1,' + createHmac('sha256', key)
  .update(`${id}.${timestamp}.${body}`)   // body = the exact bytes you send
  .digest('base64')
  • وقّع البايتات التي ترسلها كما هي. احفظ المحتوى مرة واحدة، ولا تعِد بناءه من حقوله عند إعادة المحاولة.
  • استخدم طابعاً زمنياً جديداً في كل محاولة؛ يرفض قُرب ما يبعد أكثر من 5 دقائق عن ساعته. وأبقِ المعرّف نفسه، فتُطبَّق إعادة المحاولة مرة واحدة.
  • أثناء تبديل السر، وقّع بالسرّين معاً: قيمتان ⁦v1⁩ بينهما مسافة. يقبل قُرب التطابق مع أي سر ما زال لديه.

أنواع الأحداث

كل حدث عن عضو يحمل ⁦sub⁩ — المعرّف نفسه الذي أرسلته في ⁦externalUserId⁩ — و⁦state_version⁩.

النوع⁦data⁩ما يفعله قُرب
access.changedsub, state_version, access«⁦blocked⁩»: تنتهي كل جلسات العضو فوراً ويُرفض دخوله. «⁦allowed⁩»: يستطيع الدخول من جديد دون خطوة موافقة.
member.session_revokedsub, state_version, reasonينهي كل جلسات العضو في قُرب أياً كان الإصدار. أرسله بعد استعادة كلمة المرور أو تغيير البريد لديك.
member.updatedsub, state_version, name, email, avatar_urlيستبدل اسم العضو وبريده وصورته في مجتمعك.
member.deletedsub, state_version, requested_atطلب حذف معتمد: تُمحى بيانات العضو الشخصية في المجتمع ويُنسى الربط. لا رجعة فيه.
access.snapshotsnapshot_id, generated_at, page, pages, members[]القائمة الكاملة لحسابات أعضائك كل ليلة، على صفحات. الأعضاء الذين يعرفهم قُرب ولا يظهرون في لقطة مكتملة يُحظرون.
pingmessageلا يغيّر شيئاً. استخدمه لاختبار العنوان والسر والتوقيع.

⁦state_version⁩: الأحدث هو الذي يُعتمد

عدد صحيح يزيد دائماً لكل عضو؛ وقت التغيير بالملّي ثانية يصلح لذلك. يحتفظ قُرب بالأحدث الذي وصله، فقد تصل الأحداث مرتين أو بغير ترتيبها: المكرر أو الإصدار الأقدم يُقبل ولا يغيّر شيئاً.

الردود

رمز الحالة يحدد ما يفعله العامل لديك بعدها. ومع كل رفض رمز ثابت في المحتوى.

الحالةالمعنىماذا تفعل
200قُبل.علّمه مُسلَّماً.
400الحدث غير سليم: ⁦HOST_EVENT_INVALID⁩، أو ⁦HOST_EVENT_ID_MISMATCH⁩ (المعرّف يختلف عن ترويسة ⁦webhook-id⁩)، أو ⁦HOST_EVENT_COMMUNITY_MISMATCH⁩.لا تُعِد المحاولة. نبّه شخصاً: الحدث أو الإعداد خاطئ.
401⁦WEBHOOK_SIGNATURE_INVALID⁩: سر خاطئ، أو محتوى تغيّر، أو طابع زمني يبعد أكثر من 5 دقائق.لا تُعِد المحاولة. نبّه شخصاً: الحدث أو الإعداد خاطئ.
404⁦WEBHOOK_PROVIDER_UNKNOWN⁩: معرّف مجتمع خاطئ، أو لم يُعيَّن له سر أحداث بعد.لا تُعِد المحاولة. نبّه شخصاً: الحدث أو الإعداد خاطئ.
429طلبات كثيرة: أكثر من دفعة 500 بمعدل 50 في الثانية.أعد المحاولة مع تباعد.
500 / 503عطل مؤقت لدى قُرب (503 ⁦HOST_EVENT_NOT_YET_SUPPORTED⁩: نوع حدث أحدث لا يطبّقه قُرب بعد).أعد المحاولة مع تباعد.

ومحتوى الرد 200 يخبر بما حدث: ⁦applied⁩ (طُبّق)، أو ⁦duplicate⁩ (مكرر)، أو ⁦stale⁩ (إصدار أقدم)، أو ⁦unknown_member⁩ (لم يدخل هذا الشخص المجتمع قط، فلا شيء يُفعل)، أو ⁦ignored⁩ (تُجوهل).

الإرسال

  • مهلة 10 ثوانٍ لكل محاولة.
  • تباعد 1 دقيقة ← 5 دقائق ← 30 دقيقة ← ساعتان ← 6 ساعات ← 12 ساعة ← 24 ساعة، ثم كل 24 ساعة، لمدة 72 ساعة إجمالاً. بعدها أوقف الحدث جانباً ونبّه شخصاً.
  • مُرسِل واحد لكل حدث: احجز الصفوف حتى لا يرسل عاملان الحدث نفسه.
  • لا تحويلات: رد ⁦3xx⁩ يعني إعداداً خاطئاً، وليس انتقالاً.

اكتب الحدث في نفس العملية مع التغيير

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

⁦member.updated⁩

استبدال كامل: أرسل كل حقل تشاركه في كل مرة. الحقل المحذوف يعني أنه فارغ.

  • ⁦name⁩: بحد أقصى 200 حرف.
  • ⁦email⁩: إن حُذف أو كان مستخدماً في حساب آخر على قُرب، يبقى للعضو عنوان بديل. لا تُدمج الحسابات أبداً.
  • ⁦avatar_url⁩: عبر ⁦https⁩ على المنفذ 443 فقط. يجلب قُرب الصورة مرة واحدة (⁦JPEG⁩ أو ⁦PNG⁩ أو ⁦WebP⁩، بحد أقصى 2 ميغابايت)، ويعيد ترميزها بمقاس 512 بكسل ويحفظ نسخته الخاصة. وإن فشل الجلب تبقى الصورة السابقة.
  • أرسله فقط والعضو يملك حق الدخول. لا سبب لخروج بيانات شخصية من موقعك عن شخص لا يستطيع الدخول.

⁦access.snapshot⁩

مرة كل ليلة، أرسل القائمة الكاملة لحسابات الأعضاء مع حالة الوصول الحالية و⁦state_version⁩. هي آلية الإصلاح: ما فات أي حدث تصلحه اللقطة.

  • صفحات بحد أقصى 500 عضو، وبحد أقصى 1000 صفحة، كلها بنفس ⁦snapshot_id⁩ و⁦generated_at⁩. الترتيب لا يهم.
  • ⁦generated_at⁩ وقت بصيغة ⁦RFC⁩ 3339 مع ⁦Z⁩ أو فرق التوقيت، لا يتقدم أكثر من 5 دقائق، ولا يزيد عمره عند الإرسال على 72 ساعة.
  • عندما تصل كل الصفحات، يُحظر الأعضاء الذين يعرفهم قُرب ولا يظهرون في القائمة؛ لذلك أدرج كل حسابات الأعضاء وليس الفعّالة فقط. ولا يُحظر بالغياب عضو كان أول دخول له قبل ⁦generated_at⁩ بأقل من 10 دقائق، أو بعده.
  • حدث الوصول الأحدث يتقدم على اللقطة لذلك العضو.

مكابح الأمان

إن كان إكمال لقطة سيحظر أكثر من 10% من أعضاء المجتمع المعروفين، لا يحظر قُرب أحداً ويحتجزها لمسؤول في قُرب. وأي تغيير يزيد على 1% يطلق تنبيهاً لدى قُرب في كل الأحوال. ملف تصدير معطوب لا يستطيع إفراغ مجتمعك في ليلة.

الحذف

أرسل ⁦member.deleted⁩ فقط لطلب حذف معتمد، مع ⁦requested_at⁩ بوقت تقديم الطلب. يمحو قُرب بيانات العضو الشخصية في المجتمع ويزيل الربط. لا رجعة فيه؛ ولا ترسل بعده شيئاً عن ذلك الـ ⁦sub⁩.

باستخدام حزم المطورين

الحزمتان تبنيان هذه الأحداث وتوقعانها وترسلانها، وترفضان محلياً ما سيرفضه قُرب. البناء لا يرسل شيئاً — احفظ الناتج في جدول الصادر؛ والإرسال لا يعيد المحاولة من تلقاء نفسه.

ts
import { GurbPartnerEvents } from '@gurb/server'   // ≥ 1.8.0

const events = new GurbPartnerEvents({
  communityId: process.env.GURB_COMMUNITY_ID!,
  secret: process.env.GURB_EVENTS_SECRET!,          // whsec_… — during a rotation: [newest, previous]
  baseUrl: 'https://community.example.com',
})

// 1. Build — pure. Store it in YOUR outbox, in the same transaction as the change.
const evt = events.accessChanged({ sub, stateVersion: Date.now(), access: 'blocked' })
await tx.outbox.insert({ id: evt.id, payload: JSON.stringify(evt) })

// 2. Send — from your worker. Never throws for HTTP or network failures.
const result = await events.send(JSON.parse(row.payload))
if (result.outcome === 'delivered') markDelivered(row)       // applied, duplicate, stale, unknown member
else if (result.outcome === 'retry') scheduleRetry(row)      // 408 / 429 / 5xx / network
else alertHuman(row, result.code)                            // 400 / 401 / 403 / 404
php
use Gurb\{GurbPartnerEvents, PartnerEvent, PartnerSendResult};   // gurb/sdk ≥ 1.8

$events = new GurbPartnerEvents(
    getenv('GURB_COMMUNITY_ID'),
    getenv('GURB_EVENTS_SECRET'),            // during a rotation: [$newest, $previous]
    'https://community.example.com',
);

$event = $events->accessChanged($member->externalId, $member->version, 'blocked');
$outbox->insert($event->id, json_encode($event->toArray()));

$result = $events->send(PartnerEvent::fromArray(json_decode($row->payload, true)));
match ($result->outcome) {
    PartnerSendResult::DELIVERED => $outbox->markDelivered($row),
    PartnerSendResult::RETRY     => $outbox->scheduleRetry($row),
    PartnerSendResult::REJECTED  => $alerts->raise($row, $result->code),
};
الدالةمتى
accessChangedعند كل تغيير في وصول العضو.
sessionRevokedأنهت استعادة كلمة المرور أو تغيير البريد دخول العضو لديك.
memberUpdatedتغيّر حقل مشترك: الاسم أو البريد أو الصورة.
memberDeletedطلب حذف معتمد.
snapshotكل ليلة. تعيد كل صفحات القائمة الكاملة.
ping«اختبار الاتصال».

الحدود

الحدالقيمة
⁦sub⁩، عدد الأحرف255
⁦name⁩، عدد الأحرف200
⁦avatar_url⁩، عدد الأحرف2048
ملف الصورة⁦JPEG⁩ أو ⁦PNG⁩ أو ⁦WebP⁩ · ≤ 2 ميغابايت
أعضاء في صفحة اللقطة500
صفحات في اللقطة1000
فرق الساعة المسموح (⁦webhook-timestamp⁩)± 5 دقائق
⁦generated_at⁩≤ 5 دقائق للأمام · ≤ 72 ساعة عمراً
الطلباتدفعة 500 · 50 في الثانية
مدة إعادة المحاولة لديك72 ساعة

تبديل سر الأحداث

  1. يصدر قُرب سراً جديداً ويُبقي السابق صالحاً.
  2. توقّع بالسرّين (الأحدث أولاً)، ثم بالجديد وحده.
  3. يُلغي قُرب السر السابق. لا يُرفض أي حدث في أي لحظة.