@onlyworlds/sdk 4.43.0 → 4.45.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.45.0] - 2026-10-22
+
+### Added
+- `hide(type, id)` and `unhide(type, id)`: the hidden mark's writes, `PUT` and `DELETE /{type}/{id}/hidden` (keel #421), for the parlor (Temper, h66 #9720). 204; the element's body and `change_seq` do not move.
+- `listAccountWorlds()` (`GET /account/worlds`, `OwAccountWorld[]`: owned and shared worlds with their keys by name and last four) and `mintWorldKey(worldId, { scope, name })` (`POST /account/worlds/{id}/keys`, `OwMintedKey` with the full key once), the two account routes Atlas and the parlor hand-rolled. Account token only.
+
+## [4.44.0] - 2026-10-22
+
+### Added
+- `changes({ after })` and `changesAll(since, { after })`: keel #514 (PR 152, D142, live 2026-10-22 00:55), `GET /changes?after=<ISO time>` returns only the changes made at or after that time, a filter and not a position: order, `cursor`, `has_more` and `head` are unchanged, and the window is read by passing the cursor back as `since` with the same `after`. A bad value is a 422 naming `after`.
+
 ## [4.43.0] - 2026-10-22
 
 ### Added

package/dist/index.d.ts

@@ -2426,6 +2426,39 @@ interface OwSignedIn {
     last4: string;
 }
 /** One live agent seat, as GET /account/worlds/{id}/seats lists it (keel #355, D106). No key or secret. */
