@v3finance/core-sdk 0.2.0 → 0.2.1

package/dist/esm/resources/transfers.js.map

@@ -1 +1 @@
-{"version":3,"file":"transfers.js","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAmB,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,OAAO,EAAc,MAAM,kBAAkB,CAAA;AAgBtD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,iBAAiB;IACnB,KAAK,CAAY;IACjB,KAAK,CAAQ;IAEtB,YAAY,IAAgB,EAAE,SAAiB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,KAAK,GAAG,kBAAkB,GAAG,CAAC,SAAS,CAAC,YAAY,CAAA;IAC3D,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,IAAI,CACR,KAAyB,EACzB,OAAO,GAAiD,EAAE;QAE1D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAA0B,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE;YACnF,IAAI,EAAE,KAAK;YACX,GAAG,CAAC,KAAK,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;YACvF,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;YACnE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;SAC7E,CAAC,CAAA;QACF,OAAO,OAAO,CAAmD,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE;YACrF,WAAW,EAAE,IAAI;SAClB,CAAC,CAAA;IACJ,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IACzF,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,UAAkB,EAAE,KAAgB;QACvC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAkB;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAe,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;IAC5F,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CACP,UAAkB,EAClB,KAAK,GAA0B,EAAE;QAEjC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;CACF"}
+{"version":3,"file":"transfers.js","sourceRoot":"","sources":["../../../src/resources/transfers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAmB,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,OAAO,EAAc,MAAM,kBAAkB,CAAA;AAgBtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,iBAAiB;IACnB,KAAK,CAAY;IACjB,KAAK,CAAQ;IAEtB,YAAY,IAAgB,EAAE,SAAiB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,KAAK,GAAG,kBAAkB,GAAG,CAAC,SAAS,CAAC,YAAY,CAAA;IAC3D,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CACR,KAAyB,EACzB,OAAO,GAAiD,EAAE;QAE1D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAA0B,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE;YACnF,IAAI,EAAE,KAAK;YACX,GAAG,CAAC,KAAK,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;YACvF,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;YACnE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;SAC7E,CAAC,CAAA;QACF,OAAO,OAAO,CAAmD,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE;YACrF,WAAW,EAAE,IAAI;SAClB,CAAC,CAAA;IACJ,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IACzF,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,UAAkB,EAAE,KAAgB;QACvC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAkB;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAe,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;IAC5F,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CACP,UAAkB,EAClB,KAAK,GAA0B,EAAE;QAEjC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CACvB,MAAM,EACN,GAAG,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,EAC5C,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAA;IACH,CAAC;CACF"}

package/dist/esm/resources/types.d.ts

@@ -34,10 +34,6 @@ import type { AddressDetail as GeneratedAddressDetail, AddressListItem, CreateTr
  * the two must not be merged, because "no account" and "empty account"
  * deserve different wording. Amounts are raw smallest units; put them through
  * the helpers in `units.ts` rather than `Number`.
- *
- * One field is thinner than the type admits: `sharing` is optional because
- * `PATCH /addresses/{id}` reuses this schema WITHOUT it (the document says so
- * itself, on the property). Listings and the detail endpoint do send it.
  */
 export type Address = AddressListItem;
 /** A single address with its sharing and access details. */

package/dist/esm/resources/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/resources/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,aAAa,IAAI,sBAAsB,EACvC,eAAe,EACf,uBAAuB,EACvB,WAAW,IAAI,oBAAoB,EACnC,UAAU,EACX,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,OAAO,GAAG,eAAe,CAAA;AAErC,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,sBAAsB,CAAA;AAElD,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,uBAAuB,CAAC,aAAa,CAAC,CAAA;AAEhE,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAA;AAE9C,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAAG,UAAU,CAAA;AAEnC;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,SAAS,GACT,WAAW,GACX,WAAW,GACX,QAAQ,GACR,WAAW,GACX,UAAU,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/resources/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,aAAa,IAAI,sBAAsB,EACvC,eAAe,EACf,uBAAuB,EACvB,WAAW,IAAI,oBAAoB,EACnC,UAAU,EACX,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,OAAO,GAAG,eAAe,CAAA;AAErC,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,sBAAsB,CAAA;AAElD,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,uBAAuB,CAAC,aAAa,CAAC,CAAA;AAEhE,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAA;AAE9C,4DAA4D;AAC5D,MAAM,MAAM,UAAU,GAAG,UAAU,CAAA;AAEnC;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,SAAS,GACT,WAAW,GACX,WAAW,GACX,QAAQ,GACR,WAAW,GACX,UAAU,CAAA"}

package/dist/esm/version.d.ts

@@ -1,5 +1,5 @@
 /** SDK version, sent in the `user-agent` header. */
-export declare const SDK_VERSION = "0.2.0";
+export declare const SDK_VERSION = "0.2.1";
 /** Default API base URL. */
 export declare const DEFAULT_BASE_URL = "https://policy-engine-rest.ezig.workers.dev";
 //# sourceMappingURL=version.d.ts.map

package/dist/esm/version.js

@@ -1,5 +1,5 @@
 /** SDK version, sent in the `user-agent` header. */
-export const SDK_VERSION = '0.2.0';
+export const SDK_VERSION = '0.2.1';
 /** Default API base URL. */
 export const DEFAULT_BASE_URL = 'https://policy-engine-rest.ezig.workers.dev';
 //# sourceMappingURL=version.js.map

package/docs/concepts.md

@@ -57,7 +57,7 @@ The API expresses this with the HTTP status, because **the response bodies are i
 | --- | --- |
 | 201 | applied — it happened |
 | 202 | pending — funds are RESERVED, nothing has moved, there is a request to sign |
-| 200 | replayed — the same idempotency key; it already happened earlier |
+| 200 | replayed — the same idempotency key; the transfer already existed, in whatever state it is now |
 
 The SDK turns that into `Gated`:
 
@@ -65,13 +65,15 @@ The SDK turns that into `Gated`:
 switch (result.outcome) {
   case 'applied':  return toast('Transfer sent')
   case 'pending':  return toast('Awaiting signatures — funds are reserved')
-  case 'replayed': return toast('This transfer was already sent')
+  case 'replayed': return toast(describeStatus(result.data.transaction.status))
 }
 ```
 
 `replayed` is kept apart from `applied` on purpose: a replay means the previous attempt reached the
-server and only the answer was lost, so the person should be told "already sent" rather than being
-told "sent" a second time.
+server and only the answer was lost — not that it succeeded. The body is that transfer as it stands
+now, so `replayed` must not be shown as "sent": `data.transaction.status` says whether it went out
+(`confirmed`, or `submitted`), is waiting for signatures (`awaiting_approval`), is still executing
+(`pending`) or did not go out (`failed`, `rejected`, `cancelled`).
 
 **Only `transfers.send` can return it.** `idempotencyKey` exists on exactly one request body in the
 whole API — the transfer — so it is the only place where a 200 means "this already happened". On

package/docs/errors.md

@@ -181,6 +181,16 @@ Two sets of uppercase strings travel inside **successful** bodies and will misle
 
 Address creation that requires signatures is **not** an error: the server answers **202** with `{status:"awaiting_approval", approvalRequestId, approvalThreshold}`. Nothing is thrown. (`POLICY_REQUIRES_APPROVAL` exists in the server's type but is never sent — see [Declared but never returned](#declared-but-never-returned).)
 
+Creating an address **into a folder** (`groupId`) can succeed without the folder, and that is not an error either. The right to the folder is checked before anything is created — a refusal there is `GROUP_CREATE_FORBIDDEN` above — but the address is put into the folder only after the signing service and monitoring, and the right is checked again at that moment. If that fails, the address still exists and the answer is still **201**, with `warnings: [{code, message}]` in the body:
+
+| Code | Meaning |
+|---|---|
+| `FOLDER_NOT_FOUND` | The folder was deleted. |
+| `FOLDER_FORBIDDEN` | The address's creator may no longer add addresses to the folder. |
+| `FOLDER_WRITE_FAILED` | Writing the membership failed. |
+
+The same three arrive in `applyWarnings` of a **200** vote that applied an approved `create_address`: there the folder is checked when the request is applied, not when it was filed, and the request's history gets a `folder_skipped` event. Nothing is thrown in either case, so read the field. The address is fine; do not show it inside the folder.
+
 ## Grants and sharing
 
 Address shares, folder shares, member-visibility grants. All grant `POST`s are idempotent: repeating a pair changes the rights, and a revoked grant is reactivated. There is no `GRANT_EXISTS` anywhere.
@@ -385,7 +395,17 @@ A risk threshold in a policy is expressed as a **level**, not a numeric score, a
 
 `/api/auth/*` is the auth library's own namespace. It answers with a flat `{code, message}` that the API's envelope does not rewrite; `CoreError` reads it, so `code` is populated, but the values come from that library and are not part of this API's contract. Do not branch on a fixed list there — branch on `status`, and show `message`.
 
-Rate limiting is not implemented in the API itself. A 429 therefore comes from the platform in front of it, usually without a JSON body, which means `code: "RATE_LIMITED"` and no `details`. Back off and retry.
+One of the library's codes is named here anyway, because the API itself refers to it: `FAILED_TO_GET_SESSION`. The library raises it when it fails to read or renew a session — a sign-out or a revocation deleting the session in the middle of a renewal is one way to get there. The API retries the session lookup once on it; on the API's own paths a failure that survives the retry arrives as `INTERNAL_ERROR`, and only `/api/auth/*` can hand you `FAILED_TO_GET_SESSION` itself, in the library's flat form. Treat it by `status`, like the rest of that namespace.
+
+Three refusals the API puts **in front of** the library are its own: they arrive in the API's envelope, and their codes can be branched on.
+
+| Code | Status | When | What to do |
+|---|---|---|---|
+| `ADMIN_CANNOT_APPROVE_WEB_LOGIN` | 403 | `POST /api/auth/device/approve` by a platform administrator. Approving a web login gives the holder of the code a new session of the approving user, and a platform administrator's session is not handed to the web version at all. | Terminal. Approve from an account that is not a platform administrator. |
+| `WEB_SESSION_CANNOT_APPROVE` | 403 | The same approval sent with a session that was itself obtained through a web login. Only a session signed in another way may approve, so one leaked web token cannot keep minting new ones. | Approve from the mobile app. |
+| `WEB_SESSION_CANNOT_MANAGE_SESSIONS` | 403 | A web-login session called `list-sessions`, `revoke-session`, `revoke-sessions` or `revoke-other-sessions`. Signing out (`sign-out`) is not affected. | Hide session management in a web client; it is done from the mobile app. |
+
+Rate limiting outside `/api/auth/*` is not implemented in the API itself. A 429 there comes from the platform in front of it, usually without a JSON body, which means `code: "RATE_LIMITED"` and no `details`. Inside `/api/auth/*` a 429 can also come from the library's own limiter, as a bare `{message}`; and requesting a web-login code (`/api/auth/device/code`) is limited by the API itself, with a 429 in the API's envelope and `code: "RATE_LIMITED"`. Whichever answered, back off — for `X-Retry-After` seconds when the header is there — and retry.
 
 ## Easily confused
 
@@ -438,15 +458,15 @@ try {
   } else throw e
 }
 
-if (result.outcome === 'replayed') showAlreadySent(result.data)
-else if (result.outcome === 'pending') showAwaitingApproval(result.data)
-else showSent(result.data)
+if (result.outcome === 'pending') showAwaitingApproval(result.data)
+else if (result.outcome === 'applied') showSent(result.data)
+else showByStatus(result.data.transaction.status) // replayed: NOT necessarily sent — see below
 ```
 
 Rules that follow from how the server handles the key:
 
 - **The key is reserved before any external call.** A replay is therefore recognised even if the first attempt died mid-broadcast. The server answers **200** and does not broadcast again; the SDK labels that `outcome: 'replayed'`.
-- **Tell "replayed" apart from "sent".** A replay means the earlier attempt did reach the server and only the answer was lost. Say "already sent", not "sent" a second time.
+- **`replayed` does not mean "sent".** It means "a transfer with this key already exists": the earlier attempt did reach the server and only its answer was lost. `data` is that transfer as it stands **now**, and what happened to it is in `data.transaction.status` — `confirmed` (or `submitted`): it left; `awaiting_approval`: it is waiting for signatures, funds reserved; `pending`: it is still executing; `failed`, `rejected` or `cancelled`: it did not leave. Tell the person that, not "sent".
 - **A new key after a `failed` or `rejected` transfer.** The old key is bound to that row, and reusing it returns the dead transfer instead of sending a new one.
 - **No key sent, and a timeout?** Do **not** retry. Fetch the transfer list or the operation history first and establish whether the transfer exists. Make the SDK's own callers always pass a key so this situation cannot arise.
 - **`network` and `aborted` carry the same uncertainty as `timeout`** on money paths. The request may have been received and executed; only the response was lost. Treat all three identically: same key, or verify first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v3finance/core-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The official TypeScript SDK for the V3 Finance Core API — custodial addresses, transfers under policy control, approvals, shared access, labelling and reports",
   "license": "MIT",
   "repository": {

package/src/core/gated.ts

@@ -15,8 +15,10 @@
  * frozen.
  *
  * `replayed` is kept separate from `applied` on purpose. A replay means the
- * previous attempt DID reach the server and only the answer was lost, so the
- * person should be told "already sent", not "sent" a second time.
+ * previous attempt DID reach the server and only the answer was lost — not
+ * that it succeeded. The body is that operation as it stands now: a replayed
+ * transfer may have gone out, be waiting for signatures, be still executing
+ * or have failed, and only its own status says which.
  */
 
 export type GatedOutcome = 'applied' | 'pending' | 'replayed'
@@ -74,7 +76,11 @@ export function toGated<TApplied, TPending>(
   }
 }
 
-/** Narrowing: the operation ran, now or earlier, and money moved. */
+/**
+ * Narrowing: `applied` or `replayed`. For `applied` the operation ran now.
+ * For `replayed` it only existed already — whether money moved is in the
+ * body's own status, not in this check.
+ */
 export function isApplied<A, P>(
   r: Gated<A, P>,
 ): r is Extract<Gated<A, P>, { outcome: 'applied' | 'replayed' }> {

package/src/core/http.ts

@@ -157,13 +157,27 @@ export class HttpClient {
   constructor(options: ClientOptions & { baseUrl: string }) {
     this.baseUrl = options.baseUrl.replace(/\/+$/, '')
     this.#options = options
-    const f = options.fetch ?? globalThis.fetch
-    if (typeof f !== 'function') {
+    const custom = options.fetch
+    if (typeof (custom ?? globalThis.fetch) !== 'function') {
       throw new Error(
         '@v3finance/core-sdk: fetch is unavailable in this runtime — pass one to the client options.',
       )
     }
-    this.#fetch = f
+    // NEVER store the function and call it as `this.#fetch(…)`. A private
+    // field call passes the client as the receiver, and a browser's `fetch`
+    // checks its receiver: anything but the window is
+    // `TypeError: Illegal invocation`, thrown before a single byte leaves.
+    // Node and React Native do not check, which is how every request from a
+    // web page failed while the whole test suite passed — and since a
+    // `TypeError` out of `fetch` is what a dropped connection looks like, the
+    // failure surfaced as a "network error" on a perfectly good network.
+    //
+    // The wrapper calls with no receiver at all. Without a custom fetch the
+    // global one is looked up per call rather than captured here, so whatever
+    // patches it later (instrumentation, a mock server) is still honoured.
+    this.#fetch = custom
+      ? (input, init) => custom(input, init)
+      : (input, init) => globalThis.fetch(input, init)
     this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
   }
 

package/src/generated/operations.ts

@@ -9,7 +9,7 @@
 // the API does not slip in unclassified.
 //
 // Operations: 171 · admin: 40 · both: 1 · member: 127 · service: 3
-// Spec sha256: a03bd2e06186734bd8816c3d764dd90a48c1c31d7edda2743a3ae29550601cd1
+// Spec sha256: 017bae30075b232ab4efdcfb7785335020be3060b46e3569b1cd887fcf037597
 
 export type Audience = 'member' | 'admin' | 'service' | 'both' | 'unknown'
 

package/src/generated/types.ts

@@ -250,8 +250,8 @@ export interface AddressDetail {
   tokenId: string | null
   /** format: date-time */
   createdAt: string
-  /** Сводка совместного доступа. Приходит в списке и детали адреса; PATCH /addresses/{id} переиспользует эту же схему и sharing НЕ возвращает */
-  sharing?: SharingSummary
+  /** Сводка совместного доступа. Приходит всегда: в списке, ответе PATCH и детали адреса */
+  sharing: SharingSummary
   /** Код токена адреса (из segmentsJson + asset route) */
   asset: string | null
   assetName: string | null
@@ -491,8 +491,8 @@ export interface AddressListItem {
   assetSymbol: string | null
   /** Баланс в decimal (по token.decimals). NULL — ledger-счёта ещё нет */
   balanceDecimal: string | null
-  /** Сводка совместного доступа. Приходит в списке и детали адреса; PATCH /addresses/{id} переиспользует эту же схему и sharing НЕ возвращает */
-  sharing?: SharingSummary
+  /** Сводка совместного доступа. Приходит всегда: в списке, ответе PATCH и детали адреса */
+  sharing: SharingSummary
   /** Владелец адреса (создатель) с UI-метаданными */
   owner: MemberCard | null
   access: AddressAccess
@@ -791,11 +791,11 @@ export interface ApprovalRequestDetail {
 
 export interface ApprovalRequestEvent {
   id: string
-  /** created|voted|approved|rejected|cancelled|applied|apply_failed|stale */
+  /** created|voted|approved|rejected|cancelled|applied|apply_failed|stale|folder_skipped. folder_skipped идёт ПОСЛЕ applied: адрес по заявке create_address создан, но в папку, выбранную при подаче, не положен (папку удалили или у инициатора отозвали право) — причина в comment */
   type: string
   actorId: string | null
   decision: string | null
-  /** Пояснение ПОДПИСАНТА. У события applied всегда null — id созданного объекта лежит в resultId, чтобы клиент не напечатал его как комментарий */
+  /** У voted — пояснение ПОДПИСАНТА; у stale, apply_failed и folder_skipped — системное пояснение для человека. У события applied всегда null — id созданного объекта лежит в resultId, чтобы клиент не напечатал его как комментарий */
   comment: string | null
   /** Только у applied: id созданного/изменённого объекта */
   resultId: string | null
@@ -1328,7 +1328,7 @@ export interface CreateAddressBody {
    * length: 1..16
    */
   emoji?: string
-  /** Создать адрес В группу адресов (нужно право create_address на группе). Новый адрес — member группы, доступен её участникам */
+  /** Создать адрес В группу адресов (нужно право create_address на группе). Новый адрес — member группы, доступен её участникам. Если создание ушло на подпись (202), папка сохраняется в заявке, а право на неё перепроверяется при применении: отозвали — адрес создаётся без папки, с оговоркой applyWarnings в ответе голосования. При прямом создании (201) то же — оговорка `warnings` в теле ответа */
   groupId?: string
 }
 
@@ -1354,6 +1354,15 @@ export interface CreateAddressResult {
     label: string | null
     description: string | null
   }
+  /** Создано, но не всё: адрес есть, а в папку из `groupId` не положен. Право на папку роут проверяет до создания (иначе 403), а запись членства — уже после Wallet Service и мониторинга; право могли отозвать в этом окне или запись могла не пройти. Есть только когда непусто; не показывать адрес в папке, если оговорка пришла */
+  warnings?: FolderSkipWarning[]
+}
+
+export interface FolderSkipWarning {
+  /** FOLDER_NOT_FOUND — папку удалили; FOLDER_FORBIDDEN — у создателя адреса больше нет права заводить в неё адреса; FOLDER_WRITE_FAILED — сбой записи */
+  code: "FOLDER_NOT_FOUND" | "FOLDER_FORBIDDEN" | "FOLDER_WRITE_FAILED"
+  /** Готовая фраза для человека */
+  message: string
 }
 
 export interface CreateCompositeBody {
@@ -3203,6 +3212,8 @@ export interface RequestVoteResult {
   resolvedResultId: string | null
   /** Только для композитных заявок: прогресс по шагам */
   stepsProgress?: StepProgress[]
+  /** Применено, но не всё: адрес по заявке create_address создан (resolvedResultId), а в папку, выбранную при подаче, не положен. Право на папку проверяется при ПРИМЕНЕНИИ, а не при подаче. Есть только когда непусто; в истории заявки — событие folder_skipped */
+  applyWarnings?: FolderSkipWarning[]
 }
 
 export interface StepProgress {

package/src/resources/addresses.ts

@@ -73,9 +73,10 @@ export class AddressesResource {
   /**
    * Metadata only: this touches neither money nor the derivation path.
    *
-   * Answers with the listing shape, minus `sharing` — the endpoint reuses the
-   * schema but does not fill that property, which is why it is optional on
-   * `Address`. Refresh the list rather than reading the share count back.
+   * Answers with the same row as the listing — `owner`, `access` and
+   * `sharing` included — so it can replace the address in a list without a
+   * refetch. Recent operations and `shares`, which `get()` carries, are not
+   * in it.
    */
   update(addressId: string, input: PatchAddressBody): Promise<Address> {
     return this.#http.request<Address>('PATCH', `${this.#base}/${seg(addressId)}`, { body: input })

package/src/resources/transfers.ts

@@ -23,10 +23,20 @@ export interface VoteInput {
  *
  *   applied (201)  — executed, the money left;
  *   pending (202)  — awaiting signatures, funds RESERVED but not sent;
- *   replayed (200) — a repeat; the transfer already existed.
+ *   replayed (200) — a transfer with this `idempotencyKey` already existed,
+ *                    and this is that transfer as it stands NOW.
  *
  * They cannot be told apart by the body. Showing "sent" on `pending` tells
  * the person money has gone when it is frozen.
+ *
+ * `replayed` does not mean "sent" either. It says only that the request was
+ * seen before; what became of it is in `data.transaction.status`:
+ *
+ *   confirmed, submitted     — it left;
+ *   awaiting_approval        — waiting for signatures, funds reserved;
+ *   pending                  — still executing;
+ *   failed, rejected,
+ *   cancelled                — it did not leave.
  */
 export class TransfersResource {
   readonly #http: HttpClient
@@ -37,7 +47,13 @@ export class TransfersResource {
     this.#base = `/api/v1/vaults/${seg(vaultCode)}/transfers`
   }
 
-  /** Sends a transfer. The timeout is long: the path calls the wallet service. */
+  /**
+   * Sends a transfer. The timeout is long: the path calls the wallet service.
+   *
+   * On `outcome: 'replayed'` read `data.transaction.status` before telling
+   * anyone anything — a replay of an attempt that failed, or that is still
+   * waiting for signatures, comes back the same way as one that went out.
+   */
   async send(
     input: CreateTransferBody,
     options: { signal?: AbortSignal; timeoutMs?: number } = {},

package/src/resources/types.ts

@@ -42,10 +42,6 @@ import type {
  * the two must not be merged, because "no account" and "empty account"
  * deserve different wording. Amounts are raw smallest units; put them through
  * the helpers in `units.ts` rather than `Number`.
- *
- * One field is thinner than the type admits: `sharing` is optional because
- * `PATCH /addresses/{id}` reuses this schema WITHOUT it (the document says so
- * itself, on the property). Listings and the detail endpoint do send it.
  */
 export type Address = AddressListItem
 

package/src/version.ts

@@ -1,5 +1,5 @@
 /** SDK version, sent in the `user-agent` header. */
-export const SDK_VERSION = '0.2.0'
+export const SDK_VERSION = '0.2.1'
 
 /** Default API base URL. */
 export const DEFAULT_BASE_URL = 'https://policy-engine-rest.ezig.workers.dev'