@onlyworlds/sdk 4.50.0 → 4.52.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.52.0] - 2026-10-22
+
+### Changed
+
+- **Every options object refuses an unknown key** the way `list()` did in 4.51.0: `draught`, `get`, `create`, `bulk`, `changes`, `changesAll`, `removeImage`, `redeemJoin`, `signInWithPassword`, `mintWorldKey`, `signInWithOnlyWorlds`, `completeSignIn`, `ask` and `sort` throw a TypeError naming the key and the known keys before anything is sent. A dropped key was never harmless: `atomc: true` ran a batch non-atomically, `idempotency_key` let a retry create twice, `afetr` read the whole feed, `mode` misspelt widened a draught to the caller's view. TypeScript callers were already refused at compile time; this is for plain JavaScript.
+
+## [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

package/dist/index.d.ts

@@ -2726,6 +2726,11 @@ interface OwFileDownload {
     kind: OwFileKind;
     size: number;
 }
+/**
+ * The parameters of `list()` and `listAll()`. A wire filter goes under `filter`; any key not named
+ * here is a TypeError before anything is sent (since 4.51.0; before, an unknown key was dropped and the
+ * list came back whole).
+ */
 interface ListParams {
     limit?: number;
     cursor?: string;
@@ -3159,8 +3164,9 @@ declare class OwV2Client {
      * 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 (`character_taken`); 404 for one this key cannot see; 403 for an agent seat, a
-     * player, the owner (who sets it on the world page) or a read key. A guest's view resets once.
+     * 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>;

package/dist/index.js

@@ -544,8 +544,9 @@ var OwV2Client = class {
    * 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 (`character_taken`); 404 for one this key cannot see; 403 for an agent seat, a
-   * player, the owner (who sets it on the world page) or a read key. A guest's view resets once.
+   * 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") {
@@ -574,6 +575,7 @@ var OwV2Client = class {
   // -- Element CRUD --------------------------------------------------------
   /** GET /{type}/ -- one cursor page. */
   async list(type, params = {}) {
+    only("list", params, LIST_PARAM_KEYS, "A wire filter (name, name__icontains, supertype, subtype, characters) goes under filter: { ... }.");
     const query = buildQuery({
       limit: params.limit ?? this.pageSize,
       cursor: params.cursor,
@@ -598,6 +600,7 @@ var OwV2Client = class {
    * empty means the serving is partial. Served `Cache-Control: private, no-store`.
    */
   async draught(characterId, policy = {}) {
+    only("draught", policy, ["components", "mode", "asOf", "undated", "since", "budget", "depth"]);
     const query = buildQuery({
       components: policy.components?.join(","),
       mode: policy.mode,
@@ -623,6 +626,7 @@ var OwV2Client = class {
    * #421: the owner reads as another reader; see ListParams.viewAs).
    */
   async get(type, id, opts = {}) {
+    only("get", opts, ["expand", "fields", "viewAs"]);
     const query = buildQuery({ expand: opts.expand?.join(","), fields: opts.fields?.join(","), as: opts.viewAs });
     return this.request("GET", `/${type}/${id}/`, { query });
   }
@@ -637,6 +641,7 @@ var OwV2Client = class {
    * `null` are accepted and stored as `''` (nameless Markers exist).
    */
   async create(type, element, opts = {}) {
+    only("create", opts, ["idempotencyKey"]);
     refuseKnownOf(element, "create");
     const body = sanitizePayload(element);
     if (body.id === void 0 || body.id === null || body.id === "") {
@@ -723,6 +728,7 @@ var OwV2Client = class {
    * fresh UUIDv7. Ids you supply are kept.
    */
   async bulk(items, opts = {}) {
+    only("bulk", opts, ["atomic", "idempotencyKey"]);
     items.forEach((it, index) => refuseKnownOf(it.element, `bulk: items[${index}]`));
     const body = {
       items: items.map((it, index) => {
@@ -764,6 +770,7 @@ var OwV2Client = class {
    * that is not a date and time is a 422 naming `after`.
    */
   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 });
     return { ...page, cursor: String(page.cursor) };
@@ -794,6 +801,7 @@ var OwV2Client = class {
    * `head` and `epoch`: the view epoch the walk ran under, for a guest or a contributor).
    */
   async *changesAll(since, opts = {}) {
+    only("changesAll", opts, ["after"]);
     let cursor = since;
     let page;
     do {
@@ -883,6 +891,7 @@ var OwV2Client = class {
    * ticket is still unspent).
    */
   async removeImage(keyOrUrl, opts = {}) {
+    only("removeImage", opts, ["ticket"]);
     const ticket = opts.ticket ?? await this.createRemovalTicket(keyOrUrl);
     let res;
     try {
@@ -1068,6 +1077,7 @@ var OwV2Client = class {
    * for one ignores `character`.
    */
   async redeemJoin(code, opts = {}) {
+    only("redeemJoin", opts, ["name", "agentName", "character"]);
     const body = { code };
     if (opts.name !== void 0) body.name = opts.name;
     if (opts.agentName !== void 0) body.agent_name = opts.agentName;
@@ -1096,6 +1106,7 @@ var OwV2Client = class {
    * `failed` (anything else, with keel's message). The password is never in an error.
    */
   async signInWithPassword(opts) {
+    only("signInWithPassword", opts, ["email", "username", "password", "tokenName"]);
     const { email, username, password, tokenName } = opts ?? {};
     const login = typeof email === "string" ? email.trim() : "";
     const user = typeof username === "string" ? username.trim() : "";
@@ -1376,6 +1387,7 @@ var OwV2Client = class {
    * token only; no Idempotency-Key.
    */
   async mintWorldKey(worldId, opts = {}) {
+    only("mintWorldKey", opts, ["scope", "name"]);
     if (this.keyKind !== "account") {
       throw new TypeError("mintWorldKey needs an account token (ow_a_)");
     }
@@ -1395,6 +1407,7 @@ var OwV2Client = class {
    * is sent; any client, keyless included. The handoff sheet: Orrery `keel/signin-handoff.md` §3.
    */
   async signInWithOnlyWorlds(opts) {
+    only("signInWithOnlyWorlds", opts, ["clientId", "redirectUri", "resume", "storage", "navigate"]);
     return beginSignIn(this.baseUrl, opts);
   }
   /**
@@ -1407,6 +1420,7 @@ var OwV2Client = class {
    * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`.
    */
   async completeSignIn(opts) {
+    only("completeSignIn", opts, ["clientId", "storage", "url"]);
     return completeSignIn(this.baseUrl, this.fetchImpl, opts);
   }
   // -- Ask your world (keel #159) -------------------------------------------
@@ -1421,6 +1435,7 @@ var OwV2Client = class {
    * them counts. 422 for a question over 500 characters or context past its limits.
    */
   async ask(req) {
+    only("ask", req, ["worldId", "question", "context"]);
     if (this.keyKind !== "account") {
       throw new TypeError("ask needs an account token (ow_a_): the proxy meters per account");
     }
@@ -1440,6 +1455,7 @@ var OwV2Client = class {
    * to 200 characters, anchors up to 120.
    */
   async sort(req) {
+    only("sort", req, ["worldId", "notes", "slice"]);
     if (this.keyKind !== "account") {
       throw new TypeError("sort needs an account token (ow_a_): the proxy meters per account");
     }
@@ -1637,6 +1653,15 @@ function objectKey(keyOrUrl) {
   if (!/^https?:\/\//i.test(keyOrUrl)) return keyOrUrl;
   return decodeURIComponent(new URL(keyOrUrl).pathname.replace(/^\/+/, ""));
 }
+var LIST_PARAM_KEYS = ["limit", "cursor", "ids", "createdBy", "expand", "fields", "filter", "viewAs"];
+function only(method, obj, keys, hint = "") {
+  if (!obj || typeof obj !== "object") return;
+  for (const k of Object.keys(obj)) {
+    if (!keys.includes(k)) {
+      throw new TypeError(`${method}: unknown parameter '${k}'. ${hint ? hint + " " : ""}The keys are ${keys.join(", ")}. Nothing was sent.`);
+    }
+  }
+}
 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.50.0",
+  "version": "4.52.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {