@onlyworlds/sdk 4.63.0 → 4.65.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.65.0] - 2026-10-23
+
+### Fixed
+
+- **`patchWorld` takes a `getWorld()` body back again** (keel #571, live 2026-10-23). keel's `GET /world` now serves `origin`, and a PATCH naming it is a 422 (an unknown key), so a world body read and sent back failed. `patchWorld` now leaves out `origin`, and `id` too: keel answers `id` with the same 422 (it is not a key PATCH takes), so the round trip 4.57.1's entry promised never held for a whole body. `owner_character` is still sent.
+
+### Added
+
+- **`OwWorldMeta.origin?: OwWorldOrigin`**, read-only: where the world first came from, `{ source, producer }`, both keys always present, each the folder format's provenance line (spec 4.2) as the tool that made the world from a folder gave it, or `null`. Types `OwWorldOrigin`, `OwWorldSource` (`server`, `world`, `at`) and `OwWorldProducer` (`tool`, `version`, `input`), each open to keys keel keeps as given. The origin is written as the plain keys `source` and `producer`: `patchWorld({ source, producer })` sends them as given (an object, or `null` to clear).
+- **The World's extension keys on `OwWorldMeta`**: `x_*`, `atlas_*` and `shadow_*`, typed `unknown` by template-literal index signatures (the first is `x_names`, the names profile `typeWord` reads). `patchWorld` sends every one as given, `null` included (keel removes the key); over keel's 64 KB cap on the whole store the answer is a 422 with `param: extensions`.
+- Tests: a full `GET /world` body sent back sends neither `origin` nor `id` and keeps `x_names`; `source`, `producer` and a key of each extension prefix pass untouched, `null` included; the published types declare `origin` and its two keys, and the documented calls (`patchWorld(await getWorld())`, `patchWorld({ source, producer, x_names })`, `typeWord(world, …)`) compile against the built `.d.ts`. Watched failing on mutants: `origin` and `id` each out of the strip list, `origin` out of `OwWorldMeta`, and a narrowed `patchWorld` parameter.
+
+## [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/README.md

@@ -184,6 +184,8 @@ To poll for news cheaply, `client.changesHead()` returns `{ head, cursor, epoch,
 
 Edits to the world itself (its name, calendar, `public_read`) don't appear in the change feed. Read `client.getWorld()` and compare `updated_at`.
 
+`client.patchWorld(partial)` writes the world's own settings, and takes a `getWorld()` body back: the keys keel does not take (`id`, `origin`, `slug`, `public_page` and the owner's switches) are left out. The world's `origin` is written as the plain keys `source` and `producer` (each an object or `null`), and extension keys (`x_*`, `atlas_*`, `shadow_*`) are sent as given; `null` removes one.
+
 ### Only if unchanged
 
 A client that edits offline, or from a copy it has held a while, can ask for an update to land only if nobody changed the element since it was read: pass the `change_seq` you read as `ifMatch`, on `patch`, `editLinks` or `delete` (since 4.61.0: a delete of an element someone changed since you read it is refused, nothing deleted).

package/dist/index.d.ts

@@ -1968,9 +1968,47 @@ interface OwWorldMeta {
      * the owner on the world page; read-only on the wire, and patchWorld strips it.
      */
     agent_writes_proposed?: boolean;
+    /**
+     * Where the world first came from (keel #571, #477): the folder format's provenance lines (spec
+     * 4.2) as the tool that made the world from a folder gave them, both keys always present, each
+     * null when not known. Read-only on the wire, and patchWorld strips it: write it as the plain
+     * keys `source` and `producer` (`patchWorld({ source, producer })`, each an object or null).
+     */
+    origin?: OwWorldOrigin;
     created_at?: string | null;
     /** Moves when the world's own fields change, not on element writes. */
     updated_at?: string | null;
+    /**
+     * Extension keys (keel #571): a tool's own setting on the world, any JSON value, served at the
+     * top level as an element's are (the first is `x_names`, the names profile: see `typeWord`).
+     * patchWorld sends them as given; `null` removes one; 64 KB in all, else a 422 `param: extensions`.
+     */
+    [extension: `x_${string}`]: unknown;
+    [extension: `atlas_${string}`]: unknown;
+    [extension: `shadow_${string}`]: unknown;
+    [field: string]: unknown;
+}
+/**
+ * OwWorldMeta.origin (keel #571, #477), as keel's `World` component types it: both keys always
+ * present, each an object or null. Kept as the writer gave it; keel checks only that `source.world`
+ * and `producer.tool` are strings when present.
+ */
+interface OwWorldOrigin {
+    source: OwWorldSource | null;
+    producer: OwWorldProducer | null;
+}
+/** The folder format's `source` line (spec 4.2): the server and world a folder was exported from, and when. Kept as given. */
+interface OwWorldSource {
+    server?: string;
+    world?: string;
+    at?: string;
+    [field: string]: unknown;
+}
+/** The folder format's `producer` line (spec 4.2): the tool that made a folder, its version, and what it made it from. Kept as given. */
+interface OwWorldProducer {
+    tool?: string;
+    version?: string;
+    input?: string;
     [field: string]: unknown;
 }
 /** OwWorldMeta.public_page (keel #471), as keel's `World` component types it: all six keys, always. */
@@ -3421,7 +3459,10 @@ declare class OwV2Client {
     /**
      * PATCH /world -- partial world-meta update. The element write's server-managed keys are
      * stripped, and so are the world's own read-only ones (WORLD_READ_ONLY_FIELDS: `slug` and
-     * `public_page`, keel #471; `agent_writes_proposed`, keel #519; set on the world page, not here).
+     * `public_page`, keel #471; `agent_writes_proposed`, keel #519; set on the world page, not here;
+     * `origin`, keel #571; `id`), so a `getWorld()` body can be sent back. The world's origin is
+     * written as `source` and `producer` (keel #571, each an object or null, served under `origin`);
+     * extension keys (`x_*`, `atlas_*`, `shadow_*`) are sent as given, and `null` removes one.
      */
     patchWorld(partial: Record<string, unknown>): Promise<OwWorldMeta>;
     /**
@@ -4371,7 +4412,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 +4577,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 +4683,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 +4950,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;
@@ -5218,4 +5261,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 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 OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwHiddenRow, 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, type OwNamesMap, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, OwStaleProposalError, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldProposalQuery, type OwWorldPublicPage, type OwWriteDoor, type OwWriteWorldFileOptions, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, 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, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, typeWord, 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 OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwHiddenRow, 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, type OwNamesMap, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, OwStaleProposalError, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWorldOrigin, type OwWorldProducer, type OwWorldProposalQuery, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, ROOM_PAIRS, 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, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, isRoomElement, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, simpleCaseFold, typeWord, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

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;
@@ -603,7 +617,10 @@ var OwV2Client = class {
   /**
    * PATCH /world -- partial world-meta update. The element write's server-managed keys are
    * stripped, and so are the world's own read-only ones (WORLD_READ_ONLY_FIELDS: `slug` and
-   * `public_page`, keel #471; `agent_writes_proposed`, keel #519; set on the world page, not here).
+   * `public_page`, keel #471; `agent_writes_proposed`, keel #519; set on the world page, not here;
+   * `origin`, keel #571; `id`), so a `getWorld()` body can be sent back. The world's origin is
+   * written as `source` and `producer` (keel #571, each an object or null, served under `origin`);
+   * extension keys (`x_*`, `atlas_*`, `shadow_*`) are sent as given, and `null` removes one.
    */
   async patchWorld(partial) {
     const body = sanitizePayload(partial);
@@ -652,7 +669,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 +708,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 +1736,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)}`);
     }
@@ -1784,7 +1803,7 @@ var HeadPollState = class {
   }
 };
 var READ_ONLY_FIELDS = ["world", "type", "created_at", "updated_at", "change_seq", "known_of"];
-var WORLD_READ_ONLY_FIELDS = ["slug", "public_page", "public_read", "agent_narrator_rule", "agent_writes_proposed"];
+var WORLD_READ_ONLY_FIELDS = ["id", "slug", "public_page", "public_read", "agent_narrator_rule", "agent_writes_proposed", "origin"];
 function proposalsPath(type, id) {
   return `/${type}/${encodeURIComponent(id)}/proposals`;
 }
@@ -1930,12 +1949,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 +2917,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 +3197,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 +3289,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 +3400,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 +3411,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 +3434,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 +3739,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 +3858,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 +3944,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 +3971,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 +4310,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 +4329,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 +4460,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 +4540,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.65.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {