Dev dokümanları

Docs

Quickstart, 4 SDK, 16 modül, ~270 endpoint. Closed beta — yüzeyi olduğu kadarıyla yayınlıyoruz, fazlasını uydurmuyoruz.

Quickstart

Dakikalar içinde first event

Install → init → track. Web + server arası identity zaten birleştirilir, registry kontratı CI'da doğrulanır.

01
Paketleri kur
Bun, pnpm veya npm — fark etmez. Sıfır-dep tarayıcı bundle'ı 8.1 KB gzip, server SDK Node 20+ ve Bun runtime'da test edilmiştir.
```
bun add @gurulu/web @gurulu/node
```
02
Tarayıcıda track
publicKey ile init et — kalan her şey otomatik: anonymous_id (UUIDv7), session, GCM v2 consent state, autocapture (5 sinyal: 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' });
```

Sunucuda outcome doğrula

Para hareketi, signup_completed gibi outcome event'lerini server'dan gönder — kullanıcı tarayıcısı bunları manipüle edemesin. personId zorunlu, attribution buradan tetiklenir.

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
Registry'i kontrat olarak kullan
Event isimleri serbest string değil — registry'den typed code-gen edilir. CI'da `gurulu validate` çalıştır, contract drift PR'da düşer.
```
gurulu pull               # registry → typed code-gen
gurulu validate           # contract drift check
gurulu push events.ts     # add/update event contracts
```

SDK & araçlar

4 kanal, 4 paket

Script (tarayıcı), SDK (sunucu), CLI (registry) ve MCP (Cursor/Claude Code/Lovable). Hepsi NPM'de public.

MCP server

@gurulu/mcp-server

list_events, add_event, validate_event tool'ları. AI editörünüz registry'i okuyabilir — `bet.placed` gibi tahmin event ismi uydurmaz, registry'deki `bet_placed`'i kullanır.

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

Cursor / Claude Code / LovableDetay

Web SDK

@gurulu/web

Zero-dep tarayıcı bundle. Autocapture 5 sinyal + manual track + identify + consent + session-replay opt-in (Faz 2). t.js CDN üzerinden tek satır script tag de çalışır.

bun add @gurulu/web

8.1 KB gzipDetay

Server SDK

@gurulu/node

secretKey ile outcome verification, batch flush, 23 webhook verifier (Stripe, Shopify, LemonSqueezy, Custom + 19 ek), Hono/Express/Fastify middleware.

bun add @gurulu/node

Node 20+ · Bun · EdgeDetay

CLI

@gurulu/cli

gurulu init / pull / push / validate / doctor. Registry'i Git akışına bağlar — events.ts dosyan source of truth, CI'da drift kontrolü.

bun add -g @gurulu/cli

@gurulu/cliDetay

Modül kataloğu

Faz 0 + Faz 1 — 16 modül

Hangi modülde kaç PG tablosu, kaç ClickHouse view'u, kaç REST endpoint var — tek bakışta.

Modül

Paket

Endpoint

Faz

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

PG = Postgres tablosu · CH = ClickHouse tablo veya materialized view · EP = public REST endpoint

API cheatsheet

REST yüzeyi — gruplanmış

Faz 0 + Faz 1 mühründen seçili endpoint'ler. Tam liste (≈270) closed-beta tenant onboarding sırasında verilir.

Auth & tenant

Magic link birincil (K23), OAuth Google + GitHub PKCE S256 ikincil. Şifre yok.

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

Public data plane — apps/ingest (3001). Validation gate (accept/warn/quarantine/reject) ingestion'da çalışır.

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

Event registry

Truth Layer'ın sözleşme kaynağı. snake_case zorunlu, code-gen 3 dil (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-step resolve, 3-level confidence, append-only merge ledger. Her merge geri alınabilir.

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

Event health

ML anomaly + dedup + coverage + CAPI mismatch. SDK gönderdiklerini sunucu gördükleriyle karşılaştırır.

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

Attribution

Müşteri tanımlı policy + multi-model (first/last/linear/time-decay/position/data-driven) + provenance trace.

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

Consent & DSR

GCM v2, GDPR/CCPA/KVKK uyumlu. DSR export + forget queue 60 sn SLA.

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

Admin & ops

Workspace, üye, audit log, healthz. apps/api (3000) control plane'i.

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

Auth: Bearer JWT (kullanıcı) veya pk_/sk_ API anahtarı (server-to-server). Tüm yanıtlar UTF-8 JSON, hata RFC 7807 problem+json.

Data model

Universe Kernel — sözleşmeli, açıklanabilir

K15 mührü: her event/tablo/endpoint başlangıçtan tam set field taşır. UI sonradan eklenir, veri eklenmez.

Zorunlu alanlar (K15)

Her event ve her satır bu alanları taşır. Sonradan ALTER TABLE yok — Universe Kernel mandatory.

tenant_id
workspace_id
anonymous_id | person_id
session_id
source_context
confidence
consent_state
health_status

3 sınıf event (K14)

Class karıştırma yasak — ingestion ayrı, attribution ayrı, raporlama ayrı.

InteractionTarayıcıdan autocapture: click, pageview, scroll. Outcome değildir.
IntentAdd-to-cart, checkout_started gibi niyet sinyalleri. Veri modelinde baştan ayrı, üretim Faz 2+.
Outcomepurchase_completed, signup_completed — server'dan gelir, attribution buradan tetiklenir.

Validation gate (K17)

Ingestion her event'i registry'ye göre 4 kararla işler. CI'da contract drift PR'da düşer — prod'a sızmaz.

acceptwarnquarantinereject

Daha derin

İlgili sayfalar

Detay aradığın yere git.

Özellikler Changelog Karşılaştırma Fiyatlandırma

Docs

Dakikalar içinde first event

Paketleri kur

Tarayıcıda track

Sunucuda outcome doğrula

Registry'i kontrat olarak kullan

4 kanal, 4 paket

MCP server

Web SDK

Server SDK

CLI

Faz 0 + Faz 1 — 16 modül

REST yüzeyi — gruplanmış

Auth & tenant

Ingest

Event registry

Identity

Event health

Attribution

Consent & DSR

Admin & ops

Universe Kernel — sözleşmeli, açıklanabilir

Zorunlu alanlar (K15)

3 sınıf event (K14)

Validation gate (K17)

İlgili sayfalar