@lovrabet/sdk 1.4.3 → 1.5.1-beta.1

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

@@ -7,6 +7,7 @@ import { BffClient } from '../api/bff-client';
 import { ClientAkBffClient } from '../api/client-ak-bff-client';
 import { UserClient } from '../api/user-client';
 import { ServicesNamespace } from '../services';
+import { PersonalNamespace } from '../personal';
 /**
  * Lovrabet SDK 核心客户端类
  *
@@ -50,6 +51,10 @@ export declare class LovrabetClient implements ILovrabetClient {
      * 平台服务命名空间 - OCR 等不绑定数据集或 BFF 的通用运行态能力
      */
     readonly services: ServicesNamespace;
+    /**
+     * 当前用户拥有的资源，如个人 BFF。
+     */
+    readonly personal: PersonalNamespace;
     /**
      * API 命名空间 - 别名入口（向后兼容）
      *

package/dist/src/config/constants.d.ts

@@ -28,6 +28,15 @@ export declare const ENVIRONMENTS: {
     /** 开发环境 */
     readonly DEVELOPMENT: "development";
 };
+/**
+ * Lovrabet official deployment regions.
+ */
+export declare const REGIONS: {
+    /** Mainland China node (default). */
+    readonly CN: "cn";
+    /** Indonesia node. */
+    readonly ID: "id";
+};
 /**
  * HTTP 状态码常量
  */

package/dist/src/config/endpoints.d.ts

