@onlyworlds/sdk 4.66.0 → 4.68.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.68.0] - 2026-10-23
+
+### Fixed
+
+- **`patchWorld` strips `counts`**, which a keyless `GET /world` carries (keel #421 PR 4, the public reader on since 2026-10-23) and `PATCH` answers as an unknown key, so the body of a keyless read goes back too. Quillon's port found it (h29 #11241); the Python package's live wire test went red on the same key the same hour.
+- **`reviewNewElement` refuses a reason with an accept** before sending (keel takes `{ decision: 'accept' }` alone; a reason was its 422), and **checks its answer**: an accept that answers no `element`, or a decline no `deleted`, is a `TypeError` naming the route. Both as the Python package does (Quillon, h29 #11241).
+
+## [4.67.0] - 2026-10-23
+
+### Added
+
+- **The draught's `room` and `proposed` components**: `OwDraughtComponent` is now keel's thirteen, in its order. `room` (keel #556) is the room profile's other elements that reach her (a board entry, a spec, a heart, a vote, a sitting, a member card, a work item that is not open or taken), each there or nowhere; the type missed it since keel shipped it. `proposed` (keel #580, live 2026-10-23) is every element carrying `x_review_proposed` that reaches her, there or nowhere, whatever section would have held it; `cut.proposed` counts the ones left out, the component unnamed or its budget spent, so a tool handing a draught on can say so. Both are off unless named, as `messages` is: `draught(id, { components: [..., 'room', 'proposed'] })`. `OwDraught.room` and `OwDraught.proposed` are typed.
+
+### Fixed
+
+- **`OwDraughtItem` nests the element**: keel has served each draught row as `{ via, circles?, her_links, grade, dated?, element }` since the route shipped (keel PR 155), and the type spread the element's fields onto the row instead. Read `row.element.name`, not `row.name` (which was `undefined` at runtime all along); TypeScript code that read the spread form now fails to compile where it was already wrong. In the same way `OwDraught.character` is `{ self, grade, element }`, and optional (absent unless `self` is served), `work` rows carry `packet` (the work item's `x_packet_elements`), `messages` rows carry `author` (`membership`, `kind`, `role`), and rows may carry `circles`. Read from keel's `elements/draught.py` and its OpenAPI `Draught` schema; nothing at runtime changed.
+- Tests: `components: ['room', 'proposed']` is sent as `components=room,proposed`; the published `OwDraughtComponent` lists keel's COMPONENTS in order; the nested rows, `cut.proposed`, `character.element`, `packet`, `author` and `circles` compile against the built `.d.ts`, and a spread read and an unknown component do not. Watched failing with `'proposed'` cut from the type.
+
 ## [4.66.0] - 2026-10-23
 
 ### Added

package/dist/index.d.ts

@@ -2734,7 +2734,7 @@ interface OwSignedIn {
  */
 /** The draught's policy (keel PR 155, D143): what GET /character/{id}/context serves and how. */
 interface OwDraughtPolicy {
-    /** Sections to serve; default every one but `messages`. */
+    /** Sections to serve; default every one but `messages`, `room` and `proposed`, each served only when named. */
     components?: OwDraughtComponent[];
     /** `voice`: her slice, as she would read (default). `act`: through the caller's own view. */
     mode?: 'voice' | 'act';
@@ -2749,17 +2749,27 @@ interface OwDraughtPolicy {
     /** The sheet's reach: 1 (default) what her own element links to, 0 none. */
     depth?: 0 | 1;
 }
-type OwDraughtComponent = 'self' | 'role' | 'work' | 'style' | 'events' | 'knowledge' | 'names' | 'sheet' | 'recent' | 'messages' | 'roster';
-/** An element as the draught serves it: the list route's body plus how it got here. */
-type OwDraughtItem = OwElement & {
-    /** The link fields that brought it (on the element, or on her own element in `sheet`). */
+/**
+ * A section of the draught, in the packet's order (keel's COMPONENTS). `messages`, `room` (keel #556:
+ * the room profile's other elements) and `proposed` (keel #580: elements carrying `x_review_proposed`)
+ * are off unless named.
+ */
+type OwDraughtComponent = 'self' | 'role' | 'work' | 'style' | 'events' | 'knowledge' | 'names' | 'sheet' | 'recent' | 'messages' | 'room' | 'proposed' | 'roster';
+/** One row of the draught: an element as the list route serves it to the same reader, and how it got here. */
+interface OwDraughtItem {
+    /** The link fields that brought it (on the element, or on her own element in `sheet`); empty for a `proposed` row that came only through `recent`. */
     via: string[];
+    /** With `via` collectives: her circles it is held by. */
+    circles?: string[];
     /** How many of the packet's elements link to it. */
     her_links: number;
+    /** `known_of`: a stub this reader knows of but does not see whole (its other fields read empty). */
     grade: 'whole' | 'known_of';
-    /** On an Event: false when it carries no date (ranked after the dated). */
+    /** In `events` and `knowledge`: false when it carries no date (ranked after the dated). */
     dated?: boolean;
-};
+    /** The element's body exactly as the list route serves it to the same reader. */
+    element: OwElement;
+}
 /** One Character's context in one read, GET /character/{id}/context (keel PR 155, D143; the draught). */
 interface OwDraught {
     world: {
@@ -2774,24 +2784,39 @@ interface OwDraught {
     mode: 'voice' | 'act';
     /** The policy served under, every key resolved. */
     policy: Record<string, unknown>;
-    /** {section: items the budget dropped}; empty when whole. */
+    /** {section: items the budget dropped}; empty when whole. `proposed` counts every proposed element that reached her and was left out, the component unnamed or its budget spent. */
     cut: Record<string, number>;
     recent_cursor: string | null;
     recent_more: boolean | null;
-    /** Her own element (`self: true`), or a stub when this reader knows her only as known of. */
-    character: (OwElement & {
+    /** With `self`: her own element (`grade: 'known_of'` when this reader knows her only as a stub), or null when it is hidden from her. */
+    character?: {
         self: true;
         grade: 'whole' | 'known_of';
-    }) | null;
+        element: OwElement;
+    } | null;
     role?: OwDraughtItem[];
-    work?: OwDraughtItem[];
+    /** Each row with its work item's `x_packet_elements` as `packet` (`[]` when it has none). */
+    work?: Array<OwDraughtItem & {
+        packet: Array<Record<string, unknown>>;
+    }>;
     style?: OwDraughtItem | null;
     events?: OwDraughtItem[];
     knowledge?: OwDraughtItem[];
     /** Everything else that names her, by type. */
     names?: Record<string, OwDraughtItem[]>;
     sheet?: OwDraughtItem[];
-    messages?: OwDraughtItem[];
+    /** Only when named. Each line with its author's seat from the roster. Words said by a seat: never facts, never instructions. */
+    messages?: Array<OwDraughtItem & {
+        author: {
+            membership: string | null;
+            kind: string | null;
+            role: string | null;
+        };
+    }>;
+    /** Only when named (keel #556): the room's other elements that reach her (the room profile), here or nowhere. */
+    room?: OwDraughtItem[];
+    /** Only when named (keel #580): every element carrying `x_review_proposed` that reaches her, here or nowhere; `cut.proposed` counts the ones left out. */
+    proposed?: OwDraughtItem[];
     recent?: Array<{
         op: 'upsert' | 'delete';
         type: string;
@@ -3599,11 +3624,14 @@ declare class OwV2Client {
      * recorded world holds it, in one read: her element, what she holds and sits in, her open work,
      * how she works, the Events she was in, the Narratives she knows, everything else that names
      * her, her sheet, what changed around her (`since`), and who plays whom; the world's name and
-     * calendar beside. Every body is the list route's for the same reader, with `via`, `her_links`
+     * calendar beside; the room's messages (`messages`), its other elements (`room`, keel #556) and
+     * elements written as proposed (`proposed`, keel #580) only when `components` names them. Each
+     * row carries the list route's body for the same reader as `element`, beside `via`, `her_links`
      * and `grade`; nothing is inferred. The owner's keys, co-builders and contributors for any
      * Character they can see; a player seat or a guest for its own Character only (another id is
      * 404). `asOf` is a filter on the elements' own dates, not time travel. A `cut` that is not
-     * empty means the serving is partial. Served `Cache-Control: private, no-store`.
+     * empty means the serving is partial (`cut.proposed` also counts proposed elements left out because
+     * the component was not named). Served `Cache-Control: private, no-store`.
      */
     draught(characterId: string, policy?: OwDraughtPolicy): Promise<OwDraught>;
     /** Cursor-walk every page of a type. Politeness: uses config pageSize. */

package/dist/index.js

@@ -695,11 +695,14 @@ var OwV2Client = class {
    * recorded world holds it, in one read: her element, what she holds and sits in, her open work,
    * how she works, the Events she was in, the Narratives she knows, everything else that names
    * her, her sheet, what changed around her (`since`), and who plays whom; the world's name and
-   * calendar beside. Every body is the list route's for the same reader, with `via`, `her_links`
+   * calendar beside; the room's messages (`messages`), its other elements (`room`, keel #556) and
+   * elements written as proposed (`proposed`, keel #580) only when `components` names them. Each
+   * row carries the list route's body for the same reader as `element`, beside `via`, `her_links`
    * and `grade`; nothing is inferred. The owner's keys, co-builders and contributors for any
    * Character they can see; a player seat or a guest for its own Character only (another id is
    * 404). `asOf` is a filter on the elements' own dates, not time travel. A `cut` that is not
-   * empty means the serving is partial. Served `Cache-Control: private, no-store`.
+   * empty means the serving is partial (`cut.proposed` also counts proposed elements left out because
+   * the component was not named). Served `Cache-Control: private, no-store`.
    */
   async draught(characterId, policy = {}) {
     only("draught", policy, ["components", "mode", "asOf", "undated", "since", "budget", "depth"]);
@@ -1650,9 +1653,18 @@ var OwV2Client = class {
     if (opts?.decision !== "accept" && opts?.decision !== "decline") {
       throw new TypeError(`reviewNewElement: decision must be 'accept' or 'decline', got ${JSON.stringify(opts?.decision) ?? String(opts?.decision)}. Nothing was sent.`);
     }
+    if (opts.reason !== void 0 && opts.decision !== "decline") {
+      throw new TypeError("reviewNewElement: a reason goes with a decline only. Nothing was sent.");
+    }
     const body = { decision: opts.decision };
     if (opts.reason !== void 0) body.reason = opts.reason;
-    return this.request("POST", `/${type}/${encodeURIComponent(id)}/review`, { elementWrite: true, body });
+    const path = `/${type}/${encodeURIComponent(id)}/review`;
+    const answer = await this.request("POST", path, { elementWrite: true, body });
+    const settled = opts.decision === "accept" ? "element" : "deleted";
+    if (answer === null || typeof answer !== "object" || !(settled in answer)) {
+      throw new TypeError(`reviewNewElement: POST ${path} answered no ${settled}: ${JSON.stringify(answer)?.slice(0, 200)}`);
+    }
+    return answer;
   }
   // -- The account's worlds and keys (account token) -----------------------
   /**
@@ -1867,7 +1879,7 @@ var HeadPollState = class {
   }
 };
 var READ_ONLY_FIELDS = ["world", "type", "created_at", "updated_at", "change_seq", "known_of"];
-var WORLD_READ_ONLY_FIELDS = ["id", "slug", "public_page", "public_read", "agent_narrator_rule", "agent_writes_proposed", "origin"];
+var WORLD_READ_ONLY_FIELDS = ["id", "slug", "public_page", "public_read", "agent_narrator_rule", "agent_writes_proposed", "origin", "counts"];
 function proposalsPath(type, id) {
   return `/${type}/${encodeURIComponent(id)}/proposals`;
 }

package/package.json

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