@onlyworlds/sdk 4.17.0 → 4.18.1

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.32.0-dist.20** (canonical 00.32.00).
+**Current as of**: SDK **4.x** · schema-dist **v0.32.0-dist.23** (canonical 00.32.00).
 This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
 re-read against it, the check fails rather than letting this document rot quietly.
 
@@ -45,6 +45,10 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Ask (since 4.13.0, account token): `buildAskContext(hits, index)` then
   `account.ask({ worldId, question, context })`; answers only from the context. 50 a day per
   account (`err.isQuotaExceeded`); `isAskUnavailable`, `isAskFailed` count nothing.
+- Sort (since 4.18.0, account token): `account.sort({ worldId, notes, slice })` turns unsorted
+  notes (text, or a picture already uploaded into the world) into rows to review: `make`,
+  `add_to`, `link`, `ask`, plus `not_proposed` with reasons. Ids come only from your `slice`
+  (up to 100 elements your own lookup found); nothing is written. Counts as one ask.
 - 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.

package/CHANGELOG.md

@@ -5,6 +5,26 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.18.1] — 2026-10-12
+
+### Changed
+- **Schema repinned to schema-dist v0.32.0-dist.23** (same canonical 00.32.00). The one
+  generated change is the `id` doc comment: a UUID, new ids minted as uuidv7, earlier uuidv4
+  ids still valid. No type changes. The vendored dist gains `walk/lint_folder.py`.
+- README and AGENTS.md describe `sort()`.
+
+## [4.18.0] — 2026-10-12
+
+### Added
+- **`client.sort({ worldId, notes, slice })`**: POST /account/sort, ask's sibling (Temper for
+  Lantern, h37 #3599; Skeld's route, #3591, #3594, #3596, #3597). Notes as words or
+  `{ text, image_url }`; the slice is the app's own lookup. Rows of four kinds come back to
+  review (`make`, `add_to`, `link`, `ask` with an optional `then`) and `not_proposed` with
+  reasons; nothing is written. One allowance with `ask`, and the same refusals. Types
+  `OwSortRef`, `OwSortNote`, `OwSortRow` and its four kinds, `OwSortAnswer`. Built against
+  keel PR #4 (90961fa, Skeld's final for the types, #3618), released once it was on keel
+  main and in production (#3663): verify-sdk-wire PASS 1,111 against production's document.
+
 ## [4.17.0] — 2026-10-12
 
 ### Added

package/README.md

@@ -174,6 +174,14 @@ const reply = await account.ask({ worldId, question, context }); // account: a c
 reply.answer;                                            // from those elements only, or "The world doesn't say."
 ```
 
+The same proxy sorts loose notes into changes for the user to review. Send the elements your own lookup found for them as the `slice`; every id in a row comes from it, and nothing is written until your app applies what the user accepts. A sort counts as one question.
+
+```typescript
+const slice = hits.slice(0, 100).map(({ element: e }) => ({ id: e.id, type: e.type, name: e.name }));
+const { rows, not_proposed } = await account.sort({ worldId, notes: ['Mira moved to Ostvik.'], slice });
+// rows: make (a new element), add_to (text for a field), link (one element to another), ask (which one?)
+```
+
 ## World files
 
 A world file is one `.zip` holding a whole world folder (`world.json` and `elements/<type>/*.json`, as Atlas keeps a world on disk), the way Atlas downloads and opens one. It needs no account and works in the browser and in Node.

package/SCHEMA.md

@@ -1,6 +1,6 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.0-dist.20** — canonical schema **00.32.00**, published 2026-10-11.
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.0-dist.23** — canonical schema **00.32.00**, published 2026-10-12.
 
 GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
 Written for both humans and AI agents reading this package locally.

package/dist/index.d.ts

@@ -6,7 +6,7 @@
 interface OwElementBase {
     /** Element type slug (server-managed, read-only). */
     type: string;
-    /** Unique identifier for the element, uuidv7 format. */
+    /** Unique identifier for the element, a UUID. New ids are minted as uuidv7; ids minted earlier as uuidv4 remain valid. */
     id: string;
     /** Name of the element. */
     name: string;
@@ -2013,6 +2013,87 @@ interface OwAskAnswer {
     remaining: number;
     [k: string]: unknown;
 }
+/**
+ * One element the notes may be about, as POST /account/sort takes it (the slice), and as a
+ * row names it back: keel copies a target's name, type and anchor from the slice, never
+ * from the model. `type` is lowercase going in; keel answers with its own spelling.
+ */
+interface OwSortRef {
+    id: string;
+    type: string;
+    name: string;
+    /** A short phrase that tells two same-named elements apart (up to 120 characters). */
+    anchor?: string;
+}
+/**
+ * A note for sorting: its words, or an object with words and/or a picture already uploaded
+ * into this world (`https://media.onlyworlds.com/u/<world id>/<name>`, no query). An object
+ * needs at least one of the two; the picture is read as a photographed note.
+ */
+type OwSortNote = string | {
+    text?: string;
+    image_url?: string | null;
+};
+/** A new element the notes describe. */
+interface OwSortMakeRow {
+    kind: 'make';
+    source_line: string;
+    proposal: {
+        type: string;
+        name: string;
+        description: string;
+    };
+}
+/** Text to append to a field of a slice element. */
+interface OwSortAddToRow {
+    kind: 'add_to';
+    source_line: string;
+    target: OwSortRef;
+    field: string;
+    op: 'append';
+    value: string;
+}
+/** A link from one slice element to another, through a named field. */
+interface OwSortLinkRow {
+    kind: 'link';
+    source_line: string;
+    target: OwSortRef;
+    field: string;
+    value_id: string;
+    value_name: string;
+}
+/**
+ * A question for the user: a name matches two or more slice elements, or the sorter is
+ * unsure a thing exists. `then`, when sent, is the add_to or link the question stands for,
+ * its target left out: the user's pick fills it.
+ */
+interface OwSortAskRow {
+    kind: 'ask';
+    source_line: string;
+    question: string;
+    candidates: OwSortRef[];
+    then?: Omit<OwSortAddToRow, 'source_line' | 'target'> | Omit<OwSortLinkRow, 'source_line' | 'target'>;
+}
+type OwSortRow = OwSortMakeRow | OwSortAddToRow | OwSortLinkRow | OwSortAskRow;
+/** POST /account/sort: proposed changes for the user to review. Nothing is written to the world. */
+interface OwSortAnswer {
+    /** Every id in a row is from the request's slice. */
+    rows: OwSortRow[];
+    /** The lines the sorter could not place, and rows keel refused, each with a reason. */
+    not_proposed: {
+        source_line: string;
+        reason: string;
+    }[];
+    model: string;
+    stop_reason: string | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    /** Questions the account has left today: a sort counts as one ask. */
+    remaining: number;
+    [k: string]: unknown;
+}
 /** POST /join/preview: what a join code holds, read without using it (keel #212). */
 interface OwJoinPreview {
     /** `person`: an invite link, accepted with acceptJoin. `agent`: redeemed by an AI agent at POST /join. */
@@ -2486,6 +2567,22 @@ declare class OwV2Client {
         question: string;
         context: string[];
     }): Promise<OwAskAnswer>;
+    /**
+     * POST /account/sort -- the user's unsorted notes, and the elements the app's own search
+     * found for them (`slice`: id, lowercase type, name, optional anchor; build it from
+     * lookupWorld's hits), sorted by the same proxy as ask into rows to review: `make`, `add_to`,
+     * `link`, `ask`. Nothing is written; the app applies what the user accepts. Every id in a
+     * row is from the slice; keel moves any other row to `not_proposed` with its reason.
+     * A sort counts as one ask: the same account token, allowance and refusals as ask. 422
+     * names the param: notes 1 to 8, each up to 4,000 characters and 16,000 in all (text
+     * only), at most four pictures, each uploaded into this world; slice up to 100, names up
+     * to 200 characters, anchors up to 120.
+     */
+    sort(req: {
+        worldId: string;
+        notes: OwSortNote[];
+        slice: OwSortRef[];
+    }): Promise<OwSortAnswer>;
     /**
      * Raw authenticated request against this client's baseUrl. Public since 4.0
      * so auxiliary resources can ride the same transport — it structurally
@@ -3166,4 +3263,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { ASK_LIMITS, type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwJoinPreview, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMediaTicket, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldMeta, PHOTO_MAX_BYTES, PHOTO_TYPES, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, buildAskContext, buildWorldIndex, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, lookupWorld, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readWorldFile, renderElement, writeWorldFile };
+export { ASK_LIMITS, type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwJoinPreview, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMediaTicket, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldMeta, PHOTO_MAX_BYTES, PHOTO_TYPES, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, buildAskContext, buildWorldIndex, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, lookupWorld, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readWorldFile, renderElement, writeWorldFile };

package/dist/index.js

@@ -494,6 +494,25 @@ var OwV2Client = class {
       body: { world_id: req.worldId, question: req.question, context: req.context }
     });
   }
+  /**
+   * POST /account/sort -- the user's unsorted notes, and the elements the app's own search
+   * found for them (`slice`: id, lowercase type, name, optional anchor; build it from
+   * lookupWorld's hits), sorted by the same proxy as ask into rows to review: `make`, `add_to`,
+   * `link`, `ask`. Nothing is written; the app applies what the user accepts. Every id in a
+   * row is from the slice; keel moves any other row to `not_proposed` with its reason.
+   * A sort counts as one ask: the same account token, allowance and refusals as ask. 422
+   * names the param: notes 1 to 8, each up to 4,000 characters and 16,000 in all (text
+   * only), at most four pictures, each uploaded into this world; slice up to 100, names up
+   * to 200 characters, anchors up to 120.
+   */
+  async sort(req) {
+    if (this.keyKind !== "account") {
+      throw new TypeError("sort needs an account token (ow_a_): the proxy meters per account");
+    }
+    return this.request("POST", "/account/sort", {
+      body: { world_id: req.worldId, notes: req.notes, slice: req.slice }
+    });
+  }
   // -- Core request machinery ----------------------------------------------
   /**
    * Raw authenticated request against this client's baseUrl. Public since 4.0

package/package.json

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