@lovrabet/sdk 1.1.12 → 1.1.13

package/README.md

@@ -1,339 +1,418 @@
-# Lovrabet Node SDK
+# Lovrabet SDK
 
-一个现代化的 Lovrabet 数据平台 SDK，支持 TypeScript，提供优雅的 API 设计。
+强大且灵活的 Lovrabet 数据平台 SDK，支持多种认证模式，适用于 Node.js 和浏览器环境。
 
-## 特性
+## ✨ 特性
 
-- 🚀 **现代化 API** - 基于 `createClient()` 的简洁设计
-- 🔒 **多种鉴权** - 支持用户 token、OpenAPI 等多种认证方式
-- 🌍 **环境切换** - 支持生产环境和日常环境
-- 📦 **TypeScript** - 完整的类型支持
-- 🔧 **配置文件** - 支持配置文件管理
+- 🔐 **三种认证模式** - OpenAPI（服务端）、OpenAPI（浏览器）、WebAPI（Cookie）
+- 🎯 **环境自适应** - 根据运行环境自动选择最佳认证方式
+- 🔑 **Token 生成** - 内置 Token 生成器，支持批量生成
+- 📦 **TypeScript** - 完整的类型定义和智能提示
+- 🚀 **简洁 API** - 基于 `createClient()` 的现代化设计
+- 🌍 **多环境支持** - 轻松切换生产、测试环境
 - 🔄 **向后兼容** - 保持对旧版 API 的兼容
-- ⚡ **动态实体** - 通过 Proxy 实现动态实体访问
 
-## 快速开始
-
-### 安装
+## 📦 安装
 
 ```bash
 npm install @lovrabet/sdk
+# 或
+bun add @lovrabet/sdk
 ```
 
-### 基础用法
+## 🚀 快速开始
 
-#### 方式 1: 预注册配置（推荐）
+### 服务端使用（Node.js）
 
 ```typescript
-import { registerModels, createClient } from "@lovrabet/sdk";
+import { createClient } from "@lovrabet/sdk";
 
-// 1. 注册模型配置
-registerModels({
+// 使用 accessKey 认证（推荐）
+const client = createClient({
   appCode: "your-app-code",
+  accessKey: process.env.LOVRABET_ACCESS_KEY,
   models: {
-    Requirements: {
-      tableName: "requirements",
-      datasetCode: "your-dataset-code",
-    },
-    Projects: {
-      tableName: "projects",
-      datasetCode: "your-project-dataset-code",
+    users: {
+      tableName: "users",
+      datasetId: "your-dataset-id",
     },
   },
 });
 
-// 2. 创建客户端（无参数！）
-const client = createClient();
+// CRUD 操作
+const users = await client.models.users.getList();
+const user = await client.models.users.getOne("user-id");
+const newUser = await client.models.users.create({ name: "John" });
+```
 
-// 3. 使用模型
-const requirements = await client.models.Requirements.getList();
-const newReq = await client.models.Requirements.create({
-  title: "New Requirement",
-});
+### 浏览器端使用
+
+#### 方式 1：使用预生成 Token（推荐）
+
+**服务端生成 Token:**
+
+```typescript
+// app/api/token/route.ts (Next.js)
+import { generateOpenApiToken } from "@lovrabet/sdk";
+
+export async function GET() {
+  const result = await generateOpenApiToken({
+    appCode: process.env.LOVRABET_APP_CODE!,
+    datasetCode: process.env.DATASET_ID!,
+    accessKey: process.env.LOVRABET_ACCESS_KEY!,
+  });
+
+  return Response.json(result);
+}
 ```
 
-#### 方式 2: 直接传配置
+**浏览器使用 Token:**
 
 ```typescript
 import { createClient } from "@lovrabet/sdk";
 
+// 获取 token
+const { token, timestamp } = await fetch('/api/token').then(r => r.json());
+
 // 创建客户端
 const client = createClient({
   appCode: "your-app-code",
-  env: "online",
-
+  token: token,
+  timestamp: timestamp,
   models: {
-    Requirements: {
-      tableName: "requirements",
-      datasetCode: "your-dataset-code",
+    users: {
+      tableName: "users",
+      datasetId: "your-dataset-id",
     },
   },
 });
 
-// 使用模型
-const requirements = await client.models.Requirements.getList();
-const newReq = await client.models.Requirements.create({
-  title: "New Requirement",
-});
+// 使用
+const users = await client.models.users.getList();
 ```
 
-### 多环境配置
+#### 方式 2：使用 Cookie（已登录用户）
 
 ```typescript
-import {
-  registerModels,
-  createClient,
-  CONFIG_NAMES,
-  ENVIRONMENTS,
-} from "@lovrabet/sdk";
+import { createClient } from "@lovrabet/sdk";
 
-// 注册生产环境配置
-registerModels(
-  {
-    appCode: "app-prod-123",
-    env: ENVIRONMENTS.ONLINE,
-    models: {
-      Requirements: {
-        tableName: "requirements",
-        datasetCode: "prod-dataset-code",
-      },
-    },
-  },
-  CONFIG_NAMES.PROD
-);
-
-// 注册开发环境配置
-registerModels(
-  {
-    appCode: "app-dev-123",
-    env: ENVIRONMENTS.DAILY,
-    models: {
-      Requirements: {
-        tableName: "requirements",
-        datasetCode: "dev-dataset-code",
-      },
+// 不提供认证信息，自动使用 Cookie
+const client = createClient({
+  appCode: "your-app-code",
+  models: {
+    users: {
+      tableName: "users",
+      datasetId: "your-dataset-id",
     },
   },
-  CONFIG_NAMES.DEV
-);
+});
 
-// 创建不同环境的客户端
-const prodClient = createClient(CONFIG_NAMES.PROD);
-const devClient = createClient(CONFIG_NAMES.DEV);
+// 请求会自动带上 Cookie
+const users = await client.models.users.getList();
 ```
 
-### 配置文件支持
+## 🔑 Token 管理
 
-创建 `lovrabet.config.js`：
+### 生成单个 Token
 
-```javascript
-const { registerModels } = require("@lovrabet/sdk");
+```typescript
+import { generateOpenApiToken } from "@lovrabet/sdk";
 
-const config = {
+const result = await generateOpenApiToken({
+  appCode: "your-app-code",
+  datasetCode: "your-dataset-id",
+  accessKey: process.env.LOVRABET_ACCESS_KEY!,
+});
+
+console.log(result.token);      // 生成的 token
+console.log(result.timestamp);  // 时间戳
+console.log(result.expiresAt); // 过期时间
+```
+
+### 批量生成 Token
+
+```typescript
+import { TokenGenerator } from "@lovrabet/sdk";
+
+const generator = new TokenGenerator(process.env.LOVRABET_ACCESS_KEY!);
+
+const tokens = await generator.generateBatch({
+  appCode: "your-app-code",
+  datasets: [
+    { name: "users", code: "dataset-001" },
+    { name: "posts", code: "dataset-002" },
+  ],
+});
+
+// 使用生成的 tokens
+console.log(tokens.users.token);
+console.log(tokens.posts.token);
+```
+
+### Token 有效期管理
+
+```typescript
+import { isTokenExpiring, getTokenRemainingTime } from "@lovrabet/sdk";
+
+// 检查 token 是否即将过期
+if (isTokenExpiring(timestamp)) {
+  // 刷新 token
+  const newToken = await fetchNewToken();
+  client.setToken(newToken.token, newToken.timestamp);
+}
+
+// 获取剩余时间
+const remaining = getTokenRemainingTime(timestamp);
+console.log(`Token 剩余 ${remaining / 1000} 秒`);
+```
+
+## 🔧 高级用法
+
+### 预注册配置
+
+```typescript
+import { registerModels, createClient } from "@lovrabet/sdk";
+
+// 注册配置
+registerModels({
   appCode: "your-app-code",
-  env: "online",
   models: {
-    Requirements: {
-      tableName: "requirements",
-      datasetCode: "your-dataset-code",
-    },
+    users: { tableName: "users", datasetId: "ds-001" },
+    posts: { tableName: "posts", datasetId: "ds-002" },
   },
-};
+});
 
-// 注册配置
-registerModels(config);
+// 创建客户端（无参数）
+const client = createClient();
 
-module.exports = config;
+// 使用
+const users = await client.models.users.getList();
 ```
 
-使用配置文件：
+### 多环境管理
 
 ```typescript
-// 引入配置文件（自动注册）
-require("./lovrabet.config.js");
+import { registerModels, createClient } from "@lovrabet/sdk";
 
+// 注册不同环境的配置
+registerModels({
+  appCode: "prod-app",
+  models: { /* ... */ },
+}, "prod");
+
+registerModels({
+  appCode: "dev-app",
+  models: { /* ... */ },
+}, "dev");
+
+// 创建不同环境的客户端
+const prodClient = createClient("prod");
+const devClient = createClient("dev");
+```
+
+### 动态更新 Token
+
+```typescript
 // 创建客户端
-const client = createClient();
+const client = createClient({
+  appCode: "your-app-code",
+  models: { /* ... */ },
+});
+
+// 后续更新 token
+client.setToken(newToken, newTimestamp);
+
+// 切换环境
+client.switchEnv("daily");
 ```
 
-## API 文档
+## 📖 API 文档
 
-### 创建客户端
+### 主要导出
 
 ```typescript
-import { createClient, ClientConfig } from '@lovrabet/sdk';
-
-const config: ClientConfig = {
-  // 必需
-  appCode: string;
-
-  // 可选
-  serverUrl?: string;           // 自定义服务器地址
-  env?: 'online' | 'daily';     // 环境，默认 'online'
-
-  // 鉴权方式（选择其一或组合使用）
-  token?: string;               // 用户 token
-  accessKey?: string;           // OpenAPI access key
-  secretKey?: string;           // OpenAPI secret key
-  requiresAuth?: boolean;       // 是否必须鉴权
-
-  // 模型配置
-  models?: Record<string, {
-    tableName: string;
-    datasetCode: string;
-  }>;
-
-  // 其他选项
-  options?: {
-    timeout?: number;           // 请求超时时间
-    retryCount?: number;        // 重试次数
-    onError?: (error: any) => void;        // 错误回调
-    onRedirectToLogin?: () => void;        // 登录重定向回调
-  };
-};
+import {
+  // 客户端
+  createClient,
+
+  // Token 生成
+  generateOpenApiToken,
+  TokenGenerator,
+  isTokenExpiring,
+  getTokenRemainingTime,
+
+  // 配置管理
+  registerModels,
+  getRegisteredModels,
+  getRegisteredConfigNames,
+  unregisterModels,
+  clearAllRegistrations,
+
+  // 环境配置
+  getApiEndpoint,
+  getAvailableEnvironments,
+
+  // 错误处理
+  LovrabetError,
+
+  // TypeScript 类型
+  type ClientConfig,
+  type TokenResult,
+  type ListResponse,
+  type ListParams,
+} from "@lovrabet/sdk";
 ```
 
-### 模型操作
+### 客户端配置
+
+```typescript
+interface ClientConfig {
+  appCode?: string;           // 应用代码
+  accessKey?: string;         // OpenAPI 密钥（服务端）
+  secretKey?: string;         // 密钥（可选）
+  token?: string;             // 预生成 token（浏览器）
+  timestamp?: number;         // token 时间戳
+  env?: 'online' | 'daily';  // 环境
+  models?: ModelsConfig;      // 模型配置
+}
+```
 
-每个模型支持标准的 CRUD 操作：
+### CRUD 操作
 
 ```typescript
 // 查询列表
