@onlyworlds/sdk 4.63.0 → 4.64.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.64.0] - 2026-10-23
+
+### Changed
+
+- **Every options object in the package now refuses an unknown key**, not only the client's typed methods (4.51.0 to 4.53.0): `readWorldFile`, `parseDate`, `resolveCalendarLens`, `lookupWorld`, `renderElement`, `planPhoto`, `preparePhoto`, the client's `request()` escape hatch, `listAll` (with its own keys: a `cursor` it was handed was overwritten unread), the deprecated `tokens.consume` and `new OwSignInError`'s third argument throw a `TypeError` naming the function, the key and the keys it takes, before anything is read, decoded, parsed or sent. A dropped key was never harmless: `readWorldFile(bytes, { maxbytes: 1e6 })` read with the 2 GiB budget, `parseDate(cfg, input, { Now: 12 })` parsed as if the world had no now, and W11's `list('character', { name__icontains })` read every Character and a cleanup script deleted 99 of them (2026-10-22). A plain-JavaScript caller passing a misspelt key will now see a `TypeError` where the call used to run with the default; TypeScript callers were already refused at compile time. `writeWorldFile` and `typeWord` keep their refusals on the same shared check; `typeWord`'s message now reads like the others (`typeWord: unknown option 'plural'. The keys are supertype, many.`).
+- Tests: one test calls every options parameter of the exported surface with `{ __unknown__: 1 }` and asserts a `TypeError` naming the key, nothing sent; a second reads `src/index.ts` with the TypeScript checker and fails on any exported object parameter that is neither in that list nor named as data (a calendar config, a world index, an element), so a new options object cannot ship unfenced. Watched failing on mutants of the `readWorldFile`, `parseDate`, `preparePhoto` and `request()` fences, and on an exported options function added without one.
+
 ## [4.63.0] - 2026-10-23
 
 ### Added

package/dist/index.d.ts

@@ -4371,7 +4371,8 @@ interface OwReadWorldFileOptions {
 declare function simpleCaseFold(text: string): string;
 /**
  * Read a world file. Throws `OwWorldFileError` saying why, having returned
- * nothing; the caller writes only what this returns.
+ * nothing; the caller writes only what this returns. An unknown option is a
+ * `TypeError` before the bytes are looked at.
  */
 declare function readWorldFile(bytes: Uint8Array, opts?: OwReadWorldFileOptions): OwReadWorldFile;
 interface OwWriteWorldFileOptions {
@@ -4535,13 +4536,13 @@ declare function buildWorldIndex<T extends OwLookupElement>(elements: Iterable<T
  * elements whose other text holds the question's words. An empty question
  * returns no hits.
  */
-declare function lookupWorld<T extends OwLookupElement>(index: OwWorldIndex<T>, question: string, { limit }?: OwLookupOptions): OwLookupHit<T>[];
+declare function lookupWorld<T extends OwLookupElement>(index: OwWorldIndex<T>, question: string, opts?: OwLookupOptions): OwLookupHit<T>[];
 /**
  * A compact text card for one element, for a person or a model: name, type,
  * kind, description, its fields, its links by name (or how many point outside
  * the data), and what links to it.
  */
-declare function renderElement<T extends OwLookupElement>(element: T, index: OwWorldIndex<T>, { descMax, linkMax, incomingMax }?: OwRenderOptions): string;
+declare function renderElement<T extends OwLookupElement>(element: T, index: OwWorldIndex<T>, opts?: OwRenderOptions): string;
 
 /**
  * Context for keel's AI proxy (POST /api/v2/account/ask, Keel #159): the elements a
@@ -4641,9 +4642,9 @@ declare function planPhoto(source: {
     type: string;
 }, opts?: OwPhotoOptions): OwPhotoPlan;
 /**
- * Shrink and convert a picture for upload. Throws `TypeError` outside a
- * browser, for a file the browser cannot decode, or when the result is still
- * over `maxBytes`.
+ * Shrink and convert a picture for upload. Throws `TypeError` for an unknown
+ * option (before anything is decoded), outside a browser, for a file the
+ * browser cannot decode, or when the result is still over `maxBytes`.
  */
 declare function preparePhoto(input: Blob, opts?: OwPhotoOptions): Promise<OwPreparedPhoto>;
 
@@ -4908,7 +4909,8 @@ declare function worldCalendars(elements: Iterable<OwCalendarElement>): WorldCal
  *
  * `fallbackToOnly`: when no calendar was ever chosen (`activeId` is `undefined`, not
  * `null`) and the world holds exactly one, use it. `null` is an explicit "no calendar" and
- * stays null. With several calendars and no choice, nothing is guessed.
+ * stays null. With several calendars and no choice, nothing is guessed. An unknown option is a
+ * TypeError (the caller's bug, not the world's data).
  */
 declare function resolveCalendarLens(elements: Iterable<OwCalendarElement>, activeId: string | null | undefined, opts?: {
     fallbackToOnly?: boolean;

package/dist/index.js

@@ -56,6 +56,19 @@ function keyedId(idempotencyKey, index) {
 ${index}`);
 }
 
+// src/options.ts
+function unknownKey(opts, keys) {
+  if (!opts || typeof opts !== "object") return void 0;
+  for (const k of Object.keys(opts)) if (!keys.includes(k)) return k;
+  return void 0;
+}
+function refuseUnknownOptions(fn, opts, keys, after = "") {
+  const k = unknownKey(opts, keys);
+  if (k !== void 0) {
+    throw new TypeError(`${fn}: unknown option '${k}'. The keys are ${keys.join(", ")}.${after ? ` ${after}` : ""}`);
+  }
+}
+
 // src/v2/errors.ts
 var OwApiError = class extends Error {
   constructor(status, code, message, docUrl, detail, type = null, param = null, retryAfter = null) {
@@ -342,6 +355,7 @@ var OwNetworkError = class extends Error {
 };
 var OwSignInError = class extends Error {
   constructor(reason, message, opts = {}) {
+    refuseUnknownOptions("OwSignInError", opts, ["status", "code", "retryAfter"]);
     super(message);
     this.name = "OwSignInError";
     this.reason = reason;
@@ -652,7 +666,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: { ... }.");
+    only("list", params, LIST_PARAM_KEYS, LIST_FILTER_HINT);
     const query = buildQuery({
       limit: params.limit ?? this.pageSize,
       cursor: params.cursor,
@@ -691,6 +705,7 @@ var OwV2Client = class {
   }
   /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
   async *listAll(type, params = {}) {
+    only("listAll", params, LIST_ALL_PARAM_KEYS, LIST_FILTER_HINT);
     let cursor;
     do {
       const page = await this.list(type, { ...params, cursor });
@@ -1718,6 +1733,7 @@ var OwV2Client = class {
    * sanitizePayload — callers own their body shape.
    */
   async request(method, path, opts = {}) {
+    only("request", opts, REQUEST_OPTION_KEYS);
     if (opts.ifMatch !== void 0 && !(Number.isInteger(opts.ifMatch) && opts.ifMatch >= 0)) {
       throw new TypeError(`ifMatch must be a whole number (an element's change_seq), got ${String(opts.ifMatch)}`);
     }
@@ -1930,12 +1946,26 @@ function objectKey(keyOrUrl) {
   return decodeURIComponent(new URL(keyOrUrl).pathname.replace(/^\/+/, ""));
 }
 var LIST_PARAM_KEYS = ["limit", "cursor", "ids", "createdBy", "expand", "fields", "filter", "viewAs"];
+var LIST_ALL_PARAM_KEYS = LIST_PARAM_KEYS.filter((k) => k !== "cursor");
+var LIST_FILTER_HINT = "A wire filter (name, name__icontains, supertype, subtype, characters) goes under filter: { ... }.";
+var REQUEST_OPTION_KEYS = [
+  "query",
+  "body",
+  "idempotencyKey",
+  "auth",
+  "allowEmpty",
+  "replayAware",
+  "write",
+  "elementWrite",
+  "proposable",
+  "ifMatch",
+  "ifNoneMatch",
+  "onEtag"
+];
 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.`);
-    }
+  const k = unknownKey(obj, keys);
+  if (k !== void 0) {
+    throw new TypeError(`${method}: unknown parameter '${k}'. ${hint ? hint + " " : ""}The keys are ${keys.join(", ")}. Nothing was sent.`);
   }
 }
 var CLIENT_CONFIG_KEYS = ["apiKey", "apiPin", "baseUrl", "pageSize", "changesPageSize", "fetch", "agent", "client"];
@@ -2884,6 +2914,7 @@ var OwWorldFileError = class extends Error {
     this.reason = reason;
   }
 };
+var READ_OPTION_KEYS = ["maxBytes", "maxEntries", "skip"];
 var refuse = (reason, message) => {
   throw new OwWorldFileError(reason, message);
 };
@@ -3163,6 +3194,7 @@ function checkFileAndFolder(files) {
   }
 }
 function readWorldFile(bytes, opts = {}) {
+  refuseUnknownOptions("readWorldFile", opts, READ_OPTION_KEYS, "Nothing was read.");
   const maxBytes = opts.maxBytes ?? WORLD_FILE_MAX_BYTES;
   const maxEntries = opts.maxEntries ?? WORLD_FILE_MAX_ENTRIES;
   const entries = centralDirectory(bytes);
@@ -3254,11 +3286,7 @@ var RECORDS_MANIFEST = "records/RECORDS.json";
 function asksPrivate(opts) {
   if (opts === void 0 || opts === null) return false;
   if (typeof opts !== "object") throw new TypeError(`writeWorldFile: options must be an object, such as { includePrivateRecords: true }. Nothing was written.`);
-  for (const k of Object.keys(opts)) {
-    if (!WRITE_OPTION_KEYS.includes(k)) {
-      throw new TypeError(`writeWorldFile: unknown option '${k}'. The keys are ${WRITE_OPTION_KEYS.join(", ")}. Nothing was written.`);
-    }
-  }
+  refuseUnknownOptions("writeWorldFile", opts, WRITE_OPTION_KEYS, "Nothing was written.");
   const asked = opts.includePrivateRecords;
   if (asked !== void 0 && typeof asked !== "boolean") {
     throw new TypeError(`writeWorldFile: includePrivateRecords must be true or false; got ${JSON.stringify(asked) ?? String(asked)}. Nothing was written.`);
@@ -3369,7 +3397,7 @@ function isRoomElement(el) {
 
 // src/names.ts
 var SLUGS = new Set(ELEMENT_TYPES);
-var OPTION_KEYS = /* @__PURE__ */ new Set(["supertype", "many"]);
+var OPTION_KEYS = ["supertype", "many"];
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function word(pair, many) {
   if (!isObject(pair) || typeof pair.one !== "string") return null;
@@ -3380,9 +3408,7 @@ function word(pair, many) {
   return plural === "" ? one : plural;
 }
 function typeWord(world, type, opts = {}) {
-  for (const key of Object.keys(opts ?? {})) {
-    if (!OPTION_KEYS.has(key)) throw new TypeError(`typeWord: unknown option "${key}" (known: supertype, many)`);
-  }
+  refuseUnknownOptions("typeWord", opts, OPTION_KEYS);
   const map = world?.x_names;
   if (!isObject(map) || map.version !== 1) return null;
   const { types, supertypes } = map;
@@ -3405,6 +3431,8 @@ function typeWord(world, type, opts = {}) {
 }
 
 // src/lookup.ts
+var LOOKUP_OPTION_KEYS = ["limit"];
+var RENDER_OPTION_KEYS = ["descMax", "linkMax", "incomingMax"];
 var STOP = /* @__PURE__ */ new Set([
   "a",
   "an",
@@ -3708,7 +3736,9 @@ function similarWords(w, vocab) {
   }
   return res;
 }
-function lookupWorld(index, question, { limit = 8 } = {}) {
+function lookupWorld(index, question, opts = {}) {
+  refuseUnknownOptions("lookupWorld", opts, LOOKUP_OPTION_KEYS);
+  const { limit = 8 } = opts;
   const seeds = 12;
   const q = words(normalize(question));
   const qSet = new Set(q);
@@ -3825,7 +3855,9 @@ function lookupWorld(index, question, { limit = 8 } = {}) {
   for (const [id, c] of cand) if (SPATIAL.has(index.byId.get(id).type)) c.score *= 0.85;
   return [...cand.entries()].map(([id, c]) => ({ element: index.byId.get(id), score: Math.round(c.score * 10) / 10, reasons: c.reasons })).sort((a, b) => b.score - a.score || String(a.element.name).length - String(b.element.name).length || (a.element.id < b.element.id ? -1 : 1)).slice(0, limit);
 }
-function renderElement(element, index, { descMax = 500, linkMax = 12, incomingMax = 10 } = {}) {
+function renderElement(element, index, opts = {}) {
+  refuseUnknownOptions("renderElement", opts, RENDER_OPTION_KEYS);
+  const { descMax = 500, linkMax = 12, incomingMax = 10 } = opts;
   const el = element;
   const name = (id) => index.byId.get(id)?.name ?? "?";
   const kind = [el.supertype, el.subtype].filter((x) => x && x !== "undefined").join(" / ");
@@ -3909,7 +3941,9 @@ function buildAskContext(items, index) {
 // src/photo.ts
 var PHOTO_TYPES = ["image/webp", "image/png", "image/jpeg", "image/avif"];
 var PHOTO_MAX_BYTES = 15 * 1024 * 1024;
+var PHOTO_OPTION_KEYS = ["maxSide", "quality", "maxBytes"];
 function planPhoto(source, opts = {}) {
+  refuseUnknownOptions("planPhoto", opts, PHOTO_OPTION_KEYS);
   const maxSide = opts.maxSide ?? 2048;
   if (!(maxSide > 0)) throw new TypeError("preparePhoto: maxSide must be a positive number");
   if (!(source.width > 0 && source.height > 0)) throw new TypeError("preparePhoto: the picture has no size");
@@ -3934,6 +3968,7 @@ function makeCanvas(width, height) {
   throw new TypeError("preparePhoto needs a browser: no canvas here");
 }
 async function preparePhoto(input, opts = {}) {
+  refuseUnknownOptions("preparePhoto", opts, PHOTO_OPTION_KEYS);
   const quality = opts.quality ?? 0.82;
   const maxBytes = opts.maxBytes ?? PHOTO_MAX_BYTES;
   const decode = globalThis.createImageBitmap;
@@ -4272,6 +4307,7 @@ function formatMidLabel(cfg, step) {
   if (b.monthName != null && b.day != null) return `${b.day} ${b.monthName} ${b.year}`;
   return formatYearLabel(cfg, step);
 }
+var PARSE_OPTION_KEYS = ["now"];
 function absYearForEraYear(cfg, era, Y) {
   if (era.restart === false) return Y;
   const base = era.year_base ?? 1;
@@ -4290,6 +4326,7 @@ function defaultEra(cfg, now) {
   return [...pool].sort((a, b) => b.start - a.start)[0];
 }
 function parseDate(cfg, input, opts = {}) {
+  refuseUnknownOptions("parseDate", opts, PARSE_OPTION_KEYS);
   const raw = input.trim();
   if (raw === "") return { error: "empty date" };
   if (/^-?\d+$/.test(raw)) return { step: parseInt(raw, 10) };
@@ -4420,6 +4457,7 @@ function worldCalendars(elements) {
   return out;
 }
 function resolveCalendarLens(elements, activeId, opts) {
+  refuseUnknownOptions("resolveCalendarLens", opts, ["fallbackToOnly"]);
   if (activeId === void 0 && opts?.fallbackToOnly) {
     const all = worldCalendars(elements);
     return all.length === 1 ? all[0] : null;
@@ -4499,6 +4537,7 @@ var TokenResource = class {
    * ```
    */
   async consume(params) {
+    refuseUnknownOptions("consume", params, ["amount", "service", "sessionId", "metadata"], "Nothing was sent.");
     return this.req("POST", "/tokens/consume/", {
       body: {
         amount: params.amount,

package/package.json

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