+/**
+ * One world of the account, from GET /account/worlds: owned (`role: 'owner'`) or shared
+ * (`'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).
+ */
+interface OwAccountWorld {
+    id: string;
+    name: string;
+    role: 'owner' | 'collaborator';
+    member_role?: OwMemberRole;
+    public_read: boolean;
+    keys: Array<{
+        name: string;
+        last4: string;
+        scope: 'READ' | 'WRITE';
+        revoked: boolean;
+    }>;
+}
+/**
+ * A world key as minted by POST /account/worlds/{id}/keys: the row the account's key list shows,
+ * plus the full key once in `key` (never shown again). A member's key carries its `member` label
+ * (keel D72); an owner's row has no such field.
+ */
+interface OwMintedKey {
+    id: string;
+    name: string;
+    last4: string;
+    scope: 'READ' | 'WRITE';
+    last_used_at: string | null;
+    revoked: boolean;
+    key: string;
+    member?: Record<string, unknown>;
+}
 interface OwSeat {
     /** The seat's membership id: removeSeat takes it, and GET /members names the seat by it. */
     id: string;
@@ -3075,10 +3108,17 @@ declare class OwV2Client {
      * 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 a key
      * whose cursor carries no epoch); it is handed back as a string, like every cursor here.
+     * `after` (keel #514, D142): only the changes made at or after an ISO 8601 time (`updated_at` of an
+     * upsert, `deleted_at` of a delete; no offset means UTC). A filter, not a position: the order,
+     * `cursor`, `has_more` and `head` are as without it, so to read the whole window pass the cursor
+     * back as `since` with the same `after` until `has_more` is false (`changesAll` does). "Since
+     * yesterday" by the clock; a kept cursor is still the exact "since my last visit". Anything
+     * that is not a date and time is a 422 naming `after`.
      */
     changes(opts?: {
         since?: string;
         limit?: number;
+        after?: string;
     }): Promise<OwChangesPage>;
     /**
      * GET /changes?head=true -- where the feed is now, without a page: no element is read.
@@ -3105,7 +3145,9 @@ declare class OwV2Client {
      * 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 or a contributor).
      */
-    changesAll(since?: string): AsyncGenerator<OwChange, {
+    changesAll(since?: string, opts?: {
+        after?: string;
+    }): AsyncGenerator<OwChange, {
         cursor: string;
         head: number;
         epoch: number | null;
@@ -3418,6 +3460,32 @@ declare class OwV2Client {
      * goes with it, any other stays. Needs the client's `ow_a_` token.
      */
     removeSeat(worldId: string, seatId: string): Promise<void>;
+    /**
+     * PUT /{type}/{id}/hidden -- hide an element (keel #421). The owner's key or a co-builder's
+     * (a person's or a seat's) with its PIN; hiding a hidden element again changes nothing, and
+     * the element's body and `change_seq` do not move. Hidden, it is seen only by the owner, the
+     * co-builders and the member who created it; to every other key it is a 404, left out of
+     * lists, search, counts and the link arrays that name it. 204, no body. No Idempotency-Key.
+     */
+    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 /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.
+     */
+    listAccountWorlds(): Promise<OwAccountWorld[]>;
+    /**
+     * POST /account/worlds/{id}/keys -- mint a world key, `scope` `'write'` (the default) or
+     * `'read'`, `name` as the key list shows it (at most 255 characters). The full key comes back
+     * once in `key`. The owner mints a world key; a member mints their own member key, 409
+     * `pin_required` (`err.isPinRequired`) for a write key while the account has no PIN. Account
+     * token only; no Idempotency-Key.
+     */
+    mintWorldKey(worldId: string, opts?: {
+        scope?: 'read' | 'write';
+        name?: string;
+    }): Promise<OwMintedKey>;
     /**
      * POST /account/ask -- a question about a world the account owns or is in, answered by
      * keel's AI proxy from `context` only (build it with buildAskContext from the elements
@@ -4460,4 +4528,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 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, 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, 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, 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 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, 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, 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, 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, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -558,9 +558,15 @@ var OwV2Client = class {
    * 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 a key
    * whose cursor carries no epoch); it is handed back as a string, like every cursor here.
+   * `after` (keel #514, D142): only the changes made at or after an ISO 8601 time (`updated_at` of an
+   * upsert, `deleted_at` of a delete; no offset means UTC). A filter, not a position: the order,
+   * `cursor`, `has_more` and `head` are as without it, so to read the whole window pass the cursor
+   * back as `since` with the same `after` until `has_more` is false (`changesAll` does). "Since
+   * yesterday" by the clock; a kept cursor is still the exact "since my last visit". Anything
+   * that is not a date and time is a 422 naming `after`.
    */
   async changes(opts = {}) {
-    const query = buildQuery({ since: opts.since, limit: opts.limit ?? this.changesPageSize });
+    const query = buildQuery({ since: opts.since, limit: opts.limit ?? this.changesPageSize, after: opts.after });
     const page = await this.request("GET", "/changes/", { query });
     return { ...page, cursor: String(page.cursor) };
   }
@@ -589,11 +595,11 @@ var OwV2Client = class {
    * 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 or a contributor).
    */
-  async *changesAll(since) {
+  async *changesAll(since, opts = {}) {
     let cursor = since;
     let page;
     do {
-      page = await this.changes({ since: cursor });
+      page = await this.changes({ since: cursor, after: opts.after });
       for (const op of page.changes) yield op;
       cursor = page.cursor;
     } while (page.has_more);
@@ -1128,6 +1134,49 @@ var OwV2Client = class {
     }
     await this.request("DELETE", `/account/worlds/${encodeURIComponent(worldId)}/seats/${encodeURIComponent(seatId)}`);
   }
+  // -- The hidden mark (keel #421) ------------------------------------------
+  /**
+   * PUT /{type}/{id}/hidden -- hide an element (keel #421). The owner's key or a co-builder's
+   * (a person's or a seat's) with its PIN; hiding a hidden element again changes nothing, and
+   * the element's body and `change_seq` do not move. Hidden, it is seen only by the owner, the
+   * co-builders and the member who created it; to every other key it is a 404, left out of
+   * lists, search, counts and the link arrays that name it. 204, no body. No Idempotency-Key.
+   */
+  async hide(type, id) {
+    await this.request("PUT", `/${type}/${id}/hidden`, { write: true, body: {}, allowEmpty: true });
+  }
+  /** DELETE /{type}/{id}/hidden -- clear the mark; an element that is not hidden stays as it is. 204. */
+  async unhide(type, id) {
+    await this.request("DELETE", `/${type}/${id}/hidden`, { write: true, allowEmpty: true });
+  }
+  // -- 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
+   * name and last four (a member sees only their own keys on a shared world). Account token only.
+   */
+  async listAccountWorlds() {
+    if (this.keyKind !== "account") {
+      throw new TypeError("listAccountWorlds needs an account token (ow_a_)");
+    }
+    const page = await this.request("GET", "/account/worlds");
+    return page.data;
+  }
+  /**
+   * POST /account/worlds/{id}/keys -- mint a world key, `scope` `'write'` (the default) or
+   * `'read'`, `name` as the key list shows it (at most 255 characters). The full key comes back
+   * once in `key`. The owner mints a world key; a member mints their own member key, 409
+   * `pin_required` (`err.isPinRequired`) for a write key while the account has no PIN. Account
+   * token only; no Idempotency-Key.
+   */
+  async mintWorldKey(worldId, opts = {}) {
+    if (this.keyKind !== "account") {
+      throw new TypeError("mintWorldKey needs an account token (ow_a_)");
+    }
+    const body = {};
+    if (opts.scope !== void 0) body.scope = opts.scope;
+    if (opts.name !== void 0) body.name = opts.name;
+    return this.request("POST", `/account/worlds/${encodeURIComponent(worldId)}/keys`, { write: true, body });
+  }
   // -- Ask your world (keel #159) -------------------------------------------
   /**
    * POST /account/ask -- a question about a world the account owns or is in, answered by

package/package.json

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