@onlyworlds/sdk 4.15.0 → 4.17.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [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
+- **`epoch` on the feed** (keel 979eb0c). `OwChangesPage.epoch` and `changesHead()`'s
+  `epoch`: a guest's view epoch (an integer), `null` for every other key. It moves when what a
+  guest may see changes, even with `head` unchanged, so a poll walks when either `head` or
+  `epoch` moved; nothing needs to read inside the cursor. `changesHead()` answers
+  `epoch: null` from a keel without the field. Checked live on Moppetopia (the head read and a
+  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
 
 ### Added

package/dist/index.d.ts

@@ -1901,6 +1901,12 @@ interface OwChangesPage {
      * instead of assuming caught-up.
      */
     head: number;
+    /**
+     * A guest's view epoch (an integer), null for every other key. It moves when what the
+     * guest may see changes, even with `head` unchanged (a Character given or taken, a role):
+     * walk again on either move. Compare it, never read it out of the cursor (keel, 2026-10-12).
+     */
+    epoch: number | null;
 }
 interface OwBulkItem {
     type: ElementType | string;
@@ -2369,21 +2375,26 @@ declare class OwV2Client {
      * re-sends nothing at the head (a guest's carries its view's epoch). The cheap "anything
      * new?" for a poll: compare `head` with the head you last APPLIED (not the previous
      * poll's, so a missed tick never drops a change) and walk changesAll only when it moved;
-     * a head below yours means the server rewound: walk again from zero. keel returns the
-     * owner's cursor as a number; it is handed back as a string, like every cursor here.
+     * a head below yours means the server rewound: walk again from zero. `epoch` is a
+     * guest's view epoch (null for other keys): it can move with `head` unchanged, so walk on
+     * either move. keel returns the owner's cursor as a number; it is handed back as a
+     * string, like every cursor here.
      */
     changesHead(): Promise<{
         head: number;
         cursor: string;
+        epoch: number | null;
     }>;
     /**
      * 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

package/dist/index.js

@@ -335,17 +335,20 @@ var OwV2Client = class {
    * re-sends nothing at the head (a guest's carries its view's epoch). The cheap "anything
    * new?" for a poll: compare `head` with the head you last APPLIED (not the previous
    * poll's, so a missed tick never drops a change) and walk changesAll only when it moved;
-   * a head below yours means the server rewound: walk again from zero. keel returns the
-   * owner's cursor as a number; it is handed back as a string, like every cursor here.
+   * a head below yours means the server rewound: walk again from zero. `epoch` is a
+   * guest's view epoch (null for other keys): it can move with `head` unchanged, so walk on
+   * either move. keel returns the owner's cursor as a number; it is handed back as a
+   * string, like every cursor here.
    */
   async changesHead() {
     const page = await this.request("GET", "/changes/", { query: buildQuery({ head: "true" }) });
-    return { head: page.head, cursor: String(page.cursor) };
+    return { head: page.head, cursor: String(page.cursor), epoch: page.epoch ?? null };
   }
   /**
    * 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;
@@ -355,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 ---------------------------------------------------------------
   /**

package/package.json

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