@onlyworlds/sdk 4.51.0 → 4.53.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.53.0] - 2026-10-22
+
+### Changed
+
+- **The last seven options objects refuse an unknown key** too: `patch` and `editLinks` (`ifMatch`; the edit itself is `{add, remove}`), `uploadImage`, `createFileTicket`, `uploadFile`, `createWorldLink` and `createSeat`. With 4.51.0 and 4.52.0 every method of the client that takes an object now names a stray key before anything is sent; a client that drops a key it does not know has no place left.
+
+## [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

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;

package/dist/index.js

@@ -575,13 +575,7 @@ 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.`
-        );
-      }
-    }
+    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,
@@ -606,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,
@@ -631,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 });
   }
@@ -645,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 === "") {
@@ -676,6 +673,7 @@ var OwV2Client = class {
    * it for today's unconditional write.
    */
   async patch(type, id, partial, opts = {}) {
+    only("patch", opts, ["ifMatch"]);
     refuseKnownOf(partial, "patch");
     return this.request("PATCH", `/${type}/${id}/`, { write: true, body: sanitizePayload(partial), ifMatch: opts.ifMatch });
   }
@@ -695,6 +693,8 @@ var OwV2Client = class {
    * moves the element too.
    */
   async editLinks(type, id, field, edit, opts = {}) {
+    only("editLinks", opts, ["ifMatch"]);
+    only("editLinks", edit, ["add", "remove"], "The edit is { add?: string[], remove?: string[] }.");
     return this.request("POST", `/${type}/${id}/links/${field}`, { write: true, body: edit, ifMatch: opts.ifMatch });
   }
   /**
@@ -731,6 +731,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) => {
@@ -772,6 +773,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) };
@@ -802,6 +804,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 {
@@ -841,6 +844,7 @@ var OwV2Client = class {
    * needs a new one.
    */
   async uploadImage(image, opts = {}) {
+    only("uploadImage", opts, ["key", "ticket"]);
     const ticket = opts.ticket ?? await this.createMediaTicket();
     const size = typeof Blob !== "undefined" && image instanceof Blob ? image.size : image.byteLength;
     if (size > ticket.max_bytes) {
@@ -891,6 +895,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 {
@@ -943,6 +948,7 @@ var OwV2Client = class {
    * `retryAfter`; 503 `media_unavailable`.
    */
   async createFileTicket(type, id, req) {
+    only("createFileTicket", req, ["name", "kind", "size", "label"]);
     const { name, size } = req;
     if (typeof name !== "string" || name.trim() === "") {
       throw new TypeError("createFileTicket needs the file's name, with its extension");
@@ -983,6 +989,7 @@ var OwV2Client = class {
    * upload succeeds: another file needs a new one.
    */
   async uploadFile(type, id, file, opts = {}) {
+    only("uploadFile", opts, ["name", "kind", "label", "ticket", "onProgress"]);
     const size = typeof Blob !== "undefined" && file instanceof Blob ? file.size : file.byteLength;
     let ticket = opts.ticket;
     if (!ticket) {
@@ -1076,6 +1083,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;
@@ -1104,6 +1112,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() : "";
@@ -1246,6 +1255,7 @@ var OwV2Client = class {
    * `not_found` (`err.isNotFound`). A world key is a TypeError before anything is sent.
    */
   async createWorldLink(worldId, opts) {
+    only("createWorldLink", opts, ["reader", "role", "days", "inviterName", "withCharacter", "character", "preview", "maxUses", "characters"]);
     if (this.keyKind !== "account") {
       throw new TypeError("createWorldLink needs an account token (ow_a_): only the world's owner makes links");
     }
@@ -1297,6 +1307,7 @@ var OwV2Client = class {
    * its key: rekeySeat gives it a new one (or removeSeat and make another). Needs the client's `ow_a_` token.
    */
   async createSeat(worldId, opts) {
+    only("createSeat", opts, ["name", "role", "character"]);
     if (this.keyKind !== "account") {
       throw new TypeError("createSeat needs an account token (ow_a_): a seat is made by the person who answers for it");
     }
@@ -1384,6 +1395,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_)");
     }
@@ -1403,6 +1415,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);
   }
   /**
@@ -1415,6 +1428,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) -------------------------------------------
@@ -1429,6 +1443,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");
     }
@@ -1448,6 +1463,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");
     }
@@ -1645,7 +1661,15 @@ 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"]);
+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.51.0",
+  "version": "4.53.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {