Changelog

This document summarizes @lovrabet/sdk (lovrabet-node-sdk) releases from January through August 2026 — 13 official releases from v1.2.5 to v1.4.3.

INFO

Latest version: v1.4.3 (2026-08-07) | Package: @lovrabet/sdk | Source: Git commit diffs

---

v1.4.3 (2026-08-07)

INFO

Runtime OCR recognition and file services (client.services)

✨ feat: new client.services runtime services namespace

LovrabetClient gains a services namespace that brings together runtime OCR recognition and file upload/retrieval, with two clients: ocr and file.

✨ feat: OCR recognition via services.ocr.recognize

Pass a publicly accessible image/file URL and a recognition type; the call returns text, per-line results, and structured key-value data. The OcrType enum covers 11 types, including general, invoice, ID card, bank card, business license, vehicle license, license plate, and table.

const res = await client.services.ocr.recognize({
  url: 'https://example.com/invoice.png',
  type: OcrType.Invoice,
});
// { requestId, type, text, lines, kvData }

✨ feat: file upload and retrieval via services.file.upload / queryUrl

upload takes a Blob/File, uploads it, and returns a filePath; queryUrl exchanges a filePath for an access URL, with download and longTerm options. The file service supports cookie and client-ak auth modes; OpenAPI is not supported.

const uploaded = await client.services.file.upload({
  file: blob,
  fileName: 'report.pdf',
});
const { fileUrl } = await client.services.file.queryUrl({
  filePath: uploaded.filePath!,
});

---

v1.4.2 (2026-06-27)

INFO

aggregate parameter alignment: column

🐞 fix: aggregate now uses the column parameter

Aggregate fields uniformly use column; the old field spelling still works as a backward-compatible alias. A missing column throws INVALID_AGGREGATE_COLUMN.

model.aggregate({
  aggregate: [{ type: 'SUM', column: 'amount' }],
});
// 旧写法 field 仍兼容：
// model.aggregate({ aggregate: [{ type: 'SUM', field: 'amount' }] });

---

v1.4.1 (2026-04-12)

INFO

$notNull condition operator + wrap-up of earlier breaking changes

✨ feat: added the $notNull condition operator

The ConditionOperator type adds $notNull for checking that a field is not null.

// 使用示例
model.getList({
  filter: {
    field: { $notNull: true }
  }
})

Unit tests for filter were added as well.

---

v1.4.0 (feature/cli-client branch)

INFO

⚠️ Contains BREAKING CHANGES — watch out for backward compatibility

✨ feat: Client AK auth mode + batchCreate

Adds an explicit authMode switch with three authentication modes:

authMode	Description	Use case
openapi	OpenAPI signature authentication	Node.js server side, explicitly using AccessKey
client-ak	Client AK authentication (new)	Next-generation BFF/SQL clients
cookie (default)	WebAPI Cookie authentication	Browser/server side, the default mode

BREAKING CHANGE (important):

When authMode is not set, the default is cookie (WebAPI) — the SDK no longer infers OpenAPI from accessKey/token alone.

✨ feat: batchCreate for bulk inserts (1–1000 records)

AbstractBaseModel gains a batchCreate method:

// 一次创建最多 1000 条
model.batchCreate([
  { name: '张三', age: 25 },
  { name: '李四', age: 30 }
])

• WebAPI sends the body as an array
• OpenAPI uses paramList (aligned with the server-side contract)

✨ feat: new ClientAKModel and ClientAkAuth

src/api/ adds client-ak-bff-client.ts and client-ak-sql-client.ts, providing client-ak-prefixed SQL/BFF client capabilities.

ModelFactory refactor: selects the model implementation based on authMode, for clearer responsibilities.

---

v1.3.8 (feature/cli-client branch)

INFO

Q1 changelog doc additions + silenced environment-mapping logs

Mostly documentation additions and log-level adjustments. No functional changes.

---

v1.3.7 (2026-04-03)

INFO

Configuration naming alignment + smoother API calls + parameter pass-through bug fix

✨ feat: runtimeDomain replaces serverUrl

ClientConfig.serverUrl → @deprecated; the new runtimeDomain field aligns with the naming in rabetbase-cli's .rabetbase.json.

getBaseUrl() priority chain:

