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

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

# @xid-kit/core

## 安装与配置

将 `apiUrl` 指向你的 XID 实例来源（托管或自托管）。SDK 不会存储客户端密钥，也不会将 refresh token 内容暴露给浏览器脚本。

```ts
import { XidClient } from '@xid-kit/core'

const xid = new XidClient({ apiUrl: 'https://xid.dev' })
await xid.load()
const token = await xid.getToken()
```

## 会话生命周期

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

## Management API 辅助工具

当前版本仅封装了 API 密钥管理。其他所有 Management API 资源需直接使用 `/v1/` REST 调用，并携带 `Authorization: Bearer sk_live_xxx`。

```ts
const keys = await xid.listApiKeys()
const created = await xid.createApiKey({ name: 'CI deploy', scopes: ['read'] })
await xid.revokeApiKey(created.id)
```

## 导出的 API

| 导出 | 类型 | 用途 |
| --- | --- | --- |
| `XidClient` | class | 顶层浏览器客户端：load、signIn、getToken、setActiveOrganization、signOut 及 Management API 辅助工具 |
| `XidStore` | class | 与框架无关的响应式 store；在框架绑定中使用 useSyncExternalStore 订阅 |
| `TokenManager` | class | 短期 JWT 缓存和定时刷新（高级用法和测试） |
| `XidApiClient` | class | 用于 /v1/me 和 token 端点的 HTTP 客户端 |
| `XidNetworkError` | class | 传输失败时抛出：网络错误、非 JSON 响应、无结构体的 5xx 响应 |
| `makeXidError` | function | 为本地校验失败构建结构化 XidError，无需网络往返 |
| `isXidErrorShape` | function | 类型守卫：检查未知值是否符合网络传输中的 XidError 结构 |
| `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` | 字符串常量 | 包名标识符 '@xid-kit/core' |

## 类型

| 类型 | 描述 |
| --- | --- |
| `XidUser` | 已认证用户的只读视图（不含密钥或哈希） |
| `XidOrganization` | 组织公开视图 |
| `XidOrganizationMembership` | 用户在组织中的成员关系，包含角色和权限 |
| `XidSession` | 包含状态、过期时间和当前组织的会话视图 |
| `XidApiKey` | 不含密钥的 API 密钥（列表视图） |
| `XidApiKeyWithSecret` | 创建时返回一次的 API 密钥，包含 key 字段 |
| `XidPage<T>` | 游标分页响应封装 |
| `CreateApiKeyInput` | createApiKey 的输入类型 |
| `SignInPasswordInput` | signInPassword 的输入类型 |
| `SignInResult` | signInPassword 的返回结果：下一步或重定向 URL |
| `SessionStatus` | SESSION\_STATUS 取值的联合类型 |
| `ClientStatus` | CLIENT\_STATUS 取值的联合类型 |
| `XidState` | 从 XidStore 订阅的完整 SDK 状态快照 |
| `XidStateListener` | 状态变更监听器 callback 类型 |
| `Unsubscribe` | XidStore.subscribe 的返回类型 |
| `GetTokenOptions` | getToken 的选项：template、skipCache、leewaySeconds、signal |
| `XidClientOptions` | XidClient 构造选项：apiUrl、fetcher、now |
| `TokenResponse` | token 端点原始响应结构 |
| `ClientStateResponse` | /v1/me 原始响应结构 |
| `DecodedTokenClaims` | decodeTokenClaims 返回的 JWT payload claims |

## 相关文档

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

Source: https://xid.dev/zh-hans/sdks/core/index.mdx