@onlyworlds/sdk 4.58.0 → 4.59.0

package/AGENTS.md

@@ -148,4 +148,5 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 
 **Auth**: prefixed keys — `ow_w_` (read+write), `ow_r_` (read-only, no PIN — the share
 primitive), `ow_a_` (account Bearer). Demo keys `0000000000`–`0000000009` are read-only
-test credentials against real data.
+test credentials against real data. A configured `apiPin` is sent only where keel checks it:
+on writes, on `me()`, and on every request of a 10-digit legacy key; other reads go without it.

package/CHANGELOG.md

@@ -5,6 +5,13 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.59.0] - 2026-10-22
+
+### Changed
+
+- **`API-Pin` is sent only where keel checks it** (Skeld's ruling, OW Keel h29 #10663). keel verifies a PIN wherever one is sent (argon2, 64 MiB each), and on 2026-10-22 scripts reading with the PIN OOM-killed staging on a cold cache after a restart. The client used to send a configured `apiPin` on every request. It now sends it on every request whose method is not GET (every write: elements, links, bulk, adopt, hide and unhide, media and file tickets, seats, world links, proposals, `setMyCharacter`, `mintWorldKey`, `patchWorld`, and any route added later), on `GET /me` (`me()`, the connection test: keel checks a PIN there when sent, keel #314, D93), and on every request of a 10-digit legacy key (v1 parity, keel #421: such a key needs the PIN on reads of a world with a PIN). Any other read from an `ow_w_`, `ow_r_` or member key goes without it; an account token never sent it and still does not. The rule is derived in `request()` from the method and path, so a raw `request()` call follows it too. No API changed.
+- Tests: `test/api-pin.test.mjs`, five, on a recorded fetch: eight reads, `me()` and ten writes across POST, PATCH, PUT and DELETE, for an `ow_w_` key with a PIN, a legacy key with a PIN, an `ow_r_` key with none and an account token with one configured; and raw `request()` GETs to other paths, `/me` and other methods. Two existing tests that expected the PIN on a GET now expect none. Mutants: the PIN on every request again fails four tests; without the `/me` clause, three; without the legacy clause, one.
+
 ## [4.58.0] - 2026-10-22
 
 ### Added

package/dist/index.d.ts

@@ -2924,8 +2924,11 @@ interface OwClientConfig {
      */
     apiKey?: string;
     /**
-     * The PIN, needed for writes when the world has one, and for legacy-key reads of private worlds.
-     * Prefixed keys read without a PIN. A string, not a number: '0123' !== 123.
+     * The PIN (or an agent seat's `ow_s_` secret), needed for writes when the world has one, and for
+     * legacy-key reads of a world with a PIN. Sent as `API-Pin` only where keel checks it: on every
+     * write (any method but GET), on GET /me (me(), the connection test), and on every request of a
+     * 10-digit legacy key. A prefixed key's other reads go without it, and an account token never
+     * sends it. A string, not a number: '0123' !== 123.
      */
     apiPin?: string;
     /** The API's base URL, default https://www.onlyworlds.com/api/v2. */

package/dist/index.js

@@ -1725,7 +1725,9 @@ var OwV2Client = class {
         headers["Authorization"] = `Bearer ${this.apiKey}`;
       } else {
         headers["API-Key"] = this.apiKey;
-        if (this.apiPin) headers["API-Pin"] = this.apiPin;
+        const read = method.toUpperCase() === "GET";
+        const me = path === "/me/" || path === "/me";
+        if (this.apiPin && (!read || me || this.keyKind === "legacy")) headers["API-Pin"] = this.apiPin;
       }
     }
     if (opts.body !== void 0) headers["Content-Type"] = "application/json";

package/package.json

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