1. runtimeDomain (new)
2. serverUrl (kept for compatibility; runtimeDomain wins if both are set)
3. window.__GLOBAL__.deploymentConfig.RUNTIME_API_DOMAIN (SSR-injected)
4. getApiEndpoint(env) (environment fallback)

The default environment changed from online to production (online maps automatically to production).

✨ feat: object-merge style for update() / delete()

<grid> <column width-ratio="0.500000"> Old style (still supported)

await model.update(1001, { name: '张三' });
await model.delete(1001);

</column> <column width-ratio="0.500000"> New style (recommended)

await model.update({ id: 1001, name: '张三' });
await model.delete({ id: [1001, 1002] });

</column> </grid>

Internally: typeof idOrData === 'object' && !Array.isArray(idOrData) takes the object branch, destructures id, and merges it with ...rest.

🐛 fix: createClient() ModelsConfig pass-through

The createClient({ appCode, models }) form used to destructure only those two fields, silently dropping extras such as runtimeDomain / token. The fix spreads const { appCode, models, ...rest } = config so rest lands in the final configuration.

---

v1.3.6 (2026-03-16)

INFO

Custom headers, bulk operations, ListResponse type refactor, 5 bug fixes

<grid> <column width-ratio="0.500000"> ✨ feat

• Custom request headers: ClientConfig.options adds headers: Record<string, string> for injecting X-Invoke-Source, trace IDs, and more- Bulk update/delete: the id parameter now accepts string | number | (string | number)[], joined internally with join(','), capped at 1000 records </column> <column width-ratio="0.500000"> 🐛 fix
• ListResponse types aligned with the server: tableData / paging / tableColumns are required; the fictional total / currentPage / pageSize are gone; a new Paging interface- OpenAPI SQL defensive validation: non-empty check on models[0], throws INVALID_MODEL_CONFIG- Explicit cookie detection: new hasExplicitCookie() fixes misdetection in Node.js- aggregate method mapping: OpenApiModel.methodMap completed- LovrabetError override fix </column> </grid>

♻️ refactor: unified environment variables

Adds a development environment (dev.lovrabet.com); online → production and dev → development map automatically. New getApiEndpoint() / getAvailableEnvironments() utility functions.

---

v1.3.4 (2026-03-07)

INFO

aggregate capability completed for OpenAPI mode

✨ feat: aggregate supported in OpenAPI mode

Removes the aggregate override on OpenApiModel; it now inherits the AbstractBaseModel implementation. 'aggregate' is added to supportedOperations, so OpenAPI and WebAPI share the same aggregation logic.

v1.3.5 was a patch release with no functional changes.

---

v1.3.2 (2026-03-06)

INFO

Explicit cookie authentication for Node.js — the server-side SDK works without a browser

✨ feat: ClientConfig adds cookie?: string

CookieAuth is refactored into a dual-mode design:

<grid> <column width-ratio="0.500000"> Browser

• credentials: 'include' sends cookies automatically- no extra headers- isValid() = isBrowser </column> <column width-ratio="0.500000"> Node.js
• the cookie string is injected into the Cookie header- credentials: 'include' only enabled in browsers- isValid() = hasExplicitCookie </column> </grid>

v1.3.3 was a patch release with no functional changes.

---

v1.3.1 (2026-01-25)

INFO

getOne parameter compatibility improvements

✨ feat: getOne() accepts an object argument

model.getOne(123);           // 数字 ID
model.getOne('abc');         // 字符串 ID
model.getOne({ id: 123 });   // 对象格式（新增）

Internally, when typeof idOrParams === 'object', id is destructured — fully backward compatible.

---

v1.3.0 (2026-01-24)

INFO

Architecture upgrade: APIs split into dedicated client modules; breaking changes to the BFF interface

⚠️ Breaking: BFF client interface changes

Removes the FxResult<T> wrapper; execute() now returns the business data T directly:

<grid> <column width-ratio="0.500000"> Old style

const result = await client.bff
.execute('getBundleTemplates');
if (result.success) {
console.log(result.data);
}

</column> <column width-ratio="0.500000"> New style

const templates = await client.bff
.execute({
  scriptName: 'getBundleTemplates',
});
// 失败直接抛 LovrabetError

</column> </grid>

Migration note: result.success checks become try-catch.

✨ feat: safe() / sqlSafe() error handling

