SDK de lecture

@vskstudio/takt-read est un SDK TypeScript côté serveur au-dessus de l'API HTTP de lecture. Il encapsule les endpoints /api/v1/sites/{domain}/stats/* (authentifiés par clé Bearer) dans des méthodes typées, pour rapatrier tes statistiques dans un backend, un cron ou une route d'API sans écrire le HTTP à la main.

pnpm add @vskstudio/takt-read

Il a zéro dépendance runtime, fournit ESM + CJS et nécessite Node.js ≥ 18 (fetch natif).

Démarrage rapide

import TaktClient from '@vskstudio/takt-read'

const takt = new TaktClient({
  apiKey: process.env.TAKT_API_KEY!, // secret — à garder côté serveur
  domain: 'exemple.com',
  baseUrl: 'https://app.taktlytics.com/api/v1',
  timeoutMs: 30_000, // optionnel, 30s par défaut
  retries: 2 // optionnel, 2 par défaut (réessaie 429 + 5xx avec backoff)
})

const resume = await takt.stats.summary({ period: '30d' })
console.log(resume.visitors, resume.pageviews)

baseUrl est obligatoire : pointe-le vers la racine /api/v1 de ton instance Takt. Le constructeur valide ses options et lève une TaktError (code: 'config_invalide') en cas d’entrée invalide.

Options de TaktClient :

Méthodes de stats

Tous les endpoints de lecture vivent sous takt.stats. Chaque méthode accepte un dernier argument optionnel { signal } pour l’annulation via un AbortController.

const ac = new AbortController()
const realtime = await takt.stats.realtime({ signal: ac.signal })

// Plusieurs classements en une requête
const { breakdowns } = await takt.stats.breakdowns(['pages', 'sources'], { period: '30d' })

// Export du classement des pages (nécessite `org` sur le client)
const csv = await takt.stats.export({ period: '30d' }) // chaîne CSV brute
const rows = await takt.stats.export({ period: '30d', format: 'json' }) // StatsExportRow[]

Options de requête

Les méthodes de lecture acceptent un StatsQuery optionnel : une period (day, 7d, 30d, month, 6mo, 12mo) ou un intervalle explicite from/to, plus tz, country, interval, compare, limit et des filtres segment.

await takt.stats.timeseries({
  period: '30d',
  interval: 'day',
  tz: 'Europe/Paris',
  compare: true, // inclut la période précédente
  segment: [
    { dim: 'browser', op: 'is', val: 'Firefox' },
    { dim: 'page', op: 'contains', val: '/blog', join: 'or' }
  ]
})

Gestion des erreurs

Les réponses non-2xx lèvent une TaktError portant le statut HTTP et le code d’erreur de l’API. Le SDK lève aussi config_invalide sur des options invalides, timeout quand une requête dépasse timeoutMs, et erreur_reseau en cas de panne réseau.

import { TaktError } from '@vskstudio/takt-read'

try {
  await takt.stats.summary()
} catch (err) {
  if (err instanceof TaktError && err.code === 'quota_api_depasse') {
    // quota mensuel d'API dépassé (HTTP 402)
  }
}