@onlyworlds/sdk 4.56.0 → 4.57.0

package/AGENTS.md

@@ -30,8 +30,10 @@ 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.
+- Polling: `changesHead()` (since 4.15.0) gives `{head, cursor, epoch, unchanged}` without a
+  page; walk only when `head` or `epoch` moved past what you last applied. Since 4.57.0 it
+  sends the last ETag as `If-None-Match`: a 304 (refunded by keel) comes back as the held
+  values with `unchanged: true`. The client never sleeps or picks an interval.
 - 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.57.0] - 2026-10-22
+
+### Added
+
+- **The conditional head poll** (keel #518, live 2026-10-22; Orrery's `revision-poll.md`, decision 3): `changesHead()` keeps the last head read's `ETag` per client and sends it back as `If-None-Match` on the next one, exactly as received (keel's 200 sends a weak `W/"821:-"`; nothing is quoted, parsed or compared). keel's tag is `"<head>:<epoch>"`, so a view change moves it as a new change does. When nothing moved, keel answers 304 Not Modified with no body, and `changesHead()` returns the `head`, `cursor` and `epoch` of the last 200 with `unchanged: true`; every 200 says `unchanged: false`. keel refunds a 304 against the request budget, so a poll that mostly finds nothing costs little. A 409 `resync_required` from `changesHead()`, `changes()` or `changesAll()` clears the held tag, so the next head read is a full 200 with `epoch_reason`. A 304 while no tag is held is an `OwApiError` with status 304, never a made-up head. The client still never polls or sleeps on its own: the interval is the caller's.
+- **The public page on `OwWorldMeta`** (keel #471, PR 173, live 2026-10-22), both read-only: `slug` (`string | null`), the page's address, onlyworlds.com/w/<slug>, null while the page is off, and also a keyless `?world=` value; `public_page` (the new `OwWorldPublicPage`), the page as its owner set it: `on`, `palette` (midnight, daylight, parchment, brass, dusk, or null for the house's), `hero` (one plain line), `sections` (the types shown in order, empty for all), `pin` (an element id or null) and `index` (always false for now), every key present with the page off. Both are set by the owner on the world page; `patchWorld()` strips them, so a body read from `getWorld()` stays writable.
+- **`request()` gains two options**: `ifNoneMatch` (a tag sent as `If-None-Match` as given) and `onEtag(etag, status)` (called with each response's `ETag` and status before the body is read; with it given, a 304 returns null instead of throwing). Every other path is unchanged.
+
+### Changed
+
+- **`changesHead()`'s return type gains `unchanged: boolean`**, beside `head`, `cursor`, `epoch` and the optional `epoch_reason`.
+
 ## [4.56.0] - 2026-10-22
 
 ### Added

package/README.md

@@ -180,7 +180,7 @@ 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.
+To poll for news cheaply, `client.changesHead()` returns `{ head, cursor, epoch, unchanged }` without reading any element: walk `changesAll` only when `head` or `epoch` moved past what you last applied. Since 4.57.0 the client sends the last answer's ETag back, so when nothing moved keel answers 304 (refunded against your request budget) and `unchanged` is true. Sleep on it; the interval is yours.
 
 Edits to the world itself (its name, calendar, `public_read`) don't appear in the change feed. Read `client.getWorld()` and compare `updated_at`.
 

package/dist/index.d.ts

@@ -1947,11 +1947,38 @@ interface OwWorldMeta {
     agent_narrator_rule?: boolean;
     /** The owner's "this Character is me": a Character id in this world, or null (null too, to a reader it is hidden from: keel #421). */
     owner_character?: string | null;
+    /**
+     * The world's public page address, onlyworlds.com/w/<slug> (keel #471): null when the world has
+     * no page (a slug exists only while the page is on). Also a keyless `?world=` value. Set by the
+     * owner on the world page; read-only on the wire, and patchWorld strips it.
+     */
+    slug?: string | null;
+    /**
+     * The world's public page as its owner set it (keel #471): `on`, and the levers. Every key is
+     * present with the page off. Set by the owner on the world page; read-only on the wire, and
+     * patchWorld strips it.
+     */
+    public_page?: OwWorldPublicPage;
     created_at?: string | null;
     /** Moves when the world's own fields change, not on element writes. */
     updated_at?: string | null;
     [field: string]: unknown;
 }
+/** OwWorldMeta.public_page (keel #471), as keel's `World` component types it: all six keys, always. */
+interface OwWorldPublicPage {
+    /** Whether the page is on. */
+    on: boolean;
+    /** The page's palette, or null for the house's. */
+    palette: 'midnight' | 'daylight' | 'parchment' | 'brass' | 'dusk' | null;
+    /** One plain line (at most 120 characters). */
+    hero: string;
+    /** The element types shown, in their order; empty for all, in the house order. */
+    sections: string[];
+    /** One element's id, or null. */
+    pin: string | null;
+    /** Always false for now: search engines stay off. */
+    index: boolean;
+}
 /** List envelope: cursor-paginated. */
 interface OwPage<T = OwElement> {
     data: T[];
@@ -3180,6 +3207,8 @@ declare class OwV2Client {
     private readonly agent;
     /** The name sent as X-OW-Client on element writes (keel #520), checked at construction. */
     private readonly clientName;
+    /** The conditional head poll's state (keel #518), per instance. */
+    private readonly headPoll;
     constructor(config?: OwClientConfig);
     /** GET /health -- unauthenticated liveness pulse. */
     health(): Promise<unknown>;
@@ -3189,7 +3218,10 @@ declare class OwV2Client {
      * do not bump change_seq. Poll getWorld().updated_at for meta freshness.
      */
     getWorld(): Promise<OwWorldMeta>;
-    /** PATCH /world -- partial world-meta update. */
+    /**
+     * PATCH /world -- partial world-meta update. The element write's server-managed keys are
+     * stripped, and so are `slug` and `public_page` (keel #471: set on the world page, not here).
+     */
     patchWorld(partial: Record<string, unknown>): Promise<OwWorldMeta>;
     /**
      * GET /me -- who this world key is: the world, read or write scope, the kind (owner,
@@ -3353,11 +3385,25 @@ declare class OwV2Client {
      * says why the epoch last moved, `role` or `view` (see OwChangesPage.epoch_reason).
      * keel returns the owner's cursor as a number; it is handed back as a
      * string, like every cursor here.
+     *
+     * Conditional (keel #518, 4.57.0): keel tags the answer with an ETag that covers the head and
+     * the epoch, so a view change moves it too. The client keeps the last tag and sends it as
+     * If-None-Match on its next head read. When nothing moved, keel answers 304 with no body, and
+     * this returns the `head`, `cursor` and `epoch` from the last 200 with `unchanged: true`
+     * (no `epoch_reason`); every 200 says `unchanged: false`. keel refunds a 304 against the
+     * request budget, so a poll that mostly sees nothing costs little. A poller: read the head,
+     * sleep when `unchanged`, walk changesAll when `head` or `epoch` moved past what you applied.
+     * The interval is yours; the client never sleeps or polls on its own. The tag is kept per
+     * client instance and sent back exactly as received (`W/` and quotes included), never
+     * compared; a 409 `resync_required` from this or from changes/changesAll clears it, so the
+     * next head read is a full 200 (with `epoch_reason`). A 304 while no tag is held is an
+     * OwApiError (status 304): the client never makes up a head.
      */
     changesHead(): Promise<{
         head: number;
         cursor: string;
         epoch: number | null;
+        unchanged: boolean;
         epoch_reason?: OwResyncReason | null;
     }>;
     /**
@@ -3790,6 +3836,13 @@ declare class OwV2Client {
         /** One of the seven element writes keel reads X-OW-Client on (keel #520: create, put, patch, delete, links, bulk, adopt): where the client's name goes. */
         elementWrite?: boolean;
         ifMatch?: number;
+        /** A tag to send as `If-None-Match` exactly as given (keel #518, the head read): unlike ifMatch, nothing is quoted or checked. */
+        ifNoneMatch?: string;
+        /**
+         * Called with every response's `ETag` header (as received, null when absent) and status, before
+         * the body is read. With it given, a 304 Not Modified returns null instead of throwing.
+         */
+        onEtag?: (etag: string | null, status: number) => void;
     }): Promise<T>;
 }
 /**
@@ -4830,4 +4883,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAccountWorld, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwDeleteReason, type OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, type OwMintedKey, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };
+export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAccountWorld, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwDeleteReason, type OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, type OwMintedKey, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldPublicPage, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -504,6 +504,8 @@ var DEFAULT_PAGE_SIZE = 100;
 var DEFAULT_CHANGES_PAGE_SIZE = 100;
 var OwV2Client = class {
   constructor(config = {}) {
+    /** The conditional head poll's state (keel #518), per instance. */
+    this.headPoll = new HeadPollState();
     only("new OwV2Client", config, CLIENT_CONFIG_KEYS);
     this.clientName = clientNameOf(config.client);
     this.apiKey = config.apiKey ?? "";
@@ -531,9 +533,14 @@ var OwV2Client = class {
   async getWorld() {
     return this.request("GET", "/world/");
   }
-  /** PATCH /world -- partial world-meta update. */
+  /**
+   * PATCH /world -- partial world-meta update. The element write's server-managed keys are
+   * stripped, and so are `slug` and `public_page` (keel #471: set on the world page, not here).
+   */
   async patchWorld(partial) {
-    return this.request("PATCH", "/world/", { body: sanitizePayload(partial) });
+    const body = sanitizePayload(partial);
+    for (const field of WORLD_READ_ONLY_FIELDS) delete body[field];
+    return this.request("PATCH", "/world/", { body });
   }
   // -- Who am I, and who is here ---------------------------------------------
   /**
@@ -779,7 +786,7 @@ var OwV2Client = class {
   async changes(opts = {}) {
     only("changes", opts, ["since", "limit", "after"]);
     const query = buildQuery({ since: opts.since, limit: opts.limit ?? this.changesPageSize, after: opts.after });
-    const page = await this.request("GET", "/changes/", { query });
+    const page = await this.headPoll.feedRead(() => this.request("GET", "/changes/", { query }));
     return { ...page, cursor: String(page.cursor) };
   }
   /**
@@ -794,10 +801,41 @@ var OwV2Client = class {
    * says why the epoch last moved, `role` or `view` (see OwChangesPage.epoch_reason).
    * keel returns the owner's cursor as a number; it is handed back as a
    * string, like every cursor here.
+   *
+   * Conditional (keel #518, 4.57.0): keel tags the answer with an ETag that covers the head and
+   * the epoch, so a view change moves it too. The client keeps the last tag and sends it as
+   * If-None-Match on its next head read. When nothing moved, keel answers 304 with no body, and
+   * this returns the `head`, `cursor` and `epoch` from the last 200 with `unchanged: true`
+   * (no `epoch_reason`); every 200 says `unchanged: false`. keel refunds a 304 against the
+   * request budget, so a poll that mostly sees nothing costs little. A poller: read the head,
+   * sleep when `unchanged`, walk changesAll when `head` or `epoch` moved past what you applied.
+   * The interval is yours; the client never sleeps or polls on its own. The tag is kept per
+   * client instance and sent back exactly as received (`W/` and quotes included), never
+   * compared; a 409 `resync_required` from this or from changes/changesAll clears it, so the
+   * next head read is a full 200 (with `epoch_reason`). A 304 while no tag is held is an
+   * OwApiError (status 304): the client never makes up a head.
    */
   async changesHead() {
-    const page = await this.request("GET", "/changes/", { query: buildQuery({ head: "true" }) });
-    const out = { head: page.head, cursor: String(page.cursor), epoch: page.epoch ?? null };
+    const seen = { status: 0, etag: null };
+    const poll = this.headPoll;
+    const page = await poll.feedRead(() => this.request("GET", "/changes/", {
+      query: buildQuery({ head: "true" }),
+      ifNoneMatch: poll.tag,
+      onEtag: (etag, status) => {
+        seen.etag = etag;
+        seen.status = status;
+      }
+    }));
+    if (seen.status === 304) {
+      if (!poll.held) {
+        throw new OwApiError(304, null, "GET /changes?head=true answered 304 Not Modified while nothing is held: no head read has answered 200 on this client, so there is no head to return", null, null);
+      }
+      return { ...poll.held, unchanged: true };
+    }
+    const tip = { head: page.head, cursor: String(page.cursor), epoch: page.epoch ?? null };
+    poll.tag = seen.etag || void 0;
+    poll.held = tip;
+    const out = { ...tip, unchanged: false };
     if (page.epoch_reason !== void 0) out.epoch_reason = page.epoch_reason;
     return out;
   }
@@ -1514,6 +1552,7 @@ var OwV2Client = class {
     if (opts.body !== void 0) headers["Content-Type"] = "application/json";
     if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
     if (opts.ifMatch !== void 0) headers["If-Match"] = `"${opts.ifMatch}"`;
+    if (opts.ifNoneMatch !== void 0) headers["If-None-Match"] = opts.ifNoneMatch;
     if (this.agent && opts.write) headers["X-OW-Agent"] = "1";
     if (opts.elementWrite) headers["X-OW-Client"] = this.clientName;
     let res;
@@ -1526,6 +1565,10 @@ var OwV2Client = class {
     } catch (cause) {
       throw new OwNetworkError(`OnlyWorlds request failed: ${method} ${path}`, cause);
     }
+    if (opts.onEtag) {
+      opts.onEtag(res.headers?.get?.("ETag") ?? null, res.status);
+      if (res.status === 304) return null;
+    }
     if (!res.ok) throw await errorFromResponse(res);
     if (res.status === 204 || opts.allowEmpty) {
       const text = await res.text();
@@ -1538,7 +1581,22 @@ var OwV2Client = class {
     return parsed;
   }
 };
+var HeadPollState = class {
+  /** A read of /changes: a 409 `resync_required` drops the tag and the held head, then is thrown as is. */
+  async feedRead(read) {
+    try {
+      return await read();
+    } catch (err) {
+      if (err instanceof OwApiError && err.isResyncRequired) {
+        this.tag = void 0;
+        this.held = void 0;
+      }
+      throw err;
+    }
+  }
+};
 var READ_ONLY_FIELDS = ["world", "type", "created_at", "updated_at", "change_seq", "known_of"];
+var WORLD_READ_ONLY_FIELDS = ["slug", "public_page"];
 function sanitizePayload(payload) {
   if (!payload || typeof payload !== "object") return payload;
   const rest = { ...payload };

package/package.json

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