@onlyworlds/sdk 4.13.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,29 @@ 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
+- **The co-builder role is `co_builder` on the wire.** `OwJoinPreview.role` and
+  `OwJoinedMembership.role` listed `'co-builder'`, which is only the label keel shows (keel
+  `MemberRole.CO_BUILDER = "co_builder"`). The types were open, so nothing broke at runtime, but
+  a comparison written from them would never match. Caught by Temper from Lantern's fakes.
+
+### Added
+- `OwMemberRole` (`'co_builder' | 'contributor' | 'guest'`, open), the type both now use.
+
 ## [4.13.0] — 2026-10-12
 
 ### Added

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

@@ -1988,6 +1988,11 @@ interface OwRemovalTicket {
     referenced: number;
 }
 /** The edge's 200 for one removal. */
+/**
+ * A member's role as the wire sends it (keel `MemberRole`, accounts/models.py). `co_builder`
+ * is the value; "co-builder" is only its label in prose. Open, so a new role still types.
+ */
+type OwMemberRole = 'co_builder' | 'contributor' | 'guest' | (string & {});
 /** POST /account/ask: keel's AI proxy's answer (keel #159). */
 interface OwAskAnswer {
     /** The answer, from the context only; "The world doesn't say." when it does not hold one. */
@@ -2014,7 +2019,7 @@ interface OwJoinPreview {
     invited_by: string | null;
     /** The world owner's chosen Character's name, never a username; null when none is set. */
     owner_character: string | null;
-    role: 'co-builder' | 'contributor' | 'guest' | (string & {});
+    role: OwMemberRole;
     /** Whether joining gives the joiner a Character of their own (agent links). */
     with_character: boolean | null;
     /** ISO 8601, UTC. */
@@ -2027,7 +2032,7 @@ interface OwJoinedMembership {
     id: string;
     world_id: string;
     world_name: string;
-    role: 'co-builder' | 'contributor' | 'guest' | (string & {});
+    role: OwMemberRole;
     joined_at: string | null;
     /** The id of the joiner's roster Character, or null. */
     roster_character: string | null;
@@ -2358,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
@@ -3137,4 +3155,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, 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 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

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