@vonvon-kit/core

Cliente do navegador para estado de sessão, acesso JWT de curta duração e auxiliares da Management API.

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.

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.

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. Verificação no servidor: @vonvon-kit/backend.