@onlyworlds/sdk 4.16.0 → 4.18.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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
+- **`changesAll` returns `epoch`** beside `cursor` and `head`: the last page's, so a full walk
+  says which view epoch it ran under (a guest's integer; `null` for other keys or a keel
+  without the field) and the first poll after it needs no extra walk to learn it. Live on
+  Moppetopia: a full walk of 465 changes returns `{ cursor, head: 818, epoch: null }`. The first
+  tests of `changesAll`'s return value (Temper, h29 #3534).
+
 ## [4.16.0] — 2026-10-12
 
 ### Added
@@ -16,6 +37,8 @@ earlier history lives in git log only.
   page both carry `epoch: null`). The wire gate now holds `OwChangesPage` and `OwBulkResponse`
   to keel's `ChangesPage` and `BulkResult` (keel #108), and failed on 4.15.0 for the missing
   `epoch` before this release.
+  Published from tag `v4.16.0`; the workflow's read-back gave up before npm showed the
+  version, so the tarball (shasum `d08de22b`) was read back by hand against a build of the tag.
 
 ## [4.15.0] — 2026-10-12
 

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. */
@@ -2388,11 +2469,13 @@ declare class OwV2Client {
     /**
      * Walk the feed from `since` (or from zero = full export) to the current
      * tail, yielding ops in order. Returns the final cursor via the generator's
-     * return value; persist it for the next incremental pull.
+     * return value; persist it for the next incremental pull (with the last page's
+     * `head` and `epoch`: the view epoch the walk ran under, for a guest).
      */
     changesAll(since?: string): AsyncGenerator<OwChange, {
         cursor: string;
         head: number;
+        epoch: number | null;
     }>;
     /**
      * POST /media/ticket -- permission to upload ONE image into this world (a write
@@ -2484,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
@@ -3164,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

@@ -347,7 +347,8 @@ var OwV2Client = class {
   /**
    * Walk the feed from `since` (or from zero = full export) to the current
    * tail, yielding ops in order. Returns the final cursor via the generator's
-   * return value; persist it for the next incremental pull.
+   * return value; persist it for the next incremental pull (with the last page's
+   * `head` and `epoch`: the view epoch the walk ran under, for a guest).
    */
   async *changesAll(since) {
     let cursor = since;
@@ -357,7 +358,7 @@ var OwV2Client = class {
       for (const op of page.changes) yield op;
       cursor = page.cursor;
     } while (page.has_more);
-    return { cursor: page.cursor, head: page.head };
+    return { cursor: page.cursor, head: page.head, epoch: page.epoch ?? null };
   }
   // -- Images ---------------------------------------------------------------
   /**
@@ -493,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.16.0",
+  "version": "4.18.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {