@lovrabet/sdk 1.5.3 → 1.5.4-beta.3

package/README.md

@@ -76,6 +76,70 @@ const user = await client.models.users.getOne("user-id");
 const newUser = await client.models.users.create({ name: "John" });
 ```
 
+### 独立审批 Flow OpenAPI
+
+Flow 仅支持 `openapi` 认证，并绑定当前应用与操作人。Node 客户端已经绑定 `appCode`，因此通过 `client.flow(operatorUserId)` 创建审批客户端：
+
+```typescript
+import { createClient } from "@lovrabet/sdk";
+
+const client = createClient({
+  appCode: "your-app-code",
+  authMode: "openapi",
+  accessKey: process.env.LOVRABET_ACCESS_KEY!,
+  // Runtime dev profile 本地联调：runtimeDomain: "http://127.0.0.1:8081"
+});
+
+const flow = client.flow("1001");
+
+const started = await flow.start({
+  flowCode: "leave",
+  formData: { days: 2, reason: "年假" },
+  variables: { businessId: "LEAVE-20260821-001" },
+  idempotencyKey: "leave-request-001",
+});
+
+const todo = await flow.listTodo({
+  variables: { businessId: "LEAVE-20260821-001" },
+  currentPage: 1,
+  pageSize: 20,
+});
+
+await flow.approve({
+  taskId: todo.records[0].taskId,
+  comment: "同意",
+  variables: { auditSource: "node-sdk" },
+});
+```
+
+常用入口包括 `listTodo`、`listDone`、`listSubmitted`、`getTaskDetail`、`getProcessDetail`、`updateVariables`、`approve`、`reject`、`complete`、`transfer`、`withdraw`、`resubmit`、`returnTask`、`ccProcess` 和 `listCc`。应用管理员可使用 `listAppTodo`、`listAppDone`、`listAppSubmitted` 查询当前应用全量数据；服务端仍会校验操作人是否为应用管理员。
+
+浏览器不能保存 `accessKey`。服务端可使用 `generateFlowOpenApiToken()` 为指定操作人生成短期 Token，浏览器必须用同一个 `appCode`、`operatorUserId` 和 `timestamp` 发起请求：
+
+```typescript
+import { generateFlowOpenApiToken } from "@lovrabet/sdk";
+
+const auth = await generateFlowOpenApiToken({
+  appCode: "your-app-code",
+  operatorUserId: "1001",
+  accessKey: process.env.LOVRABET_ACCESS_KEY!,
+});
+```
+
+浏览器拿到 `{ token, timestamp }` 后：
+
+```typescript
+const client = createClient({
+  appCode: "your-app-code",
+  authMode: "openapi",
+  token,
+  timestamp,
+});
+
+const flow = client.flow("1001"); // 必须与生成 Token 时的 operatorUserId 一致
+const todo = await flow.listTodo();
+```
+
 ### 浏览器端使用
 
 #### 方式 1：使用预生成 Token（推荐）
@@ -490,7 +554,7 @@ import {
 
   // 环境配置
   getApiEndpoint,
-  getAvailableEnvironments,
+  getAvailableRegions,
 
   // 错误处理
   LovrabetError,
@@ -553,7 +617,6 @@ interface ClientConfig {
   secretKey?: string; // 密钥（可选）
   token?: string; // 预生成 token（浏览器）
   timestamp?: number; // token 时间戳
-  env?: "production" | "online" | "daily" | "development"; // 环境
   region?: "cn" | "id"; // 官方节点，默认 cn
   runtimeDomain?: string; // 企业独立部署覆盖，优先于 region
   models?: ModelsConfig; // 模型配置
@@ -565,19 +628,66 @@ interface ClientConfig {
 ```typescript
 const client = createClient({
   appCode: "app-xxx",
-  region: "id",
-  env: "production"
+  region: "id"
+});
+```
+
+企业独立部署直接传入最终 `runtimeDomain`：
+
+```typescript
+const client = createClient({
+  appCode: "app-xxx",
+  runtimeDomain: "https://runtime.customer.example.com"
 });
 ```
 
-企业独立部署直接传入 `runtimeDomain`。解析优先级为：`runtimeDomain` →
-兼容字段 `serverUrl` → 页面注入的 `RUNTIME_API_DOMAIN` → `region + env`
-→ 默认 CN Production。
+解析优先级为：`runtimeDomain` → 兼容字段 `serverUrl` → 页面注入的
+`RUNTIME_API_DOMAIN` → `region` 对应的官方 Runtime Domain → 默认中国大陆节点。
 
 SDK 会对显式 Runtime 地址去除首尾空白和尾斜杠，并拒绝非法 URL、凭证、
 query 或 fragment。未传 `region` 时默认 `cn`；显式传入 `cn` / `id` 以外的值
 会抛出 `INVALID_REGION`，不会静默请求其他区域。
 
+### 路由配置来源
+
+SDK 不会在运行时访问 `lovrabet-routing` 仓库，也不会打开 CLI 的企业路由
+JSON 文件。官方国家/地区的 Runtime Domain 在开发阶段由独立
+`lovrabet-routing` 仓库生成到
+`src/config/generated-region-endpoints.ts`，然后随 `@lovrabet/sdk` npm 包一起
+发布。生成文件包含路由目录 SHA-256，用于检查三个消费者是否来自同一份真源。
+
+```text
+lovrabet-routing/catalog/official-routing.v1.json
+                    │
+                    │ npm run generate
+                    ▼
+src/config/generated-region-endpoints.ts
+                    │
+                    │ SDK build and npm publish
+                    ▼
+createClient({ region })
+```
+
+官方目录中的 Domain 可以是所有消费者共用的字符串，也可以按消费者覆盖。
+生成 SDK 快照时固定以 `lovrabet-node-sdk` 身份解析，优先读取 SDK 专属值，
+否则读取 `default`；两者都没有则生成失败。
+
+SDK 只消费 `runtimeDomain`。`userDomain`、`apiDomain`、`skillDomain`、
+`kbDomain` 和 `appDomain` 属于 CLI 或其他平台能力，不应在 SDK 内复制路由
+判断。
+
+企业部署由应用或上游工具把最终 `runtimeDomain` 传给 SDK。Rabetbase 生成的
+前端项目可通过 `sdk-config.ts` 注入该值；SDK 本身不依赖 Node.js 文件系统，
+因此同一行为可用于浏览器和 Node.js。企业清单中的 `lovrabet-node-sdk` 专属值
+只有在上游以 SDK 身份解析后才会生效，不能仅把清单文件放在项目中。
+
+### 路由维护与发布
+
+维护者不得直接编辑 `src/config/generated-region-endpoints.ts`。新增或调整官方
+节点时，应在 `lovrabet-routing` 修改真源并执行 `npm run generate`，然后在本仓
+执行类型检查、完整测试和构建。只发布路由仓不会改变已安装 SDK；生成快照必须
+随新的 SDK 版本发布，并与两个 CLI 的快照放在同一发布批次。
+
 ### CRUD 操作
 
 ```typescript

package/dist/index.d.ts

@@ -11,10 +11,12 @@ export { AbstractBaseModel, OpenApiModel, WebApiModel, ClientAkModel, ModelFacto
 export { ApiNamespace } from "./src/api/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 { AuthManager, } from "./src/auth/index";
-export { generateOpenApiToken, TokenGenerator, isTokenExpiring, getTokenRemainingTime, type GenerateTokenParams, type TokenResult } 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";
 export type { ListParams, ListResponse, FilterParams, WhereCondition, FieldCondition, ConditionOperator, Environment, BaseModelMethods, SortList, SelectOption, SelectOptionsParams, AggregateParams, AggregateField, HavingCondition, } from "./src/types/index";
 export type { SqlExecuteRequest, SqlExecuteResult, } from "./src/api/types";