@onlyworlds/sdk 4.8.0 → 4.9.0

package/dist/index.d.ts

@@ -33,7 +33,7 @@ type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creat
 declare const ELEMENT_TYPES: ElementType[];
 /** Canonical OnlyWorlds schema version. Source: the `canonical:` value of the pinned
  *  distribution's VERSION file (see the provenance block at the top of this file). */
-declare const ONLYWORLDS_VERSION: "00.31.00";
+declare const ONLYWORLDS_VERSION: "00.32.00";
 /** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
 type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
 /** Per-type semantic family. Source: the distribution's `presentation.json` sidecar
@@ -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, {
@@ -475,7 +503,7 @@ function buildQuery(params) {
 
 // src/v2/types.generated.ts
 var ELEMENT_TYPES = ["ability", "character", "collective", "construct", "creature", "event", "family", "institution", "language", "law", "location", "map", "marker", "narrative", "object", "phenomenon", "pin", "relation", "species", "title", "trait", "zone"];
-var ONLYWORLDS_VERSION = "00.31.00";
+var ONLYWORLDS_VERSION = "00.32.00";
 var ELEMENT_FAMILIES = {
   ability: "abstract",
   character: "agents",
@@ -1488,6 +1516,7 @@ export {
   ONLYWORLDS_VERSION,
   OwApiError,
   OwNetworkError,
+  OwPreconditionFailedError,
   OwV2Client,
   SPATIAL_TYPES,
   TokenResource,

package/package.json

@@ -1,64 +1,64 @@
-{
-  "name": "@onlyworlds/sdk",
-  "version": "4.8.0",
-  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "types": "dist/index.d.ts",
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "README.md",
-    "AGENTS.md",
-    "CHANGELOG.md",
-    "SCHEMA.md"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
-    "pretest": "npm run build",
-    "test": "node --test",
-    "codegen": "python codegen/generate_types.py",
-    "codegen:check": "python codegen/generate_types.py --check",
-    "schema:verify": "python codegen/verify_dist.py",
-    "schema:check": "npm run schema:verify && npm run codegen:check",
-    "prepublishOnly": "npm run build",
-    "release:verify": "node codegen/verify_release.mjs"
-  },
-  "keywords": [
-    "onlyworlds",
-    "worldbuilding",
-    "api",
-    "sdk",
-    "typescript",
-    "rpg",
-    "ttrpg",
-    "game-development"
-  ],
-  "author": "OnlyWorlds",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/OnlyWorlds/sdk.git"
-  },
-  "homepage": "https://onlyworlds.github.io/",
-  "bugs": {
-    "url": "https://github.com/OnlyWorlds/sdk/issues"
-  },
-  "devDependencies": {
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3"
-  },
-  "peerDependencies": {
-    "typescript": ">=4.5.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "@onlyworlds/sdk",
+  "version": "4.9.0",
+  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "SCHEMA.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "pretest": "npm run build",
+    "test": "node --test",
+    "codegen": "python codegen/generate_types.py",
+    "codegen:check": "python codegen/generate_types.py --check",
+    "schema:verify": "python codegen/verify_dist.py",
+    "schema:check": "npm run schema:verify && npm run codegen:check",
+    "prepublishOnly": "npm run build",
+    "release:verify": "node codegen/verify_release.mjs"
+  },
+  "keywords": [
+    "onlyworlds",
+    "worldbuilding",
+    "api",
+    "sdk",
+    "typescript",
+    "rpg",
+    "ttrpg",
+    "game-development"
+  ],
+  "author": "OnlyWorlds",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OnlyWorlds/sdk.git"
+  },
+  "homepage": "https://onlyworlds.github.io/",
+  "bugs": {
+    "url": "https://github.com/OnlyWorlds/sdk/issues"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}