@hezor/hezor2-sdk

Hezor2 SDK，供第三方项目引入使用。

安装

# npm
npm install @hezor/hezor2-sdk

# yarn
yarn add @hezor/hezor2-sdk

# pnpm
pnpm add @hezor/hezor2-sdk

使用

import { greet, VERSION } from '@hezor/hezor2-sdk'

console.log(VERSION)         // '0.1.0'
console.log(greet('Alice'))  // 'Hello from @hezor/hezor2-sdk, Alice!'

OAuth 2.0 客户端

OAuthClient 封装了 hezor2 后端 /oauth/* 全部端点，覆盖两类典型用法：

• Authorization Code + PKCE：浏览器跳转 / 服务端代用户授权（第三方 Web/移动应用）。
• Device Authorization Grant（RFC 8628）：无浏览器环境（CLI、starship、嵌入式 runtime）。

两种流程都支持 refresh_token 续期与 RFC 7009 revoke。

Authorization Code + PKCE（第三方应用）

import { OAuthClient, generatePKCEPair, generateState } from '@hezor/hezor2-sdk'

const client = new OAuthClient({
  // baseUrl 必须包含 `/api/v1` 前缀；SDK 所有路径按 `${baseUrl}${path}` 拼接
  baseUrl: 'https://hezor.example.com/api/v1',
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.example.com/callback',
})

// 1) 跳转用户去授权
const pkce = await generatePKCEPair()
const state = generateState()
// 把 pkce.code_verifier / state 存到 session，回调时取回
const url = client.buildAuthorizeUrl({
  state,
  codeChallenge: pkce.code_challenge,
  scope: 'base:user-info base:llm-invoke',
})
// window.location.href = url

// 2) 回调拿到 code 后换 token
const token = await client.exchangeAuthorizationCode({
  code: 'CODE_FROM_CALLBACK',
  codeVerifier: pkce.code_verifier,
})

// 3) 续期 / 撤销
const refreshed = await client.refreshToken(token.refresh_token!)
await client.revokeToken(refreshed.refresh_token!, 'refresh_token')

Device Authorization Grant（代理进程 / starship）

import { OAuthClient } from '@hezor/hezor2-sdk'

const client = new OAuthClient({
  baseUrl: 'https://hezor.example.com/api/v1',
  clientId: 'your-device-client-id',
})

// 1) 申请 device_code
const dc = await client.requestDeviceCode({
  deviceId: 'demo-host-1234',
  hostname: 'demo-host',
  os: 'darwin',
  runtimeKind: 'starship',
  vendor: 'hezor',
  scope: 'device:bind silicon:proxy base:llm-invoke',
})

// 2) 提示用户在浏览器输入 user_code
console.log(`请打开：${dc.verification_uri_complete}`)
console.log(`输入码：${dc.user_code}`)

// 3) 轮询 token（自动处理 authorization_pending / slow_down）
const token = await client.pollDeviceToken({
  deviceCode: dc.device_code,
  interval: dc.interval,
  expiresIn: dc.expires_in,
})

完整可运行示例：examples/oauth-auth-code.ts / examples/oauth-device-flow.ts。

错误处理：协议错误以 OAuthError 抛出（code 字段为 RFC 6749 错误码）；invalid_grant 单独以 OAuthInvalidGrantError 抛出，便于上层针对失效 token 做特殊处理。

开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 开发模式（监听变更）
pnpm dev

# 类型检查
pnpm typecheck

# 运行完整测试套件（单元 + e2e mock）
pnpm test

# 仅运行 OAuth e2e mock 测试（pnpm test 的子集，快速调试用）
pnpm test:e2e

# 运行测试（监听模式）
pnpm test:watch

# 测试覆盖率
pnpm test:coverage

# Examples smoke test（验证非交互示例不崩溃）
pnpm test:examples

# Lint
pnpm lint

# 格式化
pnpm format

测试分层说明

| 命令 | 内容 | CI | |---|---|---| | pnpm test | 单元测试 + e2e mock（全部）| ✅ 每次 push | | pnpm test:e2e | OAuth e2e mock（pnpm test 的子集，局部调试用）| — | | pnpm test:examples | examples smoke test（非交互示例）| ✅ 每次 push | | e2e:real（预留） | 真实 hezor2 dev server 跑通全链路 | 手动，仅 release 前 |

e2e:real 跑法（release 前手动）：

1. cd deploy && docker compose up -d（起 hezor2 dev server）
2. 配置 examples/.env（HEZOR2_API_BASE_URL、OAUTH_CLIENT_ID 等）
3. npx tsx examples/oauth-auth-code.ts / npx tsx examples/oauth-device-flow.ts

发布

# 先登录 npm
npm login

# 发布（自动执行 build + typecheck）
npm publish --access public

License

MIT