@lovrabet/sdk 1.5.4-beta.3 → 1.6.1-beta.0

package/README.md

@@ -14,6 +14,19 @@
 
 ## 🆕 What's New
 
+### v1.6.0 (2026-10-23)
+- ✨ **业务域命名空间** - 新增权限、Artifact、审批、应用、数据集元信息、脚本管理能力
+  ```typescript
+  await client.permit.getRoleList({ currentPage: 1, pageSize: 20 });
+  const artifacts = await client.artifact.list({ artifactType: "page" });
+  const todo = await client.approval.listTodo();
+  ```
+- ✨ **区分 `/api` 与 `/client`** - 双模式能力自动按 `authMode` 选择前缀；单模式能力在不支持的模式下 fail-closed
+- ✨ **数据集可恢复导入** - `ClientAkModel` 新增 `importContract` / `importBatch` / `importReadback` / `importImage` / `importImageReadback`
+- ✨ **SQL 与 BFF 扩展** - 新增 `client.sql.query()` / `client.sql.listSqls()` 与 `client.bff.getEndpoint()` / `listEndpoints()` / `getScript()`
+- ✨ **其余 Client 接口补齐** - `datasetMeta.queryByCode()`、`artifact.updateFavorite()`、`permit.resolveIdentity()`、`permit.appInviteCallback()`
+- ✨ **Personal BFF CRUD** - `client.personal.bff` 新增 `list` / `get` / `create` / `update`
+
 ### v1.3.7 (2026-03-16)
 - ✨ **批量操作支持** - `update()` 和 `delete()` 现在支持批量操作，最多 1000 条记录
   ```typescript
@@ -530,6 +543,249 @@ try {
 }
 ```
 
+## 业务域能力（v1.6.0 新增）
+
+SDK 按后端实际注册的路径把能力划分为多个顶级命名空间。双模式能力自动按 `authMode` 选择 `/api` 或 `/client` 前缀；单模式能力在不支持的模式下会直接抛出错误，不会静默请求不存在的路径。
+
+### 模式支持对照
+
+| 命名空间 | cookie（`/api`） | client-ak（`/client`） | openapi |
+| --- | --- | --- | --- |
+| `client.permit` | 支持 | 支持 | 抛 `API_AUTH_MODE_UNSUPPORTED` |
+| `client.personal.bff` | 支持 | 支持 | 抛 `PERSONAL_BFF_AUTH_MODE_UNSUPPORTED` |
+| `client.artifact` | 抛 `ARTIFACT_AUTH_MODE_UNSUPPORTED` | 支持 | 抛 `ARTIFACT_AUTH_MODE_UNSUPPORTED` |
+| `client.approval` | 抛 `APPROVAL_AUTH_MODE_UNSUPPORTED` | 支持 | 抛 `APPROVAL_AUTH_MODE_UNSUPPORTED` |
+| `client.app` | 抛 `APP_AUTH_MODE_UNSUPPORTED` | 支持 | 抛 `APP_AUTH_MODE_UNSUPPORTED` |
+| `client.datasetMeta` | 抛 `DATASET_META_AUTH_MODE_UNSUPPORTED` | 支持 | 抛 `DATASET_META_AUTH_MODE_UNSUPPORTED` |
+| `client.management` | 支持 | 抛 `MANAGEMENT_AUTH_MODE_UNSUPPORTED` | 抛 `MANAGEMENT_AUTH_MODE_UNSUPPORTED` |
+
+`appCode` 会由 SDK 自动注入请求体或查询参数，调用时无需重复传递。
+
+> 例外：`client.permit.resolveIdentity()` 后端只在 `/client` 注册，cookie 模式会抛 `IDENTITY_PERMISSION_AUTH_MODE_UNSUPPORTED`。
+
+```typescript
+const web = createClient({ appCode: "demo" }); // 默认 cookie
+
+const ak = createClient({
+  appCode: "demo",
+  authMode: "client-ak",
+  accessKey: "ak_xxx",
+  secretKey: "sk_xxx",
+});
+```
+
+### 权限、角色与成员
+
+适用于 cookie 与 client-ak 两种模式，后端同时提供 `/api/permit/*` 与 `/client/permit/*` 镜像。
+
+```typescript
+// 角色
+const roles = await client.permit.getRoleList({ currentPage: 1, pageSize: 20 });
+
+await client.permit.createRole({
+  roleName: "店长",
+  roleCode: "store_manager",
+  permits: { page: ["order-list"], dataset: ["orders"] },
+});
+await client.permit.updateRole({ id: 12, roleName: "新名称" });
+await client.permit.deleteRole(12);
+await client.permit.getRolePermitList({ needSelf: true, needPublic: false });
+
+// 角色成员
+await client.permit.getRoleUserList({ roleId: 12 });
+await client.permit.updateRoleUserList({
+  roleList: [{ id: 12, userList: [{ userId: "u1" }] }],
+});
+
+// 应用成员
+const employees = await client.permit.queryAppUsers();
+
+// 页面权限
+await client.permit.getPagePermit(menuId);
+await client.permit.savePagePermit({ menuId, dataCreate: { /* ResourcePermitDTO */ } });
+
+// 资源权限
+await client.permit.getResourceMenuList({ roleId: 12 });
+await client.permit.saveMenuPermits({ permitList: [] });
+await client.permit.saveDatasetPermits({ permitList: [] });
+
+// 数据集与菜单权限
+await client.permit.getDatasetPermitList(12);
+await client.permit.getDatasetPermitMeta();
+await client.permit.getMenuPermitList();
+
+// 当前用户运行态权限快照（仅 client-ak；cookie 模式抛 IDENTITY_PERMISSION_AUTH_MODE_UNSUPPORTED）
+const identity = await client.permit.resolveIdentity();
+
+// 应用邀请审批回调（双模式）
+const approved = await client.permit.appInviteCallback({ userId: "u1", approve: "agree" });
+```
+
+### Artifact（仅 client-ak）
+
+```typescript
+const list = await client.artifact.list({ artifactType: "page", favorite: true });
+const one = await client.artifact.get(3); // 不存在时为 null
+
+const created = await client.artifact.create({
+  artifactType: "page",
+  name: "订单页",
+  content: "...",
+  metadata: { version: 1 },
+});
+await client.artifact.update(created.id!, { content: "新内容" });
+await client.artifact.updateFavorite(created.id!, true);
+```
+
+### 审批任务（仅 client-ak）
+
+```typescript
+const todo = await client.approval.listTodo({ currentPage: 1, pageSize: 20 });
+const detail = await client.approval.getTask("task-id");
+
+await client.approval.approve({
+  taskId: "task-id",
+  approved: true,
+  comment: "同意",
+  formPatch: { amount: 100 }, // 只允许当前节点可编辑的顶层字段
+  formDataVersion: detail.formDataVersion, // 必须原样回传 task 详情返回值
+});
+await client.approval.transfer({
+  taskId: "task-id",
+  targetUserId: "u2",
+  comment: "转办",
+});
+```
+
+### 应用、用户、配置与通知（仅 client-ak）
+
+```typescript
+const apps = await client.app.myApps();
+const me = await client.app.loginUserInfo();
+await client.app.bindAccount({ provider: "dingtalk", accountId: "acc_1" });
+
+const flag = await client.app.getConfigByKey<boolean>("feature.newImport");
+const channels = await client.app.listNotificationChannels("DINGTALK");
+```
+
+### 数据集元信息（仅 client-ak）
+
+```typescript
+const datasets = await client.datasetMeta.list({ code: "orders" });
+
+// 按 code 查单个数据集（后端已标记 @Deprecated，优先用 getDrivenData）
+const dataset = await client.datasetMeta.queryByCode("orders");
+
+// id 与 code 至少传一个；返回结构随 doVersion 为 v1 / v2
+const driven = await client.datasetMeta.getDrivenData<DoProtocol>({ code: "orders" });
+```
+
+### 脚本缓存与日志（仅 cookie）
+
+```typescript
+await client.management.clearScriptCache();
+
+const logs = await client.management.searchScriptLogs({
+  startTime: Date.now() - 3600_000,
+  endTime: Date.now(),
+  level: "ERROR",
+  keyword: "timeout",
+  limit: 200,
+});
+```
+
+### 自定义 SQL 列表查询（仅 client-ak）
+
+`client.sql` 是联合类型，`query()` 只由 `ClientAkSqlClient` 提供，需要先用 `instanceof` 收窄。
+
+```typescript
+import { ClientAkSqlClient } from "@lovrabet/sdk";
+
+if (client.sql instanceof ClientAkSqlClient) {
+  const page = await client.sql.query({
+    sqlName: "order",
+    currentPage: 1,
+    pageSize: 20,
+  });
+  // page.tableData / page.paging
+
+  // 不分页，返回应用下全部自定义 SQL
+  const sqls = await client.sql.listSqls();
+}
+```
+
+### BFF 端点查询（仅 client-ak）
+
+```typescript
+import { ClientAkBffClient } from "@lovrabet/sdk";
+
+if (client.bff instanceof ClientAkBffClient) {
+  // 脚本不存在或为 personalOnly 时返回 null
+  const summary = await client.bff.getEndpoint("sqlTest");
+
+  // 当前应用下全部独立端点脚本
+  const endpoints = await client.bff.listEndpoints();
+
+  // 按脚本主键查询详情（personalOnly 仅创建者本人可读）
+  const script = await client.bff.getScript(12);
+}
+```
+
+### 数据集可恢复导入（仅 client-ak）
+
+导入能力位于 `ClientAkModel`。由于 `client.models.X` 的静态类型是 `BaseModelMethods`，需要显式收窄为 `ClientAkModel`。
+
+```typescript
+import { ClientAkModel } from "@lovrabet/sdk";
+
+const model = client.getModel("orders") as ClientAkModel;
+
+const contract = await model.importContract<{
+  schemaFingerprint: string;
+  maxBatchSize: number;
+  maxBatchBytes: number;
+}>();
+
+const { ids, count } = await model.importBatch({
+  schemaFingerprint: contract.schemaFingerprint,
+  items: rows, // 1~500 条
+  // taskId: "auto-id-task", // 需要后端分配 id 时传入
+});
+
+// body 只传 { ids }
+const { items } = await model.importReadback<Order>(ids);
+
+// 图片导入为 multipart/form-data
+await model.importImage({
+  importId: "imp-1",
+  contentHash: "sha256-...",
+  file: blob,
+  fileName: "logo.png",
+});
+await model.importImageReadback({
+  importId: "imp-1",
+  contentHash: "sha256-...",
+  type: "image/png",
+  size: blob.size,
+});
+```
+
+### Personal BFF 管理（双模式）
+
+```typescript
+const scripts = await client.personal?.bff.list();
+const script = await client.personal?.bff.get(12);
+
+await client.personal?.bff.create({
+  functionName: "myFn",
+  scriptContent: "...",
+  description: "说明",
+});
+await client.personal?.bff.update(12, { description: "新说明" });
+
+await client.personal?.bff.execute({ scriptId: 12, params: { id: 1 } });
+```
+
 ## 📖 API 文档
 
 ### 主要导出
