JavaScript / TypeScript SDK

kestrel-sdk —— 零依赖、约 1 KB gzip、纯被动捕获。

安装

npm install kestrel-sdk
# 或：bun add kestrel-sdk / pnpm add kestrel-sdk / yarn add kestrel-sdk

初始化

应用入口处尽早调用一次 init() —— 越早越好，最好在任何可能抛错的代码之前。

import { init } from 'kestrel-sdk'

init({
  endpoint: 'https://kestrel.example.com/api/v1/ingest',
  token: process.env.KESTREL_TOKEN!, // 永远从环境变量读，不要 inline 写在源码里
  release: process.env.GIT_COMMIT,    // 可选；省略时会自动检测
})

init() 注册运行时的未捕获异常钩子后立即返回。挂上之后下面这些会自动捕获：

• 浏览器 —— window.error、window.unhandledrejection。
• Node / Bun / Deno —— uncaughtException、unhandledRejection。

接入到此结束。完事。

配置项

init({
  endpoint: string,           // 必填——你的 /api/v1/ingest URL
  token: string,              // 必填——项目 ingest token
  release?: string,           // 构建标识；不填会自动尝试常见环境变量
  fetch?: typeof fetch,       // 覆盖 fetch 实现（SSR / 测试）
  recordConsole?: boolean,    // 见下文"console buffer"；默认 false
})

release 自动检测顺序：import.meta.env.GIT_COMMIT → import.meta.env.VITE_GIT_COMMIT → import.meta.env.PUBLIC_GIT_COMMIT → globalThis.KESTREL_RELEASE → process.env.KESTREL_RELEASE → process.env.GIT_COMMIT → process.env.npm_package_version。第一个解析到的就赢。

手动捕获

有时候你需要记录一个异常但不让它继续抛。第二个参数是只附加到这一条事件的自由 context 对象：

import { capture } from 'kestrel-sdk'

try {
  await thingThatMightFail()
} catch (err) {
  capture(err, { userId, requestId })
  // ...你的兜底逻辑
}

手动捕获 API 存在，但不作为推荐的接入方式。SDK 的本职是接住你代码漏的；如果你在到处调 capture()，那这个 SDK 干的事比 console.error 还少。

Console buffer（opt-in）

想把最近 N 条 console.* 调用挂到每条捕获的事件上：

init({ ..., recordConsole: true })

这会 wrap console.log / info / warn / error / debug，维护一个 50 条的环形缓冲区。包装层保留原行为（你的日志依旧打到 stdout / 浏览器控制台）。

这是 SDK 唯一做的 monkey-patch，所以它默认关闭、需要显式开启。recordConsole 不传时遵循默认契约 —— 纯被动捕获。

Sourcemap

浏览器端的压缩 bundle，部署时一起上传 .map：

kestrel sourcemaps upload ./dist --release "$(git rev-parse --short HEAD)"

服务端在读取时解析；web UI 和 MCP get_error 都会同时返回原始（minified）堆栈和解析后的堆栈。

包体积

bun run build && du -h dist/index.js 应当 < 5 KB。CI 在体积超标时会让 SDK 构建失败。