@@ -1,3 +1,5 @@
+import type { Region } from '../types';
+/** Mainland China endpoints retained as the backward-compatible public export. */
 export declare const API_ENDPOINTS: {
     readonly production: "https://runtime.lovrabet.com";
     readonly online: "https://runtime.lovrabet.com";
@@ -5,12 +7,30 @@ export declare const API_ENDPOINTS: {
     readonly development: "https://dev.lovrabet.com";
 };
 export type Environment = keyof typeof API_ENDPOINTS;
+/** Runtime endpoints selected by official region and environment. */
+export declare const REGION_API_ENDPOINTS: {
+    readonly cn: {
+        readonly production: "https://runtime.lovrabet.com";
+        readonly online: "https://runtime.lovrabet.com";
+        readonly daily: "https://daily-runtime.lovrabet.com";
+        readonly development: "https://dev.lovrabet.com";
+    };
+    readonly id: {
+        readonly production: "https://runtime.lovrabet.id";
+        readonly online: "https://runtime.lovrabet.id";
+        readonly daily: "https://daily-runtime.lovrabet.id";
+        readonly development: "https://dev.lovrabet.id";
+    };
+};
 /**
  * 获取指定环境的 API 端点（支持向下兼容）
  * @param env - 环境名称（支持 "production", "online", "daily", "dev", "development"）
+ * @param region - 官方节点（"cn" 或 "id"），默认 "cn"
  * @returns API 端点 URL
  */
-export declare function getApiEndpoint(env: Environment | string): string;
+export declare function getApiEndpoint(env: Environment | string, region?: Region | string): string;
+/** Returns official regions supported by the SDK's built-in Runtime mapping. */
+export declare function getAvailableRegions(): Region[];
 /**
  * 获取所有可用的环境
  * @returns 环境列表（返回标准化的环境名）

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

@@ -6,7 +6,8 @@ export declare class HttpClient {
     constructor(config: ClientConfig, authManager: AuthManager);
     /**
      * 获取 API 基础地址
-     * 优先级：runtimeDomain > window.__GLOBAL__.deploymentConfig.RUNTIME_API_DOMAIN > getApiEndpoint(env)
+     * 优先级：runtimeDomain > serverUrl >
+     * window.__GLOBAL__.deploymentConfig.RUNTIME_API_DOMAIN > getApiEndpoint(env, region)
      *
      * 注：serverUrl 为 runtimeDomain 的旧名称，向下兼容保留；两者均设置时以 runtimeDomain 优先。
      */

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

@@ -0,0 +1,11 @@
+import type { HttpClient } from "../http/http-client";
+import type { AuthMode } from "../types";
+import type { PersonalBffExecuteRequest, PersonalBffService } from "./types";
+/** Personal BFF execution client exposed under `client.personal.bff`. */
+export declare class PersonalBffClient implements PersonalBffService {
+    private readonly httpClient;
+    private readonly appCode;
+    private readonly authMode;
+    constructor(httpClient: HttpClient, appCode: string, authMode: AuthMode);
+    execute<T = unknown>(request: PersonalBffExecuteRequest): Promise<T>;
+}

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

@@ -0,0 +1,11 @@
+import type { HttpClient } from "../http/http-client";
+import type { AuthMode } from "../types";
+import { PersonalBffClient } from "./bff-client";
+import type { LovrabetPersonal } from "./types";
+/** Namespace for resources owned by the current user. */
+export declare class PersonalNamespace implements LovrabetPersonal {
+    readonly bff: PersonalBffClient;
+    constructor(httpClient: HttpClient, appCode: string, authMode: AuthMode);
+}
+export { PersonalBffClient } from "./bff-client";
+export type { LovrabetPersonal, PersonalBffExecuteRequest, PersonalBffService, PersonalRequestOptions, } from "./types";

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

@@ -0,0 +1,18 @@
+/** Per-request options supported by personal resource clients. */
+export type PersonalRequestOptions = Omit<RequestInit, "method" | "body">;
+/** Input accepted when executing a personal BFF. */
+export interface PersonalBffExecuteRequest {
+    /** Positive integer identifier of the personal BFF script. */
+    scriptId: number;
+    /** Parameters passed to the personal BFF script. */
+    params?: Record<string, unknown>;
+    /** Optional fetch settings. The HTTP method and body are controlled by the SDK. */
+    options?: PersonalRequestOptions;
+}
+export interface PersonalBffService {
+    execute<T = unknown>(request: PersonalBffExecuteRequest): Promise<T>;
+}
+/** Personal resources exposed under `client.personal`. */
+export interface LovrabetPersonal {
+    readonly bff: PersonalBffService;
+}

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

@@ -17,6 +17,8 @@
  * - development: 本地开发环境
  */
 export type Environment = "production" | "online" | "daily" | "development";
+/** Official Lovrabet Runtime region. Mainland China is the default. */
+export type Region = "cn" | "id";
 /**
  * 排序方向枚举
  * @description 定义数据排序的方向
@@ -103,15 +105,17 @@ export interface ListResponse<T> {
  * 支持的操作符：
  * - $eq: 等于
  * - $ne: 不等于
- * - $gte / $gteq: 大于等于
- * - $lte / $lteq: 小于等于
+ * - $gt: 大于
+ * - $lt: 小于
+ * - $gte: 大于等于（推荐）；$gteq 为兼容旧写法的别名，后端同样映射为 >=
+ * - $lte: 小于等于（推荐）；$lteq 为兼容旧写法的别名，后端同样映射为 <=
  * - $in: 在集合内
  * - $contain: 包含（模糊匹配）
  * - $startWith: 以...开头
  * - $endWith: 以...结尾
  * - $notNull: 非空判断
  */
-export type ConditionOperator = "$eq" | "$ne" | "$gte" | "$gteq" | "$lte" | "$lteq" | "$in" | "$contain" | "$startWith" | "$endWith" | "$notNull";
+export type ConditionOperator = "$eq" | "$ne" | "$gt" | "$lt" | "$gte" | "$gteq" | "$lte" | "$lteq" | "$in" | "$contain" | "$startWith" | "$endWith" | "$notNull";
 /**
  * 字段条件类型
  * @description 单个字段的查询条件
@@ -419,7 +423,9 @@ export interface ClientConfig {
     serverUrl?: string;
     /** 运行环境，默认为 'production'（向下兼容 'online'） */
     env?: Environment;
-    /** 用户 Token，用于 Bearer 认证 */
+    /** 官方运行节点，默认为 'cn'；显式 runtimeDomain 的优先级更高。 */
+    region?: Region;
+    /** 预计算 OpenAPI token，配合 timestamp 通过 X-Token / X-Time-Stamp 传递，不是 Authorization: Bearer */
     token?: string;
     /** 与 token 配对的时间戳（OpenAPI 模式必需） */
     timestamp?: number;
@@ -429,9 +435,17 @@ export interface ClientConfig {
     secretKey?: string;
     /** Cookie 字符串，用于 Cookie 认证（Node.js 环境专用） */
     cookie?: string;
-    /** 是否需要认证，默认为 true */
+    /**
+     * 显式要求当前 authMode 下的凭据已经齐全时设为 true。
+     * 未设置时不做强制检查（没有默认 true）。
+     * 校验按 authMode：client-ak 需要 accessKey；openapi 需要 accessKey，或 token + timestamp；
+     * cookie / 缺省不能把 token、accessKey 当成已生效的 Cookie 认证。
+     */
     requiresAuth?: boolean;
-    /** 显式声明鉴权模式，优先于字段组合推断。向下兼容：未设置时保持旧推断逻辑 */
+    /**
+     * 显式声明鉴权模式。**未设置时固定回退到 cookie 模式**，不会根据 accessKey / token 等字段自动推断；
+     * 需要 Client AK / OpenAPI 鉴权时必须显式设置（`"client-ak"` 或 `"openapi"`）。
+     */
     authMode?: AuthMode;
     /**
      * 模型配置
@@ -488,7 +502,7 @@ export interface BaseModelMethods {
      * @template T 返回数据的类型
      * @param params Filter 查询参数，支持复杂条件、字段选择、排序和分页
      * @returns 返回分页数据
-     * @description 提供比 getList 更强大的查询能力，支持复杂的 where 条件、字段选择等（仅 WebAPI 模式支持）
+     * @description 提供比 getList 更强大的查询能力，支持复杂的 where 条件、字段选择等（filter 在 WebAPI / OpenAPI / Client AK 模式均支持；delete、excelExport、getSelectOptions 当前不支持 OpenAPI 模式，WebAPI 与 Client AK 均支持）
      * @example
      * ```typescript
      * // 使用枚举
@@ -569,7 +583,7 @@ export interface BaseModelMethods {
     update<T = any>(id: string | number | (string | number)[], data: Record<string, any>): Promise<T>;
     /**
      * 删除数据，支持单条和批量
-     * @throws Error OpenAPI 模式暂不支持此操作，仅 WebAPI 模式可用
+     * @throws Error OpenAPI 模式暂不支持此操作；WebAPI 与 Client AK 模式均可用
      *
      * **推荐写法（对象传入）**：
      * ```typescript
@@ -591,7 +605,7 @@ export interface BaseModelMethods {
      * 获取下拉选项
      * @param params 字段映射参数，指定用作 value 和 label 的字段名
      * @returns 返回下拉选项数组
-     * @description 用于获取数据表的下拉选项数据，适用于 Select 组件（仅 WebAPI 模式支持）
+     * @description 用于获取数据表的下拉选项数据，适用于 Select 组件（WebAPI 与 Client AK 模式支持，OpenAPI 模式不支持）
      * @example
      * ```typescript
      * // 获取用户下拉选项
@@ -607,7 +621,7 @@ export interface BaseModelMethods {
      * 导出数据为 Excel 文件
      * @param params 查询参数（可选），与 getList 参数一致，用于按条件筛选导出数据
      * @returns 返回导出文件的 URL 地址（字符串），可直接用于下载
-     * @description 导出当前数据集的数据为 Excel 文件（仅 WebAPI 模式支持）
+     * @description 导出当前数据集的数据为 Excel 文件（WebAPI 与 Client AK 模式支持，OpenAPI 模式不支持）
      * @example
      * ```typescript
      * // 导出所有数据
@@ -734,14 +748,14 @@ export interface ModelManager {
 }
 /**
  * 认证请求头接口
- * @description 包含认证信息的 HTTP 请求头
+ * @description 包含认证信息的 HTTP 请求头。实际字段由 authMode 决定，不是 Authorization: Bearer。
  * @example
  * ```typescript
- * // Bearer Token 认证
- * { "Authorization": "Bearer your-token" }
+ * // OpenAPI：预计算 token 或 accessKey 签名
+ * { "X-Token": "…", "X-Time-Stamp": "…", "X-App-Code": "app-xxx", "X-Dataset-Code": "…" }
  *
- * // API 密钥认证
- * { "X-Access-Key": "your-key", "X-Signature": "calculated-signature" }
+ * // Client AK
+ * { "X-User-AK": "your-access-key" }
  * ```
  */
 export interface AuthHeaders {
@@ -766,16 +780,14 @@ export interface OpenApiAuthConfig {
 }
 /**
  * 认证管理器接口
- * @description 统一管理不同的认证方式，按优先级自动选择认证策略
- * 认证优先级：Token > OpenAPI密钥 > Cookie
+ * @description 按显式 authMode 选择认证策略；未设置 authMode 时固定为 cookie，不会按 token / accessKey 自动升级。
  * @example
  * ```typescript
- * // 设置 Token 认证
- * authManager.setToken('your-token');
+ * // OpenAPI 预计算 token 必须配对 timestamp
+ * authManager.setToken('your-token', Date.now());
  *
- * // 获取认证头
- * const headers = await authManager.getAuthHeaders();
- * // 返回: { "Authorization": "Bearer your-token" }
+ * const headers = await authManager.getAuthHeaders(appCode, datasetCode);
+ * // 返回: { "X-Token": "…", "X-Time-Stamp": "…" }
  * ```
  */
 export interface AuthManager {
@@ -832,6 +844,13 @@ export interface AuthManager {
 export interface LovrabetClient {
     /** 运行态通用服务，如文件与 OCR。 */
     readonly services: import("../services/types").LovrabetServices;
+    /**
+     * 当前用户拥有的资源，如个人 BFF。
+     *
+     * 该公共接口允许兼容旧版或外部注入的 client；createClient() 返回的
+     * 具体 LovrabetClient 实例始终提供 personal。
+     */
+    readonly personal?: import("../personal/types").LovrabetPersonal;
     /**
      * 模型访问接口 - 纯粹的语法糖，支持 client.models.ModelName 访问
      * @description 内部调用 client.getModel() 方法，提供更简洁的访问方式

package/package.json

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