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

Docs

بدء سريع، وأربع SDKs، و16 وحدة، ونحو 270 نقطة نهاية. نسخة تجريبية مغلقة — ننشر ما يُشحَن فعلاً، لا ما نتمنّى وجوده.

Quickstart

أول حدث في دقائق

تثبيت ← تهيئة ← تتبّع. تُخاط هوية الويب والخادم نيابةً عنك، ويُفرَض عقد السجلّ في الـ CI.

01
ثبّت الحزم
Bun أو pnpm أو npm — الخيار لك. حزمة المتصفّح بلا تبعيّات بحجم 8.1 KB مضغوطة، والـ SDK الخادمي مُختبَر على Node 20+ وBun.
```
bun add @gurulu/web @gurulu/node
```
02
تتبّع في المتصفّح
هيّئ بـ publicKey — وكل ما عداه تلقائي: anonymous_id (UUIDv7)، الجلسة، حالة موافقة GCM v2، و5 إشارات التقاط تلقائي (click وpageview وform_submit وscroll وrage_click).
```
import { gurulu } from '@gurulu/web';

gurulu.init({
  publicKey: 'pk_live_xxx',
  endpoint: 'https://ingest.gurulu.io',
});

gurulu.track('signup_completed', { plan: 'pro' });
```
03
تحقّق من النتائج من جهة الخادم
أرسِل أحداث حركة الأموال وأحداثاً بأسلوب signup_completed من خادمك — كي لا يستطيع متصفّح المستخدم تزييفها. الحقل personId مطلوب، ومن هنا ينطلق الإسناد.
```
import { gurulu } from '@gurulu/node';

const client = gurulu({
  secretKey: process.env.GURULU_SECRET_KEY,
});

await client.track('purchase_completed', {
  personId: user.id,
  amount: 149,
  currency: 'EUR',
});
```
04
استخدم السجلّ كعقد
أسماء الأحداث ليست سلاسل حرّة — بل مُولَّدة بأنواع مُحكَمة من السجلّ. شغّل `gurulu validate` في الـ CI، وانحراف العقد يُفشِل الـ PR.
```
gurulu pull               # registry → typed code-gen
gurulu validate           # contract drift check
gurulu push events.ts     # add/update event contracts
```

SDKs وأدوات

4 قنوات، 4 حزم

Script (متصفّح)، وSDK (خادم)، وCLI (سجلّ)، وMCP (Cursor وClaude Code وLovable). جميعها علنية على NPM.

خادم MCP

@gurulu/mcp-server

أدوات list_events وadd_event وvalidate_event. يستطيع محرّر الذكاء الاصطناعي خاصتك قراءة السجلّ — فيكفّ عن تخمين `bet.placed` ويستخدم `bet_placed` من السجلّ.

claude mcp add gurulu -- npx -y @gurulu/mcp-server

Cursor / Claude Code / LovableDetails

Web SDK

@gurulu/web

حزمة متصفّح بلا تبعيّات. 5 إشارات التقاط تلقائي + تتبّع يدوي + identify + موافقة + إعادة عرض جلسة اختيارية (المرحلة 2). أو أدرج وسم سكربت واحداً عبر CDN الخاص بـ t.js.

bun add @gurulu/web

8.1 KB gzipDetails

Server SDK

@gurulu/node

تحقّق من النتائج قائم على secretKey، وتفريغ دفعي، و23 مُحقِّق webhook (Stripe وShopify وLemonSqueezy وCustom و19 آخرين) ووسيط Hono/Express/Fastify.

bun add @gurulu/node

Node 20+ · Bun · EdgeDetails

CLI

@gurulu/cli

gurulu init / pull / push / validate / doctor. يربط السجلّ بتدفّق Git خاصتك — events.ts هو مصدر الحقيقة، والانحراف يُلتقَط في الـ CI.

bun add -g @gurulu/cli

@gurulu/cliDetails

كتالوج الوحدات

المرحلة 0 + المرحلة 1 — 16 وحدة

كم جدول Postgres، وعرض ClickHouse، ونقطة نهاية REST تشحنها كل وحدة — بنظرة واحدة.

Module

Package

Endpoints

Phase

M01

auth-tenant@gurulu/auth

@gurulu/auth

10 PG

—

22 EP

M02

storage@gurulu/db

@gurulu/db

1 PG

12 CH

—

M03

observability-own@gurulu/observability

@gurulu/observability

—

3 CH

5 EP

M04

consent-engine@gurulu/consent

@gurulu/consent

5 PG

—

15 EP

M05

identity-engine@gurulu/identity

@gurulu/identity

6 PG

2 CH

8 EP

M06

event-registry@gurulu/registry

@gurulu/registry

6 PG

—

19 EP

M07

event-health@gurulu/health

@gurulu/health

5 PG

4 CH

11 EP

M08

attribution-engine@gurulu/attribution

@gurulu/attribution

4 PG

3 CH

20 EP

M09

ingest-api@gurulu/ingest

@gurulu/ingest

4 PG

3 CH

11 EP

M10

event-pipeline@gurulu/pipeline

@gurulu/pipeline

2 PG

3 CH

5 EP

M11

sdk-web@gurulu/web

@gurulu/web

—

M12

sdk-server@gurulu/node

@gurulu/node

—

M13

playground@gurulu/playground

@gurulu/playground

4 PG

—

16 EP

M14

cli-mcp@gurulu/cli + mcp-server

@gurulu/cli + mcp-server

—

15 EP

M15

dashboardapps/dashboard

apps/dashboard

—

2 EP

M16

notifications@gurulu/notifications

@gurulu/notifications

5 PG

—

15 EP

M17

experiments@gurulu/experiments

@gurulu/experiments

2 PG

1 CH

8 EP

M18

popups@gurulu/activation

@gurulu/activation

1 PG

1 CH

7 EP

M19

tours@gurulu/activation

@gurulu/activation

2 PG

—

6 EP

M20

personalization@gurulu/activation

@gurulu/activation

1 PG

—

6 EP

M21

boardsapps/dashboard

apps/dashboard

2 PG

—

7 EP

M22

llm-analytics@gurulu/registry + web

@gurulu/registry + web

1 PG

2 CH

4 EP

M23

heatmaps@gurulu/web

@gurulu/web

—

2 CH

3 EP

M24

observability-suite@gurulu/observability

@gurulu/observability

3 PG

3 CH

7 EP

PG = جدول Postgres · CH = جدول ClickHouse أو عرض مادّي · EP = نقطة نهاية REST علنية

أدلة الوحدات

وحدات جديدة، خطوة بخطوة

أدلة الاستخدام للجماهير والوجهات وبرنامج الشراكة والملخص الصباحي و playground crawler.

الجماهير

حوّل cohorts إلى جماهير حية ذات مزامنة تلقائية.

الوجهات

Meta CAPI + Google Ads + Webhook — بيانات مشفّرة بـ KMS.

برنامج الشراكة

Stripe Connect Express + عمولة متدرّجة 20-30%، متكررة 12 شهراً.

الملخص الصباحي بالذكاء الاصطناعي

موجز يومي لمساحة عملك، سلسلة fallback من 5 نماذج لا تنقطع.

زاحف Playground

crawl من جهة الخادم + اكتشاف patterns لتطبيقات SPA الثقيلة بـ JS.

ورقة API المرجعية

سطح REST — مُجمَّع

نقاط نهاية مختارة من سطح المرحلة 0 + 1. القائمة الكاملة (نحو 270) تُشحَن مع تأهيل مستأجري النسخة التجريبية المغلقة.

المصادقة والمستأجر

الرابط السحري أساسي، وOAuth عبر Google + GitHub بـ PKCE S256 ثانوي. بلا كلمات مرور.

POST/v1/auth/magic-link
POST/v1/auth/magic-link/verify
GET/v1/auth/oauth/:provider
POST/v1/auth/session/refresh
POST/v1/auth/session/revoke
POST/v1/auth/api-keys

Ingest

مستوى بيانات علني — https://ingest.gurulu.io. تعمل بوّابة التحقّق (قبول / تحذير / حجر / رفض) عند الاستيعاب.

POST/v1/track
POST/v1/batch
POST/v1/identify
POST/v1/alias
POST/v1/webhook/:provider

سجلّ الأحداث

مصدر عقد طبقة الحقيقة. snake_case مفروض؛ وتوليد شيفرة لثلاث لغات (TS وPython وSwift).

GET/v1/registry/events
POST/v1/registry/events
GET/v1/registry/events/:key
POST/v1/registry/validate
GET/v1/registry/code-gen
GET/v1/registry/packs

Identity

حلّ من 7 خطوات، وثقة من 3 مستويات، وسجلّ دمج للإلحاق فقط. كل دمج قابل للعكس.

