@onlyworlds/sdk 4.14.0 → 4.16.0

package/AGENTS.md

@@ -30,6 +30,8 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Offline or stale edits: pass `{ ifMatch: el.change_seq }` to `patch`/`editLinks` (since 4.9.0).
   If the element moved, nothing is written and `OwPreconditionFailedError` (412) carries
   `current`; the server never merges, the client decides.
+- Polling: `changesHead()` (since 4.15.0) gives `{head, cursor}` without a page; walk only
+  when `head` moved past the head you last applied.
 - World-meta changes do NOT appear in `/changes` — poll `GET /world` separately.
 - Extension fields: `x_<toolname>_*` is the sanctioned namespace for tool-specific state;
   unknown unprefixed fields 422. Extensions are capped at **64 KB per element** (422,

package/CHANGELOG.md

@@ -5,6 +5,30 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [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.
+
+## [4.15.0] — 2026-10-12
+
+### Added
+- **`changesHead()`**: `GET /changes?head=true`, the feed's position now without a page
+  (keel reads no element). Returns `{ head, cursor }`: `head` is the world's `change_seq`,
+  `cursor` a position to pass as `since` that re-sends nothing (a guest's carries its view's
+  epoch). The cheap "anything new?" for a poll: compare `head` with the head you last applied
+  and walk `changesAll` only when it moved. keel sends the owner's cursor as a number; it comes
+  back as a string, like every cursor the SDK hands out. Checked live on Moppetopia: a walk
+  from the returned cursor brings nothing. Asked for by Lantern's 20-second poll (Temper,
+  Skeld's S15).
+
 ## [4.14.0] — 2026-10-12
 
 ### Fixed

package/README.md

@@ -130,6 +130,8 @@ for await (const change of client.changesAll(cursor)) {
 }
 ```
 
+To poll for news cheaply, `client.changesHead()` returns `{ head, cursor }` without reading any element: walk `changesAll` only when `head` moved past the head you last applied.
+
 Edits to the world itself (its name, calendar, `public_read`) don't appear in the change feed. Read `client.getWorld()` and compare `updated_at`.
 
 ### Only if unchanged

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;
@@ -2363,6 +2369,22 @@ declare class OwV2Client {
         since?: string;
         limit?: number;
     }): Promise<OwChangesPage>;
+    /**
+     * GET /changes?head=true -- where the feed is now, without a page: no element is read.
+     * `head` is the world's change_seq; `cursor` is a position to pass as `since` that
+     * 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. `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

package/dist/index.js

@@ -329,6 +329,21 @@ var OwV2Client = class {
     const query = buildQuery({ since: opts.since, limit: opts.limit ?? this.changesPageSize });
     return this.request("GET", "/changes/", { query });
   }
+  /**
+   * GET /changes?head=true -- where the feed is now, without a page: no element is read.
+   * `head` is the world's change_seq; `cursor` is a position to pass as `since` that
+   * 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. `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), 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

package/package.json

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