@onlyworlds/sdk 4.2.0 → 4.4.0

package/AGENTS.md

@@ -37,7 +37,18 @@ 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.
+- `created_by` rides every element read: the id of the membership that created it, `null` for
+  the world's owner and for anything made before memberships existed. It is read-only; a write
+  body that carries it has it dropped, never an error. A **contributor** can change only what
+  they created: anything else is 403 `not_author` (`err.isNotAuthor`; retrying will not help).
+  `/bulk` reports it per slot, not as a throw.
 - 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,64 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
-## [4.2.0] — staged 2026-09-28, not yet published
+## [4.4.0] — 2026-10-04 (staged, not published)
+
+Membership, as far as the server has shipped it: who created an element, and the refusal a
+contributor meets on someone else's. Additive; nothing is removed or narrows.
+
+### Added
+- **`created_by`** on `OwElementBase` (so on every element type): `string | null`, the id of the
+  membership that created the element, `null` for the world's owner and for anything made
+  before memberships existed (keel D72 phase 2, live 2026-09-28; keel spec §4). Read-only. The
+  schema does not carry it (like `created_at` it is server bookkeeping), so the generator adds
+  it to the wire base under the declared mapping. A write body that carries it has it dropped
+  by the server, so the client does not strip it and a read body still round-trips.
+- **`OwApiError.isNotAuthor`**: 403 `not_author`, a contributor changing, replacing, relinking
+  or deleting an element someone else created. `/bulk` answers 200 and reports it in the item
+  slot, so check the slot (documented on `OwBulkItemResult`).
+
+### Fixed
+- **`FIELD_SCHEMA` no longer marks `marker.map/zone/x/y/order` and `pin.map/element_type/element_id/x/y`
+  as `required: true`.** The wire requires `name` and nothing else (rulings.yaml `nullable-by-default`,
+  Captain 2026-07-28; keel's OpenAPI write schemas say `required: [name]`), but the schema files still
+  list those fields and the generator copied the lists, so a form built from the table demanded
+  coordinates the server never did. Found by comparing the SDK with keel's OpenAPI document (the
+  new `verify-sdk-wire` gate in Assembly). **If you read `required` from this table, marker and pin
+  fields now read as optional**, which is what the server accepts. The generator notes the lists it
+  ignores on every run and says when canonical stops carrying them.
+
+### Not yet
+- `me()` and `members()` wait for the server routes (keel's M2b). Nothing in this release
+  guesses at their names.
+
+## [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/SCHEMA.md

@@ -6,7 +6,7 @@ GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `pyth
 Written for both humans and AI agents reading this package locally.
 
 **The shape rules** (v2 wire dialect): every element carries `id` (UUID), `name`, optional
-`description`/`supertype`/`subtype`/`image_url`, server-managed `type`/`created_at`/`updated_at`/`change_seq`,
+`description`/`supertype`/`subtype`/`image_url`, server-managed `type`/`created_at`/`updated_at`/`change_seq`/`created_by`,
 and namespaced extension fields (`x_*` etc.) returned verbatim. Link fields use ONE bare
 name in both read and write (no `_ids` suffix). Single links are `UUID | null`; multi links
 are `UUID[]`. **Links are owned one-way**: the type listed below owns the field (e.g.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /** Every element carries these. The extension index signature admits namespaced
  *  pass-through fields (atlas_* / shadow_* / x_*) returned verbatim by the server.
  *  Derived from base_properties.yaml: `World` is dropped (the API rejects it in
- *  bodies -- the key determines the world) and the four server-managed fields are
+ *  bodies -- the key determines the world) and the five server-managed fields are
  *  added, since they ride every wire body and appear in no element YAML. */
 interface OwElementBase {
     /** Element type slug (server-managed, read-only). */
@@ -24,6 +24,8 @@ interface OwElementBase {
     updated_at?: string;
     /** Per-world change cursor, stamped on every write (server-managed, read-only). */
     change_seq?: number;
+    /** The membership that created this element (server-managed, read-only); null for the world's owner and for anything created before memberships existed. */
+    created_by?: string | null;
     /** Namespaced extension fields (atlas_* / shadow_* / x_*), returned verbatim. */
     [ext: string]: unknown;
 }
@@ -1100,27 +1102,22 @@ declare const FIELD_SCHEMA: {
         readonly map: {
             readonly type: "single_link";
             readonly target: "map";
-            readonly required: true;
         };
         readonly zone: {
             readonly type: "single_link";
             readonly target: "zone";
-            readonly required: true;
         };
         readonly x: {
             readonly type: "integer";
-            readonly required: true;
         };
         readonly y: {
             readonly type: "integer";
-            readonly required: true;
         };
         readonly z: {
             readonly type: "integer";
         };
         readonly order: {
             readonly type: "integer";
-            readonly required: true;
         };
     };
     readonly narrative: {
@@ -1407,24 +1404,19 @@ declare const FIELD_SCHEMA: {
         readonly map: {
             readonly type: "single_link";
             readonly target: "map";
-            readonly required: true;
         };
         readonly element_type: {
             readonly type: "text";
-            readonly required: true;
         };
         readonly element_id: {
             readonly type: "single_link";
             readonly target: "any";
-            readonly required: true;
         };
         readonly x: {
             readonly type: "integer";
-            readonly required: true;
         };
         readonly y: {
             readonly type: "integer";
-            readonly required: true;
         };
         readonly z: {
             readonly type: "integer";
@@ -1918,6 +1910,8 @@ interface OwBulkItem {
  * One slot of a /bulk response. WIRE-CORRECTED (fixtures P2a/P2c): `status` is
  * the NUMERIC HTTP status of that slot (201/400/...), success slots echo
  * created_at/updated_at, error slots carry an OwErrorBody under `error`.
+ * A contributor's write on someone else's element fails in its slot as
+ * `{status: 403, error: {code: 'not_author'}}` (keel D72), never as a thrown error.
  */
 interface OwBulkItemResult {
     status: number;
@@ -2014,12 +2008,41 @@ 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;
+    /**
+     * A contributor tried to change, replace, relink or delete an element someone else
+     * created (403 `not_author`, keel D72 membership phase 2). Retrying will not help; the
+     * element is not theirs. `/bulk` never throws for this: it answers 200 with a per-item
+     * slot `{status: 403, error: {code: 'not_author'}}`. Owners and co-builders never see it.
+     */
+    get isNotAuthor(): boolean;
 }
 /** Network-level failure (fetch rejected) -- no envelope to parse. */
 declare class OwNetworkError extends Error {
@@ -2029,7 +2052,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,35 @@ 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";
+  }
+  /**
+   * A contributor tried to change, replace, relink or delete an element someone else
+   * created (403 `not_author`, keel D72 membership phase 2). Retrying will not help; the
+   * element is not theirs. `/bulk` never throws for this: it answers 200 with a per-item
+   * slot `{status: 403, error: {code: 'not_author'}}`. Owners and co-builders never see it.
+   */
+  get isNotAuthor() {
+    return this.status === 403 && this.code === "not_author";
   }
 };
 var OwNetworkError = class extends Error {
@@ -29,7 +56,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 +64,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 +84,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
@@ -819,12 +855,12 @@ var FIELD_SCHEMA = {
     subtype: { type: "text", required: false },
     image_url: { type: "text", required: false },
     // Details
-    map: { type: "single_link", target: "map", required: true },
-    zone: { type: "single_link", target: "zone", required: true },
-    x: { type: "integer", required: true },
-    y: { type: "integer", required: true },
+    map: { type: "single_link", target: "map" },
+    zone: { type: "single_link", target: "zone" },
+    x: { type: "integer" },
+    y: { type: "integer" },
     z: { type: "integer" },
-    order: { type: "integer", required: true }
+    order: { type: "integer" }
   },
   narrative: {
     // Base fields (shared by all elements)
@@ -917,11 +953,11 @@ var FIELD_SCHEMA = {
     subtype: { type: "text", required: false },
     image_url: { type: "text", required: false },
     // Details
-    map: { type: "single_link", target: "map", required: true },
-    element_type: { type: "text", required: true },
-    element_id: { type: "single_link", target: "any", required: true },
-    x: { type: "integer", required: true },
-    y: { type: "integer", required: true },
+    map: { type: "single_link", target: "map" },
+    element_type: { type: "text" },
+    element_id: { type: "single_link", target: "any" },
+    x: { type: "integer" },
+    y: { type: "integer" },
     z: { type: "integer" }
   },
   relation: {

package/package.json

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