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

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

TypeScript1.9.0PHP1.9

نشر المحتوى

عشرة أقسام قابلة للكتابة — المنشورات، الفعاليات، المدونات، الألبومات، المجموعات، الاستشاريون، المشاريع، المشاريع ٢، الأوسمة والمهام — بالإضافة للتعليقات والإعجابات فوقها.

ts
await gurb.tweets.create({ content: 'أهلاً بالجميع 👋' })
await gurb.events.create({ title: 'Meetup', titleArabic: 'لقاء', startDate: iso, endDate: iso })
await gurb.blogs.create({ title: 'Welcome', contentHtml: '<p>…</p>', status: 'PUBLISHED' })
await gurb.groups.create({ name: 'القراءة', description: 'نادٍ', isPrivate: false, iconUrl })
await gurb.tasks.create({ headingId: 'h1', title: 'راجع الطلبات' })
await gurb.comments.create('tweets', 't1', { content: 'شكراً' })
await gurb.likes.like('tweets', 't1')
php
$gurb->tweets->create('أهلاً بالجميع 👋');
$gurb->groups->create('القراءة', 'نادٍ', isPrivate: false, iconUrl: $iconUrl);
$gurb->tasks->create(headingId: 'h1', title: 'راجع الطلبات');
$gurb->comments->create(CommentParent::Tweets, 't1', 'شكراً');
$gurb->likes->like(LikeParent::Tweets, 't1');

معاملات الإدخال

CreateTweetInput
الحقلإلزاميالنوعالقيود
contentنعمstring—
groupIdاختياريstringPost into a group instead of the home feed. Checked against that group's own rules.
allowCommentsاختياريboolean—
CreateEventInput
الحقلإلزاميالنوعالقيود
titleنعمstring—
titleArabicنعمstringRequired. Community-internal pages are Arabic-only by design.
descriptionاختياريstring—
statusاختياريEventStatus—
startDateنعمstringISO 8601. Sent as a string; the server parses it.
endDateنعمstring—
locationاختياريstring—
isOnlineاختياريboolean—
meetingUrlاختياريstring—
registrationUrlاختياريstring—
timezoneاختياريstring—
capacityاختياريnumber—
allowCommentsاختياريboolean—
tagsاختياريstring[]—
CreateBlogInput
الحقلإلزاميالنوعالقيود
titleنعمstring—
contentHtmlنعمstringRendered HTML. The platform stores it as sent.
statusاختياري"DRAFT" | "PUBLISHED" | "ARCHIVED"`DRAFT` publishes nothing and announces nothing.
allowCommentsاختياريboolean—
CreateGroupInput
الحقلإلزاميالنوعالقيود
nameنعمstring—
nameArabicاختياريstringDefaults to `name`. The column is NOT NULL and Gurb's UI is Arabic-first.
descriptionنعمstring—
descriptionArabicاختياريstringDefaults to `description`, same reason as `nameArabic`.
isPrivateنعمbooleanRequired, deliberately. Defaulting a VISIBILITY field is how a private group gets published by accident.
memberLimitاختياريnumberThe member CAP. `-1` is unlimited and is the default; otherwise positive.
canChatاختياريbooleanDefaults to true.
emailاختياريstring—
websiteاختياريstring—
iconUrlنعمstringRequired http(s) URL — see above.
coverUrlاختياريstring—
CreateTaskInput
الحقلإلزاميالنوعالقيود
headingIdنعمstring—
titleنعمstringMax 40 characters. Surprisingly short, and not a typo.
shortDescriptionاختياريstringMax 150.
descriptionاختياريstringMax 400.
dueAtاختياريstringISO 8601.
priorityاختياري"HIGH" | "MEDIUM" | "LOW"Defaults to `MEDIUM`.
pointsاختياريnumberA non-negative integer — it feeds the member leaderboard.
estimatedMinutesاختياريnumber—
tagsاختياريstring[]—
autoAssignNewMembersاختياريbooleanFuture joiners only; suppressed inside a SPECIFIC_MEMBERS section.
CreateCommentInput
الحقلإلزاميالنوعالقيود
contentنعمstring1–800 characters after trimming.
parentCommentIdاختياريstringMust be a comment on the SAME parent. Omit for a top-level comment.

التذكير بالفعاليات والدعوة للمشاهدة (1.9.0)

events.sendReminder يرسل تذكيراً للفعالية الآن، بالقنوات التي تختارها: البريد الإلكتروني أو إشعار الجوال أو إشعار داخل المنصة. audience يختار من يصله: going (الافتراضي — المؤكدون وحاملو التذاكر)، interested، all (كل أعضاء المجتمع)، أو members مع userIds (حتى 200). message رسالة شخصية اختيارية حتى 300 حرف. يحتاج صاحب المفتاح صلاحية calendar:manage أو calendar:moderate — نفس صلاحية الزر في المنصة. تذكير يدوي واحد لكل فعالية كل 10 دقائق (EVENT_REMINDER_COOLDOWN)، و3 تذكيرات لكل الأعضاء لكل مجتمع في اليوم (REMINDER_BROAD_DAILY_LIMIT) — لا تُعِد المحاولة في الحالتين. في members يسقط بصمت من ليس عضواً ومن أخفى نفسه من الدليل.

