TypeScript SDK

@joytoken/client-sdk-ts 是 JoyToken 公开开发者 API 的类型化客户端。它面向服务端 JavaScript runtime:Node.js 服务、Next.js route handler、worker 和 Agent runtime。

为什么使用 TypeScript SDK

SDK 在 JoyToken API 上提供一层很薄的类型和工具封装,不改变底层聊天补全契约。

收益作用
类型化请求提供 ChatCompletionRequestChatMessageChatTool 和模型列表类型
认证处理配置 API Key 后自动加 Authorization: Bearer $JOY_TOKEN_API_KEY
流式 helper解析 data: SSE 记录,并返回 JSON 分块
模型列表 helper调用 GET /api/v1/models
API 错误抛出带 status、request ID、响应头和响应体的 JoyTokenAPIError

安装

$pnpm add @joytoken/client-sdk-ts

配置

client.ts
1import { JoyTokenClient } from "@joytoken/client-sdk-ts";
2
3export const joytoken = new JoyTokenClient({
4 apiKey: process.env.JOY_TOKEN_API_KEY,
5});

默认值:

配置默认值
apiKeyprocess.env.JOY_TOKEN_API_KEY
apiBaseUrlprocess.env.JOY_TOKEN_API_BASE_URLhttps://api-dev.joytokens.ai
openAIBaseUrlprocess.env.JOY_TOKEN_OPENAI_BASE_URL${apiBaseUrl}/openai/v1
fetchglobalThis.fetch
timeoutMs不配置则 SDK 不主动设置超时

聊天补全

chat.ts
1const completion = await joytoken.chat.completions.create({
2 model: "auto",
3 tier: "standard",
4 messages: [
5 { role: "system", content: "You are concise." },
6 { role: "user", content: "Explain JoyToken in one sentence." },
7 ],
8});
9
10console.log(completion.choices[0]?.message?.content);

流式响应

stream.ts
1const stream = joytoken.chat.completions.stream({
2 model: "auto",
3 messages: [{ role: "user", content: "Write a short release note." }],
4});
5
6for await (const chunk of stream) {
7 if (chunk.choices?.length) {
8 process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
9 }
10
11 if (chunk.metadata) {
12 console.log("metadata", chunk.metadata);
13 }
14}

JoyToken 会在流式响应结束前追加元数据事件。带 metadata 的分块应作为观测数据记录,不要当成 assistant 文本渲染。

模型列表

models.ts
1const models = await joytoken.models.list();
2
3for (const model of models.data) {
4 console.log(model.id, model.name);
5}

错误处理

errors.ts
1import { JoyTokenAPIError } from "@joytoken/client-sdk-ts";
2
3try {
4 await joytoken.chat.completions.create({
5 model: "auto",
6 messages: [{ role: "user", content: "ping" }],
7 });
8} catch (error) {
9 if (error instanceof JoyTokenAPIError) {
10 console.error(error.status, error.requestId, error.body);
11 throw error;
12 }
13
14 throw error;
15}

Next.js 路由示例

app/api/chat/route.ts
1import { JoyTokenClient } from "@joytoken/client-sdk-ts";
2
3const joytoken = new JoyTokenClient({
4 apiKey: process.env.JOY_TOKEN_API_KEY,
5 defaultHeaders: {
6 "X-Request-ID": "nextjs-chat",
7 },
8});
9
10export async function POST(req: Request) {
11 const { messages } = await req.json();
12
13 const completion = await joytoken.chat.completions.create({
14 model: "auto",
15 messages,
16 });
17
18 return Response.json(completion);
19}

JoyToken API Key 只能放在服务端,不要暴露到浏览器代码里。