@onlyworlds/sdk 4.17.0 → 4.18.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [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/dist/index.d.ts

@@ -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.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {