---
title: "@vonvon-kit/core"
description: "Browser client for session state, short-lived JWT access, and Management API helpers."
locale: "en"
---

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

# @vonvon-kit/core

## Install and configure

Registry status: UNPUBLISHED. Install this SDK only from the repository source checkout; do not use an external package registry.

For a developer app on another origin, configure `mode: 'oidc'` with issuer, clientId, and an exact redirectUri. Use same-origin mode only when the application routes Core auth endpoints on its exact origin. Vonvon has no publishable-key credential.

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

## Session lifecycle

- `load()` reads `/v1/me` and hydrates user, session, and active organization.
- `signInPassword()` establishes a cookie session through Hosted Auth password flow.
- `getToken()` returns a short-lived JWT for API calls. Verify networklessly on your backend with JWKS.
- `setActiveOrganization()` switches org context and clears the token cache before reloading state.
- `signOut()` revokes the browser session cookie.

## Management API helpers

Management API helpers are `server-side or exact same-origin only`. Construct a separate client with `sk_live_*` or sk\_test\_\* on the server; OIDC browser mode rejects these operations.

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

## Exported API

| Export | Kind | Purpose |
| --- | --- | --- |
| `VonvonClient` | class | Top-level browser client: load, signIn, getToken, setActiveOrganization, signOut, and Management API helpers |
| `VonvonStore` | class | Framework-agnostic reactive store; subscribe with useSyncExternalStore in framework bindings |
| `TokenManager` | class | Short-lived JWT cache and scheduled refresh (advanced use and testing) |
| `VonvonApiClient` | class | HTTP client for /v1/me and token endpoints |
| `VonvonNetworkError` | class | Thrown on transport failures: network error, non-JSON response, 5xx with no structured body |
| `makeVonvonError` | function | Construct a structured VonvonError for local validation failures without a network round-trip |
| `isVonvonErrorShape` | function | Type guard: checks whether an unknown value conforms to VonvonError shape from the wire |
| `decodeTokenClaims` | function | Decode JWT payload claims for expiry scheduling only; does not verify the signature |
| `isTokenExpiring` | function | Returns true when the token expires within the leeway window (default 10 s) |
| `SESSION_STATUS` | as const tuple | Valid session status values: active, pending, expired, removed, ended, revoked |
| `CLIENT_STATUS` | as const tuple | Valid client status values: loading, ready, degraded, error |
| `PACKAGE` | string constant | Package name identifier '@vonvon-kit/core' |

## Types

| Type | Description |
| --- | --- |
| `VonvonUser` | Read-only view of the authenticated user (no secrets or hashes) |
| `VonvonOrganization` | Public organization view |
| `VonvonOrganizationMembership` | User membership in an org with role and permissions |
| `VonvonSession` | Session view including status, expiry, and active org |
| `VonvonApiKey` | API key without secret (list view) |
| `VonvonApiKeyWithSecret` | API key returned once at creation; includes the key field |
| `VonvonPage<T>` | Cursor-paginated response envelope |
| `CreateApiKeyInput` | Input for createApiKey |
| `SignInPasswordInput` | Input for signInPassword |
| `SignInResult` | Result from signInPassword: next step or redirect URL |
| `SessionStatus` | Union of SESSION\_STATUS values |
| `ClientStatus` | Union of CLIENT\_STATUS values |
| `VonvonState` | Full SDK state snapshot subscribed from VonvonStore |
| `VonvonStateListener` | State change listener callback type |
| `Unsubscribe` | Return type of VonvonStore.subscribe |
| `GetTokenOptions` | Options for getToken: skipCache, leewaySeconds, signal |
| `VonvonClientOptions` | Discriminated VonvonClient constructor options: same-origin accepts apiUrl, secretKey, fetcher, and now; oidc requires issuer, clientId, and redirectUri. |
| `TokenResponse` | Raw token endpoint response shape |
| `ClientStateResponse` | Raw /v1/me response shape |
| `DecodedTokenClaims` | JWT payload claims returned by decodeTokenClaims |

## Related docs

Framework bindings: [@vonvon-kit/react](/sdks/react). Server verification: [@vonvon-kit/backend](/sdks/backend).

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