---
title: "@vonvon-kit/core"
description: "用于管理会话状态、短期 JWT 访问及 Management API 的浏览器客户端。"
locale: "zh-Hans"
---

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

# @vonvon-kit/core

## 安装与配置

Registry 状态:UNPUBLISHED。此 SDK 只能从仓库源码 checkout 安装；不要使用外部 package registry。

对于位于其他 origin 的开发者应用，请使用 issuer、clientId 和精确的 redirectUri 配置 `mode: 'oidc'`。仅当应用在其自身精确 origin 上路由 Core auth endpoints 时才使用 same-origin mode。Vonvon 不存在 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)
```

## 会话生命周期

- `load()` 读取 `/v1/me` 并填充用户、会话和当前组织状态。
- `signInPassword()` 通过 Hosted Auth 密码流程建立 cookie 会话。
- `getToken()` 返回供 API 调用的短期 JWT。可在后端使用 JWKS 进行无网络验证。
- `setActiveOrganization()` 切换组织上下文，在重新加载状态前清除 token 缓存。
- `signOut()` 吊销浏览器会话 cookie。

## Management API 辅助工具

Management API helpers `仅限 server-side 或精确的 same-origin`。请在 server 上使用 `sk_live_*` 或 sk\_test\_\* 构建单独的 client；OIDC browser mode 会拒绝这些操作。

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

| 导出 | 类型 | 用途 |
| --- | --- | --- |
| `VonvonClient` | class | 顶层浏览器客户端：load、signIn、getToken、setActiveOrganization、signOut 及 Management API 辅助工具 |
| `VonvonStore` | class | 与框架无关的响应式 store；在框架绑定中使用 useSyncExternalStore 订阅 |
| `TokenManager` | class | 短期 JWT 缓存和定时刷新（高级用法和测试） |
| `VonvonApiClient` | class | 用于 /v1/me 和 token 端点的 HTTP 客户端 |
| `VonvonNetworkError` | class | 传输失败时抛出：网络错误、非 JSON 响应、无结构体的 5xx 响应 |
| `makeVonvonError` | function | 为本地校验失败构建结构化 VonvonError，无需网络往返 |
| `isVonvonErrorShape` | function | 类型守卫：检查未知值是否符合网络传输中的 VonvonError 结构 |
| `decodeTokenClaims` | function | 仅用于过期调度的 JWT payload claims 解码；不验证签名 |
| `isTokenExpiring` | function | 当 token 在宽限窗口内过期时返回 true（默认 10 秒） |
| `SESSION_STATUS` | as const 元组 | 有效的会话状态取值：active、pending、expired、removed、ended、revoked |
| `CLIENT_STATUS` | as const 元组 | 有效的客户端状态取值：loading、ready、degraded、error |
| `PACKAGE` | 字符串常量 | 包名标识符 '@vonvon-kit/core' |

## 类型

| 类型 | 描述 |
| --- | --- |
| `VonvonUser` | 已认证用户的只读视图（不含密钥或哈希） |
| `VonvonOrganization` | 组织公开视图 |
| `VonvonOrganizationMembership` | 用户在组织中的成员关系，包含角色和权限 |
| `VonvonSession` | 包含状态、过期时间和当前组织的会话视图 |
| `VonvonApiKey` | 不含密钥的 API 密钥（列表视图） |
| `VonvonApiKeyWithSecret` | 创建时返回一次的 API 密钥，包含 key 字段 |
| `VonvonPage<T>` | 游标分页响应封装 |
| `CreateApiKeyInput` | createApiKey 的输入类型 |
| `SignInPasswordInput` | signInPassword 的输入类型 |
| `SignInResult` | signInPassword 的返回结果：下一步或重定向 URL |
| `SessionStatus` | SESSION\_STATUS 取值的联合类型 |
| `ClientStatus` | CLIENT\_STATUS 取值的联合类型 |
| `VonvonState` | 从 VonvonStore 订阅的完整 SDK 状态快照 |
| `VonvonStateListener` | 状态变更监听器 callback 类型 |
| `Unsubscribe` | VonvonStore.subscribe 的返回类型 |
| `GetTokenOptions` | getToken 的选项：skipCache、leewaySeconds、signal |
| `VonvonClientOptions` | 可判别的 VonvonClient constructor options：same-origin 接受 apiUrl、secretKey、fetcher 和 now；oidc 要求 issuer、clientId 和 redirectUri。 |
| `TokenResponse` | token 端点原始响应结构 |
| `ClientStateResponse` | /v1/me 原始响应结构 |
| `DecodedTokenClaims` | decodeTokenClaims 返回的 JWT payload claims |

## 相关文档

框架绑定：[@vonvon-kit/react](/zh-hans/sdks/react)。服务端验证：[@vonvon-kit/backend](/zh-hans/sdks/backend)。

Source: https://vonvon.id/zh-hans/sdks/core/index.mdx