@lovrabet/sdk 1.1.17 → 1.1.19-beta.0

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,7 +499,7 @@ const client = createClient({ token });
 
 ## 📝 What's New
 
-### v1.1.17 (2025-10-18)
+### 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";