@onlyworlds/sdk 4.55.0 → 4.57.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.45** (canonical 00.33.00).
+**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.46** (canonical 00.33.00).
 This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
 re-read against it, the check fails rather than letting this document rot quietly.
 
@@ -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,
@@ -109,6 +111,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   `mcp`, `declared`, `api`, `v1`, `sync`, `server`), and a `/changes` delete carries
   `deleted_by` and `deleted_via`; `isAgentDoor(door)` is true for the first three. An agent
   seat's key is recorded as an agent without the option. Never set it in a tool people use.
+- **Name your tool** (since 4.56.0): `new OwV2Client({ ..., client: 'atlas' })` sends
+  `X-OW-Client: atlas` on every element write (never on a read); left out, it sends `sdk`. The name
+  is lower case letters, digits and hyphens, 1 to 32 characters, else a TypeError at construction.
+  keel stores it as `changed_client` on the element and `deleted_client` on a `/changes` delete:
+  the client's claim, never proof, and null when none was sent.
 - A guest or player reads what its own Character's sheet links to as a **stub**, marked
   `known_of: true` (`isKnownOf(el)`): only `id`, `type`, `name`, `description`, `supertype`,
   `subtype`, `image_url`, the timestamps and the fields its type lists in `PUBLIC_FIELDS` are

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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
+
+- **The client's name** (keel #520, live 2026-10-22; Orrery's `client-name.md`, decision 2): a constructor option `client`, default `'sdk'`, sent as `X-OW-Client` on every element write (`create`, `upsert`, `patch`, `delete`, `editLinks`, `bulk`, `adopt`) and on no read. keel stores it on the element as `changed_client`, so a reader can tell which tool made the last change (`new OwV2Client({ ..., client: 'atlas' })`). The rule is keel's, exact here: lower case letters, digits and hyphens, 1 to 32 characters (`[a-z0-9-]{1,32}`). Anything else, a capital, a space, an empty string, 33 characters or a value that is not a string, is a TypeError at construction naming the option and the rule, and nothing is trimmed; keel's own fence for a stranger's header is to store null, never a 422. The name is the client's claim about itself, never proof; it changes no door and no permission, and `agent` still decides `X-OW-Agent`.
+- **`changed_client`** on `OwElementBase` (`string | null`, server-managed, read-only, beside `changed_by` and `changed_via`): the name the last write gave, null when it gave none or one outside the rule, for keel's own writes, and for changes from before names were recorded. Sent back in a write it is ignored. **`deleted_client`** on a `/changes` delete (`OwChangeDelete`, beside `deleted_by` and `deleted_via`), the same for the delete; null on a `hidden` row.
+
+### Changed
+
+- **The constructor refuses an unknown key by name**, as every options object has since 4.52.0: `new OwV2Client({ clinet: 'atlas' })` is a `TypeError` naming the key and the eight the constructor knows, where it fell back to the defaults silently before. Every known caller (Atlas, Lantern, the toolkit) passes known keys only.
+- **Schema repinned to schema-dist v0.33.0-dist.46** (same canonical 00.33.00). The dist's example export (`example/world-export.json`) gains `changed_client: null` on its bodies, `walk/lint_folder.py`'s server-key set names `changed_client`, and the README's sentence on server keys names it; `VERSION` and `MANIFEST.json` carry the new serial; no schema file moved. Generated output moves its provenance lines and gains `changed_client`.
+
 ## [4.55.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/SCHEMA.md