POST/v1/identity/resolve
GET/v1/identity/person/:id
GET/v1/identity/person/:id/timeline
POST/v1/identity/merge
GET/v1/identity/merge-ledger

صحّة الأحداث

شذوذ بالتعلّم الآلي + إزالة تكرار + تغطية + عدم تطابق CAPI. يقارن ما أرسله الـ SDK بما رآه خادمك فعلاً.

GET/v1/health/events
GET/v1/health/events/:key
GET/v1/health/anomalies
GET/v1/health/coverage
POST/v1/health/dedup-check

Attribution

سياسة يحدّدها العميل + متعدّد النماذج (أول / آخر / خطّي / تناقص زمني / موقع / قائم على البيانات) + مسار المنشأ.

POST/v1/attribution/policy
POST/v1/attribution/compute
GET/v1/attribution/touchpoints/:personId
GET/v1/attribution/explain/:outcomeId

الموافقة وطلبات أصحاب البيانات (DSR)

GCM v2، متوائم مع GDPR / CCPA / KVKK. تصدير DSR + طابور النسيان باتفاقية مستوى خدمة 60 ثانية.

POST/v1/consent
GET/v1/consent/:personId
POST/v1/consent/dsr/export
POST/v1/consent/dsr/forget

الإدارة والعمليات

مساحات العمل، والأعضاء، وسجلّ التدقيق، وhealthz. https://api.gurulu.io هو مستوى التحكم.

GET/v1/workspaces
POST/v1/workspaces/:id/members
GET/v1/audit-log
GET/v1/healthz

المصادقة: Bearer JWT (مستخدم) أو مفتاح API بصيغة pk_/sk_ (خادم إلى خادم). كل الاستجابات JSON بترميز UTF-8، والأخطاء بصيغة RFC 7807 problem+json.

نموذج البيانات

نواة الكون — تعاقدية وقابلة للتفسير

مبدأ نواة الكون: كل حدث وجدول ونقطة نهاية يحمل مجموعة الحقول الكاملة منذ اليوم الأول. تُشحَن الواجهة لاحقاً، أمّا شكل البيانات فلا يتّسع أبداً.

الحقول المطلوبة

يحمل كل حدث وكل صفّ هذه المجموعة — بلا ALTER TABLE لاحقاً. نواة الكون إلزامية.

tenant_id
workspace_id
anonymous_id | person_id
session_id
source_context
confidence
consent_state
health_status

3 فئات أحداث

خلط الفئات ممنوع — استيعاب مختلف، وإسناد مختلف، وتقارير مختلفة.

Interactionالتقاط تلقائي في المتصفّح: click وpageview وscroll. ليست نتيجة.
Intentإضافة إلى السلّة، وcheckout_started، وإشارات نيّة أخرى. مفصولة في نموذج البيانات منذ اليوم الأول، ومُنتَجة في المرحلة 2+.
Outcomepurchase_completed وsignup_completed — من جهة الخادم. ومن هنا ينطلق الإسناد.

بوّابة التحقّق

يوجّه الاستيعاب كل حدث عبر 4 قرارات إزاء السجلّ. انحراف العقد يُفشِل الـ PR في الـ CI — فلا يصل الإنتاج أبداً.

acceptwarnquarantinereject

تعمّق أكثر

صفحات ذات صلة

انتقل إلى الصفحة التي تحوي ما تحتاجه.

Features Changelog Compare Pricing

Docs

أول حدث في دقائق

ثبّت الحزم

تتبّع في المتصفّح

تحقّق من النتائج من جهة الخادم

استخدم السجلّ كعقد

4 قنوات، 4 حزم

خادم MCP

Web SDK

Server SDK

CLI

المرحلة 0 + المرحلة 1 — 16 وحدة

وحدات جديدة، خطوة بخطوة

الجماهير

الوجهات

برنامج الشراكة

الملخص الصباحي بالذكاء الاصطناعي

زاحف Playground

سطح REST — مُجمَّع

المصادقة والمستأجر

Ingest

سجلّ الأحداث

Identity

صحّة الأحداث

Attribution

الموافقة وطلبات أصحاب البيانات (DSR)

الإدارة والعمليات

نواة الكون — تعاقدية وقابلة للتفسير

الحقول المطلوبة

3 فئات أحداث

بوّابة التحقّق

صفحات ذات صلة