@onlyworlds/sdk 4.37.0 → 4.39.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.32.0-dist.23** (canonical 00.32.00).
+**Current as of**: SDK **4.x** · schema-dist **v0.32.1-dist.27** (canonical 00.32.01).
 This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
 re-read against it, the check fails rather than letting this document rot quietly.
 

package/CHANGELOG.md

@@ -5,6 +5,35 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.39.0] - 2026-10-20
+
+The party link (keel #422 PR 2, keel PR 110), live in production since 2026-10-20 13:15.
+
+### Added
+- The party link (keel #422 PR 2, keel PR 110; for Lantern's pick screen, Temper): one player link for a
+  table of players. `createWorldLink(worldId, { reader: 'player', maxUses, characters })`, sent as `max_uses`
+  and `characters`: 2 to 50 uses, each player picking one Character from the owner's list, in its order; no
+  list, each player names a fresh Character after themselves. A table takes no `character`. A link for one
+  sends what it sent before. `OwWorldLink` and `OwCreatedWorldLink` gain a table's `max_uses` and
+  `characters` (`{ id, name, taken }`); `uses` counts a table's seats. `OwJoinPreview` gains a table's
+  `max_uses`, `uses_left`, `name_required` and `characters` (`{ id, name, image_url, taken }`).
+  `redeemJoin(code, { character })` sends the pick; with `name_required`, `name` alone. A pick a live seat
+  already plays is 422 `character_taken` (`err.isCharacterTaken`); a pick off the list, hidden or deleted
+  since the link was made, or missing, is 422 `invalid_request` with param `character`
+  (`err.isCharacterInvalid`, true for that param only); a world with its 50 players is 422 `world_full` (`err.isWorldFull`, its own code at my ask, Skeld h29 #8394); the last place
+  lost to another player is the one 404 (`err.isNotFound`).
+
+### Changed
+- Repinned to schema-dist v0.32.1-dist.27: only `example/world-export.json` moved (its `schema_version` now 00.32.01, Skeld h29 #8455); no schema file moved, so the generated files change only their source lines.
+
+## [4.38.0] - 2026-10-20
+
+Schema 00.32.01 (the Captain's word, h55 #8395): repinned to schema-dist v0.32.1-dist.26.
+
+### Changed
+- **An Event's `characters`** reads "Characters who know about the event: they were present, aware of it, or involved in it" (it read "Key characters relevant to the event"), in the generated doc comment and `SCHEMA.md`. No field, type or link changed.
+- **`ONLYWORLDS_VERSION`** is `'00.32.01'`. It is an `as const` export, so its literal type moves too, which is why this is a minor and not a patch.
+
 ## [4.37.0] - 2026-10-20
 
 The hidden mark (keel #421), live in production since 2026-10-20 09:24; walked on staging with the mark on, 25 of 25.

package/SCHEMA.md

@@ -1,6 +1,6 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.0-dist.23** — canonical schema **00.32.00**, published 2026-10-12.
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.32.1-dist.27** — canonical schema **00.32.01**, published 2026-10-20.
 
 GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
 Written for both humans and AI agents reading this package locally.
@@ -206,7 +206,7 @@ Families (colour semantics; icon carries the type): agents · world · abstract
 
 ### Involves
 
-- `characters` (multi link → character) — Key characters relevant to the event
+- `characters` (multi link → character) — Characters who know about the event: they were present, aware of it, or involved in it
 - `objects` (multi link → object) — Objects relevant to the event
 - `locations` (multi link → location) — Locations relevant to the event
 - `species` (multi link → species) — Species relevant to the event

package/dist/index.d.ts

@@ -37,7 +37,7 @@ type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creat
 declare const ELEMENT_TYPES: ElementType[];
 /** Canonical OnlyWorlds schema version. Source: the `canonical:` value of the pinned
  *  distribution's VERSION file (see the provenance block at the top of this file). */
-declare const ONLYWORLDS_VERSION: "00.32.00";
+declare const ONLYWORLDS_VERSION: "00.32.01";
 /** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
 type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
 /** Per-type semantic family. Source: the distribution's `presentation.json` sidecar
@@ -2254,6 +2254,19 @@ interface OwJoinPreview {
     with_character: boolean | null;
     /** ISO 8601, UTC. */
     expires_at: string;
+    /** A table only (a player link that works 2 to 50 times, keel #422 PR 2): how many times it works. Absent on a link for one. */
+    max_uses?: number;
+    /** A table only: how many places are left. */
+    uses_left?: number;
+    /** A table only: true when the owner listed no Characters, so each player sends a `name` to redeemJoin and gets a fresh Character with it. */
+    name_required?: boolean;
+    /** A table only: the Characters a player may pick, in the owner's order; empty when `name_required`. `taken` while a live seat in the world plays it (a pick screen keeps the order and puts taken ones last). A Character hidden or deleted since the link was made is left out. */
+    characters?: Array<{
+        id: string;
+        name: string;
+        image_url: string | null;
+        taken: boolean;
+    }>;
     [k: string]: unknown;
 }
 /** One of a world's invite links, as GET /account/worlds/{id}/links lists it (keel C1, 48c10d4). */
@@ -2275,16 +2288,25 @@ interface OwWorldLink {
     created_at: string;
     /** ISO 8601, UTC. */
     expires_at: string;
-    /** 0 or 1: a link works once. */
+    /** 0 or 1 for a link for one; a table's seats made, removed ones included (keel #422 PR 2). */
     uses: number;
+    /** A table is `pending` while `uses < max_uses` (and neither revoked nor expired), `used` once full. */
     status: 'pending' | 'used' | 'revoked' | 'expired';
     /** Whether the link shows the world's name and picture when it is pasted into a chat (keel #422): then the link is `/join/<world_id>#<code>`, else `/join#<code>`. Never on an agent link. */
     preview?: boolean;
-    /** A player link only: the Character the player reads as; null while a link for a fresh Character is unused. `name` is null if that Character was deleted (the redeem then makes a fresh one). */
+    /** A player link only: the Character the player reads as; null while a link for a fresh Character is unused, and always null on a table. `name` is null if that Character was deleted (the redeem then makes a fresh one). */
     character?: {
         id: string;
         name: string | null;
     } | null;
+    /** A table only (a player link that works 2 to 50 times, keel #422 PR 2): how many times it works. Absent on a link for one. */
+    max_uses?: number;
+    /** A table only: the Characters its players may pick, in the owner's order; empty when each player gets a fresh Character named after them. `taken`: a live seat in the world plays it. `name` is null if the Character was deleted. */
+    characters?: Array<{
+        id: string;
+        name: string | null;
+        taken: boolean;
+    }>;
     [k: string]: unknown;
 }
 /** POST /account/worlds/{id}/links: the new link, with its code. The code is in this answer only: keel keeps a hash. */
@@ -2715,6 +2737,28 @@ declare class OwApiError extends Error {
     get isPreconditionFailed(): boolean;
     /** 404 `not_found`: no such element or route, or a join code that is unknown, used, revoked or expired. */
     get isNotFound(): boolean;
+    /**
+     * redeemJoin on a table (keel #422 PR 2): the picked Character is one a live seat in the
+     * world already plays (422 `character_taken`, `param` character). Pick another from a fresh
+     * previewJoin, whose `characters` mark each `taken`. The code is not spent.
+     */
+    get isCharacterTaken(): boolean;
+    /**
+     * The `character` sent was refused (422 `invalid_request`, `param` character). On redeemJoin
+     * at a table (keel #422 PR 2): the pick is off the link's list, hidden or deleted since the
+     * link was made, or missing, or sent to a table with no list (send `name` instead); one
+     * answer for all, so read previewJoin again and pick from its `characters`. The code is not
+     * spent. On createWorldLink: a `character` keel refused (not a Character of the world, a
+     * hidden one, or any `character` on a table). Never true for another param's 422, nor for
+     * `character_taken` (see isCharacterTaken).
+     */
+    get isCharacterInvalid(): boolean;
+    /**
+     * redeemJoin (keel #422 PR 2): the world already has its 50 live players (422 `world_full`),
+     * at any player link, a table's or a link for one's. Nothing is spent; a place frees when the
+     * owner removes a player.
+     */
+    get isWorldFull(): boolean;
     /** acceptJoin: the account is already a member of that world (409 `already_member`). The code is not spent. */
     get isAlreadyMember(): boolean;
     /** acceptJoin: the account has no PIN yet, and a member writes with their own (409 `pin_required`). The code is not spent. */
@@ -3155,7 +3199,9 @@ declare class OwV2Client {
      * which world, in what role, and `reader` (`person`: accept it with acceptJoin;
      * `agent`: an AI agent redeems it at POST /join). Sends no credential, whatever key
      * this client holds. Every bad code (unknown, used, revoked, expired) is the same
-     * 404 `not_found` (`err.isNotFound`). `code` is the part of the link after `#`.
+     * 404 `not_found` (`err.isNotFound`). `code` is the part of the link after `#`. A table
+     * (keel #422 PR 2) adds `max_uses`, `uses_left`, `name_required` and `characters`, the
+     * pick screen's list; a link for one answers without them.
      */
     previewJoin(code: string): Promise<OwJoinPreview>;
     /**
@@ -3168,10 +3214,22 @@ declare class OwV2Client {
      * Character's name or "Player" when left out) and `agentName` (an agent's, required for an
      * agent code). Every bad code is the same 404 `not_found`; a person's code is redeemed with
      * acceptJoin instead.
+     *
+     * A table (a player code whose preview carries `max_uses`, keel #422 PR 2) seats one player
+     * per redeem, until `uses_left` is 0. With a list, `character` is the player's pick, the `id`
+     * of one of the preview's `characters` not `taken`: a Character a live seat already plays is
+     * 422 `character_taken` (`err.isCharacterTaken`; pick another), one off the list, hidden or
+     * deleted since, or none sent, is 422 `invalid_request`, param `character`
+     * (`err.isCharacterInvalid`; read the preview again). With no list
+     * (`name_required`), send `name` and no `character`: the player's fresh Character takes the
+     * name (missing: 422, param `name`). A world with its 50 players is 422 `invalid_request`;
+     * the last place taken by someone else first is the one 404. A refusal spends nothing. A link
+     * for one ignores `character`.
      */
     redeemJoin(code: string, opts?: {
         name?: string;
         agentName?: string;
+        character?: string;
     }): Promise<OwJoined>;
     /**
      * Sign in with an email address (or a username) and password, and get a new account token
@@ -3218,7 +3276,14 @@ declare class OwV2Client {
      * whoever opens the link first reads as it, until removed. `preview` (person and player links,
      * keel #422) to false: true puts the world's id in the link's path, so a chat that unfurls it
      * shows the world's name and picture (the code stays after `#`); true on an agent link is
-     * 422, param `preview`. 201 with the code, shown in this
+     * 422, param `preview`. `maxUses` (player links only, keel #422 PR 2) to 1, a link for one:
+     * 2 to 50 makes a table, one link that seats that many players, each picking one of
+     * `characters` (Character ids of the world, in the order a pick screen shows them; a hidden
+     * one is 422, param `characters`). `characters` empty or left out: each player names a fresh
+     * Character after themselves. A table takes no `character`, not even `new` (422, param
+     * `character`), and `characters` on a link for one is 422, even empty. A table counts once
+     * against the 50 pending invites; its seats count against the world's 50 players as each is
+     * made, so a full world refuses the pick, never the link. 201 with the code, shown in this
      * answer only. Owner only: anyone else, and a world that doesn't exist, gets 404
      * `not_found` (`err.isNotFound`). A world key is a TypeError before anything is sent.
      */
@@ -3230,6 +3295,8 @@ declare class OwV2Client {
         withCharacter?: boolean;
         character?: string;
         preview?: boolean;
+        maxUses?: number;
+        characters?: string[];
     }): Promise<OwCreatedWorldLink>;
     /**
      * GET /account/worlds/{worldId}/links -- the world's invite links, without their codes:

package/dist/index.js

@@ -173,6 +173,34 @@ var OwApiError = class extends Error {
   get isNotFound() {
     return this.status === 404 && this.code === "not_found";
   }
+  /**
+   * redeemJoin on a table (keel #422 PR 2): the picked Character is one a live seat in the
+   * world already plays (422 `character_taken`, `param` character). Pick another from a fresh
+   * previewJoin, whose `characters` mark each `taken`. The code is not spent.
+   */
+  get isCharacterTaken() {
+    return this.status === 422 && this.code === "character_taken";
+  }
+  /**
+   * The `character` sent was refused (422 `invalid_request`, `param` character). On redeemJoin
+   * at a table (keel #422 PR 2): the pick is off the link's list, hidden or deleted since the
+   * link was made, or missing, or sent to a table with no list (send `name` instead); one
+   * answer for all, so read previewJoin again and pick from its `characters`. The code is not
+   * spent. On createWorldLink: a `character` keel refused (not a Character of the world, a
+   * hidden one, or any `character` on a table). Never true for another param's 422, nor for
+   * `character_taken` (see isCharacterTaken).
+   */
+  get isCharacterInvalid() {
+    return this.status === 422 && this.code === "invalid_request" && this.param === "character";
+  }
+  /**
+   * redeemJoin (keel #422 PR 2): the world already has its 50 live players (422 `world_full`),
+   * at any player link, a table's or a link for one's. Nothing is spent; a place frees when the
+   * owner removes a player.
+   */
+  get isWorldFull() {
+    return this.status === 422 && this.code === "world_full";
+  }
   /** acceptJoin: the account is already a member of that world (409 `already_member`). The code is not spent. */
   get isAlreadyMember() {
     return this.status === 409 && this.code === "already_member";
@@ -772,7 +800,9 @@ var OwV2Client = class {
    * which world, in what role, and `reader` (`person`: accept it with acceptJoin;
    * `agent`: an AI agent redeems it at POST /join). Sends no credential, whatever key
    * this client holds. Every bad code (unknown, used, revoked, expired) is the same
-   * 404 `not_found` (`err.isNotFound`). `code` is the part of the link after `#`.
+   * 404 `not_found` (`err.isNotFound`). `code` is the part of the link after `#`. A table
+   * (keel #422 PR 2) adds `max_uses`, `uses_left`, `name_required` and `characters`, the
+   * pick screen's list; a link for one answers without them.
    */
   async previewJoin(code) {
     return this.request("POST", "/join/preview", { auth: false, body: { code } });
@@ -787,11 +817,23 @@ var OwV2Client = class {
    * Character's name or "Player" when left out) and `agentName` (an agent's, required for an
    * agent code). Every bad code is the same 404 `not_found`; a person's code is redeemed with
    * acceptJoin instead.
+   *
+   * A table (a player code whose preview carries `max_uses`, keel #422 PR 2) seats one player
+   * per redeem, until `uses_left` is 0. With a list, `character` is the player's pick, the `id`
+   * of one of the preview's `characters` not `taken`: a Character a live seat already plays is
+   * 422 `character_taken` (`err.isCharacterTaken`; pick another), one off the list, hidden or
+   * deleted since, or none sent, is 422 `invalid_request`, param `character`
+   * (`err.isCharacterInvalid`; read the preview again). With no list
+   * (`name_required`), send `name` and no `character`: the player's fresh Character takes the
+   * name (missing: 422, param `name`). A world with its 50 players is 422 `invalid_request`;
+   * the last place taken by someone else first is the one 404. A refusal spends nothing. A link
+   * for one ignores `character`.
    */
   async redeemJoin(code, opts = {}) {
     const body = { code };
     if (opts.name !== void 0) body.name = opts.name;
     if (opts.agentName !== void 0) body.agent_name = opts.agentName;
+    if (opts.character !== void 0) body.character = opts.character;
     return this.request("POST", "/join", { auth: false, body });
   }
   // -- Signing in with a password (keel #211) --------------------------------
@@ -943,7 +985,14 @@ var OwV2Client = class {
    * whoever opens the link first reads as it, until removed. `preview` (person and player links,
    * keel #422) to false: true puts the world's id in the link's path, so a chat that unfurls it
    * shows the world's name and picture (the code stays after `#`); true on an agent link is
-   * 422, param `preview`. 201 with the code, shown in this
+   * 422, param `preview`. `maxUses` (player links only, keel #422 PR 2) to 1, a link for one:
+   * 2 to 50 makes a table, one link that seats that many players, each picking one of
+   * `characters` (Character ids of the world, in the order a pick screen shows them; a hidden
+   * one is 422, param `characters`). `characters` empty or left out: each player names a fresh
+   * Character after themselves. A table takes no `character`, not even `new` (422, param
+   * `character`), and `characters` on a link for one is 422, even empty. A table counts once
+   * against the 50 pending invites; its seats count against the world's 50 players as each is
+   * made, so a full world refuses the pick, never the link. 201 with the code, shown in this
    * answer only. Owner only: anyone else, and a world that doesn't exist, gets 404
    * `not_found` (`err.isNotFound`). A world key is a TypeError before anything is sent.
    */
@@ -958,6 +1007,8 @@ var OwV2Client = class {
     if (opts.withCharacter !== void 0) body.with_character = opts.withCharacter;
     if (opts.character !== void 0) body.character = opts.character;
     if (opts.preview !== void 0) body.preview = opts.preview;
+    if (opts.maxUses !== void 0) body.max_uses = opts.maxUses;
+    if (opts.characters !== void 0) body.characters = opts.characters;
     return this.request("POST", `/account/worlds/${encodeURIComponent(worldId)}/links`, { body });
   }
   /**
@@ -1271,7 +1322,7 @@ function buildQuery(params) {
 
 // src/v2/types.generated.ts
 var ELEMENT_TYPES = ["ability", "character", "collective", "construct", "creature", "event", "family", "institution", "language", "law", "location", "map", "marker", "narrative", "object", "phenomenon", "pin", "relation", "species", "title", "trait", "zone"];
-var ONLYWORLDS_VERSION = "00.32.00";
+var ONLYWORLDS_VERSION = "00.32.01";
 var ELEMENT_FAMILIES = {
   ability: "abstract",
   character: "agents",

package/package.json

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