@onlyworlds/sdk 4.2.0 → 4.3.0

package/AGENTS.md

@@ -37,7 +37,13 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   A v4 or v7 id you supply is accepted. **Never sort elements by id**: worlds mix v7, v4
   and legacy `06x…` ids (nibble 7 too, but seconds-first). For creation order use
   `created_at`; `change_seq` is last-write order, not creation.
-  A PUT or bulk item whose id belongs to **another world** returns 409 `id_conflict`.
+  A create with an id that already exists, or a PUT whose id belongs to **another world**,
+  returns 409 `id_conflict` (`err.isIdConflict`; retrying won't help). `/bulk` never throws:
+  check each slot for `status: 409` with `error.code: 'id_conflict'`. A different 409, `idempotency_error`, means an
+  Idempotency-Key was reused with another body (`err.isIdempotencyConflict`).
+- Under load keel answers 503 `server_busy` with `Retry-After` (`err.isBusy`, `err.retryAfter`
+  in seconds). The client does not retry for you; back off and retry yourself. Works the same
+  in browsers.
 - A string holding an unpaired surrogate (text cut mid-emoji) is a 422 naming the field.
   Slice strings by code point, not by UTF-16 unit.
 - Colour carries the element's FAMILY (`elementColor(type, mode)`); the icon

package/CHANGELOG.md

@@ -5,7 +5,34 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
-## [4.2.0] — staged 2026-09-28, not yet published
+## [4.3.0] — 2026-09-28
+
+Errors you can act on: the two 409s told apart, and the busy server's `Retry-After`, in Node and
+browsers. One getter narrows (see Fixed); nothing is removed.
+
+### Fixed
+- **`OwApiError.isIdempotencyConflict` no longer claims every 409.** keel sends two: 409
+  `idempotency_error` (a key reused with a different body) and 409 `id_conflict` (the id is
+  taken: a create with an existing id since D39, or a PUT / bulk id held by another world since
+  D70). The getter was true for both, so an id conflict read as a key problem, and retrying with
+  a fresh key could never help. It now matches `idempotency_error` only, and the new
+  **`isIdConflict`** names the other. A caller who relied on the old catch-all for `id_conflict`
+  should switch to `isIdConflict`. A 409 with no code (a proxy, a non-JSON body) now reads
+  false for both. `/bulk` is unaffected: it answers 200 and reports a per-item 409 in the slot.
+
+### Added
+- **`OwApiError.retryAfter`** (seconds, or null) is parsed from `Retry-After`, as a delay or an
+  HTTP date, and **`isBusy`** marks keel's 503 `server_busy` (admission control, keel D71: six
+  requests at once per worker, up to 10 s of queueing, then 503 with `Retry-After: 5`). The client
+  still never retries on its own; it gives callers what they need to back off. A malformed
+  `Retry-After` is null, never "retry now". **Works in browsers too** since keel `4949406`
+  (2026-09-28): every response exposes `Retry-After`, `Idempotent-Replay` and
+  `X-OW-Schema-Version` over CORS (probed from an allowed origin), and keel reports that the
+  admission gate's 503 now carries CORS headers, so a busy server reads as busy, not as
+  `OwNetworkError` (keel's word; the 503 can't be triggered on demand to probe). Six tests; the
+  four core ones watched failing on the previous `errors.ts`.
+
+## [4.2.0] — 2026-09-28
 
 Ids, honest filter docs, and the schema repin. Nothing is removed; no call needs to change.
 

package/dist/index.d.ts

@@ -2014,12 +2014,34 @@ declare class OwApiError extends Error {
     readonly docUrl: string | null;
     /** Raw parsed envelope (or body text when the body wasn't JSON). */
     readonly detail: unknown;
-    constructor(status: number, code: string | null, message: string, docUrl: string | null, detail: unknown, type?: string | null, param?: string | null);
+    /**
+     * Seconds to wait before retrying, from the `Retry-After` header (a delay in
+     * seconds or an HTTP date), else null. keel sends it on 503 `server_busy`
+     * (admission control, D71) and 429 `rate_limited`. This client never retries
+     * on its own; the value is here so callers can back off politely.
+     * Readable in browsers too: keel exposes `Retry-After` over CORS and its
+     * admission gate's 503 carries CORS headers (keel `4949406`, 2026-09-28).
+     */
+    readonly retryAfter: number | null;
+    constructor(status: number, code: string | null, message: string, docUrl: string | null, detail: unknown, type?: string | null, param?: string | null, retryAfter?: number | null);
     get isAuthError(): boolean;
     /** 422s/400s name the offending param/field -- typos error loudly platform-wide. */
     get isValidationError(): boolean;
-    /** Same Idempotency-Key replayed with a different payload. */
+    /**
+     * Same Idempotency-Key replayed with a different payload (409 `idempotency_error`).
+     * Through 4.2.0 this was true for ANY 409, which misread an id conflict as a key
+     * conflict: keel also answers 409 `id_conflict` (see isIdConflict).
+     */
     get isIdempotencyConflict(): 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
+     * help; the id is the problem. `/bulk` never throws for this: it answers 200 with a
+     * per-item slot `{status: 409, error: {code: 'id_conflict'}}` — check the slot.
+     */
+    get isIdConflict(): boolean;
+    /** keel's admission control turned the request away (503 `server_busy`); see retryAfter. */
+    get isBusy(): boolean;
 }
 /** Network-level failure (fetch rejected) -- no envelope to parse. */
 declare class OwNetworkError extends Error {
@@ -2029,7 +2051,7 @@ declare class OwNetworkError extends Error {
 /** Parse a wire envelope into OwApiError parts (exported for the error type-tests). */
 /** Parse the platform ERROR envelope into an OwApiError. (Renamed from parseEnvelope in 4.0 —
  *  distinct from the world-export envelope, which is a different artifact entirely.) */
-declare function parseErrorEnvelope(status: number, body: unknown): OwApiError;
+declare function parseErrorEnvelope(status: number, body: unknown, retryAfter?: number | null): OwApiError;
 /** Build an OwApiError from a non-2xx response, tolerating non-JSON bodies. */
 declare function errorFromResponse(res: Response): Promise<OwApiError>;
 

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/v2/errors.ts
 var OwApiError = class extends Error {
-  constructor(status, code, message, docUrl, detail, type = null, param = null) {
+  constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
     super(message);
     this.name = "OwApiError";
     this.status = status;
@@ -9,6 +9,7 @@ var OwApiError = class extends Error {
     this.param = param;
     this.docUrl = docUrl;
     this.detail = detail;
+    this.retryAfter = retryAfter;
   }
   get isAuthError() {
     return this.code === "invalid_credentials" || this.code === "key_revoked" || this.code === "world_gone";
@@ -17,9 +18,26 @@ var OwApiError = class extends Error {
   get isValidationError() {
     return this.status === 422 || this.status === 400;
   }
-  /** Same Idempotency-Key replayed with a different payload. */
+  /**
+   * Same Idempotency-Key replayed with a different payload (409 `idempotency_error`).
+   * Through 4.2.0 this was true for ANY 409, which misread an id conflict as a key
+   * conflict: keel also answers 409 `id_conflict` (see isIdConflict).
+   */
   get isIdempotencyConflict() {
-    return this.status === 409;
+    return this.status === 409 && this.code === "idempotency_error";
+  }
+  /**
+   * 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
+   * help; the id is the problem. `/bulk` never throws for this: it answers 200 with a
+   * per-item slot `{status: 409, error: {code: 'id_conflict'}}` — check the slot.
+   */
+  get isIdConflict() {
+    return this.status === 409 && this.code === "id_conflict";
+  }
+  /** keel's admission control turned the request away (503 `server_busy`); see retryAfter. */
+  get isBusy() {
+    return this.status === 503 && this.code === "server_busy";
   }
 };
 var OwNetworkError = class extends Error {
@@ -29,7 +47,7 @@ var OwNetworkError = class extends Error {
     this.cause2 = cause;
   }
 };
-function parseErrorEnvelope(status, body) {
+function parseErrorEnvelope(status, body, retryAfter = null) {
   const env = body && typeof body === "object" ? body : {};
   const nested = typeof env.error === "object" && env.error !== null ? env.error : void 0;
   const code = env.code ?? nested?.code ?? (typeof env.error === "string" ? env.error : null) ?? null;
@@ -37,7 +55,16 @@ function parseErrorEnvelope(status, body) {
   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);
+  return new OwApiError(status, code, message, docUrl, body, type, param, retryAfter);
+}
+function parseRetryAfter(value, now = Date.now()) {
+  if (value == null) return null;
+  const v = value.trim();
+  if (/^\d+$/.test(v)) return Number(v);
+  if (!/[A-Za-z]/.test(v)) return null;
+  const when = Date.parse(v);
+  if (Number.isNaN(when)) return null;
+  return Math.max(0, Math.ceil((when - now) / 1e3));
 }
 async function errorFromResponse(res) {
   let body = null;
@@ -48,7 +75,7 @@ async function errorFromResponse(res) {
   } catch {
     body = text || null;
   }
-  return parseErrorEnvelope(res.status, body);
+  return parseErrorEnvelope(res.status, body, parseRetryAfter(res.headers?.get?.("Retry-After") ?? null));
 }
 
 // src/v2/keys.ts

package/package.json

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