@onlyworlds/sdk 4.8.1 → 4.9.0

package/AGENTS.md

@@ -27,6 +27,9 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Never send a `"world"` field in payloads — world identity comes from the API key (422 otherwise).
 - v2 link fields use ONE name both directions (no `_ids` suffix — that is v1 dialect only).
 - PATCH is destructive on sent fields; use `editLinks` (atomic add/remove) for relationships.
+- Offline or stale edits: pass `{ ifMatch: el.change_seq }` to `patch`/`editLinks` (since 4.9.0).
+  If the element moved, nothing is written and `OwPreconditionFailedError` (412) carries
+  `current`; the server never merges, the client decides.
 - World-meta changes do NOT appear in `/changes` — poll `GET /world` separately.
 - Extension fields: `x_<toolname>_*` is the sanctioned namespace for tool-specific state;
   unknown unprefixed fields 422. Extensions are capped at **64 KB per element** (422,

package/CHANGELOG.md

@@ -5,6 +5,21 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.9.0] — 2026-10-11
+
+### Added
+- **Only if unchanged (keel #210).** `patch(type, id, partial, { ifMatch })` and
+  `editLinks(type, id, field, edit, { ifMatch })` send `If-Match: "<change_seq>"`: the write
+  lands only if the element is still at that `change_seq`. When it has moved, nothing is
+  written and the call throws **`OwPreconditionFailedError`** (412 `precondition_failed`), an
+  `OwApiError` whose `current` is the element as it is now, so the client's re-read is free.
+  `OwApiError.isPreconditionFailed` names the case. The server never merges; the client
+  compares the copy it edited from with `current`. An `ifMatch` that is not a whole number
+  throws `TypeError` before anything is sent. Without `ifMatch`, nothing changes.
+  Checked live on keel-staging: a matching token lands, a stale one is refused with
+  `current` at the live `change_seq`, the refused write changes nothing, and the links
+  route behaves the same.
+
 ## [4.8.1] — 2026-10-11
 
 ### Changed

package/README.md

@@ -119,9 +119,25 @@ for await (const change of client.changesAll(cursor)) {
 
 Edits to the world itself (its name, calendar, `public_read`) don't appear in the change feed. Read `client.getWorld()` and compare `updated_at`.
 
+### Only if unchanged
+
+A client that edits offline, or from a copy it has held a while, can ask for an update to land only if nobody changed the element since it was read: pass the `change_seq` you read as `ifMatch`, on `patch` or `editLinks`.
+
+```typescript
+try {
+  await client.patch('character', el.id, { name: 'Mine' }, { ifMatch: el.change_seq });
+} catch (err) {
+  if (err instanceof OwPreconditionFailedError) {
+    // nothing was written; err.current is the element as it is now
+  }
+}
+```
+
+The check is per element and the server never merges. Compare the copy you edited from with `err.current`: when the fields you changed are not the ones that moved, send again with `ifMatch: err.current.change_seq`; when the same field moved on both sides, ask the user which to keep. Without `ifMatch` a write is unconditional, as before.
+
 ## Errors
 
-Every non-2xx response throws `OwApiError` with the API's envelope: `.status`, `.type`, `.code`, `.param` (the field that failed) and `.docUrl`, which is worth showing to your users. A transport failure throws `OwNetworkError`. `err.isValidationError` covers the common case.
+Every non-2xx response throws `OwApiError` with the API's envelope: `.status`, `.type`, `.code`, `.param` (the field that failed) and `.docUrl`, which is worth showing to your users. A transport failure throws `OwNetworkError`. `err.isValidationError` covers the common case. A write sent with `ifMatch` that found the element moved throws `OwPreconditionFailedError` (412, `err.isPreconditionFailed`), an `OwApiError` that also carries `current`.
 
 ## Schema constants
 

package/dist/index.d.ts

@@ -2132,6 +2132,25 @@ declare class OwApiError extends Error {
      * key never sees it.
      */
     get isOwnerOnly(): boolean;
+    /**
+     * A `patch` or `editLinks` sent with `ifMatch` found the element moved past that
+     * `change_seq` (412 `precondition_failed`, keel #210): nothing was written and nothing
+     * merged. The error is an OwPreconditionFailedError; its `current` is the element as it
+     * is now, so no second read is needed.
+     */
+    get isPreconditionFailed(): boolean;
+}
+/**
+ * 412 `precondition_failed` (keel #210): the element changed since the `change_seq` sent as
+ * `ifMatch`. `current` is the element as it is now, as this key sees it (keel sends it beside
+ * the error envelope; null if a response ever lacks it). The check is per element and the
+ * server never merges: compare the copy you edited from with `current`; when the fields you
+ * changed are not the ones that moved, re-send with `ifMatch: current.change_seq`; when the
+ * same field moved on both sides, ask the user which to keep.
+ */
+declare class OwPreconditionFailedError extends OwApiError {
+    readonly current: Record<string, unknown> | null;
+    constructor(status: number, code: string | null, message: string, docUrl: string | null, detail: unknown, type?: string | null, param?: string | null, retryAfter?: number | null);
 }
 /** Network-level failure (fetch rejected) -- no envelope to parse. */
 declare class OwNetworkError extends Error {
@@ -2227,8 +2246,15 @@ declare class OwV2Client {
      * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
      * replace wholesale, omitted fields stay untouched. For link arrays prefer
      * editLinks() -- atomic server-side merge, no read-before-write.
+     *
+     * `ifMatch` (keel #210): the element's `change_seq` as you read it. The update lands
+     * only if nobody changed the element since; otherwise nothing is written and this throws
+     * an OwPreconditionFailedError (412) whose `current` is the element as it is now. Omit
+     * it for today's unconditional write.
      */
-    patch(type: ElementType | string, id: string, partial: Record<string, unknown>): Promise<OwElement>;
+    patch(type: ElementType | string, id: string, partial: Record<string, unknown>, opts?: {
+        ifMatch?: number;
+    }): Promise<OwElement>;
     /**
      * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
      * tombstone AND scrubs the id from every other element's links in the same
@@ -2239,9 +2265,12 @@ declare class OwV2Client {
      * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
      * Dedupes, tolerates already-present/already-absent ids. Returns the FULL
      * updated element (fixture P5). Use this for all relationship editing; it
-     * retires the read-merge-PATCH dance.
+     * retires the read-merge-PATCH dance. `ifMatch` works as on patch(): a link write
+     * moves the element too.
      */
-    editLinks(type: ElementType | string, id: string, field: string, edit: OwLinkEdit): Promise<OwElement>;
+    editLinks(type: ElementType | string, id: string, field: string, edit: OwLinkEdit, opts?: {
+        ifMatch?: number;
+    }): Promise<OwElement>;
     /**
      * POST /bulk -- up to ~1000 items. Partial success by default (HTTP 200
      * always; inspect per-slot numeric `status` + top-level `errors` flag);
@@ -2353,6 +2382,8 @@ declare class OwV2Client {
         auth?: boolean;
         allowEmpty?: boolean;
         replayAware?: boolean;
+        /** A `change_seq` to send as `If-Match` (keel #210); a whole number, else TypeError before sending. */
+        ifMatch?: number;
     }): Promise<T>;
 }
 
@@ -2712,4 +2743,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, type OwMediaTicket, OwNetworkError, type OwPage, type OwRemovalTicket, type OwRemovedImage, type OwUploadedImage, OwV2Client, type OwWorldMeta, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, parseErrorEnvelope, pinExpectation };
+export { type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, type OwMediaTicket, OwNetworkError, type OwPage, OwPreconditionFailedError, type OwRemovalTicket, type OwRemovedImage, type OwUploadedImage, OwV2Client, type OwWorldMeta, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, parseErrorEnvelope, pinExpectation };

package/dist/index.js

@@ -66,6 +66,23 @@ var OwApiError = class extends Error {
   get isOwnerOnly() {
     return this.status === 403 && this.code === "owner_only";
   }
+  /**
+   * A `patch` or `editLinks` sent with `ifMatch` found the element moved past that
+   * `change_seq` (412 `precondition_failed`, keel #210): nothing was written and nothing
+   * merged. The error is an OwPreconditionFailedError; its `current` is the element as it
+   * is now, so no second read is needed.
+   */
+  get isPreconditionFailed() {
+    return this.status === 412 && this.code === "precondition_failed";
+  }
+};
+var OwPreconditionFailedError = class extends OwApiError {
+  constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
+    super(status, code, message, docUrl, detail, type, param, retryAfter);
+    this.name = "OwPreconditionFailedError";
+    const cur = detail && typeof detail === "object" ? detail.current : void 0;
+    this.current = cur && typeof cur === "object" ? cur : null;
+  }
 };
 var OwNetworkError = class extends Error {
   constructor(message, cause) {
@@ -82,7 +99,8 @@ function parseErrorEnvelope(status, body, retryAfter = null) {
   const param = env.param ?? nested?.param ?? null;
   const docUrl = env.doc_url ?? nested?.doc_url ?? null;
   const message = env.message ?? nested?.message ?? (typeof env.detail === "string" ? env.detail : void 0) ?? `OnlyWorlds API error ${status}${code ? ` (${code})` : ""}`;
-  return new OwApiError(status, code, message, docUrl, body, type, param, retryAfter);
+  const Cls = status === 412 && code === "precondition_failed" ? OwPreconditionFailedError : OwApiError;
+  return new Cls(status, code, message, docUrl, body, type, param, retryAfter);
 }
 function parseRetryAfter(value, now = Date.now()) {
   if (value == null) return null;
@@ -221,9 +239,14 @@ var OwV2Client = class {
    * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
    * replace wholesale, omitted fields stay untouched. For link arrays prefer
    * editLinks() -- atomic server-side merge, no read-before-write.
+   *
+   * `ifMatch` (keel #210): the element's `change_seq` as you read it. The update lands
+   * only if nobody changed the element since; otherwise nothing is written and this throws
+   * an OwPreconditionFailedError (412) whose `current` is the element as it is now. Omit
+   * it for today's unconditional write.
    */
-  async patch(type, id, partial) {
-    return this.request("PATCH", `/${type}/${id}/`, { body: sanitizePayload(partial) });
+  async patch(type, id, partial, opts = {}) {
+    return this.request("PATCH", `/${type}/${id}/`, { body: sanitizePayload(partial), ifMatch: opts.ifMatch });
   }
   /**
    * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
@@ -237,10 +260,11 @@ var OwV2Client = class {
    * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
    * Dedupes, tolerates already-present/already-absent ids. Returns the FULL
    * updated element (fixture P5). Use this for all relationship editing; it
-   * retires the read-merge-PATCH dance.
+   * retires the read-merge-PATCH dance. `ifMatch` works as on patch(): a link write
+   * moves the element too.
    */
-  async editLinks(type, id, field, edit) {
-    return this.request("POST", `/${type}/${id}/links/${field}`, { body: edit });
+  async editLinks(type, id, field, edit, opts = {}) {
+    return this.request("POST", `/${type}/${id}/links/${field}`, { body: edit, ifMatch: opts.ifMatch });
   }
   // -- Bulk ----------------------------------------------------------------
   /**
@@ -395,6 +419,9 @@ var OwV2Client = class {
    * sanitizePayload — callers own their body shape.
    */
   async request(method, path, opts = {}) {
+    if (opts.ifMatch !== void 0 && !(Number.isInteger(opts.ifMatch) && opts.ifMatch >= 0)) {
+      throw new TypeError(`ifMatch must be a whole number (an element's change_seq), got ${String(opts.ifMatch)}`);
+    }
     const url = `${this.baseUrl}${path}${opts.query ? `?${opts.query}` : ""}`;
     const headers = {};
     if (opts.auth !== false) {
@@ -407,6 +434,7 @@ var OwV2Client = class {
     }
     if (opts.body !== void 0) headers["Content-Type"] = "application/json";
     if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+    if (opts.ifMatch !== void 0) headers["If-Match"] = `"${opts.ifMatch}"`;
     let res;
     try {
       res = await this.fetchImpl(url, {
@@ -1488,6 +1516,7 @@ export {
   ONLYWORLDS_VERSION,
   OwApiError,
   OwNetworkError,
+  OwPreconditionFailedError,
   OwV2Client,
   SPATIAL_TYPES,
   TokenResource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.8.1",
+  "version": "4.9.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {