# Sarutobi

> Sarutobi est une plateforme de Product Analytics auto-hébergée, écrite en TypeScript (Next.js, PostgreSQL, Drizzle, Better Auth). Elle relie collecte d'événements, identité persistante, exploration et décision : pages vues, visites, sessions, personnes, groupes, funnels, rétention, cohortes, parcours, feature flags, expériences, Web Vitals et erreurs JavaScript. Les SDK navigateur pèsent moins de 5 ko gzip, n'ont aucune dépendance runtime et ne peuvent jamais faire échouer le site instrumenté. Un serveur MCP expose les mêmes mesures aux agents.

Le produit et sa documentation sont en **français** ; le code, les routes et les noms d'API sont en **anglais**. Instance officielle : `https://sarutobi.ascencia.re`. Dépôt : `https://github.com/pedrokarim/sarutobi` (MIT).

Repères pour intégrer sans rien lire d'autre :

- **La clé d'un site s'appelle `siteId`.** Elle ressemble à `st_live_8f3a1c9d2e4b6071` et s'obtient sur la page **Installation** du site, dans le dashboard. Elle **n'est pas un secret** : elle transite en clair dans le JavaScript. Ce qui protège les chiffres, c'est la liste des domaines autorisés déclarée sur le site. Ne jamais l'appeler « token » ni « clé d'API ».
- **La clé serveur `st_secret_…`** est réservée à `@ascencia/sarutobi-node` et ne doit jamais atteindre un bundle client.
- **Installer** : `bun add @ascencia/sarutobi-react@next` (React, Next.js) ou `@ascencia/sarutobi-js@next` (vanilla, Vue, Svelte). Sans bundler : `<script defer src="https://sarutobi.ascencia.re/s.js" data-site="st_live_…"></script>`.
- **Brancher** : `<SarutobiProvider siteId={…}>` en React, `sarutobi.init({ siteId })` ailleurs. Pages vues, visites, referrers, UTM, pays, appareil, Core Web Vitals et erreurs JavaScript sont collectés sans autre instrumentation.
- **API** : `capture(name, props?)`, `identify(id, props?)`, `reset()`, `setConsent(state)`, `pageview(path?)`, `setContext(props)`, `group(type, key, props?)`, `groupIdentify(type, key, props)`, `isFeatureEnabled(key)`, `getFeatureFlag(key)`, `flush()`. Aucune méthode ne renvoie de promesse ; aucune ne fait attendre l'appelant.
- **Ingestion** : `POST /api/collect`, corps JSON envoyé en `text/plain;charset=UTF-8` pour éviter le pré-vol CORS, 1 à 20 events par lot, 32 ko maximum. Réponse `202` au corps toujours vide.
- **En développement, rien n'est envoyé** : le SDK se désactive seul sur `localhost`, `127.0.0.1` et les domaines en `.localhost`. Passer `enabled: true` pour tester en local.
- **Un `202` veut dire « accepté », pas « visible »** : le temps réel lit les visites brutes, les courbes lisent des agrégats recalculés toutes les dix minutes par un cron.
- **Nommer un event** : verbe au passé en `snake_case`, jamais d'identifiant dans le nom, propriétés à faible cardinalité, jamais de donnée personnelle. Trente-deux clés par event, cinq cent douze caractères par valeur ; chaînes, nombres, booléens et `null` uniquement.
- **Consentement** : le SDK démarre en `consent: "pending"` et ne crée aucun identifiant avant `setConsent("granted")`.

## Démarrer

- [Démarrage rapide](https://sarutobi.ascencia.re/docs) : récupérer la clé du site, installer le paquet, brancher le provider, vérifier la réception du premier event.
- [Comment ça fonctionne](https://sarutobi.ascencia.re/docs/fonctionnement) : le trajet d'un event du SDK au dashboard, la latence des rollups, ce que répond chaque écran, et pourquoi visite, session et personne sont trois choses distinctes.
- [Next.js](https://sarutobi.ascencia.re/docs/nextjs) : App Router et Pages Router, `disabled` réévalué à chaque rendu, Content Security Policy, `NEXT_PUBLIC_SARUTOBI_SITE_ID`.
- [React et autres frameworks](https://sarutobi.ascencia.re/docs/react) : le hook `useSarutobi()`, l'usage hors composant, Vue, Svelte, vanilla, SPA et rendu côté serveur.
- [Sans bundler](https://sarutobi.ascencia.re/docs/script) : la balise `<script>`, ses attributs `data-*`, l'autocapture structurée par `data-sarutobi`, et le repli pixel pour `<noscript>`.

## Référence

- [API de la librairie](https://sarutobi.ascencia.re/docs/api) : toutes les méthodes, le tableau complet des options avec types et valeurs par défaut, l'identité, le consentement, `setContext`, `beforeSend` et les budgets de poids.
- [Contrat HTTP](https://sarutobi.ascencia.re/docs/http) : enveloppe et champs abrégés de `POST /api/collect`, types d'events, codes de réponse, quotas et allowlist d'origines.
- [Nommer ses events](https://sarutobi.ascencia.re/docs/conventions) : les quatre règles de nommage, la cardinalité des propriétés, les types acceptés et les limites de taille.

## Exploitation

- [Déploiement](https://sarutobi.ascencia.re/docs/deploiement) : services requis, variables d'environnement, migrations, planification des crons et contrôles avant ouverture.
- [Vie privée et consentement](https://sarutobi.ascencia.re/docs/vie-privee) : modes de persistance, branchement d'un gestionnaire de consentement, `identify` et `reset`, données à ne jamais envoyer.
- [Dépannage](https://sarutobi.ascencia.re/docs/depannage) : les trois causes qui expliquent presque tous les cas où rien n'arrive, plus les situations secondaires et le mode debug.
- [Statut de l'instance](https://sarutobi.ascencia.re/status) : page publique de supervision. `GET /api/health` renvoie le même état en JSON.

## Agents et MCP

- [Serveur MCP](https://sarutobi.ascencia.re/docs/mcp) : connexion OAuth 2.1 ou par jeton `st_mcp_…`, scopes de lecture et d'écriture, ce que le serveur refuse de faire, journal d'audit.
- [Installer un agent](https://sarutobi.ascencia.re/docs/mcp/installation) : l'écran d'autorisation, les clients sans navigateur, la configuration par fichier.
- [Catalogue des clients MCP](https://sarutobi.ascencia.re/mcp) : les clients qui savent parler à ce serveur et la commande de chacun.
- Endpoint : `https://sarutobi.ascencia.re/api/mcp`, transport HTTP. `claude mcp add --transport http sarutobi https://sarutobi.ascencia.re/api/mcp`.
- Trente-huit outils, dont cinq en écriture. Commencer par `list_sites` puis `list_event_names` : un nom d'event inventé renvoie zéro sans erreur. La ressource `sarutobi://glossary` porte le vocabulaire qui évite les contresens.

## Paquets npm

- [@ascencia/sarutobi-js](https://www.npmjs.com/package/@ascencia/sarutobi-js) : SDK navigateur, aucune dépendance runtime, environ 4,9 ko gzip. Batching, navigation SPA, Web Vitals, erreurs, flags et groupes.
- [@ascencia/sarutobi-react](https://www.npmjs.com/package/@ascencia/sarutobi-react) : `SarutobiProvider` et `useSarutobi()` pour React et Next.js, environ 5,1 ko gzip.
- [@ascencia/sarutobi-vue](https://www.npmjs.com/package/@ascencia/sarutobi-vue) : `SarutobiPlugin` et `useSarutobi()` pour Vue et Nuxt.
- [@ascencia/sarutobi-svelte](https://www.npmjs.com/package/@ascencia/sarutobi-svelte) : `initSarutobi()` et `useSarutobi()` pour Svelte et SvelteKit.
- [@ascencia/sarutobi-node](https://www.npmjs.com/package/@ascencia/sarutobi-node) : SDK serveur, clé `st_secret_…`, `createClient({ writeKey, host })`, file bornée et arrêt propre. Node 20 ou supérieur.

## Produit

- [Accueil](https://sarutobi.ascencia.re/) : positionnement et parcours d'entrée.
- [Fonctionnalités](https://sarutobi.ascencia.re/features) : ce que couvre la plateforme, écran par écran.
- [Créer un compte](https://sarutobi.ascencia.re/signup) et [se connecter](https://sarutobi.ascencia.re/login).
- [Contact](https://sarutobi.ascencia.re/contact), [mentions légales](https://sarutobi.ascencia.re/legal), [conditions](https://sarutobi.ascencia.re/conditions).
- [Identité visuelle](https://sarutobi.ascencia.re/branding) et [bibliothèque de composants](https://sarutobi.ascencia.re/branding/components).

## Optional

- [llms-full.txt](https://sarutobi.ascencia.re/llms-full.txt) : toute la documentation d'intégration en un seul fichier, sans navigation.
- [README du dépôt](https://github.com/pedrokarim/sarutobi/blob/main/README.md) : monorepo, commandes et état d'avancement.
- [AGENTS.md](https://github.com/pedrokarim/sarutobi/blob/main/AGENTS.md) : règles de contribution, invariants d'architecture et critères de revue.
- [CHANGELOG](https://github.com/pedrokarim/sarutobi/blob/main/CHANGELOG.md) : versions des SDK, publiées ensemble sous un même numéro.
- [Vision et périmètre](https://github.com/pedrokarim/sarutobi/blob/main/docs/00-vision-et-perimetre.md) : ce que le produit cherche à répondre, et ce qu'il ne cherche pas à faire.
- [Architecture](https://github.com/pedrokarim/sarutobi/blob/main/docs/01-architecture.md) : flux de collecte, identité, stockage et moteur analytique.
- [Modèle de données](https://github.com/pedrokarim/sarutobi/blob/main/docs/02-modele-de-donnees.md) : events, persons, sessions, insights, cohorts et flags.
- [API d'ingestion](https://github.com/pedrokarim/sarutobi/blob/main/docs/03-api-ingestion.md) : contrat batch complet, identité, propriétés et endpoints.
- [Librairie client](https://github.com/pedrokarim/sarutobi/blob/main/docs/04-librairie-client.md) : comportement attendu des SDK.
- [Dashboard](https://github.com/pedrokarim/sarutobi/blob/main/docs/05-dashboard.md) : organisation des écrans et des groupes de navigation.
- [Vie privée et RGPD](https://github.com/pedrokarim/sarutobi/blob/main/docs/06-vie-privee-et-rgpd.md) : consentement, minimisation et conservation.
- [Rollups et performance](https://github.com/pedrokarim/sarutobi/blob/main/docs/07-rollups-et-performance.md) : agrégats, matérialisations et seuils.
- [Sécurité](https://github.com/pedrokarim/sarutobi/blob/main/docs/08-securite.md) : modèle de menace, clés, RBAC et exports.
- [Déploiement](https://github.com/pedrokarim/sarutobi/blob/main/docs/09-deploiement.md) : environnements, migrations et runbooks.
- [Roadmap](https://github.com/pedrokarim/sarutobi/blob/main/docs/10-roadmap.md) : lots livrés, en cours et différés.
- [Versions et publication](https://github.com/pedrokarim/sarutobi/blob/main/docs/11-versions-et-publication.md) : semver des SDK et publication npm.
- [Serveur MCP](https://github.com/pedrokarim/sarutobi/blob/main/docs/13-serveur-mcp.md) : conception, outils, jetons et scopes.
- [Runbook de production](https://github.com/pedrokarim/sarutobi/blob/main/deploy/README.md) : proxy, conteneurs, contrôles de santé et retour arrière.