@lovrabet/sdk 1.2.9-beta.0 → 1.3.0-beta.2

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

@@ -1,20 +1,42 @@
 import type { HttpClient } from "../http/http-client";
-import type { FxResult } from "./types";
+/**
+ * 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 result = await client.bff.execute('getBundleTemplates');
- * if (result.success) {
- *   console.log(result.data);
- * }
+ * const templates = await client.bff.execute({
+ *   scriptName: 'getBundleTemplates'
+ * });
+ * templates.forEach(template => console.log(template.name));
  *
  * // 带参数调用
- * const result = await client.bff.execute('calculatePrice', {
- *   productId: '123',
- *   quantity: 10
+ * 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' } }
  * });
  *
  * // 带类型提示
@@ -23,10 +45,9 @@ import type { FxResult } from "./types";
  *   name: string;
  *   items: string[];
  * }
- * const result = await client.bff.execute<BundleTemplate>('getBundleTemplates');
- * if (result.success && result.data) {
- *   result.data.forEach(template => console.log(template.name));
- * }
+ * const templates = await client.bff.execute<BundleTemplate>({
+ *   scriptName: 'getBundleTemplates'
+ * });
  * ```
  */
 export declare class BffClient {
@@ -36,9 +57,9 @@ export declare class BffClient {
     /**
      * 调用 Backend For Frontend (BFF) 端点
      *
-     * @param scriptName 脚本名称（endpoint 函数名）
-     * @param bodyParams 请求体参数（可选）
-     * @returns Function 执行结果（包含 success 和 data）
+     * @param request 请求参数
+     * @returns BFF 函数返回的业务数据
+     * @throws {LovrabetError} 当 HTTP 请求失败时抛出异常
      */
-    execute<T = any>(scriptName: string, bodyParams?: Record<string, any>): Promise<FxResult<T>>;
+    execute<T = any>(request: BffExecuteRequest): Promise<T>;
 }

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

@@ -28,11 +28,17 @@ export declare class ApiNamespace {
      *
      * @example
      * ```typescript
-     * // 推荐用法
-     * const data = await client.sql.execute('fc8e7777-06e3847d');
+     * // 推荐用法（对象参数）
+     * const data = await client.sql.execute({
+     *   sqlCode: 'fc8e7777-06e3847d',
+     *   params: { userId: '123' }
+     * });
      *
      * // 别名用法（兼容）
-     * const data = await client.api.sql('fc8e7777-06e3847d');
+     * const data = await client.api.sql({
+     *   sqlCode: 'fc8e7777-06e3847d',
+     *   params: { userId: '123' }
+     * });
      * ```
      */
     get sql(): SqlClient["execute"];
@@ -51,11 +57,15 @@ export declare class ApiNamespace {
      *
      * @example
      * ```typescript
-     * // 推荐用法
-     * const result = await client.bff.execute('getBundleTemplates');
+     * // 推荐用法（对象参数）
+     * const result = await client.bff.execute({
+     *   scriptName: 'getBundleTemplates'
+     * });
      *
      * // 别名用法（兼容）
-     * const result = await client.api.bff('getBundleTemplates');
+     * const result = await client.api.bff({
+     *   scriptName: 'getBundleTemplates'
+     * });
      * ```
      */
     get bff(): BffClient["execute"];

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

@@ -5,24 +5,26 @@ import type { SqlExecuteResult } from "./types";
  *
  * @example
  * ```typescript
- * // 方式1：直接传参（推荐）
+ * // 推荐：对象参数
+ * 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'
  * });
  *
- * // 方式2：对象参数（兼容 customSql.execute）
- * const data = await client.sql.execute({
- *   sqlCode: 'fc8e7777-06e3847d',
- *   params: { userId: '123' }
- * });
- *
  * // 带类型提示
  * interface PageStat {
  *   creation_date: string;
  *   page_count: number;
  * }
- * const data = await client.sql.execute<PageStat>('fc8e7777-06e3847d');
+ * const data = await client.sql.execute<PageStat>({
+ *   sqlCode: 'fc8e7777-06e3847d'
+ * });
  * ```
  */
 export declare class SqlClient {
@@ -32,8 +34,8 @@ export declare class SqlClient {
      * 执行自定义 SQL 查询
      *
      * 支持两种调用方式：
-     * 1. execute(sqlCode, params) - 直接传参（推荐）
-     * 2. execute({ sqlCode, params }) - 对象参数（兼容 customSql.execute）
+     * 1. execute({ sqlCode, params }) - 对象参数（推荐）
+     * 2. execute(sqlCode, params) - 直接传参（兼容）
      *
      * @returns SQL执行结果（包含 execSuccess 和 execResult）
      */

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

@@ -16,24 +16,6 @@ export interface SqlExecuteResult<T = Record<string, any>> {
     /** SQL 查询结果数组 */
     execResult?: T[];
 }
-/**
- * Backend Function (独立端点) 请求参数
- */
-export interface FxRequest {
-    /** 请求体参数，由调用方传递任意 JSON 数据 */
-    [key: string]: any;
-}
-/**
- * Backend Function (独立端点) 执行结果数据
- */
-export interface FxResult<T = any> {
-    /** Function 执行是否成功 */
-    success: boolean;
-    /** Function 返回的业务数据 */
-    data?: T;
-    /** 错误消息（执行失败时） */
-    message?: string;
-}
 /**
  * 用户信息
  */

package/dist/src/models/openapi-model.d.ts

@@ -12,7 +12,7 @@ export declare class OpenApiModel extends AbstractBaseModel {
     /**
      * OpenAPI 模式的请求体构建策略
      * 认证信息（token、timeStamp）由 HttpClient 自动添加到请求头（Header）中
-     * 请求体只包含业务数据
+     * 请求体格式：{ appCode, datasetCode, paramMap }
      */
     protected buildRequestBody(method: string, data: any, sortList?: SortList): any;
     /**

package/dist/src/utils/browser-detection.d.ts

@@ -6,6 +6,15 @@
  * @returns {boolean} 如果在浏览器环境中返回 true，否则返回 false
  */
 export declare function isBrowser(): boolean;
+/**
+ * 检测是否为开发环境
+ * @returns {boolean} 开发环境返回 true，否则返回 false
+ *
+ * 判断逻辑：
+ * - Node.js 环境：process.env.NODE_ENV !== 'production'
+ * - 浏览器环境：dev.lovrabet.com 或 localhost 或 127.* 或 192.168.*
+ */
+export declare function isDevelopment(): boolean;
 /**
  * 在浏览器环境中使用 accessKey 时显示安全警告
  * @param message - 自定义警告消息（可选）

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 { isBrowser, isDevelopment, 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.9-beta.0",
+  "version": "1.3.0-beta.2",
   "license": "SEE LICENSE IN LICENSE",
   "main": "dist/index.js",
   "module": "dist/index.js",