@@ -1,6 +1,6 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.45** — canonical schema **00.33.00**, published 2026-10-22.
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.46** — canonical schema **00.33.00**, published 2026-10-22.
 
 GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
 Written for both humans and AI agents reading this package locally.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /** Every element carries these. The extension index signature admits namespaced
  *  pass-through fields (atlas_* / shadow_* / x_*) returned verbatim by the server.
  *  Derived from base_properties.yaml: `World` is dropped (the API rejects it in
- *  bodies -- the key determines the world) and the seven server-managed fields are
+ *  bodies -- the key determines the world) and the eight server-managed fields are
  *  added, since they ride every wire body and appear in no element YAML; `known_of`
  *  rides only a stub. */
 interface OwElementBase {
@@ -31,6 +31,8 @@ interface OwElementBase {
     changed_by?: string | null;
     /** The door of the last write (server-managed, read-only): `seat` (an agent seat), `mcp`, `declared` (a client that sent X-OW-Agent), then `api`, `v1`, `sync`, `server` (keel's own writes) or `site` (the owner signed in on onlyworlds.com; keel PR 160). The first three are agent-made. Null for anything last changed before writes recorded it. */
     changed_via?: 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | 'site' | null;
+    /** The name the client gave in the X-OW-Client header on the last write (server-managed, read-only): lower case letters, digits and hyphens, 1 to 32 characters, such as `sdk` or `atlas`. It is the client's claim about itself, never proof, and says nothing about whether an agent drove the write (that is `changed_via`). Null when the last write sent no name or one outside the rule, for keel's own writes, and for anything last changed before names were recorded. Sent in a write it is ignored. This SDK sends its `client` option, `sdk` by default. */
+    changed_client?: string | null;
     /** Present, and true, only when the world's owner or a co-builder hid this element and this reader still sees it (server-managed, read-only): the owner, a co-builder, a key the owner minted, or the member who made it; to every other reader the element does not exist. Absent otherwise, whatever `fields` asked; on the read, the list, the change feed's upserts and MCP, never in the download, world sync or v1. Sent in a write it is ignored. */
     hidden?: true;
     /** Present, and true, only on a stub (server-managed, read-only): an element a guest or player reaches only through its own Character's sheet. A stub keeps id, type, name, description, supertype, subtype, image_url, created_at, updated_at and change_seq, and the fields its type lists in PUBLIC_FIELDS with their values; every other field reads unset ("", null, []), created_by/changed_by/changed_via null, no extension fields, and its files are 404. Its empties are not values and not a deletion: never write a stub back. Absent: the element is whole. See isKnownOf(). */
@@ -1945,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[];
@@ -1981,6 +2010,12 @@ interface OwChangeDelete {
     deleted_by?: string | null;
     /** The door the delete came through (see {@link OwWriteDoor}); null for deletes before writes recorded it. */
     deleted_via?: OwWriteDoor | null;
+    /**
+     * The name the deleting client gave in its `X-OW-Client` header (keel #520), as an element's
+     * `changed_client`: the client's claim, never proof. Null when none was recorded, and on a
+     * `hidden` row (a hide carries no client).
+     */
+    deleted_client?: string | null;
     /**
      * Why the element left this reader's view (keel #421): `deleted` (it is gone; a GET answers 410),
      * `hidden` (the world's owner or a co-builder hid it from this reader; it still exists, a GET answers
@@ -2812,6 +2847,18 @@ interface OwClientConfig {
      * as an agent without it.
      */
     agent?: boolean;
+    /**
+     * This client's own name, sent as `X-OW-Client` on every element write (create, upsert, patch,
+     * delete, editLinks, bulk, adopt) and on no read (keel #520). keel stores it on the element as
+     * `changed_client`, and on a /changes delete as `deleted_client`, so a reader can tell which tool
+     * made a change: `'atlas'`, `'lantern'`, your app's name. Default `'sdk'`.
+     *
+     * The rule: lower case letters, digits and hyphens, 1 to 32 characters (`[a-z0-9-]{1,32}`), no
+     * version (`'atlas'`, not `'atlas-1.76'`). Anything else is a TypeError when the client is
+     * constructed, and nothing is trimmed. It is the client's claim about itself, not proof, and it
+     * changes no permission and no door: whether an agent made a write is `agent`'s business.
+     */
+    client?: string;
 }
 
 /**
@@ -3158,6 +3205,10 @@ declare class OwV2Client {
     private readonly apiPin;
     private readonly fetchImpl;
     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>;
@@ -3167,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,
@@ -3331,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;
     }>;
     /**
@@ -3763,9 +3831,18 @@ declare class OwV2Client {
         allowEmpty?: boolean;
         replayAware?: boolean;
         /** A `change_seq` to send as `If-Match` (keel #210); a whole number, else TypeError before sending. */
-        /** An element write (create, put, patch, delete, links, bulk): where an agent client sends X-OW-Agent. */
+        /** A write keel's document lists X-OW-Agent on (the element writes, hide and unhide, the file ticket, setMyCharacter, mintWorldKey): where an agent client sends it. */
         write?: boolean;
+        /** 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>;
 }
 /**
@@ -4806,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,10 @@ 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 ?? "";
     this.apiPin = config.apiPin || void 0;
     this.keyKind = config.apiKey ? detectKeyKind(config.apiKey) : "none";
@@ -529,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 ---------------------------------------------
   /**
@@ -649,6 +658,7 @@ var OwV2Client = class {
     }
     return this.request("POST", `/${type}/`, {
       write: true,
+      elementWrite: true,
       body,
       idempotencyKey: opts.idempotencyKey
     });
@@ -660,7 +670,7 @@ var OwV2Client = class {
    */
   async upsert(type, id, element) {
     refuseKnownOf(element, "upsert");
-    return this.request("PUT", `/${type}/${id}/`, { write: true, body: sanitizePayload(element) });
+    return this.request("PUT", `/${type}/${id}/`, { write: true, elementWrite: true, body: sanitizePayload(element) });
   }
   /**
    * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
@@ -675,7 +685,7 @@ var OwV2Client = class {
   async patch(type, id, partial, opts = {}) {
     only("patch", opts, ["ifMatch"]);
     refuseKnownOf(partial, "patch");
-    return this.request("PATCH", `/${type}/${id}/`, { write: true, body: sanitizePayload(partial), ifMatch: opts.ifMatch });
+    return this.request("PATCH", `/${type}/${id}/`, { write: true, elementWrite: true, body: sanitizePayload(partial), ifMatch: opts.ifMatch });
   }
   /**
    * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
@@ -683,7 +693,7 @@ var OwV2Client = class {
    * transaction -- no client-side unlink pass needed, ever.
    */
   async delete(type, id) {
-    await this.request("DELETE", `/${type}/${id}/`, { write: true, allowEmpty: true });
+    await this.request("DELETE", `/${type}/${id}/`, { write: true, elementWrite: true, allowEmpty: true });
   }
   /**
    * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
@@ -695,7 +705,7 @@ var OwV2Client = class {
   async editLinks(type, id, field, edit, opts = {}) {
     only("editLinks", opts, ["ifMatch"]);
     only("editLinks", edit, ["add", "remove"], "The edit is { add?: string[], remove?: string[] }.");
-    return this.request("POST", `/${type}/${id}/links/${field}`, { write: true, body: edit, ifMatch: opts.ifMatch });
+    return this.request("POST", `/${type}/${id}/links/${field}`, { write: true, elementWrite: true, body: edit, ifMatch: opts.ifMatch });
   }
   /**
    * POST /{type}/{id}/adopt with {member} -- change who made an element (keel #427, D141).
@@ -711,7 +721,7 @@ var OwV2Client = class {
    */
   async adopt(type, id, member) {
     if (typeof member !== "string" || member === "") throw new TypeError('adopt: member must be a membership id or "owner"');
-    return this.request("POST", `/${type}/${id}/adopt`, { write: true, body: { member } });
+    return this.request("POST", `/${type}/${id}/adopt`, { write: true, elementWrite: true, body: { member } });
   }
   // -- Bulk ----------------------------------------------------------------
   /**
@@ -745,6 +755,7 @@ var OwV2Client = class {
     };
     return this.request("POST", "/bulk/", {
       write: true,
+      elementWrite: true,
       body,
       idempotencyKey: opts.idempotencyKey,
       replayAware: true
@@ -775,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) };
   }
   /**
@@ -790,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;
   }
@@ -1510,7 +1552,9 @@ 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;
     try {
       res = await this.fetchImpl(url, {
@@ -1521,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();
@@ -1533,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 };
@@ -1670,6 +1733,16 @@ function only(method, obj, keys, hint = "") {
     }
   }
 }
+var CLIENT_CONFIG_KEYS = ["apiKey", "apiPin", "baseUrl", "pageSize", "changesPageSize", "fetch", "agent", "client"];
+var CLIENT_NAME_RULE = /^[a-z0-9-]{1,32}$/;
+var DEFAULT_CLIENT_NAME = "sdk";
+function clientNameOf(value) {
+  if (value === void 0) return DEFAULT_CLIENT_NAME;
+  if (typeof value !== "string" || !CLIENT_NAME_RULE.test(value)) {
+    throw new TypeError(`OwV2Client: client must be lower case letters, digits and hyphens, 1 to 32 characters ([a-z0-9-]{1,32}), such as 'atlas'; got ${JSON.stringify(value) ?? String(value)}. It is sent as X-OW-Client on writes; leave it out for '${DEFAULT_CLIENT_NAME}'.`);
+  }
+  return value;
+}
 function buildQuery(params) {
   const q = new URLSearchParams();
   for (const [k, v] of Object.entries(params)) {

package/package.json

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