API Analytics (dashboard admin)

Cette page documente /api/v1/analytics/* : une API REST read-only, authentifiée par token machine-à-machine, destinée à un dashboard d'administration qui vit dans un dépôt séparé, sans accès au code de Kutsum. Le contrat ci-dessous doit donc être suffisant pour écrire un client typé sans jamais lire une ligne de source — types, nullabilité, exemples réels, codes d'erreur, tout est explicite.

Contrairement au reste d'api.md, cette API n'est pas authentifiée par cookie/JWT utilisateur : elle est consommée côté serveur par un job/route handler du dashboard, jamais depuis un navigateur (voir Authentification).

Base URL : /api/v1/analytics

Format des dates : toutes les dates sont des chaînes ISO-8601 en UTC (ex. 2026-08-05T14:02:11.483Z), jamais en heure locale. Un bucketStart / monthStart de série temporelle est toujours un minuit UTC exact.

Authentification

Chaque route de cette API exige un en-tête :

Authorization: Bearer <token>

• Absent, malformé, inconnu, expiré ou révoqué → 401 avec le même code ANALYTICS_UNAUTHORIZED dans tous les cas (voir Codes d'erreur — c'est délibéré : distinguer ces cas permettrait à un attaquant de sonder l'existence d'un token).
• La portée (scope) de la réponse — globale (toutes organisations confondues) ou restreinte à un établissement — vient exclusivement du token présenté, jamais d'un en-tête ou d'un paramètre envoyé par le client. Un token d'établissement ne peut pas être élargi, un token global ne peut pas être restreint après coup.
• Un appel réussi met à jour lastUsedAt sur le token (repérage d'un token dormant ou fuité) — cette écriture ne peut jamais faire échouer la requête.

Obtenir un token

Il n'existe pas de route pour créer un token (v1 volontairement fermée). La provision se fait par un script CLI, côté serveur Kutsum :

# Depuis app/backend/
npm run analytics:token -- create --label "dashboard prod"
npm run analytics:token -- create --label "lycée X" --org lycee-x
npm run analytics:token -- create --label "temporaire" --expires 2027-01-01T00:00:00Z

• Sans --org, le token est global (agrégat toutes organisations).
• Avec --org <subdomain>, le token est restreint à cet établissement.
• Le token en clair est affiché une seule fois, à la création. Seul son hash SHA-256 est stocké en base — il ne peut pas être récupéré après coup. Le perdre implique d'en créer un nouveau et de révoquer l'ancien.

npm run analytics:token -- list      # liste les tokens (métadonnées uniquement, jamais le hash ni le token)
npm run analytics:token -- revoke <id>

Une fois révoqué, tout appel avec ce token renvoie immédiatement 401.

Expiration et révocation

• expiresAt est optionnel (--expires <ISO-8601> à la création). Un token sans expiration reste valide jusqu'à révocation explicite.
• revokedAt est renseigné par analytics:token -- revoke <id> — c'est la seule voie de révocation en v1 (pas de self-service).
• Passé l'expiration ou après révocation, toute route de cette API renvoie 401 ANALYTICS_UNAUTHORIZED, immédiatement et sans délai de grâce.

⚠️ Le token ne doit jamais atteindre un navigateur

C'est un identifiant bearer : dans du JavaScript client, il devient un secret public. Le dashboard doit appeler cette API côté serveur (route handler / job), jamais depuis le navigateur de l'utilisateur final.

Limite de débit (rate limiting)

60 requêtes GET par minute, par token (comptées sur la clé = hash du token, pas sur l'IP — plusieurs dashboards derrière la même IP de sortie ne se pénalisent pas entre eux).

Au-delà, chaque route renvoie :

{
  "error": "Too many requests. Please retry later.",
  "code": "API_RATE_LIMIT_EXCEEDED"
}

avec un statut 429. Il n'y a pas d'en-tête Retry-After — la fenêtre est fixe (60 s) et redémarre à la première requête acceptée après expiration ; en cas de 429, espacez les nouvelles tentatives d'au moins quelques secondes plutôt que de réessayer en boucle serrée.

GET /api/v1/analytics/meta

Plus petit appel authentifié : indique la portée réelle du token présenté. Sert aussi de vérification de credentials au démarrage du dashboard.

Authentification : requise (voir ci-dessus)

Paramètres : aucun

Réponse 200 :

Exemple (token d'établissement) :

curl -sS https://app.kutsum.org/api/v1/analytics/meta \
  -H 'Authorization: Bearer <token>'

{
  "scope": "organization",
  "organizationId": "3f1b4b8a-2c4e-4b0a-9b7a-8e6f0f1a2b3c",
  "computedAt": "2026-08-05T14:02:11.483Z"
}

GET /api/v1/analytics/active-users

Série temporelle du nombre d'utilisateurs actifs distincts, à une résolution choisie par le serveur — le client ne devine jamais la granularité, il la lit dans la réponse.

Authentification : requise

Paramètres de requête :

Résolution (granularity) choisie par le serveur

Un token d'établissement ne reçoit jamais day : DailyActiveStats (la table qui alimente la granularité journalière) n'a pas de dimension établissement — c'est une propriété assumée du contrat, pas un manque tu. range=30d sur un token d'établissement est donc automatiquement rabattu sur week.

⚠️ Non-additivité — ne jamais sommer les points

Chaque point est un décompte d'utilisateurs distincts dans SON seau, et seulement dans son seau. Un enseignant actif lundi et mardi de la même semaine vaut 2 sur deux points day (1 chacun), et exactement 1 sur le point week correspondant. Ne sommez jamais les points d'une série (ex. pour reconstituer un "MAU" en additionnant des points day) — le résultat serait 3 à 5 fois trop haut, avec une courbe d'allure tout à fait plausible.

⚠️ Granularité month : points approximés

Quand granularity vaut month (systématique pour range=all), chaque point est marqué "approximate": true. Raison : la table source (ActorWeeklyActivity) est hebdomadaire, pas mensuelle. Une semaine à cheval sur deux mois calendaires est comptée dans les deux mois qu'elle touche — l'utilisateur actif la dernière semaine de juillet et la première d'août apparaît dans le total de juillet et dans celui d'août. C'est une légère sur-estimation assumée (arbitrage mainteneur), jamais une sous-estimation qui masquerait de l'activité réelle. Ne traitez pas un point approximate: true comme un chiffre exact.

Réponse 200

Élément de points :

La série est continue : chaque seau de la fenêtre est présent, y compris ceux sans aucune activité (activeUsers: 0) — jamais de trou à combler côté client.

Exemple — token global, range=30d (granularité day) :

curl -sS 'https://app.kutsum.org/api/v1/analytics/active-users?range=30d' \
  -H 'Authorization: Bearer <token>'

{
  "scope": "global",
  "organizationId": null,
  "range": "30d",
  "granularity": "day",
  "dataAvailableFrom": "2026-07-08T00:00:00.000Z",
  "computedAt": "2026-08-05T13:00:04.221Z",
  "points": [
    { "bucketStart": "2026-07-07T00:00:00.000Z", "activeUsers": 0, "approximate": false, "partial": false },
    { "bucketStart": "2026-07-08T00:00:00.000Z", "activeUsers": 6, "approximate": false, "partial": false },
    { "bucketStart": "2026-08-04T00:00:00.000Z", "activeUsers": 19, "approximate": false, "partial": false },
    { "bucketStart": "2026-08-05T00:00:00.000Z", "activeUsers": 12, "approximate": false, "partial": true }
  ]
}

Exemple — token d'établissement, range=30d (rabattu sur week) :

curl -sS 'https://app.kutsum.org/api/v1/analytics/active-users?range=30d' \
  -H 'Authorization: Bearer <token-etablissement>'

{
  "scope": "organization",
  "organizationId": "3f1b4b8a-2c4e-4b0a-9b7a-8e6f0f1a2b3c",
  "range": "30d",
  "granularity": "week",
  "dataAvailableFrom": "2026-07-06T00:00:00.000Z",
  "computedAt": "2026-08-05T13:00:04.221Z",
  "points": [
    { "bucketStart": "2026-07-06T00:00:00.000Z", "activeUsers": 4, "approximate": false, "partial": false },
    { "bucketStart": "2026-07-13T00:00:00.000Z", "activeUsers": 5, "approximate": false, "partial": false },
    { "bucketStart": "2026-07-20T00:00:00.000Z", "activeUsers": 3, "approximate": false, "partial": false },
    { "bucketStart": "2026-07-27T00:00:00.000Z", "activeUsers": 6, "approximate": false, "partial": false },
    { "bucketStart": "2026-08-03T00:00:00.000Z", "activeUsers": 4, "approximate": false, "partial": true }
  ]
}

Exemple — range=all (granularité month, approximée) :

{
  "scope": "global",
  "organizationId": null,
  "range": "all",
  "granularity": "month",
  "dataAvailableFrom": "2026-07-08T00:00:00.000Z",
  "computedAt": "2026-08-05T13:00:04.221Z",
  "points": [
    { "bucketStart": "2026-07-01T00:00:00.000Z", "activeUsers": 41, "approximate": true, "partial": false },
    { "bucketStart": "2026-08-01T00:00:00.000Z", "activeUsers": 27, "approximate": true, "partial": true }
  ]
}

GET /api/v1/analytics/growth

Séries cumulatives mensuelles (enseignants inscrits, activités créées, questions créées), calculées en direct depuis User.createdAt / GameInstance.createdAt / Question.createdAt — jamais depuis les tables d'agrégats horaires que lit active-users.

C'est un endpoint volontairement séparé, avec un schéma séparé, de active-users. Un cumul ne fait que monter ; un décompte d'actifs oscille. Ne comparez jamais un champ de growth à un champ de active-users comme s'ils mesuraient la même chose.

Contrairement à active-users, growth a une profondeur historique complète dès le premier jour : User/GameInstance/Question existent depuis toujours, alors que les tables d'agrégats d'active-users ne remontent qu'au 2026-07-08.

Authentification : requise

Paramètres de requête :

Réponse 200

Élément de points :

Exemple :

curl -sS 'https://app.kutsum.org/api/v1/analytics/growth?range=all' \
  -H 'Authorization: Bearer <token-etablissement>'

{
  "scope": "organization",
  "organizationId": "3f1b4b8a-2c4e-4b0a-9b7a-8e6f0f1a2b3c",
  "range": "all",
  "computedAt": "2026-08-05T13:00:04.221Z",
  "points": [
    { "monthStart": "2026-04-01T00:00:00.000Z", "teachersRegistered": 3, "activitiesCreated": 5, "questionsCreated": 12, "partial": false },
    { "monthStart": "2026-05-01T00:00:00.000Z", "teachersRegistered": 4, "activitiesCreated": 9, "questionsCreated": 18, "partial": false },
    { "monthStart": "2026-06-01T00:00:00.000Z", "teachersRegistered": 5, "activitiesCreated": 14, "questionsCreated": 27, "partial": false },
    { "monthStart": "2026-07-01T00:00:00.000Z", "teachersRegistered": 5, "activitiesCreated": 18, "questionsCreated": 33, "partial": false },
    { "monthStart": "2026-08-01T00:00:00.000Z", "teachersRegistered": 6, "activitiesCreated": 22, "questionsCreated": 40, "partial": true }
  ]
}

GET /api/v1/analytics/organizations/:organizationId/members

(et sa variante sans identifiant : GET /api/v1/analytics/organizations/members)

La seule route nominative de cette API — chaque autre route ci-dessus est strictement agrégée (aucun userId, username ni email n'y apparaît jamais). Celle-ci liste les enseignants rattachés à un seul établissement nommé, avec le statut de leur rattachement, leur dernière période d'activité et quelques compteurs simples d'adoption.

Authentification : requise (voir Authentification)

Deux formes d'URL, un seul comportement serveur :

Paramètres :

Comptes exclus de la liste

• Seuls les comptes de rôle enseignant (TEACHER) apparaissent — élèves et invités (GUEST) en sont exclus.
• Les comptes enseignants éphémères (inscription MathALEA, démo page d'accueil) sont exclus : ils ne sont jamais rattachés à un établissement, donc absents par construction de cette vue (pas de filtre dédié à écrire ni à maintenir).
• Un enseignant rattaché à plusieurs établissements apparaît dans chaque vue où il est effectivement rattaché, avec les compteurs propres à cet établissement à chaque fois — jamais un mélange des deux.

Réponse 200

⚠️ Contrairement à /meta, active-users et growth, cette réponse n'a pas de champ scope — la table ci-dessous est exhaustive (schéma .strict() côté serveur : tout champ non listé ici n'est jamais émis).

Élément de members :

Exemple — token d'établissement, forme courte :

curl -sS https://app.kutsum.org/api/v1/analytics/organizations/members \
  -H 'Authorization: Bearer <token-etablissement>'

{
  "organizationId": "3f1b4b8a-2c4e-4b0a-9b7a-8e6f0f1a2b3c",
  "computedAt": "2026-08-05T13:00:04.221Z",
  "members": [
    {
      "userId": "7e2a1c3d-9f0b-4a5c-8d6e-1b2c3d4e5f60",
      "username": "marie.dupont",
      "email": "marie.dupont@lycee-x.example",
      "membershipStatus": "active",
      "lastActiveWeekStart": "2026-07-27T00:00:00.000Z",
      "activitiesCreated": 12,
      "personalQuestionsCreated": 34
    },
    {
      "userId": "0a1b2c3d-4e5f-4061-8283-84858687888a",
      "username": "j.martin",
      "membershipStatus": "active",
      "lastActiveWeekStart": null,
      "activitiesCreated": 0,
      "personalQuestionsCreated": 0
    }
  ]
}

(le second enseignant, j.martin, n'a pas d'adresse email en base — le champ email est absent de l'objet, pas null ; il n'a par ailleurs jamais été actif, d'où lastActiveWeekStart: null.)

Exemple — token global, forme nommée :

curl -sS https://app.kutsum.org/api/v1/analytics/organizations/3f1b4b8a-2c4e-4b0a-9b7a-8e6f0f1a2b3c/members \
  -H 'Authorization: Bearer <token-global>'

Réponse de forme identique à l'exemple précédent.

Exemple — token global, forme courte, sans établissement nommé (400) :

curl -sS https://app.kutsum.org/api/v1/analytics/organizations/members \
  -H 'Authorization: Bearer <token-global>'

{
  "error": "This view always requires a named organization: a global-scoped token must call GET /organizations/:organizationId/members",
  "code": "ANALYTICS_ORGANIZATION_REQUIRED"
}

Erreurs spécifiques à cette route

(Ces deux codes s'ajoutent à ANALYTICS_UNAUTHORIZED, API_RATE_LIMIT_EXCEEDED et ANALYTICS_INTERNAL_ERROR, communs à toutes les routes de cette API — voir Codes d'erreur ci-dessous.)

Codes d'erreur

Un client doit toujours distinguer sur code (machine-readable), jamais sur error (prose humaine, peut changer sans préavis).

Forme d'un corps d'erreur (tous les codes ci-dessus) :

{
  "error": "Human-readable message (peut changer)",
  "code": "ANALYTICS_UNAUTHORIZED"
}