@onlyworlds/sdk 4.27.1 → 4.28.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [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
+- **`bulk` mints an id for each element that has none, as `create` does.** It sent id-less elements
+  bare and keel minted them. With an `idempotencyKey`, each id is now derived from the key and the
+  element's position in `items` (the ids the Python package mints), so the same key and items send the
+  same body from either client, and a resend after keel's 24-hour replay window rewrites the same
+  elements instead of creating new ones. Without a key, a fresh UUIDv7 each. Ids you pass are kept, and
+  your items are not changed. Found by Quillon's parity audit of the Unity SDK (h37 #5794).
+
 ## [4.27.1] — 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. */
@@ -2610,6 +2653,10 @@ declare class OwV2Client {
      * After an atomic:true request with errors:true NOTHING was written, yet the slots of
      * the items that would have succeeded still say 201 with the ids and timestamps they
      * would have had (keel's "counterfactual 201s"): do not record those ids as created.
+     * An element without an id gets one, as `create` mints it, by its position in `items`: with an
+     * `idempotencyKey`, derived from the key and the position (the ids the Python package mints),
+     * so a retry with the same key and items sends the same body; without one, a
+     * fresh UUIDv7. Ids you supply are kept.
      */
     bulk(items: OwBulkItem[], opts?: {
         atomic?: boolean;
@@ -2759,6 +2806,33 @@ 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: remove it with 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[]>;
+    /**
+     * 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
@@ -3760,4 +3834,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

@@ -399,10 +399,20 @@ var OwV2Client = class {
    * After an atomic:true request with errors:true NOTHING was written, yet the slots of
    * the items that would have succeeded still say 201 with the ids and timestamps they
    * would have had (keel's "counterfactual 201s"): do not record those ids as created.
+   * An element without an id gets one, as `create` mints it, by its position in `items`: with an
+   * `idempotencyKey`, derived from the key and the position (the ids the Python package mints),
+   * so a retry with the same key and items sends the same body; without one, a
+   * fresh UUIDv7. Ids you supply are kept.
    */
   async bulk(items, opts = {}) {
     const body = {
-      items: items.map((it) => ({ type: it.type, element: sanitizePayload(it.element) })),
+      items: items.map((it, index) => {
+        const element = sanitizePayload(it.element);
+        if (element.id === void 0 || element.id === null || element.id === "") {
+          element.id = opts.idempotencyKey ? keyedId(opts.idempotencyKey, index) : mintUuid();
+        }
+        return { type: it.type, element };
+      }),
       atomic: opts.atomic ?? false
     };
     return this.request("POST", "/bulk/", {
@@ -616,6 +626,49 @@ 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: remove it with 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;
+  }
+  /**
+   * 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.1",
+  "version": "4.28.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {