@lovrabet/sdk 1.1.18 → 1.1.19

package/README.md

@@ -34,7 +34,7 @@ const client = createClient({
   models: {
     users: {
       tableName: "users",
-      datasetId: "your-dataset-id",
+      datasetCode: "your-dataset-code",
     },
   },
 });
@@ -82,7 +82,7 @@ const client = createClient({
   models: {
     users: {
       tableName: "users",
-      datasetId: "your-dataset-id",
+      datasetCode: "your-dataset-code",
     },
   },
 });
@@ -102,7 +102,7 @@ const client = createClient({
   models: {
     users: {
       tableName: "users",
-      datasetId: "your-dataset-id",
+      datasetCode: "your-dataset-code",
     },
   },
 });
@@ -177,8 +177,8 @@ import { registerModels, createClient } from "@lovrabet/sdk";
 registerModels({
   appCode: "your-app-code",
   models: {
-    users: { tableName: "users", datasetId: "ds-001" },
-    posts: { tableName: "posts", datasetId: "ds-002" },
+    users: { tableName: "users", datasetCode: "ds-001" },
+    posts: { tableName: "posts", datasetCode: "ds-002" },
   },
 });
 
@@ -238,6 +238,83 @@ client.setToken(newToken, newTimestamp);
 client.switchEnv("daily");
 ```
 
+### 执行自定义 SQL
+
+SDK 提供了 `client.api` 命名空间，用于执行自定义 SQL 查询和其他通用 API 调用。
+
+#### 基础查询
+
+```typescript
+// 执行 SQL 查询，返回结果数组
+const results = await client.api.executeSql('fc8e7777-06e3847d');
+console.log(results);
+// [
+//   { creation_date: '2025-08-13', page_count: 2 },
+//   { creation_date: '2025-08-19', page_count: 3 },
+//   ...
+// ]
+```
+
+#### 参数化查询
+
+```typescript
+// 传递参数到 SQL
+const results = await client.api.executeSql('fc8e7777-xxxxx', {
+  userId: '123',
+  startDate: '2025-01-01'
+});
+```
+
+#### 带类型提示
+
+```typescript
+// 定义结果类型
+interface PageStat {
+  creation_date: string;
+  page_count: number;
+}
+
+// 使用泛型获得类型安全
+const stats = await client.api.executeSql<PageStat>('fc8e7777-06e3847d');
+stats.forEach(stat => {
+  console.log(stat.creation_date);  // TypeScript 自动补全
+  console.log(stat.page_count);
+});
+```
+
+#### 处理查询结果
+
+```typescript
+// 获取第一条结果
+const results = await client.api.executeSql<PageStat>('fc8e7777-xxxxx');
+const firstResult = results[0];
+
+if (firstResult) {
+  console.log(`日期: ${firstResult.creation_date}, 数量: ${firstResult.page_count}`);
+} else {
+  console.log('无结果');
+}
+
+// 过滤结果
+const activeItems = results.filter(item => item.status === 'active');
+
+// 查找特定结果
+const targetItem = results.find(item => item.id === '123');
+```
+
+#### 错误处理
+
+```typescript
+try {
+  const results = await client.api.executeSql('fc8e7777-xxxxx');
+} catch (error) {
+  if (error instanceof LovrabetError) {
+    console.error('SQL执行失败:', error.message);
+    console.error('错误代码:', error.code);
+  }
+}
+```
+
 ## 📖 API 文档
 
 ### 主要导出
@@ -267,6 +344,9 @@ import {
   // 错误处理
   LovrabetError,
 
+  // API 命名空间
+  ApiNamespace,
+
   // TypeScript 类型
   type ClientConfig,
   type TokenResult,
@@ -275,6 +355,8 @@ import {
   type SortList,
   type SelectOption,
   type SelectOptionsParams,
+  type SqlExecuteRequest,
+  type SqlExecuteResult,
 
   // 枚举
   SortOrder,
@@ -298,12 +380,13 @@ interface ClientConfig {
 ### CRUD 操作
 
 ```typescript
-// 查询列表
+// 查询列表（返回 paging/tableData/tableColumns）
 const response = await client.models.users.getList({
   currentPage: 1,
   pageSize: 20,
-  // 其他查询参数
 });
+console.log(response.paging.totalCount);
+console.log(response.tableColumns);
 
 // 查询列表（带排序）
 import { SortOrder } from "@lovrabet/sdk";
@@ -416,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):**

package/dist/index.d.ts

@@ -4,8 +4,10 @@ export { getApiEndpoint, getAvailableEnvironments, } from "./src/config/endpoint
 export { CONFIG_NAMES, ENVIRONMENTS, DEFAULTS, HTTP_STATUS, ERROR_MESSAGES, API_PATHS, } from "./src/config/constants";
 export { LovrabetError } from "./src/utils/errors";
 export { AbstractBaseModel, OpenApiModel, WebApiModel, ModelFactory, } from "./src/models/index";
+export { ApiNamespace } from "./src/api/index";
 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, SortList, SelectOption, SelectOptionsParams, } from "./src/types/index";
+export type { SqlExecuteRequest, SqlExecuteResult, } from "./src/api/types";
 export { SortOrder, } from "./src/types/index";