@onlyworlds/sdk 4.14.0 → 4.15.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,18 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [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

@@ -2363,6 +2363,19 @@ 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. 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;
+    }>;
     /**
      * 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,19 @@ 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. 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) };
+  }
   /**
    * 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.15.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {