@onlyworlds/sdk 4.3.0 → 4.5.0

package/AGENTS.md

@@ -44,6 +44,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - 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,6 +5,54 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.5.0] — 2026-10-04 (staged, not published)
+
+What the staging write probes found on the wire (Python package, 2026-10-04): one new getter, and
+three behaviours the server has always had that no client doc said. Additive; nothing is removed.
+
+### Added
+- **`OwApiError.isOwnerOnly`**: 403 `owner_only`, a contributor attempting a world-level change
+  (`patchWorld`, publishing a show page). Owners and co-builders never see it. keel's OpenAPI
+  document does not name the code yet (Skeld has that to close); the wire returns it.
+
+### Documented
+- **An atomic `/bulk` rollback still returns 201 slots** for the items that would have
+  succeeded, with the ids and timestamps they would have had (keel spec: "counterfactual 201s").
+  After `atomic: true` with `errors: true`, nothing was written. On `bulk()`, `OwBulkItemResult`
+  and the README.
+- **`name` is required as a key only**: `''` and `null` are accepted and stored as `''` (keel
+  ruling 2026-09-28, spec §6; nameless Markers exist). On `create()` and the README.
+
+## [4.4.0] — 2026-10-04
+
+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

package/README.md

@@ -45,6 +45,8 @@ const location = await writer.create('location', {
   name: 'Dragon Peak',
   description: 'A treacherous mountain peak where dragons nest',
 }); // id minted client-side when omitted (retries stay idempotent)
+// name is the one required field, and required means the key is present:
+// '' and null are accepted and stored as '' (nameless Markers exist).
 
 const dragon = await writer.create('creature', {
   name: 'Vorrath the Ember-Scaled',
@@ -84,6 +86,8 @@ if (res.errors) {
   }
 }
 // Pass { atomic: true } for all-or-nothing instead. res.wasReplay flags idempotent replays.
+// After a failed atomic batch NOTHING was written, but the slots that would have succeeded
+// still say 201 (keel's counterfactual 201s): do not record those ids as created.
 ```
 
 ## Sync

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,11 @@ 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.
+ * After an `atomic: true` request with `errors` true NOTHING was written, yet the slots of
+ * the items that would have succeeded still say 201 (keel's "counterfactual 201s"): do not
+ * record their ids as created.
  */
 interface OwBulkItemResult {
     status: number;
@@ -2042,6 +2039,19 @@ declare class OwApiError extends Error {
     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;
+    /**
+     * A contributor tried a world-level change: `patchWorld`, or publishing a show page
+     * (403 `owner_only`, keel D72 membership phase 2). Retrying will not help; only the
+     * owner may. Owners and co-builders never see it.
+     */
+    get isOwnerOnly(): boolean;
 }
 /** Network-level failure (fetch rejected) -- no envelope to parse. */
 declare class OwNetworkError extends Error {
@@ -2125,6 +2135,8 @@ declare class OwV2Client {
      * POST /{type}/ -- create. Mints an RFC 9562 UUIDv7 for element.id when the
      * caller omits one (design ruling D29d) so a retry carrying the same
      * Idempotency-Key is structurally safe. Callers MAY still supply their own id.
+     * `name` is the one required field, and required means the key is present: `''` and
+     * `null` are accepted and stored as `''` (nameless Markers exist; keel ruling 2026-09-28).
      */
     create(type: ElementType | string, element: OwElement | Record<string, unknown>, opts?: {
         idempotencyKey?: string;
@@ -2158,6 +2170,9 @@ declare class OwV2Client {
      * Success slots echo server-authoritative timestamps: set your sync baseline
      * from this response alone. When an idempotencyKey is replayed, the returned
      * response carries wasReplay:true (read from the Idempotent-Replay header).
+     * After an atomic:true request with errors:true NOTHING was written, yet the slots of
+     * the items that would have succeeded still say 201 with the ids and timestamps they
+     * would have had (keel's "counterfactual 201s"): do not record those ids as created.
      */
     bulk(items: OwBulkItem[], opts?: {
         atomic?: boolean;

package/dist/index.js

@@ -39,6 +39,23 @@ var OwApiError = class extends Error {
   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";
+  }
+  /**
+   * A contributor tried a world-level change: `patchWorld`, or publishing a show page
+   * (403 `owner_only`, keel D72 membership phase 2). Retrying will not help; only the
+   * owner may. Owners and co-builders never see it.
+   */
+  get isOwnerOnly() {
+    return this.status === 403 && this.code === "owner_only";
+  }
 };
 var OwNetworkError = class extends Error {
   constructor(message, cause) {
@@ -173,6 +190,8 @@ var OwV2Client = class {
    * POST /{type}/ -- create. Mints an RFC 9562 UUIDv7 for element.id when the
    * caller omits one (design ruling D29d) so a retry carrying the same
    * Idempotency-Key is structurally safe. Callers MAY still supply their own id.
+   * `name` is the one required field, and required means the key is present: `''` and
+   * `null` are accepted and stored as `''` (nameless Markers exist; keel ruling 2026-09-28).
    */
   async create(type, element, opts = {}) {
     const body = sanitizePayload(element);
@@ -222,6 +241,9 @@ var OwV2Client = class {
    * Success slots echo server-authoritative timestamps: set your sync baseline
    * from this response alone. When an idempotencyKey is replayed, the returned
    * response carries wasReplay:true (read from the Idempotent-Replay header).
+   * After an atomic:true request with errors:true NOTHING was written, yet the slots of
+   * the items that would have succeeded still say 201 with the ids and timestamps they
+   * would have had (keel's "counterfactual 201s"): do not record those ids as created.
    */
   async bulk(items, opts = {}) {
     const body = {
@@ -846,12 +868,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)
@@ -944,11 +966,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.3.0",
+  "version": "4.5.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {