---
title: "@vonvon-kit/core"
description: "Client navigateur pour l'état de session, l'accès JWT de courte durée et les assistants de l'API de gestion."
locale: "fr"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/fr/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# @vonvon-kit/core

## Installer et configurer

Statut du registre : UNPUBLISHED. Installez ce SDK uniquement depuis un checkout du code source du dépôt ; n'utilisez pas de registre de paquets externe.

Pour une application de développeur sur une autre origine, configurez `mode: 'oidc'` avec issuer, clientId et un redirectUri exact. Utilisez le mode same-origin uniquement lorsque l'application route les points de terminaison d'authentification Core sur son origine exacte. Vonvon ne possède aucun identifiant publishable-key.

```ts
import { VonvonClient } from '@vonvon-kit/core'

const vonvon = new VonvonClient({
  mode: 'oidc',
  issuer: 'https://vonvon.id',
  clientId: 'client_abc123',
  redirectUri: 'https://app.example.com/auth/callback',
})

const authorization = await vonvon.createAuthorizationUrl({ returnUrl: '/dashboard' })
if (!authorization.ok) throw new Error(authorization.error.message)
window.location.assign(authorization.value)
```

## Cycle de vie de session

- `load()` lit `/v1/me` et hydrate l'utilisateur, la session et l'organisation active.
- `signInPassword()` établit une session cookie via le flux de mot de passe Hosted Auth.
- `getToken()` retourne un JWT de courte durée pour les appels API. Vérifiez sans réseau sur votre serveur avec JWKS.
- `setActiveOrganization()` change le contexte d'organisation et vide le cache de jeton avant de recharger l'état.
- `signOut()` révoque le cookie de session du navigateur.

## Assistants de l'API de gestion

Les helpers Management API sont réservés `au serveur ou à une origine strictement identique`. Construisez un client distinct avec `sk_live_*` ou sk\_test\_\* sur le serveur; le mode navigateur OIDC rejette ces opérations.

```ts
const management = new VonvonClient({
  apiUrl: 'https://vonvon.id',
  secretKey: process.env.VONVON_SECRET_KEY,
})

const keys = await management.listApiKeys()
if (!keys.ok) throw new Error(keys.error.message)

const created = await management.createApiKey({ name: 'CI deploy', scopes: ['read'] })
if (!created.ok) throw new Error(created.error.message)

const revoked = await management.revokeApiKey({ id: created.value.id })
if (!revoked.ok) throw new Error(revoked.error.message)
```

## API exportée

| Exporter | Type | Objectif |
| --- | --- | --- |
| `VonvonClient` | class | Client navigateur de niveau supérieur : load, signIn, getToken, setActiveOrganization, signOut et assistants de l'API de gestion |
| `VonvonStore` | class | Store réactif indépendant du framework ; s'abonner avec useSyncExternalStore dans les liaisons framework |
| `TokenManager` | class | Cache JWT de courte durée et rafraîchissement planifié (usage avancé et tests) |
| `VonvonApiClient` | class | Client HTTP pour les points de terminaison /v1/me et token |
| `VonvonNetworkError` | class | Levée lors d'échecs de transport : erreur réseau, réponse non-JSON, 5xx sans corps structuré |
| `makeVonvonError` | function | Construit un VonvonError structuré pour les échecs de validation locaux sans aller-retour réseau |
| `isVonvonErrorShape` | function | Type guard : vérifie si une valeur inconnue est conforme à la structure VonvonError depuis le réseau |
| `decodeTokenClaims` | function | Décode les revendications du payload JWT uniquement pour la planification d'expiration ; ne vérifie pas la signature |
| `isTokenExpiring` | function | Retourne true lorsque le token expire dans la fenêtre de tolérance (défaut 10 s) |
| `SESSION_STATUS` | tuple as const | Valeurs valides du statut de session : active, pending, expired, removed, ended, revoked |
| `CLIENT_STATUS` | tuple as const | Valeurs valides du statut client : loading, ready, degraded, error |
| `PACKAGE` | constante string | Identifiant du nom de package '@vonvon-kit/core' |

## Types

| Type | Description |
| --- | --- |
| `VonvonUser` | Vue en lecture seule de l'utilisateur authentifié (sans secrets ni hachages) |
| `VonvonOrganization` | Vue publique de l'organisation |
| `VonvonOrganizationMembership` | Appartenance d'un utilisateur à une organisation avec rôle et permissions |
| `VonvonSession` | Vue de session incluant le statut, l'expiration et l'organisation active |
| `VonvonApiKey` | Clé API sans secret (vue liste) |
| `VonvonApiKeyWithSecret` | Clé API retournée une seule fois à la création ; contient le champ key |
| `VonvonPage<T>` | Enveloppe de réponse paginée par curseur |
| `CreateApiKeyInput` | Entrée pour createApiKey |
| `SignInPasswordInput` | Entrée pour signInPassword |
| `SignInResult` | Résultat de signInPassword : étape suivante ou URL de redirection |
| `SessionStatus` | Union des valeurs de SESSION\_STATUS |
| `ClientStatus` | Union des valeurs de CLIENT\_STATUS |
| `VonvonState` | Instantané complet de l'état SDK souscrit depuis VonvonStore |
| `VonvonStateListener` | Type de callback de listener de changement d'état |
| `Unsubscribe` | Type de retour de VonvonStore.subscribe |
| `GetTokenOptions` | Options pour getToken : skipCache, leewaySeconds, signal |
| `VonvonClientOptions` | Options discriminées du constructeur VonvonClient: same-origin accepte apiUrl, secretKey, fetcher et now; oidc exige issuer, clientId et redirectUri. |
| `TokenResponse` | Structure de réponse brute du point de terminaison token |
| `ClientStateResponse` | Structure de réponse brute de /v1/me |
| `DecodedTokenClaims` | Revendications du payload JWT retournées par decodeTokenClaims |

## Documentation connexe

Liaisons framework : [@vonvon-kit/react](/fr/sdks/react). Vérification serveur : [@vonvon-kit/backend](/fr/sdks/backend).

Source: https://vonvon.id/fr/sdks/core/index.mdx