---
title: "@vonvon-kit/core"
description: "Cliente de navegador para estado de sesión, acceso JWT de corta duración y utilidades de la API de administración."
locale: "es"
---

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

# @vonvon-kit/core

## Instalar y configurar

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

Para una aplicación de desarrollador en otro origen, configure `mode: 'oidc'` con issuer, clientId y una redirectUri exacta. Use el modo same-origin únicamente cuando la aplicación enrute los endpoints de autenticación de Core en su origen exacto. Vonvon no tiene credenciales de 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)
```

## Ciclo de vida de la sesión

- `load()` lee `/v1/me` e hidrata el usuario, la sesión y la organización activa.
- `signInPassword()` establece una sesión con cookie a través del flujo de contraseña de Hosted Auth.
- `getToken()` devuelve un JWT de corta duración para llamadas a la API. Verifícalo sin llamadas de red en tu servidor con JWKS.
- `setActiveOrganization()` cambia el contexto de organización y limpia el caché de tokens antes de recargar el estado.
- `signOut()` revoca la cookie de sesión del navegador.

## Utilidades de la API de administración

Los helpers de Management API son `exclusivos del servidor o de un origen exactamente igual`. Cree un cliente independiente con `sk_live_*` o sk\_test\_\* en el servidor; el modo OIDC del navegador rechaza estas operaciones.

```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 exportada

| Exportar | Tipo | Propósito |
| --- | --- | --- |
| `VonvonClient` | class | Cliente de navegador de nivel superior: load, signIn, getToken, setActiveOrganization, signOut y utilidades de la API de administración |
| `VonvonStore` | class | Store reactivo independiente del framework; suscríbete con useSyncExternalStore en los vínculos del framework |
| `TokenManager` | class | Caché JWT de corta duración y refresco programado (uso avanzado y pruebas) |
| `VonvonApiClient` | class | Cliente HTTP para los endpoints /v1/me y de tokens |
| `VonvonNetworkError` | class | Lanzado en fallos de transporte: error de red, respuesta no JSON, 5xx sin cuerpo estructurado |
| `makeVonvonError` | function | Construye un VonvonError estructurado para fallos de validación locales sin ida y vuelta de red |
| `isVonvonErrorShape` | function | Protector de tipo: verifica si un valor desconocido se ajusta a la forma VonvonError del wire |
| `decodeTokenClaims` | function | Decodifica las declaraciones del payload JWT solo para programación de expiración; no verifica la firma |
| `isTokenExpiring` | function | Devuelve true cuando el token expira dentro de la ventana de tolerancia (predeterminado 10 s) |
| `SESSION_STATUS` | tupla as const | Valores válidos de estado de sesión: active, pending, expired, removed, ended, revoked |
| `CLIENT_STATUS` | tupla as const | Valores válidos de estado del cliente: loading, ready, degraded, error |
| `PACKAGE` | constante de cadena | Identificador de nombre de paquete '@vonvon-kit/core' |

## Tipos

| Tipo | Descripción |
| --- | --- |
| `VonvonUser` | Vista de solo lectura del usuario autenticado (sin secretos ni hashes) |
| `VonvonOrganization` | Vista pública de la organización |
| `VonvonOrganizationMembership` | Membresía de usuario en una organización con rol y permisos |
| `VonvonSession` | Vista de sesión con estado, expiración y organización activa |
| `VonvonApiKey` | Clave API sin secreto (vista de lista) |
| `VonvonApiKeyWithSecret` | Clave API devuelta una sola vez al crearla; incluye el campo key |
| `VonvonPage<T>` | Envoltorio de respuesta con paginación por cursor |
| `CreateApiKeyInput` | Entrada para createApiKey |
| `SignInPasswordInput` | Entrada para signInPassword |
| `SignInResult` | Resultado de signInPassword: siguiente paso o URL de redirección |
| `SessionStatus` | Unión de valores de SESSION\_STATUS |
| `ClientStatus` | Unión de valores de CLIENT\_STATUS |
| `VonvonState` | Instantánea completa del estado del SDK suscrita desde VonvonStore |
| `VonvonStateListener` | Tipo de callback para escucha de cambios de estado |
| `Unsubscribe` | Tipo de retorno de VonvonStore.subscribe |
| `GetTokenOptions` | Opciones para getToken: skipCache, leewaySeconds, signal |
| `VonvonClientOptions` | Opciones discriminadas del constructor de VonvonClient: same-origin acepta apiUrl, secretKey, fetcher y now; oidc requiere issuer, clientId y redirectUri. |
| `TokenResponse` | Forma de la respuesta bruta del endpoint de token |
| `ClientStateResponse` | Forma de la respuesta bruta de /v1/me |
| `DecodedTokenClaims` | Declaraciones del payload JWT devueltas por decodeTokenClaims |

## Documentación relacionada

Vínculos de framework: [@vonvon-kit/react](/es/sdks/react). Verificación en servidor: [@vonvon-kit/backend](/es/sdks/backend).

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