Developer Page Specifications
API Contracts
4 endpoints. Lead capture is consent-gated + rate-limited 5/IP/hour.
مكتمل
أربع endpoints: القائمة، التفاصيل، التقاط-العميل (POST)، و قياسات جلسة-القارئ (POST). التقاط-العميل محدود-المعدّل وله تحقّق موافقة صارم.
1 · GET /api/founder-files
- Query: category? · topic? · sort (newest|featured-first|most-downloaded) · page · pageSize · lang.
- عناصر الاستجابة: { id، slug، number، title، bestForTagline، category، topics[]، readingTimeMinutes، coverImageUrl، hasSponsor (bool)، sponsor {name، logoUrl}?، isFeatured، downloadCount }.
- Cache: 300s public + 900s s-maxage.
2 · GET /api/founder-files/{slug}
- Query: lang · variant ('details' | 'reader'، افتراضي 'details'). variant='reader' يُرجع الـ ReaderBodyHtml كامل؛ variant='details' يَستثنيه (الجسم كبير، وَفِّر bandwidth على السطح التسويقي).
- الاستجابة: { ...FounderFile الأساسي، title، bestForTagline، subtitle?، learningPoints[]، bestForBullets[]، artifacts[]، authors[] (كروت Founder)، topics[]، sponsor?، readerBodyHtml? (حين variant=reader)، connectedSignals[]، relatedFiles[]، seo {metaTitle، metaDescription، jsonLd} }.
- Cache: 600s public + 1800s s-maxage.
3 · POST /api/founder-files/{id}/leads
- الـ Body: { email، name، role، country، stage?، consentPlatform (يجب true)، consentPartners (افتراضي false)، source: 'details' | 'reader' }.
- الخادم: يَتحقّق من البريد + consentPlatform=true، يَكتب صف FounderFileLead (مع التقاط IP + UserAgent)، يَزيد DownloadCount، يُدرج بريد التحميل + webhook لـ sponsor-CRM لو consentPartners=true.
- حد المعدّل: 5 leads/IP/ساعة. 422 مع أخطاء الحقول عند فشل التحقّق. 429 عند ضرب حد المعدّل.
- الاستجابة: 201 { leadId، downloadCount (بعد-الزيادة) }.
4 · POST /api/founder-files/{id}/reader-telemetry
- الـ Body: { sessionId، scrollDepthPct (0-100)، completed (bool)، durationMs }. مجهولة حين لا lead. Idempotent على (sessionId، fileId).
- يُطلَق عند visibility-change + معالم scroll (25/50/75/complete). الخادم يَكتب/يُحَدِّث FounderFileReadSession.