@onlyworlds/sdk 4.28.0 → 4.29.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.29.0] — 2026-10-16
+
+### Added
+- `rekeySeat(worldId, seatId)` (keel #355 piece 3, D108): a new key and secret for a seat whose AI lost
+  its own, by its sponsor or the world's owner. The old key and secret stop at once; the answer has
+  `createSeat`'s shape (`OwSeatCreated`: `key`, `pin`, `env`), shown once. No Idempotency-Key, by keel's
+  rule: if the answer is lost too, ask for another.
+
+### Changed
+- `createSeat`'s doc names `rekeySeat` as the way back from a lost answer.
+- `OwApiError.param`'s doc: `API-Pin` on a 401 PIN refusal (keel #357, D107), not only a 422/400's field.
+
 ## [4.28.0] — 2026-10-16
 
 ### Added

package/dist/index.d.ts

@@ -2412,7 +2412,7 @@ declare class OwApiError extends Error {
     readonly code: string | null;
     /** Error family from the envelope, e.g. 'invalid_request', 'not_found'. */
     readonly type: string | null;
-    /** Offending field/param named by the envelope (422/400), else null. */
+    /** Offending field/param named by the envelope (a 422/400's field; `API-Pin` on a 401 PIN refusal, keel #357), else null. */
     readonly param: string | null;
     /** Documentation link from the envelope -- show it to users/logs verbatim. */
     readonly docUrl: string | null;
@@ -2815,7 +2815,7 @@ declare class OwV2Client {
      * `mine` (members only: it plays the Character you play). 201 with `key`, `pin` and the
      * `.env` lines in `env`, shown in this answer only. Sends no Idempotency-Key, by keel's rule:
      * a replay would have to keep the key. If the answer is lost, listSeats shows the seat without
-     * its key: remove it with removeSeat and make another. Needs the client's `ow_a_` token.
+     * its key: rekeySeat gives it a new one (or removeSeat and make another). Needs the client's `ow_a_` token.
      */
     createSeat(worldId: string, opts: {
         name: string;
@@ -2827,6 +2827,14 @@ declare class OwV2Client {
      * as the world's owner, every seat. No keys or secrets. Needs the client's `ow_a_` token.
      */
     listSeats(worldId: string): Promise<OwSeat[]>;
+    /**
+     * POST /account/worlds/{worldId}/seats/{seatId}/key -- a new key and secret for a seat whose AI
+     * lost its own: its sponsor or the world's owner may. The old key and secret stop at once;
+     * nothing else about the seat changes. 201 with the same shape as createSeat (`key`, `pin`,
+     * `env`), shown in this answer only. No Idempotency-Key, by keel's rule: if this answer is lost
+     * too, ask for another new key. Needs the client's `ow_a_` token.
+     */
+    rekeySeat(worldId: string, seatId: string): Promise<OwSeatCreated>;
     /**
      * DELETE /account/worlds/{worldId}/seats/{seatId} -- remove an agent seat: its sponsor or the
      * world's owner may. Its key and secret stop at once; a Character it made that nobody touched

package/dist/index.js

@@ -636,7 +636,7 @@ var OwV2Client = class {
    * `mine` (members only: it plays the Character you play). 201 with `key`, `pin` and the
    * `.env` lines in `env`, shown in this answer only. Sends no Idempotency-Key, by keel's rule:
    * a replay would have to keep the key. If the answer is lost, listSeats shows the seat without
-   * its key: remove it with removeSeat and make another. Needs the client's `ow_a_` token.
+   * its key: rekeySeat gives it a new one (or removeSeat and make another). Needs the client's `ow_a_` token.
    */
   async createSeat(worldId, opts) {
     if (this.keyKind !== "account") {
@@ -658,6 +658,19 @@ var OwV2Client = class {
     const page = await this.request("GET", `/account/worlds/${encodeURIComponent(worldId)}/seats`);
     return page.data;
   }
+  /**
+   * POST /account/worlds/{worldId}/seats/{seatId}/key -- a new key and secret for a seat whose AI
+   * lost its own: its sponsor or the world's owner may. The old key and secret stop at once;
+   * nothing else about the seat changes. 201 with the same shape as createSeat (`key`, `pin`,
+   * `env`), shown in this answer only. No Idempotency-Key, by keel's rule: if this answer is lost
+   * too, ask for another new key. Needs the client's `ow_a_` token.
+   */
+  async rekeySeat(worldId, seatId) {
+    if (this.keyKind !== "account") {
+      throw new TypeError("rekeySeat needs an account token (ow_a_)");
+    }
+    return this.request("POST", `/account/worlds/${encodeURIComponent(worldId)}/seats/${encodeURIComponent(seatId)}/key`);
+  }
   /**
    * DELETE /account/worlds/{worldId}/seats/{seatId} -- remove an agent seat: its sponsor or the
    * world's owner may. Its key and secret stop at once; a Character it made that nobody touched

package/package.json

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