-await client.models.ModelName.getList({
-  currentPage?: number;
-  pageSize?: number;
-  [key: string]: any;
+const response = await client.models.users.getList({
+  currentPage: 1,
+  pageSize: 20,
+  // 其他查询参数
 });
 
-// 获取单条
-await client.models.ModelName.getOne(id: string | number);
+// 获取单条记录
+const user = await client.models.users.getOne("user-id");
 
 // 创建
-await client.models.ModelName.create(data: Record<string, any>);
+const newUser = await client.models.users.create({
+  name: "John Doe",
+  email: "john@example.com",
+});
 
 // 更新
-await client.models.ModelName.update(id: string | number, data: Record<string, any>);
+const updated = await client.models.users.update("user-id", {
+  name: "Jane Doe",
+});
 
 // 删除
-await client.models.ModelName.delete(id: string | number);
+await client.models.users.delete("user-id");
+```
+
+## 🛡️ 安全最佳实践
 
-// 批量创建
-await client.models.ModelName.bulkCreate(data: Record<string, any>[]);
+### ❌ 错误做法
+
+```typescript
+// 绝不要在客户端代码中硬编码 accessKey
+const client = createClient({
+  accessKey: "sk_live_xxx", // 危险！会暴露密钥
+});
 ```
 
-### 客户端方法
+### ✅ 正确做法
+
+**服务端：**
 
 ```typescript
-// 设置新 token
-client.setToken(token: string);
+// 使用环境变量存储敏感信息
+const client = createClient({
+  accessKey: process.env.LOVRABET_ACCESS_KEY,
+});
+```
 
-// 获取配置
-client.getConfig(): ClientConfig;
+**客户端：**
 
-// 测试连接
-await client.testConnection(): Promise<boolean>;
+```typescript
+// 使用服务端生成的 token
+const { token } = await fetch('/api/token').then(r => r.json());
+const client = createClient({ token });
+```
 
-// 设置环境
-client.setEnvironment(env: 'online' | 'daily');
+## 🎯 选择正确的认证模式
 
-// 获取当前环境
-client.getEnvironment(): 'online' | 'daily';
+| 环境 | 认证方式 | 使用场景 |
+|------|---------|---------|
+| **Node.js 服务端** | `accessKey` | SSR、API 路由、后端服务 |
+| **浏览器（未登录）** | `token` | 公开数据访问、匿名用户 |
+| **浏览器（已登录）** | Cookie | 已认证用户、私有数据 |
 
-// 获取所有可用模型
-client.getAvailableModels(): string[];
+## 📚 文档
 
-// 动态获取模型
-client.getModel(modelName: string): ModelInstance;
-```
+- **[文档中心](./docs/README.md)** - 完整的文档导航
+- **[OpenAPI 完整指南](./docs/openapi-guide.md)** - OpenAPI 实现原理和使用案例 ⭐
+- [使用指南](./docs/usage-guide.md) - 详细的使用文档和示例
+- [API 参考](./docs/api-reference.md) - 完整的 API 文档
+- [架构分析](./docs/architecture-analysis.md) - SDK 内部架构说明
 
-## 错误处理
+## 📝 What's New
 
-```typescript
-import { createClient, LovrabetError } from "@lovrabet/sdk";
-
-try {
-  const data = await client.models.Requirements.getList();
-} catch (error) {
-  if (error instanceof LovrabetError) {
-    console.log("Status:", error.status);
-    console.log("Code:", error.code);
-    console.log("Message:", error.message);
-    console.log("Data:", error.data);
-
-    // 根据错误类型处理
-    if (error.status === 401) {
-      console.log("需要重新登录");
-      // 跳转到登录页
-    } else if (error.status === 403) {
-      console.log("权限不足");
-    }
-  }
-}
+### v1.1.11 (2025-10-09)
 
-// 使用全局错误处理
-const client = createClient({
-  // ... 其他配置
-  options: {
-    onError: (error) => {
-      console.error("Lovrabet SDK Error:", error.message);
-      // 全局错误处理逻辑
-    },
-    onRedirectToLogin: () => {
-      console.log("跳转到登录页");
-      // window.location.href = '/login';
-    },
-  },
-});
-```
+**新增功能 (New Features):**
 
-## 文档
+- ✨ **后端 Token 生成器** - 新增 `generateOpenApiToken()` 函数，支持服务端生成 Token
+  ```typescript
+  import { generateOpenApiToken } from "@lovrabet/sdk";
 
-- [使用指南](./docs/usage-guide.md) - 详细的使用文档和最佳实践
-- [架构设计](./docs/new-sdk-design.md) - SDK 的架构设计说明
-- [迁移指南](./docs/usage-guide.md#迁移指南) - 从旧版本迁移的指南
+  const { token, timestamp } = await generateOpenApiToken({
+    appCode: "your-app",
+    datasetCode: "ds-001",
+    accessKey: process.env.ACCESS_KEY,
+  });
+  ```
 
-## 快速参考
+---
 
-### 常用常量
+### v1.1.8 (2025-09-30)
 
-```typescript
-import {
-  ENVIRONMENTS, // 环境常量
-  CONFIG_NAMES, // 配置名称常量
-  DEFAULTS, // 默认值常量
-} from "@lovrabet/sdk";
+**新增功能 (New Features):**
 
-// 环境常量
-ENVIRONMENTS.ONLINE; // 'online'
-ENVIRONMENTS.DAILY; // 'daily'
+- 🛡️ **浏览器安全警告** - 新增浏览器环境 accessKey 使用安全警告机制
+  - 在浏览器中使用 accessKey 会触发明确的错误提示
+  - 引导开发者使用正确的 Token 认证方式
 
-// 配置名称常量
-CONFIG_NAMES.DEFAULT; // 'default'
-CONFIG_NAMES.PROD; // 'prod'
-CONFIG_NAMES.DEV; // 'dev'
+**改进 (Improvements):**
 
-// 默认值
-DEFAULTS.TIMEOUT; // 10000
-DEFAULTS.RETRY_COUNT; // 3
-```
+- 📚 **文档优化** - 修正浏览器安全警告中的文档链接地址
 
-### 工具函数
+---
 
-```typescript
-import {
-  getRegisteredConfigNames, // 获取所有已注册的配置名称
-  getRegisteredModels, // 获取指定配置的模型信息
-} from "@lovrabet/sdk";
 
-// 查看所有已注册的配置
-const configNames = getRegisteredConfigNames();
-console.log("已注册的配置:", configNames);
+### v1.1.5 (2025-09-27)
 
-// 获取特定配置的详细信息
-const config = getRegisteredModels("default");
-console.log("默认配置:", config);
-```
+**重大变更 (Breaking Changes):**
+
+- 🔴 **统一认证架构** - 重构认证系统，实现 OpenAPI 双模式支持（AccessKey + Token）
+
+**新增功能 (New Features):**
+
+- ✨ **OpenAPI 双模式** - 支持服务端 AccessKey 和浏览器 Token 两种认证方式
+- 🔑 **Token 管理工具** - 新增 Token 生命周期管理相关工具函数
+
+---
+
+
+## 🤝 反馈
+
+如遇到问题或有功能建议，欢迎提交 Issue！
+
+## 📄 许可证
+
+**专有软件（Proprietary）** - 详见 [LICENSE](./LICENSE) 文件
 
-## 支持
+本 SDK 为 Lovrabet 开放平台的专有组件：
+- ✅ **允许使用** - 可以安装并在项目中集成本 SDK
+- ✅ **应用分发** - 可以分发包含本 SDK 的应用程序
+- ✅ **商业使用** - 可用于个人和商业项目
+- ❌ **不得修改** - 不得修改、反编译或逆向工程
+- ❌ **不得单独分发** - 不得单独复制或分发本 SDK
+- ❌ **源代码不公开** - 本 SDK 为闭源软件
 
-如有问题或建议，请提交 Issue。
+如需商业授权或有疑问，请访问 [lovrabet.com](https://www.lovrabet.com)