@onlyworlds/sdk 4.26.0 → 4.27.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.27.1] — 2026-10-16
+
+### Fixed
+- **A retried `create` with the same `idempotencyKey` now replays instead of failing.** `create` minted a
+  fresh id on every call, so a retry of an id-less element sent a different body and keel answered 409
+  `idempotency_error`. With a key and no id, the id is now derived from the key (a UUIDv5, the same id the
+  Python package mints), so the retry sends the same body and gets the first answer back. Without a key,
+  a fresh UUIDv7 as before; an id you pass is kept.
+- `create`'s doc said a keyed retry "rewrites the same element"; keel's replay writes nothing. Found by
+  Quillon's parity audit of the Unity SDK (h37 #5764).
+
+## [4.27.0] — 2026-10-16
+
+### Added
+- `OwApiError.isIdempotencyInFlight` (keel #307, D105): a request with the same Idempotency-Key is still
+  running (409 `idempotency_in_flight`, `retryAfter` 1). Nothing was written by this one; send again with
+  the same key and body after `retryAfter` and it replays the first answer. `isIdempotencyConflict` stays
+  the different-body case only. The client still does not retry for you.
+
 ## [4.26.0] — 2026-10-15
 
 ### Added

package/dist/index.d.ts

@@ -2394,6 +2394,13 @@ declare class OwApiError extends Error {
      * conflict: keel also answers 409 `id_conflict` (see isIdConflict).
      */
     get isIdempotencyConflict(): boolean;
+    /**
+     * A request with this Idempotency-Key is still running (409 `idempotency_in_flight`, keel
+     * #307, D105): two sends of one create or bulk overlapped. Nothing was written by this one.
+     * Wait `retryAfter` seconds (keel sends 1) and send again with the SAME key and body: once
+     * the first has answered, that retry replays its answer. Not a key conflict (see above).
+     */
+    get isIdempotencyInFlight(): boolean;
     /**
      * The id is already taken (409 `id_conflict`): a create with an id that exists
      * (keel D39), or a PUT whose id belongs to another world (D70). Retrying will not
@@ -2549,9 +2556,12 @@ declare class OwV2Client {
     /** GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields. */
     get(type: ElementType | string, id: string, opts?: Pick<ListParams, 'expand' | 'fields'>): Promise<OwElement>;
     /**
-     * POST /{type}/ -- create one element, minting a UUIDv7 id on the client when you leave id out.
-     * The client-side id makes a retry carrying the same Idempotency-Key safe: it rewrites
-     * the same element instead of creating a second one. You may still supply your own id.
+     * POST /{type}/ -- create one element, minting an id on the client when you leave id out.
+     * With an `idempotencyKey`, the minted id is derived from the key (a UUIDv5, the same one the
+     * Python package mints), so a retry with the same key and element sends the same body and keel
+     * replays its first answer: nothing is written twice, and the stored 201 comes back. Without a
+     * key, a fresh UUIDv7. You may still supply your own id. A new create meant to write again
+     * (an undo that re-creates) needs a new key, or none: within 24 h a reused key only replays.
      * `name` is the one required field, and required means the key is present: `''` and
      * `null` are accepted and stored as `''` (nameless Markers exist).
      */

package/dist/index.js

@@ -1,3 +1,61 @@
+// src/v2/keyed-id.ts
+var KEYED_IDS = "0199b6a0-6f0e-7c2a-9d1e-3b5c7a8e4f21";
+function sha1(msg) {
+  const ml = msg.length;
+  const total = (ml + 8 >> 6) + 1 << 6;
+  const buf = new Uint8Array(total);
+  buf.set(msg);
+  buf[ml] = 128;
+  const bits = ml * 8;
+  const view = new DataView(buf.buffer);
+  view.setUint32(total - 8, Math.floor(bits / 2 ** 32));
+  view.setUint32(total - 4, bits >>> 0);
+  let h0 = 1732584193, h1 = 4023233417, h2 = 2562383102, h3 = 271733878, h4 = 3285377520;
+  const w = new Uint32Array(80);
+  for (let off = 0; off < total; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + i * 4);
+    for (let i = 16; i < 80; i++) {
+      const x = w[i - 3] ^ w[i - 8] ^ w[i - 14] ^ w[i - 16];
+      w[i] = x << 1 | x >>> 31;
+    }
+    let a = h0, b = h1, c = h2, d = h3, e = h4;
+    for (let i = 0; i < 80; i++) {
+      const [f, k] = i < 20 ? [b & c | ~b & d, 1518500249] : i < 40 ? [b ^ c ^ d, 1859775393] : i < 60 ? [b & c | b & d | c & d, 2400959708] : [b ^ c ^ d, 3395469782];
+      const t = (a << 5 | a >>> 27) + f + e + k + w[i] >>> 0;
+      e = d;
+      d = c;
+      c = b << 30 | b >>> 2;
+      b = a;
+      a = t;
+    }
+    h0 = h0 + a >>> 0;
+    h1 = h1 + b >>> 0;
+    h2 = h2 + c >>> 0;
+    h3 = h3 + d >>> 0;
+    h4 = h4 + e >>> 0;
+  }
+  const out = new Uint8Array(20);
+  const ov = new DataView(out.buffer);
+  [h0, h1, h2, h3, h4].forEach((h, i) => ov.setUint32(i * 4, h));
+  return out;
+}
+var hexBytes = (hex) => Uint8Array.from(hex.replace(/-/g, "").match(/../g).map((b) => parseInt(b, 16)));
+function uuid5(ns, name) {
+  const nameBytes = new TextEncoder().encode(name);
+  const input = new Uint8Array(16 + nameBytes.length);
+  input.set(hexBytes(ns));
+  input.set(nameBytes, 16);
+  const b = sha1(input).slice(0, 16);
+  b[6] = b[6] & 15 | 80;
+  b[8] = b[8] & 63 | 128;
+  const h = [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+function keyedId(idempotencyKey, index) {
+  return uuid5(KEYED_IDS, `${idempotencyKey}
+${index}`);
+}
+
 // src/v2/errors.ts
 var OwApiError = class extends Error {
   constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
@@ -26,6 +84,15 @@ var OwApiError = class extends Error {
   get isIdempotencyConflict() {
     return this.status === 409 && this.code === "idempotency_error";
   }
+  /**
+   * A request with this Idempotency-Key is still running (409 `idempotency_in_flight`, keel
+   * #307, D105): two sends of one create or bulk overlapped. Nothing was written by this one.
+   * Wait `retryAfter` seconds (keel sends 1) and send again with the SAME key and body: once
+   * the first has answered, that retry replays its answer. Not a key conflict (see above).
+   */
+  get isIdempotencyInFlight() {
+    return this.status === 409 && this.code === "idempotency_in_flight";
+  }
   /**
    * The id is already taken (409 `id_conflict`): a create with an id that exists
    * (keel D39), or a PUT whose id belongs to another world (D70). Retrying will not
@@ -265,16 +332,19 @@ var OwV2Client = class {
     return this.request("GET", `/${type}/${id}/`, { query });
   }
   /**
-   * POST /{type}/ -- create one element, minting a UUIDv7 id on the client when you leave id out.
-   * The client-side id makes a retry carrying the same Idempotency-Key safe: it rewrites
-   * the same element instead of creating a second one. You may still supply your own id.
+   * POST /{type}/ -- create one element, minting an id on the client when you leave id out.
+   * With an `idempotencyKey`, the minted id is derived from the key (a UUIDv5, the same one the
+   * Python package mints), so a retry with the same key and element sends the same body and keel
+   * replays its first answer: nothing is written twice, and the stored 201 comes back. Without a
+   * key, a fresh UUIDv7. You may still supply your own id. A new create meant to write again
+   * (an undo that re-creates) needs a new key, or none: within 24 h a reused key only replays.
    * `name` is the one required field, and required means the key is present: `''` and
    * `null` are accepted and stored as `''` (nameless Markers exist).
    */
   async create(type, element, opts = {}) {
     const body = sanitizePayload(element);
     if (body.id === void 0 || body.id === null || body.id === "") {
-      body.id = mintUuid();
+      body.id = opts.idempotencyKey ? keyedId(opts.idempotencyKey, 0) : mintUuid();
     }
     return this.request("POST", `/${type}/`, {
       write: true,

package/package.json

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