@onlyworlds/sdk 4.46.0 → 4.48.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.48.0] - 2026-10-22
+
+### Added
+
+- `listHidden()`: `GET /world/hidden`, the world's hidden elements newest first as `OwHiddenRow[]` (`type`, `id`, `set_at`, `set_by`; keel #421). Any key of the owner's or a co-builder's; served with `Cache-Control: no-store`, so read it each time. For the parlor, whose host room marks what it hid (Temper, h66 #9778).
+
+## [4.47.0] - 2026-10-22
+
+### Added
+- `draught(characterId, policy)`: `GET /character/{id}/context` (keel PR 155, D143, live 2026-10-22 02:05), one Character's context in one read, typed as `OwDraught` with the policy's seven keys (`components`, `mode`, `asOf`, `undated`, `since`, `budget`, `depth`) as `OwDraughtPolicy`.
+- `list` takes `ids` (1 to 200, the list's own order; one the key cannot see is absent) and `createdBy` (a membership id, or `'owner'`), the two list filters of the same PR; both were already reachable through `filter`.
+
 ## [4.46.0] - 2026-10-22
 
 ### Added

package/dist/index.d.ts

@@ -1975,6 +1975,17 @@ interface OwChangeDelete {
 }
 /** Why a /changes delete row says the element left the reader's view (keel #421). */
 type OwDeleteReason = 'deleted' | 'hidden' | 'out_of_view';
+/** One row of GET /world/hidden (keel #421): an element the owner or a co-builder hid. */
+interface OwHiddenRow {
+    /** The element's type. */
+    type: ElementType | string;
+    /** The element's id. */
+    id: string;
+    /** When it was hidden (ISO 8601). */
+    set_at: string;
+    /** The membership (a person's or a seat's) that hid it, or null when the world's owner did (as an element's `created_by`). */
+    set_by: string | null;
+}
 /**
  * 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),
@@ -2431,6 +2442,83 @@ interface OwSignedIn {
  * (`'collaborator'`, with `member_role` the membership's role). Keys by name and last four only,
  * never the key; on a shared world only the member's own keys (keel H8).
  */
+/** The draught's policy (keel PR 155, D143): what GET /character/{id}/context serves and how. */
+interface OwDraughtPolicy {
+    /** Sections to serve; default every one but `messages`. */
+    components?: OwDraughtComponent[];
+    /** `voice`: her slice, as she would read (default). `act`: through the caller's own view. */
+    mode?: 'voice' | 'act';
+    /** The horizon in the world's time unit; default the world's `time_range_current`. */
+    asOf?: number;
+    /** Undated Events: `include` (default, marked `dated: false`, after the dated) or `exclude`. */
+    undated?: 'include' | 'exclude';
+    /** For `recent`: a /changes cursor, or an ISO 8601 time (as /changes' `after`). Absent, `recent` is empty. */
+    since?: string;
+    /** Items per section, 1 to 1000, default 50; `cut` says what was dropped. */
+    budget?: number;
+    /** The sheet's reach: 1 (default) what her own element links to, 0 none. */
+    depth?: 0 | 1;
+}
+type OwDraughtComponent = 'self' | 'role' | 'work' | 'style' | 'events' | 'knowledge' | 'names' | 'sheet' | 'recent' | 'messages' | 'roster';
+/** An element as the draught serves it: the list route's body plus how it got here. */
+type OwDraughtItem = OwElement & {
+    /** The link fields that brought it (on the element, or on her own element in `sheet`). */
+    via: string[];
+    /** How many of the packet's elements link to it. */
+    her_links: number;
+    grade: 'whole' | 'known_of';
+    /** On an Event: false when it carries no date (ranked after the dated). */
+    dated?: boolean;
+};
+/** One Character's context in one read, GET /character/{id}/context (keel PR 155, D143; the draught). */
+interface OwDraught {
+    world: {
+        id: string;
+        name: string;
+        description: string;
+    };
+    /** The world's own time fields, as it carries them. */
+    calendar: Record<string, unknown>;
+    as_of: number | null;
+    now: number | null;
+    mode: 'voice' | 'act';
+    /** The policy served under, every key resolved. */
+    policy: Record<string, unknown>;
+    /** {section: items the budget dropped}; empty when whole. */
+    cut: Record<string, number>;
+    recent_cursor: string | null;
+    recent_more: boolean | null;
+    /** Her own element (`self: true`), or a stub when this reader knows her only as known of. */
+    character: (OwElement & {
+        self: true;
+        grade: 'whole' | 'known_of';
+    }) | null;
+    role?: OwDraughtItem[];
+    work?: OwDraughtItem[];
+    style?: OwDraughtItem | null;
+    events?: OwDraughtItem[];
+    knowledge?: OwDraughtItem[];
+    /** Everything else that names her, by type. */
+    names?: Record<string, OwDraughtItem[]>;
+    sheet?: OwDraughtItem[];
+    messages?: OwDraughtItem[];
+    recent?: Array<{
+        op: 'upsert' | 'delete';
+        type: string;
+        id: string;
+        when: string | null;
+        who: string | null;
+        [k: string]: unknown;
+    }>;
+    roster?: Array<{
+        id: string | null;
+        kind: string;
+        role: string;
+        character: string | null;
+        status: string;
+        name: string;
+    }>;
+}
 interface OwAccountWorld {
     id: string;
     name: string;
@@ -2639,6 +2727,10 @@ interface OwFileDownload {
 interface ListParams {
     limit?: number;
     cursor?: string;
+    /** Only these ids (1 to 200), in the list's own order; one this key cannot see is simply absent (keel PR 155). */
+    ids?: string[];
+    /** A membership id, or `'owner'` for the owner's own writes: only what that member created (keel PR 155). */
+    createdBy?: string;
     /** One-level stub expansion, e.g. ['friends', 'location']. */
     expand?: string[];
     /** Sparse include-set of field names. */
@@ -3065,6 +3157,18 @@ declare class OwV2Client {
     members(): Promise<OwMember[]>;
     /** GET /{type}/ -- one cursor page. */
     list(type: ElementType | string, params?: ListParams): Promise<OwPage>;
+    /**
+     * GET /character/{id}/context -- the draught (keel PR 155, D143): what one Character knows, as the
+     * recorded world holds it, in one read: her element, what she holds and sits in, her open work,
+     * how she works, the Events she was in, the Narratives she knows, everything else that names
+     * her, her sheet, what changed around her (`since`), and who plays whom; the world's name and
+     * calendar beside. Every body is the list route's for the same reader, with `via`, `her_links`
+     * and `grade`; nothing is inferred. The owner's keys, co-builders and contributors for any
+     * Character they can see; a player seat or a guest for its own Character only (another id is
+     * 404). `asOf` is a filter on the elements' own dates, not time travel. A `cut` that is not
+     * empty means the serving is partial. Served `Cache-Control: private, no-store`.
+     */
+    draught(characterId: string, policy?: OwDraughtPolicy): Promise<OwDraught>;
     /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
     listAll(type: ElementType | string, params?: Omit<ListParams, 'cursor'>): AsyncGenerator<OwElement>;
     /**
@@ -3529,6 +3633,12 @@ declare class OwV2Client {
     hide(type: ElementType | string, id: string): Promise<void>;
     /** DELETE /{type}/{id}/hidden -- clear the mark; an element that is not hidden stays as it is. 204. */
     unhide(type: ElementType | string, id: string): Promise<void>;
+    /**
+     * GET /world/hidden -- every hidden element of the world, newest first: `{type, id, set_at,
+     * set_by}` each (`set_by` null when the owner hid it). Any key of the owner's or a co-builder's;
+     * any other key is a 403. Served with `Cache-Control: no-store`: read it each time, keep no copy.
+     */
+    listHidden(): Promise<OwHiddenRow[]>;
     /**
      * GET /account/worlds -- every world the account owns or is a member of, with its keys by
      * name and last four (a member sees only their own keys on a shared world). Account token only.
@@ -4607,4 +4717,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 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, 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, 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, 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, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, 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 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, 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, 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, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -559,11 +559,36 @@ var OwV2Client = class {
       cursor: params.cursor,
       expand: params.expand?.join(","),
       fields: params.fields?.join(","),
+      ids: params.ids?.join(","),
+      created_by: params.createdBy,
       ...params.filter,
       as: params.viewAs
     });
     return this.request("GET", `/${type}/`, { query });
   }
+  /**
+   * GET /character/{id}/context -- the draught (keel PR 155, D143): what one Character knows, as the
+   * recorded world holds it, in one read: her element, what she holds and sits in, her open work,
+   * how she works, the Events she was in, the Narratives she knows, everything else that names
+   * her, her sheet, what changed around her (`since`), and who plays whom; the world's name and
+   * calendar beside. Every body is the list route's for the same reader, with `via`, `her_links`
+   * and `grade`; nothing is inferred. The owner's keys, co-builders and contributors for any
+   * Character they can see; a player seat or a guest for its own Character only (another id is
+   * 404). `asOf` is a filter on the elements' own dates, not time travel. A `cut` that is not
+   * empty means the serving is partial. Served `Cache-Control: private, no-store`.
+   */
+  async draught(characterId, policy = {}) {
+    const query = buildQuery({
+      components: policy.components?.join(","),
+      mode: policy.mode,
+      as_of: policy.asOf,
+      undated: policy.undated,
+      since: policy.since,
+      budget: policy.budget,
+      depth: policy.depth
+    });
+    return this.request("GET", `/character/${characterId}/context`, { query });
+  }
   /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
   async *listAll(type, params = {}) {
     let cursor;
@@ -1302,6 +1327,15 @@ var OwV2Client = class {
   async unhide(type, id) {
     await this.request("DELETE", `/${type}/${id}/hidden`, { write: true, allowEmpty: true });
   }
+  /**
+   * GET /world/hidden -- every hidden element of the world, newest first: `{type, id, set_at,
+   * set_by}` each (`set_by` null when the owner hid it). Any key of the owner's or a co-builder's;
+   * any other key is a 403. Served with `Cache-Control: no-store`: read it each time, keep no copy.
+   */
+  async listHidden() {
+    const page = await this.request("GET", "/world/hidden");
+    return page.data;
+  }
   // -- The account's worlds and keys (account token) -----------------------
   /**
    * GET /account/worlds -- every world the account owns or is a member of, with its keys by

package/package.json

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