@lovrabet/sdk 1.1.19-beta.0 → 1.1.19

package/README.md

@@ -499,6 +499,97 @@ const client = createClient({ token });
 
 ## 📝 What's New
 
+### v1.1.19 (2025-11-10)
+
+**新增功能 (New Features):**
+
+- ✨ **SQL API 支持** - 新增 `client.api.executeSql()` 方法，支持执行自定义 SQL 查询
+
+  ```typescript
+  // 执行 SQL 查询
+  const data = await client.api.executeSql('fc8e7777-06e3847d');
+
+  // 应用层检查执行结果
+  if (data.execSuccess && data.execResult) {
+    data.execResult.forEach(row => {
+      console.log(row);
+    });
+  }
+  ```
+
+  **核心特性：**
+  - 支持参数化查询，防止 SQL 注入
+  - 完整的 TypeScript 类型支持（泛型）
+  - 返回 `{ execSuccess: boolean, execResult?: T[] }` 结构
+  - 应用层负责检查 `execSuccess` 状态
+
+  **适用场景：**
+  - 复杂数据统计和聚合查询
+  - 跨表关联查询
+  - 自定义报表数据获取
+  - 灵活的数据分析需求
+
+- 🏗️ **API 命名空间架构** - 新增 `client.api` 命名空间，用于管理通用 API 调用
+
+  ```typescript
+  const client = createClient({ /* ... */ });
+
+  // 通过 api 命名空间访问
+  const data = await client.api.executeSql('sqlCode');
+  ```
+
+  - 统一的 API 调用入口
+  - 为未来扩展预留空间（executeFunction、callWebhook 等）
+  - 与 Model API 保持一致的设计风格
+
+**类型定义 (Type Definitions):**
+
+- 新增 `SqlExecuteRequest` 接口：
+
+  ```typescript
+  interface SqlExecuteRequest {
+    sqlCode: string | number;  // SQL 代码
+    params?: Record<string, string | number>;  // SQL 参数
+  }
+  ```
+
+- 新增 `SqlExecuteResult<T>` 接口：
+
+  ```typescript
+  interface SqlExecuteResult<T = Record<string, any>> {
+    execSuccess: boolean;  // SQL 执行是否成功
+    execResult?: T[];      // 查询结果数组
+  }
+  ```
+
+- 导出 `ApiNamespace` 类供高级用户使用
+
+**重要说明 (Important Notes):**
+
+:::warning SDK 返回值设计原则
+
+SDK 的 `executeSql()` 方法返回包含 `execSuccess` 和 `execResult` 的对象，**不直接返回结果数组**。
+
+这是因为：
+1. **分离职责** - SDK 负责 HTTP 通信，应用层负责业务逻辑判断
+2. **错误处理** - `execSuccess: false` 表示 SQL 执行失败（业务错误），HTTP 失败才抛异常
+3. **灵活性** - 应用层可以根据 `execSuccess` 自行决定如何处理
+
+```typescript
+// ✅ 正确使用方式
+const data = await client.api.executeSql('sqlCode');
+if (data.execSuccess && data.execResult) {
+  // 使用 execResult
+}
+
+// ❌ 错误使用方式
+const data = await client.api.executeSql('sqlCode');
+data.execResult.forEach(...);  // 没有检查 execSuccess！
+```
+:::
+
+---
+
 ### v1.1.18 (2025-10-18)
 
 **新增功能 (New Features):**