SDK 快速开始
官方 TypeScript SDK 封装了 OAuth Token 管理和事件上报，让你专注于业务逻辑。
npm install @profy-ai/sdk
初始化
import { ProfyApp } from "@profy-ai/sdk";
const profy = new ProfyApp({
clientId: process.env.PROFY_APP_ID!,
clientSecret: process.env.PROFY_APP_SECRET!,
baseUrl: "https://app.profy.cn", // 可选，默认 profy.cn
onTokenRefresh: (newToken) => { // 可选，Token 轮换时触发
saveToDatabase(newToken); // 持久化新 Token
},
});
OAuth 授权码交换
用户授权后，回调地址会收到 code 参数。在后端将其换成 Token：
const token = await profy.exchangeCode(code, redirectUri);
// → { accessToken, refreshToken, expiresAt }
| 字段 | 类型 | 说明 |
|---|
accessToken | string | JWT 格式，1 小时有效 |
refreshToken | string | 90 天有效，每次使用后轮换 |
expiresAt | number | 过期时间戳（毫秒） |
exchangeCode 必须在后端调用。App Secret 不能暴露在前端。
上报计费事件
const result = await profy.reportEvent("generate_report", {
token,
idempotencyKey: "order-12345", // 可选，防重复扣费
metadata: { plan: "pro" }, // 可选，业务追踪
});
错误处理
import {
AuthExpired,
InsufficientBalance,
InvalidEvent,
ProfyApiError,
} from "@profy-ai/sdk";
try {
await profy.reportEvent("action", { token });
} catch (err) {
if (err instanceof AuthExpired) {
// Token 过期且无法刷新 → 引导用户重新授权
} else if (err instanceof InsufficientBalance) {
// 用户积分不足 → 提示充值
} else if (err instanceof InvalidEvent) {
// 事件名未配置 → 检查 Studio 计费事件设置
} else if (err instanceof ProfyApiError) {
// 其他 API 错误
console.error(err.statusCode, err.body);
}
}
错误类速查
| 错误类 | HTTP 状态码 | 触发条件 | 处理方式 |
|---|
AuthExpired | 401 | Token 过期且刷新失败 | 重新授权 |
InsufficientBalance | 402 | 用户积分不足 | 提示充值 |
InvalidEvent | 400 | 事件名未注册 | 检查 Meter 配置 |
ProfyApiError | * | 通用 API 错误 | 按 statusCode 处理 |
完整示例
→ profy-app-template（Vite + Hono 全栈脚手架）
API 参考
OAuth 端点与 Events API 详细文档
