Developer docs

Docs

Quickstart, four SDKs, 16 modules, ~270 endpoints. Closed beta — we publish what actually ships, not what we wish existed.

Quickstart

First event in minutes

Install → init → track. Web and server identity are stitched for you, the registry contract is enforced in CI.

  1. 01

    Install the packages

    Bun, pnpm or npm — your choice. The zero-dep browser bundle is 8.1 KB gzip and the server SDK is tested on Node 20+ and Bun.

    bun add @gurulu/web @gurulu/node
  2. 02

    Track in the browser

    Init with a publicKey — everything else is automatic: anonymous_id (UUIDv7), session, GCM v2 consent state, and 5 autocapture signals (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' });
  3. 03

    Verify outcomes server-side

    Send money-movement and signup_completed-style events from your server — so the user's browser cannot fake them. personId is required, and attribution fires from here.

    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',
});
  4. 04

    Use the registry as a contract

    Event names are not free strings — they are typed-codegen'd from the registry. Run `gurulu validate` in CI and contract drift fails the PR.

    gurulu pull               # registry → typed code-gen
gurulu validate           # contract drift check
gurulu push events.ts     # add/update event contracts

SDKs & tools

4 channels, 4 packages

Script (browser), SDK (server), CLI (registry) and MCP (Cursor, Claude Code, Lovable). All public on NPM.

MCP server

@gurulu/mcp-server

list_events, add_event, validate_event tools. Your AI editor can read the registry — it stops guessing `bet.placed` and uses the registry's `bet_placed`.

claude mcp add gurulu -- npx -y @gurulu/mcp-server
Cursor / Claude Code / LovableDetails

Web SDK

@gurulu/web

Zero-dep browser bundle. 5 autocapture signals + manual track + identify + consent + session-replay opt-in (Phase 2). Or drop one script tag via the t.js CDN.

bun add @gurulu/web
8.1 KB gzipDetails

Server SDK

@gurulu/node

secretKey-based outcome verification, batch flush, 23 webhook verifiers (Stripe, Shopify, LemonSqueezy, Custom + 19 more) and Hono/Express/Fastify middleware.

bun add @gurulu/node
Node 20+ · Bun · EdgeDetails

CLI

@gurulu/cli

gurulu init / pull / push / validate / doctor. Wires the registry into your Git flow — events.ts is the source of truth, drift caught in CI.

bun add -g @gurulu/cli
@gurulu/cliDetails

Module catalog

Phase 0 + Phase 1 — 16 modules

How many Postgres tables, ClickHouse views and REST endpoints each module ships — at a glance.

#
Module
Phase
M01
auth-tenant@gurulu/auth
F0
M02
storage@gurulu/db
F0
M03
observability-own@gurulu/observability
F0
M04
consent-engine@gurulu/consent
F0
M05
identity-engine@gurulu/identity
F1
M06
event-registry@gurulu/registry
F1
M07
event-health@gurulu/health
F1
M08
attribution-engine@gurulu/attribution
F1
M09
ingest-api@gurulu/ingest
F1
M10
event-pipeline@gurulu/pipeline
F1
M11
sdk-web@gurulu/web
F1
M12
sdk-server@gurulu/node
F1
M13
playground@gurulu/playground
F1
M14
cli-mcp@gurulu/cli + mcp-server
F1
M15
dashboardapps/dashboard
F1
M16
notifications@gurulu/notifications
F1

PG = Postgres table · CH = ClickHouse table or materialized view · EP = public REST endpoint

أدلة الوحدات

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

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

الجماهير

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

الوجهات

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

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

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

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

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

Playground Crawler

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

API cheatsheet

REST surface — grouped

Selected endpoints from the Phase 0 + 1 surface. The full list (~270) ships with closed-beta tenant onboarding.

Auth & tenant

Magic link is primary, OAuth Google + GitHub PKCE S256 secondary. No passwords.

  • 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 — https://ingest.gurulu.io. The validation gate (accept / warn / quarantine / reject) runs on ingestion.

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

Event registry

The Truth Layer's contract source. snake_case enforced; code-gen for 3 languages (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. Every merge is reversible.

  • 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. Compares what the SDK sent against what your server actually saw.

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

Attribution

Customer-defined 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 aligned. DSR export + forget queue with a 60s SLA.

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

Admin & ops

Workspaces, members, audit log, healthz. https://api.gurulu.io is the control plane.

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

Auth: Bearer JWT (user) or pk_/sk_ API key (server-to-server). All responses are UTF-8 JSON, errors are RFC 7807 problem+json.

Data model

Universe Kernel — contractual and explainable

Universe Kernel principle: every event, table and endpoint carries the full field set from day one. UI ships later, the data shape never widens.

Required fields

Every event and every row carries this set — no ALTER TABLE later. Universe Kernel is mandatory.

  • tenant_id
  • workspace_id
  • anonymous_id | person_id
  • session_id
  • source_context
  • confidence
  • consent_state
  • health_status

3 event classes

Mixing classes is forbidden — different ingestion, different attribution, different reporting.

  • InteractionBrowser autocapture: click, pageview, scroll. Not an outcome.
  • IntentAdd-to-cart, checkout_started and other intent signals. Separated in the data model from day one, productized in Phase 2+.
  • Outcomepurchase_completed, signup_completed — server-side. Attribution fires from here.

Validation gate

Ingestion routes every event through 4 decisions against the registry. Contract drift fails the PR in CI — it never reaches prod.

acceptwarnquarantinereject

Go deeper

Related pages

Jump to the page that has what you need.

FeaturesChangelogComparePricing
Docs — Gurulu