@torrow/sdk-client 0.10.0 → 0.11.0

package/README.md

@@ -60,6 +60,12 @@ Network failures use `TorrowSdkError`: `category` is independent of the outcome
 
 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
 

package/dist/index.d.ts

@@ -41638,6 +41638,7 @@ interface TorrowSdkSensitiveDetails {
 /** Безопасный снимок ошибки. Отсутствие effects не доказывает отсутствие изменений. */
 interface TorrowSdkErrorInfo {
     /** Общая причина отказа. */ readonly category: TorrowSdkErrorCategory;
+    /** Необязательное пояснение для человека, не для ветвления. Передающий текст отвечает за его безопасность. */ readonly publicMessage?: string;
     /** Метаданные HTTP, если они известны. */ readonly http?: TorrowSdkHttpDetails;
     /** Предметное уточнение выбранного домена. */ readonly detail?: TorrowSdkErrorDetail;
     /** Начало fetch соответствующего запроса. */ readonly request?: TorrowSdkRequestState;
@@ -41653,6 +41654,7 @@ interface TorrowSdkErrorInit extends TorrowSdkErrorInfo {
 declare class TorrowSdkError extends Error implements TorrowSdkErrorInfo {
     #private;
     /** Общая причина отказа. */ readonly category: TorrowSdkErrorCategory;
+    /** Пояснение без изменения исходной строки: до 512 UTF-16 единиц, не пустое после trim; иначе undefined. */ readonly publicMessage?: string;
     /** Безопасные метаданные ответа. */ readonly http?: TorrowSdkHttpDetails;
     /** Неизменяемое предметное уточнение. */ readonly detail?: TorrowSdkErrorDetail;
     /** Начало fetch; не доставка. */ readonly request?: TorrowSdkRequestState;

package/dist/index.js

@@ -89,6 +89,8 @@ var AuthSessionEffectStep = /* @__PURE__ */ ((AuthSessionEffectStep2) => {
 var TorrowSdkError = class _TorrowSdkError extends Error {
   /** Общая причина отказа. */
   category;
+  /** Пояснение без изменения исходной строки: до 512 UTF-16 единиц, не пустое после trim; иначе undefined. */
+  publicMessage;
   /** Безопасные метаданные ответа. */
   http;
   /** Неизменяемое предметное уточнение. */
@@ -106,6 +108,7 @@ var TorrowSdkError = class _TorrowSdkError extends Error {
     super(`Torrow SDK: ${init.category}`);
     this.name = "TorrowSdkError";
     this.category = init.category;
+    this.publicMessage = typeof init.publicMessage === "string" && init.publicMessage.length <= 512 && init.publicMessage.trim().length > 0 ? init.publicMessage : void 0;
     this.http = init.http && Object.freeze({ ...init.http });
     this.detail = init.detail && Object.freeze({ ...init.detail });
     this.request = init.request;
@@ -122,6 +125,7 @@ var TorrowSdkError = class _TorrowSdkError extends Error {
   toJSON() {
     return {
       category: this.category,
+      publicMessage: this.publicMessage,
       http: this.http,
       detail: this.detail,
       request: this.request,
@@ -3460,91 +3464,131 @@ function validField(value, rule) {
   }
   return valid && (rule.validate?.(value) ?? true);
 }
+function patchPublicMessage(category, failureAt) {
+  switch (category) {
+    case "InvalidInput" /* InvalidInput */:
+      return "\u041F\u0430\u0440\u0430\u043C\u0435\u0442\u0440\u044B \u0447\u0430\u0441\u0442\u0438\u0447\u043D\u043E\u0433\u043E \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u044F \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430 \u043D\u0435\u043A\u043E\u0440\u0440\u0435\u043A\u0442\u043D\u044B.";
+    case "InsufficientData" /* InsufficientData */:
+      return "\u0412 \u0441\u043D\u0438\u043C\u043A\u0435 \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430 \u043D\u0435\u0434\u043E\u0441\u0442\u0430\u0442\u043E\u0447\u043D\u043E \u0434\u0430\u043D\u043D\u044B\u0445 \u0434\u043B\u044F \u0431\u0435\u0437\u043E\u043F\u0430\u0441\u043D\u043E\u0433\u043E \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u044F.";
+    case "AccessDenied" /* AccessDenied */:
+      return "\u041D\u0435\u0434\u043E\u0441\u0442\u0430\u0442\u043E\u0447\u043D\u043E \u043F\u0440\u0430\u0432 \u0434\u043B\u044F \u0432\u044B\u043F\u043E\u043B\u043D\u0435\u043D\u0438\u044F \u0447\u0430\u0441\u0442\u0438\u0447\u043D\u043E\u0433\u043E \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u044F \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430.";
+    case "InvalidResponse" /* InvalidResponse */:
+      return failureAt === "ProjectResult" /* ProjectResult */ ? "\u041D\u0435 \u0443\u0434\u0430\u043B\u043E\u0441\u044C \u043F\u0440\u0435\u043E\u0431\u0440\u0430\u0437\u043E\u0432\u0430\u0442\u044C \u043F\u043E\u043B\u0443\u0447\u0435\u043D\u043D\u044B\u0439 \u044D\u043B\u0435\u043C\u0435\u043D\u0442 \u0432 \u0440\u0435\u0437\u0443\u043B\u044C\u0442\u0430\u0442 SDK." : "\u041E\u0442\u0432\u0435\u0442 \u0441\u0435\u0440\u0432\u0435\u0440\u0430 \u043D\u0435\u043F\u0440\u0438\u0433\u043E\u0434\u0435\u043D \u0434\u043B\u044F \u0432\u044B\u043F\u043E\u043B\u043D\u0435\u043D\u0438\u044F \u0447\u0430\u0441\u0442\u0438\u0447\u043D\u043E\u0433\u043E \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u044F \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430.";
+    case "AuthenticationRequired" /* AuthenticationRequired */:
+      return "\u0414\u043B\u044F \u0432\u044B\u043F\u043E\u043B\u043D\u0435\u043D\u0438\u044F \u0447\u0430\u0441\u0442\u0438\u0447\u043D\u043E\u0433\u043E \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u044F \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430 \u0442\u0440\u0435\u0431\u0443\u0435\u0442\u0441\u044F \u0430\u0443\u0442\u0435\u043D\u0442\u0438\u0444\u0438\u043A\u0430\u0446\u0438\u044F.";
+    case "Cancelled" /* Cancelled */:
+      return "\u0412\u044B\u043F\u043E\u043B\u043D\u0435\u043D\u0438\u0435 \u0447\u0430\u0441\u0442\u0438\u0447\u043D\u043E\u0433\u043E \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u044F \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430 \u043E\u0442\u043C\u0435\u043D\u0435\u043D\u043E.";
+    case "RateLimited" /* RateLimited */:
+      return "\u0421\u0435\u0440\u0432\u0435\u0440 \u043E\u0433\u0440\u0430\u043D\u0438\u0447\u0438\u043B \u0447\u0430\u0441\u0442\u043E\u0442\u0443 \u0437\u0430\u043F\u0440\u043E\u0441\u043E\u0432 \u043F\u0440\u0438 \u0447\u0430\u0441\u0442\u0438\u0447\u043D\u043E\u043C \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u0438 \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430.";
+    case "TransportFailure" /* TransportFailure */:
+      return "\u0421\u0431\u043E\u0439 \u0441\u0432\u044F\u0437\u0438 \u0441 \u0441\u0435\u0440\u0432\u0435\u0440\u043E\u043C \u043F\u0440\u0438 \u0447\u0430\u0441\u0442\u0438\u0447\u043D\u043E\u043C \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u0438 \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430.";
+    case "HttpFailure" /* HttpFailure */:
+      return "\u0421\u0435\u0440\u0432\u0435\u0440 \u043E\u0442\u043A\u043B\u043E\u043D\u0438\u043B \u0437\u0430\u043F\u0440\u043E\u0441 \u043F\u0440\u0438 \u0447\u0430\u0441\u0442\u0438\u0447\u043D\u043E\u043C \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u0438 \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430.";
+    default:
+      return "\u041D\u0435 \u0443\u0434\u0430\u043B\u043E\u0441\u044C \u0432\u044B\u043F\u043E\u043B\u043D\u0438\u0442\u044C \u0447\u0430\u0441\u0442\u0438\u0447\u043D\u043E\u0435 \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u0435 \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430.";
+  }
+}
 async function patchItem(http, itemId, fields, options, adapter) {
   let failureAt = "ValidateInput" /* ValidateInput */;
   let effect = "NotApplied" /* NotApplied */;
+  const trustedErrors = /* @__PURE__ */ new Set();
+  function localError(category, publicMessage) {
+    const error = new TorrowSdkError({
+      category,
+      publicMessage: publicMessage ?? patchPublicMessage(category, failureAt),
+      detail: { domain: "ItemPatch" /* ItemPatch */ }
+    });
+    trustedErrors.add(error);
+    return error;
+  }
   try {
     try {
       if (torrowObjectTypeToCode(getTorrowObjectTypeFromTorrowId(itemId)) !== adapter.objectType) {
-        throw itemPatchError("InvalidInput" /* InvalidInput */);
+        throw localError("InvalidInput" /* InvalidInput */);
       }
     } catch {
-      throw itemPatchError("InvalidInput" /* InvalidInput */);
+      throw localError("InvalidInput" /* InvalidInput */);
     }
     const opts = options ?? {};
     if (!isRecord(opts) || Object.keys(opts).some((key) => key !== "versionToCheck" && key !== "signal")) {
-      throw itemPatchError("InvalidInput" /* InvalidInput */);
+      throw localError("InvalidInput" /* InvalidInput */);
     }
     if (options === null) {
-      throw itemPatchError("InvalidInput" /* InvalidInput */);
+      throw localError("InvalidInput" /* InvalidInput */);
     }
     const expectedVersion = opts.versionToCheck;
     const signal = opts.signal;
     if (expectedVersion !== void 0 && !isVersion(expectedVersion) || Object.hasOwn(opts, "versionToCheck") && expectedVersion === void 0 || signal !== void 0 && !isAbortSignal(signal)) {
-      throw itemPatchError("InvalidInput" /* InvalidInput */);
+      throw localError("InvalidInput" /* InvalidInput */);
     }
     const selected = copyValue(fields);
     if (!isRecord(selected) || Object.keys(selected).length === 0) {
-      throw itemPatchError("InvalidInput" /* InvalidInput */);
+      throw localError("InvalidInput" /* InvalidInput */);
     }
     for (const [key, value] of Object.entries(selected)) {
       if (!Object.hasOwn(adapter.fields, key) || !validField(value, adapter.fields[key])) {
-        throw itemPatchError("InvalidInput" /* InvalidInput */);
+        throw localError("InvalidInput" /* InvalidInput */);
       }
     }
     adapter.validateFields?.(selected);
     const readQuery = adapter.readQuery ? { ...adapter.readQuery } : void 0;
     const writeQuery = adapter.writeQuery ? { ...adapter.writeQuery } : void 0;
     if (signal?.aborted) {
-      throw itemPatchError("Cancelled" /* Cancelled */);
+      throw localError("Cancelled" /* Cancelled */);
     }
     const path = `${adapter.basePath}/${encodePathSegment(itemId)}`;
     failureAt = "ReadCurrent" /* ReadCurrent */;
     const dto = await http.requestJson({ method: "GET", path, query: readQuery, signal });
     failureAt = "PrepareWrite" /* PrepareWrite */;
     if (!isRecord(dto) || dto.id !== itemId) {
-      throw itemPatchError("InvalidResponse" /* InvalidResponse */);
+      throw localError("InvalidResponse" /* InvalidResponse */);
     }
     if (dto.meta == null || dto.personalInfo == null) {
-      throw itemPatchError("InsufficientData" /* InsufficientData */);
+      throw localError("InsufficientData" /* InsufficientData */);
     }
     if (!isRecord(dto.meta) || !isRecord(dto.personalInfo)) {
-      throw itemPatchError("InvalidResponse" /* InvalidResponse */);
+      throw localError("InvalidResponse" /* InvalidResponse */);
     }
     const contentType = dto.personalInfo.itemContentType;
     if (contentType === "NoRights" /* NoRights */) {
-      throw itemPatchError("AccessDenied" /* AccessDenied */);
+      throw localError("AccessDenied" /* AccessDenied */, "\u041D\u0435\u0442 \u0434\u043E\u0441\u0442\u0443\u043F\u0430 \u043A \u043F\u043E\u043B\u043D\u043E\u043C\u0443 \u0441\u043D\u0438\u043C\u043A\u0443 \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430.");
     }
     if (contentType !== void 0 && contentType !== null && typeof contentType !== "string") {
-      throw itemPatchError("InvalidResponse" /* InvalidResponse */);
+      throw localError("InvalidResponse" /* InvalidResponse */);
     }
     if (!isVersion(dto.meta.version) || contentType !== "Full" /* Full */) {
-      throw itemPatchError("InsufficientData" /* InsufficientData */);
+      throw localError(
+        "InsufficientData" /* InsufficientData */,
+        "\u0421\u043D\u0438\u043C\u043E\u043A \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430 \u043D\u0435 \u044F\u0432\u043B\u044F\u0435\u0442\u0441\u044F \u043F\u043E\u043B\u043D\u044B\u043C \u0438\u043B\u0438 \u043D\u0435 \u0441\u043E\u0434\u0435\u0440\u0436\u0438\u0442 \u043F\u0440\u0438\u0433\u043E\u0434\u043D\u043E\u0439 \u0432\u0435\u0440\u0441\u0438\u0438 \u0434\u043B\u044F \u0431\u0435\u0437\u043E\u043F\u0430\u0441\u043D\u043E\u0433\u043E \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u044F."
+      );
     }
     const operations = dto.personalInfo.operationList;
     if (operations == null) {
-      throw itemPatchError("InsufficientData" /* InsufficientData */);
+      throw localError("InsufficientData" /* InsufficientData */);
     }
     if (!Array.isArray(operations) || operations.some((value) => typeof value !== "string")) {
-      throw itemPatchError("InvalidResponse" /* InvalidResponse */);
+      throw localError("InvalidResponse" /* InvalidResponse */);
     }
     if (!operations.includes("UpdateItem" /* UpdateItem */)) {
-      throw itemPatchError("AccessDenied" /* AccessDenied */);
+      throw localError("AccessDenied" /* AccessDenied */, "\u0412 \u0441\u043D\u0438\u043C\u043A\u0435 \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430 \u043E\u0442\u0441\u0443\u0442\u0441\u0442\u0432\u0443\u0435\u0442 \u043F\u0440\u0430\u0432\u043E UpdateItem.");
     }
     if (Object.hasOwn(adapter.fields, "name")) {
       if (dto.name == null) {
-        throw itemPatchError("InsufficientData" /* InsufficientData */);
+        throw localError("InsufficientData" /* InsufficientData */);
       }
       if (typeof dto.name !== "string" || dto.name.length === 0) {
-        throw itemPatchError("InvalidResponse" /* InvalidResponse */);
+        throw localError("InvalidResponse" /* InvalidResponse */);
       }
     }
     adapter.assertSnapshot?.(dto);
     if (expectedVersion !== void 0 && expectedVersion !== dto.meta.version) {
-      throw itemPatchError("VersionConflict" /* VersionConflict */);
+      throw localError(
+        "VersionConflict" /* VersionConflict */,
+        "\u041E\u0436\u0438\u0434\u0430\u0435\u043C\u0430\u044F \u0432\u0435\u0440\u0441\u0438\u044F \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430 \u043D\u0435 \u0441\u043E\u0432\u043F\u0430\u0434\u0430\u0435\u0442 \u0441 \u0432\u0435\u0440\u0441\u0438\u0435\u0439 \u043F\u0440\u043E\u0447\u0438\u0442\u0430\u043D\u043D\u043E\u0433\u043E \u0441\u043D\u0438\u043C\u043A\u0430."
+      );
     }
     if (signal?.aborted) {
-      throw itemPatchError("Cancelled" /* Cancelled */);
+      throw localError("Cancelled" /* Cancelled */);
     }
     const unchanged = Object.entries(selected).every(([key, value]) => {
       const equal = adapter.equalField?.(key, dto[key], value, dto);
@@ -3587,13 +3631,18 @@ async function patchItem(http, itemId, fields, options, adapter) {
     } catch (cause) {
       if (dispatched && cause instanceof TorrowSdkError && adapter.casRefusal?.(cause)) {
         effect = "NotApplied" /* NotApplied */;
-        throw cause.withContext({ category: "VersionConflict" /* VersionConflict */ });
+        const error = cause.withContext({
+          category: "VersionConflict" /* VersionConflict */,
+          publicMessage: "\u0421\u0435\u0440\u0432\u0435\u0440 \u043E\u0442\u043A\u043B\u043E\u043D\u0438\u043B \u0437\u0430\u043F\u0438\u0441\u044C \u0438\u0437-\u0437\u0430 \u043A\u043E\u043D\u043A\u0443\u0440\u0435\u043D\u0442\u043D\u043E\u0433\u043E \u0438\u0437\u043C\u0435\u043D\u0435\u043D\u0438\u044F \u0432\u0435\u0440\u0441\u0438\u0438 \u044D\u043B\u0435\u043C\u0435\u043D\u0442\u0430."
+        });
+        trustedErrors.add(error);
+        throw error;
       }
       throw cause;
     }
     failureAt = "ValidateWriteResponse" /* ValidateWriteResponse */;
     if (!isRecord(ack) || ack.id !== itemId) {
-      throw itemPatchError("InvalidResponse" /* InvalidResponse */);
+      throw localError("InvalidResponse" /* InvalidResponse */);
     }
     effect = "Applied" /* Applied */;
     failureAt = "ProjectResult" /* ProjectResult */;
@@ -3601,6 +3650,7 @@ async function patchItem(http, itemId, fields, options, adapter) {
   } catch (cause) {
     const error = cause instanceof TorrowSdkError ? cause : new TorrowSdkError({ category: "Unknown" /* Unknown */, sensitive: { cause } });
     throw error.withContext({
+      publicMessage: trustedErrors.has(error) ? error.publicMessage : patchPublicMessage(error.category, failureAt),
       operation: adapter.operation,
       failureAt,
       detail: { domain: "ItemPatch" /* ItemPatch */ },