@openloaf-saas/sdk 0.1.9 → 0.1.11

package/README.md

@@ -0,0 +1,520 @@
+# @openloaf-saas/sdk
+
+统一入口 SDK，包含全部模块能力：
+- **模块**：`auth` / `user` / `feedback` / `ai` / `aiTools` / `auxiliary`
+- **模块**：`auth` / `user` / `feedback` / `ai` / `aiTools` / `auxiliary` / `skills`
+- **tRPC**：`createTrpcClient`（仅 publicRouter）
+- **契约**：`SaaSContract` + `Endpoint` 统一校验输入/输出
+
+---
+
+## 安装
+
+```bash
+bun add @openloaf-saas/sdk
+```
+
+---
+
+## 入口
+
+```ts
+import { SaaSClient, createTrpcClient } from "@openloaf-saas/sdk";
+```
+
+---
+
+## 快速上手
+
+### 初始化客户端
+
+```ts
+import { SaaSClient } from "@openloaf-saas/sdk";
+
+let accessToken = "";
+let refreshToken = "";
+
+const client = new SaaSClient({
+	baseUrl: "https://saas.example.com",
+	getAccessToken: () => accessToken,
+});
+```
+
+### Auth：换码 + 刷新 + 退出
+
+```ts
+const exchanged = await client.auth.exchange("<login-code>");
+accessToken = exchanged.accessToken;
+refreshToken = exchanged.refreshToken;
+
+const refreshed = await client.auth.refresh(refreshToken);
+if ("message" in refreshed) {
+	throw new Error(refreshed.message);
+}
+accessToken = refreshed.accessToken;
+refreshToken = refreshed.refreshToken;
+
+await client.auth.logout(refreshToken);
+```
+
+### User：获取当前用户
+
+```ts
+const me = await client.user.self();
+console.log(me.user.id, me.user.membershipLevel, me.user.creditsBalance);
+```
+
+### Feedback：提交/列表/详情
+
+```ts
+await client.feedback.submit({
+	source: "tenas",
+	type: "performance",
+	content: "页面加载有点慢",
+	context: { page: "/dashboard", device: "macOS" },
+	email: "user@example.com",
+});
+
+const list = await client.feedback.list({
+	page: 1,
+	pageSize: 20,
+	type: "ui",
+	saasStatus: "unread",
+	keyword: "按钮",
+});
+
+const detail = await client.feedback.detail("<feedback-id>");
+console.log(list, detail);
+```
+
+### 上传反馈附件
+
+```ts
+const attachment = await client.feedback.uploadAttachment(file, "screenshot.png");
+console.log(attachment.url, attachment.key);
+```
+
+说明：
+- `feedback.submit` 支持匿名或登录调用（token 可选）
+- `feedback.list`、`feedback.detail`、`feedback.uploadAttachment` 需要登录态（Bearer token）
+- `feedback.uploadAttachment` 使用 multipart/form-data 上传
+
+### Skills：列表 / 详情 / 下载
+
+```ts
+const skills = await client.skills.list({
+	page: 1,
+	pageSize: 12,
+	keyword: "sdk",
+	type: "development",
+});
+
+const detail = await client.skills.detail("<skill-id>");
+const archive = await client.skills.download("<skill-id>");
+
+console.log(skills.items.length, detail.skill.name, archive.fileName);
+```
+
+说明：
+- `skills.list`、`skills.detail`、`skills.download` 需要登录态
+- `skills.download` 返回二进制内容 `ArrayBuffer`
+
+---
+
+## AI 能力（ai）
+
+### 积分计费
+
+所有 AI 接口按积分计费，**不暴露原始 token 用量**，统一返回积分消耗：
+
+| 接口类型 | 积分返回方式 |
+|---------|------------|
+| 图片/视频任务 | 轮询 `task()` 响应中的 `creditsConsumed` 字段 |
+| Chat 非流式 | JSON body `x_credits_consumed` + header `x-credits-consumed` |
+| Chat 流式 | 流末尾追加 SSE 事件 `data: {"x_credits_consumed": N}` |
+
+积分不足时返回 HTTP 402 + `{"error":{"message":"...","code":"INSUFFICIENT_CREDITS"}}`。
+
+### 提交图像任务
+
+```ts
+const created = await client.ai.image({
+	modelId: "qwen-image-edit-plus",
+	prompt: "A dancing bear",
+	output: {
+		count: 1,
+		aspectRatio: "1:1",
+		quality: "standard",
+	},
+});
+
+if (!created.success) {
+	throw new Error(created.message);
+}
+```
+
+### 查询任务与获取积分消耗
+
+```ts
+const status = await client.ai.task(created.data.taskId);
+if (status.success && status.data.status === "succeeded") {
+	console.log(status.data.resultUrls);        // 结果地址
+	console.log(status.data.creditsConsumed);    // 本次消耗积分
+}
+
+// 取消任务
+await client.ai.cancelTask(created.data.taskId);
+```
+
+### Chat 聊天补全
+
+Chat 接口兼容 OpenAI 格式（`/api/v1/chat/completions`），SDK 不封装，使用标准 AI SDK 调用。
+
+支持以下可选元数据字段，用于平台侧日志追踪与统计分析；所有字段均为可选，旧请求可继续按原样发送：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `chatSessionId` | `string?` | 会话 ID，用于关联同一对话的多次请求 |
+| `clientId` | `string?` | 客户端实例 ID，区分同一用户的不同设备/实例 |
+| `desktopVersion` | `string?` | Desktop 客户端版本号 |
+| `serverVersion` | `string?` | Server 端版本号 |
+| `webVersion` | `string?` | Web 客户端版本号 |
+
+这些字段仅用于平台内部日志记录，不会透传给上游 AI 供应商。
+
+如需在 TypeScript 中约束请求体，可使用 SDK 导出的 `AiChatCompletionsRequest` / `AiResponsesRequest` 类型。
+
+**非流式 — 从响应 body 读取积分：**
+
+```ts
+import type { AiChatCompletionsRequest } from "@openloaf-saas/sdk";
+
+const payload: AiChatCompletionsRequest = {
+	model: "deepseek-chat",
+	chatSessionId: "chat_sess_123",
+	clientId: "device_abc",
+	desktopVersion: "1.2.0",
+	messages: [{ role: "user", content: "Hello" }],
+};
+
+const resp = await fetch(`${baseUrl}/api/v1/chat/completions`, {
+	method: "POST",
+	headers: {
+		"Content-Type": "application/json",
+		Authorization: `Bearer ${accessToken}`,
+	},
+	body: JSON.stringify(payload),
+});
+const data = await resp.json();
+console.log(data.x_credits_consumed); // number — 本次消耗积分
+// 注意：响应中不包含 usage（token 用量已剥离）
+```
+
+**流式 — 从 SSE 事件读取积分：**
+
+```ts
+const resp = await fetch(`${baseUrl}/api/v1/chat/completions`, {
+	method: "POST",
+	headers: {
+		"Content-Type": "application/json",
+		Authorization: `Bearer ${accessToken}`,
+	},
+	body: JSON.stringify({
+		model: "deepseek-chat",
+		chatSessionId: "chat_sess_123",
+		messages: [{ role: "user", content: "Hello" }],
+		stream: true,
+	}),
+});
+
+let creditsConsumed: number | null = null;
+const reader = resp.body!.getReader();
+const decoder = new TextDecoder();
+let buffer = "";
+
+while (true) {
+	const { done, value } = await reader.read();
+	if (done) break;
+	buffer += decoder.decode(value, { stream: true });
+	const lines = buffer.split("\n");
+	buffer = lines.pop()!;
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("data:")) continue;
+		const payload = trimmed.slice(5).trim();
+		if (payload === "[DONE]") continue;
+		try {
+			const parsed = JSON.parse(payload);
+			// 流末尾的积分消耗事件
+			if (parsed.x_credits_consumed != null) {
+				creditsConsumed = parsed.x_credits_consumed;
+			}
+		} catch {}
+	}
+}
+console.log(creditsConsumed); // number — 本次消耗积分
+```
+
+### 模型与 Provider 模板
+
+```ts
+const imageModels = await client.ai.imageModels();
+const videoModels = await client.ai.videoModels();
+const chatModels = await client.ai.chatModels();
+const modelTimestamps = await client.ai.modelsUpdatedAt();
+
+// 公开接口：不需要鉴权
+const providers = await client.ai.providerTemplates();
+console.log(imageModels, videoModels, chatModels, modelTimestamps, providers);
+```
+
+### 上传文件（AI 对话附件）
+
+```ts
+const uploaded = await client.ai.uploadFile(file, "image.png");
+console.log(uploaded.url);
+```
+
+说明：
+- SDK 方法名为 `video`，对应服务端路径为 `/api/ai/video`
+- `imageModels` / `videoModels` / `chatModels` / `modelsUpdatedAt` 对应公开路径 `/api/public/ai/*`
+- `ai.uploadFile` 使用 multipart/form-data 上传，需要登录态
+
+### 模型缓存推荐用法
+
+```ts
+const timestamps = await client.ai.modelsUpdatedAt();
+if (!timestamps.success) {
+	throw new Error(timestamps.message);
+}
+
+const latestUpdatedAt = timestamps.data.latestUpdatedAt;
+const cachedLatest = localStorage.getItem("ai_models_latest_updated_at");
+
+if (cachedLatest !== latestUpdatedAt) {
+	const [imageModels, videoModels, chatModels] = await Promise.all([
+		client.ai.imageModels(),
+		client.ai.videoModels(),
+		client.ai.chatModels(),
+	]);
+	localStorage.setItem("ai_models_latest_updated_at", latestUpdatedAt);
+	localStorage.setItem("ai_models_image_cache", JSON.stringify(imageModels));
+	localStorage.setItem("ai_models_video_cache", JSON.stringify(videoModels));
+	localStorage.setItem("ai_models_chat_cache", JSON.stringify(chatModels));
+}
+```
+
+---
+
+## AI 辅助工具（aiTools）
+
+来自 `ai-tools` 模块的 3 个非流式接口：
+- `analyzeSkills`：技能分析（翻译、分类、图标）
+- `recommendActions`：行为推荐
+- `summarize`：文本总结
+
+服务端行为说明（与 `.agents/skills/ai-auxiliary-tools.md` 对齐）：
+- 不扣积分，仅记录日志
+- 按用户内存限流，每日 100 次
+- 复用 `ai.default_auxiliary_model` 配置进行路由
+
+### analyzeSkills
+
+```ts
+const analyzed = await client.aiTools.analyzeSkills({
+	skills: [
+		{ name: "Prompt Engineering", description: "构建高质量提示词" },
+		{ name: "TypeScript" },
+	],
+});
+
+if (!analyzed.success) {
+	throw new Error(analyzed.message);
+}
+console.log(analyzed.data.skills);
+```
+
+### recommendActions
+
+```ts
+const recommended = await client.aiTools.recommendActions({
+	text: "用户反馈移动端上传按钮不明显，转化率下降。",
+	scene: "product-optimization",
+});
+
+if (!recommended.success) {
+	throw new Error(recommended.message);
+}
+console.log(recommended.data.actions);
+```
+
+### summarize
+
+```ts
+const summarized = await client.aiTools.summarize({
+	text: "这里放长文本内容...",
+});
+
+if (!summarized.success) {
+	throw new Error(summarized.message);
+}
+console.log(summarized.data.summary);
+```
+
+说明：
+- `aiTools` 接口需要登录态（Bearer token）
+
+---
+
+## 辅助推理（auxiliary）
+
+### 通用推理
+
+```ts
+const result = await client.auxiliary.infer({
+	capabilityKey: "translate",
+	input: { text: "Hello world", targetLang: "zh" },
+});
+console.log(result);
+```
+
+### 查询日配额
+
+```ts
+const quota = await client.auxiliary.getQuota();
+console.log(quota);
+```
+
+说明：
+- `auxiliary` 接口需要登录态（Bearer token）
+- 不扣积分，仅记录日志，按用户每日限流
+
+---
+
+## Public tRPC（仅 publicRouter）
+
+```ts
+import { createTrpcClient } from "@openloaf-saas/sdk";
+
+const trpc = createTrpcClient({
+	baseUrl: "https://saas.example.com",
+	getAccessToken: () => localStorage.getItem("saas_access_token") ?? "",
+});
+
+const health = await trpc.healthCheck.query();
+await trpc.feedback.submit.mutate({
+	source: "tenas",
+	type: "bug",
+	content: "保存按钮偶尔无响应",
+	context: { page: "/settings" },
+});
+
+console.log(health);
+```
+
+说明：
+- SDK 只暴露 publicRouter；内部 tRPC 不对外暴露
+
+---
+
+## 错误处理
+
+```ts
+import {
+	SaaSHttpError,
+	SaaSNetworkError,
+	SaaSSchemaError,
+} from "@openloaf-saas/sdk";
+
+try {
+	await client.user.self();
+} catch (error) {
+	if (error instanceof SaaSHttpError) {
+		console.error(error.status, error.statusText, error.payload);
+	} else if (error instanceof SaaSSchemaError) {
+		console.error(error.issues);
+	} else if (error instanceof SaaSNetworkError) {
+		console.error(error.cause);
+	}
+}
+```
+
+---
+
+## 自定义 fetch 与请求头
+
+```ts
+import fetch from "node-fetch";
+import { SaaSClient } from "@openloaf-saas/sdk";
+
+const client = new SaaSClient({
+	baseUrl: "https://saas.example.com",
+	fetcher: fetch,
+	headers: {
+		"x-sdk-app": "tenas-web",
+	},
+});
+```
+
+---
+
+## 端点契约
+
+```ts
+import { contract } from "@openloaf-saas/sdk";
+
+contract.ai.image.method; // "POST"
+contract.ai.image.path; // "/api/ai/image"
+
+contract.aiTools.summarize.method; // "POST"
+contract.aiTools.summarize.path; // "/api/ai/tools/summarize"
+```
+
+---
+
+## 当前支持的接口
+
+### REST — 认证
+- `POST /api/auth/exchange` — 登录码换取令牌
+- `POST /api/auth/refresh` — 刷新令牌
+- `POST /api/auth/logout` — 退出登录
+
+### REST — 用户
+- `GET /api/user/self` — 获取当前用户信息（含积分余额）
+
+### REST — 反馈
+- `POST /api/public/feedback` — 提交反馈（可匿名）
+- `POST /api/feedback/list` — 反馈列表
+- `GET /api/feedback/{feedbackId}` — 反馈详情
+- `POST /api/feedback/upload` — 上传反馈附件 (multipart/form-data)
+
+### REST — AI 媒体生成（返回 `creditsConsumed`）
+- `POST /api/ai/image` — 提交图片生成任务
+- `POST /api/ai/video` — 提交视频生成任务
+- `GET /api/ai/task/{taskId}` — 查询任务状态（成功时含 `creditsConsumed`）
+- `POST /api/ai/task/{taskId}/cancel` — 取消任务
+- `POST /api/ai/file/upload` — 上传 AI 对话附件 (multipart/form-data)
+
+### REST — AI Chat（OpenAI 兼容，返回 `x_credits_consumed`）
+- `POST /api/v1/chat/completions` — 聊天补全（流式/非流式）
+- `POST /api/v1/responses` — 统一响应（流式/非流式）
+
+### REST — AI 模型（公开，无需认证）
+- `GET /api/public/ai/image/models` — 图片模型列表
+- `GET /api/public/ai/video/models` — 视频模型列表
+- `GET /api/public/ai/chat/models` — 聊天模型列表
+- `GET /api/public/ai/models/updated-at` — 模型更新时间
+- `GET /api/public/ai/providers` — 供应商模板
+
+### REST — AI 辅助工具（不扣积分）
+- `POST /api/ai/tools/analyze-skills` — 技能分析
+- `POST /api/ai/tools/recommend-actions` — 行为推荐
+- `POST /api/ai/tools/summarize` — 文本总结
+
+### REST — 辅助推理（不扣积分）
+- `POST /api/auxiliary/infer` — 通用推理
+- `POST /api/auxiliary/quota` — 查询日配额
+
+### Public tRPC
+- `healthCheck`（publicRouter）
+- `feedback.submit`（publicRouter）