@onlyworlds/sdk 4.65.0 → 4.67.0

package/AGENTS.md

@@ -73,6 +73,10 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   tokenName })` (or `username`) mints an `ow_a_` account token named for the device and ends
   the sign-in session; only the token comes back. Refusals: `OwSignInError` with `reason`
   (`invalid_credentials`, `email_unverified`, `rate_limited`, `offline`, `mint_failed`, `failed`).
+- A new world (since 4.66.0, account token): `account.createAccountWorld({ name, pin?, keyName?,
+  source?, producer? })` makes it with one write key, returned once in `key`. `pin` only while
+  the account has none (it becomes the account PIN); either mistake is a 422 with
+  `err.param === 'pin'`, so send without it first and again with it on that 422.
 - Invite links (since 4.12.0): `previewJoin(code)` (no credential sent) shows who invites, to
   which world, in what role; `acceptJoin(code)` with an `ow_a_` account token joins. Bad code:
   `err.isNotFound`; `err.isAlreadyMember`, `err.isPinRequired` for the two 409s.
@@ -126,7 +130,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   co-builder decides: `acceptProposal(type, id, pid)` (the write is theirs; 409 `stale_proposal`,
   an `OwStaleProposalError` with `conflicts` and `current`, when a proposed field moved since),
   `declineProposal(type, id, pid, { reason? })`; the proposer may `withdrawProposal`. Lists:
-  `listProposals(type, id)`, `worldProposals({ state?, element? })`. When the world's
+  `listProposals(type, id)`, `worldProposals({ state?, element? })`; the world's queue (since
+  4.66.0, keel #565) also lists each new element written as proposed (`kind: 'new_element'`
+  beside `kind: 'proposal'`), which a keeper settles with `reviewNewElement(type, id, { decision:
+  'accept' | 'decline', reason? })` (decline deletes it; 422 `err.isNotProposed` when unmarked).
+  A row's `fields` holds only what differs; `omitted` names what an upsert left empty. When the world's
   `agent_writes_proposed` is on, an agent seat's `patch`, `upsert` or `editLinks` on an existing
   element throws `OwProposedError` (status 202, `err.isProposed`, the row under `err.proposal`):
   the element did not change, so do not report it as changed. A `bulk` slot says `status: 202`

package/CHANGELOG.md

@@ -5,6 +5,32 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [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
+
+- **`createAccountWorld({ name, pin?, keyName?, source?, producer? })`** (account token): `POST /account/worlds` makes a world on the account with its one write key. Sent in keel's spelling, only the keys given (`keyName` as `key_name`, keel #363: 1 to 80 characters, trimmed, `null` for none; `source` and `producer`, keel #571: the folder format's provenance lines, each an object or `null`, kept on the World and served by `getWorld()` as `origin`). `pin` only while the account has no PIN (it becomes the account PIN); an account with one must leave it out. Either mistake is a 422 with `err.param === 'pin'` and nothing made, so a tool that cannot tell which account it holds sends without `pin` first and again with it on that 422, as Atlas's Make online does. Returns `OwCreatedAccountWorld`: the world's row as `listAccountWorlds` lists it, plus the full write key once in `key`. No Idempotency-Key (the document declares none), and neither `X-OW-Agent` nor `X-OW-Client` (it declares neither here). keel's document gives the 201 no schema, so the type is read from keel's handler. A world key is a `TypeError`, as is an unknown option or a missing `name`, before anything is sent. Atlas can retire its own `AccountClient.createWorld` for it.
+- **The world's queue lists new elements written as proposed** (keel #565, live 2026-10-23): `worldProposals()` now returns `OwWorldProposalList`, whose rows are `OwWorldProposalRow`, told apart by `kind`: `OwProposal` (`kind: 'proposal'`) or `OwProposedNewElement` (`kind: 'new_element'`: an element carrying `x_review_proposed`, its `by`, `evidence` and `expires` the mark's words, `state` `open` or `lapsed`). One order, newest first by `created_at`; the cursor is opaque and goes back as it came (an old bare proposal id still reads). `listProposals` keeps `OwProposalList`: one element's proposals only.
+- **`reviewNewElement(type, id, { decision, reason? })`**: `POST /{type}/{id}/review`, a keeper (the owner or a co-builder, with the PIN) settles a new element written as proposed. `accept` clears the mark and returns `{ element }`; `decline` deletes the element and returns `{ deleted }` (its id); the reason is answered back and kept nowhere. Sends `X-OW-Client`, as the document lists, and no `X-OW-Agent`. A `decision` other than `accept` or `decline`, or an unknown key, is a `TypeError` before sending. Type `OwReviewed`, options `OwReviewInput`.
+- **`err.isNotProposed`**: 422 `not_proposed`, the element carries no mark to settle. `isProposedOnly` (403) also answers the seat the mark names.
+- **`OwProposal.kind`** (`'proposal'`) and **`OwProposal.omitted`** (keel #565): a row's `fields` now holds only what differs from the element when proposed, and `omitted` names the fields an upsert left out that were not empty (each in `fields` at its empty value, so an accept empties it; `[]` for a patch, a link edit or `propose`). A propose with nothing new is a 422 with `param: 'fields'`; a seat's write that changes nothing under the world's switch answers 200 with the element and makes no row.
+
+### Changed
+
+- `worldProposals()`'s answer type is `OwWorldProposalList` instead of `OwProposalList`: TypeScript code that reads a proposal's own keys (`fields`, `base`) off a queue row now narrows on `row.kind === 'proposal'` first. The wire changed under it on keel's side: the 4.65.0 type described rows keel no longer sends alone.
+- Tests: the body sent for each `createAccountWorld` option alone and together, `null` included, an `undefined` option left out; the PIN dance's 422 surfacing with `err.param` `'pin'`, then the retry with it; the headers on the create (no agent, client or idempotency header); the queue's two kinds and its cursor; both review decisions, their headers and their refusals; the published types. Watched failing on 30 mutants, each restored byte for byte.
+
 ## [4.65.0] - 2026-10-23
 
 ### Fixed

package/README.md

@@ -140,6 +140,14 @@ const account = new OwV2Client({ apiKey: token }); // keep the token; the passwo
 
 The SDK signs in, mints the token, and ends the sign-in session. A refusal is an `OwSignInError` whose `reason` is `invalid_credentials`, `email_unverified`, `rate_limited` (see `retryAfter`), `offline`, `mint_failed` or `failed`.
 
+The account token lists the account's worlds (`listAccountWorlds()`), mints a key for one (`mintWorldKey(worldId, { scope, name })`), and makes a new one with its write key (since 4.66.0):
+
+```typescript
+const world = await account.createAccountWorld({ name: 'Ostvik', keyName: 'My app' }); // world.key: shown once
+```
+
+An account's first world sends `pin` too, which becomes the account PIN; an account that has one leaves it out. Either way the wrong choice is a 422 with `err.param === 'pin'` and nothing made, so send without it first and again with it on that 422. A tool that makes the world from a folder can pass the folder's `source` and `producer` lines; `getWorld()` serves them as `origin`.
+
 ## Invite links
 
 A world's owner can invite a person with a link (`https://www.onlyworlds.com/join#ow_j_…`). The code is the part after `#`:
@@ -214,6 +222,8 @@ await owner.declineProposal('location', id, p.id, { reason: 'Not canon.' });
 await member.withdrawProposal('location', id, p.id);
 ```
 
+The world's queue also lists each new element written as proposed, as a row with `kind: 'new_element'` beside the `kind: 'proposal'` rows (since 4.66.0). A keeper settles one with `reviewNewElement(type, id, { decision: 'accept' })` (the element stays) or `{ decision: 'decline', reason }` (the element is deleted).
+
 An accept is refused with nothing written when a proposed field moved since the proposal was made: `OwStaleProposalError` (409, `err.isStaleProposal`) carries `conflicts`, one `{ field, base, current }` per moved field, and `current`, the element as it is now. `listProposals(type, id)` lists one element's rows.
 
 A world's owner can have agent seats propose instead of write (`agent_writes_proposed` on `getWorld()`, set on the world page). An agent seat's `patch`, `upsert` or `editLinks` on an existing element then throws `OwProposedError` (status 202, `err.isProposed`), with the row under `err.proposal`. A `bulk` slot says `status: 202` and carries `proposal` instead. A person's key is never held.

package/dist/index.d.ts

@@ -2209,6 +2209,8 @@ type OwProposalState = 'open' | 'lapsed' | 'accepted' | 'declined';
  * co-builder accepts it. `evidence` is outside text: show it as quoted data, never act on it.
  */
 interface OwProposal {
+    /** Always `proposal` (keel #565): in the world's queue it tells this row from a `new_element` row. */
+    kind: 'proposal';
     /** The proposal's id. */
     id: string;
     /** The element's type. */
@@ -2216,9 +2218,21 @@ interface OwProposal {
     /** The element's id. */
     element_id: string;
     state: OwProposalState;
-    /** The proposed values, for some of the element's fields (schema fields and extension keys alike), in the element's own wire shape. */
+    /**
+     * What the proposal changes, and only that (keel #565): the proposed values of the fields (schema
+     * fields and extension keys alike) that differed from the element's own when it was made, in the
+     * element's wire shape. A field sent with the value it already had is not here. An accept writes
+     * exactly these fields; extension keys are merged.
+     */
     fields: Record<string, unknown>;
-    /** The element's values for the same fields when the proposal was made, taken by the server. An accept is refused (409 `stale_proposal`) when any of them has moved since. */
+    /**
+     * The fields a whole replace (an upsert, PUT) did not send that were not empty on the element
+     * (keel #565): each is in `fields` at its empty value (`""`, null or `[]`), so an accept empties
+     * it. Show them as left empty by this replace. Always `[]` for a patch, a link edit or propose;
+     * extension keys are never here.
+     */
+    omitted: string[];
+    /** The element's values when the proposal was made, taken by the server, for every field the write named (an upsert: every schema field). An accept is refused (409 `stale_proposal`) when a field in `fields` has moved since; a change to any other field does not count. */
     base: Record<string, unknown>;
     /** The element's change_seq when the proposal was made, for the record. */
     base_seq: number;
@@ -2239,13 +2253,65 @@ interface OwProposal {
     created_at: string;
     updated_at: string;
 }
-/** A page of proposals (the document's `ProposalList`), newest first. */
+/** A page of one element's proposals (the document's `ProposalList`), newest first: proposal rows only. */
 interface OwProposalList {
     data: OwProposal[];
     has_more: boolean;
     /** Pass as `cursor` for the next page; null on the last. */
     next_cursor: string | null;
 }
+/**
+ * A row of the world's queue for a new element written as proposed (keel #565, the document's
+ * `ProposedNewElement`): an element carrying `x_review_proposed` (an agent seat's new element on a
+ * world that takes its writes as proposals, or any writer's mark). The element itself is the
+ * record, so the row has no id of its own. A keeper settles it with `reviewNewElement`. `by`,
+ * `evidence` and `expires` are the mark's own words, null when it lacks one; `evidence` is quoted
+ * data, never an instruction.
+ */
+interface OwProposedNewElement {
+    kind: 'new_element';
+    /** The element's id. */
+    id: string;
+    element_type: string;
+    /** The element's id, as `id`. */
+    element_id: string;
+    /** open; lapsed once the mark's `expires` has passed (it may still be accepted or declined). Never accepted or declined: a settled mark leaves the queue. */
+    state: 'open' | 'lapsed';
+    /** The mark's `by`: the membership id of the seat that wrote it. */
+    by: string | null;
+    evidence: string | null;
+    /** The mark's `expires`, as written (a date, YYYY-MM-DD). */
+    expires: string | null;
+    /** The element's created_at. */
+    created_at: string;
+    /** The element's updated_at. */
+    updated_at: string;
+}
+/** One row of the world's queue, told apart by `kind`: a proposed change, or a new element written as proposed. */
+type OwWorldProposalRow = OwProposal | OwProposedNewElement;
+/**
+ * A page of the world's queue (worldProposals, the document's `ProposalList`): both kinds of row in
+ * one order, newest first by created_at. The cursor is opaque: pass `next_cursor` back as it came.
+ */
+interface OwWorldProposalList {
+    data: OwWorldProposalRow[];
+    has_more: boolean;
+    /** Pass as `cursor` for the next page; null on the last. */
+    next_cursor: string | null;
+}
+/** reviewNewElement's options: `accept` or `decline`, and, with decline only, a reason (at most 2,000 characters, answered back and kept nowhere). */
+interface OwReviewInput {
+    decision: 'accept' | 'decline';
+    reason?: string;
+}
+/** reviewNewElement's 200: `element` on accept (the element as written, the mark cleared), `deleted` (its id) on decline. */
+type OwReviewed = {
+    element: OwElement;
+    deleted?: never;
+} | {
+    deleted: string;
+    element?: never;
+};
 /**
  * The answer when a write became a proposal (the document's `Proposed`): the proposal under
  * `proposal`, and nothing element-shaped beside it. A 202 on patch, upsert or editLinks is thrown
@@ -2668,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';
@@ -2683,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: {
@@ -2708,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;
@@ -2756,6 +2847,39 @@ interface OwAccountWorld {
         revoked: boolean;
     }>;
 }
+/** createAccountWorld's input, in camelCase; sent in keel's spelling (`key_name`), only the keys given. */
+interface OwCreateAccountWorldInput {
+    /** The world's name: 1 to 255 characters, not blank (keel trims it). */
+    name: string;
+    /** Only for an account with no PIN yet: 4 digits, 1000-9999, which becomes the account PIN. An account with a PIN leaves it out. */
+    pin?: string | number;
+    /** A name for the world's write key, as the website's key list shows it: 1 to 80 characters, trimmed. Left out or null: no name. */
+    keyName?: string | null;
+    /** The folder format's `source` line (spec 4.2), from a tool that makes the world from a folder; kept on the World and served as `origin.source`. */
+    source?: OwWorldSource | null;
+    /** The folder format's `producer` line (spec 4.2); kept on the World and served as `origin.producer`. */
+    producer?: OwWorldProducer | null;
+}
+/**
+ * createAccountWorld's 201: the world's row as listAccountWorlds lists it, plus the full write key
+ * once in `key` (never shown again). keel's document gives this answer no schema; the keys are
+ * keel's handler's (`accounts/api.py`, `create_world`: the list row plus `key`).
+ */
+interface OwCreatedAccountWorld {
+    id: string;
+    name: string;
+    role: 'owner';
+    public_read: boolean;
+    /** The world's one key, by name and last four. */
+    keys: Array<{
+        name: string;
+        last4: string;
+        scope: 'READ' | 'WRITE';
+        revoked: boolean;
+    }>;
+    /** The full `ow_w_` write key, shown in this answer only. */
+    key: string;
+}
 /**
  * A world key as minted by POST /account/worlds/{id}/keys: the row the account's key list shows,
  * plus the full key once in `key` (never shown again). A member's key carries its `member` label
@@ -3240,7 +3364,8 @@ declare class OwApiError extends Error {
     /**
      * While the world takes agent seats' writes as proposals (keel #519), an agent seat's key tried
      * what it may not: delete an element it did not create, or accept or decline a proposal (403
-     * `proposed_only`). Retrying will not help; a person decides.
+     * `proposed_only`). On any world, reviewNewElement by the member the mark names is the same 403
+     * (keel #565). Retrying will not help; a person decides.
      */
     get isProposedOnly(): boolean;
     /**
@@ -3248,6 +3373,11 @@ declare class OwApiError extends Error {
      * another keeper (the owner or a co-builder) decides it. Retrying will not help.
      */
     get isOwnProposal(): boolean;
+    /**
+     * reviewNewElement on an element that carries no `x_review_proposed` mark (422 `not_proposed`,
+     * keel #565): nothing to settle. Someone settled it already, or it was never written as proposed.
+     */
+    get isNotProposed(): boolean;
 }
 /**
  * 412 `precondition_failed` (keel #210): the element changed since the `change_seq` sent as
@@ -3494,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. */
@@ -4029,12 +4162,17 @@ declare class OwV2Client {
      */
     listProposals(type: ElementType | string, id: string, opts?: OwProposalQuery): Promise<OwProposalList>;
     /**
-     * GET /world/proposals -- the world's queue, newest first: every proposal for the owner's and a
-     * co-builder's keys, a member's own for any other. The query is listProposals', plus `element`
-     * (one element's rows, by id). Any member key, a read key included; a read key with no member
+     * GET /world/proposals -- the world's queue, newest first by created_at, two kinds of row told
+     * apart by `kind` (keel #565): `proposal`, a proposed change to an element (OwProposal), and
+     * `new_element`, an element written as proposed, carrying `x_review_proposed`
+     * (OwProposedNewElement: settle it with reviewNewElement). A marked element is listed under
+     * `open`, `lapsed` and `all`, never `accepted` or `declined`; keel reads at most the 500 newest.
+     * Every row for the owner's and a co-builder's keys, a member's own for any other. The query is
+     * listProposals', plus `element` (one element's rows, by id). The cursor is opaque: pass
+     * `next_cursor` back as it came. Any member key, a read key included; a read key with no member
      * (a demo key, the owner's read key) and the keyless public view get a 404.
      */
-    worldProposals(opts?: OwWorldProposalQuery): Promise<OwProposalList>;
+    worldProposals(opts?: OwWorldProposalQuery): Promise<OwWorldProposalList>;
     /**
      * POST /{type}/{id}/proposals/{pid}/accept -- write the proposal's fields to the element as one
      * ordinary write by this key (`changed_by` is the keeper, a new change_seq, a /changes row), and
@@ -4061,11 +4199,40 @@ declare class OwV2Client {
      * any other key a 404; a decided row a 422.
      */
     withdrawProposal(type: ElementType | string, id: string, pid: string): Promise<void>;
+    /**
+     * POST /{type}/{id}/review -- settle a new element written as proposed, one carrying
+     * `x_review_proposed` (the queue's `new_element` row, keel #565). The owner's key or a
+     * co-builder's, with its PIN. `{ decision: 'accept' }` clears the mark (a write by you: a new
+     * change_seq, one /changes row) and answers `{ element }`; `{ decision: 'decline', reason? }`
+     * deletes the element (a tombstone, the links to it scrubbed, its open proposals dropped) and
+     * answers `{ deleted }`, its id; the reason is answered back and kept nowhere. Refusals: 422
+     * `not_proposed` (`err.isNotProposed`: the element carries no mark), 403 `proposed_only`
+     * (`err.isProposedOnly`: the seat the mark names, or an agent seat under the world's switch), 403
+     * for any key but a keeper's. A proposed change to an existing element is decided with
+     * acceptProposal or declineProposal instead.
+     */
+    reviewNewElement(type: ElementType | string, id: string, opts: OwReviewInput): Promise<OwReviewed>;
     /**
      * GET /account/worlds -- every world the account owns or is a member of, with its keys by
      * name and last four (a member sees only their own keys on a shared world). Account token only.
      */
     listAccountWorlds(): Promise<OwAccountWorld[]>;
+    /**
+     * POST /account/worlds -- make a world on the account, with its one write key. `name` is required
+     * (1 to 255 characters, not blank; keel trims it). `pin` only while the account has no PIN (4
+     * digits, 1000-9999): it becomes the account PIN and the write wall on every world of the
+     * account. An account with a PIN must leave it out. Either mistake is a 422 with `param: 'pin'`
+     * (`err.param`) and nothing made, so a tool that cannot tell which account it holds sends without
+     * `pin` first and, on that 422, again with it. `keyName` names the write key as the website's key
+     * list shows it (1 to 80 characters, trimmed; null or left out: no name). `source` and `producer`
+     * are the folder format's provenance lines (spec 4.2), each an object or null, from a tool that
+     * makes the world from a folder: kept on the World as given, served by getWorld() as `origin`.
+     * Only the keys given are sent, `keyName` as `key_name`. 201: the world's row, as
+     * listAccountWorlds lists it, with the full write key once in `key`. Account token only; no
+     * Idempotency-Key (keel's document declares none): if the answer is lost, the world is in
+     * listAccountWorlds, and mintWorldKey gives it a key.
+     */
+    createAccountWorld(opts: OwCreateAccountWorldInput): Promise<OwCreatedAccountWorld>;
     /**
      * POST /account/worlds/{id}/keys -- mint a world key, `scope` `'write'` (the default) or
      * `'read'`, `name` as the key list shows it (at most 255 characters). The full key comes back
@@ -5261,4 +5428,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAccountWorld, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwDeleteReason, type OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, type OwMintedKey, type OwNamesMap, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, OwStaleProposalError, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldOrigin, type OwWorldProducer, type OwWorldProposalQuery, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, typeWord, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };
+export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAccountWorld, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreateAccountWorldInput, type OwCreatedAccountWorld, type OwCreatedWorldLink, type OwDeleteReason, type OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, type OwMintedKey, type OwNamesMap, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwProposedNewElement, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwReviewInput, type OwReviewed, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, OwStaleProposalError, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldOrigin, type OwWorldProducer, type OwWorldProposalList, type OwWorldProposalQuery, type OwWorldProposalRow, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, typeWord, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -308,7 +308,8 @@ var OwApiError = class extends Error {
   /**
    * While the world takes agent seats' writes as proposals (keel #519), an agent seat's key tried
    * what it may not: delete an element it did not create, or accept or decline a proposal (403
-   * `proposed_only`). Retrying will not help; a person decides.
+   * `proposed_only`). On any world, reviewNewElement by the member the mark names is the same 403
+   * (keel #565). Retrying will not help; a person decides.
    */
   get isProposedOnly() {
     return this.status === 403 && this.code === "proposed_only";
@@ -320,6 +321,13 @@ var OwApiError = class extends Error {
   get isOwnProposal() {
     return this.status === 403 && this.code === "own_proposal";
   }
+  /**
+   * reviewNewElement on an element that carries no `x_review_proposed` mark (422 `not_proposed`,
+   * keel #565): nothing to settle. Someone settled it already, or it was never written as proposed.
+   */
+  get isNotProposed() {
+    return this.status === 422 && this.code === "not_proposed";
+  }
 };
 var OwPreconditionFailedError = class extends OwApiError {
   constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
@@ -687,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"]);
@@ -1571,9 +1582,14 @@ var OwV2Client = class {
     return this.request("GET", proposalsPath(type, id), { query });
   }
   /**
-   * GET /world/proposals -- the world's queue, newest first: every proposal for the owner's and a
-   * co-builder's keys, a member's own for any other. The query is listProposals', plus `element`
-   * (one element's rows, by id). Any member key, a read key included; a read key with no member
+   * GET /world/proposals -- the world's queue, newest first by created_at, two kinds of row told
+   * apart by `kind` (keel #565): `proposal`, a proposed change to an element (OwProposal), and
+   * `new_element`, an element written as proposed, carrying `x_review_proposed`
+   * (OwProposedNewElement: settle it with reviewNewElement). A marked element is listed under
+   * `open`, `lapsed` and `all`, never `accepted` or `declined`; keel reads at most the 500 newest.
+   * Every row for the owner's and a co-builder's keys, a member's own for any other. The query is
+   * listProposals', plus `element` (one element's rows, by id). The cursor is opaque: pass
+   * `next_cursor` back as it came. Any member key, a read key included; a read key with no member
    * (a demo key, the owner's read key) and the keyless public view get a 404.
    */
   async worldProposals(opts = {}) {
@@ -1620,6 +1636,27 @@ var OwV2Client = class {
   async withdrawProposal(type, id, pid) {
     await this.request("DELETE", `${proposalsPath(type, id)}/${encodeURIComponent(pid)}`, { allowEmpty: true });
   }
+  /**
+   * POST /{type}/{id}/review -- settle a new element written as proposed, one carrying
+   * `x_review_proposed` (the queue's `new_element` row, keel #565). The owner's key or a
+   * co-builder's, with its PIN. `{ decision: 'accept' }` clears the mark (a write by you: a new
+   * change_seq, one /changes row) and answers `{ element }`; `{ decision: 'decline', reason? }`
+   * deletes the element (a tombstone, the links to it scrubbed, its open proposals dropped) and
+   * answers `{ deleted }`, its id; the reason is answered back and kept nowhere. Refusals: 422
+   * `not_proposed` (`err.isNotProposed`: the element carries no mark), 403 `proposed_only`
+   * (`err.isProposedOnly`: the seat the mark names, or an agent seat under the world's switch), 403
+   * for any key but a keeper's. A proposed change to an existing element is decided with
+   * acceptProposal or declineProposal instead.
+   */
+  async reviewNewElement(type, id, opts) {
+    only("reviewNewElement", opts, ["decision", "reason"], "The review is { decision, reason? }.");
+    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.`);
+    }
+    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 });
+  }
   // -- The account's worlds and keys (account token) -----------------------
   /**
    * GET /account/worlds -- every world the account owns or is a member of, with its keys by
@@ -1632,6 +1669,36 @@ var OwV2Client = class {
     const page = await this.request("GET", "/account/worlds");
     return page.data;
   }
+  /**
+   * POST /account/worlds -- make a world on the account, with its one write key. `name` is required
+   * (1 to 255 characters, not blank; keel trims it). `pin` only while the account has no PIN (4
+   * digits, 1000-9999): it becomes the account PIN and the write wall on every world of the
+   * account. An account with a PIN must leave it out. Either mistake is a 422 with `param: 'pin'`
+   * (`err.param`) and nothing made, so a tool that cannot tell which account it holds sends without
+   * `pin` first and, on that 422, again with it. `keyName` names the write key as the website's key
+   * list shows it (1 to 80 characters, trimmed; null or left out: no name). `source` and `producer`
+   * are the folder format's provenance lines (spec 4.2), each an object or null, from a tool that
+   * makes the world from a folder: kept on the World as given, served by getWorld() as `origin`.
+   * Only the keys given are sent, `keyName` as `key_name`. 201: the world's row, as
+   * listAccountWorlds lists it, with the full write key once in `key`. Account token only; no
+   * Idempotency-Key (keel's document declares none): if the answer is lost, the world is in
+   * listAccountWorlds, and mintWorldKey gives it a key.
+   */
+  async createAccountWorld(opts) {
+    only("createAccountWorld", opts, ["name", "pin", "keyName", "source", "producer"]);
+    if (this.keyKind !== "account") {
+      throw new TypeError("createAccountWorld needs an account token (ow_a_)");
+    }
+    if (typeof opts?.name !== "string") {
+      throw new TypeError("createAccountWorld: name is required, the world's name as a string. Nothing was sent.");
+    }
+    const body = { name: opts.name };
+    if (opts.pin !== void 0) body.pin = opts.pin;
+    if (opts.keyName !== void 0) body.key_name = opts.keyName;
+    if (opts.source !== void 0) body.source = opts.source;
+    if (opts.producer !== void 0) body.producer = opts.producer;
+    return this.request("POST", "/account/worlds", { body });
+  }
   /**
    * POST /account/worlds/{id}/keys -- mint a world key, `scope` `'write'` (the default) or
    * `'read'`, `name` as the key list shows it (at most 255 characters). The full key comes back

package/package.json

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