Platform Services (OCR / File)

client.services is the platform services namespace introduced in @lovrabet/sdk v1.4.3+. It exposes general platform capabilities that are not tied to a dataset or BFF. It currently includes OCR recognition and file upload / access URL.

Requires: SDK v1.4.3+ ｜ Imports: createClient, OcrType, OCR_TYPES

client.services.ocr    // OCR recognition
client.services.file   // File upload and access URL query

Auth Mode & Routing

Both the OCR and file services select the server-side route automatically based on authMode:

authMode	OCR route	File route	Notes
`cookie`	`GET /api/ocr/recognize-text`	`/api/common/uploadFile`, `/api/common/queryFileUrl`	WebAPI, carries the user Cookie
`client-ak`	`POST /client/ocr`	`/client/uploadFile`, `/client/queryFileUrl`	Client API, carries `X-User-AK`
`openapi`	❌ throws `OCR_AUTH_MODE_UNSUPPORTED`	❌ throws `FILE_AUTH_MODE_UNSUPPORTED`	No corresponding contract yet

💡 Both supported modes use runtimeDomain; the auth mode only decides the route prefix and headers. The OpenAPI (dataset signing) mode does not support these services.

OCR Recognition: `client.services.ocr.recognize()`

Signature

client.services.ocr.recognize(request: OcrRecognizeRequest): Promise<OcrRecognizeResponse>

interface OcrRecognizeRequest {
  url: string;            // Publicly accessible image / file URL (required)
  type: OcrType;          // OCR recognition type (required)
  options?: ServiceRequestOptions; // Optional fetch settings (method/body are SDK-controlled)
}

Supported recognition types

Reference them via the OcrType enum to avoid hand-written strings; OCR_TYPES is a read-only array you can use directly in dropdowns or capability discovery.

`OcrType`	Description
`General`	General text recognition
`Invoice`	VAT invoice
`Advanced`	High-accuracy full-text
`AdvancedCoordinate`	High-accuracy (with coordinates)
`AdvancedGeneral`	High-accuracy general
`IdCard`	ID card
`BankCard`	Bank card
`BusinessLicense`	Business license
`DrivingLicense`	Driving license
`CarNumber`	License plate
`Table`	Table

import { createClient, OcrType, OCR_TYPES } from "@lovrabet/sdk";

const client = createClient({
  appCode: "your-app-code",
  authMode: "cookie",
  // Browser carries the Cookie automatically; in Node.js pass the cookie field here
});

const result = await client.services.ocr.recognize({
  url: "https://example.com/invoice.png",
  type: OcrType.Invoice,
});

console.log(result.text);     // Full text
console.log(result.kvData);   // Structured key-values (invoice no., amount, etc.)
console.log(OCR_TYPES);       // ['General', 'Invoice', ...] for dropdowns

Example: Client AK (server-side)

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,
});

Response

interface OcrRecognizeResponse {
  requestId?: string;
  type?: OcrType;
  text?: string;                 // Full text
  lines?: string[];              // Split by line
  kvData?: Record<string, string>; // Structured key-values
  width?: number;
  height?: number;
  pageNo?: number | null;
  // ...other fields vary by recognition type, all optional
}

⚠️ The OCR interface only accepts a URL and does not upload local files. To recognize a local file, first upload it via client.services.file.upload() to get a reachable URL, then pass it to recognize().

File Service: `client.services.file`

Upload: `upload()`

client.services.file.upload(request: FileUploadRequest): Promise<FileUploadResponse>

interface FileUploadRequest {
  file: Blob;             // Browser File or standards-compatible Blob (required)
  fileName?: string;      // Optional filename; required for Blob without a name, otherwise falls back to upload.bin
  options?: ServiceRequestOptions;
}

Browser upload (input.files[0] is a standard File):

const client = createClient({ appCode: "your-app-code", authMode: "cookie" });

const uploaded = await client.services.file.upload({ file: input.files[0] });
console.log(uploaded.filePath); // Persistent reference — recommended to store in a business field

Node.js upload (pass a standard Blob and an explicit filename):

const uploaded = await client.services.file.upload({
  file: new Blob([buffer], { type: "application/pdf" }),
  fileName: "invoice.pdf",
});

Response:

interface FileUploadResponse {
  fileName?: string | null;
  filePath?: string | null;   // ⭐ Persistent reference, suitable for long-term storage
  fileUrl?: string | null;    // Temporary access URL
  downloadFlag?: boolean;
  fileType?: string | null;
  size?: number | null;
  sourceDir?: string | null;
}

Query access URL: `queryUrl()`

client.services.file.queryUrl(request: FileQueryUrlRequest): Promise<FileUrlResponse>

interface FileQueryUrlRequest {
  filePath: string;        // filePath returned by upload() (required)
  download?: boolean;      // true returns a download URL, default false (preview URL)
  longTerm?: boolean;      // Request a long-term URL, default false
  options?: ServiceRequestOptions;
}

const access = await client.services.file.queryUrl({
  filePath: uploaded.filePath!,
});
console.log(access.fileUrl);

// Need a download link
const dl = await client.services.file.queryUrl({
  filePath: uploaded.filePath!,
  download: true,
});

`filePath` vs `fileUrl`: when to use which

Field	Purpose	Validity
`filePath`	A stable reference stored in a business field; swap for a URL anytime later	Long-term
`fileUrl`	Temporary preview, OCR input, short-lived consumption	Short-term
`longTerm: true`	Request only when content needs URL-only long-term display	Long-term

💡 Recommended: store only filePath in your business table; call queryUrl() to obtain a temporary URL when you need to display or download.

Error Handling

The services throw LovrabetError on validation failure or unsupported auth mode; the code and description are directly usable for diagnostics:

code	Trigger	description key fields
`OCR_URL_REQUIRED`	`url` is empty	`field: "url"`
`OCR_TYPE_UNSUPPORTED`	`type` not in `OCR_TYPES`	`supportedTypes`
`OCR_AUTH_MODE_UNSUPPORTED`	OCR called in OpenAPI mode	`supportedAuthModes: ["cookie","client-ak"]`
`FILE_REQUIRED`	`file` is not a Blob/File	`field: "file"`
`FILE_PATH_REQUIRED`	`queryUrl` `filePath` is empty	`field: "filePath"`
`FILE_AUTH_MODE_UNSUPPORTED`	File service called in OpenAPI mode	`supportedAuthModes: ["cookie","client-ak"]`

import { LovrabetError } from "@lovrabet/sdk";

try {
  await client.services.ocr.recognize({ url: "", type: OcrType.Invoice });
} catch (e) {
  if (e instanceof LovrabetError) {
    console.log(e.code);        // 'OCR_URL_REQUIRED'
    console.log(e.description); // { field: 'url', suggestion: '...' }
  }
}

Next Steps

Authentication Configuration — Configuring the four modes (Client AK / OpenAPI / Cookie)
API Usage Guide — Dataset CRUD and batch operations
API Reference — Full signatures for ServicesNamespace / OcrClient / FileClient

Auth Mode & Routing​

OCR Recognition: client.services.ocr.recognize()​

Signature​

Supported recognition types​

Example: browser / Cookie​

Example: Client AK (server-side)​

Response​

File Service: client.services.file​

Upload: upload()​

Query access URL: queryUrl()​

filePath vs fileUrl: when to use which​

Error Handling​

Next Steps​