TypeScript SDK
@21stware/raise-sdk 是 Raise 开放接口的 TypeScript 服务端 SDK，给集成方、小程序后台、三方 SaaS 和应用后端用。换令牌、重试、分页、幂等和 Webhook 验签都在里面。
- 包名：
@21stware/raise-sdk - 当前版本：0.7.7（2026-11-03），遵循语义化版本
- 运行环境：Node.js 18+、Deno、Bun、Cloudflare Workers；ESM 与 CommonJS 都能引用
- 零运行时依赖
注意
这是服务端 SDK。客户端密钥只放在服务端，不要打进浏览器页面或小程序前端。
安装
这个包不在公共 npm 注册表上，从平台的开发者门户下载安装，不用登录：
npm install "https://dev.<你的域名>/dl/sdk/21stware-raise-sdk-0.7.7.tgz"文件名带版本号。先看平台提供的是哪个版本：
curl https://dev.<你的域名>/dl/sdk/把命令里的文件名换成列表里的那个。
第一次调用
import { Raise } from '@21stware/raise-sdk'
const raise = new Raise({
clientId: process.env.RAISE_CLIENT_ID!,
clientSecret: process.env.RAISE_CLIENT_SECRET!,
tenant: process.env.RAISE_TENANT,
baseUrl: `https://api.${process.env.DOMAIN}/open/v1`,
})
const me = await raise.platform.whoami()
console.log(me.tenant, me.app, me.scopes)baseUrl：你的部署的开放接口地址https://api.<你的域名>/open/v1。请总是写上。tenant：自建应用的密钥绑定了组织，可以不写；商店应用要写你在为哪个组织调用。为多个组织调用时用raise.withTenant('<组织 ID>')，共享一份令牌缓存。
令牌在第一次调用时才去换，按组织缓存，到期前 60 秒自动换新；同时发起多个调用时只换一次。
分页
列表接口返回 { data, nextCursor }，nextCursor 为 null 就是最后一页。每个列表方法都有一个 …All 版本，自动翻页：用完一页才取下一页，break 即停止请求。
const page = await raise.tables.listRows('orders', 'all', { limit: 100 })
for await (const row of raise.tables.listRowsAll('orders', 'all')) {
console.log(row)
}错误与重试
状态码 400 及以上一律抛 RaiseError。按 code 分支，不要解析 message；联系支持时带上 requestId。
import { isRaiseError } from '@21stware/raise-sdk'
try {
await raise.platform.whoami()
} catch (e) {
if (isRaiseError(e, 'scope_required')) console.error('应用没有被授予这个范围', e.requestId)
else throw e
}自动重试的规则：
| 情况 | 处理 |
|---|---|
| 429、5xx、网络错误 | GET 等幂等方法，以及带 Idempotency-Key 的 POST 自动重试，默认最多 3 次（maxRetries） |
| POST 的幂等键 | SDK 给每个 POST 自动生成一个，重试时不变 |
| 等多久 | 有 Retry-After 就照它等；否则 0.5 s × 2ⁿ 加抖动，最长 8 s |
令牌失效（401 invalid_token） | 自动换一次令牌再试 |
以客户身份调用
会员小程序等场景：用客户的手机号断言客户，拿到一个只能调用 /me… 接口的客户端。
const cu = await raise.forCustomer({ phone: '+8613800000000' })
if (!cu) return '没有这个会员'
const profile = await cu.me.listMemberships()没有人用这个号时返回 null；几个客户共用一个号时抛 ambiguous_customer，候选在 details.candidates 里，选一个再调用。
Webhook 验签
收到事件时，用原始请求体（不要先 JSON.parse 再序列化）和 X-Kwork-Signature 请求头验签。签名不对或时间戳超过 300 秒，抛 WebhookVerificationError，回 400 即可。
import { webhooks } from '@21stware/raise-sdk'
const event = await webhooks.verify(rawBody, req.headers['x-kwork-signature'], process.env.RAISE_WEBHOOK_SECRET!)
if (event.type === 'app.installed') console.log('装到了', event.tenant)测试与正式
密钥分两种：kwo_test_… 只能用于你开发者组织的测试企业，kwo_live_… 只能用于正式企业，拿错了得到 403 wrong_environment。代码不用改，换环境变量里的密钥和 tenant 即可。令牌响应和每个接口的 Raise-Environment 响应头会告诉你当前是哪个环境。