@onlyworlds/sdk 4.64.0 → 4.66.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,33 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [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
+
+- **`patchWorld` takes a `getWorld()` body back again** (keel #571, live 2026-10-23). keel's `GET /world` now serves `origin`, and a PATCH naming it is a 422 (an unknown key), so a world body read and sent back failed. `patchWorld` now leaves out `origin`, and `id` too: keel answers `id` with the same 422 (it is not a key PATCH takes), so the round trip 4.57.1's entry promised never held for a whole body. `owner_character` is still sent.
+
+### Added
+
+- **`OwWorldMeta.origin?: OwWorldOrigin`**, read-only: where the world first came from, `{ source, producer }`, both keys always present, each the folder format's provenance line (spec 4.2) as the tool that made the world from a folder gave it, or `null`. Types `OwWorldOrigin`, `OwWorldSource` (`server`, `world`, `at`) and `OwWorldProducer` (`tool`, `version`, `input`), each open to keys keel keeps as given. The origin is written as the plain keys `source` and `producer`: `patchWorld({ source, producer })` sends them as given (an object, or `null` to clear).
+- **The World's extension keys on `OwWorldMeta`**: `x_*`, `atlas_*` and `shadow_*`, typed `unknown` by template-literal index signatures (the first is `x_names`, the names profile `typeWord` reads). `patchWorld` sends every one as given, `null` included (keel removes the key); over keel's 64 KB cap on the whole store the answer is a 422 with `param: extensions`.
+- Tests: a full `GET /world` body sent back sends neither `origin` nor `id` and keeps `x_names`; `source`, `producer` and a key of each extension prefix pass untouched, `null` included; the published types declare `origin` and its two keys, and the documented calls (`patchWorld(await getWorld())`, `patchWorld({ source, producer, x_names })`, `typeWord(world, …)`) compile against the built `.d.ts`. Watched failing on mutants: `origin` and `id` each out of the strip list, `origin` out of `OwWorldMeta`, and a narrowed `patchWorld` parameter.
+
 ## [4.64.0] - 2026-10-23
 
 ### Changed

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 `#`:
@@ -184,6 +192,8 @@ To poll for news cheaply, `client.changesHead()` returns `{ head, cursor, epoch,
 
 Edits to the world itself (its name, calendar, `public_read`) don't appear in the change feed. Read `client.getWorld()` and compare `updated_at`.
 
+`client.patchWorld(partial)` writes the world's own settings, and takes a `getWorld()` body back: the keys keel does not take (`id`, `origin`, `slug`, `public_page` and the owner's switches) are left out. The world's `origin` is written as the plain keys `source` and `producer` (each an object or `null`), and extension keys (`x_*`, `atlas_*`, `shadow_*`) are sent as given; `null` removes one.
+
 ### Only if unchanged
 
 A client that edits offline, or from a copy it has held a while, can ask for an update to land only if nobody changed the element since it was read: pass the `change_seq` you read as `ifMatch`, on `patch`, `editLinks` or `delete` (since 4.61.0: a delete of an element someone changed since you read it is refused, nothing deleted).
@@ -212,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

@@ -1968,9 +1968,47 @@ interface OwWorldMeta {
      * the owner on the world page; read-only on the wire, and patchWorld strips it.
      */
     agent_writes_proposed?: boolean;
+    /**
+     * Where the world first came from (keel #571, #477): the folder format's provenance lines (spec
+     * 4.2) as the tool that made the world from a folder gave them, both keys always present, each
+     * null when not known. Read-only on the wire, and patchWorld strips it: write it as the plain
+     * keys `source` and `producer` (`patchWorld({ source, producer })`, each an object or null).
+     */
+    origin?: OwWorldOrigin;
     created_at?: string | null;
     /** Moves when the world's own fields change, not on element writes. */
     updated_at?: string | null;
+    /**
+     * Extension keys (keel #571): a tool's own setting on the world, any JSON value, served at the
+     * top level as an element's are (the first is `x_names`, the names profile: see `typeWord`).
+     * patchWorld sends them as given; `null` removes one; 64 KB in all, else a 422 `param: extensions`.
+     */
+    [extension: `x_${string}`]: unknown;
+    [extension: `atlas_${string}`]: unknown;
+    [extension: `shadow_${string}`]: unknown;
+    [field: string]: unknown;
+}
+/**
+ * OwWorldMeta.origin (keel #571, #477), as keel's `World` component types it: both keys always
+ * present, each an object or null. Kept as the writer gave it; keel checks only that `source.world`
+ * and `producer.tool` are strings when present.
+ */
+interface OwWorldOrigin {
+    source: OwWorldSource | null;
+    producer: OwWorldProducer | null;
+}
+/** The folder format's `source` line (spec 4.2): the server and world a folder was exported from, and when. Kept as given. */
+interface OwWorldSource {
+    server?: string;
+    world?: string;
+    at?: string;
+    [field: string]: unknown;
+}
+/** The folder format's `producer` line (spec 4.2): the tool that made a folder, its version, and what it made it from. Kept as given. */
+interface OwWorldProducer {
+    tool?: string;
+    version?: string;
+    input?: string;
     [field: string]: unknown;
 }
 /** OwWorldMeta.public_page (keel #471), as keel's `World` component types it: all six keys, always. */
@@ -2171,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. */
@@ -2178,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;
@@ -2201,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
@@ -2718,6 +2822,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
@@ -3202,7 +3339,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;
     /**
@@ -3210,6 +3348,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
@@ -3421,7 +3564,10 @@ declare class OwV2Client {
     /**
      * PATCH /world -- partial world-meta update. The element write's server-managed keys are
      * stripped, and so are the world's own read-only ones (WORLD_READ_ONLY_FIELDS: `slug` and
-     * `public_page`, keel #471; `agent_writes_proposed`, keel #519; set on the world page, not here).
+     * `public_page`, keel #471; `agent_writes_proposed`, keel #519; set on the world page, not here;
+     * `origin`, keel #571; `id`), so a `getWorld()` body can be sent back. The world's origin is
+     * written as `source` and `producer` (keel #571, each an object or null, served under `origin`);
+     * extension keys (`x_*`, `atlas_*`, `shadow_*`) are sent as given, and `null` removes one.
      */
     patchWorld(partial: Record<string, unknown>): Promise<OwWorldMeta>;
     /**
@@ -3988,12 +4134,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
@@ -4020,11 +4171,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
@@ -5220,4 +5400,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 OwWorldProposalQuery, type OwWorldPublicPage, 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) {
@@ -617,7 +625,10 @@ var OwV2Client = class {
   /**
    * PATCH /world -- partial world-meta update. The element write's server-managed keys are
    * stripped, and so are the world's own read-only ones (WORLD_READ_ONLY_FIELDS: `slug` and
-   * `public_page`, keel #471; `agent_writes_proposed`, keel #519; set on the world page, not here).
+   * `public_page`, keel #471; `agent_writes_proposed`, keel #519; set on the world page, not here;
+   * `origin`, keel #571; `id`), so a `getWorld()` body can be sent back. The world's origin is
+   * written as `source` and `producer` (keel #571, each an object or null, served under `origin`);
+   * extension keys (`x_*`, `atlas_*`, `shadow_*`) are sent as given, and `null` removes one.
    */
   async patchWorld(partial) {
     const body = sanitizePayload(partial);
@@ -1568,9 +1579,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 = {}) {
@@ -1617,6 +1633,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
@@ -1629,6 +1666,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
@@ -1800,7 +1867,7 @@ var HeadPollState = class {
   }
 };
 var READ_ONLY_FIELDS = ["world", "type", "created_at", "updated_at", "change_seq", "known_of"];
-var WORLD_READ_ONLY_FIELDS = ["slug", "public_page", "public_read", "agent_narrator_rule", "agent_writes_proposed"];
+var WORLD_READ_ONLY_FIELDS = ["id", "slug", "public_page", "public_read", "agent_narrator_rule", "agent_writes_proposed", "origin"];
 function proposalsPath(type, id) {
   return `/${type}/${encodeURIComponent(id)}/proposals`;
 }

package/package.json

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