@@ -562,6 +818,16 @@ import {
   // API 命名空间
   ApiNamespace,
 
+  // 业务域命名空间（v1.6.0）
+  PermitClient,
+  ArtifactClient,
+  ApprovalClient,
+  AppClient,
+  DatasetMetaClient,
+  ManagementClient,
+  ClientAkSqlClient,
+  ClientAkBffClient,
+
   // 运行态服务命名空间
   ServicesNamespace,
   FileClient,
@@ -576,6 +842,7 @@ import {
   AbstractBaseModel,
   OpenApiModel,
   WebApiModel,
+  ClientAkModel,
   ModelFactory,
 
   // 排序枚举
@@ -599,6 +866,39 @@ import {
   type SelectOptionsParams,
   type SqlExecuteRequest,
   type SqlExecuteResult,
+  type CustomSqlQueryRequest,
+  type UserCustomSqlDTO,
+  type DataList,
+  type PageResult,
+  type DatasetRequest,
+  type DatasetMeta,
+  type DatasetDrivenDataQuery,
+  type RuntimeArtifactDTO,
+  type ArtifactUpsertRequest,
+  type ApprovalFlowTaskItem,
+  type ApprovalFlowTaskDetail,
+  type ApprovalFlowApproveRequest,
+  type ApprovalFlowTransferRequest,
+  type AppRoleVO,
+  type AppRoleCreateParam,
+  type AppRoleUpdateParam,
+  type RoleUserUpdateParam,
+  type ResourcePermitDTO,
+  type MenuPermitDTO,
+  type RuntimeIdentityPermission,
+  type UserAppRelation,
+  type EndpointScriptSummary,
+  type ScriptDefinition,
+  type AppEmployee,
+  type LoginUserInfo,
+  type SmartApp,
+  type NotificationChannelConfig,
+  type ScriptLogQuery,
+  type DatasetImportBatchRequest,
+  type DatasetImportBatchResult,
+  type DatasetImportReadbackResult,
+  type PersonalBffScript,
+  type PersonalBffUpsertRequest,
   type Environment,
   type BaseModelMethods,
   type LovrabetServices,

package/dist/index.d.ts

@@ -8,13 +8,15 @@ export type { SafeResult } from "./src/utils/safe";
 export { sqlSafe } from "./src/utils/sql-safe";
 export type { SqlSafeResult } from "./src/utils/sql-safe";
 export { AbstractBaseModel, OpenApiModel, WebApiModel, ClientAkModel, ModelFactory, } from "./src/models/index";
-export { ApiNamespace } from "./src/api/index";
+export { ApiNamespace, ClientAkSqlClient, ClientAkBffClient, PermitClient, ArtifactClient, ApprovalClient, AppClient, DatasetMetaClient, ManagementClient, } from "./src/api/index";
+export type { AppRoleRequest, AppRoleCreateParam, AppRoleUpdateParam, AppRolePermitQueryParam, AppRoleVO, UserAppRelationQueryParam, AppUserBaseVO, AppRoleUserVO, RoleUserUpdateParam, AppEmployee, BaseRoleVO, ResourcePermitDTO, MenuPermitDTO, AppResourceMenuParam, ResourcePermitParam, MenuRolePermitListVO, RuntimeIdentityPermission, UserAppRelation, ArtifactUpsertRequest, ArtifactListQuery, RuntimeArtifactDTO, ApprovalTodoQuery, ApprovalFlowTaskItem, ApprovalFlowTaskDetail, ApprovalFlowApproveRequest, ApprovalFlowTransferRequest, LoginUserInfo, SmartApp, UserAccountBindRequest, NotificationChannelConfig, ScriptLogQuery, EndpointScriptSummary, ScriptDefinition, ClientAkBffExecuteRequest, PageResult, Paging, DataList, CustomSqlQueryRequest, UserCustomSqlDTO, DatasetRequest, DatasetMeta, DatasetDrivenDataQuery, } from "./src/api/index";
+export type { DatasetImportBatchRequest, DatasetImportBatchResult, DatasetImportReadbackResult, DatasetImportImageRequest, DatasetImportImageReadbackRequest, } from "./src/models/index";
 export { ServicesNamespace, FileClient, OcrClient, OcrType, OCR_TYPES, } from "./src/services/index";
 export type { LovrabetServices, FileQueryUrlRequest, FileService, FileUploadRequest, FileUploadResponse, FileUrlResponse, OcrRecognizeRequest, OcrRecognizeResponse, OcrService, ServiceRequestOptions, } from "./src/services/index";
 export { LovrabetFlowClient } from "./src/flow/index";
 export type { FlowBatchTaskActionRequest, FlowBatchTransferRequest, FlowCcQuery, FlowCcRequest, FlowCustomPageCcDetail, FlowCustomPageDefinition, FlowCustomPageStartResponse, FlowCustomPageSubmittedProcess, FlowCustomPageTaskDetail, FlowCustomPageTaskItem, FlowCustomPageTimeline, FlowDefinitionQuery, FlowPage, FlowPageQuery, FlowProcessReasonRequest, FlowRecord, FlowResubmitRequest, FlowReturnRequest, FlowReturnTarget, FlowStartRequest, FlowSubmittedQuery, FlowTaskActionRequest, FlowTransferRequest, FlowUpdateVariablesRequest, FlowVariableProjectionQuery, FlowVariableQuery, } from "./src/flow/index";
 export { PersonalNamespace, PersonalBffClient, } from "./src/personal/index";
-export type { LovrabetPersonal, PersonalBffExecuteRequest, PersonalBffService, PersonalRequestOptions, } from "./src/personal/index";
+export type { LovrabetPersonal, PersonalBffExecuteRequest, PersonalBffScript, PersonalBffService, PersonalBffUpsertRequest, PersonalRequestOptions, } from "./src/personal/index";
 export { AuthManager, } from "./src/auth/index";
 export { generateOpenApiToken, generateFlowOpenApiToken, TokenGenerator, isTokenExpiring, getTokenRemainingTime, type GenerateTokenParams, type GenerateFlowTokenParams, type TokenResult } from "./src/auth/index";
 export type { ClientConfig, LovrabetClient, ModelConfig, ModelsConfig, AuthMode, Region, } from "./src/types/index";