@onlyworlds/sdk 4.49.0 → 4.51.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.51.0] - 2026-10-22
+
+### Changed
+
+- **`list()` and `listAll()` refuse an unknown top-level key** with a TypeError before anything is sent, naming the key and where a wire filter goes (`filter: { name__icontains: ... }`). Until now an unknown key was dropped without a word, so a plain-JavaScript caller who wrote `list('character', { name__icontains: 'probe' })` got every Character, unfiltered, and TypeScript's compile-time check was the only fence. A cleanup script written that way deleted 99 Characters on a test world on 2026-10-22; this is the SDK's half of the lesson. A caller who passed a stray key by accident now hears about it; the known keys are `limit`, `cursor`, `ids`, `createdBy`, `expand`, `fields`, `filter`, `viewAs`.
+
+## [4.50.0] - 2026-10-22
+
+### Added
+
+- `setMyCharacter(characterId | null)`: `PUT /me/character`, a person member's pick of the roster Character that is them in this world (keel PR 160, #533); answers the `/me` body. `err.isCharacterHidden` for the 422 `character_hidden` it and the member PATCH answer.
+- `hidden?: true` on every element body (`OwElementBase`): present only when the owner or a co-builder hid the element and this reader still sees it (keel #537); never on other readers' bodies, ignored in a write.
+- `site` joins `OwWriteDoor`: a write or delete the owner made signed in on onlyworlds.com (keel #530).
+
 ## [4.49.0] - 2026-10-22
 
 ### Changed

package/dist/index.d.ts

@@ -29,8 +29,10 @@ interface OwElementBase {
     created_by?: string | null;
     /** The membership whose write last changed this element (server-managed, read-only); null for the world's owner and for anything last changed before writes recorded it. */
     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`, or `server` (keel's own writes). The first three are agent-made. Null for anything last changed before writes recorded it. */
-    changed_via?: 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | 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;
+    /** 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(). */
     known_of?: true;
     /** Namespaced extension fields (atlas_* / shadow_* / x_*), returned verbatim. */
@@ -2920,6 +2922,11 @@ declare class OwApiError extends Error {
      * previewJoin, whose `characters` mark each `taken`. The code is not spent.
      */
     get isCharacterTaken(): boolean;
+    /**
+     * setMyCharacter, or the member PATCH's `character` (keel #421, PR 160): the picked Character is
+     * hidden (422 `character_hidden`, `param` character). Unhide it first, or pick another.
+     */
+    get isCharacterHidden(): boolean;
     /**
      * The `character` sent was refused (422 `invalid_request`, `param` character). On redeemJoin
      * at a table (keel #422 PR 2): the pick is off the link's list, hidden or deleted since the
@@ -3148,6 +3155,15 @@ declare class OwV2Client {
      * creates; null for the owner) and the member's Character. A world key's call; an account
      * token is a TypeError before sending.
      */
+    /**
+     * PUT /me/character -- pick the roster Character that is you in this world, or none (keel PR 160,
+     * #533). A person member's write key with its PIN; answers GET /me's body. 422 for a hidden
+     * Character (`character_hidden`, `err.isCharacterHidden`), a guest's pick it did not make, or a
+     * taken Character (`invalid_request`, `param` character); 404 for one this key cannot see; 403 for
+     * an agent seat, a player, the owner (whose own is the world's `owner_character`, set with
+     * patchWorld) or a read key. A guest's view resets once.
+     */
+    setMyCharacter(character: string | null): Promise<OwMe>;
     me(): Promise<OwMe>;
     /**
      * GET /members -- the world's roster: each member's id (null for the owner), kind, role,

package/dist/index.js

@@ -191,6 +191,13 @@ var OwApiError = class extends Error {
   get isCharacterTaken() {
     return this.status === 422 && this.code === "character_taken";
   }
+  /**
+   * setMyCharacter, or the member PATCH's `character` (keel #421, PR 160): the picked Character is
+   * hidden (422 `character_hidden`, `param` character). Unhide it first, or pick another.
+   */
+  get isCharacterHidden() {
+    return this.status === 422 && this.code === "character_hidden";
+  }
   /**
    * The `character` sent was refused (422 `invalid_request`, `param` character). On redeemJoin
    * at a table (keel #422 PR 2): the pick is off the link's list, hidden or deleted since the
@@ -533,6 +540,20 @@ var OwV2Client = class {
    * creates; null for the owner) and the member's Character. A world key's call; an account
    * token is a TypeError before sending.
    */
+  /**
+   * PUT /me/character -- pick the roster Character that is you in this world, or none (keel PR 160,
+   * #533). A person member's write key with its PIN; answers GET /me's body. 422 for a hidden
+   * Character (`character_hidden`, `err.isCharacterHidden`), a guest's pick it did not make, or a
+   * taken Character (`invalid_request`, `param` character); 404 for one this key cannot see; 403 for
+   * an agent seat, a player, the owner (whose own is the world's `owner_character`, set with
+   * patchWorld) or a read key. A guest's view resets once.
+   */
+  async setMyCharacter(character) {
+    if (this.keyKind === "account") {
+      throw new TypeError("setMyCharacter needs a world key: an account token is not a member of one world");
+    }
+    return this.request("PUT", "/me/character", { write: true, body: { character } });
+  }
   async me() {
     if (this.keyKind === "account") {
       throw new TypeError("me needs a world key: an account token is not a member of one world");
@@ -554,6 +575,13 @@ var OwV2Client = class {
   // -- Element CRUD --------------------------------------------------------
   /** GET /{type}/ -- one cursor page. */
   async list(type, params = {}) {
+    for (const k of Object.keys(params)) {
+      if (!LIST_PARAM_KEYS.has(k)) {
+        throw new TypeError(
+          `list: unknown parameter '${k}'. A wire filter (name, name__icontains, supertype, subtype, characters) goes under filter: { ${k}: ... }; the other keys are ${[...LIST_PARAM_KEYS].join(", ")}. Nothing was sent: an unknown key was once dropped, and the list came back whole.`
+        );
+      }
+    }
     const query = buildQuery({
       limit: params.limit ?? this.pageSize,
       cursor: params.cursor,
@@ -1617,6 +1645,7 @@ function objectKey(keyOrUrl) {
   if (!/^https?:\/\//i.test(keyOrUrl)) return keyOrUrl;
   return decodeURIComponent(new URL(keyOrUrl).pathname.replace(/^\/+/, ""));
 }
+var LIST_PARAM_KEYS = /* @__PURE__ */ new Set(["limit", "cursor", "ids", "createdBy", "expand", "fields", "filter", "viewAs"]);
 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.49.0",
+  "version": "4.51.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {