@onlyworlds/sdk 4.27.2 → 4.29.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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
+- **Seats for your own AI** (keel #355, D106), on an account token (`ow_a_`):
+  - `createSeat(worldId, { name, role?, character? })`: a seat for your own AI in a world you own or
+    belong to, with its own write key and `ow_s_` secret and no join link. You answer for it. `role` is at
+    most your own; `character` is `new` (default), `none`, or `mine` (it plays the Character you play).
+    The answer (`OwSeatCreated`) carries `key`, `pin` and the `.env` lines in `env`, shown once.
+  - `listSeats(worldId)`: the seats you can see (yours, or every seat for the world's owner), as `OwSeat`
+    rows with their `sponsor`, no keys.
+  - `removeSeat(worldId, seatId)`: its sponsor or the world's owner removes it; its key and secret stop.
+  - No Idempotency-Key on `createSeat`, by keel's rule (a replay would keep the key). A lost answer:
+    `listSeats` shows the seat, `removeSeat` it and make another.
+
 ## [4.27.2] — 2026-10-16
 
 ### Fixed

package/dist/index.d.ts

@@ -2259,6 +2259,49 @@ interface OwCreatedWorldLink extends OwWorldLink {
     /** The one line to send: who invites, to which world, and the link. */
     line: string;
 }
+/** One live agent seat, as GET /account/worlds/{id}/seats lists it (keel #355, D106). No key or secret. */
+interface OwSeat {
+    /** The seat's membership id: removeSeat takes it, and GET /members names the seat by it. */
+    id: string;
+    /** The AI's own name in the world. */
+    name: string;
+    role: OwMemberRole;
+    /** Always `agent`: a seat has no account of its own. */
+    kind: 'agent';
+    /** The Character the seat plays, or null. With `character: 'mine'` it is its sponsor's own: two rows, one Character. */
+    character: string | null;
+    /** Who answers for the seat: a username when they are the world's owner or a member; null for a seat from an email invite, or a sponsor who left. */
+    sponsor: string | null;
+    /** ISO 8601, UTC. */
+    joined_at: string | null;
+    /** The latest use of the seat's key, or null. */
+    last_active: string | null;
+    [k: string]: unknown;
+}
+/** POST /account/worlds/{id}/seats's answer: the seat, its key and secret, shown in this answer only. */
+interface OwSeatCreated {
+    world: {
+        id: string;
+        name: string;
+        [k: string]: unknown;
+    };
+    seat: {
+        id: string;
+        name: string;
+        role: OwMemberRole;
+        kind: 'agent';
+        [k: string]: unknown;
+    };
+    /** The Character the seat plays, or null for none. */
+    character: string | null;
+    /** The seat's write key (`API-Key`). */
+    key: string;
+    /** The seat's `ow_s_` secret, sent as `API-Pin` where a person sends their PIN. */
+    pin: string;
+    /** The lines of a `.env` file for the AI: OW_API_KEY, OW_API_PIN, OW_WORLD, OW_CHARACTER when it plays one, OW_API_BASE. */
+    env: string;
+    [k: string]: unknown;
+}
 /** POST /account/join: the new membership (the same row as accepting an email invite). */
 interface OwJoinedMembership {
     /** The membership's id. */
@@ -2369,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;
@@ -2763,6 +2806,41 @@ declare class OwV2Client {
      * createWorldLink. Needs the client's `ow_a_` token.
      */
     revokeWorldLink(worldId: string, linkId: string): Promise<void>;
+    /**
+     * POST /account/worlds/{worldId}/seats -- a seat for your own AI in a world you own or are a
+     * member of: its own membership, write key and `ow_s_` secret, no join link. You answer for
+     * it, and its writes are marked as an agent's. `name` is required (1 to 80 characters);
+     * `role` is at most your own (the owner may give any; default contributor, or your own role
+     * when that is lower); `character` is `new` (default: a Character of its own), `none`, or
+     * `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: rekeySeat gives it a new one (or removeSeat and make another). Needs the client's `ow_a_` token.
+     */
+    createSeat(worldId: string, opts: {
+        name: string;
+        role?: OwMemberRole;
+        character?: 'new' | 'none' | 'mine';
+    }): Promise<OwSeatCreated>;
+    /**
+     * GET /account/worlds/{worldId}/seats -- the live agent seats you can see: your own AI's, or,
+     * 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
+     * goes with it, any other stays. Needs the client's `ow_a_` token.
+     */
+    removeSeat(worldId: string, seatId: string): Promise<void>;
     /**
      * POST /account/ask -- a question about a world the account owns or is in, answered by
      * keel's AI proxy from `context` only (build it with buildAskContext from the elements
@@ -3764,4 +3842,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_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, 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 OwElement, type OwElementBase, type OwErrorBody, type OwJoinPreview, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, type ParseError, type ParseOptions, type ParseResult, 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, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, 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_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, 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 OwElement, type OwElementBase, type OwErrorBody, type OwJoinPreview, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwSeat, type OwSeatCreated, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, type ParseError, type ParseOptions, type ParseResult, 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, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -626,6 +626,62 @@ var OwV2Client = class {
     }
     await this.request("DELETE", `/account/worlds/${encodeURIComponent(worldId)}/links/${encodeURIComponent(linkId)}`);
   }
+  // -- Seats for your own AI (keel #355, D106) ------------------------------
+  /**
+   * POST /account/worlds/{worldId}/seats -- a seat for your own AI in a world you own or are a
+   * member of: its own membership, write key and `ow_s_` secret, no join link. You answer for
+   * it, and its writes are marked as an agent's. `name` is required (1 to 80 characters);
+   * `role` is at most your own (the owner may give any; default contributor, or your own role
+   * when that is lower); `character` is `new` (default: a Character of its own), `none`, or
+   * `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: 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") {
+      throw new TypeError("createSeat needs an account token (ow_a_): a seat is made by the person who answers for it");
+    }
+    const body = { name: opts.name };
+    if (opts.role !== void 0) body.role = opts.role;
+    if (opts.character !== void 0) body.character = opts.character;
+    return this.request("POST", `/account/worlds/${encodeURIComponent(worldId)}/seats`, { body });
+  }
+  /**
+   * GET /account/worlds/{worldId}/seats -- the live agent seats you can see: your own AI's, or,
+   * as the world's owner, every seat. No keys or secrets. Needs the client's `ow_a_` token.
+   */
+  async listSeats(worldId) {
+    if (this.keyKind !== "account") {
+      throw new TypeError("listSeats needs an account token (ow_a_)");
+    }
+    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
+   * goes with it, any other stays. Needs the client's `ow_a_` token.
+   */
+  async removeSeat(worldId, seatId) {
+    if (this.keyKind !== "account") {
+      throw new TypeError("removeSeat needs an account token (ow_a_)");
+    }
+    await this.request("DELETE", `/account/worlds/${encodeURIComponent(worldId)}/seats/${encodeURIComponent(seatId)}`);
+  }
   // -- Ask your world (keel #159) -------------------------------------------
   /**
    * POST /account/ask -- a question about a world the account owns or is in, answered by

package/package.json

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