@lovrabet/sdk 1.1.15 → 1.1.17

package/README.md

@@ -72,7 +72,7 @@ export async function GET() {
 import { createClient } from "@lovrabet/sdk";
 
 // 获取 token
-const { token, timestamp } = await fetch('/api/token').then(r => r.json());
+const { token, timestamp } = await fetch("/api/token").then((r) => r.json());
 
 // 创建客户端
 const client = createClient({
@@ -124,8 +124,8 @@ const result = await generateOpenApiToken({
   accessKey: process.env.LOVRABET_ACCESS_KEY!,
 });
 
-console.log(result.token);      // 生成的 token
-console.log(result.timestamp);  // 时间戳
+console.log(result.token); // 生成的 token
+console.log(result.timestamp); // 时间戳
 console.log(result.expiresAt); // 过期时间
 ```
 
@@ -195,15 +195,25 @@ const users = await client.models.users.getList();
 import { registerModels, createClient } from "@lovrabet/sdk";
 
 // 注册不同环境的配置
-registerModels({
-  appCode: "prod-app",
-  models: { /* ... */ },
-}, "prod");
-
-registerModels({
-  appCode: "dev-app",
-  models: { /* ... */ },
-}, "dev");
+registerModels(
+  {
+    appCode: "prod-app",
+    models: {
+      /* ... */
+    },
+  },
+  "prod"
+);
+
+registerModels(
+  {
+    appCode: "dev-app",
+    models: {
+      /* ... */
+    },
+  },
+  "dev"
+);
 
 // 创建不同环境的客户端
 const prodClient = createClient("prod");
@@ -216,7 +226,9 @@ const devClient = createClient("dev");
 // 创建客户端
 const client = createClient({
   appCode: "your-app-code",
-  models: { /* ... */ },
+  models: {
+    /* ... */
+  },
 });
 
 // 后续更新 token
@@ -260,6 +272,12 @@ import {
   type TokenResult,
   type ListResponse,
   type ListParams,
+  type SortList,
+  type SelectOption,
+  type SelectOptionsParams,
+
+  // 枚举
+  SortOrder,
 } from "@lovrabet/sdk";
 ```
 
@@ -267,13 +285,13 @@ import {
 
 ```typescript
 interface ClientConfig {
-  appCode?: string;           // 应用代码
-  accessKey?: string;         // OpenAPI 密钥（服务端）
-  secretKey?: string;         // 密钥（可选）
-  token?: string;             // 预生成 token（浏览器）
-  timestamp?: number;         // token 时间戳
-  env?: 'online' | 'daily';  // 环境
-  models?: ModelsConfig;      // 模型配置
+  appCode?: string; // 应用代码
+  accessKey?: string; // OpenAPI 密钥（服务端）
+  secretKey?: string; // 密钥（可选）
+  token?: string; // 预生成 token（浏览器）
+  timestamp?: number; // token 时间戳
+  env?: "online" | "daily"; // 环境
+  models?: ModelsConfig; // 模型配置
 }
 ```
 
@@ -287,6 +305,17 @@ const response = await client.models.users.getList({
   // 其他查询参数
 });
 
+// 查询列表（带排序）
+import { SortOrder } from "@lovrabet/sdk";
+
+const sortedUsers = await client.models.users.getList(
+  { currentPage: 1, pageSize: 20 },
+  [
+    { createTime: SortOrder.DESC }, // 按创建时间降序
+    { name: SortOrder.ASC }, // 再按名称升序
+  ]
+);
+
 // 获取单条记录
 const user = await client.models.users.getOne("user-id");
 
@@ -303,6 +332,40 @@ const updated = await client.models.users.update("user-id", {
 
 // 删除
 await client.models.users.delete("user-id");
+
+// 获取下拉选项（WebAPI 模式）
+const options = await client.models.users.getSelectOptions({
+  code: "user_id", // 用作选项值的字段名
+  label: "user_name", // 用作显示文本的字段名
+});
+// 返回: [{ label: '张三', value: 'user001' }, { label: '李四', value: 'user002' }]
+```
+
+### ⚠️ 操作限制
+
+**OpenAPI 模式暂不支持以下操作：**
+
+- ❌ `delete()` - 删除操作（如需删除，请使用 WebAPI 模式）
+- ❌ `getSelectOptions()` - 获取下拉选项（仅 WebAPI 模式支持）
+
+```typescript
+// OpenAPI 模式调用 delete 会抛出错误
+try {
+  await client.models.users.delete("user-id");
+} catch (error) {
+  // Error: OpenAPI 模式暂不支持 delete 操作。如需删除数据，请使用 WebAPI 模式（Cookie 认证）。
+}
+
+// 如需删除，请使用 WebAPI 模式（Cookie 认证）
+const webApiClient = createClient({
+  appCode: "your-app-code",
+  // 不提供 token/accessKey，自动使用 Cookie 认证
+  models: {
+    /* ... */
+  },
+});
+
+await webApiClient.models.users.delete("user-id"); // ✅ 可以使用
 ```
 
 ## 🛡️ 安全最佳实践
@@ -331,17 +394,17 @@ const client = createClient({
 
 ```typescript
 // 使用服务端生成的 token
-const { token } = await fetch('/api/token').then(r => r.json());
+const { token } = await fetch("/api/token").then((r) => r.json());
 const client = createClient({ token });
 ```
 
 ## 🎯 选择正确的认证模式
 
-| 环境 | 认证方式 | 使用场景 |
-|------|---------|---------|
-| **Node.js 服务端** | `accessKey` | SSR、API 路由、后端服务 |
-| **浏览器（未登录）** | `token` | 公开数据访问、匿名用户 |
-| **浏览器（已登录）** | Cookie | 已认证用户、私有数据 |
+| 环境                 | 认证方式    | 使用场景                |
+| -------------------- | ----------- | ----------------------- |
+| **Node.js 服务端**   | `accessKey` | SSR、API 路由、后端服务 |
+| **浏览器（未登录）** | `token`     | 公开数据访问、匿名用户  |
+| **浏览器（已登录）** | Cookie      | 已认证用户、私有数据    |
 
 ## 📚 文档
 
@@ -353,11 +416,118 @@ const client = createClient({ token });
 
 ## 📝 What's New
 
+### v1.1.17 (2025-10-18)
+
+**新增功能 (New Features):**
+
+- ✨ **下拉选项接口** - 新增 `getSelectOptions` 方法，用于快速获取下拉选项数据
+
+  ```typescript
+  // 获取下拉选项（WebAPI 模式）
+  const options = await client.models.users.getSelectOptions({
+    code: "user_id", // 用作选项值的字段名
+    label: "user_name", // 用作显示文本的字段名
+  });
+
+  // 返回格式：
+  // [
+  //   { label: '张三', value: 'user001' },
+  //   { label: '李四', value: 'user002' },
+  //   { label: '王五', value: 'user003' }
+  // ]
+
+  // 在 React 中使用
+  <Select>
+    {options.map((option) => (
+      <Option key={option.value} value={option.value}>
+        {option.label}
+      </Option>
+    ))}
+  </Select>;
+  ```
+
+  - 返回标准化的 `{ label, value }` 格式，直接适用于前端组件
+  - 自动从数据表字段映射为选项数据
+  - 适用于 Select、Radio、Checkbox 等表单组件
+  - **仅 WebAPI 模式（Cookie 认证）支持**
+
+**操作限制说明 (Restrictions):**
+
+- ⚠️ **明确 OpenAPI 模式限制** - OpenAPI 模式暂不支持以下操作：
+
+  - ❌ `delete()` - 删除操作（如需删除，请使用 WebAPI 模式）
+  - ❌ `getSelectOptions()` - 获取下拉选项（仅 WebAPI 模式支持）
+
+  ```typescript
+  // OpenAPI 模式调用这些方法会抛出明确的错误提示
+  try {
+    await client.models.users.delete("user-id");
+  } catch (error) {
+    // Error: OpenAPI 模式暂不支持 delete 操作。如需删除数据，请使用 WebAPI 模式（Cookie 认证）。
+  }
+  ```
+
+**类型定义 (Type Definitions):**
+
+- 新增 `SelectOption` 接口：
+
+  ```typescript
+  interface SelectOption {
+    label: string; // 显示文本
+    value: string; // 选项值
+  }
+  ```
+
+- 新增 `SelectOptionsParams` 接口：
+  ```typescript
+  interface SelectOptionsParams {
+    code: string; // 用作选项值的字段名
+    label: string; // 用作显示文本的字段名
+  }
+  ```
+
+---
+
+### v1.1.16 (2025-10-15)
+
+**新增功能 (New Features):**
+
+- ✨ **列表排序支持** - `getList` 方法现在支持多字段排序功能
+
+  ```typescript
+  import { SortOrder } from "@lovrabet/sdk";
+
+  // 单字段排序
+  const users = await client.models.users.getList(
+    { currentPage: 1, pageSize: 20 },
+    [{ createTime: SortOrder.DESC }]
+  );
+
+  // 多字段排序
+  const products = await client.models.products.getList(
+    { currentPage: 1, pageSize: 20 },
+    [
+      { priority: SortOrder.DESC }, // 优先级降序
+      { createTime: SortOrder.DESC }, // 创建时间降序
+      { name: SortOrder.ASC }, // 名称升序
+    ]
+  );
+  ```
+
+  - 使用简洁的 key-value 格式：`{ "字段名": SortOrder.ASC/DESC }`
+  - 支持多字段组合排序
+  - 同时支持 OpenAPI 和 WebAPI 两种模式
+  - 向后兼容，sortList 参数可选
+  - 导出 `SortOrder` 枚举和 `SortList` 类型供开发者使用
+
+---
+
 ### v1.1.14 (2025-10-11)
 
 **新增功能 (New Features):**
 
 - ✨ **OpenAPI Create/Update 支持** - OpenAPI 模式现已支持完整的 CRUD 操作
+
   ```typescript
   // 创建记录
   const newUser = await client.models.users.create({
@@ -370,6 +540,7 @@ const client = createClient({ token });
     name: "Jane Doe",
   });
   ```
+
   - 认证信息自动添加到请求头（X-Token、X-Time-Stamp）
   - 请求体只包含业务数据（`appCode`、`datasetCode`、`paramMap`）
   - 与查询接口保持一致的架构设计
@@ -401,6 +572,7 @@ const client = createClient({ token });
 **新增功能 (New Features):**
 
 - ✨ **后端 Token 生成器** - 新增 `generateOpenApiToken()` 函数，支持服务端生成 Token
+
   ```typescript
   import { generateOpenApiToken } from "@lovrabet/sdk";
 
@@ -427,7 +599,6 @@ const client = createClient({ token });
 
 ---
 
-
 ### v1.1.5 (2025-09-27)
 
 **重大变更 (Breaking Changes):**
@@ -441,7 +612,6 @@ const client = createClient({ token });
 
 ---
 
-
 ## 🤝 反馈
 
 如遇到问题或有功能建议，欢迎提交 Issue！
@@ -451,6 +621,7 @@ const client = createClient({ token });
 **专有软件（Proprietary）** - 详见 [LICENSE](./LICENSE) 文件
 
 本 SDK 为 Lovrabet 开放平台的专有组件：
+
 - ✅ **允许使用** - 可以安装并在项目中集成本 SDK
 - ✅ **应用分发** - 可以分发包含本 SDK 的应用程序
 - ✅ **商业使用** - 可用于个人和商业项目
@@ -458,4 +629,4 @@ const client = createClient({ token });
 - ❌ **不得单独分发** - 不得单独复制或分发本 SDK
 - ❌ **源代码不公开** - 本 SDK 为闭源软件
 
-如需商业授权或有疑问，请访问 [lovrabet.com](https://www.lovrabet.com)
+如需商业授权或有疑问，请访问 [lovrabet.com](https://www.lovrabet.com)

package/dist/index.d.ts

@@ -7,4 +7,5 @@ export { AbstractBaseModel, OpenApiModel, WebApiModel, ModelFactory, } from "./s
 export { AuthManager, } from "./src/auth/index";
 export { generateOpenApiToken, TokenGenerator, isTokenExpiring, getTokenRemainingTime, type GenerateTokenParams, type TokenResult } from "./src/auth/index";
 export type { ClientConfig, LovrabetClient, ModelConfig, ModelsConfig, } from "./src/types/index";
-export type { ListParams, ListResponse, Environment, BaseModelMethods, } from "./src/types/index";
+export type { ListParams, ListResponse, Environment, BaseModelMethods, SortList, SelectOption, SelectOptionsParams, } from "./src/types/index";
+export { SortOrder, } from "./src/types/index";