@torrow/sdk-client 0.9.1 → 0.11.0

package/README.md

@@ -42,6 +42,12 @@ Show an access-denied screen for reads; preserve unsaved input for denied writes
 
 See [the guide and runnable examples](https://github.com/torrowtechnologies/torrow-sdk-ts/blob/main/docs/item-access-errors.md).
 
+## Service updates and personal metadata
+
+Full `client.services.update` can change `personalInfo.meta` even when only the service name changes. The server updates participants' personal links after saving the service; `isNeedAnnouncement: false` only disables announcement creation. Service `meta` and personal-link `personalInfo.meta` have independent versions and modification times. Use the service version for its CAS contract; do not restore old personal-link metadata to remove the diff.
+
+See [the service update explanation and illustrative diff](https://github.com/torrowtechnologies/torrow-sdk-ts/blob/main/src/resources/services/README.md#обновление-услуги-и-personalinfometa), including the current write-type limitation for `meta`. This observation covers full Service update; other types/endpoints and atomicity of the whole server chain are not confirmed.
+
 ## Field docs package
 
 MCP and LLM field catalogs live in `@torrow/sdk-docs`.
@@ -53,3 +59,29 @@ Network failures use `TorrowSdkError`: `category` is independent of the outcome
 `message`, `toJSON()`, spread and standard console output contain safe diagnostics. Original `cause`, response `body`, full `url` and optional OTP `cleanup` are available explicitly through `getSensitiveDetails()`; do not log that object. Known API names are allowlisted; arbitrary server messages stay private.
 
 Selected composite methods provide optional `detail`, `operation`, `failureAt` and immutable `effects`. Missing `effects` means no description is supplied. Local builder/ID/constructor errors retain their existing exception types. Errors do not authorize automatic retry.
+
+`publicMessage?: string` is an optional explanation for people or AI clients. The eight item `patch` methods supply short Russian messages from SDK templates; other methods may omit it. Use `error.publicMessage ?? "Не удалось выполнить операцию."` for display and `category`/`effects` for decisions. Wording is not a stable machine code and does not prove whether a write happened. Applications can replace it with their own localized text. The standard `Error.message` stays generic.
+
+The constructor accepts nonblank strings of at most 512 UTF-16 code units and preserves them unchanged. Invalid values become `undefined` without throwing, coercing or truncating. This checks shape, not confidentiality: callers creating errors or using `withContext` must supply safe text. SDK patch never forwards server/callback messages or item data into this field.
+
+`toJSON()` includes the explanation. `withContext({})` preserves it, `withContext({ publicMessage: undefined })` clears it, and a supplied string replaces it under the same validation. The original error and sensitive diagnostics remain intact. Unknown server codes, status and correlation metadata remain available through `http`; raw data stays behind `getSensitiveDetails()`.
+
+
+## Частичное обновление item
+
+`client.contexts.patch`, `contacts.patch`, `notes.patch`, `calendars.patch`, `services.patch`, `resourceItems.patch`, `cases.patch` и `loyaltySystems.patch` принимают ID, собственный тип `*ItemPatch` и `{ versionToCheck?, signal? }`. SDK читает полный элемент, сохраняет пропущенные поля и отправляет максимум один полный PUT с обязательной проверкой версии. Объекты и массивы заменяются целиком; способы очистки зависят от поля. Unknown/system поля, пустой patch и explicit undefined запрещены до HTTP.
+
+```ts
+import type { ContextItemPatch } from "@torrow/sdk-client";
+
+const fields: ContextItemPatch = { name: "Обновлённый контекст", description: null };
+// itemId — ID редактируемого контекста; client получает auth от приложения.
+const result = await client.contexts.patch(itemId, fields);
+console.log(result.changed, result.item.meta?.version);
+```
+
+`versionToCheck` задаёт внешнюю ожидаемую версию; без него используется версия внутреннего GET. Результат `{itemId,item,changed}` содержит GET при no-op или фактический ответ сервера после PUT. Нет автоматических retry/readback/rollback. `TorrowSdkError` с `detail.domain=ItemPatch` отделяет причину от эффекта целевого Write: `NotApplied`, `Unknown`, `Applied`. После `Unknown` приложение отдельно читает состояние перед решением о новой записи.
+
+Цена Service/Resource/Case: передавать только один из `priceInfo` (вся область) и `priceProperties` (первая цена с сохранением расписания и остальных настроек). `priceInfo:null` очищает всю область, `priceProperties:null` только первую цену. SDK ничего не рассчитывает.
+
+Изменения контракта: `PackingStrategyProperties` исключено из SDK; `numeratorInfo` Service/LoyaltySystem доступно только create/read и исключается из update/patch. Ответы root PUT этих доменов преобразуют только объявленные OpenAPI даты; название в формате ISO остаётся строкой. `loyaltyCards.patch` отложен до исправления серверного удаления изображений подписок. Примеры и полевые карты находятся в репозитории в `examples/node/` и `docs/research/item-patches/`.