API Contracts

ستّ endpoints: القائمة (مع scope)، الملخّص (شرائط الهبوط)، التفاصيل، التقديم، تَحميل ics (مُتولَّد جانب-الخادم)، و iCal feed عام لكل scope (مُخَطَّط، انظر roadmap).

1 · GET /api/calendar/events — القائمة

• Query: scope (all|country|category|audience|stage|time)، scopeValue?، country (csv)، category (csv)، audience (csv)، stage (csv)، status، mode (physical|online|hybrid)، sort (start-asc افتراضي|start-desc|deadline-asc|created-desc)، page، pageSize، lang.
• عناصر الاستجابة: { id، slug، title، shortDescription، status، category {slug، label، iconKey}، country {code، name}، city، mode، startDate، endDate?، applicationDeadline?، registrationDeadline?، organizer {name، logoUrl}، isFeatured، isSpotlight، audiences[]، stages[]، coverImageUrl }.
• Cache: 60s public + 180s s-maxage (التقويم يُحَدَّث بشكل متكرّر).

2 · GET /api/calendar/summary

• يُرجع شرائط صفحة-الهبوط: { thisWeek[]، closingSoon[]، spotlight?، countryCounts (عدد فعاليات لكل دولة)، categoryCounts (عدد فعاليات لكل فئة)، totalUpcoming }.
• Cache: 60s — العَدَّادات يجب أن تَعكس الفعاليات التي تَنقلب إلى closing-soon فوراً.

3 · GET /api/calendar/events/{slug}

• الاستجابة: CalendarEvent كامل + relatedEntities مُحَلَّة + coverage[] (كل CoverageArticle بـ parentEventId = this.id) + seo.
• Cache: 300s + 1800s s-maxage. أبطل عند update أو نشر/إلغاء نشر coverage يَلمس هذه الفعالية.

4 · POST /api/calendar/events/submissions

• الـ Body: حمولة تقديم-فعالية كاملة (انظر حقول النموذج §13.4.2). الخادم يَتحقّق من الحقول المطلوبة + على الأقل URL خارجي واحد + title/short-description bilingual موجودة.
• الخادم: يَكتب صف CalendarEvent مع verificationStatus=pending، يَكتب صف تدقيق CalendarEventSubmission، يُدرج 2 emails (تأكيد المُقدِّم + تنبيه فرز admin).
• حد المعدّل: 3 تقديمات/IP/يوم. 429 عند ضرب الحد. CAPTCHA مطلوب لـ IP بـ ≥2 تقديم/يوم.
• الاستجابة: 201 { submissionId، eventId، status: 'pending' }.

5 · GET /api/calendar/events/{slug}/ics

• يُرجع text/calendar VEVENT. Cache 300s. اسم الملف: {slug}.ics. يُطلق حدث تحليلات calendar_ics_download عند فَتح أو نقر العميل.