@lovrabet/sdk 1.4.2-beta.0 → 1.4.3-beta.1

package/README.md

@@ -4,7 +4,7 @@
 
 ## ✨ 特性
 
-- 🔐 **三种认证模式** - OpenAPI（服务端）、OpenAPI（浏览器）、WebAPI（Cookie）
+- 🔐 **三种认证模式** - OpenAPI、Client AK、WebAPI（Cookie）
 - 🎯 **环境自适应** - 根据运行环境自动选择最佳认证方式
 - 🔑 **Token 生成** - 内置 Token 生成器，支持批量生成
 - 📦 **TypeScript** - 完整的类型定义和智能提示
@@ -155,6 +155,93 @@ const client = createClient({
 const users = await client.models.users.getList();
 ```
 
+### 运行态服务：OCR
+
+OCR 通过 `client.services.ocr` 提供统一入口。SDK 会根据认证模式选择真实服务端路由：
+
+- `cookie`：调用 WebAPI `GET /api/ocr/recognize-text`
+- `client-ak`：调用 Client API `POST /client/ocr`
+- `openapi`：当前没有对应 OCR 契约，会在发送请求前抛出 `OCR_AUTH_MODE_UNSUPPORTED`
+
+浏览器或显式 Cookie 场景：
+
+```typescript
+import { createClient, OCR_TYPES, OcrType } from "@lovrabet/sdk";
+
+const client = createClient({
+  appCode: "your-app-code",
+  authMode: "cookie",
+  // 浏览器会自动携带 Cookie；Node.js 可在这里传入 cookie
+});
+
+const result = await client.services.ocr.recognize({
+  url: "https://example.com/invoice.png",
+  type: OcrType.Invoice,
+});
+
+console.log(result.text, result.kvData);
+console.log(OCR_TYPES); // 可直接用于下拉框或能力发现
+```
+
+Client AK 场景：
+
+```typescript
+import { createClient, OcrType } from "@lovrabet/sdk";
+
+const client = createClient({
+  appCode: "your-app-code",
+  authMode: "client-ak",
+  accessKey: process.env.LOVRABET_ACCESS_KEY,
+});
+
+const result = await client.services.ocr.recognize({
+  url: "https://example.com/license.png",
+  type: OcrType.BusinessLicense,
+});
+```
+
+当前支持的 OCR 类型为 `General`、`Invoice`、`Advanced`、`AdvancedCoordinate`、
+`AdvancedGeneral`、`IdCard`、`BankCard`、`BusinessLicense`、`DrivingLicense`、
+`CarNumber` 和 `Table`。当前 SDK OCR 接口只接收 URL，不负责本地文件上传。
+
+### 运行态服务：文件
+
+文件上传与访问 URL 查询通过 `client.services.file` 提供。SDK 根据认证模式选择路由：
+
+- `cookie`：在 Runtime 域名调用 WebAPI `/api/common/uploadFile`、`/api/common/queryFileUrl`
+- `client-ak`：调用 Client API `/client/uploadFile`、`/client/queryFileUrl`
+- `openapi`：当前没有对应文件接口契约
+
+浏览器上传：
+
+```typescript
+const client = createClient({
+  appCode: "your-app-code",
+  authMode: "cookie",
+});
+
+const uploaded = await client.services.file.upload({ file: input.files[0] });
+const access = await client.services.file.queryUrl({
+  filePath: uploaded.filePath!,
+});
+```
+
+Cookie 与 Client AK 模式都使用 `runtimeDomain`。认证模式只决定路由与请求头：
+Cookie 使用 WebAPI 路由并携带 Cookie，Client AK 使用 `/client/*` 路由并携带
+`X-User-AK`。
+
+Node.js 可传入标准 `Blob`，并显式提供文件名：
+
+```typescript
+const uploaded = await client.services.file.upload({
+  file: new Blob([buffer], { type: "application/pdf" }),
+  fileName: "invoice.pdf",
+});
+```
+
+`filePath` 是适合业务字段长期保存的稳定引用。`fileUrl` 默认用于临时预览、OCR
+或短时间消费；只有 URL-only 内容需要长期展示时才传 `longTerm: true`。
+
 ## 🔑 Token 管理
 
 ### 生成单个 Token
@@ -409,6 +496,13 @@ import {
   // API 命名空间
   ApiNamespace,
 
+  // 运行态服务命名空间
+  ServicesNamespace,
+  FileClient,
+  OcrClient,
+  OcrType,
+  OCR_TYPES,
+
   // 认证管理（高级用法）
   AuthManager,
 
@@ -441,6 +535,10 @@ import {
   type SqlExecuteResult,
   type Environment,
   type BaseModelMethods,
+  type LovrabetServices,
+  type OcrService,
+  type OcrRecognizeRequest,
+  type OcrRecognizeResponse,
 } from "@lovrabet/sdk";
 ```
 

package/dist/index.d.ts

@@ -9,6 +9,8 @@ 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 { 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 { AuthManager, } from "./src/auth/index";
 export { generateOpenApiToken, TokenGenerator, isTokenExpiring, getTokenRemainingTime, type GenerateTokenParams, type TokenResult } from "./src/auth/index";
 export type { ClientConfig, LovrabetClient, ModelConfig, ModelsConfig, AuthMode, } from "./src/types/index";