@onlyworlds/sdk 4.36.2 → 4.38.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.32.0-dist.23** (canonical 00.32.00).
+**Current as of**: SDK **4.x** · schema-dist **v0.32.1-dist.26** (canonical 00.32.01).
 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.
 

package/CHANGELOG.md

@@ -5,6 +5,38 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.38.0] - 2026-10-20
+
+Schema 00.32.01 (the Captain's word, h55 #8395): repinned to schema-dist v0.32.1-dist.26.
+
+### Changed
+- **An Event's `characters`** reads "Characters who know about the event: they were present, aware of it, or involved in it" (it read "Key characters relevant to the event"), in the generated doc comment and `SCHEMA.md`. No field, type or link changed.
+- **`ONLYWORLDS_VERSION`** is `'00.32.01'`. It is an `as const` export, so its literal type moves too, which is why this is a minor and not a patch.
+
+## [4.37.0] - 2026-10-20
+
+The hidden mark (keel #421), live in production since 2026-10-20 09:24; walked on staging with the mark on, 25 of 25.
+
+### Added
+- A `/changes` delete row's `reason` (`OwDeleteReason`: `deleted` | `hidden` | `out_of_view`; keel #421's hidden
+  mark): an element hidden from this reader leaves its copy as a deleted one does, and a GET of it answers 404,
+  not 410. `isResyncRequired`'s comment names every case keel now sends it for, not only a guest's.
+- `viewAs` on `get`, `list` and `listAll`, sent as `as` (keel #421 PR 3, view as): the owner's key reads as a
+  member (a membership id), as a Character's guest (a Character id) or as the public (`'public'`). A member key
+  gets 403 `view_as_owner_only` (`err.isViewAsOwnerOnly`); an element hidden from that reader is 404, never 410;
+  an unknown value is 422. Until keel's hidden mark is on, keel answers 422 (an unknown parameter).
+- `err.resyncReason` (`'role'` | `'view'` | `undefined`) and `OwResyncReason`: why `/changes` answered 409
+  `resync_required`, from the envelope's `reason` (keel #421, keel PR 103; only while keel's hidden mark is on).
+  `epoch_reason` beside `epoch` on `OwChangesPage` and on `changesHead()`'s answer: why the epoch last moved.
+
+### Changed
+- The resync instruction adds the hidden mark's reasons to 4.36.1's keep (the Captain, 2026-10-20): after a
+  409 `resync_required`, walk again from the start; reason `role` (the key's own role or membership moved):
+  keep what the local copy holds that the walk no longer names; reason `view`, or a delete row with reason
+  `hidden`: drop it; no reason (keel's hidden mark off): keep it, a reset never empties a copy. A tool never
+  empties a copy on its own. `isResyncRequired`'s comment and the `changes`,
+  `changesHead` and `OwChangesPage` comments say so.
+
 ## [4.36.2] - 2026-10-20
 
 ### Changed

package/SCHEMA.md

@@ -1,6 +1,6 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.0-dist.23** — canonical schema **00.32.00**, published 2026-10-12.
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.1-dist.26** — canonical schema **00.32.01**, published 2026-10-20.
 
 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.
@@ -206,7 +206,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 
 ### Involves
 
-- `characters` (multi link → character) — Key characters relevant to the event
+- `characters` (multi link → character) — Characters who know about the event: they were present, aware of it, or involved in it
 - `objects` (multi link → object) — Objects relevant to the event
 - `locations` (multi link → location) — Locations relevant to the event
 - `species` (multi link → species) — Species relevant to the event

package/dist/index.d.ts

@@ -37,7 +37,7 @@ type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creat
 declare const ELEMENT_TYPES: ElementType[];
 /** Canonical OnlyWorlds schema version. Source: the `canonical:` value of the pinned
  *  distribution's VERSION file (see the provenance block at the top of this file). */
-declare const ONLYWORLDS_VERSION: "00.32.00";
+declare const ONLYWORLDS_VERSION: "00.32.01";
 /** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
 type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
 /** Per-type semantic family. Source: the distribution's `presentation.json` sidecar
@@ -1895,7 +1895,7 @@ interface OwWorldMeta {
      * Character a 403 `guest_not_supported`.
      */
     agent_narrator_rule?: boolean;
-    /** The owner's "this Character is me": a Character id in this world, or null. */
+    /** 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;
     created_at?: string | null;
     /** Moves when the world's own fields change, not on element writes. */
@@ -1933,8 +1933,17 @@ 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;
+    /**
+     * 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
+     * 404, and an unhide brings it back by a 409 `resync_required`), or `out_of_view` (declared, sent by
+     * nothing yet). Remove the element from the local copy in every case.
+     */
+    reason?: OwDeleteReason;
     [k: string]: unknown;
 }
+/** Why a /changes delete row says the element left the reader's view (keel #421). */
+type OwDeleteReason = 'deleted' | 'hidden' | 'out_of_view';
 /**
  * The door a write came through, as keel records it on every element (`changed_via`) and on a
  * delete (`deleted_via`) since keel #299: `seat` (an agent seat), `mcp` (the MCP server),
@@ -1962,12 +1971,30 @@ interface OwChangesPage {
      */
     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):
+     * A guest's or a contributor's view epoch (an integer; a contributor's since keel #421), null for
+     * every other key. It moves when what the key may see changes, even with `head` unchanged (a
+     * Character given or taken, an element unhidden, a role):
      * walk again on either move. Compare it, never read it out of the cursor (keel, 2026-10-12).
      */
     epoch: number | null;
+    /**
+     * Why `epoch` last moved (keel #421, only while keel's hidden mark is on; null when `epoch` is
+     * null): `role` (this key's own role or membership moved: keep what the local copy holds that a
+     * walk from the start no longer names) or `view` (something left its view: drop it; also `view`
+     * for an epoch that never moved). It names the last move only: when the epoch moved more than
+     * once since the one you applied, walk with your cursor and read the 409's
+     * `reason` (`err.resyncReason`), which covers every move since it. Never empty a copy on your own.
+     */
+    epoch_reason?: OwResyncReason | null;
 }
+/**
+ * Why a key's view restarted (keel #421, only while keel's hidden mark is on): on a 409
+ * `resync_required` as the envelope's `reason`, on a /changes page and the head as `epoch_reason`.
+ * `role`: the key's own role or membership moved; keep what the new walk does not name (it is out
+ * of view now, not gone). `view`: something left its view (a delete, a hide, an unhide, a
+ * Character change); drop what the new walk does not name. Both since the cursor: `role`.
+ */
+type OwResyncReason = 'role' | 'view';
 interface OwBulkItem {
     type: ElementType | string;
     element: OwElement | Record<string, unknown>;
@@ -1996,6 +2023,8 @@ interface OwErrorBody {
     message?: string;
     param?: string | null;
     doc_url?: string;
+    /** On a 409 `resync_required` only, while keel's hidden mark is on: why (see {@link OwResyncReason}). */
+    reason?: OwResyncReason;
 }
 /**
  * /bulk response. WIRE-CORRECTED (fixtures P2a/P2c): the array key is `items`,
@@ -2176,7 +2205,7 @@ interface OwMe {
     role: 'owner' | OwMemberRole;
     /** The membership id (what `created_by` holds for what this key creates), or null for the owner. */
     membership: string | null;
-    /** The member's Character, or null. */
+    /** The member's Character, or null (null too when it is hidden from this key: keel #421). */
     character: string | null;
     /** Agent seats only: the agent's name. */
     name?: string;
@@ -2188,7 +2217,7 @@ interface OwMember {
     id: string | null;
     kind: 'owner' | 'person' | 'agent' | 'player';
     role: 'owner' | OwMemberRole;
-    /** The Character that is this member, or null. */
+    /** The Character that is this member, or null (null too when it is hidden from the reader: keel #421). */
     character: string | null;
     /** `removed` rows stay, so their elements keep `created_by`. */
     status: 'active' | 'removed';
@@ -2218,7 +2247,7 @@ interface OwJoinPreview {
     };
     /** The name the inviter signed the link with, or null. */
     invited_by: string | null;
-    /** The world owner's chosen Character's name, never a username; null when none is set. */
+    /** The world owner's chosen Character's name, never a username; null when none is set, or when it is hidden (keel #421). */
     owner_character: string | null;
     role: OwMemberRole;
     /** Whether joining gives the joiner a Character of their own (agent links). */
@@ -2524,6 +2553,16 @@ interface ListParams {
      * `__isnull` are designed in keel's spec but not built; `ordering` 422s too.)
      */
     filter?: Record<string, string | number | boolean>;
+    /**
+     * View as (keel #421), sent as `as`: read as another reader of this world would. A membership
+     * id (a person, an agent seat or a player seat) reads as that member's own key; a Character id
+     * reads as a guest of that Character with no membership; `'public'` reads everything not
+     * hidden. The owner's keys only (a key with no member): a member key gets 403
+     * `view_as_owner_only` (`err.isViewAsOwnerOnly`). An element hidden from that reader is 404,
+     * never 410. An unknown value is 422 (`param` as). Only while keel's hidden mark is on; until
+     * then keel answers 422 (an unknown parameter).
+     */
+    viewAs?: string;
 }
 interface OwClientConfig {
     /**
@@ -2572,6 +2611,7 @@ interface OwClientConfig {
  * envelope also carries `type` and `param` (fixtures P4a/P2c); both are
  * surfaced on the thrown error.
  */
+
 /**
  * Auth codes are distinguishable by design; client recovery UX differs per code.
  * `world_gone` is RESERVED: keel's spec promises it but the server never emits it (a deleted
@@ -2625,13 +2665,25 @@ declare class OwApiError extends Error {
      */
     get isIdConflict(): boolean;
     /**
-     * `/changes` refused the cursor (409 `resync_required`): a guest's view of the world
-     * changed, or the key's role did (a guest's cursor has another shape). Drop the stored
-     * cursor, walk again from the start, and keep what the local copy holds that the new walk
-     * does not name: a reset never empties a copy (keel PR 104, the Captain's ruling: sharing
-     * is forward-only).
+     * `/changes` refused the cursor (409 `resync_required`): what this key may see changed
+     * (a guest's slice moved; an element hidden from a contributor was unhidden; the key's role
+     * moved to or from guest or contributor, whose cursors have other shapes; keel #421). Drop
+     * the stored cursor and walk again from the start. What to do with what the local copy holds
+     * that the new walk does not name is `resyncReason`'s: `role`, keep it; `view`, drop it.
+     * Without a reason (keel's hidden mark off), keep it: a reset never empties a copy (keel PR
+     * 104, the Captain's ruling: sharing is forward-only). Never empty the copy on your own.
      */
     get isResyncRequired(): boolean;
+    /**
+     * Why `/changes` refused the cursor, from the 409 `resync_required` envelope's `reason`
+     * (keel #421, only while keel's hidden mark is on): `role` (this key's own role or
+     * membership moved: keep what the local copy holds that the new walk does not name; it is
+     * out of view now, not gone) or `view` (something left this key's view: a delete, a hide, an
+     * unhide, a Character change; drop what the new walk does not name). When both happened
+     * since the cursor, keel says `role`. Undefined for any other error, or when keel sends no
+     * reason.
+     */
+    get resyncReason(): OwResyncReason | undefined;
     /** keel's admission control turned the request away (503 `server_busy`); see retryAfter. */
     get isBusy(): boolean;
     /**
@@ -2648,6 +2700,12 @@ declare class OwApiError extends Error {
      * key never sees it.
      */
     get isOwnerOnly(): boolean;
+    /**
+     * A member key sent `viewAs` (403 `view_as_owner_only`, keel #421): reading as another
+     * reader is the owner's, from a key with no member. Retrying will not help. Only while
+     * keel's hidden mark is on; until then `viewAs` is an unknown parameter (422).
+     */
+    get isViewAsOwnerOnly(): boolean;
     /**
      * A `patch` or `editLinks` sent with `ifMatch` found the element moved past that
      * `change_seq` (412 `precondition_failed`, keel #210): nothing was written and nothing
@@ -2821,8 +2879,11 @@ declare class OwV2Client {
     list(type: ElementType | string, params?: ListParams): Promise<OwPage>;
     /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
     listAll(type: ElementType | string, params?: Omit<ListParams, 'cursor'>): AsyncGenerator<OwElement>;
-    /** GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields. */
-    get(type: ElementType | string, id: string, opts?: Pick<ListParams, 'expand' | 'fields'>): Promise<OwElement>;
+    /**
+     * GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields, and `viewAs` (keel
+     * #421: the owner reads as another reader; see ListParams.viewAs).
+     */
+    get(type: ElementType | string, id: string, opts?: Pick<ListParams, 'expand' | 'fields' | 'viewAs'>): Promise<OwElement>;
     /**
      * POST /{type}/ -- create one element, minting an id on the client when you leave id out.
      * With an `idempotencyKey`, the minted id is derived from the key (a UUIDv5, the same one the
@@ -2889,15 +2950,18 @@ declare class OwV2Client {
     }): Promise<OwBulkResponse>;
     /**
      * GET /changes -- one page of the world's ordered change feed.
-     * Cursor is OPAQUE: persist verbatim, never parse or build one (a guest's has
-     * another shape than everyone else's).
+     * Cursor is OPAQUE: persist verbatim, never parse or build one (a guest's and a
+     * contributor's carry their view's epoch, since keel #421 for a contributor).
      * Zero/absent cursor = full export (byte-aligned with the Folder Format).
      * Reset rule: a 409 `resync_required` (err.isResyncRequired) means the key's
-     * view changed (a guest's, or its role): drop the cursor, walk from zero, and keep what the
-     * local copy holds that the new walk does not name (keel's own words; sharing is forward-only).
+     * view changed (a guest's slice, an element unhidden from a contributor, or its role): drop
+     * the cursor and walk from zero. For what the local copy holds that the walk no longer names,
+     * read err.resyncReason (keel #421, while keel's hidden mark is on): `role`, keep it; `view`,
+     * drop it (as for a delete row with reason `hidden`). Without a reason, keep it (keel's own
+     * words since PR 104; sharing is forward-only). Never empty a copy on your own.
      * Citizenship: heaviest route on the platform; default page size is polite.
-     * keel sends the cursor of a page at the head as a number (an empty page, for anyone
-     * but a guest); it is handed back as a string, like every cursor here.
+     * keel sends the cursor of a page at the head as a number (an empty page, for a key
+     * whose cursor carries no epoch); it is handed back as a string, like every cursor here.
      */
     changes(opts?: {
         since?: string;
@@ -2906,24 +2970,27 @@ declare class OwV2Client {
     /**
      * 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
+     * re-sends nothing at the head (a guest's or a contributor'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
+     * guest's or a contributor's view epoch (null for other keys): it can move with `head` unchanged, so walk on
+     * either move. `epoch_reason` (keel #421, while keel's hidden mark is on; absent otherwise)
+     * 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.
      */
     changesHead(): Promise<{
         head: number;
         cursor: string;
         epoch: number | null;
+        epoch_reason?: OwResyncReason | 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
      * return value; persist it for the next incremental pull (with the last page's
-     * `head` and `epoch`: the view epoch the walk ran under, for a guest).
+     * `head` and `epoch`: the view epoch the walk ran under, for a guest or a contributor).
      */
     changesAll(since?: string): AsyncGenerator<OwChange, {
         cursor: string;
@@ -4249,4 +4316,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 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 OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, 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, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwSeat, type OwSeatCreated, OwSignInError, type OwSignInReason, 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, type ParseError, type ParseOptions, type ParseResult, 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, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, 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 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 OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, 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, 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, OwSignInError, type OwSignInReason, 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, type ParseError, type ParseOptions, type ParseResult, 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, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -103,15 +103,33 @@ var OwApiError = class extends Error {
     return this.status === 409 && this.code === "id_conflict";
   }
   /**
-   * `/changes` refused the cursor (409 `resync_required`): a guest's view of the world
-   * changed, or the key's role did (a guest's cursor has another shape). Drop the stored
-   * cursor, walk again from the start, and keep what the local copy holds that the new walk
-   * does not name: a reset never empties a copy (keel PR 104, the Captain's ruling: sharing
-   * is forward-only).
+   * `/changes` refused the cursor (409 `resync_required`): what this key may see changed
+   * (a guest's slice moved; an element hidden from a contributor was unhidden; the key's role
+   * moved to or from guest or contributor, whose cursors have other shapes; keel #421). Drop
+   * the stored cursor and walk again from the start. What to do with what the local copy holds
+   * that the new walk does not name is `resyncReason`'s: `role`, keep it; `view`, drop it.
+   * Without a reason (keel's hidden mark off), keep it: a reset never empties a copy (keel PR
+   * 104, the Captain's ruling: sharing is forward-only). Never empty the copy on your own.
    */
   get isResyncRequired() {
     return this.status === 409 && this.code === "resync_required";
   }
+  /**
+   * Why `/changes` refused the cursor, from the 409 `resync_required` envelope's `reason`
+   * (keel #421, only while keel's hidden mark is on): `role` (this key's own role or
+   * membership moved: keep what the local copy holds that the new walk does not name; it is
+   * out of view now, not gone) or `view` (something left this key's view: a delete, a hide, an
+   * unhide, a Character change; drop what the new walk does not name). When both happened
+   * since the cursor, keel says `role`. Undefined for any other error, or when keel sends no
+   * reason.
+   */
+  get resyncReason() {
+    if (!this.isResyncRequired) return void 0;
+    const env = this.detail && typeof this.detail === "object" ? this.detail : void 0;
+    const nested = env?.error && typeof env.error === "object" ? env.error : void 0;
+    const reason = nested?.reason;
+    return reason === "role" || reason === "view" ? reason : void 0;
+  }
   /** keel's admission control turned the request away (503 `server_busy`); see retryAfter. */
   get isBusy() {
     return this.status === 503 && this.code === "server_busy";
@@ -134,6 +152,14 @@ var OwApiError = class extends Error {
   get isOwnerOnly() {
     return this.status === 403 && this.code === "owner_only";
   }
+  /**
+   * A member key sent `viewAs` (403 `view_as_owner_only`, keel #421): reading as another
+   * reader is the owner's, from a key with no member. Retrying will not help. Only while
+   * keel's hidden mark is on; until then `viewAs` is an unknown parameter (422).
+   */
+  get isViewAsOwnerOnly() {
+    return this.status === 403 && this.code === "view_as_owner_only";
+  }
   /**
    * A `patch` or `editLinks` sent with `ifMatch` found the element moved past that
    * `change_seq` (412 `precondition_failed`, keel #210): nothing was written and nothing
@@ -342,7 +368,8 @@ var OwV2Client = class {
       cursor: params.cursor,
       expand: params.expand?.join(","),
       fields: params.fields?.join(","),
-      ...params.filter
+      ...params.filter,
+      as: params.viewAs
     });
     return this.request("GET", `/${type}/`, { query });
   }
@@ -355,9 +382,12 @@ var OwV2Client = class {
       cursor = page.has_more && page.next_cursor ? page.next_cursor : void 0;
     } while (cursor);
   }
-  /** GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields. */
+  /**
+   * GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields, and `viewAs` (keel
+   * #421: the owner reads as another reader; see ListParams.viewAs).
+   */
   async get(type, id, opts = {}) {
-    const query = buildQuery({ expand: opts.expand?.join(","), fields: opts.fields?.join(",") });
+    const query = buildQuery({ expand: opts.expand?.join(","), fields: opts.fields?.join(","), as: opts.viewAs });
     return this.request("GET", `/${type}/${id}/`, { query });
   }
   /**
@@ -454,15 +484,18 @@ var OwV2Client = class {
   // -- Changes feed --------------------------------------------------------
   /**
    * GET /changes -- one page of the world's ordered change feed.
-   * Cursor is OPAQUE: persist verbatim, never parse or build one (a guest's has
-   * another shape than everyone else's).
+   * Cursor is OPAQUE: persist verbatim, never parse or build one (a guest's and a
+   * contributor's carry their view's epoch, since keel #421 for a contributor).
    * Zero/absent cursor = full export (byte-aligned with the Folder Format).
    * Reset rule: a 409 `resync_required` (err.isResyncRequired) means the key's
-   * view changed (a guest's, or its role): drop the cursor, walk from zero, and keep what the
-   * local copy holds that the new walk does not name (keel's own words; sharing is forward-only).
+   * view changed (a guest's slice, an element unhidden from a contributor, or its role): drop
+   * the cursor and walk from zero. For what the local copy holds that the walk no longer names,
+   * read err.resyncReason (keel #421, while keel's hidden mark is on): `role`, keep it; `view`,
+   * drop it (as for a delete row with reason `hidden`). Without a reason, keep it (keel's own
+   * words since PR 104; sharing is forward-only). Never empty a copy on your own.
    * Citizenship: heaviest route on the platform; default page size is polite.
-   * keel sends the cursor of a page at the head as a number (an empty page, for anyone
-   * but a guest); it is handed back as a string, like every cursor here.
+   * keel sends the cursor of a page at the head as a number (an empty page, for a key
+   * whose cursor carries no epoch); it is handed back as a string, like every cursor here.
    */
   async changes(opts = {}) {
     const query = buildQuery({ since: opts.since, limit: opts.limit ?? this.changesPageSize });
@@ -472,23 +505,27 @@ var OwV2Client = class {
   /**
    * 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
+   * re-sends nothing at the head (a guest's or a contributor'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
+   * guest's or a contributor's view epoch (null for other keys): it can move with `head` unchanged, so walk on
+   * either move. `epoch_reason` (keel #421, while keel's hidden mark is on; absent otherwise)
+   * 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.
    */
   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 };
+    const out = { head: page.head, cursor: String(page.cursor), epoch: page.epoch ?? null };
+    if (page.epoch_reason !== void 0) out.epoch_reason = page.epoch_reason;
+    return out;
   }
   /**
    * 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
    * return value; persist it for the next incremental pull (with the last page's
-   * `head` and `epoch`: the view epoch the walk ran under, for a guest).
+   * `head` and `epoch`: the view epoch the walk ran under, for a guest or a contributor).
    */
   async *changesAll(since) {
     let cursor = since;
@@ -1234,7 +1271,7 @@ function buildQuery(params) {
 
 // src/v2/types.generated.ts
 var ELEMENT_TYPES = ["ability", "character", "collective", "construct", "creature", "event", "family", "institution", "language", "law", "location", "map", "marker", "narrative", "object", "phenomenon", "pin", "relation", "species", "title", "trait", "zone"];
-var ONLYWORLDS_VERSION = "00.32.00";
+var ONLYWORLDS_VERSION = "00.32.01";
 var ELEMENT_FAMILIES = {
   ability: "abstract",
   character: "agents",

package/package.json

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