@xid-kit/core

用于管理会话状态、短期 JWT 访问及 Management API 的浏览器客户端。

安装与配置

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

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。

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