@onlyworlds/sdk 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -5,7 +5,25 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
-## [4.4.0] — 2026-10-04 (staged, not published)
+## [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.

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/dist/index.d.ts

@@ -1912,6 +1912,9 @@ interface OwBulkItem {
  * 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;
@@ -2043,6 +2046,12 @@ declare class OwApiError extends Error {
      * 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 {
@@ -2126,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;
@@ -2159,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

@@ -48,6 +48,14 @@ var OwApiError = class extends Error {
   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) {
@@ -182,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);
@@ -231,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 = {

package/package.json

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