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.

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
```
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' });
```

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

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

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

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

模块指南

新模块，步步上手

受众、目的地、联盟、AI 晨间摘要、playground crawler 的操作指南。

受众

把 cohort 转成实时、自动同步的受众。

目的地

Meta CAPI + Google Ads + Webhook — 凭据 KMS 加密。

联盟计划

Stripe Connect Express + 20-30% 阶梯佣金，12 个月经常性。

AI 晨间摘要

每天早晨的 workspace 摘要，5 模型永不掉线 fallback 链。

Playground Crawler

JS-heavy SPA 的服务端 crawl + pattern detection。

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

Jump to the page that has what you need.

Features Changelog Compare Pricing

Docs

First event in minutes

Install the packages

Track in the browser

Verify outcomes server-side

Use the registry as a contract

4 channels, 4 packages

MCP server

Web SDK

Server SDK

CLI

Phase 0 + Phase 1 — 16 modules

新模块，步步上手

受众

目的地

联盟计划

AI 晨间摘要

Playground Crawler

REST surface — grouped

Auth & tenant

Ingest

Event registry

Identity

Event health

Attribution

Consent & DSR

Admin & ops

Universe Kernel — contractual and explainable

Required fields

3 event classes

Validation gate

Related pages