@lovrabet/sdk 1.2.8 → 1.3.0-beta.1

package/dist/src/api/bff-client.d.ts

@@ -0,0 +1,65 @@
+import type { HttpClient } from "../http/http-client";
+/**
+ * BFF 客户端请求参数
+ */
+export interface BffExecuteRequest {
+    /** 脚本名称（endpoint 函数名） */
+    scriptName: string;
+    /** 请求体参数（可选） */
+    params?: Record<string, any>;
+    /** Fetch 请求选项（可选） */
+    options?: RequestInit;
+}
+/**
+ * BFF 客户端 - 调用 Backend For Frontend 端点
+ *
+ * 与其他 SDK 接口保持一致的响应处理逻辑：
+ * - 成功：返回 data（业务数据）
+ * - 失败：抛出 LovrabetError 异常（由 processResponse 处理）
+ *
+ * @example
+ * ```typescript
+ * // 无参数调用
+ * const templates = await client.bff.execute({
+ *   scriptName: 'getBundleTemplates'
+ * });
+ * templates.forEach(template => console.log(template.name));
+ *
+ * // 带参数调用
+ * const price = await client.bff.execute({
+ *   scriptName: 'calculatePrice',
+ *   params: { productId: '123', quantity: 10 }
+ * });
+ * console.log('Price:', price);
+ *
+ * // 带 Fetch 选项
+ * const result = await client.bff.execute({
+ *   scriptName: 'getData',
+ *   params: { id: '123' },
+ *   options: { headers: { 'X-Custom-Header': 'value' } }
+ * });
+ *
+ * // 带类型提示
+ * interface BundleTemplate {
+ *   id: string;
+ *   name: string;
+ *   items: string[];
+ * }
+ * const templates = await client.bff.execute<BundleTemplate>({
+ *   scriptName: 'getBundleTemplates'
+ * });
+ * ```
+ */
+export declare class BffClient {
+    private httpClient;
+    private appCode;
+    constructor(httpClient: HttpClient, appCode: string);
+    /**
+     * 调用 Backend For Frontend (BFF) 端点
+     *
+     * @param request 请求参数
+     * @returns BFF 函数返回的业务数据
+     * @throws {LovrabetError} 当 HTTP 请求失败时抛出异常
+     */
+    execute<T = any>(request: BffExecuteRequest): Promise<T>;
+}

package/dist/src/api/get-user-list.d.ts

@@ -1,10 +1,4 @@
 import type { HttpClient } from "../http";
+import type { User } from "./types";
 export declare function getUserList(httpClient: HttpClient): Promise<User[]>;
-export type User = {
-    code: string;
-    userName: string;
-    nickName?: string | null;
-    mobile: string;
-    email?: string | null;
-    avatar?: string | null;
-};
+export type { User };

package/dist/src/api/index.d.ts

@@ -1,54 +1,97 @@
 import type { HttpClient } from "../http/http-client";
-import type { SqlExecuteResult } from "./types";
+import { SqlClient } from "./sql-client";
+import { BffClient } from "./bff-client";
+import { UserClient } from "./user-client";
 /**
- * API 命名空间 - 管理通用 API 调用（SQL、Function 等）
+ * API 命名空间 - 别名入口
  *
- * 设计原则：
- * 1. 依赖注入 - 通过构造函数注入 HttpClient
- * 2. 类型安全 - 支持泛型，提供 TypeScript 类型推断
- * 3. 统一错误处理 - 成功返回数据，失败抛出 LovrabetError
- * 4. 风格一致 - 与 Model 的 getList/getOne 保持一致
+ * 推荐使用客户端方式：
+ * - SQL: `client.sql.execute()`
+ * - BFF: `client.bff.execute()`
+ * - User: `client.user.getList()`
+ *
+ * 此命名空间提供向后兼容的别名：
+ * - `client.api.sql()` → `client.sql.execute()`
+ * - `client.api.bff()` → `client.bff.execute()`
+ * - `client.api.getUserList()` → `client.user.getList()`
  */
 export declare class ApiNamespace {
     private httpClient;
-    constructor(httpClient: HttpClient);
+    private appCode;
+    constructor(httpClient: HttpClient, appCode: string);
+    /**
+     * SQL 客户端实例
+     */
+    private _sql?;
     /**
-     * 执行自定义 SQL 查询
+     * SQL 查询别名 - 推荐使用 `client.sql.execute()`
      *
-     * @param sqlCode SQL代码（字符串格式 "appCode-sqlId" 或数字ID）
-     * @param params SQL参数对象（可选）
-     * @returns SQL执行结果（包含 execSuccess 和 execResult）
+     * @example
+     * ```typescript
+     * // 推荐用法（对象参数）
+     * const data = await client.sql.execute({
+     *   sqlCode: 'fc8e7777-06e3847d',
+     *   params: { userId: '123' }
+     * });
+     *
+     * // 别名用法（兼容）
+     * const data = await client.api.sql({
+     *   sqlCode: 'fc8e7777-06e3847d',
+     *   params: { userId: '123' }
+     * });
+     * ```
+     */
+    get sql(): SqlClient["execute"];
+    /**
+     * SQL 查询别名（旧名称）- 向后兼容
+     *
+     * @deprecated 使用 `client.sql.execute()` 或 `client.api.sql()`
+     */
+    get executeSql(): SqlClient["execute"];
+    /**
+     * BFF 客户端实例
+     */
+    private _bff?;
+    /**
+     * BFF 查询别名 - 推荐使用 `client.bff.execute()`
      *
      * @example
      * ```typescript
-     * // 无参数查询
-     * const data = await client.api.executeSql('fc8e7777-06e3847d');
-     * if (data.execSuccess) {
-     *   const results = data.execResult;
-     *   results.forEach(item => console.log(item));
-     * }
-     *
-     * // 参数化查询
-     * const data = await client.api.executeSql('fc8e7777-xxxxx', {
-     *   userId: '123',
-     *   startDate: '2025-01-01'
+     * // 推荐用法（对象参数）
+     * const result = await client.bff.execute({
+     *   scriptName: 'getBundleTemplates'
+     * });
+     *
+     * // 别名用法（兼容）
+     * const result = await client.api.bff({
+     *   scriptName: 'getBundleTemplates'
      * });
+     * ```
+     */
+    get bff(): BffClient["execute"];
+    /**
+     * User 客户端实例
+     */
+    private _user?;
+    /**
+     * User 查询别名 - 推荐使用 `client.user.getList()`
+     *
+     * @example
+     * ```typescript
+     * // 推荐用法
+     * const userList = await client.user.getList();
      *
-     * // 带类型提示
-     * interface PageStat {
-     *   creation_date: string;
-     *   page_count: number;
-     * }
-     * const data = await client.api.executeSql<PageStat>('fc8e7777-06e3847d');
-     * if (data.execSuccess && data.execResult) {
-     *   data.execResult.forEach(stat => {
-     *     console.log(stat.creation_date, stat.page_count);
-     *   });
-     * }
+     * // 别名用法（兼容）
+     * const userList = await client.api.getUserList();
      * ```
      */
-    executeSql<T = Record<string, any>>(sqlCode: string | number, params?: Record<string, string | number>): Promise<SqlExecuteResult<T>>;
-    user: {
-        getList: () => Promise<import("./get-user-list").User[]>;
+    get getUserList(): UserClient["getList"];
+    /**
+     * User 客户端别名 - 推荐使用 `client.user.getList()`
+     *
+     * @deprecated 使用 `client.user.getList()`
+     */
+    get user(): {
+        getList: UserClient["getList"];
     };
 }

package/dist/src/api/sql-client.d.ts

@@ -0,0 +1,47 @@
+import type { HttpClient } from "../http/http-client";
+import type { SqlExecuteResult } from "./types";
+/**
+ * SQL 客户端 - 执行自定义 SQL 查询
+ *
+ * @example
+ * ```typescript
+ * // 推荐：对象参数
+ * const data = await client.sql.execute({
+ *   sqlCode: 'fc8e7777-06e3847d',
+ *   params: { userId: '123', startDate: '2025-01-01' }
+ * });
+ *
+ * // 兼容：直接传参
+ * const data = await client.sql.execute('fc8e7777-06e3847d', {
+ *   userId: '123',
+ *   startDate: '2025-01-01'
+ * });
+ *
+ * // 带类型提示
+ * interface PageStat {
+ *   creation_date: string;
+ *   page_count: number;
+ * }
+ * const data = await client.sql.execute<PageStat>({
+ *   sqlCode: 'fc8e7777-06e3847d'
+ * });
+ * ```
+ */
+export declare class SqlClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * 执行自定义 SQL 查询
+     *
+     * 支持两种调用方式：
+     * 1. execute({ sqlCode, params }) - 对象参数（推荐）
+     * 2. execute(sqlCode, params) - 直接传参（兼容）
+     *
+     * @returns SQL执行结果（包含 execSuccess 和 execResult）
+     */
+    execute<T = Record<string, any>>(sqlCode: string | number, params?: Record<string, string | number>): Promise<SqlExecuteResult<T>>;
+    execute<T = Record<string, any>>(options: {
+        sqlCode: string | number;
+        params?: Record<string, string | number>;
+    }): Promise<SqlExecuteResult<T>>;
+}

package/dist/src/api/types.d.ts

@@ -16,3 +16,20 @@ export interface SqlExecuteResult<T = Record<string, any>> {
     /** SQL 查询结果数组 */
     execResult?: T[];
 }
+/**
+ * 用户信息
+ */
+export interface User {
+    /** 用户代码 */
+    code: string;
+    /** 用户名 */
+    userName: string;
+    /** 昵称 */
+    nickName?: string | null;
+    /** 手机号 */
+    mobile: string;
+    /** 邮箱 */
+    email?: string | null;
+    /** 头像 */
+    avatar?: string | null;
+}

package/dist/src/api/user-client.d.ts

@@ -0,0 +1,20 @@
+import type { HttpClient } from "../http/http-client";
+/**
+ * User 客户端 - 用户信息相关 API
+ *
+ * @example
+ * ```typescript
+ * const userList = await client.user.getList();
+ * console.log(userList);
+ * ```
+ */
+export declare class UserClient {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * 获取用户列表
+     *
+     * @returns 用户列表数组
+     */
+    getList: () => Promise<import("./types").User[]>;
+}

package/dist/src/client/client.d.ts

@@ -1,5 +1,8 @@
 import type { ClientConfig, LovrabetClient as ILovrabetClient, Environment, BaseModelMethods } from '../types';
 import { ApiNamespace } from '../api';
+import { SqlClient } from '../api/sql-client';
+import { BffClient } from '../api/bff-client';
+import { UserClient } from '../api/user-client';
 /**
  * Lovrabet SDK 核心客户端类
  *
@@ -25,7 +28,24 @@ export declare class LovrabetClient implements ILovrabetClient {
         [modelName: string]: BaseModelMethods;
     };
     /**
-     * API 命名空间 - 提供通用 API 调用（SQL、Function 等）
+     * SQL 客户端 - 执行自定义 SQL 查询
+     */
+    readonly sql: SqlClient;
+    /**
+     * BFF 客户端 - 调用 Backend For Frontend 端点
+     */
+    readonly bff: BffClient;
+    /**
+     * User 客户端 - 用户信息相关 API
+     */
+    readonly user: UserClient;
+    /**
+     * API 命名空间 - 别名入口（向后兼容）
+     *
+     * 推荐使用命名空间方式：
+     * - `client.sql.execute()` 而非 `client.api.sql()`
+     * - `client.bff.execute()` 而非 `client.api.bff()`
+     * - `client.user.getList()` 而非 `client.api.getUserList()`
      */
     readonly api: ApiNamespace;
     constructor(config: ClientConfig);

package/dist/src/utils/errors.d.ts

@@ -4,11 +4,13 @@ export declare class LovrabetError extends Error {
     readonly code?: string;
     readonly response?: any;
     readonly description?: ErrorDescription;
+    readonly cause?: unknown;
     constructor(message: string, options?: {
         status?: number;
         code?: string;
         response?: any;
         description?: ErrorDescription;
+        cause?: unknown;
     });
     toJSON(): {
         name: string;
@@ -17,6 +19,7 @@ export declare class LovrabetError extends Error {
         code: string;
         response: any;
         description: ErrorDescription;
+        cause: unknown;
     };
 }
 export declare function createErrorHandler(onError?: (error: any) => void): (error: any) => Promise<never>;

package/dist/src/utils/index.d.ts

@@ -1,2 +1,6 @@
 export { LovrabetError, createErrorHandler } from "./errors";
 export { isBrowser, warnBrowserAccessKey } from './browser-detection';
+export { safe } from './safe';
+export type { SafeResult } from './safe';
+export { sqlSafe } from './sql-safe';
+export type { SqlSafeResult } from './sql-safe';

package/dist/src/utils/safe.d.ts

@@ -0,0 +1,54 @@
+import { LovrabetError } from './errors';
+/**
+ * 安全执行结果类型
+ *
+ * @example
+ * ```typescript
+ * const { data, error } = await safe(client.models.customer.filter({ ... }));
+ * if (error) {
+ *   console.error(error.message, error.description);
+ *   return;
+ * }
+ * // 使用 data
+ * ```
+ */
+export interface SafeResult<T> {
+    /** 成功时的数据，失败时为 null */
+    data: T | null;
+    /** 失败时的错误对象，成功时为 null */
+    error: LovrabetError | null;
+}
+/**
+ * Promise 或返回 Promise 的函数类型
+ */
+type PromiseLike<T> = Promise<T> | (() => Promise<T>);
+/**
+ * 安全执行 Promise，将异常转换为返回值
+ *
+ * @param fn - Promise 或返回 Promise 的函数
+ * @returns 包含 data 和 error 的结果对象
+ *
+ * @example
+ * ```typescript
+ * // 直接传入 Promise
+ * const { data, error } = await safe(client.models.customer.filter({ where: { status: 'active' } }));
+ * if (error) {
+ *   console.error(error.message);
+ *   return;
+ * }
+ * console.log(data);
+ *
+ * // 传入函数（延迟执行）
+ * const { data, error } = await safe(() => client.models.customer.filter({ ... }));
+ *
+ * // 旧代码继续工作（抛异常模式）
+ * try {
+ *   const data = await client.models.customer.filter({ ... });
+ *   console.log(data);
+ * } catch (error) {
+ *   console.error(error);
+ * }
+ * ```
+ */
+export declare function safe<T>(fn: PromiseLike<T>): Promise<SafeResult<T>>;
+export {};

package/dist/src/utils/sql-safe.d.ts

@@ -0,0 +1,78 @@
+import { LovrabetError } from './errors';
+import type { SqlExecuteResult } from '../api/types';
+/**
+ * sqlSafe 执行结果类型
+ *
+ * @example
+ * ```typescript
+ * const { data, error } = await sqlSafe(() => client.sql.execute(...));
+ * if (error) {
+ *   console.error(error.message, error.code, error.cause);
+ *   return;
+ * }
+ * // data 直接是查询结果数组
+ * data.forEach(row => console.log(row));
+ * ```
+ */
+export interface SqlSafeResult<T> {
+    /** 成功时的查询结果数组，失败时为 null */
+    data: T[] | null;
+    /** 失败时的错误对象，成功时为 null */
+    error: LovrabetError | null;
+}
+/**
+ * Promise 或返回 Promise 的函数类型
+ */
+type SqlPromiseLike<T> = Promise<SqlExecuteResult<T>> | (() => Promise<SqlExecuteResult<T>>);
+/**
+ * 安全执行 SQL 查询，统一处理 HTTP 错误和业务逻辑错误
+ *
+ * @param fn - 返回 SqlExecuteResult 的 Promise 或函数
+ * @returns 包含 data（查询结果数组）和 error 的结果对象
+ *
+ * @example
+ * ```typescript
+ * // 基础用法
+ * const { data, error } = await sqlSafe(() =>
+ *   client.sql.execute({ sqlCode: 'fc8e7777-06e3847d' })
+ * );
+ *
+ * if (error) {
+ *   console.error('查询失败:', error.message);
+ *   return;
+ * }
+ *
+ * // data 直接是查询结果数组
+ * console.log(`查询到 ${data.length} 条记录`);
+ * data.forEach(row => console.log(row));
+ *
+ * // 带类型提示
+ * interface UserStat {
+ *   id: number;
+ *   name: string;
+ *   login_count: number;
+ * }
+ *
+ * const { data, error } = await sqlSafe<UserStat>(() =>
+ *   client.sql.execute({ sqlCode: 'user-stats' })
+ * );
+ *
+ * if (error) {
+ *   if (error.code === 'SQL_ERROR') {
+ *     // 业务逻辑失败（execSuccess = false）
+ *     console.error('SQL 执行失败:', error.cause);
+ *   } else {
+ *     // HTTP 错误（404、500 等）
+ *     console.error('请求失败:', error.status, error.message);
+ *   }
+ *   return;
+ * }
+ *
+ * // data 是 UserStat[]
+ * data.forEach(stat => {
+ *   console.log(`${stat.name}: ${stat.login_count} 次登录`);
+ * });
+ * ```
+ */
+export declare function sqlSafe<T>(fn: SqlPromiseLike<T>): Promise<SqlSafeResult<T>>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrabet/sdk",
-  "version": "1.2.8",
+  "version": "1.3.0-beta.1",
   "license": "SEE LICENSE IN LICENSE",
   "main": "dist/index.js",
   "module": "dist/index.js",