Go-style { data, error } return pattern; sqlSafe() unwraps execResult automatically:

const { data, error } = await safe(model.filter(params));
const { data, error } = await sqlSafe(client.sql.execute({ sqlCode }));

♻️ refactor: APIs split into dedicated clients

Client	Path	Responsibility
SqlClient	client.sql	SQL queries execute({ sqlCode, params })
BffClient	client.bff	BFF endpoint execute({ scriptName, params })
UserClient	client.user	user API getList()

client.api remains as a compatibility alias layer.

✨ feat: SortOrder type improvements

SortOrderValue union type accepts both enums and string literals:

orderBy: [{ field: 'createTime', order: SortOrder.DESC }]
orderBy: [{ field: 'createTime', order: 'desc' }]  // 新增

♻️ refactor: unified filter parameter format

All filter parameters now go into paramMap. Adds isDevelopment() environment detection; in development, getList() prints a performance hint nudging you toward filter().

✨ feat: new fx endpoint

client.api.fx() as the BFF call entry point; removes the yt-prefix filtering on filter.

---

v1.2.7 (2026-01-12)

INFO

SSR global configuration injection

✨ feat: getBaseUrl() three-level priority

HttpClient.getBaseUrl() is now public:

1. config.serverUrl (local development / on-premises deployment)
2. window.__GLOBAL__.deploymentConfig.RUNTIME_API_DOMAIN (SSR-injected)
3. getApiEndpoint(env) (environment fallback)

LovrabetClient.getBaseUrl() now simply delegates, removing duplicated logic. Adds global.d.ts type declarations.

v1.2.8 was a patch release with no functional changes.

---

v1.2.5 (2026-01-06)

INFO

Aggregation queries + error handling overhaul + smart diagnostics + safety checks

✨ feat: aggregate() aggregation queries

Supports SUM / COUNT / AVG / MIN / MAX. New types: AggregateParams, AggregateField, AggregateType, JoinConfig, HavingCondition.

WebAPI maps parameter names via YT_PARAM_MAP; OpenAPI throws OPENAPI_OPERATION_NOT_SUPPORTED.

✨ feat: structured error handling

• The LovrabetError constructor takes an options object and adds a description field
• Every throw site returns structured context (model inventory, valid ranges, sample code)
• toJSON() includes description

✨ feat: LLM-friendly smart diagnostics

processResponse intelligently parses server errors:

• Missing field → points out the required fields
• Unknown field → suggests checking the spelling and recommends MCP tools
• 401 → points to login state, appCode permissions, and CORS as places to investigate
• Timeout → includes url / method / timeout context

✨ feat: datasetCode format validation

Model resolution priority: dataset_ prefix > alias > dynamic creation. Enforces a 32-character hexadecimal check and no longer silently creates dynamic models when a configuration already exists.

v1.2.6 was a patch release with no functional changes.

---

Release overview

Version	Date	feat	fix	refactor	Breaking	Key changes
v1.4.3	08-07	3	0	0	—	client.services runtime services: OCR recognition (11 types), file upload and retrieval
v1.4.2	06-27	0	1	0	—	aggregate aligns on column; old field still works
v1.4.1	04-12	3	0	0	—	Client AK auth (client-ak); batchCreate bulk inserts; $notNull operator
v1.3.7	04-03	3	1	0	—	runtimeDomain replaces serverUrl; object-merge update/delete; createClient pass-through fix
v1.3.6	03-16	2	5	1	—	Custom headers; bulk update/delete (1000 records); ListResponse type refactor; unified environment variables
v1.3.4	03-07	1	0	0	—	aggregate supported in OpenAPI mode
v1.3.2	03-06	1	0	0	—	Explicit cookie parameter for Node.js; CookieAuth dual-mode refactor
v1.3.1	01-25	1	0	0	—	getOne accepts an object argument
v1.3.0	01-24	4	0	3	YES	APIs split into SqlClient / BffClient / UserClient; BFF drops FxResult<T>; safe/sqlSafe; SortOrder literal support
v1.2.7	01-12	1	0	0	—	getBaseUrl() three-level priority; SSR global config injection
v1.2.5	01-06	4	0	0	—	aggregate() aggregation queries; structured LovrabetError; LLM smart diagnostics; datasetCode format validation