contentInvitations.create يدعو أعضاء لمشاهدة تدوينة أو ألبوم أو فعالية أو منشور (tweet) أو مشروع (project / project2) أو مستشار (consultant). channels يختار طريقة الوصول: inApp وpush وemail — كلها إن لم تحدد. يحتاج صاحب المفتاح صلاحية إدارة قسم العنصر أو الإشراف عليه (posts وblogs وalbums وcalendar وprojects وprojects2: manage أو moderate؛ المستشارون: consultants:manage) — العضو العادي لا يدعو (403 INSUFFICIENT_PERMISSION). وصاحب المفتاح وكل مدعو يجب أن يستطيعوا فتح العنصر. الشخص يُدعى لنفس العنصر مرة واحدة، و20 مدعواً في كل استدعاء، و100 دعوة يومياً. سبب التخطي UNAVAILABLE يجمع «ليس عضواً» و«مخفي من الدليل» و«لا يستطيع فتح العنصر» عن قصد.

ts
await gurb.events.sendReminder('ev_1', {
  channels: ['push', 'inApp'], // or 'email'
  audience: 'interested',      // 'going' (default) · 'interested' · 'all' · 'members' + userIds
  message: 'لا تنسون الكتاب',
})
const { invited, skipped } = await gurb.contentInvitations.create({
  resourceType: 'project', resourceId: 'pr_1', inviteeIds: ['u_2', 'u_3'],
  message: 'شوفوا المشروع', channels: ['inApp', 'push'], // all three when omitted
})
php
$gurb->events->sendReminder('ev_1', ['push', 'inApp'], 'interested', [], 'لا تنسون الكتاب');
$res = $gurb->contentInvitations->create('project', 'pr_1', ['u_2', 'u_3'], 'شوفوا المشروع', ['inApp', 'push']);

طلبات التسجيل في الفعاليات والزوار (1.10.0)

أربعة إعدادات في الفعالية تحدد من يسجّل وكيف: guestRegistration يسمح لزائر بلا حساب أن يسجّل من رابط مشاركة الفعالية (يثبت بريده برمز من 6 أرقام)؛ وapprovalGuests وapprovalMembers يجعلان الطلب ينتظر المنظم بدل حجز المقعد فوراً؛ وregistrationQuestions هو النموذج الذي يجيب عنه الجميع (أسئلة فقط، بلا مستندات). أرسلها في events.create وevents.update — وترجع في الفعالية المكتوبة. الاعتماد للفعاليات المجانية فقط: الفعالية المدفوعة ترفضه (APPROVAL_REQUIRES_FREE_EVENT). وتسجيل الزوار يعمل في الاثنتين — في المدفوعة يدفع الزائر سعر التذكرة من الصفحة المشتركة (1.10.0).

events.listRegistrations يقرأ طلبات الفعالية — status هو PENDING (الافتراضي) أو GOING أو DECLINED أو ALL، وcounts فيه العدد لكل حالة مهما كان التصفية. كل عنصر فيه userId والاسم كما يعرفه هذا المجتمع وisGuest وanswers والقرار. approveRegistration يحجز المقعد (والتذكرة)؛ وdeclineRegistration نهائي، وسببه reason الاختياري يصل للشخص. يحتاج صاحب المفتاح صلاحية calendar:manage أو calendar:moderate — نفس صلاحية «طلبات التسجيل» في المنصة — والاعتماد والرفض يحتاجان مفتاحاً فيه نطاق write.

ts
await gurb.events.update('ev_1', { guestRegistration: true, approvalGuests: true })

const { items, counts } = await gurb.events.listRegistrations('ev_1') // PENDING by default
for (const r of items) {
  if (r.isGuest && r.answers) await gurb.events.approveRegistration('ev_1', r.userId)
}
await gurb.events.declineRegistration('ev_1', 'u_9', { reason: 'المقاعد مخصصة لجهات محددة' })
php
$gurb->events->update('ev_1', ['guestRegistration' => true, 'approvalGuests' => true]);

$list = $gurb->events->listRegistrations('ev_1'); // PENDING by default
foreach ($list->items as $r) {
    if ($r->isGuest && $r->answers !== null) $gurb->events->approveRegistration('ev_1', $r->userId);
}
$gurb->events->declineRegistration('ev_1', 'u_9', 'المقاعد مخصصة لجهات محددة');

حين يُرفض القرار

EVENT_FULL (400) — لا يوجد مقعد للاعتماد فيه. REGISTRATION_NOT_PENDING (409) — قرّر أحد قبلك؛ اقرأ القائمة من جديد بدل إعادة المحاولة. EVENT_NOT_BOOKABLE (409) — الفعالية أُلغيت أو انتهت.

الرفع غير مدعوم بعد

هذه المسارات نصية وJSON فقط. الألبوم يُنشأ فارغاً، والمنشور بلا مرفق، وأيقونة المجموعة رابط لا ملف، وما فيه إنشاء إعلان أصلاً — لأن الإعلان هو صورته. الرفع يحتاج محاسبة على حصة التخزين غير مطبّقة هنا، وشحنه بدونها يخلي المجتمع يتجاوز ما تدفع خطته مقابله بصمت.

شكلان سيبدوان كأنهما أخطاء

المشاريع تستقبل name وتُرجع title. العمود اسمه name وكل استجابة تسميه title. إرسال title لا يضبط شيئاً والنداء يفشل لغياب name.

ts
const project = await gurb.projects.create({ name: 'مشروع', description: '…' })
project.title   // ← the same value, under a different name

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

awards.create · awards.update · awards.delete