---
title: "@vonvon-kit/core"
description: "Cliente do navegador para estado de sessão, acesso JWT de curta duração e auxiliares da Management API."
locale: "pt-BR"
---

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

# @vonvon-kit/core

## Instalar e configurar

Status do registry: UNPUBLISHED. Instale este SDK somente a partir do checkout do código-fonte do repositório; não use um registry de pacotes externo.

Para uma aplicação de desenvolvedor em outra origem, configure `mode: 'oidc'` com issuer, clientId e um redirectUri exato. Use o modo same-origin apenas quando a aplicação rotear os endpoints de autenticação do Core em sua origem exata. O Vonvon não possui uma credencial 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 da sessão

- `load()` lê `/v1/me` e popula o usuário, a sessão e a organização ativa.
- `signInPassword()` estabelece uma sessão via cookie pelo fluxo de senha do Hosted Auth.
- `getToken()` retorna um JWT de curta duração para chamadas de API. Verifique sem rede no seu servidor com JWKS.
- `setActiveOrganization()` alterna o contexto da organização e limpa o cache de token antes de recarregar o estado.
- `signOut()` revoga o cookie de sessão do navegador.

## Auxiliares da Management API

Os helpers da Management API são restritos `ao servidor ou à mesma origem exata`. Crie um cliente separado com `sk_live_*` ou sk\_test\_\* no servidor; o modo OIDC do navegador rejeita essas operações.

```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 | Finalidade |
| --- | --- | --- |
| `VonvonClient` | class | Cliente de navegador de nível superior: load, signIn, getToken, setActiveOrganization, signOut e auxiliares da Management API |
| `VonvonStore` | class | Store reativo independente de framework; assine com useSyncExternalStore nos bindings de framework |
| `TokenManager` | class | Cache de JWT de curta duração e renovação agendada (uso avançado e testes) |
| `VonvonApiClient` | class | Cliente HTTP para os endpoints /v1/me e de token |
| `VonvonNetworkError` | class | Lançado em falhas de transporte: erro de rede, resposta não JSON, 5xx sem corpo estruturado |
| `makeVonvonError` | function | Constrói um VonvonError estruturado para falhas de validação locais sem chamada de rede |
| `isVonvonErrorShape` | function | Type guard: verifica se um valor desconhecido está em conformidade com o formato VonvonError recebido na rede |
| `decodeTokenClaims` | function | Decodifica as declarações do payload JWT apenas para agendamento de expiração; não verifica a assinatura |
| `isTokenExpiring` | function | Retorna true quando o token expira dentro da janela de tolerância (padrão 10 s) |
| `SESSION_STATUS` | tupla as const | Valores válidos de status de sessão: active, pending, expired, removed, ended, revoked |
| `CLIENT_STATUS` | tupla as const | Valores válidos de status do cliente: loading, ready, degraded, error |
| `PACKAGE` | constante de string | Identificador de nome de pacote '@vonvon-kit/core' |

## Tipos

| Tipo | Descrição |
| --- | --- |
| `VonvonUser` | Visão somente leitura do usuário autenticado (sem segredos ou hashes) |
| `VonvonOrganization` | Visão pública da organização |
| `VonvonOrganizationMembership` | Associação do usuário em uma organização com papel e permissões |
| `VonvonSession` | Visão da sessão incluindo status, expiração e organização ativa |
| `VonvonApiKey` | Chave de API sem segredo (visualização em lista) |
| `VonvonApiKeyWithSecret` | Chave de API retornada uma única vez na criação; inclui o campo key |
| `VonvonPage<T>` | Envelope de resposta paginado por cursor |
| `CreateApiKeyInput` | Entrada para createApiKey |
| `SignInPasswordInput` | Entrada para signInPassword |
| `SignInResult` | Resultado de signInPassword: próximo passo ou URL de redirecionamento |
| `SessionStatus` | União dos valores de SESSION\_STATUS |
| `ClientStatus` | União dos valores de CLIENT\_STATUS |
| `VonvonState` | Snapshot completo do estado do SDK obtido por assinatura do VonvonStore |
| `VonvonStateListener` | Tipo de callback para listener de mudança de estado |
| `Unsubscribe` | Tipo de retorno de VonvonStore.subscribe |
| `GetTokenOptions` | Opções para getToken: skipCache, leewaySeconds, signal |
| `VonvonClientOptions` | Opções discriminadas do construtor VonvonClient: same-origin aceita apiUrl, secretKey, fetcher e now; oidc exige issuer, clientId e redirectUri. |
| `TokenResponse` | Formato bruto da resposta do endpoint de token |
| `ClientStateResponse` | Formato bruto da resposta de /v1/me |
| `DecodedTokenClaims` | Declarações do payload JWT retornadas por decodeTokenClaims |

## Documentação relacionada

Bindings de framework: [@vonvon-kit/react](/pt-br/sdks/react). Verificação no servidor: [@vonvon-kit/backend](/pt-br/sdks/backend).

Source: https://vonvon.id/pt-br/sdks/core/index.mdx